Add workspace network policy and published ports

Replace the workspace-level boolean network toggle with explicit network policies and attach localhost TCP publication to workspace services.

Persist network_policy in workspace records, validate --publish requests, and run host-side proxy helpers that follow the service lifecycle so published ports are cleaned up on failure, stop, reset, and delete.

Update the CLI, SDK, MCP contract, docs, roadmap, and examples for the new policy model, add coverage for the proxy and manager edge cases, and validate with uv lock, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and a real guest-backed published-port probe smoke.

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.9.0
+Catalog version: 2.10.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.
@@ -72,6 +72,7 @@ deterministic structured result.
 $ uvx --from pyro-mcp pyro demo
 $ uvx --from pyro-mcp pyro workspace create debian:12 --seed-path ./repo
 $ uvx --from pyro-mcp pyro workspace sync push WORKSPACE_ID ./changes
+$ uvx --from pyro-mcp pyro workspace create debian:12 --network-policy egress
 $ uvx --from pyro-mcp pyro workspace create debian:12 --secret API_TOKEN=expected --secret-file PIP_TOKEN=./token.txt
 $ uvx --from pyro-mcp pyro workspace exec WORKSPACE_ID --secret-env API_TOKEN -- sh -lc 'test "$API_TOKEN" = "expected"'
 $ uvx --from pyro-mcp pyro workspace diff WORKSPACE_ID
@@ -80,6 +81,8 @@ $ uvx --from pyro-mcp pyro workspace reset WORKSPACE_ID --snapshot checkpoint
 $ uvx --from pyro-mcp pyro workspace export WORKSPACE_ID note.txt --output ./note.txt
 $ uvx --from pyro-mcp pyro workspace shell open WORKSPACE_ID --secret-env API_TOKEN
 $ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --secret-env API_TOKEN --ready-file .ready -- sh -lc 'touch .ready && while true; do sleep 60; done'
+$ uvx --from pyro-mcp pyro workspace create debian:12 --network-policy egress+published-ports
+$ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --ready-http http://127.0.0.1:8080/ --publish 18080:8080 -- ./start-app
 $ uvx --from pyro-mcp pyro mcp serve
 ```
 
@@ -94,6 +97,7 @@ Environment: debian:12
 State: started
 Workspace: /workspace
 Workspace seed: directory from ...
+Network policy: off
 Execution mode: guest_vsock
 Resources: 1 vCPU / 1024 MiB
 Command count: 0
@@ -144,6 +148,14 @@ $ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID web --secret-env
 $ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID worker --ready-file .worker-ready -- sh -lc 'touch .worker-ready && while true; do sleep 60; done'
 [workspace-service-start] workspace_id=... service=worker state=running cwd=/workspace ready_type=file execution_mode=guest_vsock
 
+$ uvx --from pyro-mcp pyro workspace create debian:12 --network-policy egress+published-ports
+Workspace ID: ...
+Network policy: egress+published-ports
+...
+
+$ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --ready-http http://127.0.0.1:8080/ --publish 18080:8080 -- ./start-app
+[workspace-service-start] workspace_id=... service=app state=running cwd=/workspace ready_type=http execution_mode=guest_vsock published=127.0.0.1:18080->8080/tcp
+
 $ uvx --from pyro-mcp pyro workspace service list WORKSPACE_ID
 Workspace: ...
 Services: 2 total, 2 running
@@ -175,7 +187,7 @@ $ uvx --from pyro-mcp pyro workspace service stop WORKSPACE_ID worker
 Use `--seed-path` when the workspace should start from a host directory or a local
 `.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`. Use
 `pyro workspace sync push` when you need to import later host-side changes into a started
-workspace. Sync is non-atomic in `2.9.0`; if it fails partway through, prefer `pyro workspace reset`
+workspace. Sync is non-atomic in `2.10.0`; if it fails partway through, prefer `pyro workspace reset`
 to recover from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current
 `/workspace` tree to its immutable create-time baseline, `pyro workspace snapshot *` to create
 named checkpoints, and `pyro workspace export` to copy one changed file or directory back to the
@@ -183,10 +195,13 @@ host. Use `pyro workspace exec` for one-shot commands and `pyro workspace shell
 need a persistent interactive PTY session in that same workspace. Use `pyro workspace service *`
 when the workspace needs long-running background processes with typed readiness checks. Internal
 service state and logs stay outside `/workspace`, so service runtime data does not appear in
-workspace diff or export results. Use `--secret` and `--secret-file` at workspace creation when
-the sandbox needs private tokens or config. Persisted secret files are materialized at
-`/run/pyro-secrets/<name>`, and `--secret-env SECRET_NAME[=ENV_VAR]` maps one secret into one
-exec, shell, or service call without storing that environment mapping on the workspace itself.
+workspace diff or export results. Use `--network-policy egress` for outbound guest networking, and
+`--network-policy egress+published-ports` plus `workspace service start --publish` when one
+service must be reachable from the host on `127.0.0.1`. Use `--secret` and `--secret-file` at
+workspace creation when the sandbox needs private tokens or config. Persisted secret files are
+materialized at `/run/pyro-secrets/<name>`, and `--secret-env SECRET_NAME[=ENV_VAR]` maps one
+secret into one exec, shell, or service call without storing that environment mapping on the
+workspace itself.
 
 Example output: