Add model-native workspace file operations

Remove shell-escaped file mutation from the stable workspace flow by adding explicit file and patch tools across the CLI, SDK, and MCP surfaces.

This adds workspace file list/read/write plus unified text patch application, backed by new guest and manager file primitives that stay scoped to started workspaces and /workspace only. Patch application is preflighted on the host, file writes stay text-only and bounded, and the existing diff/export/reset semantics remain intact.

The milestone also updates the 3.2.0 roadmap, public contract, docs, examples, and versioning, and includes focused coverage for the new helper module and dispatch paths.

Validation:
- uv lock
- UV_CACHE_DIR=.uv-cache make check
- UV_CACHE_DIR=.uv-cache make dist-check
- real guest-backed smoke for workspace file read, patch apply, exec, export, and delete

docs/public-contract.md

@@ -29,7 +29,11 @@ Top-level commands:
 - `pyro workspace stop`
 - `pyro workspace start`
 - `pyro workspace exec`
+- `pyro workspace file list`
+- `pyro workspace file read`
+- `pyro workspace file write`
 - `pyro workspace export`
+- `pyro workspace patch apply`
 - `pyro workspace disk export`
 - `pyro workspace disk list`
 - `pyro workspace disk read`
@@ -79,6 +83,9 @@ Behavioral guarantees:
 - `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 file list WORKSPACE_ID [PATH] [--recursive]` returns metadata for one live path under `/workspace`.
+- `pyro workspace file read WORKSPACE_ID PATH [--max-bytes N]` reads one regular text file under `/workspace`.
+- `pyro workspace file write WORKSPACE_ID PATH --text TEXT` creates or replaces one regular text file under `/workspace`, creating missing parent directories automatically.
 - `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.
@@ -92,6 +99,7 @@ Behavioral guarantees:
 - `pyro workspace exec --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into one exec call.
 - `pyro workspace service start --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into one service start call.
 - `pyro workspace exec` runs in the persistent `/workspace` for that workspace and does not auto-clean.
+- `pyro workspace patch apply WORKSPACE_ID --patch TEXT` applies one unified text patch with add/modify/delete operations under `/workspace`.
 - `pyro workspace shell open --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into the opened shell environment.
 - `pyro workspace shell *` manages persistent PTY sessions inside a started workspace.
 - `pyro workspace logs` returns persisted command history for that workspace until `pyro workspace delete`.
@@ -121,7 +129,11 @@ Supported public entrypoints:
 - `Pyro.push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `Pyro.stop_workspace(workspace_id)`
 - `Pyro.start_workspace(workspace_id)`
+- `Pyro.list_workspace_files(workspace_id, path="/workspace", recursive=False)`
+- `Pyro.read_workspace_file(workspace_id, path, *, max_bytes=65536)`
+- `Pyro.write_workspace_file(workspace_id, path, *, text)`
 - `Pyro.export_workspace(workspace_id, path, *, output_path)`
+- `Pyro.apply_workspace_patch(workspace_id, *, patch)`
 - `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)`
@@ -165,7 +177,11 @@ Stable public method names:
 - `push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `stop_workspace(workspace_id)`
 - `start_workspace(workspace_id)`
+- `list_workspace_files(workspace_id, path="/workspace", recursive=False)`
+- `read_workspace_file(workspace_id, path, *, max_bytes=65536)`
+- `write_workspace_file(workspace_id, path, *, text)`
 - `export_workspace(workspace_id, path, *, output_path)`
+- `apply_workspace_patch(workspace_id, *, patch)`
 - `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)`
@@ -209,7 +225,9 @@ Behavioral defaults:
 - `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.list_workspace_files(...)`, `Pyro.read_workspace_file(...)`, and `Pyro.write_workspace_file(...)` provide structured live `/workspace` inspection and text edits without shell quoting.
 - `Pyro.export_workspace(...)` exports one file or directory from `/workspace` to an explicit host path.
+- `Pyro.apply_workspace_patch(...)` applies unified text patches for add/modify/delete operations under `/workspace`.
 - `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.
@@ -256,7 +274,11 @@ Persistent workspace tools:
 - `workspace_stop`
 - `workspace_start`
 - `workspace_exec`
+- `workspace_file_list`
+- `workspace_file_read`
+- `workspace_file_write`
 - `workspace_export`
+- `workspace_patch_apply`
 - `workspace_disk_export`
 - `workspace_disk_list`
 - `workspace_disk_read`
@@ -291,7 +313,9 @@ Behavioral defaults:
 - `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_file_list`, `workspace_file_read`, and `workspace_file_write` provide structured live `/workspace` inspection and text edits without shell quoting.
 - `workspace_export` exports one file or directory from `/workspace` to an explicit host path.
+- `workspace_patch_apply` applies unified text patches for add/modify/delete operations under `/workspace`.
 - `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.