@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/gui/cli-surface-routing.md

@@ -0,0 +1,148 @@
+# CLI surface inventory and GUI routing
+
+> **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 promise this table makes, verbatim: *"Every currently registered user or harness command is accounted for here. 'No core GUI' means the capability is not forgotten; it is routed to a later bounded surface or an upstream interface request."*
+
+Keep that promise. When a command family is added to `src/cli/index.ts`, add a row here.
+
+## THE ORIGINAL TABLE (28 rows, verbatim)
+
+| # | Command family | Subcommands / significant knobs | GUI routing |
+| -: | --- | --- | --- |
+| 1 | Bare interactive | `--api-key`, `--no-context-files`, hidden `--no-skills` / explicit skill paths | The GUI uses ACP instead; project-context and skill policy need typed settings, while **API keys must stay host-side**. |
+| 2 | `acp` | One stdio agent process pinned to a cwd | Core transport; wired. |
+| 3 | `run` | target/model/thinking/autonomy, sampler controls, context/KV controls, JSON modes, steering, resume, agent/profile/runtime/tool profile, capability requirements, skills | Later reproducible Run Lab. Interactive work remains the notebook. |
+| 4 | `configure` | Runtime/URL/model/capability setup and default routing | Setup surface; needs typed secret-safe host operations. |
+| 5 | `targets` | list/probe/add/use/fleet/profile list/set/remove/rename/bind/unbind/bindings, convert, remove, rename | List/probe, next-turn routing, profile inventory, and agent bindings wired; authoring remains absent. |
+| 6 | `models` | List/search models for configured targets | Offline bounded inventory wired; online/global discovery and authoring remain absent. |
+| 7 | `auth` | list/status/login/logout by target/runtime | Setup/security surface; upstream typed operation preferred. |
+| 8 | `config inspect` | Effective customization graph, JSON | Effective Clio Coder provenance map wired. |
+| 9 | `doctor`, `paths` | Diagnose/fix; resolve directories with JSON | Redacted Recovery check wired in Settings; repair remains separate. |
+| 10 | `reset`, `uninstall`, `upgrade` | State/config reset, full removal, binary unlink, upgrade/migrations | Separate destructive/installation surface. |
+| 11 | `context` | status, init, refresh, wiki, reset, index, replay, working-set | Context Observatory; read-only JSON adapters first, mutations after typed progress/events. |
+| 12 | `agents` | User-facing/all recipes, JSON | Read-only catalog wired; addressable execution still needs typed dispatch operations and events. |
+| 13 | `fleet` | list/new/validate/graph/commands init/run/status/drain/resume | Installation-wide read-only status aggregate wired; plans, runs, mutations, and live events remain absent. |
+| 14 | `evidence` | build by run/session/eval, inspect, list | Evidence library after stable machine projection. |
+| 15 | `eval` | validate/run/report/compare/gate | Experiment surface. |
+| 16 | `memory` | list/propose/promote/approve/reject/prune | Memory review inbox. |
+| 17 | `usage report` | repository/window filters, JSON facts and opportunities | Project-filtered 30-day Usage record wired; broader audit and evidence discovery remain absent. |
+| 18 | `trace` | runs/phases/tail/procs/sql/ui | Bounded trace explorer; **never expose arbitrary SQL as the default non-engineer path.** |
+| 19 | `extensions` | list/discover/install/enable/disable/remove, scopes, JSON | Installed inventory wired; reviewed lifecycle mutations remain absent. |
+| 20 | `skills` | list/search/inspect/validate/install/update/sync/eval | Installed inventory wired; deeper inspection and reviewed lifecycle mutations remain absent. |
+| 21 | `library` | list/search/add/use/sync/push/remote confirm | Inventory and the reviewed lifecycle (install, update, enable, disable, remove) are wired for catalog refs. Import, register, pin, drift, sync and push remain terminal operations. |
+| 22 | `verifiers` | discover/author/validate/dry-run/add/edit/rename/remove | Typed discovery is absent; the GUI names this boundary and does not scrape formatted output. |
+| 23 | `docs` | topic server, no-open | The desktop app carries its own searchable reference (views, keys, vocabulary); Clio Coder topic docs stay external. |
+| 24 | `dev components` | list/snapshot/diff | Developer instrument, not core GUI. |
+| 25 | `dev evolve` | manifest init/validate/summarize | Developer instrument. |
+| 26 | `dev share`, `export`, `import` | inspect/export/import portable resources | Separate reviewed transfer surface. |
+| 27 | `version` | Version fact | Shown: the About record and status bar carry the ACP initialize version beside the GUI's own and doctor's. |
+| 28 | `worker` | Internal NDJSON worker server | **Never directly exposed as an operator control.** |
+
+## DRIFT, verified against `src/cli/index.ts` COMMAND_HANDLERS (2026-09-20)
+
+The live registry, in registration order: `acp, auth, config, configure, targets, models, agents, components, evidence, eval, memory, usage, trace, evolve, dev, extensions (alias ext), fleet, library, tasks, mcp, verifiers, gui, docs, share, export, import, context, run, tools, interop, panes, doctor, paths, reset, uninstall, upgrade, version, worker`.
+
+Plus `dev` re-dispatches to `components`, `evolve`, `share`.
+Plus three **retired subcommand tombstones** that are deliberately not dispatchable but stay command-shaped "so top-level value flags cannot consume them and accidentally boot another mode": `context-init`, `context-index`, `context-clear`.
+
+### Removed
+
+| Row | What happened |
+| --- | --- |
+| 20 `skills` | **Gone as a top-level family.** Absorbed into `library`. The reads are now `library skills [--all] [--json]` (discovered runtime skills, including unmanaged local files), `library inventory --json` (the fixed, body-free skill read **explicitly labelled "for GUI hosts"**), and `library validate <package-path\|SKILL.md> [--json]`. |
+
+### Added — six rows the audit has no entry for
+
+| Command family | Subcommands / knobs | Proposed GUI routing |
+| --- | --- | --- |
+| `tools` | list/status/install | **Already partly wired in the new app**: `/api/toolchain/tools`, `/install`, `/remove`, driven through `/api/operations/:id`. (The audit mentions `tools` in the parity matrix but omits it from this inventory.) |
+| `interop` | detect/inspect (`interop inspect --json`), wire a peer | Settings; detection wired, wiring remains an explicit terminal review. (Same omission.) |
+| `panes` | `panes install [--force] [--json]` | Separate toolchain mutation; runtime status still **blocked-on-phase4**. (Same omission.) |
+| `tasks` | the user-task ledger (`src/cli/tasks.ts`, also `/tasks` add/hand/done/drop) | **No `--json` yet.** Route to a task-board surface once a typed read exists; this is the same blocker shape as `memory`. |
+| `mcp` | list/trust/untrust (`/mcp` mirrors it); **7 `--json` call sites** | **Buildable today.** An MCP server panel with a closed-vocabulary trust toggle is one of the safest first write surfaces in the whole app. |
+| `gui` | the GUI's own install/upgrade/uninstall/launch | This is the app's own lifecycle, replacing the workbench's `scripts/gui-lifecycle.ts`. Never expose it from inside the running GUI as anything but a version/About fact. |
+
+### Rewritten — row 21 `library` is now the marketplace
+
+The audit recorded seven subcommands. The live surface (`src/cli/library.ts` HELP, verbatim) is:
+
+```
+One library of packages: plugin, skill, agent, prompt, fleet.
+
+  library list      [--kind <kind>] [--user|--project] [--json]
+  library search    [query] [--kind <kind>] [--json]
+  library recipes   [query] [--kind skill|agent|prompt|fleet]
+                    [--source core|package|user|project|compat] [--all] [--json]
+  library register  <path> [--user|--project] [--force] [--json]
+  library inspect   <path|kind:name|name> [--user|--project] [--json]
+  library install   <path|kind:name|name> [--user|--project] [--force]
+                    [--with-requirements] [--dry-run] [--json]
+  library import    <path|github-tree-url> [--user|--project]
+                    [--format claude|codex] [--dry-run] [--json] [--yes]
+  library update    <kind:name|name> [--user|--project] [--force] [--dry-run] [--json]
+  library enable    <kind:name|name> [--user|--project] [--dry-run] [--json]
+  library disable   <kind:name|name> [--user|--project] [--dry-run] [--json]
+  library remove    <kind:name|name> [--user|--project] [--dry-run] [--json]
+  library pin       <kind:name|name> [--user|--project] [--json]
+  library drift     [kind:name|name] [--user|--project] [--json]
+  library reload    [--json]
+  library skills    [--all] [--json]
+  library inventory --json
+  library validate  <package-path|SKILL.md> [--json]
+  library sync
+  library push
+  library remote confirm <url>
+```
+
+**The semantics that make this directly buildable as a GUI marketplace, verbatim from the HELP:**
+
+> Install and register default to user scope. Other mutations select the project copy when present; an explicit scope selects exactly that copy. List includes both scopes and all installed states. `--from <index.yaml>` selects an index. **Every mutation builds one reviewed plan, rechecks it inside the package lock, refuses to break enabled dependents, and reports per-package outcomes with disk, recipe-admission and host-refresh facts separately; `--dry-run` prints the plan and writes nothing. A CLI never refreshes a running session.**
+>
+> Import reviews a portable, Claude Code or Codex plugin from a path or GitHub tree URL, normalizes supported recipes into a foreign-trust package, and **never activates hooks, MCP, LSP or scripts.**
+>
+> List and search are package-oriented; `--kind` and a query also match the recipes a bundle provides, **returning the owning package as the install target.**
+>
+> Recipes is the versioned, body-free read of actual discovered recipes across core, installed packages and loose user/project files, with owner, origin, availability and invocation; `--all` adds internal diagnostic agents. **Nothing in these reads fetches a remote source or activates a recipe.**
+>
+> Skills lists discovered runtime skills, including unmanaged local files. **Inventory is the fixed, body-free skill read for GUI hosts.**
+>
+> Package evals run with `clio-coder eval run --package <kind:name> --eval <name>`.
+
+**Design consequences for the GUI marketplace page:**
+
+1. **`--dry-run` is the preview stage the coverage table kept demanding.** Every mutation the audit called "needs preview, confirmation, progress, recovery" already has the preview half for free. Build: *plan → show the plan → confirm → apply → show per-package outcomes*. The plan is a first-class object, not a guess.
+2. **The plan distinguishes three outcome facts** — disk, recipe-admission, and host-refresh — and reports them separately. Render all three; collapsing them into "installed ✓" throws away the distinction between "the bytes landed" and "the running session sees it".
+3. **"A CLI never refreshes a running session."** So after a mutation the GUI must explicitly tell the operator whether the open session sees the change, and offer `library reload`. Do not silently imply it took effect.
+4. **Scope is a real axis** (`--user` / `--project`) and list shows both scopes and all installed states. The page needs a scope column, not a scope filter that hides half the truth.
+5. **`library drift`** is the "is my installed copy still what the catalog says" read — a natural per-row badge.
+6. **`library import` from a GitHub tree URL is the one network-reaching read on this surface**, and it never activates hooks, MCP, LSP or scripts. Say so at the point of import; that sentence is the whole trust story.
+7. The network kill switch is the setting `integrations.library.sync` (see the settings artifact), and sync additionally refuses until `integrations.library.confirmedRemote` equals `integrations.library.remote`.
+
+**What the app ships (v0.5.0):**
+
+The Library page opens on a Catalog collection built from `packages` in `GET /api/workspaces/:id/library`, which is `discoverLibrary` joined with every installed copy. The earlier page filtered that list to `kind === "plugin"`, so 34 of the 35 bundled rows never appeared. Both scopes show on every row with the copy's state, and an install is offered only for the scope that has no copy.
+
+Mutations cross through three routes. `POST /api/workspaces/:id/library/plans` stages a plan and writes nothing. `POST …/plans/:planId/apply` commits that exact plan. `DELETE …/plans/:planId` releases it. The adapter `server/clio/adapters/library-lifecycle.ts` calls `planLibraryLifecycle` and `applyLibraryLifecycle` in the single ops lane and holds staged plans in memory for ten minutes, eight at most. A plan applies once; a second apply, an expired plan, or a plan from another workspace answers 404 and the page plans again.
+
+The request body admits only `kind:name` refs. Root resolution tries a local path before the catalog, so the adapter also refuses a ref that names an existing path under the workspace. Paths and GitHub URLs therefore never originate in the browser, and `force` is accepted by the contract but has no control on the page yet.
+
+The outcome view reports disk and recipe admission per package, and always states that open conversations have not reloaded. The web server holds no agent session, so `refresh` is `not-applicable` by construction; the page tells the operator to run `/library reload` or start a new conversation. Consuming `plugins.reloaded` to confirm the reload remains open.
+
+`Dialog` now portals to `document.body`. The shell marks `.workspace` inert while any layer is claimed, which disabled the first dialog ever opened from inside a page.
+
+### Expanded — rows whose subcommand lists grew
+
+| Row | Additions verified in the HELP strings |
+| --- | --- |
+| 13 `fleet` | `inspect --json`, `decisions --json`, `verify <runId> --json`, `view <runId\|fleetRootId>`, `preflight`. Full list: list, new, validate, graph, commands init, run, status, inspect, decisions, view, verify, preflight, drain, resume. |
+| 14 `evidence` | `evidence inventory --json` (plus `src/cli/evidence-detail.ts`). |
+| 15 `eval` | `eval skill <name\|path>`, `--package <path\|kind:name>`, `--suite`, `--task-file`, `--trials/--repeat`, `--format text\|json\|md\|swe-jsonl\|junit`, `compare … [--allow-config-drift]`, `gate --baseline --thresholds`, `inventory --json`. |
+| 18 `trace` | `inspect --json` ("a fixed bounded window with no request text"), `code-steps <rootId> --json` ("deterministic code steps of one fleet root"), `prune [--max-age-days N] [--max-bytes N] [--json]`. |
+| 19 `extensions` | `extensions run <id> <command> [--json] -- [arguments]`. |
+| 22 `verifiers` | `inspect --json`, `baseline <id>`. |
+| 9 `doctor` | nine specialized modules: deep, hpc, naming, panes, slurm, state-size, task-worktrees, toolchain, validation-contract. |
+
+### Row 23 `docs` — decision reversed
+
+The audit routed docs out of the app: "Clio Coder topic docs stay external." The new app implements `/api/docs/tree`, `/api/docs/page`, `/api/docs/search` and ships `client/pages/docs.tsx`. This is a deliberate product change, not drift. The audit's underlying worry — don't turn the main shell into a documentation browser — should be answered with navigation (docs as a peer route, not the default view) rather than by removing the feature.

package/docs/gui/delivery-order.md

@@ -0,0 +1,53 @@
+# Delivery order
+
+> **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/HARNESS_COVERAGE.md`. Items 1-8 are historical record with their constraints intact; items 9 and 10 are live policy for the new app.
+
+## The ten items (verbatim, with current status)
+
+1. **Reported token record — implemented.** Preserve terminal usage in the shared projection, render it per outcome, aggregate only visible terminal records, and **say explicitly that the GUI does not infer price.**
+   - *Live constraint:* "aggregate only visible terminal records" and "does not infer price" both still apply. Five exact fields, Clio's own cost with provenance, no rate-card multiplication.
+
+2. **Effective Clio Coder map — implemented.** The GUI host adapts fixed, read-only `config inspect --json` output into bounded DTOs and visualizes loaded settings, context, prompts, rules, agents, skills, extensions, hooks, trust, precedence, reload timing, and context cost. It answers **"why is Clio Coder behaving this way?"** without asking the operator to read YAML or inspect directories, and without sending raw values to the browser.
+   - *Live:* `/api/workspaces/:id/config-graph`. The question it answers is the right framing for the whole settings area; keep it as the page's stated purpose.
+
+3. **Capability atlas — partially implemented.** Fixed read-only adapters project Agents, installed Skills, installed Extensions, and Library resources into **independently fallible, bounded collections** with search, provenance, trust, precedence, and budget facts. The Verifiers tab deliberately remains an interface-boundary explanation until Clio Coder publishes a typed listing; **the GUI does not scrape its formatted authoring preview.**
+   - *Now:* the Library page opens on a Catalog of every package kind with both scopes per row, and install, update, enable, disable and remove run as plan, review, apply. See `cli-surface-routing.md`, "What the app ships".
+   - *Status:* `verifiers inspect --json` landed, so the Verifiers tab can become real. "Independently fallible" is the property to preserve.
+
+4. **Offline model and worker routing inventory — implemented.** Settings can explicitly inspect bounded model capabilities, token limits, reported residency, worker profiles, and agent bindings. **The three fixed JSON reads run in parallel and fail independently.** The GUI does not probe endpoints, expose provider configuration, or **treat cached/offline facts as health**; authoring and live routing still require typed operations and events.
+   - *Live constraint:* offline residency is not health. Label it as reported/cached, with its age.
+
+5. **Historical evidence and economics — Usage partially implemented.** A fixed project-filtered JSONL adapter powers the 30-day Usage record and discards the upstream report's global or raw rows. Evidence has no JSON listing, eval report lacks typed discovery, and trace runs are global and carry raw requests; **those boundaries remain visible in the GUI rather than being scraped around.** Never pass arbitrary CLI output to the browser.
+   - *Status:* all three named gaps are resolved (`evidence inventory --json`, `eval inventory --json`, `trace inspect --json`). The habit — make a boundary visible rather than scrape around it — is the part to keep.
+
+6. **Installation dispatch status — implemented.** A fixed `fleet status --json` adapter projects global admission, heartbeat counts, the reported retry count, and exact cumulative totals into a **separate installation-scoped view.** Raw durable rows and identities never cross, **the snapshot survives browser reload**, and no run, drain, or resume operation is exposed.
+   - *Live constraint:* installation-scoped facts belong in their own view, not mixed into a project view. "Survives browser reload" is a real requirement for a GUI that wants to feel instant.
+
+7. **Installation recovery check — implemented.** Settings can manually run the fixed machine-readable doctor and path commands. The host projects only severity counts, fixed categories, validated runtime versions, root-resolution count, timestamp, and whether the selected project supplied context. Raw findings and native identities stay host-side. **The GUI passes no `--fix` flag and exposes no repair control; it states that doctor may refresh durable fleet eligibility.**
+   - *Live constraint:* the side-effect disclosure. Per-check name/section/verdict now crosses (parity item 6), so the counts-only limit is superseded; the `--fix` abstention and the disclosure are not.
+
+8. **Expand the ACP event extension upstream. Dispatch lifecycle and agent attribution implemented.** The `clio-coder/event` allowlist carries the five dispatch lifecycle kinds alongside `safety.loopBlocked`, and `session/update` carries a `clio-coder/agent` attribution **additively** in `_meta`. **The remaining priorities are context activity/warning/pruned/recalled, tool budget, safety block, agent status, runtime notice, budget alert, and config-reload classification.** Version and sanitize each DTO; **do not expose raw `unknown` worker events or full settings snapshots.**
+   - *Status:* allowlist is 7 kinds now (`accountability.evidenceReady` joined). The nine remaining priorities are unchanged and each has a typed payload waiting — see the event-bus artifact. The two "do not" clauses map to concrete hazards: `DispatchProgressPayload.event` is typed `unknown`, and `ConfigChangePayload.settings` is the whole credential-bearing snapshot.
+
+9. **Expand safe settings upstream.** Add typed get/patch groups with **allowed values, effective source, apply timing, capability flags, and secret redaction. Build graphical forms only after each group is real.**
+   - *Live and now largely satisfiable:* `SETTING_CONTROLS` supplies allowed values (`choices`), kind, and optionality; `settingsChangeKind()` supplies apply timing; `config inspect --json` supplies effective source. What remains genuinely missing is **capability flags** (is this control dead in an ACP session? — the `safety.review.*` case) and **secret redaction** for `targets[]`. Ship those two before the settings page claims completeness.
+
+10. **Consequential operations.** Target authoring/auth, fleet run/drain/resume, memory approval, resource installation, verifier authoring, share import, doctor fix, and reset require **preview, scope, confirmation, progress, terminal result, and recovery semantics** before they enter the GUI.
+   - *Live policy, and the single most quotable line in either document.* Treat those six stages as the acceptance checklist for every mutation the MVP ships. Note that `library`'s `--dry-run` plan already supplies preview + scope, and `/api/operations/:id` + `/cancel` already supplies progress + terminal result, so the pattern is mostly built — it needs applying uniformly.
+
+## Coordination needed outside the GUI (verbatim)
+
+> Two workstreams cannot be completed honestly inside `apps/workbench` alone:
+>
+> 1. A harness owner must continue extending the opt-in ACP event surface. **The dispatch lifecycle has landed; context, safety, agent status, runtime notice, budget, and config-reload facts have not.**
+> 2. A harness owner must expand the safe settings/operation extensions for config groups and consequential commands; **the renderer must never receive credentials, raw environment values, arbitrary native paths, or unvalidated bus payloads.**
+
+Both still stand. Item 1 is unchanged. Item 2 changes shape for the new app: the *server* may legitimately touch settings files directly, so the blocker is smaller than it was — but the four things the renderer must never receive are unchanged, and `integrations.externalAgents.entries[].env.*` plus `targets[]` credentials are exactly where that rule bites.
+
+## The framing to carry forward
+
+> Until those boundaries exist, the GUI can continue making substantial progress through public machine-readable interfaces.
+
+That sentence is why both documents were worth the effort: they are an inventory of what can be built honestly *today*, separated from what needs someone else first. Any successor document should keep that separation as its organizing principle.

package/docs/gui/event-bus-coverage.md

@@ -0,0 +1,103 @@
+# Canonical event coverage
+
+> **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.
+
+## Framing (from the source, verbatim)
+
+> The event bus is grouped below so new upstream work can expose a small, sanitized projection rather than dumping raw bus payloads across ACP.
+
+The audit's architectural finding, also verbatim:
+
+> The in-process harness bus has **41 canonical channels**, including dispatch, context, capacity, cost, safety, config, compaction, middleware, status, and shutdown facts. **Thirty-five of those channels are not public ACP events today.**
+
+**Verified 2026-09-20: the bus now has 47 channels** (`BusChannels` in `src/core/bus-events.ts`), and the ACP forwardable allowlist has **11 kinds**, not 6 and no longer 7. So the correct sentence today is: *47 canonical channels, 36 of which are not public ACP events.*
+
+## The ACP forwardable allowlist (authoritative, `ACP_FORWARDABLE_EVENT_KINDS` in `src/engine/acp/server.ts`)
+
+```ts
+const ACP_FORWARDABLE_EVENT_KINDS = [
+	"safety.loopBlocked",
+	"dispatch.enqueued",
+	"dispatch.started",
+	"dispatch.progress",
+	"dispatch.completed",
+	"dispatch.failed",
+	"accountability.evidenceReady",
+	"compaction.end",
+	"context.warning",
+	"safety.toolBudgetExceeded",
+	"provider.health",
+] as const;
+```
+
+The mechanism, verbatim from the source comment: *"Nothing outside this list is forwardable: the list is the allowlist, and a client's requested kinds are intersected with it rather than trusted."* A client requests kinds at `initialize`; `ACP_MAX_REQUESTED_EVENT_KINDS = 16` and an over-long list **refuses the whole opt-in**. Eleven of sixteen are now spent, so the next addition is close to the ceiling. Every kind is the literal `BusChannels` value of the channel it forwards; a kind is never renamed on the way out, so a captured frame names its producer and a client's kind list cannot drift into a second vocabulary.
+
+Dispatch frames are bound to the **session**, not to a turn, because a detached run settles after the turn that started it returns. `safety.loopBlocked` and `safety.toolBudgetExceeded` are the two that ARE turn-bound, because the budgets they name are per-turn and mean nothing outside one.
+
+The four newest kinds close three parity rows. `compaction.end` (`{trigger}`) and `context.warning` (`{warning: string|null}`, transitions only, so the `null` is the clearing edge and crosses as itself) feed the context meter. `safety.toolBudgetExceeded` (`{tool, callsThisTurn, softBudget, hardCeiling, interrupted}`, `terminal` exactly when `interrupted`) feeds the footer status. `provider.health` (`{targetId, status, available, latencyMs}`) closes the retry-visibility row; `lastError` is provider prose that quotes URLs and response bodies and stays behind, exactly as `dispatch.failed`'s `outcomeDetail` does.
+
+The GUI maps all four to its own `health.*` deltas and retains them in a separate 32-entry `health` strip rather than in `fleet`: they describe this conversation, not a dispatched run, and a board that mixed them would have to filter its own feed to draw either (`apps/clio-coder-gui/contracts/fleet-events.ts`). Its reader now **logs and drops** a `clio-coder/event` kind it does not recognize, and the supervisor does the same for an unrecognized `sessionUpdate` kind. A MALFORMED frame of a kind either one does claim to handle still fails loudly: the distinction is between a newer engine and a broken peer.
+
+Sanitization constants on that path: `ACP_MAX_DISPATCH_TASK_PREVIEW_BYTES = 160` (control-character-stripped prefix with the standard truncation marker; the exact task never leaves the process), `ACP_MAX_DISPATCH_ID_BYTES = 128`, `ACP_MAX_LIVE_TOOL_CALLS = 128`, `ACP_MAX_REPLAY_TOOL_CALLS = 8192`.
+
+## THE 14-FAMILY TABLE (verbatim, with a 2026-09-20 verification column)
+
+| # | Bus group | Channels | GUI coverage | Verified against `src/core/bus-events.ts` |
+| -: | --- | --- | --- | --- |
+| 1 | Session | `session.start/end/parked/resumed/turn_switched` | Functional session operations are wired, but these lifecycle events are not public. Branch/turn switching has no GUI. | **Accurate.** All five exist. `SessionParkReason` = `create_new\|resume_other\|fork\|switch_branch\|close\|shutdown`; `SessionResumeVia` = `resume\|switch_branch`. `session.turn_switched` carries `{sessionId, turnId, at}` and exists specifically so caches keyed on session id alone know their fold is stale — a GUI that caches per session **must** subscribe to it if `/tree` ever lands. |
+| 2 | Domain | `domain.loaded/failed` | **Upstream boundary**; useful in diagnostics, not the notebook. Never forward raw `error`. | **Accurate, and the warning is enforced by the type.** `DomainFailedPayload.error` is typed `unknown` — "the caught value as-is; loaders catch unknown and rethrow after emitting." Never serialize it. |
+| 3 | Config | `config.hotReload/nextTurn/restartRequired/reloadFailed` | Safe patch response is wired; live change/reload classification is absent. Sanitize settings out of the event. | **Accurate, and the warning is load-bearing.** `ConfigChangePayload` is `{diff: ConfigDiff, settings: Readonly<ClioSettings>}` — **the whole settings snapshot, credentials included.** Forward only `diff` (`{hotReload[], nextTurn[], restartRequired[]}`), which is exactly the path list a GUI settings page needs to know what changed under it. `ConfigReloadFailedPayload.message` is already pre-formatted by `formatSettingsFailure` to one line, no stack, and is emitted on transitions only (`null` clears). |
+| 4 | Permission | `permission.requested/resolved` | Standard ACP permission is partial; richer policy/escalation provenance is absent. | **Accurate and now fully specified.** `PermissionRequestedPayload` carries exactly the fields the parity matrix's "Permission overlay: **Partial**" row is missing: `tool, actionClass, origin, axis, reasons[], ruleId, posture, rejection{short,detail,hints[]}, policySource, reasonCode, requestedBy, requestId, agentId, summary, target (sanitized one-line preview), timeoutMs, fallback ('deny'\|'fail'), escalation`. `requestedBy` is the worker run id, present only when dispatch republishes an escalate-posture worker's parked ask. `PermissionResolvedPayload` = `{status: 'granted'\|'denied'\|'expired', requestId, origin, decidedBy, tool, actionClass, reason, requestedBy, fallback, at}` — only `status` is guaranteed. **This is the single highest-value unbuilt ACP extension for the GUI's approval UI.** |
+| 5 | Safety | `safety.classified/blocked/allowed/loopBlocked/toolBudgetExceeded` | `loopBlocked` and `toolBudgetExceeded` are both public and wired; classified/blocked/allowed are not. | **Accurate.** `LoopBlockedPayload` = `{tool, repeatCount, blocksThisTurn, budget, interrupted, disposition, at, turnId?}` with `LoopBlockedDisposition = 'block'\|'lockout'\|'stop'`. The three dispositions mean different things and a GUI must not collapse them: `block` is a per-call block below budget (warn notice); `lockout` disables tools for the rest of the turn so the model answers from what it gathered, **and does not cancel the turn** (`interrupted: false`); `stop` cancels. `ToolBudgetExceededPayload` = `{tool, callsThisTurn, softBudget, hardCeiling, interrupted, at, turnId?}`. `SafetyBlockedPayload`/`SafetyClassifiedPayload`/`SafetyAllowedPayload` carry `{tool, actionClass, ruleId?, posture?, policySource, reasonCode}` (+`reasons[]` on classified, +`rejection` on blocked). |
+| 6 | Provider | `provider.health` | Public and wired. The explicit GUI target probe and unsolicited health transitions both reach the client now. | **Accurate.** `{id, status: TargetStatus}` after every probe/disconnect. Trivially safe to forward; the cheapest win on this table. |
+| 7 | Runtime/residency | `runtime.notice`, `residency.mutation` | **Upstream boundary**; capacity/VRAM/degradation facts must retain source and numeric detail. | **Accurate, and the kinds are a closed vocabulary now.** `RUNTIME_NOTICE_KINDS = ['will-not-fit','about-to-evict','swap','co-resident','stress','degraded','route-fallback']`, each with a declared producer enforced by a contract test "so no kind outlives the code that emits it". Payload `{kind, level: 'info'\|'warning'\|'error', targetId, runtimeId, model, message, detail?: Record<string, number\|string\|boolean>}`, branded `DeclaredRuntimeNotice` so a raw notice fails to typecheck. `degraded` reports a live turn whose token rate collapsed, i.e. a silent spill to CPU becoming visible while it happens — **that is the HPC-DNA fact the operator wants visible in the GUI.** `ResidencyMutationPayload` = `{targetKey, targetId, runtimeId, model, operation: 'load'\|'evict', at}`. |
+| 8 | Dispatch | `dispatch.scopeNotice/enqueued/started/progress/completed/failed` | Enqueued/started/progress/completed/failed are public and wired to the fleet strip; `scopeNotice` is still absent. | **Accurate.** See the payload notes below — this family is where the dispatch board's data comes from. `DispatchScopeNoticePayload` is a discriminated union on `code`: `typed_scope_replaced_inferred_paths` (carries `omittedPaths[]`) or `legacy_scope_inferred\|legacy_scope_empty` (carries `paths[]` of `{path, policy: 'working-context'\|'write-boundary', provenance: 'declared'\|'derived'\|'inferred', source, confidence: 'certain'\|'high'\|'medium'\|'low'}`). It carries filesystem paths, which is why it is not in the allowlist. |
+| 9 | Compaction | `compaction.begin/end` | `compaction.end` is public and wired; `begin` is not, because a client that drew a "compacting" state from it would have to guess when to clear it. Combine the end with token/pressure facts before visualizing. | **Accurate.** `CompactionPayload = {trigger, at}` — deliberately thin, which is why the row says combine it with token facts. |
+| 10 | Middleware | `middleware.hookFailed` | **Upstream boundary**; diagnostics/inbox surface. | **Accurate, and richer than the row implies.** `{kind: 'hook_failed'\|'budget_exceeded'\|'registration_conflict', registrationId, hook, at, message?, elapsedMs?, budgetMs?, steadyStateWarn?, p50Ms?, p95Ms?, overCount?, windowSamples?}`. **`steadyStateWarn` is the field a GUI performance panel wants**: true only when an overrun is steady-state (≥N of the last M post-warmup calls over budget), not a lone spike. "Diagnostics only; nothing subscribing here may decide anything." |
+| 11 | Context | `context.activity/warning/pruned/recalled` | `context.warning` is public and wired; activity/pruned/recalled are still an **upstream boundary**, and `pruned`'s `pressure` is the remaining piece of a scientific context instrument. | **Accurate but INCOMPLETE — a fifth channel exists**, `context.sourcesChanged` (`{cwd}`), an explicit boundary meaning descendant sessions must recapture disk sources. `ContextActivityPayload` = `{kind: 'context-init'\|'context-clear'\|'context-refresh'\|'context-wiki'\|'compaction', phase: 'scan'\|'codewiki'\|'generate'\|'clio-md'\|'state'\|'compact'\|'done', status: 'started'\|'running'\|'completed'\|'failed', message, at, current?, total?, detail?}` — **it already has `current`/`total`, so it is a ready-made progress bar.** `ContextPrunedPayload` = `{stage: 'mask_observations'\|'working_set'\|'llm_summary', tokensBefore, tokensAfter, trigger, snapshotIdBefore, snapshotIdAfter, at, pressure?, maskedObservations?, maskedThinkingBlocks?, maskedThinkingChars?, policyId?, evictedItems?}` — **`pressure` is the context meter the parity matrix calls Absent.** `ContextRecalledPayload` = `{ref, trigger: 'tool'\|'operator', tokensReadmitted, at}`. `ContextWarningPayload = {warning: string\|null}`, transitions only. |
+| 12 | Agent | `agent.status.changed` | **Upstream boundary**. Run-level identity is public through the dispatch events, but per-phase status is not. | **Accurate, and this is the GUI's live status line.** `{runId: string\|null, phase: StatusPhase, prevPhase: StatusPhase, at, elapsedFromStart, watchdogTier: 0\|1\|2\|3\|4, metadata?: {toolName?, attempt?, reason?, agentName?}}`. `StatusPhase` = `idle\|preparing\|waiting_model\|thinking\|writing\|tool_running\|tool_blocked\|retrying\|compacting\|dispatching\|stuck\|ended`. The taxonomy is owned in `core/bus-events.ts` (not `src/interactive`) precisely because it rides the bus into the safety domain's audit trail. **This one channel would replace most of the GUI's inferred spinner state with reported fact.** |
+| 13 | Run/budget | `run.aborted`, `budget.alert` | **Upstream boundary**; keep abort sources and cost provenance distinct. | **Accurate, and the distinctness rule is enforced.** `RunAbortSource = 'dispatch_abort'\|'dispatch_drain'\|'stream_cancel'\|'loop_guard'` with a runtime guard `isRunAbortedPayload`. "Subscribers must not collapse the sources: a drained dispatch run, a user-cancelled stream, and a guard-stopped loop are different operator situations." `BudgetAlertPayload = {level: 'at'\|'over', currentUsd, ceilingUsd}` — **informational in v0.x: scheduling never rejects the enqueue**, so the GUI notice is the operator's only signal and must not imply enforcement. |
+| 14 | Shutdown | `shutdown.requested/drained/terminated/persisted` | The GUI observes child/process loss, not these structured phases. Diagnostics only. | **Accurate.** `ShutdownRequestedPayload = {phase: TerminationPhase}`; the other three carry `EmptyPayload = Record<string, never>`. |
+
+## THREE FAMILIES WITH NO ROW (add them)
+
+| Bus group | Channels | Payload | GUI verdict to assign |
+| --- | --- | --- | --- |
+| **Accountability** | `accountability.evidenceReady` | `AccountabilityEvidenceReadyPayload extends ObservabilityRunEvidence { runId }` | **PUBLIC AND WIRED — already in the ACP allowlist and the audit has no row for it.** From the source comment: it fires once a finalized run's evidence bundle and its sidecar index row have landed, so "the board can show first-pass success and a finding count without reading Clio's state tree." The fields are *exactly* `ObservabilityRunEvidence`, the same shape the projection attaches to the run summary, "so the bus and the snapshot cannot describe the same moment two ways." **A failed build publishes nothing here** — a client that never receives it has learned only that no bundle is ready, which is the truth. This is the backbone of the evidence-receipts surface the operator asked for. |
+| **Extensions / plugins** | `extensions.reloaded`, `plugins.reloaded`, `extensions.loadIssue` | `ExtensionsReloadedPayload = {generation, previousGeneration, changed, digest}`; `PluginsReloadedPayload` is the same shape; `ExtensionsLoadIssuePayload = {message}` | **Upstream boundary → easy win.** `extensions.reloaded` is published only after *both* the new extension generation and its user-hook registrations have been committed, never between. `plugins.reloaded` is a separate, data-only generation for recipe and prompt consumers. **The library-marketplace page needs exactly this to know when to refetch after an install**, instead of polling. `digest` is a content identity, so the GUI can skip a refetch when `changed` is false. |
+| **Memory** | `memory.stepCompleted` | `{endpointKey, targetId}` | **Diagnostics only.** Deliberately carries the endpoint a proactive-memory step called and *nothing about what it decided*. Its only consumer stamps an expected-cold reason when a step ran between turns on the endpoint the chat target streams against. Useful as the "observed memory steps" the settings table asks to pair with the `context.memory.*` controls. |
+
+## Full channel roster (47), for the record
+
+`session.start`, `session.end`, `session.parked`, `session.resumed`, `session.turn_switched`, `domain.loaded`, `domain.failed`, `config.hotReload`, `config.nextTurn`, `config.restartRequired`, `config.reloadFailed`, `permission.requested`, `permission.resolved`, `safety.classified`, `safety.blocked`, `safety.allowed`, `safety.loopBlocked`, `safety.toolBudgetExceeded`, `provider.health`, `runtime.notice`, `residency.mutation`, `dispatch.scopeNotice`, `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, `accountability.evidenceReady`, `compaction.begin`, `compaction.end`, `middleware.hookFailed`, `extensions.reloaded`, `plugins.reloaded`, `extensions.loadIssue`, `context.activity`, `context.sourcesChanged`, `context.warning`, `context.pruned`, `context.recalled`, `memory.stepCompleted`, `agent.status.changed`, `run.aborted`, `budget.alert`, `shutdown.requested`, `shutdown.drained`, `shutdown.terminated`, `shutdown.persisted`.
+
+A compile-time tripwire (`BusPayloadMapCoversAllChannels`) means adding a channel without a payload fails to typecheck — so this roster can be regenerated mechanically and a GUI test should assert the GUI's own event union is a subset of it.
+
+## Dispatch payload fields the board needs (verbatim from the types)
+
+`DispatchRunIdentity` (shared by every dispatch event): `runId, agentId, task?, agentAudience?, requestOrigin?, targetId, wireModelId, runtimeId, runtimeKind, endpoint?{key,label,limit}, budget?, node?, gate?{role,cycle}, council?{group,label,color?,round}, rerouteCount?, contextWindow?`.
+
+- `task` is the **exact** dispatched task; the comment says "UI projections must sanitize and bound it before rendering." Over ACP only the 160-byte stripped preview crosses.
+- `gate` and `council` exist **for board badges** — the compete/council surfaces are meant to be driven from these, not reconstructed.
+- `contextWindow` is there "for the per-worker context meter."
+- `node` absent renders as the local node.
+
+`DispatchStartedPayload` adds `pid, processCommand?, assignmentId, attempt, parentToolCallId?`. **`assignmentId` and `attempt` are required**: "a surface that draws one entry per logical work item has to key on the assignment, and a spawn path that forgot to send it would silently split a failover into two entries." **Key the GUI's run rows on `assignmentId`, not `runId`.** `parentToolCallId` is what lets a transcript nest a worker under the tool segment that started it instead of appending it wherever the turn happens to be — that is the nesting the operator wants in the agent viewport.
+
+`DispatchProgressPayload.event` is **deliberately `unknown`**: it is the worker/ACP event stream crossing a process boundary. The workbench dropped it entirely in favour of a per-run progress count. Any GUI that renders it must validate it at runtime.
+
+`DispatchTerminalStats` (required on completed, partial on failed): `lineage, tokenCount, inputTokenCount, outputTokenCount, cacheReadTokenCount, cacheWriteTokenCount, cacheWrite1hTokenCount?, reasoningTokenCount, staticShellHash, sessionShellHash, dynamicHash, costUsd, costProvenance?, durationMs, exitCode, toolActivity: ToolActivitySummary|null, hostVerification?: 'verified'|'rejected'|'skipped'|'not_implicated'`. Required on completed specifically so "dropping a field from one finalizer is a compile error."
+
+`DispatchFailedPayload.reason: RunOutcome | 'retry_denied'` — "the board maps it to a presentation status, so emitters must not collapse the taxonomy."
+
+Both terminal payloads may carry `skillActivations[]`, present only when the run activated a skill. "A run that loaded a skill and then failed is exactly when the operator needs to know which skill and which copy of it."
+
+## Terminal token metadata (the one non-event fact on this boundary)
+
+Terminal metadata carries **exactly five** token fields: `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, under `_meta["clio-coder/usage"]`. The workbench rule, worth keeping: **never converted to price or context pressure by the GUI.** Show the five numbers and Clio's own reported cost with its provenance; do not multiply by a rate card.
+
+## Agent attribution (already public, easy to miss)
+
+Every live `session/update` carries a `clio-coder/agent` attribution in its `_meta`, and a tool call whose execution spawned a delegated run is **re-announced** carrying that worker's agent id, run id, and node. The main narrative is attributed to the orchestrator explicitly, "so the GUI states who produced a card instead of assuming it."
+
+What does **not** cross, and must not be simulated: a sub-agent's own narrative or reasoning. A delegated run's output reaches the orchestrator as a tool result, so per-message worker attribution has nothing to attach to on the ACP session stream.

package/docs/gui/inspector-presentation.md

@@ -0,0 +1,71 @@
+# Inspector presentation atlas
+
+> **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.
+
+What each of the retired workbench's thirteen inspectors showed, in what order, and
+which route in `apps/clio-coder-gui` now carries the same data. The data is
+reproduced; the presentation decisions recorded here are what the new GUI still owes.
+
+**Verification of the audit's data claim, per inspector → new route:**
+
+| Inspector | Data reproduced by | Verdict |
+| --- | --- | --- |
+| catalog (26K) | `contracts/library.ts` | yes, with agents/skills/verifiers/extensions collapsed into one `Library` shape |
+| config (16K) | `contracts/settings.ts` + `settings-safe.ts` | yes: `ConfigEntry.contextCostTokens` and `reloadClass` are on the wire |
+| decisions (12K) | `contracts/evidence.ts` (`gate`) | yes, but shape is opaque (`JSON.stringify(gate)` at evidence.tsx:226) |
+| dispatch (8K) | `contracts/fleet.ts` | yes |
+| eval (24K) | `contracts/reports.ts` | yes |
+| evidence (17K) | `contracts/evidence.ts` | yes |
+| fleet (25K) | `contracts/fleet.ts` + `fleet-events.ts` | yes |
+| interop (11K) | `contracts/system.ts` | yes: `wiring`, `decisionStale` and `decidedAt` are on the wire, derived by the core's own `interopProposals` |
+| recovery (10K) | `contracts/system.ts` | yes |
+| routing (12K) | `contracts/targets.ts` | yes |
+| toolchain (9K) | `contracts/toolchain.ts` | yes |
+| trace (15K) | `contracts/traces.ts` | yes |
+| usage (16K) | `contracts/reports.ts` | yes: the token fields and the origin split are read out of `facts[].values` by `client/pages/usage-model.ts` |
+
+**The empty-state grammar — the most reusable thing here.** Every panel distinguished four states and used different words for each. Reproduce this everywhere:
+1. *Not read in this session* — `"The durable evidence inventory has not been read in this session."` / `"No diagnostic sweep has run in this desktop session. Nothing is inferred from a successful conversation."`
+2. *Store missing* — `"This installation has never run an evaluation, so it has no eval store at all. That is a missing store, not an empty one."` A dash in a figure means the store was not found: `"A dash means Clio Coder could not find that local history store. It does not mean zero activity."`
+3. *Store present, nothing in it* — `"Clio Coder has built no evidence bundles on this installation. This is an empty record, not a health claim."`
+4. *Record predates the schema* — `"This bundle predates the canonical trust projection, so it records no axes to open."`
+
+And a fifth, for every bounded list: `"Older evidence bundles are outside this bounded window."` / `"Later phases are outside this bounded index."` / `"rarer kinds not shown"`. Every truncation flag on the wire gets a sentence; none is silently dropped.
+
+**Per-inspector fact order and grouping.**
+
+- **config** → *Effective Clio Map*. Four summary figures first: effective setting facts, customization surfaces, estimated context cost (`~` + locale-formatted sum of `contextCostTokens`), needs-a-restart count. Then a three-stage "influence path" diagram: **01 Sources** (scope + setting-source counts, merged into one map, sorted by count descending then name, top 8) → **02 Loaded layers** (categories in `CUSTOMIZATION_CATEGORY_ORDER`, shown as a 3-4 letter code plus label) → **03 Behavior**. Then settings grouped by *family* (`key.split(/[.[]/, 1)[0]`), families sorted alphabetically. Entry source line: the project-relative path, or `"project root"` when the path is `/`, or `` `${scope} scope` `` when no path.
+- **catalog** → tabbed (Agents / Skills / Verifiers / Library / Extensions) with arrow-key tab navigation. Agent card facts in order: capability, project context tier, tool-call budget (`min–max` or bare `min`), read reserve; bound skills as chips; declared tool surfaces behind `<details>` with the count on the summary; footer = result contract + `"Text synthesis at boundary"` / `"Stops at boundary"`. Skill card leads with the *reach sentence* — `"The model can load this by name"` / `"Its root is not trusted, so the model never sees it"` / `"Its frontmatter reserves it for you"` — then precedence, root trust, model invocation; footer counts issues and flags `installed by a dispatched worker` / `has an upstream`. Free-text query filters across all string fields, case-folded with `toLocaleLowerCase("en-US")`.
+- **usage** → 30-day window, stated as `from … through …`. Summary: total tokens (+ API calls), Clio-reported cost (`"Recorded cost, never a GUI estimate"`), sessions, dispatch runs. Then token composition as five comparative bars — **`"Bars compare token fields with one another; they are not additive percentages. Provider accounting can overlap cache and reasoning fields."`** Then origin split (turns / side questions / handoffs), models sorted by tokens, skills split into activated vs dormant.
+- **trace** → per run: status mark, four totals (tokens, cost, wall time, runtime), then an ordered phase list with name / `kind · owner` / `tokens · cost · duration · N retries` / status, then event-kind and process-kind histograms. Boundary line: `"Event payloads, event names, and process command lines stay on the host by design. What crosses is how many of each kind there were."`
+- **toolchain** → one resolution label per item, with a deliberate three-way split: `!supported → "Platform unsupported"/neutral`; `source === "path" → "Using PATH"/success`; `source === "vendored" → "Using pinned copy"/success`; otherwise `"Not available"/warning`.
+- **interop** → summary (detected of known kinds, wired as peers, would be offered, detected-at), then one row per agent with the wiring sentence. Boundary: detection reads files only, starts no agent, and the version shown is the last one Clio recorded — `"opening this panel cannot become 'execute every coding agent installed on this machine'"`.
+- **routing** → target selector (targets derived client-side from the model rows, deduped and `localeCompare`-sorted), then a filtered model grid. Filter is a `useDeferredValue` over the lowercased query, matched against `[modelId, runtimeId, residency, ...capabilities]`. Zero values render `"Not reported"`, never `0`.
+- **dispatch** → installation-wide, explicitly not project-scoped and not a live stream: `"This is global installation state, not a fact about the selected project and not a live event stream."`
+- **recovery**, **evidence**, **fleet**, **eval**, **decisions** → see their own artifacts.
+
+**Shared idioms worth extracting into `client/design/`:**
+- `<StatusMark tone label>` — a glyph + label pair with tones `success | warning | error | neutral | info | action`. Used by every panel; there is no other status primitive.
+- A `PanelHeading` with `eyebrow` (all-caps, wide-tracked), `title`, optional action slot. Every panel opens with an eyebrow that names the data's *scope and mutability*: `EVIDENCE BUNDLES · INSTALLATION-WIDE`, `DURABLE ACCOUNTING · TRACE DATABASE`, `EVAL REPORTS · INSTALLATION-WIDE · READ ONLY`, `INSTALLATION · REDACTED DIAGNOSTICS`, `MODELS · WORKER ROUTING`, `GATE DECISIONS · SEALED COORDINATOR VERDICTS`, `COUNCIL TOPOLOGY · SEATED VOICES AND ROUNDS`, `APPROVAL NEEDED · ONE USE`.
+- A closing **boundary paragraph** on every panel naming exactly what stays on the host. These are not boilerplate; each one is specific and each should survive.
+- Formatters: `formatTokens(v) = v === null ? "not recorded" : v.toLocaleString("en-US")`; `formatCostUsd(v) = v === null ? "not recorded" : "$" + v.toFixed(v > 0 && v < 0.01 ? 4 : 2)` — **exactly zero prints as `$0.00`, not "free", because a local runtime that prices at zero and a run whose cost was never recorded are different facts and only the second is null**. `client/api/clock.ts` already has `formatCost` and `formatTokens` matching this; keep them.
+
+**Status against this atlas.** Every claim above is either built or listed here as a deliberate difference.
+
+| Inspector | Where it lives now | Pure model and test |
+| --- | --- | --- |
+| config | `/settings/why` (four figures, influence path, inventory by category) and `/settings/effective` (settings grouped by family) | `client/pages/config-map-model.ts`, `tests/config-map-model.test.ts` |
+| catalog | `/library`: a `tablist` with arrow, Home and End keys; agent cards in the fact order above; skill cards led by the reach sentence; free text across every string field | `client/pages/library-model.ts`, `tests/library-model.test.ts` |
+| interop | `/system/interop`: summary, one card per kind with the wiring sentence | `client/pages/interop-model.ts`, `tests/interop-model.test.ts`, `tests/system-http.test.ts` |
+| dispatch | `/fleet`, which carries the installation-wide sentence as `DISPATCH_SCOPE` | `client/design/panel-model.ts` |
+| usage, trace, toolchain, routing, evidence, eval, decisions | unchanged since the previous sprint | `usage-model.ts`, `trace-model.ts`, `toolchain-model.ts` |
+
+Every page now opens with a `PanelHeading` from the `PANELS` registry and closes with its own `Boundary`. An eyebrow ends in one word from `MUTABILITIES`, and `tests/panel-model.test.ts` holds the registry to that list.
+
+Deliberate differences from the retired workbench:
+
+- **The interop read probes versions only when asked.** Opening `/system/interop` reads files and runs nothing, as the workbench did, and shows the last version Clio Coder recorded. The "Detect again and probe versions" button sends `?probe=versions`, which runs one bounded `<bin> --version` per installed agent inside a scratch home. Each version says which of the two it is (`versionSource`), and `tests/system-http.test.ts` holds both halves.
+- **Wiring has a fifth and a sixth word.** Besides configured, not-ACP, proposed and decided, the wire carries `not-offered` (an ACP kind with no executable to wire and no standing answer) and `unknown` (the settings that decide wiring could not be read). Neither may collapse into one of the four.
+- **Two skill footer flags are not on the wire.** "Has an upstream" is derived from `origin.kind === "remote"`. "Installed by a dispatched worker" has no counterpart in `LibraryResource` and is not shown.
+- **The entry source line shows the path as the wire gives it.** `ConfigEntry.sourcePath` is absolute in this application, which is local by construction, so there is no project-relative form to prefer. The `"project root"` and `` `${scope} scope` `` rules hold.
+- **Wire vocabulary reads as words.** `scalarText` humanizes a lowercase wire token only under a vocabulary key (`kind`, `state`, `status`, `reason`, `outcome`, `verdict`, `level`, `tier`, `mode`, `phase`, `class`, `category`, alone or as a camel-case or snake-case suffix). The key decides, never the value, so an id, name or model is never rewritten.

package/docs/gui/parity/01-cli-surface.md

@@ -0,0 +1,74 @@
+# GUI parity matrix — part 1: command-line 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.
+
+Extracted verbatim from `apps/workbench/PARITY.md`. Original audit anchor: commit `d41e7dd1` (`v0.4.0`), 2026-08-31, comparing `src/cli/index.ts`, `src/interactive/slash-commands.ts`, and `src/entry/orchestrator.ts` against the protocol-v4 GUI at `apps/workbench`.
+
+## Verdict vocabulary (load-bearing — do not soften)
+
+- **Present** — the GUI renders or drives the same authoritative fact or operation.
+- **Partial** — a useful, truthful subset crosses a typed boundary.
+- **Absent** — there is no GUI surface, even when a formatted terminal command exists.
+- A graphical substitute is NOT claimed for destructive administration, developer-only instruments, or terminal presentation that should deliberately stay outside the app.
+
+## Marker vocabulary
+
+- **host-only-by-design** — a payload the workbench would not carry in any form, as distinct from one it had not carried yet. Members at audit time: event payloads, event names, process command lines, a council's deliberation, a gate's reasoning, a verification check's argument vector, an eval report's runner attachments. Bounded aggregates, topologies, classifications, and verdicts over them cross; the rows and prose never do, and the panel says so on screen rather than leaving the absence to be inferred.
+- **deferred-by-design** — the remaining gap is a *mutation*, not a missing read. The workbench was read-only by decision: every adapter ran a fixed, argument-free command and changed nothing. Rows whose gap mixes a missing read with a missing mutation are deliberately left unmarked so the read half stays visible as work the GUI can still do.
+- **blocked-on-phase4** — the owning surface publishes no fixed typed read command, so parity cannot be claimed honestly.
+
+## STALENESS NOTE FOR THE NEW APP (verified 2026-09-20 against `src/` and `apps/clio-coder-gui/`)
+
+`host-only-by-design` is **workbench policy, not a universal rule**, and the replacement app has already decided otherwise on purpose. `apps/clio-coder-gui/contracts/traces.ts` carries `payload_json` on `TraceEvent` and `command` + `command_digest` on `TraceProcess`, served over `/api/traces/runs/:runId/events` and `/api/traces/runs/:runId/processes`. The threat model changed: the workbench shipped a browser talking to a bounded ACP child over a validated protocol, the new app is a localhost server the operator started against their own machine. Do not "restore" the exclusion rule. Keep the *reasoning* (§ the exclusion-vs-redaction doctrine artifact) and re-derive the verdict per field.
+
+## Row-count correction
+
+The file's own verdict summary claims Present 22 / Partial 61 / Absent 29 / **Total 112**. The four tables physically contain **113** rows (32 + 32 + 31 + 18). The discrepancy is the corrupt `Worker result and archive sharing` row (part 2), whose Gap cell was eaten by an unescaped pipe.
+
+## The table (32 rows)
+
+| # | Harness capability | Harness operation | GUI verdict | Gap | Obsolete for the new app? |
+| -: | --- | --- | --- | --- | --- |
+| 1 | Interactive repository chat | Bare `clio-coder` starts the full TUI | **Partial** | ACP conversation, tools, approvals, and session replay are present, but many TUI overlays and side workflows are not. | No — still the core parity target. |
+| 2 | ACP agent server | `acp` serves Clio Coder over stdio | **Present** | The GUI launches and binds one real ACP child per open project. | No — `apps/clio-coder-gui/server/acp/` keeps this. |
+| 3 | Headless turn | `run` with route, autonomy, session, sampling, output, and context flags | **Partial** | The GUI drives interactive ACP turns but has no headless job form or print, JSON, JSONL, and JSON-stream output modes. | No. A "Run Lab" remains unbuilt. |
+| 4 | First-run configuration | `configure` interactive wizard | **Partial** | **deferred-by-design**: The GUI edits four safe settings and probes targets; it cannot author a complete installation. | Partly — the four-key limit is superseded; see the settings artifact. |
+| 5 | Target management | `targets` list/add/use/profile/remove/rename and probe | **Partial** | **deferred-by-design**: Target listing, selection, offline models, worker profiles, bindings, and explicit probes are present; lifecycle mutations are absent. | **STALE** — the new app already exposes `POST /api/workspaces/:id/targets/:targetId/use` and `/remove` alongside `/probe`. |
+| 6 | Model discovery | `models [search]`, online and offline JSON inventories | **Partial** | Offline model capability inventory is present; online discovery, selection breadth, favorites, and load controls are absent. | No — favorites now have a real settings home at `chat.modelPicker.favorites`. |
+| 7 | Authentication | `auth list/status/login/logout` | **Absent** | **deferred-by-design**: No credential-status or reviewed login/logout operation crosses the GUI boundary. | No. Still the right call; never route secrets through the renderer. |
+| 8 | Diagnostic sweep | `doctor [--fix]` | **Partial** | **deferred-by-design**: Every check reaches Settings by name, section, and verdict; finding details, repair preview, `--fix`, and focused checks are absent. | No. Note `src/cli/` now has nine doctor modules (deep/hpc/naming/panes/slurm/state-size/task-worktrees/toolchain/validation-contract) the audit predates. |
+| 9 | Resolved installation paths | `paths [--json]` | **Partial** | Recovery reports a root-resolution count but intentionally withholds native paths and has no path reference surface. | Revisit — a localhost app that already shows the workspace path has no reason to withhold install roots. |
+| 10 | State reset and recovery | `reset` | **Partial** | **deferred-by-design**: Read-only installation recovery inspection is present; previewed repair, selective reset, and wipe operations are absent. | No. |
+| 11 | Project context | `context` status/init/refresh/wiki/reset/index/replay/working-set | **Partial** | Effective context sources and earlier replay are visible; authoring, indexing, working-set state, recall, and reset are absent. | No — but `context-init`/`context-index`/`context-clear` are now RETIRED subcommand tombstones (`src/cli/index.ts:333`); the live path is `context <sub>`. |
+| 12 | Uninstall | `uninstall` | **Absent** | **deferred-by-design**: Destructive installation removal belongs in a separate confirmed lifecycle surface. | No. |
+| 13 | Upgrade | `upgrade` | **Absent** | **deferred-by-design**: The GUI has no version comparison, migration preview, or upgrade operation. | No. |
+| 14 | Agent reference | `agents [--json]` | **Present** | Capability atlas renders bounded discovered-agent recipes and provenance. | No — new app has `GET /api/workspaces/:id/library/agents`. |
+| 15 | Fleet lifecycle | `fleet` list/new/validate/graph/commands/run/status/view/inspect/drain/resume | **Partial** | **deferred-by-design**: Recent run inspection, bounded journal follow, and the fleet-root step index are graphical; authoring, validation, admission control, and execution are absent. | No — and `fleet decisions --json` + `fleet verify` + `fleet preflight` now exist as separate modules. |
+| 16 | Evidence artifacts | `evidence` build/list/inspect | **Present** | Runs lists recent bundles and opens one to its per-run trust axes. Building a bundle stays terminal, which is a mutation rather than a read. | **STALE** — the new app already has `POST /api/workspaces/:id/evidence/:runId/build`. Also `evidence inventory --json` exists now. |
+| 17 | Evaluation | `eval` run/report/compare | **Partial** | Runs lists every stored report with its outcome, route, accounting, and per-scenario result. A report's runner attachments are the whole session transcript and are **host-only-by-design**. Running an eval is execution; comparison and per-trial metric distributions are absent. | Partly — `eval` now also has `skill`, `validate`, `gate`, `--package`, `--task-file`, `--format swe-jsonl\|junit`, and `eval inventory --json`. |
+| 18 | Durable memory | `memory` list/propose/promote/approve/reject/prune | **Partial** | Effective configuration can report memory presence and the catalog can describe resources, but memory records and reviewed mutations are absent. | No. `src/cli/memory.ts` still has no `--json`; a typed read is still the blocker. |
+| 19 | Historical usage | `usage report` | **Present** | The project-scoped 30-day Usage record projects bounded report rows and distinguishes a missing store from zero activity. | No — new app has `GET /api/workspaces/:id/usage`. |
+| 20 | Durable trace | `trace` runs/phases/tail/procs/prune/sql/ui | **Partial** | Runs renders per-run and per-phase accounting plus event and process shapes. Row-level tails and process rows are **host-only-by-design**; pruning is deferred, and arbitrary SQL must never become the GUI boundary. | **STALE on host-only** — see the staleness note above. `trace code-steps <rootId> --json` is also new. The "never expose arbitrary SQL" clause still holds. |
+| 21 | Extension packages | `extensions` list/discover/install/enable/disable/remove | **Partial** | Installed extension inventory, scope, precedence, resources, and diagnostics are present; lifecycle mutations are absent. | Partly — `extensions run <id> <command>` is new; `library` now overlaps this family heavily. |
+| 22 | Skills | `skills` list/search/inspect/validate/install/update/sync/eval | **Present** | Every installed skill reaches the atlas with its trust, invocability, tool policy, provenance, and the loader's own validity verdict; installed search is the atlas filter and marketplace search is the library. Installing, updating, and evaluating are mutations rather than reads. | **STALE — the command family no longer exists.** `skills` was absorbed into `library`: the reads are `library skills [--all] [--json]`, `library inventory --json`, `library validate <SKILL.md> [--json]`; the mutations are `library install/update/enable/disable/remove/pin`. |
+| 23 | Resource library | `library` list/search/add/use/sync/push/remote-confirm | **Partial** | Bounded available-resource inventory is present; search across remotes and reviewed lifecycle operations are absent. | **STALE — rewritten.** See the CLI-surface-inventory artifact for the current 20-subcommand surface. |
+| 24 | Verifiers | `verifiers` discover/author/validate/dry-run/add/edit/rename/remove | **Partial** | **deferred-by-design**: The atlas renders the declared check plane and the catalog's parse verdict. Each check's argument vector is **host-only-by-design**; authoring, editing, and dry-run execution are absent. | Partly — `verifiers baseline <id>` is new. New app has `GET /api/workspaces/:id/library/verifiers`. |
+| 25 | External toolchain | `tools` list/status/install | **Partial** | Settings renders a path-free pinned inventory with resolution and platform facts; per-tool status detail and reviewed installation are absent. | **STALE** — the new app already has `POST /api/toolchain/tools/:toolId/install` and `/remove`, driven through `/api/operations/:id`. |
+| 26 | Pane installation | `panes install` | **Absent** | **deferred-by-design**: Installation is a consequential toolchain mutation and has no GUI operation. | No. `panes install [--force] [--json]` is still the only JSON on that family. |
+| 27 | Documentation server | `docs [topic]` | **Absent** | There is no contextual documentation launcher or embedded operator reference. | **STALE** — the new app has `/api/docs/tree`, `/api/docs/page`, `/api/docs/search` and a `client/pages/docs.tsx`. |
+| 28 | Effective configuration command | `config inspect --json` | **Present** | Effective Clio Coder uses its bounded projection for settings, sources, precedence, reload timing, and issues. | No — new app has `GET /api/workspaces/:id/config-graph`. |
+| 29 | Portable sharing | `share`, `export`, and `import` | **Absent** | **deferred-by-design**: No archive inspection, export, dry-run import, confirmation, or conflict surface exists. | No. Note `share` is registered both top-level and under `dev`. |
+| 30 | Component instrument | `dev components` list/snapshot/diff | **Absent** | This developer instrument is intentionally outside the core GUI and has no separate developer canvas. | No. |
+| 31 | Evolution instrument | `dev evolve` init/validate/summarize | **Absent** | Change-manifest development remains a CLI workflow. | No. |
+| 32 | Version | `--version` and `version` | **Present** | Settings opens with an About record: the version Clio Coder reported in the ACP handshake, the GUI's own version from an optional bootstrap field, the ten advertised capabilities in words, and doctor's Clio Coder, Node, and platform versions beside the handshake's, labelled by source and never reconciled. The status bar names the handshake version. | No — new app has `GET /api/meta`. Keep the "labelled by source and never reconciled" rule; it is the honest thing. |
+
+## Missing rows the new app must add
+
+The audit predates these command families entirely; each needs its own parity row:
+
+| Harness capability | Harness operation | Starting verdict | Note |
+| --- | --- | --- | --- |
+| MCP servers | `mcp` (7 `--json` call sites in `src/cli/mcp.ts`) | **Absent** | Has machine-readable output already; a typed read is available today. |
+| GUI lifecycle | `gui` (`src/cli/gui.ts`) | n/a | This is the launcher for the app itself; it replaces the workbench's `scripts/gui-lifecycle.ts`. |
+| Task ledger (CLI) | `tasks` (`src/cli/tasks.ts`) | **Absent** | No `--json` yet — the typed read is the blocker, same shape as memory. |
+| Fleet preflight | `fleet preflight` (`src/cli/fleet-preflight.ts`) | **Absent** | Admission dry-run; the natural first mutation-adjacent GUI surface. |