@iowarp/clio-coder 0.3.3 → 0.3.6

package/docs/tool-usage.md

@@ -1,11 +1,11 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.6).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.3.3, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In Clio Coder v0.3.6, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
@@ -21,7 +21,7 @@ Truncated text results append exactly one notice line:
 
 Segments that do not apply are omitted. `<total>` renders as `N+` when the search stopped early at its item limit, so the true total was never counted. `next:` is an exact argument fragment (for example `limit=200` or `offset=451`); re-issue the same call with that argument changed to continue.
 
-Offload: when the byte cap cut content that was already collected, the complete rendering is written to `<clio-coder state dir>/scratch/<sessionId>/<toolCallId>.txt` and the notice's `full:` segment names the path. Read it with `read` using offset/limit. Tools offload only when the byte cap cut collected content; a bare item-limit truncation continues via `next` and does not offload. `read` never offloads, because the source file is directly re-addressable via `offset`.
+Offload: when the byte cap cut content that was already collected, the complete rendering is written to `<clio-coder state dir>/scratch/<sessionId>/<sha256 of the captured text>.txt` and the notice's `full:` segment names the path. Read it with `read` using offset/limit. Tools offload only when the byte cap cut collected content; a bare item-limit truncation continues via `next` and does not offload. `read` never offloads, because the source file is directly re-addressable via `offset`.
 
 JSON-format results (code_nav, context scope=docs/workspace) never get an appended notice. An oversize JSON payload is replaced whole by the parseable stub `{"error":"result exceeded <cap>","offloadPath":"...","next":"..."}` so the model never receives JSON cut mid-document. Empty results are also valid JSON with empty arrays and `next` populated.
 
@@ -102,17 +102,24 @@ Arguments:
 - `command` (required).
 - `cwd` (optional). Working directory; resolved against the session workspace and rejected when it escapes it. The safety net blocks an escaping cwd at admission, and the tool enforces the same rule itself.
 - `timeout_ms` (optional). Default 300000 (5 minutes).
+- `output_policy` (optional). Canonical model-context disposition: `full`, `bounded`, `summary`, or `metadata-only`. Omission is exactly `bounded`.
 
 Workspace containment: commands whose filesystem targets resolve outside the session workspace escalate to `system_modify` and ask for one-shot confirmation at every autonomy level (headless runs deny asks). Recognized targets are shell redirects, `tee`/`mkdir`/`touch` path operands, `cp`/`mv`/`ln` destinations, in-place `sed -i` operands, and any `cd`/`pushd` whose directory leaves the workspace, since a `cd` outside re-bases every relative path that follows it. Inside-workspace equivalents stay plain `execute` with no new prompts.
 
-Output shaping is tail-biased: the display keeps the LAST 16KB / 2000 lines, because the failing assertion, compiler error, and exit summary live at the end. Before truncating, the full output is spilled to the per-session scratch file and the appended note names the path; read it with offset/limit. A command producing more than 16MB of output is stopped with an error. A timeout or nonzero exit returns the shaped output plus a status line (`bash: command timed out after <ms>ms`, `bash: command failed (exit N)`).
+The default `bounded` policy keeps a tail-biased model excerpt under the 16KB result budget, because the failing assertion, compiler error, and exit summary usually live at the end. `summary` is useful for noisy builds and test runs: code deterministically selects a bounded head, tail, and error-like lines, applies Clio's repository secret redactor, and records the source hash and algorithm in summary provenance. `metadata-only` is appropriate when the model needs only outcome and termination facts; stdout and stderr stay out of model context while the operator presentation, retained byte size, and retrieval path remain available. `full` is for output known to be small. It is admitted only when the complete captured result and its facts fit the bounded result/context budget; otherwise the result explicitly records a typed downgrade to tail-biased `bounded` and provides retrieval. Do not use `full` as the routine default.
 
-Reach for bash for builds, git, package managers, and anything without a dedicated tool. Prefer the dedicated tools over their shell equivalents: grep/find/read/ls get envelope truncation, exact continuation hints, and the shared ignore policy that `cat`, shell `grep`, and shell `find` do not. Prefer `verify` over bash for declared package.json verification scripts, since verify produces typed evidence.
+Presentation is independent from model context. The operator-facing display remains folded and tail-biased under every policy. When the display or selected context omits captured content, the terminal result writes one per-session scratch artifact and names it in the result. Live updates use the selected policy, remain bounded, and never write per-update artifacts. Every terminal result records requested and applied context modes, captured/displayed/context bytes, truncation or downgrade state, and any offload path. Exit code, signal, timeout, abort, and output-cap facts survive every policy. Scratch retrieval may contain the raw retained output; the deterministic `summary` projection is the redacted surface.
+
+A command producing more than 16MB of combined output is stopped with an error. UTF-8 decoding spans process chunks, and a code point split by the hard byte cap is discarded rather than replaced with an invalid character. Raw NUL bytes are removed from model context under every policy, which leaves multi-byte code points and ANSI escape sequences whole; the operator presentation and the scratch artifact keep the captured bytes, and the result still records the omission and its retrieval path. A timeout, abort, output cap, or nonzero exit preserves captured diagnostics and appends a status line such as `bash: command timed out after <ms>ms` or `bash: command failed (exit N)` before canonical shaping.
+
+Reach for bash for builds, git, package managers, and anything without a dedicated tool. Prefer the dedicated tools over their shell equivalents: grep/find/read/ls get envelope truncation, exact continuation hints, and the shared ignore policy that `cat`, shell `grep`, and shell `find` do not. Prefer `verify` over bash for declared package scripts and project-catalog entries, since verify produces typed evidence.
 
 ```text
 bash(command="git status --short")
 bash(command="git log --oneline -10")
 bash(command="npm run build", timeout_ms=600000)
+bash(command="npm run test", timeout_ms=600000, output_policy="summary")
+bash(command="make artifact", output_policy="metadata-only")
 ```
 
 ## grep: search file contents with ripgrep
@@ -266,27 +273,87 @@ dispatch(tasks=["Refactor step 1", "Refactor step 2"], mode="sequential", timeou
 
 ## verify: run declared verification checks
 
-One EXECUTE entry point for declared verification. Sources: `src/tools/verify/index.ts`, `src/tools/verify/scripts.ts`, `src/tools/verify/frontend.ts`.
+One EXECUTE entry point for declared verification. Sources: `src/tools/verify/index.ts`, `src/tools/verify/catalog.ts`, `src/tools/verify/scripts.ts`, `src/tools/verify/authoring.ts`, `src/tools/verify/frontend.ts`.
 
 Arguments:
 
-- `check` (optional). A declared package.json script name or `"frontend"`. Omit to list available checks.
+- `check` (optional). A declared project-catalog ID, package.json script name, or `"frontend"`. Omit to list available checks.
 - `path` (check=frontend). Artifact file under the workspace root.
-- `args` (optional). Extra arguments passed to the script after `--`. A JSON-string array is tolerated and parsed.
+- `args` (package scripts only). Extra arguments passed after `--`. A JSON-string array is tolerated and parsed. Project-catalog checks ignore this field.
 - `browser` (check=frontend). `auto` (default), `required`, or `off`.
-- `cwd` (optional). Working directory.
-- `timeout_ms` (optional). Default 120000.
+- `cwd` (package scripts only). Package working directory. Project catalogs are always discovered at the session workspace root, and a project check uses its declared `cwd`.
+- `timeout_ms` (package scripts and frontend only). Default 120000. A project check uses its declared `timeoutMs`.
+- `max_output_bytes` (package scripts and frontend only). Default 600000. Project checks retain the safe-exec default cap.
+
+`verify()` lists checks grouped as `package.json` and `.clio-coder/verifiers.yaml`. Both providers project through the same canonical metadata: `{id, description, command, cwd, timeoutMs, tags, source}`. Package scripts must match the verification family `test*/lint*/build*/typecheck*/check*/format*/ci*` (a family prefix, optionally followed by `:`, `.`, or `-` and a suffix, e.g. `test:unit`). `verify(check="typecheck")` runs `npm run typecheck` through the safe-exec spine with no shell. A package script name outside the family is rejected with a pointer to run it through bash.
+
+### Project verifier catalog
+
+Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
+
+```yaml
+version: 1
+checks:
+  - id: rust-workspace
+    description: Run the Rust workspace tests
+    command: [cargo, test, --workspace]
+    cwd: .
+    timeoutMs: 600000
+    tags: [rust, test]
+```
+
+Version 1 is strict. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
+
+Provider IDs share one namespace. If a catalog ID collides with a discovered package script, listing and execution fail and identify both source files. Catalog parsing also fails closed before any package or project check runs.
+
+`verify(check="rust-workspace")` spawns exactly `cargo` with `test` and `--workspace`; it does not interpolate model text or invoke a shell. Model-supplied `args`, `cwd`, `timeout_ms`, `max_output_bytes`, or undeclared environment fields cannot widen or replace the catalog entry. Safe execution passes only Clio's small environment allowlist, applies cancellation and the declared timeout, and shapes output at the standard 600000-byte cap. Execution details retain the compatible command string plus exact `argv`, `cwd`, `exitCode`, `durationMs`, `aborted`, `timedOut`, and `outputCapped` evidence, along with the check's declared source, command, cwd, timeout, description, and tags.
+
+### Guided catalog authoring
+
+An empty `verify()` result points to `clio-coder verifiers author`. The authoring command inspects only command-bearing files at the workspace root:
+
+- verification-family package scripts, projected exactly as `npm run <script>` and shown as already active rather than duplicated into the catalog;
+- `Cargo.toml`, projected to Cargo's package or workspace test vector;
+- visible build and test entries in `CMakePresets.json`, projected to the corresponding `cmake --build --preset` or `ctest --preset` vector;
+- declared Python runners in `pyproject.toml`, `pytest.ini`, `tox.ini`, `noxfile.py`, or the pytest section of `setup.cfg`;
+- a module directive in `go.mod`, projected to `go test ./...`;
+- top-level `validators` entries in the documented YAML scientific-validation files.
+
+Every proposal records its source path and location and labels the command origin as `project-declared` or `toolchain-defined`. Project-declared examples include a package script, a Python entry point, and an exact validation-contract command. Toolchain-defined examples include Cargo's test command, a named CMake preset invocation, a configured Python runner, and Go's module test command. Validation command strings are converted to argv only when their quoting is complete and they contain no shell operators, expansion, redirection, or environment assignment. Ambiguous entries and `VALIDATION.md` prose receive a manual-entry diagnostic. Directory names such as `build`, `tests`, `python`, or `cargo` never imply a command.
+
+`discover` and every mutating command first print an authority preview. Each check shows the destination or active source path, source provenance, exact JSON argv vector, repository-relative cwd, timeout, tags, and effective execution authority. Preview and discovery do not create `.clio-coder`, write a file, or run a check. A mutating command without `--yes` ends after the preview. Repeating the reviewed command with `--yes` is the explicit write decision; the serialized YAML must pass the production catalog parser before the atomic write is reachable.
+
+```text
+clio-coder verifiers discover
+clio-coder verifiers author
+clio-coder verifiers author --exclude cmake-build-debug --rename go-test=go-suite
+clio-coder verifiers author --dry-run go-suite --yes
+clio-coder verifiers validate
+```
+
+`validate` reads the committed file with the same parser used by `verify()`. `dry-run <id>` is an explicit request to execute one admitted check through the production `verify` path. `author --dry-run <id> --yes` writes only after confirmation and starts the selected dry run only after the write is accepted by production discovery.
+
+Later changes use the same preview and confirmation boundary. `edit` preserves the ID unless `rename` is requested. Renames and additions reject collisions with catalog IDs and active package-script IDs. Removals state that the deleted command will no longer be executable through catalog authority. Generated IDs are stable for a stable ordered signal set; a collision receives the first available deterministic `-2`, `-3`, and later suffix.
+
+```text
+clio-coder verifiers add --id validate-grid --description "Validate the regional grid" --command '["python","tools/check_grid.py","out/region_west.nc"]'
+clio-coder verifiers add --id validate-grid --description "Validate the regional grid" --command '["python","tools/check_grid.py","out/region_west.nc"]' --tags scientific,netcdf --yes
+clio-coder verifiers edit validate-grid --timeout-ms 300000
+clio-coder verifiers rename validate-grid validate-regional-grid --yes
+clio-coder verifiers remove validate-regional-grid --yes
+```
 
-`verify()` with no check lists declared checks grouped by source; today the only source is package.json scripts whose names match the verification family `test*/lint*/build*/typecheck*/check*/format*/ci*` (a family prefix, optionally followed by `:`, `.`, or `-` and a suffix, e.g. `test:unit`). `verify(check="typecheck")` runs `npm run typecheck` through the safe-exec spine with no shell; output is capped at 600000 bytes and `details = {command, cwd, exitCode, durationMs, timedOut, outputCapped}`. A script name outside the family is rejected with a pointer to run it through bash.
+The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority.
 
 `verify(check="frontend", path=<file>)` validates an HTML, CSS, or JavaScript artifact without shell access. The path must stay inside the workspace root and end in `.html`, `.htm`, `.css`, `.js`, `.mjs`, or `.cjs`. Checks per type: HTML tag balance (comment-aware, HTML5 optional end tags honored), inline and referenced script syntax (classic scripts parsed in-process, modules via `node --check`), inline and linked CSS brace/string/comment balance, local script and stylesheet references resolved and existence-checked (external and root-relative references are skipped), and an optional headless browser load. `browser="auto"` warns when no chromium/chrome/edge executable is on PATH, `"required"` fails, `"off"` skips. Each check reports pass, warn, fail, or skip; any fail makes the whole result an error. `details = {action: "verify", check: "frontend", path, browserMode, status, checks}`.
 
-Prefer verify over bash for the verification family: the typed result feeds the finish contract as validation evidence.
+Prefer verify over bash for the verification family and project catalog: the typed result feeds the finish contract as validation evidence.
 
 ```text
 verify()
 verify(check="typecheck")
 verify(check="test", args=["tests/contracts/dispatch.test.ts"])
+verify(check="rust-workspace")
 verify(check="frontend", path="site/index.html", browser="off")
 ```
 

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # 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.3).
+> **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.6).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # 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.3`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.6`.
 
 ---
 

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # 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.3).
+> **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.6).
 
 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/).
 
@@ -36,7 +36,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 - Color is used functionally to indicate state. If removing a color does not lose information, the text is colored using `dim`, `muted`, or left unstyled.
 - `warning` amber is reserved for true warnings. Costs and neutral telemetry numbers use `muted`.
 - `accentDeep` is used only in section tags. Metric values (such as TTFT, tokens-per-second, and autonomy status) use `muted`.
-- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting or a prompt owns the keyboard (e.g. running connect/probe operations, active dispatch/fleet execution, or the keyboard-owning confirmation border / `STEER` mode). It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region.
+- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting, for workspace-authority and worker-escalation decision frames, or in `STEER` mode. It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region. Outward, safety-net, and system decision frames use `warning`; conversational answers use `accent`.
 - 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.
 
 ---
@@ -118,6 +118,8 @@ Overlay frames share the island's top border rules and include keyboard shortcut
 └─ [Tab] mode · [Esc] close ─────────────────┘
 ```
 
+Fleet run cards add two bounded budget rows when native dispatch admission supplies an envelope. The `policy` row shows the recipe default or exact pin, its optional maximum, and the invocation request. The `budget` row shows the effective phase, the operator lifetime cap, and the clamp or retry/revision escalation reason. Historical or external-agent rows without this provenance omit both rows.
+
 ### 4.3 Section Headers
 
 - **Panel Section Tag**: Bold CAPS in `accentDeep`.
@@ -144,6 +146,21 @@ All TUI overlays and cards support compact widths down to 40 columns:
 - Keybinding hints, cards, and markdown detail text wrap fluidly without horizontal clipping.
 - Settings provides a dedicated drill-down stack below 72 columns.
 
+### 4.7 Decision Consequence Frames
+
+Permission confirmation and `ask_user` use one pure consequence presentation classifier while keeping separate input and execution protocols. The classifier supplies the tier title, semantic frame token, consequence and reversibility copy, requester attribution, and display actions. Permission keeps allow-once, deny, and stop behavior. `ask_user` keeps selection, free-text, cancellation, and its compact, panel, or interview layout chosen from question shape.
+
+| Tier | Title | Token | Plain-text identity |
+| --- | --- | --- | --- |
+| Conversation | `Answer a question` | `accent` | `Conversational answer` |
+| Workspace | `Approve workspace action` | `action` | `Workspace authority` |
+| Outward | `Confirm outward consequence` | `warning` | `Outward consequence` |
+| Safety net | `Safety-net confirmation` | `warning` | `Safety-net confirmation` |
+| System | `Approve system change` | `warning` | `System change` |
+| Worker | `Worker needs approval` | `action` | `Worker escalation` |
+
+The words carry the meaning when color is disabled. Permission copy states the exact one-shot authority, whether effects are reversible, the authenticated requester and axis, and what deny and stop do. The classifier never consumes question, reason, summary, option-label, or requested-title prose, so those strings cannot select or lower a tier.
+
 ---
 
 ## 5. Screen Surfaces & State Choreography
@@ -230,6 +247,7 @@ The collapsed form is one composed ledger line:
 - Expanded calls show the primary argument in the signature and every secondary argument as a typed field list. Multiline argument bodies become line and byte facts, nested objects retain structured rendering, and safety-sensitive values remain redacted.
 - Running calls label `live output` and replace the cumulative partial result in place. Settled calls label `output` and show available exit status, result or observation counts, line count, displayed and total byte sizes, truncation, timeout, tool-token usage, dynamically added tools, context exclusion, and the full-output path. A blocked or aborted admission instead labels its `decision` and does not claim that the tool ran.
 - A call parked for one-shot approval replaces its running timer with `awaiting approval` and shows the already-sanitized action class, asking safety axis, and target below the row. These facts are transient UI state: approval, denial, abort, or settlement clears them, and they are never reconstructed from the session ledger.
+- The live permission frame derives its consequence tier from those typed facts and the authenticated origin. It anchors at bottom center with five rows reserved for the composer and footer, and it recomputes that anchor on resize. Each queued frame retains its own tier and requester.
 - Text and image tool results keep their text while rendering images as MIME and byte-size placeholders; base64 image data is never written to the terminal.
 - Successful `edit` and `write` calls render the bounded diff produced by the tool result. Live regular-screen and fullscreen rows color removed and added lines with the `error` and `success` tokens and emphasize changed words; `/resume` replay and `/export` keep the same numbered diff as plain text.
 - Operator `!` and `!!` bash commands use the same running and settled block as model-initiated bash. The block appears before the process starts, streams the throttled cumulative stdout/stderr tail, and settles in place while the existing `bashExecution` session entry remains the durable record. `!!` continues to exclude that record from model context and says so in the block.
@@ -294,13 +312,22 @@ The `/settings` overlay is a full-screen transactional control center:
 - **Scoped Models Checklist**: Settings → `Models` provides a provider-backed checklist subview with target-level and target/model items, checked current selections, `Space` to toggle, and capability details in the inspector. Unresolved model references are preserved under an `Unavailable` group.
 - **Narrow Terminal Drill-Down Navigation**: Below 72 columns, Settings transitions from a split view to a modal drill-down stack (section list → section rows → detail drawer) with a breadcrumb and `Esc` moving up one level before closing. Includes `/` filtering across label, path, and description, narrowing per keystroke like `/model` and `/resume`. Below 60 columns, side margins are removed for full-width presentation.
 
-### 7.2 Task and Decision Boards
+### 7.2 Fleet Runs Board
+
+The `Alt+W` board renders one card per run. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
+
+- **`doing`**: the phase (`◐ thinking` in `reason`, `◑ writing` in `accent`, `⚙ tool` in `action`, `◔ waiting` in `info`) followed by the running call as `<tool> <verb> <object>`, or the last finished call as `last <tool> <verb> <object>`. The verb and object come from a descriptor composed at the worker seam; raw arguments never reach the renderer.
+- **`answer`**: the newest rows of the worker's bounded prose on a `│` rail with a hanging indent under the key, then a dim row naming the lines and bytes the bounds refused and the `/view dispatch:<runId>` deep link.
+
+Wrapping happens before the row cap, so the block is at most six rows tall at any width and a streaming answer cannot make the card grow under the operator. Detail follows the cursor rather than pinning to a run, and closing the board closes it. Reasoning text is never rendered; the `thinking` phase word is the whole of what the board says about it.
+
+### 7.3 Task and Decision Boards
 
 - **Composite Tasks Board (`/tasks`, `Alt+B`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
 - **Settled Decisions Board (`/decisions`, `Alt+D`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
 - **Approved editor overrides**: `Alt+B` and `Alt+D` are deliberate application-input boundary overrides of Pi's editor word-back and word-delete chords. Clio routes them before the editor so the two global boards remain one chord away. They are explicit exceptions to the general rule that Clio app bindings avoid Pi editor reserves, and users may rebind the Clio actions in `settings.yaml`.
 
-### 7.3 Slash Autocomplete Command Palette
+### 7.4 Slash Autocomplete Command Palette
 - **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
 - **One Canonical Spelling**: Autocomplete, help, and parsing expose the same unique slash-command names; no alias rows compete with canonical commands.
 
@@ -330,3 +357,10 @@ Two shapes, both ending at something the user can act on.
 ### 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.
+
+Knowledge and procedural task-bank rows expose `p` to propose the selected
+entry for the active canonical repository and `g` to propose it globally.
+Global scope requires a second `g` press on the same entry after the warning
+line appears. Status rows are labeled private and neither action can promote
+them. Both actions create unapproved durable proposals, show the resulting
+memory ID, and leave approval to the separate reviewed memory lifecycle.

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.3).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.6).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
@@ -213,6 +213,16 @@ Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 1
 - **Strict Primitive Handling**: `undefined` object properties are omitted; non-finite numbers (`NaN`, `Infinity`) or `bigint` throw an explicit serialization error.
 - **Coverage**: Includes every current receipt field and reconstructible ledger field, including route intent/decision/quality, execution role, worker identity, result-contract conformance, node/reroute/gate/plan provenance, briefing, steering, and `outcomeCode`.
 
+Integrity is only the artifact-integrity axis of the canonical trust status.
+The other axes are validation grounding, independent review, context
+provenance, autonomy enforcement, and completion evidence. Sealing proves that
+the receipt matches its covered ledger facts; it does not verify correctness,
+establish context authorship, turn a correlated review into an independent
+one, or prove completion. Every non-absent canonical fact retains a named
+source and authority plus bounded references to detailed artifacts. The full
+state vocabulary and compatibility map are documented in
+[`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
+
 ### 5.3 Acceptance Coverage
 
 The assignment contract's acceptance scenarios map to deterministic contract

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.3",
+	"version": "0.3.6",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -76,8 +76,7 @@
 		"test:file": "node --import tsx --import ./tests/harness/tmp-root.ts --test",
 		"pretest": "test -f dist/assets/codewiki.json && [ -z \"$(find src -newer dist/assets/codewiki.json -type f -print -quit)\" ] || npm run build",
 		"test": "node scripts/shard-tests.mjs",
-		"test:coverage": "node scripts/test-coverage.mjs --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/*.d.ts' 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts'",
-		"test:repeat": "node tests/harness/repeat-tests.mjs",
+		"test:repeat": "node scripts/repeat-tests.mjs",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
 		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
@@ -86,15 +85,15 @@
 		"prepublishOnly": "npm run ci:release",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
-		"//": "below here: real providers or a live model target, cost money and/or time, never run in CI",
-		"test:live": "node scripts/live-smoke.mjs",
-		"test:live-eval": "node scripts/live-eval-recon.mjs",
-		"test:live-eval:fleet-dispatch": "node scripts/live-eval-fleet-dispatch.mjs",
-		"test:live-verify:dispatch-routing": "node scripts/live-verify-dispatch-routing.mjs",
-		"test:lifecycle": "node --import tsx scripts/lifecycle-matrix.mjs",
-		"bench:swe": "python3 benchmarks/community/swe-bench-lite/swebench_clio.py",
-		"bench:scicode": "python3 benchmarks/community/scicode/scicode_clio.py",
-		"bench:tb": "python3 benchmarks/community/clio_fleet.py"
+		"benchmark:typecheck": "tsc -p benchmarks/tsconfig.json",
+		"benchmark:check": "npm run benchmark:typecheck && node --import tsx --test benchmarks/internal/tests/*.test.ts",
+		"benchmark:campaign": "node --import tsx benchmarks/internal/campaign.ts",
+		"benchmark:report": "node --import tsx benchmarks/internal/report.ts",
+		"//": "below here: a real model target, chosen with --target <id>; costs money and/or GPU time, never run in CI",
+		"live:smoke": "node --import tsx benchmarks/internal/live-smoke.ts",
+		"live:fleet-dispatch": "node --import tsx benchmarks/internal/live-fleet-dispatch.ts",
+		"live:tui": "node --import tsx benchmarks/internal/pty-drive.ts",
+		"live:home": "node --import tsx benchmarks/internal/live-home.ts"
 	},
 	"dependencies": {
 		"@anthropic-ai/claude-agent-sdk": "0.3.186",
@@ -103,7 +102,8 @@
 		"@earendil-works/pi-tui": "0.84.0",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"grok-mermaid": "0.2.2",
-		"ollama": "0.6.3"
+		"ollama": "0.6.3",
+		"smol-toml": "1.8.0"
 	},
 	"overrides": {
 		"@anthropic-ai/sdk": "0.105.0",

package/skills/meta/clio-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clio-test
 description: Use when writing or modifying Clio Coder's own source under src/, or verifying a change end-to-end against the real test harness. Covers the three real layers (contracts / smoke / boundaries), choosing which to run for a given change, the mock-provider and ACP-over-stdio harness, and the hot-reload dev loop for picking up latest code. Activate on any src/ edit, before declaring a change verified, or when asked whether Clio still works.
-version: 0.1.3
+version: 0.1.4
 license: Apache-2.0
 clio:
   registry-id: iowarp/clio-coder
@@ -24,17 +24,15 @@ local-vs-contribute boundary.
 ## Commands
 
 ```bash
-npm run typecheck         # tsc -p tsconfig.tests.json (includes tests/)
-npm run lint              # biome check .
-npm run check:boundaries  # import boundary rules (tsx, no build)
+npm run typecheck         # tsc -p tsconfig.tests.json (includes tests/ and benchmarks/internal/)
+npm run lint              # biome check . && scripts/check-hygiene.ts (import boundaries, skill pins, doc drift)
 npm run test:file -- 'tests/contracts/**/*.test.ts'  # contract tests (tsx, import src directly, no build)
 npm run test:file -- 'tests/smoke/**/*.test.ts'      # spawn dist/cli/index.js end-to-end (NEEDS a build)
 npm run test              # contracts + smoke, sharded across processes (the full gate)
 npm run build             # tsup -> dist/
 npm run dev               # tsup --watch -> rebuilds dist/ on save
 npm run ci                # typecheck && lint && skills:check && build && test && test:trace-viewer
-npm run test:live         # local live provider smoke; requires CLIO_CODER_LIVE_SMOKE=1
-npm run test:live -- --delegation  # adds local opencode/copilot ACP checks
+npm run live:smoke -- --target <id>   # one real turn against a configured target; never in CI
 ```
 
 ## Which layer catches what
@@ -44,7 +42,7 @@ npm run test:live -- --delegation  # adds local opencode/copilot ACP checks
 | pure logic in `src/domains/<x>/*.ts` | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | contract tests import `src` via tsx; no build |
 | dispatch / providers / prompts / safety / config / persistence / acp behavior | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | each has a file in `tests/contracts/` |
 | skills loader / activation | `npm run test:file -- 'tests/contracts/**/*.test.ts'` | `tests/contracts/skills.test.ts`, `skill-activation-compaction.test.ts` |
-| any `src/` import edit | `npm run check:boundaries` | enforces rule1/2/3 |
+| any `src/` import edit | `npm run lint` | the hygiene check enforces rule1/2/3 |
 | `src/cli/*` or `src/entry/*` user-facing flow | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke spawns the real `dist/cli/index.js` |
 | ACP surface (`src/cli/acp.ts`, engine ACP) | build, then `npm run test:file -- 'tests/smoke/**/*.test.ts'` | smoke drives `clio-coder acp` over JSON-RPC/stdio |
 
@@ -54,8 +52,9 @@ a single file.
 ## Boundary rules you must not break
 
 `tests/boundaries/check-boundaries.ts` enforces three rules (also the Hard
-Invariants in `CLIO-CODER.md`). If `npm run check:boundaries` reports a
-violation, fix the import — never silence the check:
+Invariants in `CLIO-CODER.md`), run by `scripts/check-hygiene.ts` under
+`npm run lint`. If it reports a violation, fix the import — never silence the
+check:
 
 - **rule1**: only `src/engine/**` may value-import `@earendil-works/pi-*`. Outside
   engine, use Clio contracts or type-only imports that erase at compile time.
@@ -70,9 +69,9 @@ There are two independent reload mechanisms; know which applies.
 
 **Source reload for tests.** This is the "pick up latest code" loop:
 
-- **Fast loop — no build.** The contracts glob and `check:boundaries` run
-  `node --import tsx --test` and import `src/**` directly, so they always run the
-  latest source with zero build step. Iterate here whenever the change is pure
+- **Fast loop — no build.** The contracts glob runs `node --import tsx --test`
+  and imports `src/**` directly, and the hygiene lint reads source statically,
+  so both always see the latest source with zero build step. Iterate here whenever the change is pure
   logic or a contract.
 - **Full loop — needs `dist/`.** The smoke glob spawns `dist/cli/index.js`, so it
   only sees code that has been built. Keep `npm run dev` (`tsup --watch`) running
@@ -98,7 +97,7 @@ restart the process (against a freshly built `dist/`).
 1. Write the change.
 2. `npm run typecheck` and `npm run lint`.
 3. Run the narrowest layer from the table above.
-4. `npm run check:boundaries` if you touched imports.
+4. `npm run lint` if you touched imports.
 5. If you touched CLI/entry/ACP: `npm run build` (or rely on `dev` watch), then
    `npm run test:file -- 'tests/smoke/**/*.test.ts'`.
 6. `npm run ci` before calling it done. Report exactly what ran and what is
@@ -113,8 +112,10 @@ node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
 
 ## What NOT to do
 
-- Don't reintroduce `tests/unit|integration|e2e/` or a pty harness — that
-  taxonomy was deliberately removed.
+- Don't reintroduce `tests/unit|integration|e2e/`; that taxonomy was
+  deliberately removed. Don't add a second pseudo-terminal: `tests/harness/pty.ts`
+  is the one PTY, used by the three `*-pty`/`tui-width-matrix` smoke suites and
+  by `benchmarks/internal/pty-drive.ts`.
 - Don't add `scripts/diag-*.ts` or `scripts/verify-*.ts`. A test belongs in
   `tests/`; a one-off probe belongs in `/tmp` and gets deleted (see
   `references/harness.md`).
@@ -126,5 +127,7 @@ node --import tsx --test --test-only tests/contracts/<file>.test.ts  # it.only
 
 ## Harness reference
 
-Driving the real CLI, the mock provider, and ACP over stdio, plus the throwaway
-probe pattern: **see `references/harness.md`**.
+Driving the real CLI, the mock provider, ACP over stdio, and the PTY, plus the
+throwaway probe pattern: **see `references/harness.md`**. Driving the real
+binary against a real model (headless, PTY, tmux, herdr) is a different claim
+and lives in `benchmarks/internal/SKILL.md`.

package/skills/meta/clio-test/evals.md

@@ -7,7 +7,7 @@ the gap (it cites the dead unit/integration/e2e taxonomy), then WITH it.
 Prompt: "I changed pure logic in `src/domains/dispatch/validation.ts`. What do I
 run and why?"
 Expected:
-- `npm run test:file -- 'tests/contracts/**/*.test.ts'` (and `check:boundaries` if imports changed).
+- `npm run test:file -- 'tests/contracts/**/*.test.ts'` (and `npm run lint` if imports changed).
 - Explains contracts import `src` via tsx, so no build is needed.
 - Does NOT suggest `test:unit` / `test:e2e` (those don't exist).
 
@@ -26,14 +26,14 @@ Expected:
   interactive testing. Distinguishes this from config hot-reload (classify.ts).
 
 ## T4 — boundary violation
-Prompt: "`check:boundaries` says a domain imports another domain's extension.ts.
+Prompt: "`npm run lint` says a domain imports another domain's extension.ts.
 Quickest fix?"
 Expected:
 - Route through the target domain's `index.ts` contract (rule3). Does NOT
   suggest a `biome-ignore` or exclude.
 
 ## Baseline failure modes to watch for (RED)
-- Cites `test:unit`/`test:integration`/`test:e2e` or a pty harness.
+- Cites `test:unit`/`test:integration`/`test:e2e`, or a PTY other than `tests/harness/pty.ts`.
 - Claims smoke tests run against source (they run against `dist/`).
 - Invents a hot-reload feature that reloads a running session's code.
 

package/skills/meta/clio-test/references/harness.md

@@ -1,18 +1,20 @@
 # Clio test harness reference
 
-How to drive the real Clio binary, a mock provider, and the ACP surface in
-tests. All of this is non-interactive — there is no pty harness in v0.2.2.
+How to drive the real Clio binary, a mock provider, the ACP surface, and a
+real pseudo-terminal in tests. Every model here is a stub; these are machinery
+tests. A run against a real model is `benchmarks/internal/SKILL.md`.
 
 ## Contents
 - The spawn harness (`runCli`, `makeScratchHome`)
 - Mocking a provider (OpenAI-compatible SSE fixture)
 - ACP over JSON-RPC/stdio
+- The PTY (`openPty`, `runInPty`)
 - One-off probes (no test file)
 
 ## The spawn harness
 
-`tests/harness/spawn.ts` is the only harness. It spawns `node dist/cli/index.js`,
-so **build first** (or keep `npm run dev` running) before `test:smoke`.
+`tests/harness/spawn.ts` spawns `node dist/cli/index.js` with piped stdio, so
+**build first** (or keep `npm run dev` running) before running smoke.
 
 ```ts
 import { makeScratchHome, runCli } from "../harness/spawn.js";
@@ -76,11 +78,38 @@ client (see `createJsonRpcProcessClient` in the smoke test): `initialize` →
 non-spec discriminator breaks strict clients like Zed, so the smoke test asserts
 every emitted variant is in the v1 set.
 
+## The PTY
+
+Piped stdio reports no terminal width and no TTY, so the TUI refuses to start
+and every width-sensitive path collapses to 80 columns. `tests/harness/pty.ts`
+opens a real pseudo-terminal through `node-pty` (a devDependency, never
+shipped):
+
+```ts
+import { openPty, runInPty, stripAnsi, visibleLines } from "../harness/pty.js";
+
+// Scripted: type on a schedule, stop when the output matches, bounded by a timeout.
+const run = await runInPty(process.execPath, [CLI], { cols: 120, rows: 40, cwd, env,
+  readyWhen: /ctx /, input: [{ afterMs: 200, data: "/quit\r" }], until: /bye/, timeoutMs: 20_000 });
+
+// Controllable: write, resize, pause output, wait for a matcher, wait for exit.
+const session = await openPty(process.execPath, [CLI], { cols: 140, rows: 44, cwd, env });
+await session.waitForOutput((out) => /ctx /.test(stripAnsi(out)), 30_000);
+session.write("/quit\r");
+await session.waitForExit(10_000);
+```
+
+Use it only for what a pipe cannot show: width, raw mode, SIGINT through a
+terminal, the alternate-screen and keyboard-protocol teardown. The three
+suites that need it are `tests/smoke/tui-width-matrix.test.ts`,
+`instant-shell-pty.test.ts`, and `render-trace-pty.test.ts`. Anything else
+belongs on `runCli`.
+
 ## One-off probes (no test file)
 
 To poke at Clio without writing a permanent test, drop a throwaway script in
-`/tmp` and run it with tsx. Delete it when done — never leave probes under
-`tests/` or `scripts/`.
+your scratch directory and run it with tsx. Delete it when done — never leave
+probes under `tests/`, `scripts/`, or `benchmarks/`.
 
 ```ts
 // /tmp/probe.ts

package/skills/meta/clio-test/references/test-map.md

@@ -1,4 +1,4 @@
-# Where Clio's tests live (v0.2.2)
+# Where Clio's tests live
 
 Three layers under `tests/`. Add a new test next to the closest existing file;
 create a new file only for a genuinely new domain cluster.
@@ -7,10 +7,17 @@ create a new file only for a genuinely new domain cluster.
 
 | Layer | Path | Runner | Build needed |
 |---|---|---|---|
-| contracts | `tests/contracts/*.test.ts` | `node --import tsx --test` | no (imports `src`) |
-| smoke | `tests/smoke/*.test.ts` | `node --import tsx --test` | **yes** (spawns `dist/`) |
-| boundaries | `tests/boundaries/*.test.ts` | `node --import tsx --test` | no |
-| harness (not a test) | `tests/harness/spawn.ts` | imported by smoke | — |
+| contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <glob>` (tsx + scratch root) | no (imports `src`) |
+| smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <glob>` | **yes** (spawns `dist/`) |
+| boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` (hygiene) | no |
+| harness (not tests) | `tests/harness/*.ts` | imported by contracts and smoke | — |
+
+The harness modules: `spawn.ts` (run the built CLI with pipes), `scratch-env.ts`
+(isolated Clio home), `pty.ts` (a real pseudo-terminal), `openai-compat-fixture.ts`
+and `fake-lmstudio-server.ts` (stub providers), `fake-ssh.ts` (stub fleet node),
+`clock.ts` (steppable clock), plus dispatch, receipt, and module-graph helpers.
+Everything under `tests/` stubs the model. Real-model runs are
+`benchmarks/internal/` and never run under `npm test`.
 
 ## Contract test files
 
@@ -33,18 +40,21 @@ create a new file only for a genuinely new domain cluster.
 | Area | File |
 |---|---|
 | non-interactive CLI + ACP-over-stdio end-to-end | `tests/smoke/cli.test.ts` |
-| import boundary rules (rule1/2/3) | `tests/boundaries/boundaries.test.ts` |
-| boundary checker implementation | `tests/boundaries/check-boundaries.ts` |
+| the package as installed from `npm pack` | `tests/smoke/pack-install.test.ts` |
+| TUI at real terminal sizes, NO_COLOR, Ctrl-C teardown (PTY) | `tests/smoke/tui-width-matrix.test.ts` |
+| instant shell before hydration, SIGTERM through the lease (PTY) | `tests/smoke/instant-shell-pty.test.ts` |
+| committed-frame render trace under PTY backpressure (PTY) | `tests/smoke/render-trace-pty.test.ts` |
+| import boundary rules (rule1/2/3), run under `npm run lint` | `tests/boundaries/check-boundaries.ts` |
 
 ## Running a subset
 
 ```bash
 # all contracts
-node --import tsx --test 'tests/contracts/**/*.test.ts'
+npm run test:file -- 'tests/contracts/**/*.test.ts'
 # one file
-node --import tsx --test tests/contracts/skills.test.ts
+npm run test:file -- tests/contracts/skills.test.ts
 # only it.only / describe.only within a file
-node --import tsx --test --test-only tests/contracts/skills.test.ts
+npm run test:file -- --test-only tests/contracts/skills.test.ts
 ```
 
 ## Writing tests