@iowarp/clio-coder 0.3.0

package/docs/trace-store.md

@@ -0,0 +1,132 @@
+# Trace store contract
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.0).
+
+Clio's trace database is a rebuildable, queryable mirror. Receipts, session
+ledgers, gate artifacts, and evidence remain the source of truth. Removing
+`<state-dir>/trace.sqlite` loses no authoritative run data.
+
+## Connection and version contract
+
+The writer creates `trace.sqlite` beside the other machine-produced state and
+opens every writable connection with:
+
+```sql
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA busy_timeout=5000;
+```
+
+Readers open SQLite in read-only mode and set `busy_timeout=5000`. They verify
+that `meta.schema_version` is exactly `1`; a missing or unknown version is an
+error. A read-only connection queries the existing journal mode but does not
+try to change it, because changing journal mode is a database write.
+
+## Tables
+
+The seven Clio trace tables are `runs`, `phases`, `events`, `envelopes`,
+`gate_results`, `agent_sessions`, and `processes`; `meta` carries the schema
+version. Runs use terminal run ids. Interactive session turns are also recorded
+as `runs` rows using `assignment_id = "session"`. A phase belongs to a run and carries its
+assignment/worker-facing name, kind, owner, attempt, timing, status, itemized
+token spend, optional itemized dollar spend, total dollar spend, and context
+occupancy. Missing historical or unavailable component costs are `NULL`, never
+zero.
+
+`events` is append-ordered by SQLite `rowid`. All events carry `run_id`,
+`phase_id`, `type`, `name`, `started_at`, and a bounded JSON payload. Only
+`tool_call` is a span: it has both `started_at` and `ended_at`; all other event
+types are point events with `ended_at IS NULL`. A real tool call is folded into
+one row keyed by its worker tool-call id. Its payload carries the readable tool
+name, arguments, bounded result snippet, success, duration, and agent.
+
+Gate checks are stored as `checks_json` arrays of `{item, ok, note}`. They are
+projected only from successfully parsed typed reviewer/judge results, never by
+scraping prose. Worker/model/session occupancy is mirrored in `agent_sessions`.
+`violations_json` is derived from failed checks. `processes.command` is a
+redacted display projection of the argv observed when a pid was registered;
+`command_digest` is the SHA-256 identity of the exact JSON-encoded argv.
+Consumers must compare the digest of the pid's current argv before ever
+signalling it; the trace CLI and UI are listing/read-only surfaces and never
+signal processes.
+
+## Polling contract
+
+Live and historical consumers use the same cursor query:
+
+```sql
+SELECT rowid, event_id, run_id, phase_id, parent_id, type, name,
+       payload_json, tokens, started_at, ended_at
+FROM events
+WHERE run_id = ? AND rowid > ?
+ORDER BY rowid
+LIMIT ?;
+```
+
+The limit is capped at 500. A consumer retains the highest returned `rowid` and
+passes it as the next cursor. A live view polls this query every 500 ms and
+drains additional pages without overlap. History performs the identical query
+at a slower cadence or only on demand. There is no ingest endpoint, push
+transport, WebSocket, replay mode, or separate backfill path.
+
+## Failure behavior
+
+The observability subscriber schedules each dispatch event onto a serialized,
+best-effort queue capped at 2,048 pending writes. Lifecycle, terminal,
+tool-span, attempt, and usage facts are retained; display-only progress may be
+dropped with a warning when the cap is full. SQLite work never runs in the
+worker event pump and never participates in receipt correctness.
+Write/open/schema failures emit one bounded `[clio:trace]` warning and degrade
+the mirror without failing the run. The Node.js `node:sqlite` `ExperimentalWarning` is suppressed by default via a scoped listener filter, which can be carved out by passing `--trace-warnings`. Domain shutdown prioritizes flushing trace
+writes before slower evidence builds.
+
+## CLI Commands
+
+The `clio-coder trace` command surfaces 6 subcommands for inspecting and querying the SQLite trace mirror:
+
+```bash
+clio-coder trace runs [--db PATH] [--limit N]
+clio-coder trace phases <runId> [--db PATH]
+clio-coder trace tail <runId> [--follow] [--db PATH]
+clio-coder trace procs <runId> [--db PATH]
+clio-coder trace sql <SELECT query> [--db PATH]
+clio-coder trace ui [--db PATH] [--port N]
+```
+
+`clio-coder trace --help` and every subcommand `--help` print usage and exit with code 0.
+
+### Database Resolution and Error Handling
+
+When resolving the SQLite database path:
+- **Default Database Path:** If `--db` is omitted and no database has been created yet, `clio-coder trace` prints an informational notice (`no trace database yet at <path>`) and exits cleanly with code 0.
+- **Explicit Database Path:** If an explicit `--db <path>` is specified but does not exist, `clio-coder trace` prints `error: trace database not found: <path>` and exits with code 1.
+
+### Subcommand Specifications
+
+1. **`runs`**: Lists recent dispatch runs from the trace store. `--limit` sets maximum rows (1 to 500, default 50). Formats status, start time, total tokens, total USD cost, and run ID.
+2. **`phases`**: Lists sequence phases for a designated `runId`. Displays status, attempt, owner, total tokens, USD cost, and phase name.
+3. **`tail`**: Displays append-ordered event rows for a designated `runId`. When `--follow` is specified, polls for new events every 500 ms until two consecutive idle polls observe a finished run status.
+4. **`procs`**: Lists orchestrator and worker process executions associated with a `runId`. Displays state (`live` or `ended`), PID, process kind, name, and command string.
+5. **`sql`**: Executes a single read-only `SELECT` or `WITH` SQL statement against the SQLite trace database. The subcommand enforces read-only access: queries containing semicolons or data mutation keywords (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, etc.) are rejected with exit code 2. BigInt numbers in result objects format as JSON strings.
+6. **`ui`**: Launches the web-based interactive trace viewer server on the specified `--port` (default 0). This subcommand requires a source checkout containing `apps/trace-viewer/server.mjs`.
+
+### Trace Viewer Surface
+
+The viewer binds to `127.0.0.1` only and serves a read-only JSON API beside the static page:
+
+| Endpoint | Source |
+| --- | --- |
+| `GET /api/health` | Schema version handshake. |
+| `GET /api/runs[?limit=N]` | `runs`, newest first. |
+| `GET /api/runs/:runId` | One `runs` row. |
+| `GET /api/runs/:runId/phases` | `phases`, ordered by `seq`. |
+| `GET /api/runs/:runId/events[?after=cursor&limit=N]` | `events` by rowid cursor, capped at 500 per page. |
+| `GET /api/runs/:runId/gates` | `gate_results`. |
+| `GET /api/runs/:runId/envelopes` | `envelopes`. |
+| `GET /api/runs/:runId/processes` | `processes`. |
+| `GET /api/runs/:runId/receipt` | Sidecars beside the database: `<stateDir>/receipts/<runId>.json` and the matching `<stateDir>/evidence-index.json` row. |
+
+The receipt endpoint derives `<stateDir>` from the directory holding the trace database, since `clio-coder trace ui` reads `<stateDir>/trace.sqlite`. A mirror copied away from its state directory has no sidecars, so a missing, unreadable, or malformed file yields a `null` half with HTTP 200 rather than an error. The response drops `output`, `upstreamResponses`, `routeDecision`, `briefing`, and `steering`: the panel renders provenance, not transcripts.
+
+The run page renders the task request, wall-clock duration, phase description, failure reason and retry count, a chronological log of every event type with its payload, gate verdicts and violations, the run's processes, and a receipt panel covering outcome, verification state and basis, spend, per-tool call statistics, safety counters, findings, and build provenance. Fields the harness never sealed read as absent rather than as zero.

package/docs/troubleshooting.md

@@ -0,0 +1,33 @@
+# Troubleshooting & Error Remediation
+
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.0`.
+
+---
+
+## Error Catalog & Remediation Matrix
+
+| User-Facing Error / Notice | Cause | Actionable Remediation |
+| :--- | :--- | :--- |
+| `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
+| `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
+| `error: trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`). |
+| `no local skill marketplace catalog or index configured` | Neither a local `skills/` catalog directory nor a valid JSON index at `CLIO_CODER_SKILL_MARKETPLACE_INDEX` was found. | Point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json` file or install a skill directly via `clio-coder skills install <path\|github-url>`. |
+| `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--cwd`, `--config-dir`, or `--state-dir`) was placed after the subcommand name. | Move the flag before the subcommand name (e.g. `clio-coder --cwd /path run ...` instead of `clio-coder run --cwd /path ...`). |
+| `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add <id> --runtime <type> --base-url <url>`. |
+| `budget: ceiling must be >= 0 (got <val>)` | An invalid negative budget ceiling was passed to the session or dispatch configuration. | Pass a non-negative USD budget value (e.g. `--budget-usd 5.0`). |
+| `worker_final_output_missing` | A worker process completed execution with exit code 0 but failed to emit a valid final answer before the stream closed. | Check the worker event log using `clio-coder trace tail <runId>` or inspect the receipt via `monitor(run_id="<id>", mode="receipt")`. |
+| `vram_capacity_fit_failure` | The model could not be scheduled or loaded due to insufficient GPU VRAM capacity on the target node. | Select a smaller quantized model variant, reduce context window size, or route to an alternative fleet node with greater memory capacity. |
+| `loop_guard_tools_disabled_exhausted` | The loop detector identified repeated unproductive tool calls with identical arguments and disabled tool execution. | Inspect model prompts and provide clearer intermediate steering instructions to prevent recursive tool loops. |
+| `Node.js ExperimentalWarning: SQLite is an experimental feature` | Node.js emitted an experimental feature warning for `node:sqlite`. | By default, Clio suppresses this warning via a scoped filter. If visible when running scripts directly, pass `--trace-warnings` to control diagnostics. |
+| `cwd-fallback: no-cwd / missing / not-a-directory` | The session recorded in `meta.json` points to a workspace directory that has been deleted, unmounted, or renamed. | When prompted by the `cwd-fallback` overlay, select a valid existing directory to re-anchor the session. |
+
+---
+
+## Diagnostic Commands
+
+When encountering unexpected system behavior:
+
+1. **System Health Check**: Run `clio-coder doctor` (or `clio-coder doctor --fix` to auto-repair state directory permissions and configuration defaults).
+2. **Target Connectivity Probe**: Run `clio-coder configure --probe` to verify authentication and reachability for all configured LLM providers.
+3. **Trace Store Inspection**: Run `clio-coder trace runs` and `clio-coder trace tail <runId>` to inspect event logs, durations, and tool outputs.
+4. **Receipt Validation**: Run `clio-coder evidence inspect <runId>` or `/view verify <runId>` to check cryptographic integrity and execution telemetry.

package/docs/tui-design.md

@@ -0,0 +1,239 @@
+# Clio TUI Design System
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.0).
+
+This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
+
+The governing principle: **the user reads state from color, structure from frames, and identity from brand marks.** Everything that is not state or structure remains visually quiet.
+
+---
+
+## 1. Color System
+
+All color styling is defined in [src/interactive/theme/tokens.ts](../src/interactive/theme/tokens.ts). No raw SGR sequences, `38;2;`/`38;5;` ANSI escape fragments, or hardcoded hex colors are allowed outside this theme module.
+
+### 1.1 Color Tokens
+
+| Token | Value (truecolor) | Role |
+|---|---|---|
+| `accent` | `rgb(70, 229, 208)` (Teal) | Brand and interactivity: frame titles, selection highlight, keybinding/slash-command affordances, agent voice glyphs, tool verbs, and active/writing phases. |
+| `accentDeep` | `rgb(31, 183, 166)` | Structural emphasis only: bold CAPS section tags. |
+| `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, and user-steering queues. |
+| `success` | `rgb(87, 227, 137)` (Green) | Positive outcomes: success indicators (`✓`), ok health status, clean git trees, and output-token count updates. |
+| `warning` | `rgb(255, 180, 84)` (Amber) | Real warnings only: stale data, dirty trees, retry status, blocked tools, and truncation. |
+| `error` | `rgb(255, 92, 102)` (Red) | Failures: error indicators (`✗`), error rails, stuck states, and error message text. |
+| `info` | `rgb(91, 168, 255)` (Blue) | Informational messages, notices, and system-prompt meters. |
+| `reason` | `rgb(157, 140, 255)` (Purple) | Reasoning-related status: thinking phases, thinking rails, reasoning-token metrics, and context compacting. |
+| `dim` | `rgb(106, 122, 133)` | Scaffolding elements: separators, key names, keyboard shortcut hints, durations, and timestamps. |
+| `muted` | `rgb(138, 153, 164)` | Secondary content: paths, previews, counts, and non-status values. |
+| `title` | alias of `accent` | Semantic title token mapping. |
+| `frame` | `rgb(47, 93, 90)` | Borders, rules, inner dividers, and unused context space. |
+| `frameStrong` | `rgb(42, 171, 158)` | The active editor input rail background. |
+
+### 1.2 Placement Rules
+
+- Color is used functionally to indicate state. If removing a color does not lose information, the text is colored using `dim`, `muted`, or left unstyled.
+- `warning` amber is reserved for true warnings. Costs and neutral telemetry numbers use `muted`.
+- `accentDeep` is used only in section tags. Metric values (such as TTFT, tokens-per-second, and autonomy status) use `muted`.
+- Per-surface color budgets limit noise: chip strips use at most one non-neutral token per chip, and framed cards use at most one status token alongside neutral colors.
+
+---
+
+## 2. Glyph Vocabulary
+
+All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src/interactive/theme/glyphs.ts). Rendering code reference these names instead of embedding hardcoded glyph literals.
+
+| Glyph | Name | Meaning | Used by |
+|---|---|---|---|
+| `>C_` | `brand` | Clio wordmark | Welcome header and dashboard header only. |
+| `✦` | `agent` | Agent voice | Chat reply prefix (accent; error red on failed turns). |
+| `›` | `user` | User voice | Chat user prefix (accent); steering queue marker (action). |
+| `❯` | `cursor` | Selection focus | Settings, list overlays, selectors. |
+| `▸` | `toolHeader` | Tool ledger line | Tool sublines and expanded tool headers. |
+| `✓` | `ok` | Success | Everywhere. |
+| `✗` | `error` | Failure | Everywhere. |
+| `⊘` | `cancelled` | Cancelled or aborted | Everywhere. |
+| `⚠` | `warn` | Warning block | Notices, stuck phase. |
+| `!` | `warnInline` | Inline warning mark | Git dirty, stale rows, fleet row warnings. |
+| `ℹ` | `info` | Informational notice | Notification surfaces. |
+| `●` | `running` | Live run (static form) | Dispatch rows when not animated, health ok. |
+| `◌` | `queued` | Queued or idle | Queued dispatch rows, idle phase. |
+| `⣾⣽⣻⢿⡿⣟⣯⣷` | `SPINNER_FRAMES` | Live activity | Phase pill and running dispatch rows. |
+| `◔ ◐ ◑` | `phaseWaiting/phaseThinking/phaseWriting` | Turn progression | Phase pill. |
+| `⚙` | `phaseTool` | Tool executing | Phase pill. |
+| `⏸` | `phaseBlocked` | Awaiting confirmation | Phase pill. |
+| `↻` | `phaseRetry` | Retrying | Phase pill, retry notices. |
+| `♻` | `phaseCompact` | Compacting | Phase pill. |
+| `⇲` | `phaseDispatch` | Dispatching (action orange) | Phase pill. |
+| `↑ ↓` | `up/down` | Input and output tokens; scroll | Everywhere. |
+| `⚡` | `speed` | Throughput | Everywhere. |
+| `▰ ▱` | `contextFull/contextFree` | Context meter cells | Meters. |
+| `▒` | `contextReserve` | Autocompact reserve cells | Context meters. |
+| `█ ░` | `barFull/barEmpty` | Wide-glyph fallback | Meters. |
+| `│` | `rail` | Body rail and section bar | Tool bodies, thinking rail, column separators. |
+| `─` | (rules) | Horizontal rule and borders | Frames and rules. |
+| `╌` | `innerDivider` | Divider inside a frame | Task island, any framed list. |
+| `·` | (dotSep) | Chip separator (dim) | Everywhere. |
+| `◆ ◇` | `active/scoped` | Active and scoped marks | Model selector, thinking selector. |
+
+---
+
+## 3. Formatting Rules
+
+Standardized formatters live in [src/interactive/theme/labels.ts](../src/interactive/theme/labels.ts) and other shared UI modules:
+
+- **Duration**: `formatCompactMs` is the unified duration formatter, yielding compact outputs (`860ms`, `4.2s`, `42s`, `1m36s`).
+- **Token Counts**: `formatFooterTokens` formats footer and chip counts (`842`, `12.4k`, `1.2M`). Full numeric strings via `toLocaleString` are reserved for detailed tables like the context legend.
+- **Cost**: The shared `formatUsd` formatter handles dollar values, printing up to four decimal places when under one cent.
+- **Model IDs**: `abbreviateModelId` keeps whole dash-separated parts of model names up to 18 characters; if the parts still overflow, it clips the ID at 18 characters.
+
+---
+
+## 4. Structural Layouts
+
+### 4.1 The Island (Framed Block)
+
+Rendered via `frame()` in [src/interactive/theme/rules.ts](../src/interactive/theme/rules.ts):
+
+```
+┌─ Title ──────────────────────────── meta ─┐
+│ body line                                 │
+│ body line                                 │
+└───────────────────────────────────────────┘
+```
+
+- Corners and borders use `frame`.
+- `Title` is written in bold `title` color, padded with exactly one space on each side.
+- The right-aligned `meta` field is drawn in `dim` color before the closing corner.
+- Body rows use the vertical rail `│` with one space of padding.
+- Inner dividers use `╌` in `frame` color.
+
+### 4.2 The Overlay
+
+Overlay frames share the island's top border rules and include keyboard shortcut hints in the bottom border:
+
+```
+└─ [Tab] mode · [Esc] close ─────────────────┘
+```
+
+### 4.3 Section Headers
+
+- **Panel Section Tag**: Bold CAPS in `accentDeep`.
+- **List Group Header**: A leading rule followed by the label, e.g. `── Label` in `dim`.
+
+### 4.4 Key-Value Rows
+
+Drawn as `<key padded, dim> <value>`, where the value defaults to `muted` unless a semantic token applies.
+
+### 4.5 The Status Pill
+
+```
+<spinner|glyph> <label> [ · badge]
+```
+
+- For active phases, the animated spinner frames replace the static phase glyph.
+- Spinner, glyph, and label all use the current phase's token color.
+- Badges are separated by dim dots: `· fleet 2` (action), `· tools 1` (muted).
+
+### 4.6 Narrow Terminal Behavior
+
+All TUI overlays and cards support compact widths down to 40 columns:
+- Split overlays such as `/view` fall back to a single pane layout with `[Tab]` switching between the artifact list and details.
+- Keybinding hints, cards, and markdown detail text wrap fluidly without horizontal clipping.
+
+
+---
+
+## 5. State Choreography
+
+The Clio screen maintains a fixed structure: banner, transcript, editor rail, and footer. State is signaled through the status pill in the footer and matches the following table:
+
+| State | Pill | Transcript Echo | Action Orange? |
+|---|---|---|---|
+| idle | `◌ idle · tools none` (muted) | None; last-turn telemetry on line 2 | No |
+| preparing / waiting | spinner + `waiting` (info) | None | No |
+| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)...` marker | No |
+| writing | spinner + `writing` (accent) | Streaming markdown text | No |
+| tool running | spinner + `tool <name>` (accent) | `▸` tool execution ledger line | No |
+| blocked | `⏸ blocked` (warning) | Permission prompt surface | No |
+| retrying | `↻ retry 2/5` (warning) | Dim retry details line | No |
+| compacting | spinner + `compacting` (reason) | None | No |
+| dispatching / fleet live | spinner + `dispatch` (action) | Task island status updates | Yes |
+| stuck | `⚠ stuck 12s` (error) | Inline watchdog warning | No |
+| done | `✓ done` (success), then telemetry | Settled transcript blocks | No |
+
+---
+
+## 6. Agent and Transcript Formatting
+
+### 6.1 Voices
+- **User**: `› text` with the user glyph in `accent`.
+- **Agent**: `✦ text` with the agent glyph in `accent` (turning `error` red on failed turns, along with the text message).
+
+### 6.2 Thinking Blocks
+Drawn as a folded dim marker (`Thinking (N tokens)...` or `Thinking...`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
+
+### 6.3 Tool Ledger
+Tool lines wrap as a single composed block:
+```
+▸ verb object · resource · facts · size ✓ · 230ms · full: path (ctrl+o)
+```
+- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end.
+
+### 6.4 Editor Rail
+The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), and `medium` and above (purple `reason`).
+
+### 6.5 Transcript Notices
+Replay and system tags (e.g. `[retry]`, `[model]`) are wrapped in `dim` brackets with a `muted` message. Retry tags use `warning` amber.
+
+### 6.6 Code Ink (Syntax Highlighting)
+
+Syntax highlighting within code blocks is handled by [src/interactive/renderers/code-ink.ts](../src/interactive/renderers/code-ink.ts). It maps a restricted set of four tokens to stay quiet:
+
+- **Comments**: `dim`
+- **String Literals**: `success`
+- **Language Keywords**: `reason`
+- **Numeric Literals**: `info`
+
+All other code elements (identifiers, types, function names, punctuation) remain plain. Diff blocks highlight added lines with `success` green and removed lines with `error` red.
+
+---
+
+## 7. v0.2.9 TUI & Cost Provenance Transformations
+
+### 7.1 Fleet Visibility Across Surfaces
+- **Dispatch Board**: Displays per-run status cards with node assignments (`local` vs remote node ID), reroute badges, gate indicators (`gate reviewer c2`), live tool activity, and context occupancy meters.
+- **`/fleet` Overlay**: Modal overlay allowing operators to view running dispatches, inspect node capabilities, edit profile node pins, and monitor worker heartbeats.
+- **Parked Tools & Approvals**: Parked tool calls awaiting permission are rendered as `⏸ awaiting approval` with explicit approval prompts. Input overlays stay modal during active runs so background completions do not displace open dialogs.
+
+### 7.2 Cost Provenance & Evidence Rendering
+- **Session vs Run Provenance**: The Activity footer renders session token/cost totals, while the dispatch board and `/fleet` overlay render per-run worker tokens and cost with `known`, `estimated`, or `unknown` provenance markers. The current surfaces do not present a separate orchestrator-versus-worker algebra.
+- **Proof Markers**: Dispatch cards and `/fleet` rows render evidence readiness as `proof` markers (`pending`, `ready`, or `failed`) from the observability projection. Model-facing dispatch and monitor output use `receipt_integrity=verified/v15/sha256` and a separate `evidence_verification` label; the TUI does not emit a `[VERIFIED_RECEIPT_OK]` badge.
+
+---
+
+## 8. Shared Vocabulary
+
+One quantity gets one word, and every surface that shows it uses that word. A user comparing the transcript, the footer, and an overlay is checking whether Clio is telling a consistent story; a synonym reads as a discrepancy. `tests/contracts/usage-vocabulary.test.ts` holds the pairs that had drifted.
+
+| Concept | Word | Surfaces |
+| --- | --- | --- |
+| One model API call | `call` | Chat panel `turn · in N over M calls`, `/cost` `model calls`, `/cost` `(avg/call …)` |
+| One user-to-assistant exchange | `turn` | Chat panel `turn · …`, `/cost` `turns` |
+| Provider-reported reasoning tokens | `reasoning N provider` | Chat panel |
+| Reasoning tokens estimated from displayed text | `reasoning ≈N estimated` | Chat panel; the footer carries the same `≈` on `r≈N` |
+| Reasoning tokens in the cost tally | `reasoning N provider-reported only` | `/cost`. This tally never estimates, so it disagrees with the panel on a model that reports nothing, and the row says which one it is. |
+| Thinking level a model cannot turn off | `forced` | Editor rail, model overlay, thinking cycle (`thinkingLevelDisplayWord`) |
+| Thinking level on a model with only on and off | `on` / `off` | Same surfaces |
+
+### 8.1 Slash-Command Failures
+
+Two shapes, both ending at something the user can act on.
+
+- A command that exists but was called wrongly prints the reason and then that command's usage line: `<reason>. usage: /<name> …`.
+- A command-shaped token that is not a command prints `/<token> is not a command. Type /help for the list.` and is never sent to the model as chat. The escape for a line that starts with a slash is a leading backslash, so `\/tmp is full` reaches the model as `/tmp is full`. A leading space does not work and never did, because the editor trims the submitted line before the parser sees it.
+
+### 8.2 Memory Step Rows
+
+`/memory` activity rows read `<trigger> <decision> <reason>`, followed by `<N>w` when the step wrote to the bank and `<N> cited` when it cited entries, then the tier and latency. `describeTaskMemoryActivity` is the one place that builds this string.