Add chat-friendly shell read rendering

Make workspace shell reads usable as direct chat-model input without changing the PTY or cursor model. This adds optional plain rendering and idle-window batching across CLI, SDK, and MCP while keeping raw reads backward-compatible.

Implement the rendering and wait-for-idle logic in the manager layer so the existing guest/backend shell transport stays unchanged. The new helper strips ANSI and other terminal control noise, handles carriage-return overwrite and backspace, and preserves raw cursor semantics even when plain output is requested.

Refresh the stable shell docs/examples to recommend --plain --wait-for-idle-ms 300, mark the 3.5.0 roadmap milestone done, and bump the package/catalog version to 3.5.0.

Validation: uv lock; UV_CACHE_DIR=.uv-cache make check; UV_CACHE_DIR=.uv-cache make dist-check; real guest-backed Firecracker smoke covering shell open/write/read with ANSI plus delayed output.

docs/public-contract.md

@@ -107,6 +107,7 @@ Behavioral guarantees:
 - `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 shell read --plain --wait-for-idle-ms 300` is the recommended chat-facing read mode; raw shell reads remain available without `--plain`.
 - `pyro workspace logs` returns persisted command history for that workspace until `pyro workspace delete`.
 - `pyro workspace update` changes only discovery metadata such as `name` and key/value `labels`.
 - Workspace create/status results expose `workspace_seed` metadata describing how `/workspace` was initialized.
@@ -157,7 +158,7 @@ Supported public entrypoints:
 - `Pyro.logs_service(workspace_id, service_name, *, tail_lines=200, all=False)`
 - `Pyro.stop_service(workspace_id, service_name)`
 - `Pyro.open_shell(workspace_id, *, cwd="/workspace", cols=120, rows=30, secret_env=None)`
-- `Pyro.read_shell(workspace_id, shell_id, *, cursor=0, max_chars=65536)`
+- `Pyro.read_shell(workspace_id, shell_id, *, cursor=0, max_chars=65536, plain=False, wait_for_idle_ms=None)`
 - `Pyro.write_shell(workspace_id, shell_id, *, input, append_newline=True)`
 - `Pyro.signal_shell(workspace_id, shell_id, *, signal_name="INT")`
 - `Pyro.close_shell(workspace_id, shell_id)`
@@ -207,7 +208,7 @@ Stable public method names:
 - `logs_service(workspace_id, service_name, *, tail_lines=200, all=False)`
 - `stop_service(workspace_id, service_name)`
 - `open_shell(workspace_id, *, cwd="/workspace", cols=120, rows=30, secret_env=None)`
-- `read_shell(workspace_id, shell_id, *, cursor=0, max_chars=65536)`
+- `read_shell(workspace_id, shell_id, *, cursor=0, max_chars=65536, plain=False, wait_for_idle_ms=None)`
 - `write_shell(workspace_id, shell_id, *, input, append_newline=True)`
 - `signal_shell(workspace_id, shell_id, *, signal_name="INT")`
 - `close_shell(workspace_id, shell_id)`
@@ -260,7 +261,7 @@ Behavioral defaults:
 - `Pyro.exec_workspace(...)` runs one command in the persistent workspace and leaves it alive.
 - `Pyro.open_shell(..., secret_env=...)` maps persisted workspace secrets into the shell environment when that shell opens.
 - `Pyro.open_shell(...)` opens a persistent PTY shell attached to one started workspace.
-- `Pyro.read_shell(...)` reads merged text output from that shell by cursor.
+- `Pyro.read_shell(...)` reads merged text output from that shell by cursor, with optional plain rendering and idle batching for chat-facing consumers.
 - `Pyro.write_shell(...)`, `Pyro.signal_shell(...)`, and `Pyro.close_shell(...)` operate on that persistent shell session.
 - `Pyro.update_workspace(...)` changes only discovery metadata such as `name` and key/value `labels`.