@pipod/cli 0.0.0-stage → 0.1.3

package/docs/ci-validation.md

@@ -0,0 +1,17 @@
+# Integration-only CI
+
+CI again runs the existing `test:integration` entrypoint, now selecting eleven
+explicit reviewed files rather than every file under `test/integration`.
+They exercise actual CLI dispatch, account/project files, HTTP/WebSockets,
+Git/tar subprocesses, OIDC signatures, or extension loading. Some collaborators
+remain fixtures; passing does not prove production remote connectivity.
+
+`account-billing.test.ts` contains isolated formatting cases and
+`plan-change-cli.test.ts` contains a fully mocked timeout case. Both files remain
+unchanged and are excluded as a whole. This also omits their genuine HTTP billing
+coverage: the selection is not the full prior integration suite. Extracting those
+existing cases requires a separate reviewed change. Do not reintroduce a directory
+glob, broad name filters, or unit execution to make CI appear complete.
+
+Typecheck, lint and build remain required. Restoring CI does not publish a package
+or deploy a server. No production credentials are needed by these fixtures.

package/docs/classic-runtime-coupling.md

@@ -0,0 +1,106 @@
+# Classic runtime coupling
+
+The classic runtime is frozen at its current RPC passthrough surface. New
+user-facing features ride the semantic gateway protocol shared with the app —
+never new RPC passthrough methods on the classic runtime. The inventory below
+is an upper bound: removals are allowed; additions and unexpected duplicates
+are not. `@earendil-works/pi-coding-agent` imports stay inside
+`src/client/runtime/` plus the import allowlist below, and only the two named
+modules may patch a live `InteractiveMode` instance.
+
+These lists were enforced by the removed `test/unit/classic-architecture.test.ts`
+under the repository's no-unit-tests policy. They are now policy that reviewers
+check by hand; do not weaken them silently.
+
+## Passthrough files
+
+- `client/runtime/remote-runtime.ts`
+- `client/runtime/remote-ui.ts`
+- `client/runtime/auth-bridge.ts`
+- `client/runtime/local-extensions.ts`
+- `client/runtime/pod-extension-bridge.ts`
+
+## Frozen RPC passthrough inventory
+
+Multiset of `file:enclosingPath:requestType` RPC call sites allowed across the
+passthrough files:
+
+```text
+client/runtime/remote-runtime.ts:createRemoteRuntime:onEvent
+client/runtime/remote-runtime.ts:prompt:prompt
+client/runtime/remote-runtime.ts:refreshRemoteModels:getAvailableModels
+client/runtime/remote-runtime.ts:cycleModel:setModel
+client/runtime/remote-runtime.ts:cycleModel:setThinkingLevel
+client/runtime/remote-runtime.ts:agent.abort:abort
+client/runtime/remote-runtime.ts:session.steer:steer
+client/runtime/remote-runtime.ts:session.followUp:followUp
+client/runtime/remote-runtime.ts:session.abort:abort
+client/runtime/remote-runtime.ts:session.waitForIdle:waitForIdle
+client/runtime/remote-runtime.ts:session.setModel:setModel
+client/runtime/remote-runtime.ts:session.setThinkingLevel:setThinkingLevel
+client/runtime/remote-runtime.ts:session.cycleThinkingLevel:cycleThinkingLevel
+client/runtime/remote-runtime.ts:session.setSteeringMode:setSteeringMode
+client/runtime/remote-runtime.ts:session.setFollowUpMode:setFollowUpMode
+client/runtime/remote-runtime.ts:session.compact:compact
+client/runtime/remote-runtime.ts:session.setAutoCompactionEnabled:setAutoCompaction
+client/runtime/remote-runtime.ts:session.setAutoRetryEnabled:setAutoRetry
+client/runtime/remote-runtime.ts:session.abortRetry:abortRetry
+client/runtime/remote-runtime.ts:session.executeBash:newRequestId
+client/runtime/remote-runtime.ts:session.executeBash:onEvent
+client/runtime/remote-runtime.ts:session.executeBash:bash
+client/runtime/remote-runtime.ts:session.abortBash:abortBash
+client/runtime/remote-runtime.ts:session.setSessionName:setSessionName
+client/runtime/remote-runtime.ts:session.getSessionStats:getSessionStats
+client/runtime/remote-runtime.ts:session.getLastAssistantText:getLastAssistantText
+client/runtime/remote-runtime.ts:session.exportToHtml:exportHtml
+client/runtime/remote-runtime.ts:runtimeHost.newSession:newSession
+client/runtime/remote-runtime.ts:runtimeHost.switchSession:switchSession
+client/runtime/remote-runtime.ts:runtimeHost.fork:fork
+client/runtime/remote-runtime.ts:runtimeHost.dispose.stderrTail:getStderr
+client/runtime/remote-runtime.ts:healStreamingRenderer:refreshStreamingSnapshot
+client/runtime/remote-runtime.ts:createRemoteRuntime.init.setModel:setModel
+client/runtime/remote-runtime.ts:createRemoteRuntime.init.setThinkingLevel:setThinkingLevel
+client/runtime/remote-runtime.ts:createRemoteRuntime.init.abort:abort
+client/runtime/remote-runtime.ts:createRemoteRuntime.init.compact:compact
+client/runtime/remote-runtime.ts:createRemoteRuntime.init.waitForIdle:waitForIdle
+client/runtime/remote-runtime.ts:quitPi:onControl
+client/runtime/remote-runtime.ts:quitPi:shutdown
+client/runtime/remote-ui.ts:RemoteUiBridge.constructor:onLifecycleInvalidated
+client/runtime/remote-ui.ts:RemoteUiBridge.consumeExtensionRequest:respondExtensionUi
+client/runtime/remote-ui.ts:RemoteUiBridge.respond:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.constructor:onLifecycleInvalidated
+client/runtime/auth-bridge.ts:AuthBridge.consumeExtensionRequest:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.consumeDialog:respondExtensionUi
+client/runtime/auth-bridge.ts:onAbort:respondExtensionUi
+client/runtime/auth-bridge.ts:AuthBridge.invoke:prompt
+client/runtime/local-extensions.ts:sendAppendEntry:prompt
+client/runtime/pod-extension-bridge.ts:PodExtensionBridge.constructor:onLifecycleInvalidated
+client/runtime/pod-extension-bridge.ts:PodExtensionBridge.invokeSeed:prompt
+client/runtime/pod-extension-bridge.ts:PodExtensionBridge.invoke:prompt
+```
+
+## Pi import allowlist
+
+Outside `src/client/runtime/`, only these modules may import
+`@earendil-works/pi-coding-agent`:
+
+- `account/gateway-rpc-codec.ts`
+- `account/gateway-rpc.ts`
+- `account/session.ts`
+- `client/piversion.ts`
+- `client/rpc.ts`
+- `client/stream-events.ts`
+- `oauth.ts`
+
+## InteractiveMode patch sites
+
+Only these modules may monkey-patch a live `InteractiveMode` instance:
+
+- `client/pod-title.ts`
+- `client/runtime/pod-command-overrides.ts`

package/docs/config-simplification.md

@@ -0,0 +1,162 @@
+# Config simplification
+
+## Removed (local schema, hard migration errors)
+
+| Key | Why | Migration |
+|---|---|---|
+| `envFile` | Client filesystem layout leaking into the server bundle. The bundle already carries secret *values/names*; the local path was only ever read by `compileBundleSource` and `projectEnvPath`, and the org layer already used a fixed path. | The project env file is always `.pi-pod/env`. Move the file, delete the key. |
+| `initScript` | Same leak. Script *contents* travel in the bundle body (`initScript` string); the config value was only the local read/write path. | The project init script is always `.pi-pod/init.sh`. |
+| `bakeScript` | Same leak, same shape as `initScript`. Bake itself is fully retained — only the path pointer is fixed. | The project bake script is always `.pi-pod/bake.sh`. |
+| `reuse` | Stored reuse is retired server-side: the bundle-write contract rejects it, reads strip it, and resolve omits it. Launches are flag-driven. | Pass `--reuse` to reuse a stopped project pod (fresh pods are the default). Delete the key. |
+| `pi.hostConfig.skills` | True no-op both sides: zero server reads, zero local consumers — the whole local agents directory always syncs. | Delete the key. |
+| `pi.hostConfig.extensions` | Same, both sides. | Delete the key. |
+| `--no-reuse` (CLI) | Redundant once stored `reuse` is gone: fresh pods are the default, so declining reuse is a no-op. `--reuse` alone covers the choice. | Retired as a plain unknown option. Drop the flag. |
+| `init --print-shell-snippet` (CLI) | Shell integration, not configuration. The snippet only tested `cwd` for `.pi-pod/config.json` while the launcher walks to `$HOME`, so it mis-dispatched in subdirectories. Removing the generator breaks nothing installed. | Retired as a plain unknown option. |
+| `--provider` (CLI) | Single-provider build: sandbox is the only backend, so there is nothing to select. | Retired as a plain unknown option. Drop the flag. |
+| `provider`, `deniedProviders` (config) | Single-provider build: sandbox is the only backend, so selection/denial lists are meaningless. Unlike the rows above, these warn-and-ignore (old files keep running) instead of failing closed. | Delete the keys. |
+
+Retired config keys fail closed in `validateConfig` (and in `planAccountLaunch`
+before resolve — covering nested `pi.hostConfig` lists and the machine layer
+`~/.pi-pod/config.json`, whose only ever-read keys are the template pin,
+`secretResolver`, and `pi.chords`/`pi.sessionNaming`) because silently ignoring a
+custom script path would read the wrong file. Server-resident bundles carrying
+retired keys (old templates) are stripped with a warning on pull and
+launch-preview — `push` clears them; `diff` strips silently by design (it is
+report-only). These warnings fire against old servers or un-migrated bundles:
+a new server already strips retired keys and flattens legacy Pi settings on
+read. Reads stay lenient, writes fail closed, and the server's own 400
+remains as backstop.
+
+## Stripped from outgoing bundles (never sent)
+
+One deep boundary, `stripNonBundleKeys` (`toOutgoingBundleConfig` for raw files),
+drops everything a bundle payload must not contain: the rejected keys
+(`template` — the local pin, a template id travels instead; `reuse`;
+`envFile`/`initScript`/`bakeScript`; `pi.hostConfig.skills`/`extensions`) plus
+client-only metadata (`$schema`, `secretResolver`, `pi.chords`/`pi.sessionNaming`).
+Covered paths: project/user/org-dir compilation, the launch bootstrap preview,
+`templates create/edit --config`, and `settings user|org edit|set` — the settings
+verbs validate the edited config locally first (types and retired keys fail
+before any write request) and throw on non-bundle keys with the fix, so an
+explicit `set reuse true` fails visibly rather than vanishing.
+
+## Retained: `config.json`
+
+- `image` — custom images; unset tracks the launcher (`defaultImage`).
+- `resources.{cpu,memoryGB,diskGB}` — sizing feeds the derived image ref and the server request.
+- `egress.{mode,builtins,allow}` — network policy. `builtins` covers only what a committed file cannot state (git remote, env-file base URLs); `allow` admits the rest under `allowlist`.
+- `name` — project identity for pod naming and list scoping; null derives from the directory.
+- `template` — client-only pin selecting the template layer; never travels.
+- `workdir` — not fixed. The server echoes it (`ResolveReport.workdir`, `resolvedConfig.workdir`), `receive` gates paths against it, and custom images may need a non-`/workspace` root.
+- `initTimeoutSeconds` — server-side init budget (request semantics, not layout).
+- `initOnFailure` — server-side init failure policy (`abort`/`prompt`/`continue`).
+- `labels` — server-side pod labels (provisioning).
+- `idleTimeoutMinutes` / `archiveAfterMinutes` — server idle/archive policy, surfaced in status/retention.
+- `pi.model` / `pi.thinking` — defaults; per-launch `--model`/`--thinking`/`--extension`/`--skill`/`--prompt-template` travel as `piOverrides` (pod-local absolute paths, appended to the configured `pi.args`).
+- `pi.command` / `pi.args` — how the pod starts pi (`buildPiArgv`); niche wrappers are real uses.
+- `pi.hostConfig.{settings,packages}` — live gates. `settings` is enforced
+  server-side; `packages` is enforced on both sides (local sanitize/filter plus
+  the server install gate).
+- `pi.chords` / `pi.sessionNaming` — client-only UI preferences, stripped before anything travels.
+- `secretResolver` / `$schema` — client-only op:// resolution config / schema hint; never travel.
+
+## Retained: CLI surface (complete inventory)
+
+Global: `-v/--verbose` (redacted debug logging), `--version`, `-h/--help`, `-y/--yes`
+(answers exactly the prompts each command documents), `--` (everything after
+belongs to pi verbatim). Launch-only: `--template` (apply a template),
+`--on <pod|self>` (co-locate on a machine;
+refuses `--dry-run` and forks with a reason), `--reuse` (warm-disk
+reuse of this repo+branch's newest stopped pod), `--no-seed` (empty workspace),
+`--dry-run` (resolve + print, create nothing). Out-of-scope flags warn and are
+ignored, except `--dry-run`/`--on`-with-fork which are usage errors.
+
+- Launch (bare `pipod`, the default): prompt words and `--model`/`--thinking`
+  (server `piOverrides`) plus `--tui-mode` (local layout only) after `--`;
+  anything else after `--` is rejected with a pointer to `pi.args`.
+- `list [pod]` (`ls`): stable short refs; project/template scoping by default.
+  `-a/--all` (whole account), `--archived` (state filter, orthogonal to scope),
+  `--template` (filter), `-q/--quiet` (ids only, for piping). With a pod arg,
+  shows that machine's co-located group.
+- `attach [pod]` (`a`): rejoin a session; archived pods offer restore (`-y`
+  accepts). After `--`: startup prompt words and `--tui-mode`.
+- `stop [pod…]`: immediate stop, disk kept; co-located pods stop with the host.
+  It never confirms, so `--yes` warns instead of pretending otherwise.
+- `fork <pod>`: new pod from a session fork (`--session` picks the file).
+  Accepts the launch template/dry-run flags; `--on` refused, reuse
+  never applies (fresh sandbox, workspace not copied — hence the warning).
+- `rename <pod> <name>`, `send [pod] <path>` (host→pod, `-y`), `receive [pod]
+  <path>` (pod→cwd, workdir-relative or absolute inside it, `-y`).
+- `archive [pod…]`: logical archival. `-a/--all`, `--template`, `--idle
+  <duration>` (4h/2d/30m) select; `--dry-run` previews; `-y` skips the bulk
+  confirm. `restore [pod…]` reverses it (`-a/--all`, `-y`; no filters).
+- `gc`: retention report over every pod (always global — it takes no `--all`).
+  `--delete` performs the reclaim, `-y` skips its confirm.
+- `jobs [action]`: server-run scheduled launches from local job files.
+  `list` (default, `-q`), `show`, `runs`, `activate`, `pause`, `resume`, `rm`,
+  `push` (promote files; `--org` is a boolean after the action — a login-style
+  `--org <alias>` placed before `jobs` is rejected rather than mis-scoped), `pull` (to
+  `~/.pi-pod/jobs/` or `--project`'s `.pi-pod/jobs/`), `diff` (exit 1 on drift).
+  `-y` skips confirms / overwrites on pull.
+- `credentials [action]`: account model-provider sign-ins (tokens stay server-side).
+  `list` (default), `connect [<provider>]` (bare = every connectable provider;
+  `--api-key` for key entry, `--from-pi` to import the local pi key),
+  `reconnect`, `test`, `remove|rm [--yes]`.
+- `secrets [action]`: four layers (org, user, template, project-file wins).
+  `list` (default: winner + shadows per name), `set <scope> <NAME>[=value]`
+  (hidden prompt/stdin without `=`), `rm|remove|unset`, `sync <scope>` (server
+  scopes only; `--file`, `--prune`, `--dry-run`). `template/<name>` addressing;
+  provider credentials refused in template scope.
+- `templates [action]`: personal by default, `--org`/`share` for org-wide.
+  `list`, `show`, `create <name>` (`--config <file>` for an explicit config,
+  `--from-here` to compile the project — mutually exclusive; `--init-script` /
+  `--bake-script` to layer contents; `--description`; `--with-secrets` requires
+  `--from-here`), `edit` (`--name/--description/--config/--init-script/--bake-script`;
+  `--org` rejected — org-wide goes through `share`; whole-snapshot replace goes through `push`), `share` (one-way),
+  `rm|delete [-y]`. A global `--yes` is honored (no false scope warning).
+- `push [template [<name>]|user|org]`: whole-bundle replace from the layer's
+  local source (project `.pi-pod/`+`.pi/`, user `~/.pi-pod`+`~/.pi/agent`, org
+  `~/.pi-pod/org/` or `--dir`), after a diff preview. `--with-secrets` uploads
+  env values (else a prompt per bundle); `-y` applies without confirming.
+- `pull [layer]`: reverse of push (same sources; `--dir` for org; `-y`).
+  Client-only keys, host-coupled settings, and model credential values survive;
+  server scripts with no local file warn instead of writing.
+- `diff [layer]`: same sources, secrets by name only; exit 1 on drift (`--dir`
+  for org; no `-y` — it never writes).
+- `settings <user|org> [show|edit|set <key> <json-value>]`: config-only
+  compare-and-swap edits (scripts/Pi files untouched — that is `push`).
+  `show` prints JSON; `edit` uses `$VISUAL`/`$EDITOR`; `set` takes a dotted key
+  plus a JSON value. Templates are not a settings scope (hint points at
+  `templates`).
+- `login`: Zitadel PKCE in the browser. `--server`, `--issuer` (self-hosted),
+  `--org` (domain pin), `--token` (dev/CI JWT). `logout` revokes and deletes
+  auth; `whoami` reports server/user/org/permissions (exit 1 signed out);
+  `account` / `org-admin` open the consoles.
+- `doctor`: per-layer diagnosis (auth, server, org, secrets, resolve) plus the
+  workspace-seed prediction. `--template` plans the checked launch.
+  Works signed out; exit non-zero on failure.
+- `init`: scaffolds `.pi-pod/` (`config.json` with no asserted defaults,
+  `env.example`, owner-only `env`, executable `init.sh`; no `bake.sh` until
+  needed). `--force` overwrites scaffold files (never `env`). Warns when
+  shadowing an enclosing project.
+- `update`: self-upgrade (registry or git checkout + rebuild); `--dry-run`
+  reports only.
+
+## Standardized without a flag day
+
+Local validation deliberately does not claim to pre-validate everything the
+server enforces: long-retired keys (`repo`, `autoDelete`, `orphanTtlMinutes`,
+`pi.version`, detach sequences, …) warn as ordinary unknown keys and still run
+(pinned by tests) — the server bundle contract is authoritative for anything
+beyond the simplification-retired set above, and its 400 names any key it will
+not store.
+
+- Bundle bodies still carry script *contents* and flat Pi files; only config
+  path pointers were removed. Conventional paths are fixed:
+  `.pi-pod/env`, `.pi-pod/init.sh`, `.pi-pod/bake.sh` (scaffold, secrets,
+  compile, pull, and launch-preview all share the `PROJECT_*` constants; the
+  org layer already did).
+- `TemplateBody.piSettings` accepts only the flat file map on writes; reads
+  still accept legacy `{user,project}` via `flatPiSettings` for old servers and
+  un-migrated rows (a new server flattens stored legacy rows on read; they
+  normalize on next write).

package/docs/extension-aux-bridge.md

@@ -0,0 +1,96 @@
+# Extension aux bridge: local rendering + pod-side completions
+
+Server-attested pod extensions run twice: in the pod (authoritative) and in the
+launcher (rendering hooks only — entry/message renderers, markdown transformers —
+via the launcher's own `ExtensionRunner`). Two bridges connect the halves.
+
+## 1. Command ownership: the pod owns every slash command by default
+
+This is deliberate. An attested extension's `/name` can close over pod-side state
+(`pi-lightweight-llm`'s `/plan`-style flows, `pi.exec` handlers): routing it to the
+launcher unconditionally would hijack that state. So bare `/name` input always
+crosses the wire exactly once for the pod copy to run. The local copy never
+intercepts, never shadows autocomplete, and never double-executes.
+
+Run a command locally only when you mean it:
+
+- `/pod local <name> [args]` — run the launcher-side copy with the real TUI
+  context. Strict: an unregistered name errors honestly and is never forwarded,
+  so one input can never execute in both places. `/pod local` alone lists the
+  locally rendered commands. Tab-completion covers `/pod local <name>`.
+- `localCommands` (session option, default empty) — names that run locally
+  directly, e.g. `["transcript"]`. An allowlisted name with no local
+  registration falls through to the pod (single owner, no duplicate run).
+
+Same-name registrations from different local extensions collide loudly: `/pod
+local` reports every claimant's `sourceInfo` and runs none, instead of guessing.
+
+### pi-lightweight-llm requirement (unchanged upstream, v0.1.4)
+
+Its summary rendering needs the TUI context (`supports: ctx.mode === "tui"`),
+which only the launcher side has. It registers `transcript`, `tool-summaries`,
+and `lightweight-llm`. Out of the box `/transcript` runs in the pod, where the
+RPC-side copy cannot render summaries. To get local summaries, either run
+`/pod local transcript summary…` per invocation, or opt `transcript` into
+`localCommands` for the session. Generic aux model calls (`find` /
+`hasConfiguredAuth` / `complete` below) work regardless — no setting needed.
+
+## 2. Auxiliary completions: `ctx.modelRegistry` backed by the pod
+
+Pod credentials never cross to the launcher, so the launcher-side registry is a
+facade:
+
+- Metadata (`find`, `getAll`, `getAvailable`, `hasConfiguredAuth`,
+  `getProviderDisplayName`, `isUsingOAuth`, …) reads the client-side model
+  catalog + auth snapshot: point-in-time, pod-authoritative, sync just like
+  native. Secret-bearing (`getApiKeyAndHeaders`, `getProviderAuth`,
+  `getApiKeyForProvider`) and provider-mutating (`registerProvider`, …) methods
+  throw explained errors.
+- `complete(model, context, options)` runs pod-side through the semantic
+  `aux_complete` gateway message, executed by the pod's real `ModelRegistry`
+  as a turn-external call: no transcript entries, no main-model change,
+  `cacheRetention: "none"` (accepted because unchanged callers always pass it;
+  any other value is rejected). Old pods (extension < 11) fail with an actionable
+  "restart Pi in the pod" error, never a hang.
+
+### Text-only contract (explicit, not full native parity)
+
+Only `{systemPrompt, messages}` with user/assistant text cross. Everything else
+is **rejected, never silently dropped**: `tools` and sampling options
+(`temperature`, `samplingParams`, …), transports, headers/env, image/audio and
+tool-result content, thinking blocks. The pod runs the call through its real
+`ModelRegistry.complete` with the native `reasoningEffort` option passed through
+verbatim (including `"off"`) — thinking semantics stay exactly the pod's native
+per-API behavior, provider-specific with no bridge-level translation. Empty-text non-terminal outcomes (toolUse /
+deferred / pending) fail rather than fabricate `ok:true` with empty text.
+Usage (including cost) passes through untouched.
+
+### Bounds (each side enforces its own; the lower wins)
+
+| Bound | Value |
+|---|---|
+| Concurrency, per launcher session / per pod session | 4 (`aux_busy`) |
+| Timeout default / cap | 60s / 5min client; gateway answers by min(timeout, 120s); pod ceiling ~130s |
+| System prompt | 16KB chars |
+| Messages | 16 entries × 64KB chars |
+| maxTokens default / cap | 2048 / 4096 |
+| Wire request/response | 256KB base64url each |
+
+### Cancellation and lifecycle
+
+Every call has its own id, deadline, and `AbortSignal`: aborting sends
+`aux_cancel` and fails only that call — never the main turn. An already-aborted
+signal fails before any transport use; a reply that arrives after abort,
+timeout, or session invalidation is discarded, never returned as success.
+Disconnect and session replacement (`/new`, `/fork`, `/resume`, `/pod switch`,
+reconnect recovery) discard pending waits before rebind; in-flight pod
+executions are the gateway's to cancel, and their late replies correlate to
+nothing. Shutdown emits `session_shutdown(quit)` to local handlers while the UI
+and caches are still live, then invalidates the host.
+
+`session_tree` is runner-local in pi (never on the wire): the runtime
+synthesizes it after local tree navigation so TUI-mode capabilities rescan,
+with the native `{newLeafId, oldLeafId, fromExtension}` payload.
+Session start/shutdown use pi's own reasons (`startup/new/resume/fork`,
+`quit/new/resume/fork`) with session-file handoffs, so mode-gated capabilities
+reset exactly like in-process pi.

package/docs/image-attachments.md

@@ -0,0 +1,58 @@
+# Local image attachments
+
+The TUI runs on your machine; the agent runs in the pod. When your prompt names an
+image file that exists **on your machine**, pi-pod reads it locally, processes it with
+pi's own image pipeline, and sends it inline with the prompt — the pod never needs the
+file. Anything that does not resolve locally is left byte-identical, so pod-side `@`
+references and pod paths keep working exactly as before.
+
+## What gets attached
+
+- Clipboard pastes (pi saves the clipboard image under your `/tmp` and inserts the
+  bare path), drag-dropped files, `@screenshot.png` mentions, and typed paths —
+  absolute, `~/…`, `./…`, `../…`, quoted, or `file://…`. Bare absolute paths stay
+  eligible on purpose: that is exactly what pastes and drag-drops insert.
+- Detection is by content sniff, not suffix: PNG, JPEG, GIF, and WebP go through pi's
+  resize to inline limits (2000px, ~4.5MB); BMP, animated PNG, and anything else gets
+  one PNG conversion attempt first.
+- The sent text keeps your words and gains one marker line per image:
+  `<file name="shot.png"></file>` (or an `[Image omitted: …]` note when a real local
+  file could not be attached). The marker carries only the **basename**, XML-escaped —
+  the pod can never open the host path, so the full path would only leak your
+  directory layout into the persisted transcript. The marker is what you see echoed
+  in your own message.
+
+## Bounds
+
+These mirror what the gateway enforces on `prompt` / `steer` / `follow_up`, so a
+prompt built here is never rejected server-side (a rejected prompt sends nothing at
+all — degrading an over-budget image to a text reference is strictly more useful):
+
+- At most **8 images per prompt, including images already attached** (e.g. by an
+  extension). Extras stay plain text and you get a warning.
+- At most **8 MiB decoded per image** and **32 MiB of base64 total** across the turn
+  (~24 MiB decoded). Over-budget images are omitted with a note, never sent.
+- Reads are bounded (one open, one stat, one capped 24 MB read), regular files only —
+  never directories, devices, or sockets. A file that grows mid-read is detected, not
+  loaded. Only paths your prompt text actually names are read; nothing is scanned
+  speculatively.
+- Extension-supplied message parts are forwarded verbatim and never scanned: only text
+  you typed (or pasted) names files on purpose. A bare word like `a.png` in prose
+  does **not** attach (only `@a.png` does), and URLs and `data:` URIs never attach.
+
+## What the pod sees
+
+Images ride the existing `prompt` / `steer` / `follow_up` RPC `images` field — the
+same shape pi's own `@file` CLI attachments produce. No new protocol, no server
+change. One-shot prompts (`pipod attach <pod> -- "look at ./shot.png"`) attach the
+same way; attach failures are reported on stderr there, as a TUI notice here.
+
+## Limits
+
+- The image bytes travel **inline** with the turn; the file itself is not copied into
+  the pod. If the agent later tries to `read` the host path inside the pod, that read
+  fails — but the model already has the image, so it does not need to. (Copying the
+  file into the pod workspace would need a server-side upload channel; that is
+  intentionally out of scope.)
+- Pod-side images need no help: `@` completion already resolves against the pod
+  workspace, and the pod-side `read` tool returns those images itself.

package/docs/personal-workstation.md

@@ -0,0 +1,132 @@
+# Personal workstations, and the SaaS fields the client hides
+
+pi pod ships as one client for two products.
+
+- **Self-hosted (open source).** The sandbox runtime runs beside the server on hardware the
+  operator already pays for. There is a shared fleet, and there is no plan, no metered hour and
+  no spend cap anywhere in the system.
+- **SaaS.** Every user gets a whole machine of their own — a **workstation** — which sleeps when
+  idle and is started again on demand. Hours are metered and capped.
+
+The client is written so that the second product's surfaces simply do not exist under the first.
+This file is the contract it implements, and it is also what a server change has to match.
+
+## 1. Waking a workstation
+
+A workstation that is asleep or coming up refuses any call that needs it. That refusal is
+**HTTP 503** with a typed detail:
+
+```json
+{
+  "error": "Your workstation is starting. This may take several minutes",
+  "detail": {
+    "kind": "admission",
+    "reason": "host_starting",
+    "resource": "transitions",
+    "unit": "count",
+    "retryable": true,
+    "hostId": "boat-…",
+    "statusHref": "/v1/workstations/boat-…",
+    "state": "starting",
+    "retryAfterMs": 10000,
+    "operation": {
+      "id": "…", "kind": "resume", "state": "running", "phase": "command:activate",
+      "deadlineAt": "…", "retryAt": null, "errorCode": null
+    }
+  }
+}
+```
+
+`kind`/`resource`/`unit` are constants and are what identify the shape. `reason` is one of
+`host_starting`, `host_stopped`, `host_deleted`, `host_retired`,
+`host_requires_reconciliation`, `boat_starts_disabled`; `retryable` on the wire is
+authoritative. The WebSocket equivalent is close code **4420** with reason `host_starting`,
+`host_stopped` or `host_archived` — the same code an idle pod uses, so the reason is what tells
+them apart.
+
+`src/account/workstation.ts` validates all of it as strictly as the server does on the way out:
+the host id against the workstation route's own rule, `statusHref` **recomputed from the id and
+compared** rather than trusted, `retryAfterMs` bounded to 0–300 s, the operation reduced to the
+seven fields `GET /v1/workstations/:hostId` exposes. A malformed field means "no detail", never
+a forged one.
+
+Then a real launch waits: poll the durable status, re-issue the same request each cycle, and
+render elapsed time plus the server's own phase. The operation deadline is not a client exit.
+The wait ends when the request succeeds, the user cancels, the refusal is terminal, or two
+observed start cycles end stopped without the request succeeding. It does not ask the user to
+come back and run the command again. A dry run reports the demand and does not wait.
+Cancelling ends the client's wait, not the machine's start.
+
+Install a waiting client from the merged source commit (`npm ci && npm run build` in `pi-pod`,
+then point the launcher at that `dist/cli.js`). `pipod update` only upgrades a git checkout or
+an npm install; a release directory under `~/.local/share/pipod/releases` is neither.
+
+### The numbers, and why the copy says "several minutes"
+
+Measured in production on 2026-09-10 — ten operations across two hosts in one evening. These are
+measurements, not an SLA:
+
+| transition | measured |
+|---|---|
+| cold create → ready (host with eight pods) | 407 s |
+| cold create → ready (empty host) | 708 s |
+| resume → ready | 243 s, 690 s, 483 s, 312 s, 357 s |
+| pod launch → ready on an already-warm workstation | 46 s |
+
+So: no copy anywhere promises seconds, and nothing counts down to a number the server did not
+send. A workstation wait must never render as fleet pressure ("the fleet has no room", "ask an
+owner to register capacity") — nobody registers a workstation — and never as data loss. A
+stopped workstation keeps every workspace on its own disk.
+
+## 2. The optional plan block
+
+`GET /v1/me` may carry a `billing` object. Every field is independently optional:
+
+```jsonc
+"billing": {
+  "plan":        { "id": "standard", "name": "Standard" },
+  "period":      { "start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z" },
+  "activeHours": { "used": 12.4, "included": 200 },
+  "spendCap":    { "limitUsd": 40, "spentUsd": 3.2, "state": "ok" },
+  "trial":       { "state": "active", "endsAt": "2026-09-24T00:00:00Z", "hoursRemaining": 8 },
+  "state":       "ok"
+}
+```
+
+`spendCap.state` ∈ `ok approaching reached`; `trial.state` ∈ `active expired none`; `state` ∈
+`ok cap_reached trial_expired payment_failed grace`. Numbers are finite and non-negative;
+`used`/`spentUsd` may exceed the allowance, because overage is a real thing that happens.
+
+`pipod list` renders one dim footer line from it:
+
+```
+pi pod   Standard · 12.4 of 200 active hours · spend cap $40 ($3.20 used) · period ends 2026-10-01
+```
+
+Each segment is dropped independently when its data is missing.
+
+**When the object is absent the whole surface is absent** — no zeroes, no "unknown", no empty
+heading, no error. That is the edition boundary: a self-hosted operator must never be shown a
+spend cap they do not have. `--quiet` is unaffected in both editions.
+
+The client never computes, projects or prices anything. "12.4 of 200 active hours" is allowed
+because the server sent both numbers; "48 hours left, about $12 more" is not.
+
+## 3. Billing refusals
+
+When the account's own billing state blocks a start, the refusal carries
+`detail.reason` ∈ `spend_cap_reached`, `trial_expired`, `payment_required`, `billing_required`,
+`payment_failed`, optionally with `limitUsd`, `spentUsd`, `periodEnd`, `endsAt`,
+`hoursRemaining`, `graceDaysRemaining`.
+
+The client says what happened, what it cost and what to do — using only the figures that
+arrived, and naming no price, plan or policy of its own. These are decisions, not waits: they
+never enter a retry loop.
+
+## 4. If you are changing the server
+
+Adding these fields is additive and safe: an older client ignores what it does not know, and a
+server that omits them keeps the surface hidden. Keep `statusHref` derivable from `hostId`,
+keep `reason` inside its allowlist, and keep every `billing` field optional — the client's
+tests assert both the present and the absent shape, and the absent shape is the open-source
+product.

package/docs/sandbox-cost-controls.md

@@ -0,0 +1,77 @@
+# Sandbox cost controls — client behavior
+
+Product policy (the server enforces; this client only presents it):
+
+- **Standard shape:** 2 shared vCPU / 4 GiB memory / 20 GiB writable disk per sandbox.
+  Shared image layers are not charged repeatedly; usable space is slightly under quota
+  (filesystem metadata).
+  The `sandbox` fleet holds a documented full local-disk
+  reservation per stopped workspace, so stopped rows render `local disk retained`.
+  A cold-storage claim additionally needs
+  sandbox-confirmed archive (`sandboxState=archived`); a bare logically-hidden row claims
+  nothing about storage.
+- **Concurrency:** up to **20 concurrent sandboxes per platform user**,
+  across organizations. Co-located (`--on`) children share the host's machine and hold no
+  extra slot. The server's configured value is authoritative — when the client names a cap
+  number it always quotes the server's refusal, never a local constant.
+- **Retention:** 15 minutes of genuine inactivity stops a pod (waiting on a model,
+  dialog, network, or detached build is not idle); 60 stopped minutes archives it.
+  Archive uploads and verifies before local disk is released. (Durations are the
+  platform defaults; an organization policy may set its own — clients never hardcode
+  them into refusal copy.)
+- **Larger memory:** 8 GiB is capability-gated opt-in. The standard stays 4 GiB. The client
+  never clamps an 8-GiB request down itself: it either receives 8 GiB on a qualified host
+  or a clear unsupported/capacity refusal, and any server clamp is printed verbatim.
+
+## Statuses the client shows
+
+| What you see | Meaning | Cost to wake |
+| --- | --- | --- |
+| `running` | Running sandbox | — |
+| `stopped` | Active row, stopped sandbox; workspace files kept on local disk | `attach` restarts in seconds |
+| `stopped · cold storage` | Archived sandbox under an active row | Restores in seconds-to-minutes depending on workspace size |
+| `archived` / `archived · cold storage` | Archived row (`list --archived` shows it), its sandbox stopped | `restore`, then attach as above |
+| `failed` | A launch or start that ended with a reason | `pipod gc --delete` removes it |
+| `preparing` / `provisioning-sandbox` / `running-init` | Still starting | Wait; do not create a duplicate |
+
+Archive is hide, not delete: it stops the pod and hides it. `stop` releases compute now and
+keeps the disk without hiding the pod. Cold storage follows the server's archive policy.
+`restore` returns the row; attach starts the sandbox when needed. There is no universal
+10-second restore promise: expect seconds for stopped disks and seconds-to-minutes for
+archived workspaces depending on size, longer near quota.
+
+## Capacity errors
+
+- **Per-user / org concurrency (409):** stop a running pod (`pipod stop <pod>`) or wait for
+  idle sleep, then retry. Do not relaunch in a loop.
+- **Fleet at capacity (503):** retry shortly without creating duplicates; stopped pods keep
+  disks and archived pods restore later. Persistent pressure needs registered capacity
+  (an owner action), not client retries.
+- **Temporarily unavailable (409):** the pod is mid-transition — retry shortly.
+- **Unsupported shape (400):** the worker shape is not available; retry at standard size.
+- **Restore-first (409):** `pipod restore <pod>`, then retry.
+
+The client renders these from validated codes and numbers only. Raw backend text, URLs
+with credentials, and secrets stay redacted. A lost launch reply is resolved by listing
+first (adopt the landed pod) rather than blindly relaunching.
+
+## Bounded capacity wait (capacity contract §1)
+
+When the fleet is full, a valid entitled launch/wake queues instead of failing at once
+(rollout-gated server-side; older servers omit the field and keep immediate errors):
+
+- `waiting` — the pod holds one concurrency slot but no host reservation. The launch
+  narrates `waiting for capacity — …` once per reason with time left on the final
+  deadline (default 60s total). Ctrl-C before Pi starts keeps its existing meaning:
+  the fresh pod is deleted, which ends the wait. `DELETE /v1/pods/:id/capacity-wait`
+  (client `cancelCapacityWait`) ends the wait cooperatively and keeps the pod row.
+- `admitted` — a retry found room; provisioning continues normally.
+- `expired` — FINAL failure for this launch: no room before the deadline. The client
+  reports the reason copy and stops; launch again by hand, never auto-duplicate.
+- `cancelled` — the wait was cancelled (or the pod deleted); the row survives deletion
+  only if it was not the thing deleted.
+
+Wait progress reuses the existing `GET /v1/pods/:id?wait=<ms>` long poll — no new
+client request fields. Typed `detail.reason` values (`memory/cpu/disk/transition/network_capacity`,
+`memory_debt`, `fairness_degraded`, `fleet_capacity`, `unsupported_shape`) map to the
+same actionable copy as the immediate errors.