@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/gui/parity/02-slash-and-surfaces.md

@@ -0,0 +1,110 @@
+# GUI parity matrix — part 2: slash-command families and interactive surfaces
+
+> **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.
+
+Extracted from `apps/workbench/PARITY.md`. Verdict and marker vocabulary is defined in part 1.
+
+## A. Slash-command families (32 rows)
+
+Two rows in the source are **corrupt Markdown**: an unescaped `|` inside the operation cell shifted the columns and destroyed the Gap cell. Both are reconstructed below and marked `[RECONSTRUCTED]`.
+
+| # | Harness capability | Interactive operation | GUI verdict | Gap |
+| -: | --- | --- | --- | --- |
+| 1 | Quit | `/quit` | **Partial** | A browser can close or switch projects, but there is no explicit graceful child-shutdown control. |
+| 2 | Help reference | `/help [query]` | **Partial** | A searchable desktop-app reference opens from the Observatory header and the status bar with no project and no connection: every view, every keybinding from the one typed table the handlers also read, working freedom, vocabulary, and boundaries. Clio Coder's own command list stays terminal. |
+| 3 | Skill selection and invocation | `/skill [name] [task]` | **Partial** | Installed skills are searchable in the atlas, but explicit invocation and the selector workflow are absent. |
+| 4 | Resource library | `/library [kind]` | **Partial** | Read-only library cards are present; install/use flows are absent. |
+| 5 | Saved prompts | `/prompts` | **Partial** | Effective prompt roots are visible, but saved-prompt selection and expansion are absent. |
+| 6 | Extensions | `/extensions` | **Partial** | **deferred-by-design**: Installed extensions are visible; interactive enablement and lifecycle controls are absent. |
+| 7 | Interoperability | `/interop` | **Partial** | Settings names every detected coding agent, its version, its ACP adapter, and how far it is wired. Reviewing and wiring a peer stays an explicit terminal operation. |
+| 8 | Worker result and archive sharing | `/share [runId]`, `/share export \| import` | **Absent** | `[RECONSTRUCTED]` — the source row is corrupt; the Gap cell was consumed by the unescaped pipe in `export \| import`. Reconstructed intent, cross-checked against the `Portable sharing` row in part 1: no archive inspection, export, dry-run import, confirmation, or conflict surface exists, and sharing a worker result is a mutation with no GUI operation. |
+| 9 | Attributed worker run | `/run <agent> <task>` | **Partial** | ACP tools expose live attributed dispatch activity, but the operator cannot directly start an addressable worker run. |
+| 10 | Delegation | `/delegate <agent> <task>` | **Partial** | Delegated tool calls are attributed when Clio Coder creates them; there is no direct operator control. |
+| 11 | Side question | `/btw <question>` | **Absent** | The GUI has no isolated, non-transcript side-question round. |
+| 12 | Oracle advisory | `/oracle <question>` | **Absent** | No read-only record-briefed advisory operation exists. |
+| 13 | Council | `/council <task>` | **Partial** | Runs reconstructs the roster, plan approval, rounds, and synthesis shape from the ledger. Member voices are **host-only-by-design**; starting and sharing a council are absent. |
+| 14 | Agent reference | `/agents` | **Present** | Capability atlas provides the graphical recipe reference. |
+| 15 | Cost record | `/cost` | **Partial** | Exact tokens and historical reported cost exist, but live session cost, budget provenance, and provider-normalized totals are incomplete. |
+| 16 | Context family | `/context view \| compact \| recall \| init \| refresh \| reset` | **Partial** | `[RECONSTRUCTED]` — the source row is corrupt for the same reason. Verified against `src/interactive/slash-commands.ts:1695-1705`, whose `kinds` are `context-view, compact, context-recall, init, context-clear, context-refresh`. Reconstructed gap, consistent with the `Project context` row in part 1 and the `Context meter and overlay` row below: effective context sources and earlier replay are visible; live window pressure, working-set state, compaction, recall, and reset have no GUI surface. |
+| 17 | Fleet | `/fleet` settings and `/fleet run` preview/approval | **Partial** | Global dispatch status exists; fleet plan selection, variable binding, preview, approval, and run are absent. |
+| 18 | Decision ledger | `/decisions` | **Absent** | No typed decision-board projection reaches the GUI. |
+| 19 | Task ledger | `/tasks`, add/hand/done/drop | **Absent** | No user-task board or reviewed task mutations reach the GUI. |
+| 20 | Memory | `/memory [seed]` | **Partial** | Configuration presence is visible, but lesson/bank/activity inspection and seeding are absent. |
+| 21 | Fleet run board and verification | `/view [filter]`, `/view verify <runId>` | **Partial** | Recent durable runs, journals, sealed receipt trust, the fleet-root step index, and on-demand verification are present. The Runs board narrows the fixed eight-run window locally by outcome, agent, node, fleet lineage, receipt state, and prefix text, and its count sentence names the bound; nothing reaches the host and older runs stay outside the window. Terminal `/view` filters over history remain absent. |
+| 22 | Panes and mux | `/panes`, show/open/close | **Absent** | No pane host health, inventory, presets, viewer focus, or close controls exist; status parity is **blocked-on-phase4** because the owning surface has no public typed read command. |
+| 23 | Reasoning level | `/thinking [level]` | **Present** | The Settings instrument edits the safe next-turn thinking level. |
+| 24 | Output verbosity | `/output [verbosity]` | **Absent** | Terminal transcript verbosity is presentation-specific and should not become a dead ACP setting. |
+| 25 | Model picker | `/model [pattern]` | **Partial** | Settings selects configured target/model and shows offline inventory, but the richer recent/favorite/search picker is absent. |
+| 26 | Settings center | `/settings [section]` | **Partial** | Four safe settings plus routing and recovery inventories are graphical; most root setting groups remain read-only or unavailable. |
+| 27 | Resume | `/resume` | **Present** | The project rail lists, searches by visible labels, and resumes Clio Coder sessions with replay. |
+| 28 | New session | `/new` | **Present** | New session creation is explicit and bound to the open project. |
+| 29 | Handoff | `/handoff <goal>` | **Absent** | **deferred-by-design**: There is no extraction round, review editor, or new-session handoff operation. |
+| 30 | Session tree | `/tree` | **Absent** | The GUI replays one active path but cannot inspect or switch branches. |
+| 31 | Fork | `/fork` | **Absent** | **deferred-by-design**: No message picker or branch-from-turn operation crosses ACP. |
+| 32 | Transcript export | `/export [path]` | **Absent** | No HTML transcript preview/export workflow exists. |
+
+### Slash-command drift, verified against `src/interactive/slash-commands.ts` (2026-09-20)
+
+The live registry is 40 commands: `background editor interrupt notifications quit help skill library skills prompts mcp doctor extensions share archive run delegate btw oracle council interop agents cost context fleet decisions tasks memory view panes files thinking model settings resume new handoff tree fork export`.
+
+**Retired since the audit — delete row 24:** `/output` no longer exists. Transcript verbosity moved into the settings schema as `interface.outputDetail` (`compact|standard|detailed`), hot-reloadable, with Alt+O cycling it. The parity verdict text is now wrong in a way that matters: it says the switch "should not become a dead ACP setting", but it is a live settings key today and belongs on the settings write surface, not in this table.
+
+**New since the audit — nine rows to add, all starting at Absent unless noted:**
+
+| Harness capability | Interactive operation | Note for the new GUI |
+| --- | --- | --- |
+| Background work | `/background` | Detach the running turn. High value for a GUI that wants a non-blocking viewport. |
+| External editor | `/editor [text]` | Deliberately out of scope for a browser app — keep Absent with the same reason as the `External editor and inline bash` row. |
+| Steering | `/interrupt <text>` | Mid-turn steering injection. This is the missing half of "the operator can shape a running turn" and should be a first-class GUI composer affordance. |
+| Notifications | `/notifications [dismiss [all]]` | Maps onto a GUI notification tray. |
+| Skills (read) | `/skills` | Now distinct from `/skill`; reads the installed catalog. |
+| MCP | `/mcp [list\|trust\|untrust] [id] [class]` | A trust mutation with a closed vocabulary — a good, bounded first write surface. |
+| Doctor | `/doctor [deep]` | Interactive diagnostic sweep. |
+| Archive | `/archive export\|import <path> [--dry-run] [--force]` | The reviewed transfer flow; `--dry-run` already gives the GUI a preview stage for free. |
+| Files | `/files` | Yazi/pane file picker — **blocked-on-phase4**, same as `/panes`. |
+
+## B. Interactive surfaces and instruments (31 rows)
+
+This is the component-level checklist. Read it as the build list for the chat viewport, the dispatch board, and the evidence surfaces.
+
+| # | Harness capability | TUI or harness surface | GUI verdict | Gap |
+| -: | --- | --- | --- | --- |
+| 1 | Main conversation | Streaming narrative, reasoning, tools, approvals, terminal outcome | **Present** | Conversation and Session Timeline project the same validated ACP evidence record. |
+| 2 | Composer and stop | Multiline editor, submit, cancel | **Present** | The GUI has an isolated request editor, explicit send, and turn cancellation. |
+| 3 | Tool activity | Running/completed/failed tool renderers and disclosure | **Present** | Folded activity groups preserve exact tool state and provenance. |
+| 4 | Permission overlay | Consequential tool preview and explicit decision | **Partial** | Allow once/reject is present; richer policy, mutation diff, escalation provenance, and persistent rules are absent. |
+| 5 | Ask-user interview | Structured options, free text, cancellation | **Partial** | Standard ACP permission is interactive, but the separate `ask_user` question protocol is not projected. |
+| 6 | Session picker | Resume, label, delete, missing working directory recovery | **Present** | GUI sessions support resume/replay, rename, delete, close, and unknown-state disclosure. |
+| 7 | Session tree and fork picker | Branch graph, switch, fork from message | **Absent** | ACP exposes neither branch topology nor switch/fork operations. |
+| 8 | Welcome dashboard | Route, context, shortcuts, recent state | **Partial** | First-run guidance, current route, project atlas, and Observatory exist; command shortcuts and context health are narrower. |
+| 9 | Footer and live status | Phase, route, context pressure, cost, tasks, notifications | **Partial** | Phase, route, autonomy, operation, tokens, and event counts exist; pressure, live cost, tasks, retry, watchdog, and capacity are absent. |
+| 10 | Context meter and overlay | Window pressure, working set, prune/recall, compaction | **Absent** | Earlier replay is not a live context-pressure or working-set instrument. |
+| 11 | Cost overlay | Session/model token and cost accounting | **Partial** | Visible usage, historical usage, and durable per-run and per-phase cost are present; live normalized cost and budget state are absent. |
+| 12 | Dispatch board | Filterable run rows, progress, receipts, steering | **Partial** | ACP fleet activity, installation aggregate, durable run detail, journal, receipt trust, root step index, local filters over the durable window, and a running-only toggle on the live strip exist; steering is absent. |
+| 13 | Run-event journal | Durable per-run NDJSON transcript and follow | **Present** | Runs renders a bounded event spine for the eight newest runs and refreshes while displayed work remains nonterminal. |
+| 14 | Fleet root inspection | Planned step index and terminal run ids | **Present** | Runs indexes recent roots to their planned step order, terminal run ids, attribution, and failure reason, and links steps into the window. |
+| 15 | Council | Roster preview, approval, rounds, member grid, synthesis | **Partial** | Runs groups the ledger into councils and renders the seated grid, each voice's route and rounds, and the synthesis shape. The voices are **host-only-by-design**. |
+| 16 | Compete | Parallel candidates, judge/gate decision, winner, cleanup evidence | **Partial** | Runs renders the sealed gate verdict, the graded candidates, the winner, and the judge's independence. Candidate diffs and the judge's reasoning are host-only. |
+| 17 | Receipt trust and verify | Sealed receipt status and `/view verify` host check | **Partial** | Runs projects sealed receipt trust, per-bundle evidence verdicts, and an on-demand re-check of the sealed bytes, all without native paths. |
+| 18 | Task and decision boards | Inspect and mutate session ledgers | **Absent** | Neither ledger is part of protocol v4. |
+| 19 | Memory overlay | Lessons, task bank, activity, promotion | **Absent** | Memory configuration facts do not expose records or mutations. |
+| 20 | Resource overlays | Agents, skills, prompts, extensions, library | **Partial** | Agents, the full installed skill catalog with its verdict, extensions, and library inventories are present; prompts and reviewed mutations are incomplete. |
+| 21 | Settings overlay | Effective values, sources, timing, routing, auth | **Partial** | Effective inspection and safe settings are strong; most settings, auth, and target authoring are absent. |
+| 22 | Model selector | Search, recent/favorite, capability-aware selection | **Partial** | Configured model selection and offline capability search exist; recent/favorite and endpoint discovery are absent. |
+| 23 | Auth dialog | Runtime credential connection | **Absent** | **deferred-by-design**: No typed credential mutation is exposed to the browser. |
+| 24 | External editor and inline bash | Editor round trip and `!command` | **Absent** | The GUI intentionally does not become a terminal emulator or embedded IDE. |
+| 25 | Notifications and retry | Notices, provider retry, stall and watchdog state | **Partial** | Command errors and operation states are visible; structured retry/watchdog/runtime notices are not public ACP facts. |
+| 26 | Panes and mux inventory | Host detection, health, pane list, focus/open/close | **Absent** | **blocked-on-phase4**: no public fixed JSON read exists and this pane must not change `src/domains/mux` or `src/interactive`. |
+| 27 | Yazi round trip | File picker pane, picked path return, focused context | **Absent** | The new terminal/mux round trip is not an ACP operation and is also **blocked-on-phase4** for GUI parity. |
+| 28 | Toolchain inventory | Pinned versions, license, platform, source, resolution, install state | **Present** | Settings renders the fixed listing with version floors, found versions, licenses, platform support, resolution source, and install state. |
+| 29 | Doctor and recovery | Categorized diagnostic sweep and repair | **Partial** | Per-check identity, section, and verdict sit under the bounded counts; finding detail and confirmed repair remain intentionally absent. |
+| 30 | Usage and routing | Historical Usage, offline models, profiles, agent bindings | **Present** | Project scoping, independent failures, provenance, and missing-store states are explicit. |
+| 31 | Catalog and config | Agent/skill/extension/library/check inventory and effective config | **Present** | Bounded projections and direct paths back to the conversation are present. |
+
+### Rows verified stale against `apps/clio-coder-gui/` (2026-09-20)
+
+- **Row 26/27 (panes, Yazi)** — still correctly `blocked-on-phase4`. `src/cli/panes.ts` has exactly one `--json`, on `panes install`. No typed status read exists. But note the settings schema now carries a full `interface.panes.*` subtree (`enabled`, `notifications`, `layout`, `workers.ratio`, `files.{enabled,mode,profile,followCwd,ratio}`), so the *configuration* half is reachable even while the *runtime status* half is not. Do not conflate them.
+- **Row 12 (dispatch board)** — the new app already serves `/api/fleet/runs`, `/api/fleet/dispatches`, `/api/fleet/receipts/:id`, `/api/fleet/councils`, `/api/fleet/gates`. Steering remains absent, and `/interrupt` (new slash command) is the harness capability that would close it.
+- **Row 17 (receipt trust)** — `POST /api/workspaces/:id/receipts/:runId/verify` exists in the new app.
+- **Row 19 (memory overlay)** — still correct. `src/cli/memory.ts` has zero `--json`; the typed read remains the blocker.
+- **Row 18 (task/decision boards)** — `/decisions` and `/tasks` are live slash commands and `src/cli/tasks.ts` is a registered CLI family, but neither emits JSON. Still correctly Absent, for the same reason.

package/docs/gui/parity/03-domains-and-plan.md

@@ -0,0 +1,69 @@
+# GUI parity matrix — part 3: runtime domain roster and implementation plan
+
+> **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.
+
+## A. Runtime domain roster (18 rows)
+
+One row per directory under `src/domains/`. Verified: all 18 named directories still exist, plus `eval`, `evidence`, `evolution`, `gateway`, `plugins`, `user-tasks` which the audit has no rows for.
+
+| # | Harness domain | Operator-facing responsibility | GUI verdict | Gap |
+| -: | --- | --- | --- | --- |
+| 1 | Config | Layered settings, sources, reload class, safe edits | **Partial** | Effective graph and four safe edits are present; most groups and live reload events are absent. |
+| 2 | Extensions | Package resources and precedence | **Partial** | Inventory is present; lifecycle and runtime activation controls are absent. |
+| 3 | Interop | Compatibility detection and import hints | **Partial** | Path-free detection, ACP adapter state, and standing accept/decline answers reach Settings; wiring a peer and adopting foreign context remain terminal operations. |
+| 4 | Resources | Skills, prompts, library catalogs | **Partial** | The skill catalog crosses whole, with its validity verdict; library inventory is present; prompts and lifecycle operations are incomplete. |
+| 5 | Share | Project/resource archives and worker-result sharing | **Absent** | **deferred-by-design**: No bounded preview or confirmed operation exists. |
+| 6 | Context | Project context, codewiki, working set, recall, compaction inputs | **Partial** | Effective context sources and replay are present; live accounting and mutations are absent. |
+| 7 | Providers | Targets, models, auth, capability and residency | **Partial** | Target probe, model selection, and offline inventory exist; auth, authoring, and live runtime notices are absent. |
+| 8 | Toolchain | Pinned optional external programs | **Partial** | The machine-readable inventory is adapted without native paths; status detail, installation, and Yazi profile reset remain terminal workflows. |
+| 9 | Safety | Autonomy, permissions, loop guard, budgets, protected artifacts | **Partial** | Autonomy, mediated approval, and loop blocks are present; wider policy and budget facts are absent. |
+| 10 | Prompts | Saved prompt discovery and expansion | **Absent** | Effective roots alone do not provide prompt listing or invocation. |
+| 11 | Agents | Recipe discovery and execution identity | **Partial** | Reference inventory and observed attribution exist; direct execution and status are absent. |
+| 12 | Middleware | Hooks, safety registrations, nudges, receipts, watchdog | **Partial** | Effective hook configuration is visible; live failures, receipts, nudges, and watchdog state are absent. |
+| 13 | Session | Lifecycle, replay, branches, task and decision ledgers | **Partial** | Core lifecycle and replay are present; branches and ledgers are absent. |
+| 14 | Observability | Usage, cost, durable trace, run facts | **Present** | Visible tokens, historical usage, trace accounting to the phase, event and process shapes, and stored eval reports all cross through bounded fixed reads. |
+| 15 | Scheduling | Capacity, admission, worker placement | **Partial** | Aggregate admission and heartbeat counts are present; capacity, placement, and controls are absent. |
+| 16 | Mux | Pane host, pane inventory, viewer presets, Yazi bridge | **Absent** | **blocked-on-phase4** until the owning work exposes a fixed typed status read. |
+| 17 | Dispatch | Worker runs, fleets, councils, compete, journals, receipts | **Partial** | Live lifecycle, aggregate status, run journals, receipt trust, fleet-root step indexes, on-demand verification, council topology, sealed gate verdicts, and local narrowing of the durable window exist; steering is absent. |
+| 18 | Lifecycle | Boot, diagnostics, version, upgrade, reset, shutdown | **Partial** | Process state, recovery inspection, and the About version record exist; reviewed mutations are incomplete. |
+
+### Domains with no row (add these)
+
+`src/domains/eval`, `src/domains/evidence`, `src/domains/evolution`, `src/domains/gateway`, `src/domains/memory`, `src/domains/plugins`, `src/domains/user-tasks`. Note the audit's "Resources" row predates the split of `plugins` out of `resources`, which is what the `library` command rewrite rides on.
+
+## B. Verdict summary (as recorded)
+
+| Verdict | Count |
+| --- | --: |
+| Present | 22 |
+| Partial | 61 |
+| Absent | 29 |
+| Total | 112 |
+
+The four tables physically hold 113 rows (32 + 32 + 31 + 18). Treat the summary as approximate and recount after the stale rows above are corrected.
+
+## C. Ordered implementation plan (8 items, verbatim, with a current verdict on each)
+
+1. **Implemented:** bounded fixed-argv fleet-run inspection, recent durable event journals, receipt trust, explicit truncation, manual refresh, and automatic refresh while a displayed run remains active.
+   - *Now:* the shape is right and the new app should keep automatic refresh while displayed work is nonterminal. Its `/api/traces/runs/:runId/live` SSE stream is the better mechanism.
+
+2. **Implemented:** fixed `tools list --json` projection and searchable Toolchain Settings instrument with pinned version, license, platform support, source, found and minimum versions, install state, and no native binary or install paths.
+   - *Now:* the new app went further and added install/remove. The "no native paths" clause is the part worth re-deciding rather than inheriting.
+
+3. Add pane/mux mode, health, inventory, and status only after the phase-4 owner publishes a fixed structured read; retain `blocked-on-phase4` and do not reach into mux state, terminal environment, or process inspection.
+   - *Now:* **still blocked.** Verified: `src/cli/panes.ts` exposes `--json` only on `panes install`.
+
+4. **Implemented:** fleet-root step indexes inside the same fixed run inspection, ordered newest first, bounded to **four roots and twenty-four steps**, linking a step only to a run inside the same window. Receipt verification is done: `fleet verify <runId> --json` re-authenticates the sealed bytes on demand, reached through the host-served-id allowlist. Council topology is done too, and by grouping rather than by a new command: a council owns no durable record, so the same fixed read scans a wider slice of the same ledger and groups rows by their council provenance into **at most four councils of five voices and three rounds each**, carrying the roster, routes, rounds, plan approval, and synthesis shape but never a member's answer. Compete and review gate outcomes are done too, through a separate fixed `fleet decisions --json` read over the sealed decision store: a gate seals an integrity-covered artifact rather than mutating the receipts it grades, and the projection carries the verdict, the graded runs, the winner, and the decider's independence from the route it graded, classifying the stored reason line instead of quoting it.
+   - *Now:* `src/cli/fleet-decisions.ts`, `fleet-verify.ts`, `fleet-inspect.ts` all still exist. **The bounds (4 roots / 24 steps / 4 councils / 5 voices / 3 rounds / 8 runs / 16 phases / 12 bundles) were workbench presentation bounds, not harness limits.** A GUI with real pagination should page rather than truncate, and should say what page it is on instead of saying it truncated.
+
+5. **Partly implemented:** durable trace runs and phases reach the GUI through the fixed `trace inspect --json` read, bounded to **eight runs and sixteen phases**, carrying no request text, description, error prose, or database path; durable evidence bundles reach it through the fixed `evidence inventory --json` read, bounded to **twelve bundles**, carrying provenance, tags, totals, redaction counts, and a per-bundle trust verdict but no task text, working directory, or bundle file name; one bundle opens to its per-run trust axes through the host-served-id allowlist. Still to come: trace event tails and process views, through fixed read commands rather than arbitrary SQL, native paths, or raw payloads. **The tail is queued for the harness owner as a bounded, newest-first per-run event tail inside `trace inspect --json` (at most 32 events with start, end, and type, and either a closed-vocabulary class or a 64-byte sanitized name; row prose and process rows stay host-only).** That same change has to settle the Durable trace row, which calls row tails host-only-by-design while this item says they are still to come. The GUI does not build glue around `trace tail <runId>`, because the fixed-argv rule bars it. Building a bundle is a mutation and belongs with item 6.
+   - *Now:* **superseded.** The new app reads the trace store server-side (`server/services/traces.ts`) and serves full events with `payload_json` and processes with `command`. The internal contradiction the item flags is resolved in the opposite direction from the one it proposed. Keep the rowid-cursor pagination it implies (`TraceEventsQuery`/`TraceEventsPage`/`RowCursor` already exist).
+
+6. **Partly implemented:** every doctor check crosses as its **name, section, and verdict**, so a failing check names its subject instead of adding one to a category tally. Finding detail stays on the host permanently. External coding agent detection reaches Settings through the fixed `interop inspect --json` read: which agents this machine has, the version Clio Coder last recorded for each, whether its ACP adapter can start offline, whether a delegation entry already names it, and whether the operator's standing accept or decline still holds. The read runs no foreign executable and carries no resolved binary or agent home directory. The installed skill catalog crosses whole through the fixed `skills inventory --json` read, which reports every skill rather than only the ones the model may load, says which are which, and carries the loader's own validity verdict from the rule `skills validate` shares with it. This project's verification checks reach the atlas through the fixed `verifiers inspect --json` read: which checks exist, where each was declared, the toolchain it drives, whether verify pins its argv, and whether the project catalog parses at all. A check's exact argument vector is host-only by design, because the schema permits its entries to be absolute paths, so the executable crosses as a toolchain class and the rest crosses as a count. Completed evaluations reach Runs through the fixed `eval inventory --json` read: which reports exist, when each ran, the route and serving configuration it ran under, its pass and token accounting, why its failures failed, what its behavioral judge concluded, and each scenario's trials. A report's runner attachments are the whole session transcript and are host-only by design, so they cross as a count. **Two reports carry the same ordinal exactly when `eval compare` would accept them as a baseline pair, which is the relation the compiled prompt hash establishes without the hash itself crossing.** Still to come: safe ACP settings and operations for target/auth lifecycle, memory review, resource installation, verifier authoring and dry-run, share import/export, doctor repair, and fleet admission, each with preview, confirmation, progress, and recovery.
+   - *Now:* `skills inventory --json` **moved** to `library inventory --json`. Everything else verified present. The "same ordinal = comparable baseline pair" trick is a genuinely good UI idea worth keeping: it lets the evals page group comparable reports without ever showing a hash.
+
+7. Expand sanitized ACP events for context pressure and working-set activity, safety budgets and protected artifacts, provider retry/runtime notices, agent status, cost budgets, config reload, middleware failures, and shutdown phases.
+   - *Now:* still open. See the event-bus artifact for the exact channels and payload types.
+
+8. Add the remaining session-native surfaces: task and decision ledgers, branch tree/fork, side questions, handoff review, saved prompts, and transcript export. **Saved prompts wait on a fixed `prompts inventory --json` read modelled on `skills inventory --json` (name, description, argument hint, scope, source, trusted, unavailable, and diagnostic counts; no bodies, paths, or diagnostic prose), owned by the harness; no Catalog stub that lists prompt roots as present is built before it.** Contextual help is implemented for the desktop app as the searchable reference; Clio Coder's own command reference stays terminal.
+   - *Now:* still open, and the `prompts inventory --json` field list is a ready-to-implement harness ticket. Note the last clause is **stale**: the new app has `/api/docs/tree|page|search` and a docs page, so Clio Coder's reference no longer stays terminal.

package/docs/gui/performance-baseline.md

@@ -0,0 +1,76 @@
+# GUI performance baseline and v0.5.0 regression budgets
+
+> **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.
+
+The tables below are the only measured rendering evidence this repository holds. They
+were recorded against the retired Deno/Preact workbench, not against
+`apps/clio-coder-gui`, so they are a starting budget rather than a current reading.
+
+Conditions: 1600x1100 headless dark, Deno 2.9.5, headless Chrome 151.0.7922.169, 24 CPUs, WSL2 Linux 6.18, 60 Hz headless compositor, machine shared with other test lanes; before runs 2026-08-30 16:11Z prod and 16:14Z dev, after runs 17:28Z-17:30Z.
+
+## 1. Workbench baseline, verbatim
+
+### Production bundle (`dist/`, minified)
+
+Columns: Run | Load | Turn | Duration ms | Tasks >50 ms (during/after stream) | Longest task ms | Frame p95/max ms | Frames >33 ms | Key→input p95 ms | Key→frame p95/max ms | Text→paint p50/p95 ms | DOM nodes | Heap peak MB | Draft kept | Scroll held / jump pill
+
+before-prod | 6.9 | 1 | 4989 | 0 (·/·) | 26.4 | 16.7/16.8 | 0 | 1.9 | 17.1/20.1 | 22.6/34.4 | 863 | 10.4 | yes | yes/no
+before-prod | 6.9 | 2 | 4889 | 0 (·/·) | 21.5 | 16.7/16.8 | 0 | 2 | 17.6/22.9 | 22.3/34 | 1371 | 12.1 | yes | yes/no
+after-prod | 10.3 | 1 | 5360 | 2 (1/1) | 95.2 | 16.8/100.1 | 7 | 2.7 | 18.6/24.1 | 26.9/47.8 | 1221 | 14.4 | yes | yes/yes
+after-prod | 10.3 | 2 | 5194 | 1 (0/1) | 75 | 16.8/50 | 1 | 2.9 | 15.6/17.1 | 25.3/33.4 | 2051 | 29.3 | yes | yes/yes
+after-prod-r2 | 6.0 | 1 | 5122 | 1 (0/1) | 79.4 | 16.7/66.6 | 1 | 2.5 | 16.2/18.3 | 24.7/33 | 1221 | 13.3 | yes | yes/yes
+after-prod-r2 | 6.0 | 2 | 4986 | 1 (0/1) | 55.9 | 16.8/33.4 | 1 | 2.1 | 15.7/16.5 | 26.2/33.1 | 2051 | 20.2 | yes | yes/yes
+after-prod-r3 | 6.0 | 1 | 5089 | 1 (0/1) | 78.9 | 16.8/66.6 | 1 | 2.1 | 15.3/16.6 | 27/33.3 | 1221 | 13.3 | yes | yes/yes
+after-prod-r3 | 6.0 | 2 | 5092 | 0 (0/0) | 49.3 | 16.7/33.4 | 1 | 2.3 | 16.8/20 | 24.5/34.3 | 2051 | 19.4 | yes | yes/yes
+
+### Development bundle (`dist-dev/`, not minified)
+
+Same columns:
+before-dev | 17.7 | 1 | 4989 | 0 (·/·) | 26.6 | 16.8/33.3 | 0 | 2.1 | 16.9/22.1 | 23.3/33.2 | 863 | 10.5 | yes | yes/no
+before-dev | 17.7 | 2 | 5085 | 0 (·/·) | 19 | 16.7/16.8 | 0 | 2.3 | 20.8/23.1 | 22.7/34.6 | 1371 | 14.4 | yes | yes/no
+after-dev | 8.8 | 1 | 5305 | 1 (0/1) | 86.2 | 16.8/66.6 | 4 | 2.7 | 17.7/18.6 | 25.9/36.9 | 1221 | 20.2 | yes | yes/yes
+after-dev | 8.8 | 2 | 5078 | 0 (0/0) | 46.9 | 16.8/33.4 | 1 | 2.3 | 16.3/21.7 | 26.5/32.9 | 2051 | 19.7 | yes | yes/yes
+after-dev-r2 | 6.4 | 1 | 5019 | 1 (0/1) | 68.6 | 16.8/66.7 | 1 | 2.5 | 17/19.2 | 26.6/33.5 | 1221 | 13.6 | yes | yes/yes
+after-dev-r2 | 6.4 | 2 | 4994 | 0 (0/0) | 44.1 | 16.7/33.3 | 0 | 2.2 | 16.6/17 | 26.2/34.7 | 2051 | 19.5 | yes | yes/yes
+
+### Resume of a 64-turn session
+
+Columns: Run | Load | Load ms | DOM nodes | Long tasks | Frame max ms | Heap MB
+before-prod | 6.9 | 191 | 934 | 0 | 16.8 | 5.5
+after-prod | 10.3 | 172 | 683 | 0 | 16.8 | 6.1
+after-prod-r2 | 6.0 | 130 | 683 | 0 | 16.8 | 5.9
+after-prod-r3 | 6.0 | 150 | 683 | 0 | 16.8 | 5.9
+before-dev | 17.7 | 203 | 934 | 0 | 16.8 | 6.1
+after-dev | 8.8 | 141 | 683 | 0 | 16.8 | 6.5
+after-dev-r2 | 6.4 | 119 | 683 | 0 | 16.8 | 6.6
+
+METHODOLOGY, carried over exactly:
+- `before` = plain-text transcript, no Markdown/highlighting/diagrams/follow-latest. `after` = all of those present. The workload fixture differed between them (before at commit 3f6e140d: tool bursts every 64 chunks regardless of Markdown structure, 1,340 text events, ~1,390 messages; after: bursts between Markdown blocks, 1,358 text events, ~1,420 messages) and by nothing else.
+- "During stream" counts long tasks whose `startTime <= lastTextAt`; "after stream" counts those that started later. That split is where diagram layout shows up.
+- Load column is the 1-minute load average at run start. The machine was shared with other test lanes throughout; the 51 ms during-stream task in the load-10.3 run did not reproduce in the two runs that followed it and is reported rather than discarded.
+- The 64-turn resume runs on a fresh server and a fresh home.
+
+FINDINGS worth carrying (they are what the design decisions rest on):
+- Streaming stays clean: in the two quiet after runs (load 6.0) no task over 50 ms started while text was arriving, in either turn.
+- The only remaining long task is Mermaid layout, after the turn. `--keep-trace=1` attributed the first-turn task to a 76 ms microtask checkpoint immediately after the `flowDiagram` and `dagre` chunks compiled. Diagrams therefore wait until the turn settles and render one at a time with a macrotask between them (already ported: `client/render/mermaid.ts` queue, `StreamingContext` in `client/render/Markdown.tsx`). Turn 1 costs 55–79 ms including ~2.5 MB of lazy chunk loading; turn 2 costs 49–56 ms.
+- Input stays responsive: keystroke→`input` p95 is 2–3 ms in every run; keystroke→next frame p95 is 15–19 ms after versus 17–21 ms before. The draft survived every turn.
+- Event→paint grew ~3 ms at p50 (22–23 → 25–27 ms) and stayed 33–35 ms at p95 in the quiet runs; the 47.8 ms p95 is the load-10.3 run.
+- DOM and heap: 1,221 nodes after turn 1 and 2,051 after turn 2, versus 863 and 1,371 for plain text; heap peak 13–20 MB versus 10–12 MB (29.3 MB is the load-10.3 run).
+- Resume got cheaper — 119–172 ms and 683 nodes versus 191–203 ms and 934 — because settled turns render as compact conversation blocks and are memoized.
+
+BUDGETS FOR THE NEW GUI. State them as fixed-before-measurement thresholds; the workload script should exit non-zero when a quiet-machine run (load average below 8.0) breaks one:
+- Zero long tasks over 50 ms starting at or before the last text event, per turn.
+- Frame p95 at or below 16.8 ms; at most 2 frames over 33.4 ms per turn.
+- Keystroke→`input` p95 at or below 5 ms; keystroke→next frame p95 at or below 20 ms.
+- Text→paint p50 at or below 30 ms, p95 at or below 40 ms.
+- DOM nodes after turn 2 at or below 2,400; heap peak at or below 24 MB.
+- `draftPreserved` true, `scrollHold.stayedPut` true, `scrollHold.jumpAffordanceVisible` true, every turn.
+- 64-turn resume at or below 220 ms with at most 800 DOM nodes and zero long tasks.
+- Complementary server-side budget already enforced by `tests/stream-load.test.ts`: over a 1,400-event turn, RSS growth under 128 MiB, heap growth under 64 MiB, event ring under 8 MiB.
+
+NOT MEASURED — keep this list and extend it, do not quietly drop it:
+- Real displays at 120 Hz or 144 Hz, and any GPU-composited path. The harness runs a 60 Hz headless compositor, so the frame figures bound work per frame and say nothing about 120 Hz behaviour. The rAF coalescing buffer is the mechanism that makes a 120 Hz display meaningful (it delivers per real frame, so a 120 Hz monitor gets ~600 commits per turn instead of ~300), but that has not been measured and must not be claimed. Measuring it needs a headed Chrome on a high-refresh display, which is a separate lane.
+- Long code fences that never close during a stream: the tail re-lex grows with the unsettled block, and the workload's fences are short.
+- Diagrams larger than a seven-node flowchart, or more than two per turn.
+- A machine without concurrent load; every run above shared the CPU.
+- Production Clio Coder output. The workload is a fixture whose shape was chosen to be representative, not recorded.

package/docs/gui/settings-write-surface.md

@@ -0,0 +1,267 @@
+# GUI settings write surface
+
+> **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.
+
+## 0. The correction that makes this artifact necessary
+
+The source table in `apps/workbench/HARNESS_COVERAGE.md` has **27 rows, not 29**. More importantly, **every group name in it is a retired v1 key.** `src/core/defaults.ts:490` pins `version: 2`, and `src/core/config.ts` holds `V1_ONLY_ROOTS`, the set of roots that exist only to be migrated away from:
+
+```
+identity, autonomy, runtimePlugins, orchestrator, background, memory, watchdog,
+workers, routing, scope, modelSelector, budget, defaults, theme, terminal,
+skills, library, attribution, delegation, keybindings, compaction, prewarm,
+panes, retry, guardrails
+```
+
+That is 22 of the 27 audited group names. A settings form built from the extracted table would bind to keys the validator rejects.
+
+**Settings v2 has exactly eight roots:** `version`, `targets`, `chat`, `fleet`, `context`, `safety`, `interface`, `integrations`.
+
+Four v1 paths were **retired outright**, not moved (`SETTINGS_V1_RETIRED_PATHS`). Never resurrect them:
+
+| Retired path | Reason (verbatim) |
+| --- | --- |
+| `identity` | it was accepted and ignored; no behavior is lost |
+| `background.thinkingLevel` | proactive memory always resolves thinking off |
+| `theme` | the only registered theme was not read by runtime rendering |
+| `compaction.excludeLastTurns` | only the temporary legacy mask used it; `context.workingSet.protectLastTurns` remains |
+
+## 1. Do not hand-maintain the allowlist — derive it
+
+`src/core/settings-controls.ts` already exports a machine-generated registry over every v2 leaf:
+
+```ts
+export interface SettingControl {
+	path: string;
+	label: string;
+	description: string;
+	help?: string | undefined;
+	choices?: readonly string[] | undefined;
+	kind: "boolean" | "number" | "string" | "list" | "json";
+	optional: boolean;
+	readOnly: boolean;
+}
+export const SETTING_CONTROLS: readonly SettingControl[];
+export function settingControl(path: string): SettingControl | undefined;
+export function applyControlValue(settings: ClioSettings, path: string, text: string): void;
+export function controlInstructions(control: SettingControl): string;
+```
+
+It walks `DEFAULT_SETTINGS` recursively (`collectControlPaths`), treats a set of `STRUCTURED` paths as opaque JSON leaves, excludes `version` and `targets`, and attaches label/description/help from three parallel maps. `applyControlValue` runs the **cross-field** validation the GUI must not reimplement:
+
+- a `*.target` must name an existing `targets[].id`;
+- `chat.target` and `context.memory.target` additionally require an orchestrator-eligible runtime ("Chat and memory need an HTTP/native connection; this connection is for workers only.");
+- changing a `*.target` **nulls the matching `*.model`**;
+- a `*.model` without a `*.target` is rejected;
+- `fleet.default.node` must be `local`, a configured node id, or cleared;
+- every `fleet.profiles` entry must name an existing connection, and every `fleet.agentProfiles` value must name an existing profile;
+- `chat.modelPicker.favorites` must survive `validateSettings` unchanged or it is rejected.
+
+**Build the GUI form from `SETTING_CONTROLS` plus a policy overlay (this document's verdict column). Do not transcribe paths into TypeBox by hand.** A leaf added to `DEFAULT_SETTINGS` then appears in the GUI automatically, and one removed disappears, which is the drift this table exists to prevent.
+
+## 2. Apply timing is already classified — surface it, do not guess it
+
+`src/domains/config/classify.ts` is the authority. `settingsChangeKind(path)` returns `hotReload | nextTurn | restartRequired`, prefix-matched, **defaulting to `restartRequired` for anything unrecognized**. Every control in the GUI must render its timing. The exact sets:
+
+**hotReload** (a running session applies it immediately): `interface.keybindings`, `safety.autonomy`, `chat.modelPicker`, `interface.outputDetail`, `interface.demo`, `interface.smoothStreaming`, `interface.panes.notifications`, `integrations.git.commitAttribution`, `interface.panes.files`, `safety.review`.
+
+**nextTurn** (used by the next relevant request, dispatch, or explicit open): `targets`, `chat`, `fleet.default`, `fleet.profiles`, `fleet.rosters`, `fleet.agentProfiles`, `fleet.adaptiveRouting`, `fleet.nodes`, `fleet.permissions`, `fleet.retry`, `fleet.worktrees`, `fleet.limits`, `fleet.history`, `context`, `safety.limits`, `interface.terminalProgress`, `interface.desktopNotifications`, `integrations.projectResources`, `integrations.externalAgents`, `integrations.library`.
+
+**restartRequired** (takes effect in the next session): `fleet.concurrency`, `interface.mode`, `interface.fullscreenScrollbar`, `interface.panes.enabled`, `integrations.runtimePlugins`.
+
+The operator-facing sentences the TUI uses, from `controlInstructions`, verbatim: `"A running session can apply this immediately."` / `"Used by the next relevant request, dispatch, or explicit open."` / `"Takes effect in the next session."`
+
+## 3. Section and group taxonomy — reuse it, do not invent one
+
+`src/core/settings-navigation.ts` defines the eight sections the TUI and `configure` share. The GUI should use the same labels so the docs, the TUI and the GUI say the same words.
+
+| id | Label | Description | Aliases |
+| --- | --- | --- | --- |
+| `targets` | Connections | Providers, endpoints, credentials, and available models. | connections, connection, auth, target, providers |
+| `chat` | Chat | Chat model, thinking, model favorites, response length, and retries. | orchestrator, models, model, thinking, retry |
+| `fleet` | Fleet | Worker models, profiles, routing, concurrency, retries, and run limits. | workers |
+| `context` | Context & Memory | Context size, compaction, working set, and proactive memory. | compaction, memory |
+| `safety` | Permissions & Limits | Autonomy, approval rules, spending limits, and safety review. | permissions, autonomy, budget, watchdog |
+| `interface` | Appearance | Display, streaming, notifications, panes, and keyboard shortcuts. | appearance, terminal, panes, pane, layout |
+| `integrations` | Integrations | Project skills, external agents, plugins, library, and Git attribution. | skills, skill, extensions, interop |
+| `advanced` | Advanced | Diagnostics, configuration files, and the full settings editor. | all, settings, diagnostics, doctor, diag |
+
+`settingsSectionForPath` routes by root with three deliberate exceptions that put policy together: `safetyNet`, `fleet.permissions.*`, and `integrations.externalAgents.defaults.toolGovernance` all route to **safety**, not to their own root. `settingsGroupForPath` supplies the sub-headings (Model picker, Recovery, Model & responses, Proactive memory, Compaction, Working set, Context limits, Worker approvals, Default model, Profiles, Agent routes, Automatic routing, Placement & capacity, Run history, Execution limits & recovery, Safety review, Spending & tool limits, External agent permissions, Autonomy, Files pane, Panes & layout, Display & keyboard, Resource library, External agents, Skills, plugins & Git).
+
+## 4. What is writable over ACP *today*
+
+`src/engine/acp/server.ts:1297`:
+
+```ts
+const ACP_SAFE_SETTINGS_KEYS = ["chat.target", "chat.model", "chat.thinkingLevel", "safety.autonomy"] as const;
+```
+
+served by `clio-coder/settings/get_safe` and `clio-coder/settings/patch_safe`, and mirrored exactly in `apps/clio-coder-gui/contracts/settings-safe.ts` as `SAFE_SETTINGS_KEYS`. **Anything wider than these four must be written by the GUI's own Hono server through the settings file, not through ACP** — which is legitimate, because the new app's server is a local process with file access, unlike the workbench's browser. That architectural difference is what unlocks the table below.
+
+## 5. THE COVERAGE TABLE — v2 paths, with an explicit GUI verdict
+
+Verdicts: **WRITABLE** (expose an editing control), **READ-ONLY-WITH-PROVENANCE** (show the effective value and where it came from; no control), **HIDDEN** (do not render at all).
+
+### Root: `version` · `targets`
+
+| v2 path | v1 row it replaces | Contains | Verdict | Reason |
+| --- | --- | --- | --- | --- |
+| `version` | `version` — "Hidden. Schema metadata, diagnostics only." | Literal `2`. | **HIDDEN** | Schema metadata. `SETTING_CONTROLS` already filters it out. Surface it only in a diagnostics panel. |
+| `targets[]` | `targets` — "**Partial**. Read/probe/select plus offline model capabilities exist. URLs, secrets, authoring, conversion, and removal need typed host operations." | Array of target descriptors: id, runtime, baseUrl, models, `ollama.numCtx`, `maxConcurrentRequests`, credentials. | **READ-ONLY-WITH-PROVENANCE** for the list; **WRITABLE via dedicated flows only** for lifecycle. | Also excluded from `SETTING_CONTROLS` on purpose: a target is a record with a lifecycle, not a leaf. Drive it through `targets add/use/remove/rename/probe` equivalents (the new app already has `/use`, `/remove`, `/probe`). **Never render a credential field.** |
+
+### Root: `chat` (replaces v1 `orchestrator`, `scope`, `modelSelector`, `defaults.maxTokens`, `prewarm`, `retry`)
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `chat.target` | string, optional | `null` | nextTurn | **WRITABLE** | Already in `ACP_SAFE_SETTINGS_KEYS`. Must be a select over `targets[].id` — free text will be rejected by `applyControlValue`. Changing it nulls `chat.model`; the UI must show that. |
+| `chat.model` | string, optional | `null` | nextTurn | **WRITABLE** | Safe key. Requires `chat.target` first. |
+| `chat.thinkingLevel` | enum `off\|minimal\|low\|medium\|high\|xhigh\|max` | `low` | nextTurn | **WRITABLE** | Safe key. The v1 row said "Target/model/thinking with next-turn timing" — still exactly right. |
+| `chat.modelPicker.cycleSet` | list | `[]` | hotReload | **WRITABLE** | v1 `scope` — "Model-cycle scope; typed setting and model catalog required." The catalog now exists (offline model inventory), so this is buildable: a multi-select over target/model refs. |
+| `chat.modelPicker.favorites` | list | `[]` | hotReload | **WRITABLE** | v1 `modelSelector` — "useful in the graphical picker after safe settings expand." Validated: entries must be `target-id/model-id` from an existing connection. |
+| `chat.modelPicker.recentLimit` | number | `12` | hotReload | **WRITABLE** | Harmless bound. |
+| `chat.maxOutputTokens` | number | `0` | nextTurn | **WRITABLE** | v1 `defaults.maxTokens` — "explain model/context clamps rather than promising the requested number." Keep that instruction: the help text says it is clamped down to each model's max-output cap and remaining window, and `0` means per-model caps only. |
+| `chat.prewarm` | boolean | `false` | nextTurn | **WRITABLE** | v1 `prewarm.enabled` was "None — needs safe setting and reported prewarm/cache outcome." The control is safe on its own; ship it with the honest caveat from the help text (local-native targets and interactive sessions only) and **never infer a cache hit from latency** — that rule from the v1 row still stands. |
+| `chat.retry.enabled` | boolean | `true` | nextTurn | **WRITABLE** | v1 `retry` — "needs retry status events and next-turn setting." The setting half is real today; ship the control, leave the status display blocked on the event work. |
+| `chat.retry.maxRetries` | number | `3` | nextTurn | **WRITABLE** | |
+| `chat.retry.baseDelayMs` | number | `2000` | nextTurn | **WRITABLE** | |
+| `chat.retry.maxDelayMs` | number | `60000` | nextTurn | **WRITABLE** | |
+| `chat.retry.streamStallMs` | number | `180000` | nextTurn | **WRITABLE** | Measured from the last token, not the request, so a slow-but-alive stream is never aborted. Say so in the control. |
+| `chat.retry.firstTokenStallMs` | number | `600000` | nextTurn | **WRITABLE** | Not in `DEFAULT_SETTINGS`' walk path by accident — it is, via `SETTINGS_CENTER_V2_PATH_OVERRIDES`. `0` never aborts a call that has not started streaming. |
+
+### Root: `fleet` (replaces v1 `workers`, `fleet.nodes`, `routing`, `budget.concurrency`, parts of `guardrails`)
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `fleet.default.target` | string, optional | `null` | nextTurn | **WRITABLE** | v1 `workers` — "Defaults, roster, editing, retries, permission escalation, and resilience need safe settings plus typed events." The defaults half is a plain select now. |
+| `fleet.default.model` | string, optional | `null` | nextTurn | **WRITABLE** | |
+| `fleet.default.thinkingLevel` | enum THINKING_LEVELS | `off` | nextTurn | **WRITABLE** | |
+| `fleet.default.node` | string, optional | unset | nextTurn | **WRITABLE** | Must be `local`, a configured node id, or cleared. Render as a select built from `fleet.nodes`. |
+| `fleet.profiles` | json | `{}` | nextTurn | **WRITABLE via a guided editor**, not raw JSON | Each profile must name an existing connection. A GUI has no excuse for a JSON textarea here: build the row editor the TUI's "profile actions" describe. |
+| `fleet.rosters` | json | `{}` | nextTurn | **WRITABLE via a guided editor** | Named teams of worker profiles for council/fleet runs. Same reasoning. |
+| `fleet.agentProfiles` | json | `{}` | nextTurn | **WRITABLE via a guided editor** | Maps native agent names to profile names; a dangling reference is rejected with "Agent X names missing profile Y". A two-column select grid. |
+| `fleet.nodes` | json | `[]` | nextTurn | **WRITABLE with a preflight gate** | v1 `fleet.nodes` — "SSH node identity, capacity, labels, residency; secret/path handling and preflight required." **That caveat stands.** Do not accept a node without running the preflight; do not render any credential field. |
+| `fleet.adaptiveRouting.roles` | list, values `researcher\|verifier\|reviewer\|judge` | `[]` | nextTurn | **WRITABLE** | v1 `routing` — "show shadow vs active decisions only when typed events exist." The activation list is a closed vocabulary and is safe to edit; the *live decision display* stays blocked. Keep the two apart. |
+| `fleet.adaptiveRouting.postures` | list, values `quality\|balanced\|latency\|economy` | `[]` | nextTurn | **WRITABLE** | `manual` is deliberately not an activatable posture. |
+| `fleet.adaptiveRouting.agentRoles` | json (pairs of `{agentId, executionRole}`) | `[]` | nextTurn | **WRITABLE via a pair editor** | Deliberately exact pairs, "because independent agent and role lists would authorize their whole cross-product." Do not render two independent multi-selects. The agentId `auto` is reserved. |
+| `fleet.permissions.mode` | enum `deny\|escalate\|fail` | `deny` | nextTurn | **WRITABLE** | Routes to the **safety** section, not fleet. Each value has operator help text already written. |
+| `fleet.permissions.escalation.timeoutMs` | number | `120000` | nextTurn | **WRITABLE** | Only the `escalate` posture reads it. |
+| `fleet.permissions.escalation.fallback` | enum `deny\|fail` | `deny` | nextTurn | **WRITABLE** | |
+| `fleet.concurrency` | `auto` or positive int | `auto` | **restartRequired** | **WRITABLE** | v1 `budget` concurrency half. Must show "Takes effect in the next session." |
+| `fleet.worktrees.root` | string | `disk` | nextTurn | **WRITABLE** | `disk`, `tmpfs`, `auto`, or an absolute directory. |
+| `fleet.retry.maxRetries` | number | `2` | nextTurn | **WRITABLE** | |
+| `fleet.retry.routeCooldownMs` | number | `15000` | nextTurn | **WRITABLE** | `0` disables the cooldown. |
+| `fleet.retry.breakerThreshold` | number | `1` | nextTurn | **WRITABLE** | Consecutive route failures before work stops going to that route. |
+| `fleet.limits.toolCallsPerRun` | number | `GUARDRAIL_DEFAULTS.workerToolCallCap` (150) | nextTurn | **WRITABLE** | v1 `guardrails` — "Numeric behavioral backstops; safety surface with exact effective source and restart/turn timing." Bounds *admitted* calls, not attempts. |
+| `fleet.limits.internalRunTimeoutMs` | number | `900000` | nextTurn | **WRITABLE** | 15 minutes; covers the wiki documenter and bootstrap scout. |
+| `fleet.history.maxRuns` | number | `1000` | nextTurn | **WRITABLE — with a destructive warning** | Runs leaving the ring also lose their event journal directory. Lowering this deletes journals the GUI is rendering. Confirm it. |
+| `fleet.history.journal` | boolean | `true` | nextTurn | **WRITABLE** | Whether every dispatched run's event tail is written to disk. Turning it off blinds the GUI's own run-journal surface; say so. |
+
+### Root: `context` (replaces v1 `compaction`, `context.workingSet`, `background`, `memory.intervention`)
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `context.toolResultMaxBytes` | number | `65536` | nextTurn | **WRITABLE** | Min 4096. The 192KB per-turn observation pool remains authoritative; three full 64KB results consume it. Show that arithmetic. |
+| `context.workingSet.enabled` | boolean | `true` | nextTurn | **WRITABLE** | v1 `context.workingSet` — "pair controls with prune/recall ledger facts." The control is safe alone; the ledger display is blocked on `context.pruned`/`context.recalled` events. |
+| `context.workingSet.policy` | enum `structural-v1\|age-horizon` | `structural-v1` | nextTurn | **WRITABLE** | |
+| `context.workingSet.target` | number (0..1 exclusive) | `0.6` | nextTurn | **WRITABLE** | Must sit below `context.compaction.threshold`; the GUI should warn if it does not. |
+| `context.workingSet.protectLastTurns` | number ≥ 1 | `6` | nextTurn | **WRITABLE** | |
+| `context.workingSet.minEvictableTokens` | number ≥ 0 | `200` | nextTurn | **WRITABLE** | Break-even is near 50 tokens; 200 is the churn guard. |
+| `context.compaction.auto` | boolean | `true` | nextTurn | **WRITABLE** | v1 `compaction` — "needs pressure and compaction events before a calibrated control." The switch itself is not calibration; ship it, and gate only the *pressure meter* on the events. |
+| `context.compaction.threshold` | number (0..1) | `0.8` | nextTurn | **WRITABLE** | `pressure = estimated tokens ÷ context window`. |
+| `context.compaction.model` | string, optional | unset | nextTurn | **WRITABLE** | Blank uses the orchestrator. |
+| `context.compaction.systemPrompt` | string (path), optional | unset | nextTurn | **READ-ONLY-WITH-PROVENANCE** | It is a filesystem path to a prompt override. A browser form that writes an arbitrary path into the config is the one control in this root worth withholding until there is a file picker bounded to the workspace. |
+| `context.memory.enabled` | boolean | `true` | nextTurn | **WRITABLE** | v1 `memory.intervention` — "pair with observed memory steps, not controls alone." Keep that as a *presentation* requirement (show `memory.stepCompleted` activity next to it), not a reason to withhold. |
+| `context.memory.target` | string, optional | `null` | nextTurn | **WRITABLE** | v1 `background` — "needs safe ACP settings and cost explanation." Requires an orchestrator-eligible runtime. Show the cost note. |
+| `context.memory.model` | string, optional | `null` | nextTurn | **WRITABLE** | Small non-reasoning model, task memory steps only. |
+| `context.memory.cadenceToolCalls` | number | `10` | nextTurn | **WRITABLE** | |
+| `context.memory.trajectorySteps` | number | `8` | nextTurn | **WRITABLE** | |
+| `context.memory.maxOutputTokens` | number | `2000` | nextTurn | **WRITABLE** | |
+| `context.memory.timeoutMs` | number | `60000` | nextTurn | **WRITABLE** | |
+
+### Root: `safety` (replaces v1 `autonomy`, `budget.sessionCeilingUsd`, `watchdog`, parts of `guardrails`)
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `safety.autonomy` | enum `read-only\|suggest\|auto-edit\|full-auto` | `auto-edit` | **hotReload** | **WRITABLE** | Already an ACP safe key. v1 row: "Plain-language default for the next session; bound-session autonomy stays separate." **That separation is mandatory** — the session's bound autonomy and the settings default are two different facts and the GUI must label which it is showing. Per-value help text already exists for all four levels; render it. |
+| `safety.limits.sessionCostUsd` | number | `5` | nextTurn | **WRITABLE** | v1 `budget` — "Needs live cost provenance and restart timing before controls." Restart timing is resolved (nextTurn). Live cost provenance is still missing, so ship the control and say the alert is informational: `budget.alert` never rejects an enqueue in v0.x. |
+| `safety.limits.chatToolCallsPerTurn` | number ≥ 1 | 60 | nextTurn | **WRITABLE** | A backstop against a model spraying calls, not a routine ceiling; a repo-wide audit legitimately runs dozens. The hard interrupt ceiling sits a fixed margin above. |
+| `safety.limits.readBytesPerCall` | number ≥ 1 | 51200 | nextTurn | **WRITABLE** | Clamped up to a 1KB floor at use. |
+| `safety.limits.observationBytesPerTurn` | number ≥ 1 | 196608 | nextTurn | **WRITABLE** | One pool shared by every observation-producing tool in a turn. |
+| `safety.review.enabled` | boolean | `false` | **hotReload** | **WRITABLE** | v1 `watchdog` said: "Harness documentation says ACP runs do not fire it, so a GUI switch would currently be dead." **That verdict is now a live design question, not a fact to inherit.** The registration reads its settings live on every trigger, so it is hot-reloadable — but `src/core/settings-controls.ts` still states "Headless and ACP runs never fire it." **If the new GUI drives turns over ACP, this control IS still dead and must be rendered disabled with that exact explanation, not hidden.** A hidden dead switch is how the operator learns the GUI lies. |
+| `safety.review.target` | string, optional | unset | hotReload | **WRITABLE (disabled with the same ACP caveat)** | Blank reuses the session's active target. |
+| `safety.review.cadenceToolCalls` | number, optional | unset | hotReload | **WRITABLE (same caveat)** | Blank fires at turn end only. |
+| `safetyNet` (virtual row) | — | — | — | **READ-ONLY-WITH-PROVENANCE** | Not a settings key: it is the always-on rails tuned in `.clio-coder/safety.yaml`. `settingsSectionForPath` routes it to safety. Show it as a provenance card pointing at the file; do not offer to edit YAML through a form. |
+
+### Root: `interface` (replaces v1 `terminal`, `theme`, `keybindings`, `panes`)
+
+The v1 table's blanket verdict was **not applicable**: "Progress, transcript verbosity, TUI mode, scrollbar, and stream pacing are terminal presentation. Never mirror dead TUI switches." **That reasoning is sound and mostly still applies, but it is not uniform.** Split it:
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `interface.demo` | boolean | `true` | hotReload | **WRITABLE** | Not terminal presentation. It governs capability suggestions and contextual guidance, which a GUI also wants. |
+| `interface.outputDetail` | enum `compact\|standard\|detailed` | `standard` | hotReload | **WRITABLE** | The v1 table called this dead TUI presentation and the parity matrix retired `/output` for the same reason. **Both are wrong now**: it governs how much reasoning, tool input, and live tool output the transcript shows, which is exactly the GUI's agent-viewport density control. Bind the GUI's own density toggle to it so the TUI and GUI agree. |
+| `interface.smoothStreaming` | enum `off\|auto\|on` | `auto` | hotReload | **HIDDEN** | Grapheme-safe pacing against a TTY with stdout backpressure. Meaningless in a browser. The GUI should own its own render pacing (see the 120Hz goal) and never write this key. |
+| `interface.mode` | enum `regular\|fullscreen` | `regular` | restartRequired | **HIDDEN** | Terminal scrollback vs alternate screen. Genuinely not applicable. |
+| `interface.fullscreenScrollbar` | enum `hidden\|auto\|always` | `auto` | restartRequired | **HIDDEN** | Same. |
+| `interface.terminalProgress` | boolean | `false` | nextTurn | **HIDDEN** | OSC 9;4 taskbar badges. |
+| `interface.desktopNotifications` | boolean | `false` | nextTurn | **READ-ONLY-WITH-PROVENANCE** | The v1 row said "Desktop notifications are GUI-local only." The key controls the *TUI's* OSC 777/OSC 9 notifications on an interactive TTY; the GUI should own its own Notification API preference separately and show this one as the terminal's setting so the two are not confused. |
+| `interface.panes.enabled` | enum `off\|auto` | `off` | restartRequired | **READ-ONLY-WITH-PROVENANCE** | The `embedded` rung is declared and refuses. `blocked-on-phase4` covers the runtime status, not the config — but a GUI offering to change a mux host's activation it cannot observe is worse than showing the value. |
+| `interface.panes.notifications` | enum `failures\|all\|off` | `failures` | hotReload | **READ-ONLY-WITH-PROVENANCE** | Same. |
+| `interface.panes.layout` | enum `off\|workers\|cockpit` | `off` | restartRequired | **READ-ONLY-WITH-PROVENANCE** | Same. |
+| `interface.panes.workers.ratio` | number | `0.34` | restartRequired | **HIDDEN** | Terminal geometry. |
+| `interface.panes.files.enabled` | boolean | `false` | hotReload | **READ-ONLY-WITH-PROVENANCE** | Yazi bridge; `blocked-on-phase4`. |
+| `interface.panes.files.mode` | enum `companion\|chooser` | `companion` | hotReload | **READ-ONLY-WITH-PROVENANCE** | |
+| `interface.panes.files.profile` | enum `managed\|user` | `managed` | hotReload | **READ-ONLY-WITH-PROVENANCE** | |
+| `interface.panes.files.followCwd` | boolean | `true` | hotReload | **READ-ONLY-WITH-PROVENANCE** | |
+| `interface.panes.files.ratio` | number | `0.3` | hotReload | **HIDDEN** | Terminal geometry. |
+| `interface.keybindings` | json (map) | `{}` | hotReload | **HIDDEN for the TUI map; the GUI owns its own registry** | v1 verdict, still exactly right: "Clio Coder TUI bindings are **not applicable**; GUI shortcuts need their own accessible registry." Keep the GUI's shortcuts in GUI-local storage with a visible, searchable, accessible registry. Do not write TUI keys. |
+
+### Root: `integrations` (replaces v1 `skills.trustProjectCompatRoots`, `library`, `attribution.gitCommits`, `delegation`, `runtimePlugins`)
+
+| v2 path | Kind / choices | Default | Timing | Verdict | Reason |
+| --- | --- | --- | --- | --- | --- |
+| `integrations.projectResources.trustProjectImports` | boolean | `false` | nextTurn | **WRITABLE — with an explicit trust warning** | v1 `skills.trustProjectCompatRoots` — "Trust boundary. Needs clear project/user provenance and next-turn timing." Both are now available. Enabling exposes `.claude/skills`, `.codex/skills`, `.github/…` to the model. The control must name the roots it is about to trust and must be per-project-visible, not a silent global. |
+| `integrations.externalAgents.entries` | json (array) | `[]` | nextTurn | **WRITABLE via a guided editor only** | v1 `delegation` — "External ACP agents, timeouts, tool governance, bounded context, labels; security-sensitive Agent setup." Each entry carries `command`, `args[]`, `cwd`, `env.*` — **this is arbitrary process execution defined through a web form.** Never a raw JSON textarea in a browser. Use the guided "External agents" flow for known integrations; for a custom entry, require an explicit confirmation naming the exact argv that will run. |
+| `integrations.externalAgents.defaults.connectTimeoutMs` | number | `DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS` | nextTurn | **WRITABLE** | |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | number | `DEFAULT_DELEGATION_TURN_TIMEOUT_MS` | nextTurn | **WRITABLE** | |
+| `integrations.externalAgents.defaults.permissionTimeoutMs` | number | `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS` | nextTurn | **WRITABLE** | |
+| `integrations.externalAgents.defaults.toolGovernance` | enum `clio-coder-policy\|agent-managed\|deny-all` | `clio-coder-policy` | nextTurn | **WRITABLE** | Routes to **safety**. Per-value help already written for all three. |
+| `integrations.runtimePlugins` | list | `[]` | **restartRequired** | **WRITABLE — with a supply-chain warning** | v1 `runtimePlugins` — "Extensions/runtime setup; restart-required and supply-chain sensitive." Package names loaded at startup. Same class of risk as external agents: name what will load and require confirmation. |
+| `integrations.library.catalog` | string (path), optional | `null` | nextTurn | **READ-ONLY-WITH-PROVENANCE** | An absolute path written through a web form. Blank uses the config-directory catalog, which is the right default. Withhold until there is a bounded picker. |
+| `integrations.library.remote` | string (URL), optional | `null` | nextTurn | **WRITABLE** | v1 `library` — "Catalog/remote/confirmation/sync in the Resource library." Setting it is not enough to sync; the remote must also be confirmed. |
+| `integrations.library.confirmedRemote` | string, optional | `null` | nextTurn | **READ-ONLY — hard** | `SETTING_CONTROLS` marks this the **only** `readOnly: true` control, and `parseControlValue` throws on any attempt: *"This value is recorded by its dedicated confirmation flow; it cannot be edited here."* Confirming a remote by typing it here would be the record confirming itself. Render it as a status line plus a **Confirm remote** action that runs `library remote confirm <url>`. |
+| `integrations.library.sync` | boolean | `false` | nextTurn | **WRITABLE** | Off means `library sync` and `push` refuse before touching the network, whatever the remote says. This is the network kill switch; render it as one. |
+| `integrations.git.commitAttribution` | boolean | `true` | **hotReload** | **WRITABLE** | v1 `attribution.gitCommits` — "Commit evidence policy; safe setting plus commit-provenance output." Role trailers are added only where Clio has trusted evidence; disabling leaves subsequent commit messages byte-for-byte unchanged. |
+
+## 6. Summary of the allowlist this table authorizes
+
+- **WRITABLE:** all of `chat.*` (14), most of `fleet.*` (23, four of them through guided editors and one behind preflight), all of `context.*` except `compaction.systemPrompt` (16), all of `safety.*` (8, three rendered disabled-with-reason if turns run over ACP), two of `interface.*` (`demo`, `outputDetail`), seven of `integrations.*`. **≈70 controls.**
+- **READ-ONLY-WITH-PROVENANCE:** `targets[]` list, `context.compaction.systemPrompt`, `safetyNet`, `interface.desktopNotifications`, the six `interface.panes.*` capability rungs, `integrations.library.catalog`, `integrations.library.confirmedRemote`.
+- **HIDDEN:** `version`, `interface.smoothStreaming`, `interface.mode`, `interface.fullscreenScrollbar`, `interface.terminalProgress`, `interface.panes.*.ratio`, `interface.keybindings`.
+
+Every WRITABLE control goes through `applyControlValue`, which validates the whole proposed configuration, not the single field. Surface `SettingsValidationError.issues` as field-level errors.
+
+## 7. What the app ships (v0.5.0)
+
+`GET /api/workspaces/:id/settings/controls` returns one row per `SETTING_CONTROLS` entry minus the hidden set, each with its section and group from `settings-navigation.ts`, its timing from `settingsChangeKind`, its per-value help, its effective value in the text form `applyControlValue` parses, and the layer that set it. `PATCH` on the same path takes `{path, value, confirmed?}` and runs `updateLayeredSettings(cwd, (s) => applyControlValue(s, path, value))` in the ops lane, so every write is serial, lands in the user layer, and passes the engine's cross-field validation. The response lists every control whose value changed, which is how the page says that changing a connection also cleared its model. The adapter is `apps/clio-coder-gui/server/clio/adapters/settings-controls.ts`; its policy overlay names only the hidden, read-only, noted and confirmed paths. A test asserts the surface equals the registry minus the hidden set.
+
+Four departures from the table above, each deliberate:
+
+1. **Structured collections are read-only for now.** `fleet.profiles`, `fleet.rosters`, `fleet.agentProfiles`, `fleet.nodes`, `fleet.adaptiveRouting.agentRoles` and `integrations.externalAgents.entries` cross as an entry count with the reason that a guided editor does not exist yet. No JSON textarea ships. The guided editors remain open work.
+2. **`safety.review.*` is writable with a caveat, not disabled.** The switch is dead for conversations in this app and live for terminal sessions that share the same file. The row says exactly that. A disabled control would have stopped an operator from configuring the terminal from here for no safety gain.
+3. **A value set by a project, local project or command-line layer is read-only.** The write lands in the user layer, which those layers outrank, and `updateLayeredSettings` refuses such a write anyway. The row names the layer instead of offering an editor that answers 409.
+4. **Origin is the exact leaf's source.** `settingsSourceFor` walks up to parent objects, and a parent recorded as a project source does not set its absent children. Using it marked all of `chat.*` project-owned when one project file set `chat.model`.
+
+Confirmation is enforced by the server, not the page: `fleet.history.maxRuns`, `integrations.projectResources.trustProjectImports` and `integrations.runtimePlugins` answer 422 without `confirmed: true`, and the page shows the named consequence beside the checkbox.
+
+The earlier effective-values list moved to `/settings/effective`. The `Confirm remote` action and the GUI-local notification and shortcut preferences are not part of this change.
+
+## 8. Provider onboarding (v0.5.0)
+
+Targets has an **Add a connection** form. `GET /api/target-runtimes` is an in-process read of `listProviderSupportEntries` with the authentication vocabulary `configure --list` prints (`none`, `login`, `connected`, `credential`, `needs-key`, `key-optional`), a configured-target count, model hints, and `modelRequired` for runtimes whose ids come from a provider catalog. Status crosses; no credential does.
+
+`POST /api/workspaces/:id/targets` admits `{id, runtime, url?, model?, apiKeyEnv?, useForChat?}` and runs `clio-coder configure --id … --runtime …` through the closed command table as a `targets.add` operation. The CLI stays the authority: it greets LM Studio, fingerprints native runtimes, lists the endpoint's models and refuses a catalog runtime without a model. The command table marks this command `explain`, so the runner keeps the first 2 KiB of stderr. A refusal reaches the page as the CLI wrote it, and a save the CLI could not verify says so instead of reading as a clean success. Before this, every failed CLI operation read "exited with exit code 2".
+
+**There is no key field, and the command table has no credential flag.** `--api-key` would put a secret in a process argv. A key is named by environment variable, or stored from a terminal with `clio-coder auth login <runtime>`; the form says which applies for the chosen runtime. The contract rejects an `apiKey` property, a non-http(s)/ws(s) URL, and any value that starts with a dash.
+
+Still terminal-only: OAuth sign-in, stored keys, `convert`, `rename`, capability overrides, fleet profiles and gateway or lifecycle flags.