@iowarp/clio-coder 0.3.4 → 0.3.7

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.7).
 
 Clio Coder has two related but separate surfaces:
 
@@ -114,7 +114,25 @@ Middleware hook budgets are phase-aware through `DEFAULT_MIDDLEWARE_HOOK_BUDGETS
 
 Per-phase budgets can be overridden via `CLIO_CODER_HOOK_BUDGET_<PHASE>_MS` or global `CLIO_CODER_HOOK_BUDGET_MS`. Warmup grace exempts initial calls (`DEFAULT_HOOK_BUDGET_WARMUP_CALLS = 1`), and steady-state warnings trigger when at least 3 of the last 5 post-warmup calls exceed budget (`DEFAULT_HOOK_BUDGET_WINDOW = 5`, `DEFAULT_HOOK_BUDGET_THRESHOLD = 3`). Overruns are reported but do not abort the turn. The orchestrator and workers share the middleware contract, but worker guard state is process-local.
 
-Middleware reminders are visible request text, not hidden prompt state. `turn_start` reminders flush into the same accepted request; `turn_end` reminders flush once on the next request. The built-in stalled-turn rule can request one automatic continuation for a user prompt, then stops rather than looping forever.
+Middleware reminders are visible request text, not hidden prompt state. `turn_start` reminders flush into the same accepted request; `turn_end` reminders flush once on the next request. A `request_continuation` from any producer is capped at one automatic continuation per user prompt; a second producer in the same prompt gets a footer notice that the nudge is spent, and the turn is handed back to the operator rather than looped.
+
+### Built-in registrations
+
+These ship in every interactive session. Each is one bounded behavior with a visible reminder; none changes a tool policy or a safety verdict.
+
+| Id | Hooks | What it does |
+| --- | --- | --- |
+| `nudge.stalled-turn` | `turn_end` | The one declarative rule. A turn that called no tools and ended on an announced action ("Next I will inspect `src/cli/index.ts`") is continued once with a reminder to perform it or say plainly that it is finished. Questions, "let me know", conditional offers ("if you want me to"), and completion statements are not announcements. |
+| `observer.skills-reminder` | `turn_start`, `turn_end` | Once per session, on the first substantive turn, when installed or installable skills exist, injects one line teaching the suggestion protocol: list with `context(scope="skills")`, open the reply with `Suggested skill: /skill <name>` when one matches, then continue the task in the same turn. Only the operator loads a skill. At `turn_end`, a reply that made the suggestion and stopped with only listing calls behind it is continued once (#184): the suggestion is not the task. Greetings do not spend the session's one reminder; a resumed or forked session never gets one. |
+| `observer.task-board-reminder` | `turn_start` | Once per session, when the operator's text literally enumerates three or more steps (`1)`, `2.`, `step 3:`, or three bulleted lines), injects one line asking for `tasks action="plan"` before the first edit. Prose that merely mentions numbers never counts. |
+| `nudge.open-tasks` | `turn_end` | A settled work turn (one that called tools) that ends while the session task board still has pending or active tasks is continued once with the open list. Pure conversation turns, aborted or errored turns, and boards where every remaining task is blocked do not trigger. |
+| `nudge.detached-dispatch` | `turn_end` | A settled turn that ends while a detached dispatch batch has every run terminal and uncollected is continued once, naming the ready batches; `monitor mode="collect"` clears it, including across resume. Batches with runs still in flight, and surfaces without `monitor`, do not trigger. |
+| `nudge.read-only-exploration` | `after_tool`, `turn_end` | After nine or more read-only calls (`read`, `grep`, `find`, `ls`, `code_nav`, read-only shell) in one user turn without a successful Scout dispatch, injects one advisory to delegate broad reconnaissance to Scout. One advisory per user turn, and only on surfaces that have `dispatch`. |
+| `rail.unbacked-worker-claim` | `after_tool`, `turn_end` | A reply that reports worker or Scout results in a turn with no `dispatch` call gets one warning that the claim is not backed by a receipt. A `[worker result]` note the operator shared is receipt-backed and exempt. No continuation: the operator decides. |
+| `observer.watchdog` | `after_tool`, `turn_end` | Opt-in through `watchdog.enabled` (default off). A turn that changed the tree is reviewed by one read-only `verifier` dispatch briefed with the turn's coalesced diff (per-path last-write-wins, bounded to 12 KiB) and the task board's current scope. Its failed checks become one transcript notice naming the count and the first three; a passing report emits nothing. `watchdog.cadenceToolCalls: N` also fires it every N tool calls inside the turn. One run in flight at a time; an overlapping trigger is dropped and counted. It emits no middleware effects, never continues a turn, and never mutates. Turns with no file mutations, headless runs, and ACP runs never fire it. |
+| `observer.memory-intervention` | `after_tool` | Every `memory.intervention.everyNTools` tool calls, asks a background model for a bounded reflection over the recent window and injects it as a reminder when it arrives. Governed by the `memory.intervention` settings block. |
+
+Two coded controls sit beside the registrations rather than among them. `tool-choice-control` turns `require_tool` and `lock_tools` effects into the provider's tool-choice field for the next round: a required tool clears when that tool starts, a lock lasts until the next submitted turn and outranks later requirements. `hook-receipts` is the durable ring (200 entries, throttled to one write per two seconds) of user-defined hook executions that `clio-coder config inspect` reads.
 
 User-defined hook declarations load from three places: `<extensionRoot>/hooks.yaml`, `.clio-coder/hooks.yaml`, and `.clio-coder/hooks.local.yaml`. A hook can be `prompt`, `effect`, or `command`. Command hooks run an argv array without a shell, under the workspace with a timeout and bounded output, and every hook execution emits a receipt.
 

package/docs/model-catalog.md

@@ -1,7 +1,7 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.7).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 

package/docs/observability.md

@@ -1,7 +1,7 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.7).
 
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
@@ -57,6 +57,53 @@ An `EvidenceIndexRow` has the following schema:
 
 ---
 
+## Cross-Session Usage Facts
+
+`clio-coder usage report` folds the local archive into one window of facts. Its token and cost facts come from two inputs: the per-session ledgers, folded through the session domain's `ledgerUsageCalls`, and the out-of-turn usage store described below. Both the text report and `--json` carry the same fields.
+
+| Field | Where it appears | Meaning |
+| --- | --- | --- |
+| `apiCalls` | `tokens in window: <total> over <n> model calls` and the `tokens` JSON fact | Provider calls folded in the window, out-of-turn rounds included. |
+| `input`, `output`, `cacheRead`, `cacheWrite`, `reasoningTokens`, `totalTokens` | the same line and fact | Provider-reported token breakdown for those calls. |
+| `costUsd` | `provider-reported cost in window` and the `tokens` fact | Provider-reported cost. Never estimated. |
+| `turns` | `turns in window` and the `tokens` fact | Folded calls that were turns, so labelled calls are subtracted exactly as `/cost` subtracts them. |
+| `sideQuestions` | `side questions in window` and the `tokens` fact | `/btw` rounds in the window. |
+| `handoffs` | `handoffs in window` and the `tokens` fact | `/handoff` extraction rounds in the window. |
+
+The last three fields appear only when at least one labelled call falls in the window. An archive with no `/btw` or `/handoff` round in it renders exactly as it did before those fields existed, so their presence is itself the signal that money was spent beside a session.
+
+### The Out-of-Turn Usage Store
+
+A `/btw` side question and a `/handoff` extraction round are real provider calls that append nothing to the session JSONL, by design: a fleet run briefs its workers from the transcript, and a question the operator asked to orient themselves must not become context those workers inherit. The spend still has to be recorded somewhere durable, so it goes to `<stateDir>/usage/out-of-turn.jsonl`, one JSON line per priced call, written by the chat loop at the same moment it reports the call to `/cost`.
+
+The file is append-only NDJSON kept as a bounded ring (capped at 1000 rows, rewritten atomically under the shared state-file lock when it grows past the cap). Reads are tolerant: a malformed line is reported as a diagnostic on stderr and skipped.
+
+A row has the following schema:
+```json
+{
+  "label": "side-question",
+  "sessionId": "01JQ2K7V8W",
+  "repoIdentity": "9f2c1b4ea77d0c31",
+  "timestamp": "2026-06-25T14:30:00.000Z",
+  "target": "dynamo",
+  "attributedModelId": "Nemo-3.5",
+  "usage": {
+    "input": 120,
+    "output": 8,
+    "cacheRead": 4,
+    "cacheWrite": 0,
+    "reasoning": 2,
+    "totalTokens": 132,
+    "costUsd": 0.0004,
+    "costProvenance": "known"
+  }
+}
+```
+
+`repoIdentity` is the same cwd hash the session ledger is filed under, which is what lets `usage report --repo <path>` select these rows with the hash it already computes for the ledgers.
+
+---
+
 ## Artifact Categories and Path Layouts
 
 Clio resolves directories under platform-specific XDG defaults (on Linux, these default to `~/.config/clio-coder/`, `~/.local/share/clio-coder/`, and `~/.local/state/clio-coder/`).
@@ -109,17 +156,17 @@ Pressing `v` on a selected receipt or running `/view verify <runId>` performs cr
 
 1. **Read Receipt**: Reads the receipt JSON from `<stateDir>/receipts/<runId>.json`.
 2. **Resolve Ledger**: Looks up the run envelope inside `<stateDir>/runs.json`.
-3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v15 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, and result-contract conformance. Every version other than 15 fails verification; there is no historical receipt reader.
+3. **Verify Integrity**: Recomputes the SHA-256 digest over the strict v19 receipt and reconstructible ledger fields. The digest covers every current field, including steering, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance. Every version other than 19 fails verification; there is no historical receipt reader.
 4. **Report Result**: The viewer reports `ok` or the verification failure reason. It does not rename or delete the receipt. Startup orphan recovery may quarantine corrupt orphan receipt files as `<name>.json.corrupt`, but `/view verify` is read-only.
 
 ---
 
 ## Receipt Fields for Dispatch Provenance
 
-A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v15 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
+A receipt carries optional provenance and context blocks that answer "what happened" for a chained (pipeline), composed (persona override), escalated, briefed, steered, council, or external run. Those optional blocks remain absent when unused. Current receipts carry strict integrity v19 and an explicit `outcomeCode: null` when no classified deterministic failure occurred. Automation consumers must treat the optional blocks below as absent by default and `outcomeCode` as nullable; older receipt versions are invalid.
 
 Receipt integrity verification and evidence verification are independent.
-`receipt_integrity=verified/v15/sha256` means Clio called the receipt verifier
+`receipt_integrity=verified/v19/sha256` means Clio called the receipt verifier
 against the ledger envelope; merely finding an embedded digest is not enough.
 `evidence_verification=<verified|unverified|not_applicable|unknown>/<basis>`
 describes validation evidence inside that verified receipt. Likewise,
@@ -130,7 +177,7 @@ separately and never substitute one hash for another.
 
 The evidence bundle renders these sets in `transcript.md` (human sentences) and `trace.cleaned.jsonl` (structured run rows), `clio-coder evidence inspect` prints them as a `provenance <runId>:` block, and the `dispatch` tool appends a compact suffix to each run line plus additive keys on `details.runs[]`. A timed-out or denied escalation also raises an `escalation` finding in the bundle.
 
-The base provenance sets, steering, routing, quality, worker identity, and result-conformance coverage all enter in v0.2.9. These fields are labeled `experimental`: their strict v15 shape is frozen for the release, but the labels stay experimental until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).
+The base provenance sets, steering, routing, quality, worker identity, result-conformance, council provenance, and fleet gate provenance use the strict v19 shape frozen for the release. These fields are labeled `experimental` until the schema is promoted post-1.0. For the complete version registry and migration contract across all artifacts, see [artifact-versions.md](artifact-versions.md).
 
 | Field path | Type | When present | Meaning | Status |
 | --- | --- | --- | --- | --- |
@@ -149,7 +196,7 @@ The base provenance sets, steering, routing, quality, worker identity, and resul
 | `steering[].sentAt` | `string` | A steer was successfully written | Write timestamp | experimental |
 | `steering[].acknowledged` | `boolean` | A steer was successfully written | Whether a worker acknowledgement was actually observed | experimental |
 | `steering[].acknowledgedAt` | `string` | Acknowledgement was observed | Acknowledgement timestamp | experimental |
-| `outcomeCode` | five-value stable string union or `null` | Every v15 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, or `worker_final_output_missing`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
+| `outcomeCode` | six-value stable string union or `null` | Every v19 terminal receipt | Non-null for `vram_capacity_fit_failure`, `worker_tool_call_cap_exhausted`, `loop_guard_tools_disabled_exhausted`, `result_contract_exhausted`, `worker_final_output_missing`, or `host_verification_rejected`; otherwise `null`. Each non-null code denotes terminal deterministic failure and is incompatible with `outcome: "succeeded"`. Dispatch retry policy consumes this code only, never diagnostic prose. | experimental |
 | `personaOverride.promptHash` | `string` | Ad-hoc specialist whose persona replaced the recipe body | Hash of the composed static prompt; equals `staticCompositionHash` for the run | experimental |
 | `safety.decisions.escalationRequested` | `number` | Run saw at least one permission escalation | Parked permission asks handed to the operator | experimental |
 | `safety.decisions.escalationApproved` | `number` | Run saw at least one permission escalation | Escalations the operator approved | experimental |
@@ -159,8 +206,8 @@ The base provenance sets, steering, routing, quality, worker identity, and resul
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.3.4 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.4 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.3.7 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.7 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.7).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
@@ -133,7 +133,7 @@ it runs detached from it.
 | Interval | After `memory.intervention.everyNTools` completed tools since the last prompted step; default 10. This is the nondeterministic/citation-gated path. |
 | Tool-error streak | Two consecutive error outcomes. A successful tool resets the streak. |
 | Loop signal | Reuses the orchestrator loop guard's verdict; it does not infer a second competing loop detector. |
-| Repeated failure | The rules tier records failed tool fingerprints and annotates the failing tool result once the same failure appears twice in the bounded trajectory. |
+| Repeated failure | The rules tier records failed operation fingerprints and annotates the failing tool result once the same failure appears twice in the bounded trajectory. |
 | Post-compaction | The first turn start after compaction restores status and knowledge once, without a model call, because compaction is precisely where execution facts leave the active window. |
 
 ### Two delivery channels
@@ -145,11 +145,13 @@ repeated failure uses exactly one of them:
 
 - **Mid-turn annotation.** The second identical failure appends one cited
   `Memory:` advisory to that tool's own result, through the existing
-  `annotate_tool_result` effect the loop guard already uses. The advisory digest
-  takes the first line of the tool error that names a problem, falling back to
-  the first line when no line names one. The model reads it on its very next round.
-  This is spent once per fingerprint per turn and re-earned in a later turn, because
-  the same command failing again after an operator turn is news again.
+  `annotate_tool_result` effect the loop guard already uses. The advisory uses
+  the canonical result-disposition digest when one is available. Older hook
+  producers fall back to the first tool-error line that names a problem. Every
+  digest is redacted and byte-capped before it reaches the task bank. The model
+  reads the advisory on its very next round. This is spent once per operation
+  fingerprint per turn and re-earned in a later turn, because the same command
+  failing again after an operator turn is news again.
 - **Next-turn reminder.** Post-compaction reactivation and any background-model
   reminder ride the `inject_reminder` buffer into the next submitted turn, inside
   the visible `<system-reminder>` block, and persist in the session ledger.
@@ -319,15 +321,23 @@ operation while leaving deterministic protection active.
 Measured on the shipped prompt against `google/gemma-4-26b-a4b-qat`, across ten
 live steps and forty controlled runs on the same route.
 
-The tier writes `update_status` reliably and `save_knowledge` rarely, and that is
-correct rather than broken. A trajectory step carries the tool name, a bounded
-call description, an outcome, and a result digest. On success the digest is an
-opaque result fingerprint, so a window of successful reads tells the model which
-files were touched and nothing about what is in them. There is no durable fact in
-that input, and a status line is the only faithful thing to write about it.
-
-Three candidate causes were ruled out by controlled runs that changed one
-variable at a time:
+Earlier measurements found that the tier wrote `update_status` reliably and
+`save_knowledge` rarely. At that time a successful trajectory step carried an
+opaque result fingerprint, so a window of successful reads told the model which
+files were touched and nothing about what was in them.
+
+A current trajectory step keeps two fields with different jobs. The operation
+fingerprint identifies repeated calls and remains derived only from the tool name
+and arguments. The result digest is human-readable diagnostic content from the
+canonical result-disposition projection, with explicit source provenance. Secret
+redaction and a 240-byte cap apply before the digest reaches the task bank or the
+background request. A metadata-only disposition contributes outcome facts and no
+captured body. Results without a canonical disposition use a redacted deterministic
+fallback, so older tool producers remain useful without gaining a second model
+summarizer.
+
+Three candidate causes were ruled out in the earlier implementation by
+controlled runs that changed one variable at a time:
 
 - rewriting the prompt's second worked example to carry a `save_knowledge` moved
   nothing, and made the model emit no operations at all in four of five runs;

package/docs/prompt-envelope-and-tools.md

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.7).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
@@ -78,6 +78,8 @@ Three tools sit in a plane for containment rather than class. `git` is read-only
 
 Registration is conditional on wiring: `context` gains its workspace scope only when a session contract is bound, `dispatch`/`monitor`/`steer` register only with a dispatch contract, and `ask_user` registers only when an interactive handler exists. Dispatch tool profiles narrow the surface for workers: `minimal-local` is `read`, `grep`, `find`, `ls`, `git`, `context`, `code_nav`; `science-local` adds `verify`; `full-agent` keeps everything.
 
+`ask_user` keeps its typed `exposure: local | outward` admission fact separate from caller prose. The registry uses exposure only in the enforced autonomy mapping. After admission, the host carries the normalized fact into the shared decision-presentation classifier; question text, headers, options, summaries, and requested color or severity words cannot select a consequence tier. The resulting presentation object contains no admission disposition and cannot grant authority.
+
 ### Consolidated call shapes
 
 Several tools absorb what used to be separate tools:
@@ -87,7 +89,7 @@ Several tools absorb what used to be separate tools:
 - `context(scope="workspace"|"docs"|"skills")` is the one OBSERVE entry point for material about the working environment: the session workspace snapshot, retrieval over Clio's bundled documentation (`query` required), and skill listing or loading (`name` optional, `include_tree` for the skill's resource files).
 - `verify(check?, path?, args?, browser?, cwd?, timeout_ms?)` runs declared verification. `verify()` lists package.json verification scripts and strict version-1 `.clio-coder/verifiers.yaml` entries through the same `{id, description, command, cwd, timeoutMs, tags, source}` projection. `verify(check="<id>")` runs a package script or the catalog's exact argv/cwd/timeout through safe-exec with no shell. Model `args`, cwd, timeout, output-cap, and environment fields cannot mutate a project entry. `verify(check="frontend", path=...)` validates an HTML/CSS/JS artifact without granting shell access.
 - `artifact(kind="plan"|"review"|"report", content, ...)` writes named artifacts behind one surface: Markdown documents (default `.clio-coder/artifacts/PLAN.md`/`REVIEW.md`/`REPORT.md`; `path` may override inside the workspace) that terminate the turn, because writing the artifact is the answer. Skills are not artifacts; a `SKILL.md` is written with the ordinary write tool and validated by the skills loader.
-- `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona` and `tool_profile`. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
+- `dispatch(task?, tasks?, mode?, ...)` supports a first-class singular assignment (`task`) and a batch (`tasks`), never both. `task` is worker instructions; `briefing` is optional bounded parent context/data and cannot replace it. Briefing stays a separate dynamic message and receipt provenance, never part of the receipt task. A shared top-level briefing applies to strings and objects without an override; an object-level briefing wins. Blank values are omitted, the cap is 12,000 UTF-8 bytes, and approval pins the exact canonical value. Ordinary handles enter one registered event consumer immediately. Synchronous calls auto-wait for stream-and-receipt completion; `detach:true` returns ids after durable batch registration while the same consumer continues. Review and compete retain gate-sensitive direct drains. Task objects may include `persona`, `tool_profile`, and a typed `budget: {toolCalls, readReserve, retryRevision?}`. The budget must fit the recipe's authored range and the operator lifetime cap. `retryRevision` is the only authority for a later retry, result-contract revision, or review revision to grow its phase. Pipeline output is threaded as bounded data. A successful native or ACP run requires a nonempty receipt-sealed final output; exit zero without one fails as `worker_final_output_missing`, with unfinished text retained only as partial diagnostics. `dispatch(list=true)` renders the catalog.
 - `monitor(run_id?, mode?)` is read-only visibility into known synchronous and detached runs: `list` enumerates, `status` reports one, `peek` returns the in-process event tail, `receipt` exposes the stored evidence, and `wait` observes one run without collecting or canceling it. `collect` is the authoritative terminal batch operation over a detached batch or run-id list; collect before final synthesis. Completed output reports receipt integrity, evidence verification, briefing provenance, and bounded project-context provenance as different fields.
 - `steer(run_id, action, message?)` controls a running worker: `guide` writes a canonical trimmed steering message to an HTTP or SDK worker and `cancel` terminates it. Successfully written steers gain ordered byte/hash/timestamp provenance; after the runtime accepts the guidance, `clio_steer_received` acknowledges the exact matching sequence, and prose is never stored in ledger or receipt. Single-shot subprocess runtimes and ACP remain non-steerable. Interactive operators can steer synchronous live-input runs; parent-model steering requires detached ids because model tools are sequential.
 

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.7).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/release-cut-checklist.md

@@ -1,6 +1,6 @@
-# v0.3.4 Release-Cut Checklist
+# v0.3.7 Release-Cut Checklist
 
-The ordered steps that turn the prepared `v0.3.4` branch into a published
+The ordered steps that turn the prepared `v0.3.7` branch into a published
 release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
 repeatable and reversible and is run locally before the cut. Everything below
 it is external or irreversible and needs an explicit decision from the
@@ -11,13 +11,15 @@ state of every step.
 
 | Item | State |
 | --- | --- |
-| Branch | `v0.3.4`; `origin/v0.3.4` exists and is pushed to the reviewed tip before the cut |
-| `package.json` version | `0.3.4`; the top `CHANGELOG.md` heading is `## 0.3.4 - 2026-08-22` |
-| `main` | `8a1c8304`, the published `v0.3.3` commit; it is an ancestor of `v0.3.4` and moves only at Part 4. |
-| `origin/main` | `8a1c8304`, matching the published `v0.3.3` commit |
-| Tags | none for 0.3.4, local or remote |
-| GitHub Release | none for 0.3.4 |
-| npm registry | `@iowarp/clio-coder@0.3.4` absent; `latest` is `0.3.3` |
+| Branch | `v0.3.7`, pushed to `origin` under the explicit refspec `refs/heads/v0.3.7`; sixteen feature and docs commits, the version-bump commit, and the fix commits the interactive release testing produced, ahead of `main` |
+| `package.json` version | `0.3.7`; the top `CHANGELOG.md` heading is `## 0.3.7 - 2026-08-24` |
+| `main` | `9b54219d`, the v0.3.6 release SHA; it is an ancestor of `v0.3.7` and moves only at Part 4 |
+| `origin/main` | `9b54219d`, matching `main` |
+| Tags | `v0.3.6` exists on `9b54219d`; none for 0.3.7, local or remote |
+| GitHub Release | `v0.3.6` published 2026-08-24; none for 0.3.7 |
+| npm registry | `@iowarp/clio-coder@0.3.7` absent; `latest` is `0.3.6` |
+| npm history | Published versions 0.3.0 through 0.3.4 and 0.3.6. Version 0.3.5 was published and withdrawn and can never be reused. |
+| Milestone | `v0.3.7` holds the thirteen issues this branch closes (#155, #204, #206 through #216); the ten off-map items (#156, #158 through #164, #198, #199) moved to `v0.3.8` on 2026-08-24 |
 | Commit provenance identity | Post-release maintainer follow-up, not a gate: verifying `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and GitLab identities (such as `clio-coder-bot` or `iowarp-clio`, with `assets/clio-coder-avatar-512.png` as the avatar) only changes how those platforms render the trailers. |
 
 ---
@@ -38,8 +40,9 @@ Run against the exact final candidate with `NO_COLOR` unset and
    integrity, version coherence between `package.json` and the top
    `CHANGELOG.md` heading, the forbidden-file list, the required runtime
    resources, and the tarball and unpacked size budgets)
-9. Step 8 again under the other supported Node major. Both Node 22 and
-   Node 24 must be green; the repo is developed against 22.22.3 and 24.9.0.
+9. Optional: step 8 again under Node 24. Hosted CI gates on Node 22 alone,
+   the `engines` floor; the weekly `flake-hunt` workflow carries Node 24.
+   Repeat locally only when the cut touches runtime-sensitive code.
 10. `npm run live:smoke -- --target <id>` for one real headless turn through
     the built binary against a configured target, which is the one release
     check a deterministic suite cannot give. The packaged-install lifecycle
@@ -51,35 +54,50 @@ Run against the exact final candidate with `NO_COLOR` unset and
     `docs/html/`, `apps/workbench`, `.superpowers`, `tests/`, `scripts/`,
     `benchmarks/`, scratch files, and source maps are absent. Record the
     filename, packed and unpacked sizes, integrity, and shasum.
-12. Install that tarball into a clean temporary prefix with empty XDG roots and
-    verify `--version`, `--help`, an empty-state non-TTY launch, `doctor`, and
-    `uninstall --dry-run` without developer-local state.
+12. Install that tarball into a clean temporary prefix with an empty
+    `CLIO_CODER_HOME` and verify `--version`, `--help`, an empty-state non-TTY
+    launch, `doctor`, and `uninstall --dry-run` without developer-local state.
+13. Interactive release testing, which this cut added because the release is
+    almost entirely interactive surface: a tester agent drives the step-12
+    install through real TUI sessions in a throwaway repository, one session
+    per shipped feature, against local targets for the main session and a
+    cloud target for council members and advice, and writes a per-feature
+    PASS / FAIL / BLOCKED table with evidence. A FAIL on a deterministic
+    behavior (a refusal, a file, a receipt field, CLI output) blocks the cut;
+    a BLOCKED(model) on a model decision does not.
 
 ## Part 2: version and notes (repeatable)
 
-13. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.4 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.4)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.4)` titles in `docs/html/*.html`, the `--branch`
+14. Files carrying a version reference, to update together if the number
+    changes: `package.json` and `package-lock.json`, the `## 0.3.7 - <date>`
+    heading in `CHANGELOG.md`, the `(Version: 0.3.7)` markers in `docs/*.md`,
+    the `Blueprint (v0.3.7)` titles in `docs/html/*.html`, the `--branch`
     pin in the README install block (the hygiene lint checks it), and the
     measured-at figures in `scripts/check-release.mjs` if the package size
-    moved materially.
-14. Confirm the `## 0.3.4` section of `CHANGELOG.md` describes every
-    user-visible behavior change, including the ones that alter existing
-    behavior, and carries no Workbench release narrative. The release workflow
-    uses this section verbatim as the GitHub Release body.
-15. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.4`.
+    moved materially. For 0.3.7 the tarball measured 6.5 MB packed and
+    37.9 MB unpacked, inside the 10 MB and 50 MB ceilings set for 0.3.6.
+15. Confirm the `## 0.3.7` section of `CHANGELOG.md` describes every
+    user-visible behavior change under `### Added`, and every change to an
+    existing behavior under `### Changed`, and carries no Workbench release
+    narrative. The release workflow uses this section verbatim as the GitHub
+    Release body.
+16. `docs/artifact-versions.md` lists every persisted artifact this release
+    added or re-versioned: run receipt integrity v19, fleet contract v5, the
+    fleet run record, the checkout writer lease, the out-of-turn usage ledger,
+    and the library pin file.
+17. Re-run `npm run ci:release` after any version edit and commit as one
+    commit on `v0.3.7`.
 
 ## Part 3: present the gate
 
-16. Report to the operator before touching `main`: the exact final `v0.3.4`
+18. Report to the operator before touching `main`: the exact final `v0.3.7`
     SHA and clean status, the commits added since the handoff SHA, the gate
-    commands with pass/fail totals for both Node majors, the package version
-    and changelog heading, the tarball audit, the clean-install results and any
-    deferred live check, confirmation that no tag, GitHub Release, or npm
-    version exists yet, the proposed commands for Parts 4 through 6, and the
-    proposed npm dist-tag. The dist-tag is the operator's call; never guess it.
+    commands with pass/fail totals, the package version and changelog heading,
+    the tarball audit, the clean-install results, the interactive test table,
+    and any deferred live check, confirmation that no tag, GitHub Release, or
+    npm version exists yet, the proposed commands for Parts 4 through 6, and
+    the npm dist-tag. The dist-tag is the operator's call; for 0.3.7 the
+    operator chose `latest` on 2026-08-24.
 
 ---
 
@@ -91,53 +109,53 @@ confirming the exact SHA and the commands.
 
 ## Part 4: fast-forward `main`
 
-17. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.4` tip and confirm no other
+19. `git fetch origin` immediately before integrating; require `origin/main`
+    to be an ancestor of the reviewed `v0.3.7` tip and confirm no other
     worktree has `main` checked out.
-18. `git checkout main && git merge --ff-only v0.3.4`. No merge commit, no
+20. `git checkout main && git merge --ff-only v0.3.7`. No merge commit, no
     rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
-19. `git fetch origin` once more; stop on any unexpected remote movement. Then
-    `git push origin main`. Never `--force` or `--force-with-lease`.
+21. `git fetch origin` once more; stop on any unexpected remote movement. Then
+    `git push origin main`. Never `--force` or `--force-with-lease`. The push
+    closes the thirteen milestone issues through their `Fixes` trailers.
 
 ## Part 5: exact-SHA CI, tag, GitHub Release
 
-20. Wait for the `ci` workflow the `main` push triggers. Both the Node 22 and
-    Node 24 jobs must succeed on the exact release SHA. A red or pending run
-    blocks the tag; a flake is rerun only with concrete evidence, never
-    silenced with an unrelated change.
-21. Reconfirm that tag `v0.3.4` and the GitHub Release do not exist, then
-    `git tag -a v0.3.4 -m "Clio Coder 0.3.4"` on the green SHA and
-    `git push origin v0.3.4`.
-22. The tag push triggers `.github/workflows/release.yml`, which requires a
-    successful `ci` run for the tagged SHA, verifies the tag matches
-    `package.json`, builds and audits the artifact, extracts the `## 0.3.4`
-    section of `CHANGELOG.md` as the release body, and attaches the tarball.
-    Do not create a release by hand. Verify the run's SHA, the notes, the
-    attached tarball, and the URL.
+22. The `main` push triggers the `ci` workflow. It is a useful signal but not
+    a gate on tagging, because `release.yml` runs the same gate on the tagged
+    tree itself. A red run still blocks the cut; investigate it rather than
+    tagging around it, and never silence a flake with an unrelated change.
+23. Reconfirm that tag `v0.3.7` and the GitHub Release do not exist, then
+    `git tag -a v0.3.7 -m "Clio Coder 0.3.7"` on the green SHA and
+    `git push origin refs/tags/v0.3.7`.
+24. The tag push triggers `.github/workflows/release.yml`, which verifies the
+    tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
+    extracts the `## 0.3.7` section of `CHANGELOG.md` as the release body, and
+    attaches the tarball. Do not create a release by hand. Verify the run's
+    SHA, the notes, the attached tarball, and the URL.
 
 ## Part 6: npm publication (irreversible)
 
-23. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.4` is still absent.
-24. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.3` as the default.
-25. Run `npm publish` (or `npm publish --tag next`) once. `prepublishOnly`
-    re-runs `ci:release` as a safety net; it is not a substitute for Part 1.
-26. A published version cannot be replaced. `npm unpublish` is restricted and
+25. `npm whoami` and confirm the registry and account; reconfirm
+    `@iowarp/clio-coder@0.3.7` is still absent.
+26. Obtain the operator's explicit dist-tag decision. `latest` makes this the
+    default install for every user; `--tag next` keeps `0.3.6` as the default.
+27. Run `npm publish` once. `prepublishOnly` re-runs `ci:release` as a safety
+    net; it is not a substitute for Part 1.
+28. A published version cannot be replaced. `npm unpublish` is restricted and
     time-limited; a mistake is corrected by publishing a higher version.
 
 ## Part 7: post-publish verification and follow-ups
 
-27. `npm view @iowarp/clio-coder@0.3.4` and the selected dist-tag.
-28. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
+29. `npm view @iowarp/clio-coder@0.3.7` and the selected dist-tag.
+30. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
     rather than from a local tarball, then repeat step 12 against it, plus
     `configure` to a real target and one real turn when one is authorized.
     This is the only step that tests what users actually receive.
-29. From an installation of 0.3.3, verify `clio-coder upgrade` finds and
-    applies 0.3.4.
-30. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
+31. From an installation of 0.3.6, verify `clio-coder upgrade` finds and
+    applies 0.3.7.
+32. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
     tarball evidence, and the post-publish verification in the release report.
-31. Maintainer follow-up, independent of the release: verify the commit
+33. Maintainer follow-up, independent of the release: verify the commit
     provenance email `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and
     GitLab identities such as `clio-coder-bot` or `iowarp-clio`, and upload
     `assets/clio-coder-avatar-512.png` as the account avatar where PNG is
@@ -150,7 +168,7 @@ confirming the exact SHA and the commands.
 
 ## Rollback
 
-There is no rollback for step 25. Before it, every step is reversible: steps
-21 and 22 by deleting the local and remote tag and the draft release, steps 17
-through 19 by a new forward commit on `main` (never by rewriting it), and
+There is no rollback for step 27. Before it, every step is reversible: steps
+23 and 24 by deleting the local and remote tag and the draft release, steps 19
+through 21 by a new forward commit on `main` (never by rewriting it), and
 everything in Parts 1 and 2 by `git checkout`.

package/docs/resource-library.md

@@ -0,0 +1,59 @@
+# Resource Library
+
+The resource library extends the existing local skills marketplace catalog to carry agent recipes, prompt templates, and fleet contracts. It does not change the Agent Skills format, discovery roots, trust gating, or existing skill installation sources.
+
+## Catalog schema
+
+A catalog is a JSON or YAML list, or an object whose `skills` property contains the list. The historical property name remains accepted so every existing skill marketplace index works unchanged.
+
+```yaml
+skills:
+  - kind: fleet
+    name: release
+    description: Build and verify a release.
+    sourceUrl: ./fleets/release.md
+    requires:
+      - agent:release-builder
+      - skill:ship
+```
+
+`kind` accepts `skill`, `agent`, `prompt`, or `fleet` and defaults to `skill`. `requires` accepts typed references with those same four prefixes. Clio resolves requirements recursively across the selected catalog and the private catalog. Missing, malformed, and cyclic requirements are refused with stable `library_requirement_*` diagnostics. A requirement is satisfied when its typed reference exists in `<configDir>/library-pins.yaml` or its kind-specific destination exists. Add output lists satisfied and unsatisfied requirements separately. Requirements are reported without installation unless `library add` receives `--with-requirements`. That flag installs only the unsatisfied dependencies in dependency order before the requested entry.
+
+## Private catalog and remote gating
+
+`library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `library.remote` records an optional git remote URL. `library.sync` defaults to false, and no git process is started while it remains false.
+
+The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
+
+When `library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
+
+## CLI
+
+```text
+clio-coder library list [--kind k] [--json]
+clio-coder library search <query> [--kind k] [--json]
+clio-coder library add <ref> [--from <catalog|path>] [--with-requirements] [--yes] [--json]
+clio-coder library use <kind> <name>
+clio-coder library push
+clio-coder library sync
+clio-coder library remote confirm <url>
+```
+
+`library add` prints every destination and SHA-256 hash before it writes. It writes nothing until `--yes` is present. `library use` prints the invocation to paste into the relevant surface.
+
+## In the TUI
+
+The Skills Hub carries one tab per kind. `/library <kind>` opens it on that kind's tab and `/library` alone opens it on Skills, which is also where `/skill` opens. Each tab lists the entries this same discovery finds, with the requirements an entry still needs named in the warning token. Installing from a row runs the same plan-then-write pair `library add` runs, behind a confirmation that states every destination and hash and writes nothing when it is cancelled, and an entry with unresolved requirements is refused by name before an install-with-requirements confirmation offers to write them all. `Enter` on an installed row leads where that kind is invoked from: the composer for an agent, a prompt, or a skill, and the `/fleet run` approval preview for a fleet. See [skills-marketplace.md](skills-marketplace.md) for the key table.
+
+## Installation roots and validation
+
+| Kind | User installation root | Validation before write |
+| --- | --- | --- |
+| skill | `<configDir>/skills/<name>/SKILL.md` | Existing skill loader and installer |
+| agent | `<configDir>/agents/<name>.md` | Agent recipe schema and policy |
+| prompt | `<configDir>/prompts/<name>.md` | Prompt template loader |
+| fleet | `<configDir>/fleets/<name>.md` | Fleet contract parser |
+
+Every installed item records a kind-qualified hash in `<configDir>/library-pins.yaml`. Agent recipes become visible through `clio-coder agents`. User fleet contracts participate between built-in and project fleet precedence, so a project contract still wins. Prompts use the existing user prompt root.
+
+Share archives may carry agent and fleet entries. Import always validates these formats before writing, and fleet entries land in the user fleet root.