@iowarp/clio-coder 0.3.4 → 0.3.7

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.7).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.4, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.3.7, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 
@@ -40,6 +40,27 @@ The `system_modify` confirm is level-invariant, so it is enforced and attributed
 
 The level is persisted as `autonomy` in `settings.yaml`, hot-reloads, and is edited in the `/settings` Autonomy & Safety section.
 
+### Consequence tier is presentation, not authority
+
+Every operator decision also receives one closed consequence tier. The tier explains what the already-required decision can affect. It never decides whether a call runs, never changes the autonomy level, and never overrides a safety-net verdict. Registry admission still follows the enforcement path below before any presentation is built.
+
+| Consequence tier | Trusted facts that select it | Operator-facing meaning |
+| --- | --- | --- |
+| Conversational answer | A local `ask_user` question that records an answer | Records an answer without granting tool authority. |
+| Workspace authority | A main-agent one-shot approval whose bounded scope is the workspace | Authorizes only the presented call. Workspace changes can be reviewed and reverted when the action class supports that. |
+| Outward consequence | Typed `exposure: outward` | The answer concerns a step that can reach people or systems outside the workspace. The interview itself does not publish or send anything. |
+| Safety-net confirmation | An always-on confirm rail | The safety net requires a one-shot operator decision independently of the autonomy level. |
+| System change | `system_modify`, destructive, unknown, or otherwise system-scoped consequences | The effect reaches outside the workspace or cannot be safely bounded, and reversibility is unknown. |
+| Worker escalation | An authenticated dispatched-worker origin | The parked decision belongs to the named worker run and returns only to that exact request. |
+
+The classifier reads the request kind, the enforced safety or autonomy axis, normalized local or outward exposure, derived reversibility and scope, authenticated main-agent or worker origin, and whether the surface records an answer or grants one-shot authority. Model-authored questions, reasons, summaries, option labels, titles, and color names do not enter the classifier. Worker and system facts take conservative precedence, and an unknown action class uses the system tier. An interview that has reached outward exposure keeps that tier for later rounds and durable replay, so a later local declaration cannot visually lower it.
+
+These three concepts answer different questions:
+
+- The autonomy level decides when the registry allows, parks, or denies an action class.
+- The safety-net axis identifies an always-on rule that can block or require confirmation at every autonomy level.
+- The consequence tier explains the scope, reversibility, requester, and effect of a decision that the enforced axes have already produced.
+
 ---
 
 ## Enforcement path
@@ -237,7 +258,7 @@ Prefer typed tools over Bash:
 
 A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml` and `.clio-coder/safety.yaml` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: both files are operator authority, and a model that could author either one could widen its own permissions in two tool calls.
 
-The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings and shell executables, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
+The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
 `clio-coder verifiers discover` and `clio-coder verifiers author` do not grant authority during inspection. They read only declared package, Cargo, CMake preset, Python runner, Go module, and YAML validation-command signals and render exact argv vectors with provenance. The preview names the catalog path, cwd, timeout, tags, and authority consequence for every check. Toolchain conventions are labeled separately from literal project declarations. Ambiguous validation prose and directory-only hints are rejected with a JSON argv manual-entry path.
 
@@ -286,7 +307,7 @@ Evidence raises a warn-level external-bypass finding for bypassed runs and an in
 
 ## Approvals
 
-An `ask` can come from either axis: a safety-net confirm rail (damage-control `ask` rule, project `requireConfirmation`, `system_modify`) or the autonomy mapping. The permission overlay names the asking axis on its `Asked by:` line, and the transcript carries an `[approval]` notice for every parked call.
+An `ask` can come from either axis: a safety-net confirm rail (damage-control `ask` rule, project `requireConfirmation`, `system_modify`) or the autonomy mapping. The permission overlay names the authenticated requester and asking axis on its `Requested by:` lines, and the transcript carries an `[approval]` notice for every parked call.
 
 Every approvable ask has one canonical identity: a `requestId` minted at the approvals plane. The `PermissionRequested` and `PermissionResolved` bus payloads and the audit permission rows all carry it, along with `origin` (who asked), `axis` (which rail or level), and `decidedBy` (who or what answered), so a request joins its resolution on one key across the bus, the ledger, and receipts, and every request resolves exactly once. Worker escalations forward their full decision provenance (reasons, reason code, rule id, policy source), so the overlay names the real asking rail for a worker exactly as it does for the main agent.
 
@@ -294,9 +315,10 @@ How an ask resolves depends on the context:
 
 ### Interactive TUI Behavior
 
-In interactive mode, a permission request opens a queued overlay prompt immediately in the TUI.
-- **Queued Overlays:** If multiple tools or worker dispatches require permission during a single turn, the TUI queues the requests. Closing one overlay automatically pops the next permission overlay in the queue.
-- **Operator Options:** The operator can grant permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. Denying rejects only the presented request and advances the queue; the next parked call re-presents. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
+In interactive mode, a permission request opens a queued overlay prompt immediately in the TUI, and the composer rail switches to `CONFIRM` with the same keys for as long as the prompt owns the keyboard.
+- **Queued Overlays:** If multiple tools or worker dispatches require permission during a single turn, the TUI queues the requests. Closing one overlay automatically pops the next permission overlay in the queue. Each queued request retains its consequence tier and authenticated requester. A request that arrives while a different overlay (a picker, `/context`, the fleet board) holds the screen is announced with an `[approval]` notice and re-presented the moment that overlay closes.
+- **Operator Options:** `Enter` grants permission once, which resumes only the parked tool call without changing the overall operating posture; the one-shot grant is scoped to the presented request's `requestId`. `Esc` denies only the presented request and advances the queue; the next parked call re-presents. `s` denies it and ends the turn. Cancel-all is reserved for shutdown, an aborted turn, headless runs, and transport failure, where no operator can answer.
+- **Enter never doubles as send:** `Enter` allows only from an empty composer. While the composer holds a draft, `Enter` does nothing, both surfaces say `[Backspace] clear draft` in its place, and only deletion keys reach the editor. An operator who typed a message and pressed the habitual send key cannot approve a parked call by accident; on a safety rail the ambiguous key resolves away from allow.
 
 ### Deterministic Headless Behavior
 

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.7).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.4, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.7, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
 
@@ -95,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.4:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.7:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.4`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.7`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -127,6 +127,42 @@ The `/fork` command (`src/domains/session/tree/fork.ts:forkFromParentTurn`) init
 3. Traces ancestry up to `parentTurnId` and copies exactly the active path entries (excluding later unanchored sidecars) into the new session ledger.
 4. Stamps `parentSession` and `parentTurnId` in the new session header.
 
+### Handoff (`/handoff <goal>`)
+
+`/handoff` mints a successor session seeded with a reviewed document describing
+what the current session settled. It is a session operation and only that: it
+writes no memory promotion candidate, touches no memory record, and never calls
+the task-memory bank.
+
+The rule that makes the document trustworthy is read-ledger validation. Clio folds
+this session's persisted `read`, `edit`, `write`, `ls`, `find`, `grep`, and
+`artifact` tool calls (plus its `fileEntry` records) into a set of
+workspace-relative paths, through `filterEntriesToActivePath` so an abandoned
+`/tree` branch contributes nothing, exactly as the task board folds its own inputs.
+Every path the extraction round names is checked against that set and never against
+the filesystem. A file that exists on disk but that this session never opened is
+still an invention, so it is dropped and listed in the review document under
+`dropped (not in this session's read ledger)`.
+
+Extracted decisions merge with the session's settled decision board
+(`src/domains/session/decision-board.ts`); board entries win on conflict and are
+marked as settled. Superseded board decisions are history and do not travel.
+
+On accept, the new session opens with one `custom` entry of type `handoffSeed`
+carrying the reviewed document, the originating session id, and the goal. It
+projects into the model's replay as one user-role context message labelled as a
+handoff from the named session, on the same seam compaction and branch summaries
+use; it is never written as a fabricated user turn. The old session's
+`skillActivation` entries are replayed into the new session so loaded skills carry
+forward. The old session gains exactly one `custom` entry of type `handoffNote`
+recording the target session id, and is otherwise untouched. Esc during review
+cancels the whole handoff with nothing written in either session.
+
+The extraction round itself runs on the out-of-turn seam `/btw` uses: one call
+against the session's live target and model, the compiled message history as
+read-only input, no tools, and no entry in the ledger. Its provider usage is
+reported to `/cost` under a handoffs row and excluded from the turn count.
+
 ### Streaming Turn Settlement During Session Transitions
 
 When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistant turn is actively streaming, `settleChatBeforeSessionSwitch` (`src/interactive/session-switch-settlement.ts`) cancels the in-flight stream and awaits completion. This guarantees that partial assistant records and completed tool executions seal cleanly into the active session ledger before the session writer is replaced, preventing orphaned records in new sessions or unanswered prompts in original sessions (#114). Synchronous session transitions when chat is idle continue to execute immediately.

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.7).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 
@@ -28,18 +28,31 @@ skills/ catalog.
 
 The CLI reports the same state as `no local skill marketplace catalog or index configured`. A marketplace source that exists but fails (an unreadable index, a broken catalog package) is a diagnostic row in the hub, not a silent omission.
 
+The same index machinery can also describe agent recipes, prompt templates, and fleet contracts through typed entries and requirements. See [resource-library.md](resource-library.md) for the schema, private catalog, installation roots, and `clio-coder library` commands. Those kinds render on their own tabs in the hub, described below.
+
 ## Using the hub
 
 | Key | Action |
 |---|---|
 | type | Filter all groups |
-| `Enter` | Insert `/skill <name> ` into the editor for the task text |
+| `←`/`→` | Switch tabs |
+| `Enter` | Use the selected row: insert `/skill <name> ` into the editor for the task text, or the invocation the row's kind is called by |
 | `Tab` | Toggle the detail pane (split layout on wide terminals) |
-| `i` | Install the selected marketplace skill into the project scope through the local marketplace resolver |
+| `i` | Install the selected row through the resolver its kind installs by |
 | `PgUp`/`PgDn` | Scroll the detail pane |
 
 Invoking an uninstalled marketplace skill with `/skill <name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
 
+## Tabs
+
+The hub carries one tab per resource library kind: Skills, Agents, Prompts, and Fleets. `←` and `→` move between them, which is the key vocabulary the Settings Center already uses to move between sections. The frame title names the active tab and the footer states its row count, so the numbers on screen always describe the tab being read. `/skill` opens the hub on Skills. `/library <kind>` opens it on that kind's tab, and `/library` alone opens it on Skills.
+
+The Skills tab is unchanged. The other three list the entries of their kind from `discoverLibrary()`, which is the same discovery `clio-coder library list --kind <kind>` reads, so the hub and the CLI never disagree about what exists. Each row carries the entry's origin and version, whether it is installed or available, the short form of its recorded pin hash, and, in the warning token, the names of any requirements it still needs. An entry the catalog refuses outright, because a requirement is missing, malformed, or cyclic, appears as a diagnostic row rather than being omitted.
+
+`Enter` uses the selected row. An agent inserts `/run <agent> ` into the composer, a prompt inserts its `/<id> ` invocation, a skill does what the Skills tab does, and a fleet closes the hub and opens the `/fleet run` approval preview for that contract. A row that is not installed says so instead and points at `i`.
+
+`i` installs, through the same plan-then-write pair `clio-coder library add` runs. A framed confirmation states every destination path and SHA-256 hash before anything is written, which is the TUI spelling of the CLI's `--yes` gate; `Esc` there leaves every destination untouched. An entry whose requirements are not all installed is refused by name on the first `i`, and a second `i` opens the install-with-requirements confirmation, which names every entry it would write in dependency order.
+
 The CLI `clio-coder skills` commands manage local skill discovery, validation, and
 creation. Extension resource roots and share archives are documented in
 [extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI

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.4).
+> **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.7).
 
 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.4, `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.7, `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
 
@@ -234,8 +234,13 @@ Dispatches one or more tasks to Clio fleet agents and returns per-run receipt su
 Arguments:
 
 - `task` (required for the singular form unless `list:true`). One worker assignment/instruction string. It is distinct from briefing.
-- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, cwd, briefing}` objects. Per-item fields override the top-level defaults below. Supplying both `task` and `tasks` is an error.
-- `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. A single task always runs down the sequential path.
+- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, cwd, briefing, intent, gate}` objects. Per-item fields override the top-level defaults below. Supplying both `task` and `tasks` is an error.
+- `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. `pipeline`, `compete`, and `council` select their named topologies. A single ordinary task always runs down the sequential path.
+- `roster` (council only). Names one `workers.rosters` entry. Supply exactly one of `roster` or `members`.
+- `members` (council only). Supplies two to five inline `{label,target,model?,thinking?}` entries.
+- `synthesis` (council only). Accepts `none`, `judge`, or `vote`; the default is `none`.
+- `rounds` (council only). Accepts an integer from 1 through 3; the default is 1.
+- `judge` (council only with judge synthesis, or compete). Accepts optional `agent`, `model`, `target`, and `node` route fields.
 - `detach` (optional boolean). For parallel fan-out, returns the durable batch id and assignment ids after registration while the shared event consumer continues in the background. An assignment id equals its first attempt's run id. This is the parent model's route to mid-run monitor/steer; ordinary synchronous, sequential, and pipeline calls auto-wait for each assignment's terminal attempt.
 - `list` (optional boolean). Returns the agent catalog instead of dispatching.
 - `agent` (optional). Default agent recipe for items that do not name one; default `coder`. `agent_id` is accepted as an alias inside items.
@@ -248,13 +253,15 @@ Arguments:
 - `cwd` (optional). Default agent working directory.
 - `timeout_ms` (optional). Aborts the whole dispatch; in sequential mode remaining tasks are skipped and the skip is reported.
 - `briefing` (optional string, top-level default or per-task override). Parent-composed context/data, not worker instructions: it cannot replace `task`. It is trimmed and omitted when blank, rejected above 12,000 UTF-8 bytes, sent as its own delimited untrusted dynamic message, and retained only as byte/hash provenance. The shared value applies to string tasks and object tasks without an override; an object-level briefing wins.
+- `intent` (optional object, top-level default or per-task override). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands.
+- `gate` (optional string, top-level default or per-task override). Exact shorthand for `intent.verification=[{check: gate}]`. Supplying it together with `intent.verification` is refused.
 - `max_output_bytes` (optional). Summary byte budget; default 20000, split across runs with at least 1024 bytes each.
 
 Argument tolerance: `tasks` sent as a JSON string is parsed and a single object or bare string is wrapped into an array. The top-level singular `task` is first-class. Briefing-only calls fail with guidance that briefing is context and cannot replace a task.
 
 Output is one batch-shaped summary even for a single task: a header `dispatch (<mode>) total=N failed=M`, the assignment id list, then one terminal-attempt receipt line per assignment (run id, agent, exit code, target, model, tokens, receipt path, verification state, failure message if any) followed by the worker's final assistant text. `details = {mode, assignmentIds, receiptCount, failedCount, runs[]}`, and each `runs[]` entry carries distinct `assignmentId` and terminal `runId` fields plus the structured `verification` state and `receiptIntegrity` result. There is no `runIds` compatibility alias. Any terminal attempt with a nonzero exit turns the whole result into an error carrying the same summary. A run that succeeded without a single successful tool call carries a `note=` marker; do not treat such a run as validated work.
 
-The summary separates four things that must never be conflated: `receipt_integrity=verified/v15/sha256` comes only from verification against the ledger; `evidence_verification=<state>/<basis>` describes validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A tampered receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
+The summary separates five things that must never be conflated: `receipt_integrity=verified/v19/sha256` comes only from verification against the ledger; `host_verification=<status>` describes orchestrator-executed declared checks; `evidence_verification=<state>/<basis>` describes worker-tool validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A tampered receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
 
 Exit zero is insufficient without a durable deliverable. A successful native or ACP run must seal a nonempty `output.state="final"`. Otherwise it fails with `worker_final_output_missing`; any unfinished text remains partial diagnostics and automatic retry is suppressed. Live tool-use preambles never replace a missing receipt answer.
 
@@ -262,11 +269,11 @@ Sealed receipts are the durable evidence; worker prose remains advisory until ve
 
 ```text
 dispatch(list=true)
-dispatch(agent="debugger", task="Adversarially verify the strict v15 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", detach=true)
+dispatch(agent="debugger", task="Adversarially verify the strict v19 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", detach=true)
 dispatch(tasks=["Run the contract tests in tests/contracts/dispatch.test.ts and report each failure with its assertion"])
 dispatch(tasks=[
   {agent: "researcher", task: "Map every caller of finalizeObservation and summarize the envelope shapes"},
-  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts; run verify(check=\"test\") before finishing"}
+  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts", intent: {write_roots: ["tests/contracts"], verification: [{check: "test"}]}}
 ], mode="parallel")
 dispatch(tasks=["Refactor step 1", "Refactor step 2"], mode="sequential", timeout_ms=600000)
 ```

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.4).
+> **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.7).
 
 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.4`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.7`.
 
 ---
 

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.4).
+> **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.7).
 
 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.4).
+> **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.7).
 
 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.
 
@@ -207,11 +207,11 @@ The coordinator classifies failures into 13 explicit categories (`src/domains/di
 
 ### 5.2 Canonical Receipt Integrity Serialization
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
+Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
 
 - **Object Key Sorting**: Keys are sorted lexicographically before serialization (`Object.keys(obj).sort()`).
 - **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`.
+- **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/council provenance, briefing, steering, task worktree application, and `outcomeCode`.
 
 Integrity is only the artifact-integrity axis of the canonical trust status.
 The other axes are validation grounding, independent review, context

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.4",
+	"version": "0.3.7",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -76,7 +76,6 @@
 		"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 scripts/repeat-tests.mjs",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
@@ -86,9 +85,12 @@
 		"prepublishOnly": "npm run ci:release",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
+		"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:recon": "node --import tsx benchmarks/internal/live-recon.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"
@@ -100,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/src/cli/agents.ts

@@ -53,8 +53,7 @@ export async function runAgentsCommand(args: ReadonlyArray<string>): Promise<num
 function renderLine(spec: AgentSpec): void {
 	const shape = `${spec.audience}/${spec.category}/${spec.capabilityClass}/${spec.latencyClass}`;
 	const skills = spec.skills.length > 0 ? ` skills=${spec.skills.join(",")}` : "";
-	const budget = spec.budget
-		? `${spec.budget.toolCalls}/${spec.budget.readReserve}/${spec.budget.synthesis ? "synthesize" : "stop"}`
-		: "operator-default";
+	const maximum = spec.budget.maximum ? `..${spec.budget.maximum.toolCalls}/${spec.budget.maximum.readReserve}` : "";
+	const budget = `${spec.budget.toolCalls}/${spec.budget.readReserve}${maximum}/${spec.budget.synthesis ? "synthesize" : "stop"}`;
 	process.stdout.write(`${spec.id.padEnd(20)} ${shape.padEnd(48)} ${spec.description}${skills} budget=${budget}\n`);
 }

package/src/cli/argv.ts

@@ -102,6 +102,19 @@ export function globalFlagPositionHint(arg: string, command: string): string | n
  * for the command boundary, so `--skill path --api-key SECRET paths` treated
  * SECRET as a subcommand and printed it in an error.
  */
+/**
+ * Sessions are resumed from the interactive picker, not from a flag, and the
+ * flag every other agent CLI spells `--resume` or `--continue` fails closed
+ * here. The failure names the picker so the habit lands somewhere (#191).
+ */
+function unknownGlobalOptionError(arg: string): string {
+	const bare = arg.replace(/=.*$/u, "");
+	if (bare === "--resume" || bare === "--continue" || bare === "-r" || bare === "-c") {
+		return `unknown global option: ${arg}. Sessions are resumed from inside the app: start clio-coder, then type /resume to pick one.`;
+	}
+	return `unknown global option: ${arg}`;
+}
+
 export function extractGlobalFlags(
 	argv: ReadonlyArray<string>,
 	isSubcommand: (token: string) => boolean = () => false,
@@ -156,7 +169,7 @@ export function extractGlobalFlags(
 			noSkills,
 			skillPaths,
 			rest,
-			error: `unknown global option: ${arg}`,
+			error: unknownGlobalOptionError(arg),
 			...(apiKey === undefined ? {} : { apiKey }),
 		};
 	}

package/src/cli/fleet-commands.ts

@@ -0,0 +1,37 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { discoverDeclaredProjectCommands } from "../tools/verify/authoring.js";
+
+function quoted(value: string): string {
+	return JSON.stringify(value);
+}
+
+export function runFleetCommands(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "init") {
+		process.stderr.write("clio-coder fleet: commands: usage: clio-coder fleet commands init\n");
+		return 2;
+	}
+	const destination = join(process.cwd(), ".clio-coder", "fleets", "commands.yaml");
+	if (existsSync(destination)) {
+		process.stderr.write(`clio-coder fleet: commands init: destination already exists: ${destination}\n`);
+		return 2;
+	}
+	const entries = discoverDeclaredProjectCommands(process.cwd());
+	const lines = [
+		"# Draft fleet command registry.",
+		"# Every entry was discovered from a project declaration. Uncommenting an entry confirms its exact invocation.",
+		"# version: 1",
+		"# commands:",
+	];
+	for (const entry of entries) {
+		lines.push(
+			`#   ${entry.id}:`,
+			`#     argv: [${entry.command.map(quoted).join(", ")}]`,
+			`#     description: ${quoted(`Discovered from ${entry.provenance.path}: ${entry.provenance.detail}`)}`,
+		);
+	}
+	mkdirSync(dirname(destination), { recursive: true });
+	writeFileSync(destination, `${lines.join("\n")}\n`, { flag: "wx" });
+	process.stdout.write(`${destination}\n`);
+	return 0;
+}