Spec/restart stopped vm

.scratch/restart-stopped-vm/issues/01-record-config-and-report-status.md

@@ -0,0 +1,14 @@
+# 01: Record the VM configuration and report true status
+
+**What to build:** A newly created VM writes an immutable VM configuration record capturing its full effective shape: machine resources and knobs, network mode and index, mounts, env, vsock settings and jailer ids. `list` classifies every VM as `running`, `crashed` or `legacy` using the existing PID-plus-start-time check; a VM with a runtime state record but no configuration record is `legacy`. Stop, cleanup and failed-creation rollback are refactored onto one shared teardown routine with no change in behaviour yet. See the parent spec and `docs/adr/0001-stop-preserves-the-vm.md`.
+
+**Blocked by:** None (can start immediately)
+
+**Status:** ready-for-agent
+
+- [x] Creating a VM writes a configuration record that is never modified afterwards
+- [x] The configuration record holds everything needed to boot the VM again without any flags
+- [x] `list` shows `running` for a live VM, `crashed` for a dead process with a runtime state record, and `legacy` when there is no configuration record
+- [x] A recycled PID is not reported as `running`
+- [x] Stop, cleanup and failed-creation rollback use one teardown routine and behave as before
+- [x] Manager-level and `list` formatting tests cover each status against a temp state directory

.scratch/restart-stopped-vm/issues/02-stop-keeps-the-vm.md

@@ -0,0 +1,16 @@
+# 02: `stop` keeps the VM
+
+**What to build:** `stop` becomes non-destructive. It signals the process as today, syncs writable block mounts back to the host directory, releases TAP/CNI, firewall rules, NFS exports and the jailer tree, writes a stop record with the stop time, and removes the runtime state record last. The disk, block images, configuration record and network index are kept. `stop` on an already stopped VM succeeds. New-VM index allocation never reuses a stopped VM's index. The host firewall chain and `ip_forward` are released when the last running VM stops, not when the last VM on disk goes. `list` shows `stopped` with a stopped-at column.
+
+**Blocked by:** 01
+
+**Status:** ready-for-agent
+
+- [x] After `stop`, the VM's disk, configuration and index are still on disk
+- [x] `list` shows the VM as `stopped` with its stop time, and a VM with no stop record whose process died still shows `crashed`
+- [x] The stop record is written before the runtime state record is removed, so an interrupted stop shows as `crashed`
+- [x] A new VM never takes a stopped VM's network index or guest IP
+- [x] A stopped VM holds no TAP device, firewall rules, NFS exports or jailer tree
+- [x] The host firewall chain and `ip_forward` are restored when the last running VM stops, even if stopped VMs remain
+- [x] `stop` on an already stopped VM succeeds, and on an unknown id fails clearly
+- [x] Manager tests cover the above against a temp state directory with host commands recorded

.scratch/restart-stopped-vm/issues/03-start-an-existing-vm.md

@@ -0,0 +1,16 @@
+# 03: `start <id>` boots an existing VM
+
+**What to build:** `start <id>` on a stopped VM boots it from its preserved disk using its saved configuration, reusing its network index and guest identity, then clears the stop record. `--mount` and `--env` on an existing VM fail with an error telling the user to delete and recreate. Starting a running VM fails clearly. `start` with a new id or no id still creates a VM exactly as today. If a restart fails partway, only the runtime resources acquired in that attempt are released; the VM stays stopped with its disk and configuration intact. A failed creation still removes everything it created.
+
+**Blocked by:** 02
+
+**Status:** ready-for-agent
+
+- [x] A stopped VM starts from its preserved disk and files written before the stop are still there
+- [x] The restarted VM has the same configuration and, in TAP mode, the same guest IP
+- [x] The stop record is removed once the VM is running
+- [x] `--mount` or `--env` on an existing VM is rejected with a message explaining how to get a different shape
+- [x] Starting a running VM fails without side effects
+- [x] A failed restart leaves the VM `stopped` with its disk and configuration untouched
+- [x] A failed creation still removes everything it created
+- [x] Manager tests (Firecracker launch stubbed) and cmd tests for the flag rules cover the above

.scratch/restart-stopped-vm/issues/04-restart-command.md

@@ -0,0 +1,13 @@
+# 04: `restart <id>`
+
+**What to build:** A `restart` command. On a running VM it stops then starts it; on a stopped or crashed VM it just starts it. An unknown id is a "no such VM" error and `restart` never creates a VM.
+
+**Blocked by:** 03
+
+**Status:** ready-for-agent
+
+- [x] `restart` on a running VM leaves it running again with its disk preserved
+- [x] `restart` on a stopped VM starts it
+- [x] `restart` on an unknown id fails with a "no such VM" error and creates nothing
+- [x] `--mount` and `--env` are not accepted by `restart`
+- [x] Manager and cmd tests cover running, stopped and unknown ids

.scratch/restart-stopped-vm/issues/05-delete-command.md

@@ -0,0 +1,15 @@
+# 05: `delete <id>`
+
+**What to build:** A `delete` command, the deliberate way to remove a VM. It removes the disk, block mount images, configuration record, jailer tree, any leftovers, and frees the reserved network slot. It refuses a running VM unless `--force`, which stops the VM first. An unknown id is an error. `cleanup` keeps its best-effort orphan-reclaim role and shares the same teardown. Every deletion path keeps the existing id validation and mount/`RemoveAll` guards.
+
+**Blocked by:** 02
+
+**Status:** ready-for-agent
+
+- [x] `delete` on a stopped VM removes everything and frees its index for reuse
+- [x] `delete` on a running VM is refused without `--force`
+- [x] `delete --force` on a running VM stops then deletes it
+- [x] `delete` on an unknown id fails clearly
+- [x] `cleanup` and `cleanup --all` still reclaim orphans with or without records
+- [x] Ids are validated before use as path components on the new path
+- [x] Manager and cmd tests cover stopped, running, forced, unknown and orphan cases

.scratch/restart-stopped-vm/issues/06-crashed-vm-recovery.md

@@ -0,0 +1,13 @@
+# 06: Crashed VM recovery
+
+**What to build:** `start <id>` and `restart <id>` on a crashed VM first tear down what the crash left behind (TAP device, firewall rules, NFS exports, jailer tree), then boot normally from the preserved disk. `stop <id>` on a crashed VM performs the same leftover teardown and records the stop, so the user can acknowledge the crash. No `fsck` is run.
+
+**Blocked by:** 03
+
+**Status:** ready-for-agent
+
+- [x] `start` on a crashed VM succeeds without running `cleanup` first
+- [x] Leftover TAP, rules, exports and jailer tree from the crash are removed before boot
+- [x] `stop` on a crashed VM leaves it `stopped` with a stop record and no leftover resources
+- [x] A failed recovery leaves the disk and configuration intact
+- [x] Manager tests simulate a crash by leaving runtime state and a dead process

.scratch/restart-stopped-vm/issues/07-mounts-and-ip-across-restarts.md

@@ -0,0 +1,14 @@
+# 07: Mounts and guest IP across restarts
+
+**What to build:** Writable block mount images are reused when an existing VM starts and are not rebuilt from the host directory, so guest-side changes are not overwritten; `stop` still syncs them back to the host directory. NFS exports are recreated on every start against the VM's current guest IP. In TAP mode the guest IP is stable across restarts; in CNI mode it is re-resolved at each start. `list` shows a non-running VM's guest IP only in TAP mode and `-` in CNI mode.
+
+**Blocked by:** 03
+
+**Status:** ready-for-agent
+
+- [x] A block mount image with guest-side changes survives stop and start unchanged
+- [x] `stop` still mirrors writable block mounts to the host directory
+- [x] NFS exports are recreated on start and scoped to the guest IP resolved for that boot
+- [x] In CNI mode a changed guest IP leads to exports for the new IP
+- [x] `list` shows the guest IP of a stopped TAP VM and `-` for a stopped CNI VM
+- [x] Manager and `list` formatting tests cover the above

.scratch/restart-stopped-vm/issues/08-actionable-errors-for-exec-and-shell.md

@@ -0,0 +1,13 @@
+# 08: Actionable errors for `exec` and `shell`
+
+**What to build:** `exec` and `shell` (and `vsock-exec`) on a VM that is not running report its status (`stopped`, `crashed` or `legacy`) and say how to start it, instead of a connection failure.
+
+**Blocked by:** 02
+
+**Status:** ready-for-agent
+
+- [x] `exec` and `shell` on a stopped VM name the status and suggest `start <id>`
+- [x] The same holds for a crashed VM
+- [x] A legacy VM's message says it cannot be restarted and suggests `cleanup`
+- [x] An unknown id still reports that the VM does not exist
+- [x] cmd tests cover each status

.scratch/restart-stopped-vm/issues/09-docs-and-release-notes.md

@@ -0,0 +1,12 @@
+# 09: Docs and release notes
+
+**What to build:** Bring the documentation in line with the new lifecycle: the on-disk layout and the stop and cleanup sections in the architecture doc, the command reference for `start <id>`, `restart`, `delete`, `stop` and the new `list` statuses, and a release note. The note says `stop` no longer deletes, `delete` reclaims disk space, and VMs created before this change show as `legacy` and cannot be restarted.
+
+**Blocked by:** 04, 05, 06, 07, 08
+
+**Status:** ready-for-agent
+
+- [ ] The architecture doc describes the configuration, runtime state and stop records and the new stop, start-existing and delete flows
+- [ ] The CLI reference documents `restart`, `delete`, `start <id>` and the `list` statuses and columns
+- [ ] A release note covers the behaviour change of `stop` and the legacy break
+- [ ] The manual smoke test is run on real hardware and its result noted: write a file in the guest, `stop`, `start`, confirm the file and (TAP) the IP survive; kill Firecracker and confirm `crashed` then recovery with `start`