Add seeded task workspace creation

Current persistent tasks started with an empty workspace, which blocked the first useful host-to-task workflow in the task roadmap. This change lets task creation start from a host directory or tar archive without changing the one-shot VM surfaces.

Expose source_path on task create across the CLI, SDK, and MCP, add safe archive upload and extraction support for guest and host-compat backends, persist workspace_seed metadata, and patch the per-task rootfs with the bundled guest agent before boot so seeded guest tasks work without republishing environments. Also switch post--- command reconstruction to shlex.join() so documented sh -lc task examples preserve argument boundaries.

Validation:
- uv lock
- UV_CACHE_DIR=.uv-cache uv run pytest --no-cov tests/test_vm_guest.py tests/test_vm_manager.py tests/test_cli.py tests/test_api.py tests/test_server.py tests/test_public_contract.py
- UV_CACHE_DIR=.uv-cache make check
- UV_CACHE_DIR=.uv-cache make dist-check
- real guest-backed smoke: task create --source-path, task exec -- cat note.txt, task delete

docs/first-run.md

@@ -22,7 +22,7 @@ Networking: tun=yes ip_forward=yes
 
 ```bash
 $ uvx --from pyro-mcp pyro env list
-Catalog version: 2.1.0
+Catalog version: 2.2.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -70,7 +70,7 @@ deterministic structured result.
 
 ```bash
 $ uvx --from pyro-mcp pyro demo
-$ uvx --from pyro-mcp pyro task create debian:12
+$ uvx --from pyro-mcp pyro task create debian:12 --source-path ./repo
 $ uvx --from pyro-mcp pyro mcp serve
 ```
 
@@ -79,11 +79,12 @@ $ uvx --from pyro-mcp pyro mcp serve
 When you need repeated commands in one sandbox, switch to `pyro task ...`:
 
 ```bash
-$ uvx --from pyro-mcp pyro task create debian:12
+$ uvx --from pyro-mcp pyro task create debian:12 --source-path ./repo
 Task: ...
 Environment: debian:12
 State: started
 Workspace: /workspace
+Workspace seed: directory from ...
 Execution mode: guest_vsock
 Resources: 1 vCPU / 1024 MiB
 Command count: 0
@@ -96,6 +97,9 @@ hello from task
 [task-exec] task_id=... sequence=2 cwd=/workspace execution_mode=guest_vsock exit_code=0 duration_ms=...
 ```
 
+Use `--source-path` when the task should start from a host directory or a local
+`.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`.
+
 Example output:
 
 ```json

docs/install.md

@@ -83,7 +83,7 @@ uvx --from pyro-mcp pyro env list
 Expected output:
 
 ```bash
-Catalog version: 2.1.0
+Catalog version: 2.2.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -174,7 +174,7 @@ pyro run debian:12 -- git --version
 
 After the CLI path works, you can move on to:
 
-- persistent workspaces: `pyro task create debian:12`
+- persistent workspaces: `pyro task create debian:12 --source-path ./repo`
 - MCP: `pyro mcp serve`
 - Python SDK: `from pyro_mcp import Pyro`
 - Demos: `pyro demo` or `pyro demo --network`
@@ -184,7 +184,7 @@ After the CLI path works, you can move on to:
 Use `pyro task ...` when you need repeated commands in one sandbox instead of one-shot `pyro run`.
 
 ```bash
-pyro task create debian:12
+pyro task create debian:12 --source-path ./repo
 pyro task exec TASK_ID -- sh -lc 'printf "hello from task\n" > note.txt'
 pyro task exec TASK_ID -- cat note.txt
 pyro task logs TASK_ID
@@ -192,7 +192,8 @@ pyro task delete TASK_ID
 ```
 
 Task commands default to the persistent `/workspace` directory inside the guest. If you need the
-task identifier programmatically, use `--json` and read the `task_id` field.
+task identifier programmatically, use `--json` and read the `task_id` field. Use `--source-path`
+when the task should start from a host directory or a local `.tar` / `.tar.gz` / `.tgz` archive.
 
 ## Contributor Clone
 

docs/integrations.md

@@ -30,7 +30,7 @@ Best when:
 Recommended surface:
 
 - `vm_run`
-- `task_create` + `task_exec` when the agent needs persistent workspace state
+- `task_create(source_path=...)` + `task_exec` when the agent needs persistent workspace state
 
 Canonical example:
 
@@ -65,14 +65,15 @@ Best when:
 Recommended default:
 
 - `Pyro.run_in_vm(...)`
-- `Pyro.create_task(...)` + `Pyro.exec_task(...)` when repeated workspace commands are required
+- `Pyro.create_task(source_path=...)` + `Pyro.exec_task(...)` when repeated workspace commands are required
 
 Lifecycle note:
 
 - `Pyro.exec_vm(...)` runs one command and auto-cleans the VM afterward
 - use `create_vm(...)` + `start_vm(...)` only when you need pre-exec inspection or status before
   that final exec
-- use `create_task(...)` when the agent needs repeated commands in one persistent `/workspace`
+- use `create_task(source_path=...)` when the agent needs repeated commands in one persistent
+  `/workspace` that starts from host content
 
 Examples:
 

docs/public-contract.md

@@ -46,8 +46,12 @@ Behavioral guarantees:
 - `pyro run`, `pyro env list`, `pyro env pull`, `pyro env inspect`, `pyro env prune`, and `pyro doctor` are human-readable by default and return structured JSON with `--json`.
 - `pyro demo ollama` prints log lines plus a final summary line.
 - `pyro task create` auto-starts a persistent workspace.
+- `pyro task create --source-path PATH` seeds `/workspace` from a host directory or a local
+  `.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
 - `pyro task exec` runs in the persistent `/workspace` for that task and does not auto-clean.
 - `pyro task logs` returns persisted command history for that task until `pyro task delete`.
+- Task create/status results expose `workspace_seed` metadata describing how `/workspace` was
+  initialized.
 
 ## Python SDK Contract
 
@@ -106,6 +110,8 @@ Behavioral defaults:
 - `Pyro.create_task(...)` defaults to `vcpu_count=1` and `mem_mib=1024`.
 - `allow_host_compat` defaults to `False` on `create_vm(...)` and `run_in_vm(...)`.
 - `allow_host_compat` defaults to `False` on `create_task(...)`.
+- `Pyro.create_task(..., source_path=...)` seeds `/workspace` from a host directory or a local
+  `.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
 - `Pyro.exec_vm(...)` runs one command and auto-cleans that VM after the exec completes.
 - `Pyro.exec_task(...)` runs one command in the persistent task workspace and leaves the task alive.
 
@@ -141,6 +147,8 @@ Behavioral defaults:
 - `task_create` defaults to `vcpu_count=1` and `mem_mib=1024`.
 - `vm_run` and `vm_create` expose `allow_host_compat`, which defaults to `false`.
 - `task_create` exposes `allow_host_compat`, which defaults to `false`.
+- `task_create` accepts optional `source_path` and seeds `/workspace` from a host directory or a
+  local `.tar` / `.tar.gz` / `.tgz` archive before the task is returned.
 - `vm_exec` runs one command and auto-cleans that VM after the exec completes.
 - `task_exec` runs one command in a persistent `/workspace` and leaves the task alive.