Add stopped-workspace disk export and inspection

Finish the 3.1.0 secondary disk-tools milestone so stable workspaces can be
stopped, inspected offline, exported as raw ext4 images, and started again
without changing the primary workspace-first interaction model.

Add workspace stop/start plus workspace disk export/list/read across the CLI,
SDK, and MCP, backed by a new offline debugfs inspection helper and guest-only
validation. Scrub runtime-only guest state before disk inspection/export, and
fix the real guest reliability gaps by flushing the filesystem on stop and
removing stale Firecracker socket files before restart.

Update the docs, examples, changelog, and roadmap to mark 3.1.0 done, and
cover the new lifecycle/disk paths with API, CLI, manager, contract, and
package-surface tests.

Validation: uv lock; UV_CACHE_DIR=.uv-cache make check; UV_CACHE_DIR=.uv-cache
make dist-check; real guest-backed smoke for create, shell/service activity,
stop, workspace disk list/read/export, start, exec, and delete.

docs/public-contract.md

@@ -26,8 +26,13 @@ Top-level commands:
 - `pyro run`
 - `pyro workspace create`
 - `pyro workspace sync push`
+- `pyro workspace stop`
+- `pyro workspace start`
 - `pyro workspace exec`
 - `pyro workspace export`
+- `pyro workspace disk export`
+- `pyro workspace disk list`
+- `pyro workspace disk read`
 - `pyro workspace diff`
 - `pyro workspace snapshot create`
 - `pyro workspace snapshot list`
@@ -72,7 +77,13 @@ Behavioral guarantees:
 - `pyro workspace create --network-policy {off,egress,egress+published-ports}` controls workspace guest networking and whether services may publish localhost ports.
 - `pyro workspace create --secret NAME=VALUE` and `--secret-file NAME=PATH` persist guest-only UTF-8 secrets outside `/workspace`.
 - `pyro workspace sync push WORKSPACE_ID SOURCE_PATH [--dest WORKSPACE_PATH]` imports later host-side directory or archive content into a started workspace.
+- `pyro workspace stop WORKSPACE_ID` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
+- `pyro workspace start WORKSPACE_ID` restarts one stopped workspace without resetting `/workspace`.
 - `pyro workspace export WORKSPACE_ID PATH --output HOST_PATH` exports one file or directory from `/workspace` back to the host.
+- `pyro workspace disk export WORKSPACE_ID --output HOST_PATH` copies the stopped guest-backed workspace rootfs as raw ext4 to the host.
+- `pyro workspace disk list WORKSPACE_ID [PATH] [--recursive]` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
+- `pyro workspace disk read WORKSPACE_ID PATH [--max-bytes N]` reads one regular file from a stopped guest-backed workspace rootfs offline.
+- `pyro workspace disk *` requires `state=stopped` and a guest-backed workspace; it fails on `host_compat`.
 - `pyro workspace diff WORKSPACE_ID` compares the current `/workspace` tree to the immutable create-time baseline.
 - `pyro workspace snapshot *` manages explicit named snapshots in addition to the implicit `baseline`.
 - `pyro workspace reset WORKSPACE_ID [--snapshot SNAPSHOT_NAME|baseline]` recreates the full sandbox and restores `/workspace` from the chosen snapshot.
@@ -108,7 +119,12 @@ Supported public entrypoints:
 - `Pyro.create_vm(...)`
 - `Pyro.create_workspace(..., network_policy="off", secrets=None)`
 - `Pyro.push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
+- `Pyro.stop_workspace(workspace_id)`
+- `Pyro.start_workspace(workspace_id)`
 - `Pyro.export_workspace(workspace_id, path, *, output_path)`
+- `Pyro.export_workspace_disk(workspace_id, *, output_path)`
+- `Pyro.list_workspace_disk(workspace_id, path="/workspace", recursive=False)`
+- `Pyro.read_workspace_disk(workspace_id, path, *, max_bytes=65536)`
 - `Pyro.diff_workspace(workspace_id)`
 - `Pyro.create_snapshot(workspace_id, snapshot_name)`
 - `Pyro.list_snapshots(workspace_id)`
@@ -147,7 +163,12 @@ Stable public method names:
 - `create_vm(...)`
 - `create_workspace(..., network_policy="off", secrets=None)`
 - `push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
+- `stop_workspace(workspace_id)`
+- `start_workspace(workspace_id)`
 - `export_workspace(workspace_id, path, *, output_path)`
+- `export_workspace_disk(workspace_id, *, output_path)`
+- `list_workspace_disk(workspace_id, path="/workspace", recursive=False)`
+- `read_workspace_disk(workspace_id, path, *, max_bytes=65536)`
 - `diff_workspace(workspace_id)`
 - `create_snapshot(workspace_id, snapshot_name)`
 - `list_snapshots(workspace_id)`
@@ -186,7 +207,13 @@ Behavioral defaults:
 - `Pyro.create_workspace(..., network_policy="off"|"egress"|"egress+published-ports")` controls workspace guest networking and whether services may publish host ports.
 - `Pyro.create_workspace(..., secrets=...)` persists guest-only UTF-8 secrets outside `/workspace`.
 - `Pyro.push_workspace_sync(...)` imports later host-side directory or archive content into a started workspace.
+- `Pyro.stop_workspace(...)` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
+- `Pyro.start_workspace(...)` restarts one stopped workspace without resetting `/workspace`.
 - `Pyro.export_workspace(...)` exports one file or directory from `/workspace` to an explicit host path.
+- `Pyro.export_workspace_disk(...)` copies the stopped guest-backed workspace rootfs as raw ext4 to an explicit host path.
+- `Pyro.list_workspace_disk(...)` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
+- `Pyro.read_workspace_disk(...)` reads one regular file from a stopped guest-backed workspace rootfs offline.
+- stopped-workspace disk helpers require `state=stopped` and a guest-backed workspace; they fail on `host_compat`.
 - `Pyro.diff_workspace(...)` compares the current `/workspace` tree to the immutable create-time baseline.
 - `Pyro.create_snapshot(...)` captures one named `/workspace` checkpoint.
 - `Pyro.list_snapshots(...)` lists the implicit `baseline` plus any named snapshots.
@@ -226,8 +253,13 @@ Persistent workspace tools:
 
 - `workspace_create`
 - `workspace_sync_push`
+- `workspace_stop`
+- `workspace_start`
 - `workspace_exec`
 - `workspace_export`
+- `workspace_disk_export`
+- `workspace_disk_list`
+- `workspace_disk_read`
 - `workspace_diff`
 - `snapshot_create`
 - `snapshot_list`
@@ -257,7 +289,13 @@ Behavioral defaults:
 - `workspace_create` accepts `network_policy` with `off`, `egress`, or `egress+published-ports` to control workspace guest networking and service port publication.
 - `workspace_create` accepts optional `secrets` and persists guest-only UTF-8 secret material outside `/workspace`.
 - `workspace_sync_push` imports later host-side directory or archive content into a started workspace, with an optional `dest` under `/workspace`.
+- `workspace_stop` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
+- `workspace_start` restarts one stopped workspace without resetting `/workspace`.
 - `workspace_export` exports one file or directory from `/workspace` to an explicit host path.
+- `workspace_disk_export` copies the stopped guest-backed workspace rootfs as raw ext4 to an explicit host path.
+- `workspace_disk_list` inspects a stopped guest-backed workspace rootfs offline without booting the guest.
+- `workspace_disk_read` reads one regular file from a stopped guest-backed workspace rootfs offline.
+- stopped-workspace disk tools require `state=stopped` and a guest-backed workspace; they fail on `host_compat`.
 - `workspace_diff` compares the current `/workspace` tree to the immutable create-time baseline.
 - `snapshot_create`, `snapshot_list`, and `snapshot_delete` manage explicit named snapshots in addition to the implicit `baseline`.
 - `workspace_reset` recreates the full sandbox and restores `/workspace` from `baseline` or one named snapshot.