@zergai/ztc 0.4.1-dev.36919234045 → 0.5.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # ZTC — Zerg Terminal Client
 
-> **License notice:** ZTC 0.2 is source-available, not open source. Free company
+> **License notice:** ZTC is source-available, not open source. Free company
 > use is limited to purpose-bound evaluation. Commercial development, ongoing
 > company engineering, customer work, and other Commercial Use require a
 > separate commercial license. By exercising a permission in the package
@@ -10,7 +10,7 @@
 An autonomous AI agent for the terminal. ZTC combines Claude-style conversational coding with native computer control, multi-agent orchestration, and a Voyager-inspired routine system for autonomous operation in graphical applications.
 
 ```
-  ╭─ ZTC v0.2.0-canary.2 ───────────────────────────────────────────────╮
+  ╭─ ZTC (illustrative session) ───────────────────────────────────────────────╮
   │ Provider: Anthropic  Model: claude-sonnet-4-20250514             │
   │ Working directory: ~/projects/my-app  Branch: main                │
   ╰───────────────────────────────────────────────────────────────────╯
@@ -30,27 +30,32 @@ An autonomous AI agent for the terminal. ZTC combines Claude-style conversationa
 
 ## Quick Start
 
-The ZergAI organization distribution is `@zergai/ztc` for the 0.2 canary.
-Install it with `npm install -g @zergai/ztc`. It provides the same `ztc` and `zerg` commands,
-license, and package exports; use `@zergai/ztc/<export>` for scoped imports.
-Install only one distribution globally because the command names overlap.
-Existing stable users can keep the legacy package below; canary releases do not
-move `zerg-ztc@latest` from the 0.1 line.
+ZTC is currently in beta. The public npm distribution is `@zergai/ztc`.
+See the [public Quickstart](https://zergai.com/docs/ztc) for install,
+authentication, your first plan, named sessions, platform support, and licensing.
 
 ```bash
-# Install the 0.2 canary CLI
+# Check the published version and install the public CLI
+npm view @zergai/ztc version
 npm install -g @zergai/ztc
+ztc --version
 
 # Start with a read-only inspection of a real project
 ztc --cwd /path/to/project --plan
 ```
 
+The package provides `ztc` and `zerg`; install only one ZTC distribution globally
+because their command names overlap. Published package versions can differ from
+the source version used during development. Use `ztc --version` to identify your
+installed release. For reproducible installs, use `@zergai/ztc@<version>` with the
+version you selected.
+
 On first launch, choose one authentication route in the welcome message. Then
 describe the project outcome you want. Review the plan and run `/execute` when
 you are ready for ZTC to make the proposed changes.
 
 Authentication options are Zerg Router browser login (`/auth login`), a provider API key
-(`/config key <api-key>`), or Claude Code OAuth (`claude setup-token`, then
+(`/config key <provider> <api-key>`), or Claude Code OAuth (`claude setup-token`, then
 `/model claude_code`).
 
 For browser login at **zergrouter.com**, run `ztc auth login` in your shell or
@@ -92,9 +97,6 @@ in the browser mirror. Run `/help` for the full command list.
 # Install dependencies and build
 npm install && npm run build
 
-# On macOS, npm install also creates ZTC Desktop.app in Applications.
-# Set ZTC_SKIP_DESKTOP_APP=1 to skip that best-effort launcher install.
-
 # Build native Rust binaries (screen capture, input injection)
 npm run build:rust
 
@@ -107,14 +109,14 @@ npm start
 
 ### Requirements
 
-- Node.js >= 20
+- Node.js 20.19+ on the 20.x line, or 22.12+
 - Rust toolchain (for native binaries — `cargo`)
 - One authentication route: Zerg Router (`/auth login` or `ztc auth login`), provider API key (`/config key`), or Claude Code CLI OAuth (`claude setup-token` + `CLAUDE_CODE_OAUTH_TOKEN`)
 
 The JS and headless surfaces support macOS, Linux, and Windows.
-Native payload support for the `0.2.0-canary.2` npm prerelease is `darwin-arm64`
+The published beta native payload supports `darwin-arm64`
 only (`aarch64-apple-darwin`). Interactive TUI, desktop, audio,
-and computer-control binaries from this prerelease are supported only on Apple
+and computer-control binaries from this beta are supported only on Apple
 Silicon macOS. Other platforms may use the JavaScript/headless APIs, but this
 beta does not claim an interactive native payload for them.
 
@@ -125,6 +127,8 @@ beta does not claim an interactive native payload for them.
 - **Streaming responses** with real-time tool execution traces
 - **Context management** — automatic compaction at configurable thresholds, manual `/compact`
 - **Session persistence** — auto-save, resume with `ztc resume` or `--resume`, per-project session storage
+- **Ephemeral host tools** — hosts can set `ZTC_EPHEMERAL_TOOL_NAMES` to a comma-separated list of exact tool names whose arguments and results must remain live-memory only. Configure it before startup. These tools keep safe call IDs and omission markers in saved transcripts/evidence; resuming cannot recover their private payloads. This does not retroactively erase existing files or provider-side retention. Embedders may instead supply matching `ToolResponseStoreConfig.ephemeralToolNames` and `SessionRuntimeState.ephemeralToolNames` policies.
+  Generic tools can opt in only selected calls with `ZTC_EPHEMERAL_TOOL_RULES`, a JSON array such as `[{"toolName":"app_invoke","argument":"command_id","values":["app.observe","app.act"]}]`. Rules match exact top-level argument values, never patterns or executable expressions; ordinary calls remain durable. Embedders must pass matching `ephemeralToolRules` to the store and session runtime state, and supply call `args` in `ToolResponseStore.put` context. These controls cover persistence, not the live events sent to the owning host, which must sanitize its own logs and UI traces.
 - **Mux-aware resume** — `ztc resume` restores the saved conversation and, when present, the prior `zmux` layout plus child ZTC panes
 - **Sub-agent delegation** — spawn isolated agents for context-heavy research
 - **Plan mode** — read-only codebase exploration, then structured implementation
@@ -145,21 +149,54 @@ beta does not claim an interactive native payload for them.
   orchestrator registry
 - **Message bus** — inter-agent communication across panes
 
-### ZTerm Desktop
+### ZTC Desktop
+
+On Apple Silicon macOS, launch the native desktop surface explicitly:
+
+```bash
+ztc --desktop --cwd /path/to/project
+```
+
+`npm install` installs the CLI; it does not automatically create an application
+bundle. The package includes an optional launcher installer. To create
+`ZTC Desktop.app`, run it explicitly after installing the scoped package:
 
-On macOS, `npm install` creates `ZTC Desktop.app` in `/Applications`
-when that directory is writable, otherwise in `~/Applications`. Opening
-the app launches `ztc --desktop --cwd "$HOME"` so the native ZTerm
-surface starts from your home folder. Set `ZTC_SKIP_DESKTOP_APP=1` to
-skip app creation during install, or `ZTC_DESKTOP_APP_DIR=/path` to
-install the app bundle somewhere else.
+```bash
+node "$(npm root -g)/@zergai/ztc/scripts/install-macos-app.mjs"
+```
 
-The update-capable native renderer is distributed separately as `ZTerm.app`.
-After installing its DMG into `/Applications` or `~/Applications`, a normal
-`ztc --desktop` launch prefers that bundle over the packaged development binary.
-ZTerm checks its signed channel feed at startup, but downloads and installation
-remain explicit; a successful update starts its helper only after a forced
-session save, then resumes the owning ZTC session with a fresh renderer socket.
+The installer uses `/Applications` when writable, otherwise `~/Applications`.
+`ZTC_DESKTOP_APP_DIR=/path` selects another directory and `ZTC_SKIP_DESKTOP_APP=1`
+skips this optional installer. These variables do not change the npm CLI install.
+Opening the launcher starts `ztc --desktop --cwd "$HOME"`.
+
+The native desktop distribution currently uses `ZTerm.app` and its existing
+signed preview/stable channels. An unbundled `ztc --desktop` launch prefers a
+compatible installed renderer in `/Applications` or `~/Applications` over the
+packaged development binary.
+
+The bundled ZTC app implementation includes its own Node and matching agent.
+It starts from the app icon without a global Node or ZTC installation and uses
+the CLI's existing accounts, configuration and session stores. Its visible name
+and Finder icon are ZTC; `ZTerm.app`, the bundle identifier and channel trust
+remain compatible with the existing distribution. Signed bundled publication
+and the installed-user upgrade matrix remain pending; older published apps
+retain their renderer-only behavior.
+
+From a bundled app session, type `/desktop install-cli` to install an optional
+`ztc` command in `~/.local/bin`, or `/desktop install-cli /path/to/bin` to choose
+another directory. Installation preserves foreign commands and does not edit
+PATH or shell configuration. The command runs that app's agent with the same
+arguments, working directory and profile/config/session selection as the CLI.
+If the app moves, the command reports how to reinstall it. An agent cannot
+request installation on the user's behalf.
+
+The native Updates window saves **Check for updates on startup**, enabled by
+default. Downloads and installation require explicit actions. Bundled sessions
+use this app update path instead of npm updates. A successful update starts its
+helper only after a forced session save, then resumes the owning ZTC session
+with a fresh renderer socket. See [desktop release details](packages/zterm/RELEASES.md)
+for the current source implementation and publication gates.
 
 ### Voice & Media
 - **Voice dictation** — native Whisper transcription (Ctrl+R)
@@ -302,6 +339,42 @@ npm run dev -- --no-mux
 
 ### Pane Tools
 
+`/layout orchestrator` opens **Main** in the large left pane, **Decisions** above
+**Status** on the right. Decisions lists pending questions from child panes;
+select one and answer its wizard to resume that child. Escape leaves the request
+pending. Status shows each child's observed task, todo progress, blockers and
+reported or estimated tokens. Missing usage stays unknown. It reads runtime
+state without model calls, refreshes every ten minutes, and accepts `r` for an
+immediate refresh. Use `/layout orchestrator --refresh-ms 30000` to change the
+interval.
+
+`/layout pair` opens Main and one new worker. `/layout grid --workers 3` opens
+Main and three new workers (four by default). Opening a preset preserves existing
+pane processes in their earlier window. Launch directly with
+`ztc --layout orchestrator`, `ztc --layout pair`, or
+`ztc --layout grid --layout-workers 3`; use `--layout-refresh-ms` for the launch
+refresh interval. These flags require an interactive workspace.
+
+For a project preset, save `.ztc/layouts/review.yaml` and run `/layout review`
+or `ztc --layout review`:
+
+```yaml
+schema_version: 1
+template: orchestrator # orchestrator, pair or grid
+refresh_ms: 600000     # 1–86400000; applies to Status
+titles:
+  main: Review Main
+  decisions: Review Choices
+  status: Review Status
+```
+
+Grid presets also accept `workers: 1` through `32` and `titles.worker` for the
+worker title prefix. Names contain up to 64 letters, digits, underscores or
+hyphens; builtin names are reserved. Invalid files report their filename and
+schema error before starting a child. Named `/layout save`, `restore`, `list`,
+`delete`, `run` and `resume` remain available. Restored monitor commands belong
+to their original parent; open a fresh preset in a new parent.
+
 When running in zmux, the agent gains access to terminal pane management:
 
 | Tool | Description |
@@ -316,7 +389,7 @@ When running in zmux, the agent gains access to terminal pane management:
 
 Because `zmux` runs in the terminal alternate screen, outer terminal scrollback is not the right primitive once mux is always on. Instead, `zmux` keeps pane-local history and exposes a tmux-style inner scroll mode:
 
-- Mouse wheel scrolls the pane under the pointer by default
+- Mouse wheel scrolls the pane under the pointer by default; `/settings` → Display controls mouse capture and the wheel step (1–20 lines, initially 3)
 - Drag across transcript text and release to copy it, including in zoomed panes and scrolled history
 - Panes with scrollable history show a live scrollbar gutter on the right edge
 - Clicking the scrollbar gutter jumps to that point in history
@@ -422,6 +495,32 @@ its REST, SSE, asset, and media URLs while the proxy strips it upstream.
 
 In `zmux` mode the browser mirror can now focus panes, switch layout presets, toggle zoom, create ZTC or shell panes, close panes, and drive pane scroll position through the same mux state machine as the terminal client.
 
+### Human Attention
+
+`/attention` lists pending approvals, questions, blocked runs, failures, review
+requests and stale requests across the session's panes. Each item shows its
+agent, session, task, blocker, age and next action. Copy the item's ID to act:
+
+```text
+/attention show <ID>
+/attention answer <ID> <answer>
+/attention approve <ID>
+/attention deny <ID> <reason>
+/attention dismiss <ID>
+```
+
+Only the operator can answer or approve requests. Dismiss acknowledges a
+failure, review or stale notice; it cannot dismiss an open approval. Use
+`/attention list 2` for the next page of a large queue.
+
+The browser mirror's **Needs you** panel reads the same queue. Selecting an
+item opens its question or approval form. Answering in either the terminal or
+browser clears that exact request from both views. Reloading the browser keeps
+live request ownership; an old answer cannot resolve a newer request. Requests
+from exited panes become stale notices. Idle status keeps failures visible
+until acknowledgement or new work. Oversized forms stay available in their
+originating pane.
+
 ### Conductor Branches
 
 Launch the ZTC build from a running Conductor workspace branch:
@@ -528,7 +627,151 @@ resume [id]             Resume session (latest or by ID)
 --list-sessions         List saved sessions
 ```
 
-When a saved session includes `zmux` state, `ztc resume` restores the pane layout, focus, zoom state, and relaunch metadata for child panes as part of the resumed session. Child ZTC panes launched from mux now receive stable session IDs automatically, so nested agent conversations resume too.
+When a saved session includes `zmux` state, `ztc resume` restores the pane layout,
+focus, zoom and launch intent. Restored children remain inactive. Use
+`/layout run <pane-id>` for an ordinary saved process or
+`/layout resume <pane-id>` for its saved agent session. Child ZTC panes keep
+stable session IDs; restoration does not submit a new prompt or start their work.
+
+A replacement pane offers a saved task handoff from the same project, with an
+exact `ztc resume <id>` selector, source directory and checkpoint time. The offer
+does not start inference. Explicit resume includes that selected checkpoint in
+the standalone agent's context; a fresh pane starts a separate task. Hosted
+agents with a caller-owned system prompt retain that prompt unchanged.
+
+The handoff records the objective, pending corrections, process receipt handles,
+unresolved calls and any recorded blocker. A process exit code does not establish
+task completion, and a historical PID does not establish current ownership.
+Corrections retain their Enter or Tab intent, but resuming does not automatically
+send them or repeat unresolved tools. Inspect uncertain outcomes before continuing.
+Long text has a bounded preview with omission counts; its retained source message
+contains the full correction. The optional web mirror shows the same sourced
+checkpoint. Discovery is bounded, so use the exact session selector for older work
+that falls outside the offered history.
+
+The terminal and headless hosts save the exact harness tool call before executing
+it, then save its observed result or error before acknowledging it or continuing
+inference. A required checkpoint write failure stops that dispatch or continuation;
+repair the storage problem and inspect the original call before resuming. A late
+result belongs to its original turn, even when a newer turn has already started.
+Unresolved calls survive compaction and resume as unknown outcomes, without an
+automatic retry. A retained invocation ID cannot dispatch again or be reused for
+different arguments or another tool. This identity check does not deduplicate
+arbitrary commands issued with new IDs. Inspect the original command job or remote operation receipts:
+local cancellation does not establish that an external operation stopped.
+These checkpoints cover process interruption, not power-loss durability. Native
+provider builtins that execute outside the host cannot offer this predispatch
+barrier; harness-dispatched dynamic tools use it.
+
+Automatic session pruning is disabled by default. To opt in, set
+`"sessionRetentionCount": 50` in the active profile's `config.json`. At the next
+startup, ZTC keeps the newest 50 unnamed, unowned sessions in the workspace.
+Named sessions and sessions loaded or saved by a running process are retained
+in addition to that count, together with their tool responses. A paused process
+still owns its sessions; ownership ends when the process exits. Set the value
+to `null` or remove it to disable pruning. Zero removes all eligible sessions,
+so use a positive count when you want recent unnamed history to remain.
+Caller-managed `--session-file` storage is excluded from startup pruning.
+
+For shared remote files, configure a guarded session in the active profile:
+
+```json
+{
+  "remoteResources": [
+    {
+      "id": "media", "host": "server.example.com", "user": "media", "root": "/data/media",
+      "broker": { "url": "https://server.example.com/v1/resources", "tokenEnv": "ZTC_MEDIA_BROKER_TOKEN" }
+    }
+  ]
+}
+```
+
+Deploy the [immutable resource broker](remote-broker/README.md) first. Configure
+the same broker, resource identity and roots in each participating pane. Supply
+the credential through the named host environment variable. Credentials and
+execution endpoints are never accepted from model tool arguments.
+
+Guarded sessions use the `remote_resource` tool for bounded reads, listings,
+file writes, and deletion of files or empty directories. File operations require
+a lease on the configured root; status remains available for inspecting ownership.
+Unrestricted shell, network and plugin tools are blocked. Use normal mode with a
+built-in Router or direct API provider. Subscription/native provider paths and
+plugin hosts are not admitted in guarded sessions. The default transport uses
+authenticated HTTPS RPC and refuses legacy SSH execution. The receiver requires
+a non-root, read-only execution image and policy, with writable data on a separate
+filesystem beneath `/data`. Its workers use an absolute, isolated Python
+interpreter without shell startup or PATH lookup. A host-only numeric loopback
+HTTP exception is available for local development; external endpoints require HTTPS.
+
+Run `/resources show` in each pane to display its immutable owner ID, current
+owner, conflicts, lease generation, and up to 100 unresolved operation references
+from each journal (with their total counts). Claim with `/resources claim media 0`
+(use the displayed generation). Transfer with
+`/resources transfer media <generation> <target-owner-id>` after the target pane
+has inspected status. Stop with `/resources stop media <generation>`. These
+commands require user input; chat and queued prompts cannot grant ownership.
+The default lease lasts 900 seconds; claim or transfer accepts a final duration
+from 1 to 3600 seconds. An expired lease requires another confirmed claim.
+
+Leases are shared in the broker's persistent state volume, cover overlapping roots and
+symlink aliases, and remain enforced across client reconnects. Stop and handoff
+revoke the former owner's writes. Set `dry_run: true` on a managed operation to
+check its target and ownership before changing files. Removing profile settings
+does not lift a running session's guard; start a new session for local work.
+
+Guarded sessions show host-authored deletion receipt reports. Provider narration
+and displayed reasoning are withheld; the agent uses `ask_user` for questions.
+Opaque provider reasoning on tool-call turns is retained for API continuity,
+including saved-history replay, without rendering it as assistant narration. Each deletion
+has a host-generated operation ID and a remote journal entry written before the
+operation. Completion requires a persisted final receipt and verification of the
+exact target's absence, physical resource identity and parent directory. Reports
+state the verification time; later changes can alter that target again.
+
+Removed logical file bytes are reported separately from reclaimed quota or free
+space. This broker does not measure attributable quota changes, so reclaimed
+space is shown as unknown. Dry runs, failed operations, pending receipts and
+unverified target state cannot produce a verified completion report. Generic
+shell and native harness sessions receive evidence guidance without this guarded
+receipt enforcement.
+
+Writes and deletions persist a client call-to-operation record before dispatch,
+then a remote receipt before the effect. A lost reply, lost acknowledgement,
+pending receipt, or unverified result fences overlapping pathnames and known
+physical target identities. New tool-call IDs, a reconnect, a replacement file,
+another client journal, and ownership transfer do not lift that fence. Independent
+targets remain usable. Repeating an originating tool call never replays its effect.
+A broker rejection proving that the exact request was never admitted releases its
+local reservation without claiming an effect.
+
+If a reply is interrupted or uncertain, retain its operation ID. The agent can
+inspect the `remote_resource` `receipt` operation with `receipt_id`; this requires
+the originating owner, resource ID and a current lease. Inspection alone does not
+release admission. The current lease owner can perform confirmed recovery:
+
+```text
+/resources reconcile media <operation-uuid>
+/resources resolve media <operation-uuid> <observation-token>
+```
+
+Review the original receipt and the current target state before typing `resolve`.
+This accepts the inspected current state and releases admission; it neither
+replays an operation nor proves an uncertain earlier effect. A changed target or
+lease generation invalidates the observation token. A request that never reached
+the remote journal gets a durable cancellation record, so a delayed arrival cannot
+mutate the target after recovery. These recovery commands are user-only, and they
+remain available to the current owner after a confirmed transfer. Reads and dry
+runs do not release a fence. External filesystem writers are not serialized by
+the broker lock; inspect changed state before making a new decision.
+
+Client records live under `ZTC_CONFIG_DIR/remote-operations` (by default
+`~/.ztc/remote-operations`); a host can supply a separate journal directory. Guarded sessions resolve and pin
+that directory at creation, so changing the working directory cannot drop admission
+records.
+Remote receipts live in the broker's `/state/.ztc/resource-leases/receipts/`.
+Each journal retains at most 10,000 entries and declines new mutations at capacity.
+No automatic pruning removes unresolved evidence. Confirmed host maintenance must
+preserve operation tombstones and call linkage before archiving evidence.
 
 ### Modes & Features
 ```
@@ -577,6 +820,8 @@ When a saved session includes `zmux` state, `ztc resume` restores the pane layou
 
 Custom config profiles keep settings and sign-ins separate. Start one with `ztc --profile work`, or switch the running session with `/profile work`. `/profile create work` starts a new profile. Switching keeps the session ID and conversation while rebuilding the agent. A later `ztc resume` restores the session's saved profile unless you specify `--profile`. The default config stays at `~/.ztc/config.json`; custom named configs live at `~/.ztc/profiles/<name>/config.json`. Session history stays shared. Switching does not rewrite settings after the one-time migration described below.
 
+An expired or unsigned Router profile can be selected in the running session. The agent waits for sign-in, and ZTC shows `/auth login --url <profile-router-origin>` for that profile. The conversation stays available. Invalid settings and mismatched Router origins still roll back the switch.
+
 The source `scripts/ztc-dev` launcher defaults to the `dev` config profile. It uses
 the same `~/.ztc/profiles/dev/` settings and Router sign-in as `ztc --profile dev`.
 Set its Router URL and sign in separately when creating that profile; the name
@@ -586,9 +831,15 @@ selects the shared config root. `ztc-dev resume` also selects `dev` unless overr
 
 On first use of this release, each existing config profile adopts the new default settings once. Its account registrations, authentication, API keys, and credential-bearing integration settings are retained. Later edits to that profile are kept. New profiles start with the same defaults. The migration writes only the active profile's config file, so switching to an unused profile applies its migration then.
 
+`/settings display` includes **Prose reading rate**, which defaults to 9 words per second. Enter a positive rate or `off`; with the cap off, **Smooth streaming text** retains the existing smooth or instant display behavior. The cap applies to assistant prose, while reasoning, tool results, and messages containing fenced code retain their existing pacing. A completed answer can finish revealing after the provider stops; the full received answer is already retained in conversation history. New input or stopping clears the previous reveal.
+
+Running local shell tools show an observed output count and, when space permits, the latest output line. Their clock measures the selected tool call. After 30 seconds of silence, the activity row adds a quiet-output hint when space permits; silence can mean the command is waiting. These display observations are separate from the final command result.
+
 #### Bottom status line
 
-The terminal status line has independently ordered left and right fields. Values that are unavailable are omitted. In narrow terminals, lower-priority fields are hidden before mode, connection state, or active errors.
+The terminal status line has independently ordered left and right fields. Normal mode is implicit and omitted at every verbosity; Plan and Auto-accept remain visible. The main agent pane is named **Main** until you rename it. A confirmed user stop briefly shows **Stopped by you** while conversation history retains the interruption notice. Values that are unavailable are omitted. In narrow terminals, lower-priority fields are hidden before mode, connection state, or active errors.
+
+The native bar shows the configured help chord while its agent is idle; the default is `Ctrl+B ? help`. Prefix, scroll, and search modes keep their own controls. `Ctrl+B ?` opens shortcut and status-marker explanations, and `/help` describes the ZTC status fields. The field editor also explains the selected item.
 
 Pick and order the fields on the editor page: press Enter on either field row, run `/settings statusline`, or use `/config statusline edit`.
 
@@ -598,11 +849,11 @@ Every field paints at one of three verbosities, and the line pane shows the one
 
 | Variant | Context left | Queue | Connection | Mode |
 |---------|--------------|-------|------------|------|
-| `raw` | `70%` | `2` | `◉` | `●` |
-| `short` | `70% left` | `2 queued` | `◉ connected` | `Normal` |
-| `long` | `70% context` | `2 messages queued` | `Connection: connected` | `● Normal` |
+| `raw` | `70%` | `2` | `◉` | omitted |
+| `short` | `70% left` | `2 queued` | `◉ connected` | omitted |
+| `long` | `70% context` | `2 messages queued` | `Connection: connected` | omitted |
 
-`raw` is the datum on its own — the symbol, where the field has one. Fields with nothing to abbreviate, such as a session name, paint the same text at every variant. Each field defaults to whichever variant painted before variants existed, so an untouched config looks exactly as it did; only the fields you change are written to the config, and setting one back to its default drops the entry.
+`raw` is the datum on its own — the symbol, where the field has one. Fields with nothing to abbreviate, such as a session name, paint the same text at every variant. The Mode column above uses default Normal mode; non-default modes retain their icon at `raw` and their name at `short` or `long`. Fields keep their configured order and variants; only the fields you change are written to the config, and setting one back to its default drops the entry.
 
 The same settings are available as commands:
 
@@ -616,7 +867,7 @@ The same settings are available as commands:
 /config statusline reset
 ```
 
-Available fields are `mode`, `session-name`, `session-id`, `workspace`, `context-used`, `context-remaining`, `tokens-used`, `queue`, `background`, `provider`, `model`, `provider-model`, `emulation`, `effort`, `reasoning`, `input-mode`, `version`, and `connection`. `/config statusline show` includes the same list with descriptions. These commands follow the active `/config scope`; session-scoped changes stay in the current process.
+Available fields are `mode`, `session-name`, `session-id`, `workspace`, `context-used`, `context-remaining`, `tokens-used`, `cache-hit-rate`, `queue`, `background`, `provider`, `model`, `provider-model`, `emulation`, `effort`, `reasoning`, `input-mode`, `version`, and `connection`. `/config statusline show` includes the same list with descriptions. These commands follow the active `/config scope`; session-scoped changes stay in the current process.
 
 ### Codex Providers
 
@@ -638,6 +889,29 @@ Each login uses the official Codex CLI with its own `CODEX_HOME` under `~/.ztc/a
 
 The Accounts panel and `/accounts list` refresh the selected profiles through the official App Server. They show the ChatGPT identity, remaining quota windows, and token activity when OpenAI reports them. A failed quota or usage read is marked stale and retains the last observed value; an expired login needs a new `/accounts login <id>`. A profile whose login cannot be verified does not replace the current active profile. The panel's Refresh button checks again immediately. If an administrator requires keyring-only credentials, Codex may refuse the per-profile file-store setting; that profile will need a supported organization policy before it can be added to this pool.
 
+Account and model switches require an idle session. An active turn or tool must
+finish before the owner accepts a switch. Idle switches retain the conversation
+and tools; the new model can have different context limits. Explicit account
+selection clears that account's cooldown. Selecting machine-default credentials
+removes the pooled selection; an unavailable login is shown as unavailable.
+
+`/usage` queries the literal working directory and reports retained observations
+for its current session, project, and current UTC day. Session and day views
+share that directory scope. Reported tokens and estimates are separate.
+Provider-reported USD includes known zero; missing charges remain unknown.
+These are observed minima, not billing totals: old sessions, retries without
+reports, and evicted receipts can be missing. Each checkpoint retains at most
+512 receipts within 512 KiB, and the project query reads at most 128 recent
+sessions. Repeated checkpoints do not count the same request twice. Historical
+account attribution remains unknown unless explicitly recorded.
+
+Compatible native desktop controls show the configured account and model,
+account health and account-wide quota observations, and these usage scopes.
+The Model button opens the existing model chooser without submitting the draft.
+After changing directories, the usage view stays unknown until observations for
+the new directory load. Published older renderers can lack these controls;
+the terminal commands remain available.
+
 Use `ztc --provider codex_legacy` for the existing direct `chatgpt.com/backend-api/codex` backend backed by `~/.codex/auth.json`. Existing config values with `provider: "codex"` remain supported as a compatibility alias for `codex_legacy`; new configs should use the explicit provider IDs.
 
 Both Codex providers default to `gpt-5.6-sol` when no model is pinned. Users with usable `~/.codex/auth.json` and no configured provider now infer `codex_legacy` instead of the older `codex` alias, so status/config output names the legacy path explicitly.
@@ -666,9 +940,13 @@ Optional App Server config:
 |---------|-------------|
 | `/clear` | Clear message history |
 | `/sessions` | List/manage saved sessions |
+| `/rename <name>` | Set a stable session name; `--clear` returns to automatic labels |
+| `/label [pane <id>] ...` | Show, name, pin, group, or tag a session or pane |
 | `/status` | Show current status |
 | `/context` | Detailed context window usage |
+| `/usage` | Session, working-directory and UTC-day request observations; unknown values stay explicit |
 | `/compact [%]` | Compact conversation (default: 50%) |
+| `/evidence` | Inspect retained source observations, interpretations, corrections and availability |
 | `/retry` | Retry last request |
 
 ### Modes
@@ -685,7 +963,9 @@ Optional App Server config:
 |---------|-------------|
 | `/shell <cmd>` or `!<cmd>` | Run shell command |
 | `/cd <path>` | Change directory |
-| `/clipboard` | Copy conversation |
+| `/clipboard` | Copy conversation (existing simple formats) |
+| `/clipboard diagnostic markdown` | Copy a bounded diagnostic report with credential redaction |
+| `/clipboard diagnostic jsonl` | Copy versioned diagnostic events for analysis |
 
 ### Voice
 | Command | Description |
@@ -719,7 +999,7 @@ Optional App Server config:
 |----------|--------|
 | `Enter` | Fill a partial completion; run an exact command or model, or submit input |
 | `Shift+Enter` | Insert newline |
-| `Ctrl+C` | Exit |
+| `Ctrl+C` | Stop the active run; otherwise clear the draft, or exit when empty |
 | `Ctrl+L` | Clear screen |
 | `Ctrl+R` | Toggle voice dictation |
 | `Ctrl+I` | Paste image from clipboard |
@@ -728,11 +1008,15 @@ Optional App Server config:
 | `Ctrl+G` | Open plan file in editor |
 | `Ctrl+T` | Toggle task list |
 | `Shift+Tab` | Cycle modes |
-| `Tab` | Fill the selected completion without running it; reopen a dismissed menu |
+| `Tab` | Queue a draft after a running turn; otherwise fill completion without running it |
 | `Up/Down` | Move between the lines of a multi-line draft; at the first/last line they select a suggestion or browse command history |
 | `Home` / `End` | Start / end of the caret's line |
 | `Ctrl+Home` / `Ctrl+End` | Start / end of the whole draft |
-| `Esc` | Close completion while keeping the draft |
+| `Esc` | Close the current form, choice or completion; otherwise confirm stopping the active run |
+| `Esc`, then `Esc` within 2 seconds | Stop that same run, preserving partial output and pending queued work |
+| `Option+Up` | Open the Ratatui queue editor; its `Esc` removes only the selected entry and `Enter` saves |
+| `/rewind` | Open the Ratatui history picker to restore a previous prompt explicitly |
+| `Ctrl+B`, then `?` | Open zmux shortcut help (or use the configured prefix) |
 | `Ctrl+A` / `Ctrl+E` | Start / end of the caret's line |
 | `Ctrl+U` | Kill to the start of the caret's line (this is also what macOS sends for Cmd+Backspace) |
 | `Ctrl+W` | Delete word before cursor |
@@ -762,8 +1046,12 @@ Argument syntax appears as one short usage line instead of selectable chips.
 - **search** — Regex code search (ripgrep-style)
 
 ### Shell & Execution
-- **run_command** — Execute shell commands with timeout
+- **run_command** — Execute shell commands with timeout, or use explicit checked pipelines that retain each stage outcome and gate dependent steps. See [checked execution](docs/checked-execution.md).
 - **run_and_monitor** — Long-running command monitoring
+- **verify_artifact** — Run the registered local `json_assertions` checker against an input JSON artifact and assertion configuration, each at most64KiB. Its retained decision covers only configured artifact assertions; original process/source qualification stays unverified and benchmark eligibility stays unknown. Inspect historical inputs and current/stale applicability with `/evidence`.
+- **benchmark_cpu** — Measure the registered integer-sum CPU fixture using captured input/config JSON, a fixed host Node runner, monotonic kernel timing and an independent exact integer checker. Input contains 1–1024 integers of absolute value at most 1,000,000. Configuration is `{schema_version:1,variant:"for_loop"|"array_reduce",iterations:1–2048,warmup:0–4,samples:3|5|7|9}`. Each file is at most 64KiB. Requires local execution and source-read permissions; guarded remote sessions cannot invoke it. Eligibility covers only this fixture and its recorded conditions; original execution qualification remains unverified.
+- **compare_benchmarks** — Compare two original retained `benchmark_cpu` observation IDs. Workload, checker, runner and declared host/runtime/measurement conditions must match; registered programs and source revisions may differ. Missing results, copied output and aliases of one run cannot admit a comparison. Historical timings and deltas remain retained when inputs later become stale. A delta establishes no causal improvement, production/GPU result or plateau.
+- **measurement_report** — Check reported measurement shape, units, ranks, instrumentation and comparability from retained managed-command observations. Source verification and benchmark eligibility remain unknown. Load `invoke_skill(id="measurement-validation")` for the producer format and smoke workflow.
 
 ### Development (LSP)
 - **goto_definition** — Jump to symbol definition
@@ -802,6 +1090,17 @@ User Input → Agent → Claude API → Tool Use? → Execute → Continue
 
 Standard ReAct loop with streaming, automatic retry (429/529/5xx), and configurable max iterations.
 
+Transient endpoint failures retain the current inference and its completed tool
+results. After the initial three attempts, ZTC keeps waiting for recovery until
+you cancel; it does not resubmit the task. Retry waits use jitter and cap at 30
+seconds. The retry fields in `/settings` → Behavior can cap the recovery window, set it to
+`0` for the previous attempt limit, or set Request attempts to `1` to disable
+Agent-level retries and sustained recovery. Backend transport reconnects retain
+their separate policy. Permanent errors and inactivity timeouts still stop the request.
+Partial answer output and dispatched native harness turns are not regenerated.
+The activity line shows when ZTC is waiting for the endpoint; request diagnostics
+include HTTP status and bounded, redacted response details.
+
 ### Native Binaries (Rust)
 - **ztc-computer** — Screen capture (CoreGraphics/X11/Win32), hardware-level input injection (IOHIDPostEvent/CGEvent), process management
 - **ztc-ml** — GPU-accelerated ML inference and training (candle framework)
@@ -986,6 +1285,16 @@ const tools = await buildAgentToolsFromDomainAsync('ca_org');
 
 ## Development
 
+This source checkout reserves ZTC v0.2.0-canary.2. The public npm package and
+its current published version are described in the Quick Start above.
+
+Use Node 20 or 22 for development checks. The tested toolchain is Vitest 4.1.11,
+Vite 6.4.3 and Stryker 9.6.1. After `npm ci`, run `npm run test:toolchain`,
+`npm run test:simulation` and `npm run test:mutation:compat`. The last command
+checks that the installed mutation runner still catches changes in a covered
+simulation module. See [the migration contract](../docs/vitest-migration.md#ztc-terminal-harness-2026-10-02)
+for the qualified versions and scope.
+
 ```bash
 npm run build          # Compile TypeScript + copy assets
 npm run build:rust     # Build native Rust binaries
@@ -1011,6 +1320,16 @@ ztc
 
 The `claude_code` provider shells out to `claude -p` with `CLAUDE_CODE_OAUTH_TOKEN` in the environment. This follows Claude Code's own auth/runtime and usage rules, and Claude Code's default system prompt/runtime behavior is intentionally involved. ZTC's prompt is appended to that runtime for context.
 
+The CLI backend passes explicit model IDs, dated versions, context suffixes and
+deployment names through as selected, after trimming whitespace. The CLI and
+account determine availability, and a rejected selection remains an error.
+The exact legacy `sonnet` and `claude-code-sonnet` choices, or an empty model,
+retain ZTC's `claude-sonnet-4-5` compatibility mapping; `claude-code-opus` and
+`claude-code-haiku` map to `opus` and `haiku`. Status and usage model fields
+describe the requested configuration; they do not attest which model the
+provider actually served. This backend behavior does not change existing
+dated-model migrations when loading or setting persistent configuration.
+
 The first implementation is text-only: ZTC tool definitions are not bridged into Claude Code CLI tool calls. A future MCP bridge can expose ZTC tools to Claude Code through official integration surfaces.
 
 ### Environment Variables
@@ -1048,7 +1367,7 @@ unset preserves normal interactive discovery.
 
 ## License
 
-ZTC 0.2 is distributed under the
+ZTC is distributed under the
 [Zerg Source Available License 1.0](./LICENSE.md). It permits purpose-limited
     evaluation and specified personal, educational, research, nonprofit, and other
     noncommercial use.
@@ -1069,7 +1388,7 @@ the ZTC 0.1.x releases.
 
 ---
 
-Part of the [Zerg](https://github.com/idanbeck/zerg) autonomous AI framework.
+Part of the [Zerg](https://zergai.com/products/ztc) autonomous AI framework.
 
 ## Updating the npm CLI
 
@@ -1087,3 +1406,30 @@ Existing releases need one ordinary npm upgrade before these commands exist.
 
 See [shared updater policy](https://github.com/Epoch-ML/zerg/blob/development/docs/npm-cli-updates.md)
 for installation safety, channel switching, and packaging details.
+
+### Session and pane labels
+
+Automatic agent labels show the project, branch, task, session identifier and
+phase. Shell panes follow terminal titles. A manual `/rename` or `/label pane
+<id> name <name>` stays separate from inference and survives later updates.
+
+Use `/label project Zerg`, `/label task Release`, `/label group Delivery`, and
+`/label pin` to organize the current session. Target a shell with, for example,
+`/label pane 1 group Builds`. `/label unpin` permits closure again. Use
+`/label group --clear` to remove a tag, `/label auto` to return to an inferred
+name, and `/label show` to inspect current choices. Names and tags have a
+64-character limit. `/sessions` lists pinned sessions first and groups labels.
+
+Choices persist through normal save and resume. A later parent-pane label takes
+precedence over an older child-session label during startup. Pane controls require a native
+renderer advertising `pane_labels_v1`; older renderers explain that an update
+is needed, and existing `/rename` remains supported. Desktop protocol sessions
+use ZTC's saved layout; the desktop renderer replays those labels when resumed.
+
+## Incoming requests
+
+Use `/inbox` to review durable requests and receipts. Delivery and acknowledgment
+do not start work. Use `/inbox run <req-ID>` after reviewing a request, then record
+its verified outcome separately. Adapters can deliver envelopes without agent
+startup using `ztc inbox receive --file request.json --json`. See [the intake
+contract](docs/intake.md) for sources, duplicate delivery and navigation.