@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/architecture/safety-model.md

@@ -6,6 +6,16 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 ---
 
+## Process isolation boundary
+
+The policies described here classify and admit tool calls; they are not an OS
+sandbox. Child tools and external agents currently run with the host user's
+filesystem and process access. Environment filtering is a denylist and does not
+guarantee isolation of arbitrary credentials, login-shell exports, or other
+process environments. Use a separately isolated account/container or machine when
+untrusted execution must not access host secrets. Approval and read-only policy
+must not be described as filesystem, PID, or credential isolation.
+
 ## Two axes: autonomy and the safety net
 
 The `safety.autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
@@ -25,17 +35,20 @@ In the current source tree, effective autonomy resolution is strictly centralize
 | `git_destructive` | net block | net block | net block | net block |
 | `unknown` | deny | ask | ask | ask |
 | `read`: a gate declaring `exposure: outward` | allow | ask | ask | allow |
+| `read`: `read`, `ls`, `grep`, or `find` on a path outside the workspace | deny | ask | ask | allow |
 
 - **`read-only`**: Clio inspects and answers. Mutating calls are auto-denied with a rejection telling the model to propose the change instead; approvals are never invoked. Denials render as `[autonomy]` notices.
 - **`suggest`**: every non-read action parks for one-shot approval. The operator drives.
 - **`auto-edit`**: workspace edits and recognized commands run; unrecognized bash asks instead of blocking.
-- **`full-auto`**: bash runs without prompting; the net is the protection, not the prompt. `system_modify` still asks because it reaches outside the workspace; `unknown` still asks because the net cannot reason about calls it cannot classify.
+- **`full-auto`**: unrecognized bash runs without an autonomy prompt; the net is the protection, not the prompt. The net's own confirm rails still ask here: `npm run lint`, `build`, `typecheck`, and `ci` and other repository scripts that are not test runners, authored `ask` rules, and writes the static rail cannot place. `system_modify` still asks because it reaches outside the workspace; `unknown` still asks because the net cannot reason about calls it cannot classify.
 
 The exposure tier is the one row keyed by the call rather than by its action class. A call may declare `exposure: outward` when answering it publishes or sends something the operator cannot quietly take back: filing an issue or a PR, posting a comment, pushing a branch, cutting a release. Today `ask_user` is the only tool that declares one, so a skill marks its own confirmation step outward and `auto-edit` parks that gate for the operator instead of answering it. Acting on the workspace without asking is not the same permission as publishing without asking. `suggest` parks it too, because the dial is ordered and a stricter level must never gate a surface less than the looser one below it. `full-auto` answers outward gates like everything else, `read-only` still answers them because the outward effect being confirmed is denied there anyway, and the tier only ever adds an ask: it never widens a row the action class already denied. The tier is declared, never inferred, because only the caller knows whether the step it is confirming leaves the machine; a value the schema does not recognize reads as `outward` and the call is then rejected, so a misspelled tier costs one prompt rather than silently downgrading the gate.
 
+The search-scope row is the other one keyed by the call. `read`, `ls`, `grep`, and `find` stay read class, and the policy engine resolves the path each one names the way the tool opens it: physically, following a link at any component and stepping `..` up from a link's target. A path that lands outside the workspace, or that cannot be resolved at all, passes the net with `readScope: outside-workspace` on the decision, and the autonomy mapping asks for it at `suggest` and `auto-edit`, runs it at `full-auto`, and denies it at `read-only`, where approvals are never invoked. Headless runs and delegations deny the ask like any other. Zero-access paths are refused first, at every level. A search that starts inside the workspace never follows a linked directory out of it, so only the path argument is judged. Trees Clio itself points the model at stay readable without an ask: installed skills, plugins, and extensions under Clio's config directory, the user skill roots of the agents Clio interoperates with, the offload scratch a truncation notice names, and dispatch receipts. These roots are resolved again at every admission. Admission judges the path the tool opens: it drops a leading `@` and folds Unicode spaces the way the file tools do, ignores a `cwd` argument on the file tools because they resolve against the process cwd, and judges every spelling a read falls back to when the plain one does not exist (curly apostrophe, NFD, the macOS AM/PM space). An operator-owned root also admits a path written under it without `..`, so a skill installed as a link into a dotfiles tree still reads; the Clio-written scratch and receipt roots admit only what physically sits under them.
+
 The `system_modify` confirm is level-invariant, so it is enforced and attributed as a safety-net confirm rail: the overlay, notices, and audit ledger name the net (reason code `system-modify-confirm`, policy source `builtin-classifier`), not the autonomy level. The matrix row above is unchanged in outcome at every level; only `read-only` converts the ask to a denial. `unknown` remains in the autonomy mapping because the registry substitutes a registered tool's base action class after the net evaluates.
 
-The level is persisted as `safety.autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
+The level is persisted as `safety.autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Permissions & Limits section.
 
 ### Consequence tier is presentation, not authority
 
@@ -181,7 +194,7 @@ Safety policy metadata records active rule IDs and hashes so receipts/evidence c
 
 The policy engine tags every bash command as recognized or unrecognized; the autonomy mapping decides what happens next:
 
-1. **Recognized**: a valid `.clio-coder/safety.yaml` command entry, or the narrow built-in no-prompt set such as `pwd`, simple `ls`, `git status`, bounded `git diff/log`, common test/lint/build commands, `pytest`, `cargo test`, `go test`, or `make test`. In addition, compound `&&` chains where every segment is a recognized safe command (up to `CHAIN_MAX_SEGMENTS = 6`) are recognized. Commands wrapped inside `sh -c` are expanded up to depth 3 (`INNER_SHELL_MAX_DEPTH = 3`) and evaluated segment by segment. Recognized commands run without prompting at `auto-edit` and `full-auto`.
+1. **Recognized**: a valid `.clio-coder/safety.yaml` command entry, or the narrow built-in no-prompt set: `pwd`, simple `ls`, `git status`, bounded `git diff/log`, and the repository test runners `npm test`, `pytest`, `python -m pytest`, `python -m unittest`, `cargo test`, `go test`, `ctest`, `make test`, `make check`, `ninja test`, `meson test`, `mvn test`, and `gradle test` (or `./gradlew test`). A test runner is recognized only with bare-word arguments; quoting, substitution, and operators make it unrecognized. Test runners execute repository-authored code, and they run without confirmation at `auto-edit` so a headless run can verify its own work (#377). The same list is the validation vocabulary the finish contract accepts as evidence, and a contract test fails when the two drift. `npm run lint`, `npm run build`, `npm run typecheck`, and `npm run ci` also run repository code but are not test runners, so they ask for one-shot confirmation at every level, `full-auto` included. In addition, compound `&&` chains where every segment is a recognized safe command (up to `CHAIN_MAX_SEGMENTS = 6`) are recognized. Commands wrapped inside `sh -c` are expanded up to depth 3 (`INNER_SHELL_MAX_DEPTH = 3`) and evaluated segment by segment. Recognized commands run without prompting at `auto-edit` and `full-auto`.
 2. **Unrecognized**: anything else. Unrecognized bash asks for one-shot approval at `auto-edit` and runs at `full-auto`; at `suggest` it asks like every mutation, and at `read-only` it is denied.
 
 Shell operators split two ways. Unrecognized sequencing and redirection (`||`, `;`, pipes, redirects, newlines, or `&&` chains with unapproved commands or more than 6 segments) make a command unrecognized: it asks at `auto-edit` and runs at `full-auto`. Command substitution (`$(...)`, backticks) is a net confirm rail at every level, full-auto included, because the net cannot scan what it executes until runtime. The rule pack scans the full command string before either check, so a destructive verb behind an operator is caught regardless of level. Project policy entries reject operator kinds unless the entry sets `shellOperators: allow`.
@@ -292,7 +305,7 @@ Prefer typed tools over Bash:
 - `verify(check="<id>")` runs either a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) or an exact version-1 `.clio-coder/verifiers.yaml` argv vector through bounded execution helpers with no shell; `verify()` lists both sources through one canonical check projection.
 - `verify(check="frontend", path=...)` validates frontend artifacts without granting arbitrary shell access.
 
-A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Creating skills therefore requires authoring outside these protected roots (such as in a staging workspace or package directory) followed by operator installation where needed. Skill installs go through `clio-coder library install`.
+The frontend validator and `verify(check="test")` are in the no-prompt set at `auto-edit`: the validator has a fixed argv shape and the package test script is a test runner. Any other package-script check, such as `lint` or `build`, asks for one-shot confirmation. A project-catalog check whose argv is a recognized test runner, such as `python3 -m pytest -q`, runs at `auto-edit` like the same bash command. Any other project-catalog check does not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Creating skills therefore requires authoring outside these protected roots (such as in a staging workspace or package directory) followed by operator installation where needed. Skill installs go through `clio-coder library install`.
 
 The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
@@ -375,6 +388,7 @@ When executing tasks in headless mode through `clio-coder run`, there is no term
 ### Workers and delegations
 
 - **Workers** inherit the session's autonomy level, capped by dispatch scope admission. A worker ask resolves per `fleet.permissions.mode`: `deny` continues the run with a rejection; `fail` ends it; `escalate` forwards it to the interactive operator (see the escalation section above). All three values are editable in the `/settings` center.
+- **Worker escalation scoping:** Answered permission escalations within a worker run are remembered and keyed by the exact call and permission conditions (`tool`, arguments, asking axis, action class, and policy provenance). Re-issuing an identical call under the same conditions reuses the prior operator decision rather than queuing duplicate permission cards, while any change in command arguments or asking rails requires a fresh decision. Denials are similarly scoped to prevent repetitive cards.
 - **Delegations (ACP)** under `clio-coder-policy` governance evaluate through the same net and autonomy mapping; an ask resolves as a non-stall deny so the external agent never hangs waiting for an operator.
 - **ACP server sessions** (a remote client driving Clio) snapshot the autonomy level at `session/new`, so a mid-session settings change on the host cannot alter an in-flight remote session's admission decisions.
 

package/docs/architecture/trace-store.md

@@ -121,7 +121,7 @@ When resolving the SQLite database path:
 
 ### Unified Web Trace API
 
-The source application in `apps/clio-coder-web/` replaces the separate trace
+The source application in `apps/clio-coder-gui/` replaces the separate trace
 viewer. It binds to `127.0.0.1` and requires the per-launch bearer token. The CLI
 trace commands above continue to work independently of the web process.
 
@@ -148,6 +148,6 @@ rich-content renderer.
 The run page shows the request, phase waterfall, duration, costs, events with
 payloads, gate decisions, processes, and receipt provenance. Unrecorded fields
 remain absent rather than becoming zero. The typed route table and OpenAPI in
-`apps/clio-coder-web/contracts/` define query parameters and response schemas.
+`apps/clio-coder-gui/contracts/` define query parameters and response schemas.
 
 The shared `TraceReader.runsPage({before, limit, filter})` seam owns run-list pagination for the web API. It orders by `started_at DESC, run_id DESC`, returns a bounded page and `nextBefore`, and combines source, status, and search filters with bound SQL parameters. A read-only legacy database derives `source` without a migration. The app validates and encodes the cursor; it does not duplicate pagination SQL.

package/docs/architecture/tui-design.md

@@ -61,7 +61,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../../src/inte
 - Color is used functionally to indicate state. If removing a color does not lose information, the text is colored using `dim`, `muted`, or left unstyled.
 - `warning` amber is reserved for true warnings. Costs and neutral telemetry numbers use `muted`.
 - `accentDeep` is used only in section tags. Metric values (such as TTFT, tokens-per-second, and autonomy status) use `muted`.
-- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting, for workspace-authority and worker-escalation decision frames, or in `STEER` mode. It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region. Outward, safety-net, and system decision frames use `warning`; conversational answers use `accent`.
+- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting, for workspace-authority and worker-escalation decision frames, or during exceptional composer preparation/compacting phases. It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region. Outward, safety-net, and system decision frames use `warning`; conversational answers use `accent`.
 - Per-surface color budgets limit noise: chip strips use at most one non-neutral token per chip, and framed cards use at most one status token alongside neutral colors.
 
 ---
@@ -200,68 +200,22 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
 
 ### 5.1 Welcome Launchpad & Session Header
 
-The header has two shapes and no box. Source: `src/interactive/welcome-dashboard.ts`;
-contracts: `tests/extended/welcome-boot-header.test.ts`.
+The header has two operational modes: a framed launchpad dashboard on fresh start, and a single live session row after prompt admission. Source: `src/interactive/welcome-dashboard.ts`; contracts: `tests/extended/welcome-boot-header.test.ts`.
 
-- **Launchpad (before the first prompt): exactly three rows.** A masthead with
-  identity flush left and workspace flush right separated by a `frame`-token
-  rule, then the route, then one next step.
+- **Launchpad (before the first prompt): framed panel dashboard.** A boxed container (`buildWelcomeDashboardLines`) enclosed by `╭─ Clio Coder v<version> ─╮` and `╰─╯`:
+  - **11 Detail Rows:** Subhead/title ("Built for the code behind science."), model route status (`routeRow`), workspace path, permissions/autonomy (`stats.autonomy`), guidance ("Ask Clio how to use or extend her."), target inventory (`stats.targets`), and fleet recipes inventory (`stats.fleet`).
+  - **Responsive Layout:** Renders wordmark ASCII art on the left at ≥76 columns (`sideBySide`), and rotating hint cards on the right at ≥160 columns (`WELCOME_HINT_MIN_WIDTH`) cycling commands and shortcuts every 15 seconds.
+  - **Action Row:** A horizontal rule (`├─┤`) separates details from the action row (`actionRow`), which prints the next step or work blocker: no route or model (`/model`), route unavailable or degraded (`/settings targets`), malformed handbook (`CLIO-CODER.md malformed · /context to inspect`), uninitialized handbook (`describe a task · /context init to index this repo`), stale handbook (`describe a task · /context refresh to update it`), or default `describe a task · <SubmitKey> to send · / for commands`.
 
-  ```
-  >C_ Clio Coder v0.4.7 ──────────────────── ~/iowarp/clio-coder · main*
-    ✓ dynamo · qwen3.8-27b
-    describe a task · Enter to send · / for commands
-  ```
-
-  Under width pressure the identity drops its version, then its name; the
-  workspace drops its branch, then head-truncates the path keeping the leaf
-  (`…/clio-coder`). The product name outranks the version, and the branch is
-  given up before the path's leaf is obscured.
-
-- **Route row.** `✓ <target> · <model>` healthy, `! …` degraded, `✗ …`
-  unavailable, `◌ …` configured but not yet probed, `not configured` when
-  neither is set. A healthy route prints no probe latency; the glyph carries the
-  verdict and `/doctor` owns the timing. A failing route prints its reason,
-  sanitized to one line. The row reserves room for that reason where it can,
-  shrinking the route text to keep it, and drops it only when the width cannot
-  hold even the floors. The action row still names the route problem either way.
-
-- **Action row: one line, chosen by what actually blocks work.** First match
-  wins: no route (`no route selected · /model`), no model
-  (`no model selected · /model`), route unavailable or degraded
-  (`… · /settings targets`), `CLIO-CODER.md` malformed
-  (`CLIO-CODER.md malformed · /context to inspect`), no handbook
-  (`describe a task · /context init to index this repo`), stale handbook
-  (`describe a task · /context refresh to update it`), otherwise
-  `describe a task · <SubmitKey> to send · / for commands`. Missing project
-  context is guidance, not a blocker; the line still invites work. A *malformed*
-  handbook is pointed at inspection rather than regeneration, since the file
-  needs repair before it needs rebuilding. `<SubmitKey>` comes from the live
-  `tui.input.submit` binding and is omitted when that action is unbound.
+- **Route row.** `✓ <target> · <model>` healthy, `! …` degraded, `✗ …` unavailable, `◌ …` configured but not yet probed, `not configured` when neither is set. Healthy routes omit latency; failing routes display sanitized failure reasons. Under width constraints, route text shrinks before dropping error reasons.
 
 - **Session header (after the first prompt): exactly one row, and live.**
-
   ```
-  >C_ Clio Coder v0.4.7 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
+  >C_ Clio Coder v0.5.0 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
   ```
+  Collapsed via `sessionRow`, this line tracks mid-session model or branch mutations. It preserves identity (`>C_ Clio Coder v<version>`), active route, workspace tail, and git dirty state (`*`), dropping readiness and onboarding hints owned by the footer. Under extreme width pressure, the route is preserved longest, outliving workspace and version labels.
 
-  It follows a mid-session model change rather than freezing at collapse. It
-  carries identity, route and workspace and deliberately drops readiness,
-  latency, project-context state and onboarding text, which the footer and the
-  composer rail own. When the row will not fit, the survival order is the `>C_`
-  wordmark, then the route, then the workspace path, then the branch, then
-  `Clio Coder v<version>`. **The route is the last fact given up**, and it
-  outlives the workspace and the product name; below roughly the width of the
-  wordmark itself the row is the truncated wordmark alone.
-
-- **Transitions.** The first submit collapses the launchpad exactly once, before
-  any handler appends transcript output, on all three submit paths (ordinary
-  submit, admission of a queued boot submission, interrupt-submit). `/new`
-  returns to the launchpad. `/resume`, `/tree`, `/fork` and `/handoff` collapse
-  it after a successful session transition, so a rebuilt transcript is never
-  shown under fresh-start onboarding. Interactive resume starts inside the app
-  with `/resume`; `--continue` and `--session <id>` belong to the headless
-  `clio-coder run` command. Transitions are idempotent.
+- **Transitions.** The first prompt submission collapses the launchpad before transcript appending. `/new` restores the framed launchpad. `/resume`, `/tree`, `/fork`, and `/handoff` collapse it after transition. Interactive resume uses `/resume`; headless runs use `--continue` or `--session <id>`. Transitions are idempotent.
 
 - **No filesystem work on the render path**, in any state, including the first
   frame and render-cache hits. Project-context state comes from the context
@@ -293,27 +247,32 @@ Starting Clio · you can type now
 
 ### 5.2 Composer (ClioEditor)
 
-- **Mode Section Tag**: The top rail features an explicit left section tag indicating prompt semantics:
-  - `MESSAGE` (dim/teal) while idle.
-  - `FOLLOW-UP` (muted) while Clio is actively processing a run.
-  - `STEER` (neon orange) when Enter will actively steer in-flight work.
-  - When the draft scrolls, the active mode folds into the scroll indicator row so the orange warning remains visible.
-- **Top Rail Metadata**: The top rail right displays target/model and thinking level. Narrow labels budget target and model separately, for example `blade… · qwopus3.…dense-q6 · low`, so the gateway does not consume the model family or variant. Thinking levels use a two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
-- **Empty-State Placeholder**: Displays dim prompt `Ask Clio…  / for commands`.
-- **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Ctrl+J newline` (or resolved keybindings).
+- **Clean Normal Rails**: Normal composition keeps both top and bottom rails quiet without duplicate identity or keyboard hints (the footer owns target/model identity, thinking level, and keyboard affordance).
+- **Exceptional State Elevation**: The top rail only renders exceptional admission, safety, or compaction states:
+  - `CONFIRM` (`warning` token, or `CONFIRM · FULL-AUTO` in `editorDanger` token) when an approval prompt owns operator input.
+  - `PREPARING` (`action` token) while Clio prepares turn admission and dispatch.
+  - `COMPACTING` (`action` token) while compacting session context before prompt submission.
+  - `FULL-AUTO` (`editorDanger` token) when the session runs in full-auto autonomy.
+  - When a draft scrolls vertically, the base editor's native scroll indicator (`↑/↓` line counts) is preserved on line 0.
+- **Context-Aware Empty Placeholder**: When the draft is empty, line 1 displays dim placeholder text matching the active state:
+  - Idle / running: `Ask Clio…  / for commands`
+  - Awaiting approval: `A parked call is waiting for your decision`
+  - Preparing turn: `Clio has your prompt and is preparing the turn`
+  - Compacting: `Clio is compacting the session context`
+- **Bottom Rail Affordance**: During normal drafting, the bottom rail remains clean. In `CONFIRM` mode, the bottom rail displays fitted decision keys (`confirmRailHint` via `src/interactive/permission-hint.ts`: `Enter allow`, or `Backspace clear draft to allow` if a draft is present; `Esc deny`; `s stop turn`; `v inspect mutation`; standing approval terms toggle via `?` on the permission card itself).
+- **Rail Dynamics & Safety Accents**: `renderEditorRail` renders subtle pulse animations when Clio is working or in attention phase (unless reduced motion or dumb terminal is detected), and applies fixed bold `editorDanger` endcaps whenever `fullAuto` is active.
 
 ### 5.3 Progressively Disclosed Footer
 
-- **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and duplicate turn receipts):
-  - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful. Long workspace parents and branch decoration yield before current activity; the workspace suffix and live worker count remain visible at narrow widths, including while the main agent is idle.
-  - **Line 2 (Context & Style)**: Context window meter, Output style, and session cost.
-- **Expanded Mode (`Alt+U`)**: Four responsive sections ordered by operational urgency rather than a static telemetry grid:
-  1. `Activity`: Live agent phase, active workers, running tool calls.
-  2. `Context`: Context window gauge, breakdown, token headroom.
-  3. `Session`: Session cost, throughput, total token breakdown, leader key state.
-  4. `Workspace`: CWD, branch, target, git dirty status.
-  Empty rows collapse rather than occupying blank grid space.
-- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Ctrl+G x] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Ctrl+G x] dismiss` → `head · [Ctrl+G x]` → `head` → glyph alone) without clipping the action key.
+Source: `src/interactive/footer/dashboard.ts`, `src/interactive/footer/pages.ts`.
+
+- **Compact Mode (Two-Line Ambient Strip)**:
+  - **Line 1 (Workload & Identity)**: Active phase (`accent` e.g. `Ready`) and worker counts (`agent` e.g. `· 2 active`) · Target/model identity (`fitIdentityLabel`) · Thinking level (`reason`) on the left; Context meter bar (8–14 cells) and token occupancy (`used / contextWindow`) on the right.
+  - **Line 2 (Status & Hints)**: Urgent input prompt (`Ctrl+C again to quit`, `Ctrl+G → choose key`), active notices (`• text`), demo tips, or rotating shortcut hints alternating with workspace path and git branch/dirty (`*`) on the left; Session throughput (`tok/s`) and dashboard toggle shortcut (`Alt+U`) on the right.
+- **Expanded Mode (`Alt+U`)**: Renders across one-quarter of the viewport (minimum 8 rows), keeping the composer anchored below. Repeated presses cycle through three responsive pages (`DASHBOARD_PAGES`) and closed:
+  1. `Activity`: Live agent phase, tool counts, session metrics, active worker cards (route, task, token usage, tool calls, timing, budget, `/view dispatch:<id>`), and finished worker history.
+  2. `Context`: Context meter bar and category occupancy grid (system, tools, files, turns, memory), compaction/cache telemetry, headroom.
+  3. `Status`: Cost & Connections (session cost, MCP servers, plugins, extensions) and Local Machine metrics (CPU, memory, disk I/O sampled on 2s cadence), plus memory bank entries and free tokens.
 
 ### 5.4 State Choreography Table
 
@@ -404,11 +363,7 @@ so partial fences never flicker into incomplete diagrams while streaming.
 
 ### 7.1 Settings Center Architecture
 The `/settings` overlay is a full-screen transactional control center:
-- **Group Structure**: Sections are organized under non-selectable section headers:
-  - `CORE`: Autonomy & Safety (`safety`), Orchestrator (`orchestrator`)
-  - `ROUTING`: Fleet (`fleet`), Targets (`targets`), Models (`models`)
-  - `RUNTIME`: Budget (`budget`), Compaction (`compaction`), Retry (`retry`)
-  - `EXPERIENCE`: Terminal (`terminal`), Advanced (`advanced`)
+- **Shared navigation**: `src/core/settings-navigation.ts` defines Connections, Chat, Fleet, Context & Memory, Permissions & Limits, Appearance, Integrations, and Advanced for both configure and `/settings`. `src/core/settings-controls.ts` supplies the searchable control catalog, validation, descriptions and application timing. Legacy section spellings resolve to the corresponding current section.
 - **Semantic Row Grammar**: Explicit presentation kinds (`setting`, `status`, `action`, `group-header`, `read-only-fact`, `destructive-action`) prevent confusion between focus (teal), health (green/amber/red), modified status (neutral/teal mark), and active operations (scarce orange).
 - **Transactional Edits**: Selecting a row and pressing `Enter` opens a dedicated value picker, input dialog, or checklist rather than immediately toggling values. Edits construct an immutable `SettingsChangePlan` and present explicit destination choices:
   - `Apply this session` (for live-capable settings)
@@ -418,9 +373,14 @@ The `/settings` overlay is a full-screen transactional control center:
   - Destructive actions (target/profile removal) execute preflight analysis showing affected chat, fleet, and memory routes before confirmation.
 - **Fleet Workbench**: Organizes fleet settings with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Profiles render as one-row summaries with `◆ Edit` affordance; pressing `Enter` drills into profile fields (target, model, thinking level, placement) or destructive removal.
 - **Targets Console Table**: Displays configured targets in an operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action/detail drawer (URL, default model, last probe, failure reason). Actions include `Use`, `Connect`, `Probe`, and `Remove`. Active connect/probe operations show the single orange activity indicator.
-- **Scoped Models Checklist**: Settings → `Models` provides a provider-backed checklist subview with target-level and target/model items, checked current selections, `Space` to toggle, and capability details in the inspector. Unresolved model references are preserved under an `Unavailable` group.
+- **Scoped Models Checklist**: Settings → `Chat` → model favorites provides a provider-backed checklist subview with target-level and target/model items, checked current selections, `Space` to toggle, and capability details in the inspector. Unresolved model references are preserved under an `Unavailable` group.
 - **Narrow Terminal Drill-Down Navigation**: Below 72 columns, Settings transitions from a split view to a modal drill-down stack (section list → section rows → detail drawer) with a breadcrumb and `Esc` moving up one level before closing. Includes `/` filtering across label, path, and description, narrowing per keystroke like `/model` and `/resume`. Below 60 columns, side margins are removed for full-width presentation.
 
+Internal warnings and errors use `src/core/diagnostics.ts`. The active terminal
+owner installs a sink that presents them through the notice area instead of raw
+stderr writes over the frame; headless processes retain stderr. This covers Clio’s
+routed diagnostics, not arbitrary third-party code writing directly to the terminal.
+
 ### 7.2 Fleet Runs Board
 
 `/fleet` and `Alt+W` open Fleet Runs; `/settings fleet` opens fleet configuration. The board consumes the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions and evidence readiness. The board owns selection and rendering; council members remain grouped in a council card.
@@ -490,7 +450,7 @@ memory ID, and leave approval to the separate reviewed memory lifecycle.
 
 ## Keyboard engine compatibility
 
-Clio pins pi-tui 0.85.1 with a tracked pnpm patch for one pre-viewport input
+Clio pins pi-tui 0.86.1 with a tracked pnpm patch for one pre-viewport input
 policy, public existing search focus/operations, and semantic Editor/Input
 edits, including atomic Input clear with native undo and kill-ring preservation. Production consumes these only through src/engine. The patch adds no
 renderer, decoder or search implementation. Published dist bundles patched

package/docs/architecture/worker-dispatch-mechanics.md

@@ -129,6 +129,10 @@ stateDiagram-v2
    - The demuxer resolves the parked promise, resuming tool execution.
    - **Timeout Safety:** If no decision arrives within `escalation.timeoutMs` (default `120000` ms), the worker resumes and applies the `escalation.fallback` posture (default `deny`). If running headlessly (no operator attached) or on runtimes that cannot support park loops, the posture collapses to the fallback immediately.
 
+### 4.1 Answered-escalation memory
+
+To prevent a worker process from repeatedly re-prompting the operator with identical approval cards after a decision has already been given, `src/engine/worker-runtime.ts` maintains an in-memory decision cache (`workerPermissionCacheKey`). Answered decisions are keyed by the exact call (`tool` name and arguments) combined with the permission conditions (asking axis, action class, and safety-net policy provenance). When a worker re-issues an identical call under the same conditions, the remembered decision (`approve` or `deny`) is resolved immediately without emitting a duplicate escalation event. Any change in arguments or policy rails requires a new card.
+
 ---
 
 ## 5. Assignment-aware retry and failover
@@ -228,7 +232,7 @@ The current reduced contract suite divides dispatch coverage by ownership:
 | --- | --- |
 | `tests/contracts/dispatch-lifecycle.test.ts` | Attached and detached lifecycle deduplication, durable transitions, terminal finalization, and orphan recovery from durable attempts. |
 | `tests/contracts/dispatch-admission.test.ts` | Typed-scope authority, capability pairing, deterministic capacity admission, conservative slot defaults, and ACP authority boundaries. |
-| `tests/extended/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
+| `tests/extended/dispatch-schema.test.ts` | Capability-shaped model schema, self-contained nested objects on Pi’s Anthropic wire, and hidden-field compatibility. |
 
 Earlier releases carried separate envelope, assignment, detached-assignment,
 and failure-class test files for the detailed retry scenarios. Those files are
@@ -237,6 +241,10 @@ coverage. Retry and failover behavior remains owned by the dispatch source and
 the three maintained contracts above cover only the responsibilities stated in
 this table.
 
+### 5.4 Helper Acceptance and Capture Ceilings
+
+Structured helper results (`src/domains/agents/result-contract.ts`) enforce an aligned acceptance and capture ceiling of 32 KiB (`STRUCTURED_HELPER_RESULT_MAX_BYTES = 32_768`). A worker rejects outputs exceeding 32 KiB during validation, guaranteeing that a worker cannot accept a helper result that exceeds the orchestrator's durable receipt capture allowance.
+
 ## 6. Worker Exit Codes
 
 The child process exits with specific status codes to signal run outcomes to the orchestrator:

package/docs/gui/README.md

@@ -0,0 +1,69 @@
+# GUI reference
+
+Clio Coder ships a graphical application as an early preview. It is a companion to
+the terminal agent, and it does not claim production parity. This page is the
+operator guide for starting it. The recovered design and parity documents that
+back its implementation follow.
+
+## Launching the application
+
+The default build bundles the application. These commands start and manage it.
+
+| Command | What it does |
+| --- | --- |
+| `clio-coder docs [topic]` | Opens the shipped documentation in your browser. A loopback server starts in the background, so the terminal is free, and later calls reuse it. |
+| `clio-coder docs --stop` | Stops that server and removes its record. |
+| `clio-coder docs --foreground` | Serves privately in the terminal until Ctrl+C. It never adopts the background app or the shared server. |
+| `clio-coder gui [--open]` | Serves the whole application in the terminal until Ctrl+C. |
+| `clio-coder gui background install\|status\|start\|open\|stop\|uninstall` | Runs the application as a login service. Linux with a systemd user session only. |
+
+The documentation server binds `127.0.0.1` and requires a private launch token. It
+stops on `--stop` or after 15 minutes without an open page, because an open page
+holds it through its event stream. Its record and log are private files under
+`<state>/gui/`, and `clio-coder docs` refuses to signal a process it cannot show is
+its own server. Where the operating system exposes process start times (Linux)
+that check needs no answer from the server. On macOS and Windows a server that
+does not answer cannot be proven ours, so it is left running and its record is
+cleared. Foreground `docs` and `gui` run on Linux and macOS, and the browser opens
+automatically on those two. On Windows, open the printed link. Background
+installation and the desktop launcher need Linux with systemd.
+
+## Sidebar navigation
+
+The desktop sidebar lists every destination. **Collapse sidebar** at its top, or `Ctrl`
+or `Cmd` plus `\`, shrinks it to an icon rail, and **Expand sidebar** restores it.
+Each icon keeps its name for assistive technology and shows it as a tooltip on hover
+and on keyboard focus, and the active destination stays marked. The choice is
+remembered per browser. The mobile navigation drawer is unchanged, and the command
+palette (`Ctrl` or `Cmd` plus `K`) offers the same toggle.
+
+## Design and parity documents
+
+Working documents for `apps/clio-coder-gui`. Every file here was recovered from the
+retired `apps/workbench` reference application before it was deleted, and re-verified
+against the current `src/` where the original had gone stale.
+
+| Document | What it is |
+| --- | --- |
+| [`parity/01-cli-surface.md`](parity/01-cli-surface.md) | Command-line surface parity, 32 rows |
+| [`parity/02-slash-and-surfaces.md`](parity/02-slash-and-surfaces.md) | Slash-command families and interactive surfaces, 63 rows |
+| [`parity/03-domains-and-plan.md`](parity/03-domains-and-plan.md) | Runtime domain roster and the ordered implementation plan |
+| [`settings-write-surface.md`](settings-write-surface.md) | The settings coverage table, ported to schema v2. Gates what the GUI may write |
+| [`event-bus-coverage.md`](event-bus-coverage.md) | Canonical event families and which cross the ACP boundary |
+| [`workflow-coverage.md`](workflow-coverage.md) | Human workflow coverage, 33 rows |
+| [`cli-surface-routing.md`](cli-surface-routing.md) | Every registered command and where it is routed in the GUI |
+| [`boundary-doctrine.md`](boundary-doctrine.md) | Why the parity verdicts land where they do |
+| [`delivery-order.md`](delivery-order.md) | Delivery sequence and the work that cannot be done inside the GUI |
+| [`performance-baseline.md`](performance-baseline.md) | Measured rendering evidence and the v0.5.0 regression budgets |
+| [`inspector-presentation.md`](inspector-presentation.md) | What the retired inspectors showed and in what order |
+| [`chat-rendering-spec.md`](chat-rendering-spec.md) | The conversation view and inspector blueprint, 17 artifacts with destination paths |
+
+The settings table is the load-bearing one. It records that the workbench's original
+table named 27 v1 keys that schema v2 retired, and that `SETTING_CONTROLS` in
+`src/core/settings-controls.ts` already machine-generates the leaf registry, so the
+GUI derives its form from the schema rather than transcribing paths by hand.
+
+The chat specification is the implementation blueprint for the conversation view.
+It carries the turn-grouping model, the per-tool-kind card taxonomy, diff and
+approval rendering, and the closed label vocabularies the inspectors need, each
+artifact addressed to the file it belongs in.

package/docs/gui/boundary-doctrine.md

@@ -0,0 +1,104 @@
+# GUI boundary doctrine
+
+> **Reference Design & Planning Blueprint**: This document is an architectural reference blueprint recovered from the deleted `apps/workbench` prototype. It specifies design doctrine, target parity, and inspection layouts for the early GUI preview (`apps/clio-coder-gui`), not verified runtime features of the core v0.5.0 terminal engine.
+
+These are the arguments the parity verdicts rest on. The protocol-v4 specifics below are historical; the reasoning is the artifact.
+
+## 1. What the workbench boundary actually was (historical, for calibration)
+
+GUI protocol v4 validated **36 client commands**:
+
+`project.browse`, `project.open`, `project.select`, `project.forget`, `fs.refresh`, `fs.create-file`, `fs.create-folder`, `fs.move`, `fs.delete.prepare`, `fs.delete.confirm`, `session.new`, `session.load`, `session.close`, `session.list`, `session.label`, `session.delete`, `turn.start`, `turn.cancel`, `permission.resolve`, `settings.get`, `settings.patch`, `targets.list`, `targets.probe`, `autonomy.set`, `config.inspect`, `catalog.inspect`, `usage.inspect`, `routing.inspect`, `dispatch.inspect`, `fleet.inspect`, `toolchain.inspect`, `trace.inspect`, `evidence.inspect`, `evidence.read`, `fleet.verify`, `recovery.inspect`.
+
+and **35 server event kinds**:
+
+`connection.ready`, `project.browse.listing`, `project.opened`, `project.forgotten`, `project.snapshot`, `fs.changed`, `fs.delete.challenge`, `clio-coder.state`, `session.list`, `settings.state`, `targets.state`, `targets.probed`, `config.state`, `catalog.state`, `usage.state`, `routing.state`, `dispatch.state`, `fleet.inspection.state`, `toolchain.state`, `trace.state`, `evidence.state`, `evidence.detail.state`, `fleet.verification.state`, `recovery.state`, `turn.started`, `turn.text`, `turn.thought`, `turn.tool`, `turn.loop`, `turn.permission.requested`, `turn.permission.resolved`, `turn.terminal`, `fleet.activity`, `protocol.error`, `command.error`.
+
+The bootstrap carried an optional `appVersion` string bounded to 64 bytes; a host that omitted it still produced a valid bootstrap, and the About record then said the version was not reported. **That pattern — an optional field whose absence is rendered as "not reported" rather than as a blank — is worth copying everywhere.**
+
+The rule, verbatim: *"That closed set is an asset. New harness areas should enter as small typed DTO families, not as a generic 'run CLI' or 'render JSON' escape hatch."* The new app's `contracts/routes.ts` TypeBox table is the same asset in a different shape. Keep it closed.
+
+## 2. The artifact allowlist — the browser may only point at what it was shown
+
+The strongest idea in either document, and the one most worth porting.
+
+**Thirty-four of the thirty-six client commands carried no artifact identity at all**, "which is the property that makes this boundary auditable: a host adapter with fixed argv cannot be steered anywhere by anything a frame says." The two exceptions were `evidence.read` and `fleet.verify`, and they went through one shared allowlist (`apps/workbench/artifact-allowlist.ts`) rather than each inventing a policy.
+
+The rules, verbatim and each load-bearing:
+
+- *"The browser never introduces an identifier. It may only echo one the host itself served, inside the snapshot the host is currently showing."*
+- *"The window is replaced wholesale on each new snapshot rather than accumulated, so an artifact that has aged out stops being referenceable: the browser is asking about something the host no longer claims exists, and being told so is more truthful than a lookup."*
+- *"A reference outside the window is refused rather than searched for, which is why it answers `refused` and not `not-found`."*
+- *"Serving an id a projection could not have produced is treated as a host bug and refused outright, because an allowlist filled from a broken projection is worse than no allowlist at all."*
+- *"The admitted value is the caller's only licence to build argv, and every consumer uses the return rather than its own input."*
+- *"This is deliberately not a capability token, a session, or a cache. It is the smallest thing that makes 'the browser may only point at what it was shown' checkable in one place."*
+
+**The consequence that reads like a bug and is not:** *"A run id printed inside the fleet-root step index is not thereby referenceable: the host serves the run window from the rows of `fleet.inspect`, and a step whose run has aged out of that window is shown but not served. **Being displayed and being served are different things, and the allowlist tracks the second.**"*
+
+### Porting note
+
+The new app is a REST server, so the equivalent is: **a path parameter is admitted only if the server can independently re-derive it from a current projection, and the handler builds its subprocess argv from the re-derived value, never from the raw param.** Refuse with 403-`refused` rather than 404-`not found` when the id is outside the window, because the distinction is information the operator wants. Put the check in one module so no route re-derives its own policy.
+
+## 3. Exclusion is not redaction — "count instead"
+
+Verbatim:
+
+> Some payloads are not redaction decisions but exclusions. A trace event's `payload_json` and a process row's command line have no safe projection at any width: **truncating a command line still leaks the binary and the first argument, and a payload is arbitrary by construction.** So the rule for those is not "project less", it is **"count instead"**. The trace aggregates are computed in SQL precisely so the excluded columns are never loaded on the way to counting them, **which turns the boundary into a property of the query rather than a discipline in the projection.**
+
+And the naming rule:
+
+> The matrix marks this class `host-only-by-design`, separately from `deferred-by-design`, because **"we will not carry this" and "we have not built this yet" should not read the same to whoever picks the work up.**
+
+**STATUS IN THE NEW APP: deliberately reversed for traces.** `apps/clio-coder-gui/contracts/traces.ts` carries `payload_json` and process `command` + `command_digest`. That is legitimate — the workbench shipped a browser talking over a protocol, the new app is a localhost server the operator started against their own machine — but three things from this section still apply:
+
+1. **Keep the vocabulary.** `host-only-by-design` vs `deferred-by-design` is a distinction worth preserving in any new parity doc, whatever the verdicts become.
+2. **Keep "the boundary is a property of the query."** Where a field genuinely must not cross, exclude it in SQL rather than trusting a projection to drop it. That is how it stays excluded when someone adds a new consumer.
+3. **Keep saying so on screen.** The workbench's rule was that the panel names the exclusion "rather than leaving the absence to be inferred." Wherever the new app does still withhold something, name it.
+
+## 4. Redaction is a decision about which field, not which record
+
+Verbatim, on doctor findings:
+
+> A doctor finding is the clearest case: its **detail** is free prose that routinely quotes native paths, endpoint URLs, socket paths, model ids, and session ids, and no version of it can safely cross. Its **name** is a fixed check label plus the subject the check ran against, which is a different kind of fact and is what separates **"one models check failed"** from **"model zbook failed"**. So the detail stays on the host and the name crosses, **subject to a structural shape rule rather than a fixed vocabulary, so that a harness renaming a check costs that check its name and nothing else costs the sweep.**
+
+That last clause is the generalizable engineering lesson: **validate a crossing string by shape, not by enum, when the producer is allowed to evolve.** A closed vocabulary makes a harness rename break the whole surface; a shape rule makes it degrade exactly one row.
+
+## 5. Separate durable stores get separate commands and an explicit `available` flag
+
+Verbatim:
+
+> Durable trace accounting is keyed by the same run ids the run journal already lists, which looks like the fleet-root case, but it is not: **the ledger and the trace database are separate durable stores with separate failure modes, and an installation that never enabled tracing has no trace database at all.** Folding that read into `fleet.inspect` would have made a missing trace file a failure of the run journal. It gets its own command, its own event, and an **explicit `available` flag**, because **"tracing was never on" and "the database holds no runs" are different answers and an operator is entitled to both.**
+
+The new app honours this with `/api/traces/status`. Extend the same treatment to every store the GUI reads: evidence, evals, usage, the decision store. **Three states, always: unavailable / available-and-empty / available-with-rows.** Never collapse the first two into an empty list.
+
+## 6. A new surface finds bugs — that is part of its value
+
+Verbatim, on the evidence inventory:
+
+> What makes it worth having is a field the store held and the reader dropped: **`redactionCount` was written to every bundle, declared on the overview type, and silently discarded by the parser that reads it back.** Adding a GUI surface is a good way to find that, **because a projection has to name every field it forwards.**
+
+Keep the discipline that produced this: an explicit field-by-field projection, never a spread of the upstream object.
+
+## 7. Widen a DTO rather than invent a command — and pay the price on both sides
+
+Verbatim:
+
+> A harness fact that is genuinely part of an existing family widens that family's DTO instead of claiming a new command kind. The fleet-root step index arrived that way: it is the parent of the durable runs `fleet.inspect` already reads, so it rides the same fixed read and the same `fleet.inspection.state` event **rather than paying for a second child process and a second global cache.** Widening a DTO is not free either, and the price is paid where it belongs: **the host projection and the browser validator both grew the new keys as required, so a snapshot from a build on either side of the change is rejected rather than partly believed.**
+
+"Rejected rather than partly believed" is the rule. Make new DTO fields required on both sides in the same change.
+
+## 8. Request isolation — why the GUI stays responsive
+
+Verbatim, and directly relevant to the operator's speed goal:
+
+> Config, catalog, Usage, routing, dispatch, and recovery inspection run through **a separate serialized request lane alongside ACP**: slow inspections cannot block turn cancellation or permission resolution, late results from a previously selected project are discarded, and **each multi-read inspector executes its fixed commands in parallel while failing independently.** Host integration tests cover that isolation.
+
+Three properties to preserve in the new app:
+
+1. **Inspection must never share a lane with turn control.** A hung `doctor` must not delay a cancel or an approval. In the new app that means the inspection routes and the ACP session routes must not contend on one subprocess queue.
+2. **Late results from a superseded selection are discarded, not rendered.** React Query's `cancelRefetch` / per-workspace query keys give this if the keys include the workspace id; assert it in a test.
+3. **Parallel and independently fallible.** A multi-read page renders the reads that succeeded and names the ones that failed, per read. Never fail a whole page because one of four adapters errored.
+
+> Future command adapters should retain the same fixed-argv, bounded-output, typed-projection discipline **and disclose any diagnostic side effect.**
+
+The live example of that last clause: the doctor sweep **may refresh durable fleet eligibility facts**, and the workbench said so on screen. A read that is not purely a read must announce it.