@iowarp/clio-coder 0.3.6 → 0.3.8

package/dist/worker/entry.js

@@ -16,25 +16,29 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-ZRGEBJ4T.js";
+} from "../chunk-WLFILSD5.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-ZXF4XRKW.js";
+} from "../chunk-7RGZWPB6.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
   WORKSPACE_SCOPE,
   isSubset
-} from "../chunk-IR4CFBFN.js";
+} from "../chunk-VCBR6CU7.js";
 import {
   createLoopState,
   observe
 } from "../chunk-UOV2BYIW.js";
-import "../chunk-EYPA3EGJ.js";
-import "../chunk-WHGPSPT5.js";
+import "../chunk-PMDBGQSJ.js";
+import "../chunk-XN3L4EYL.js";
+import "../chunk-SPULKLCF.js";
+import "../chunk-KTYTFRMB.js";
+import "../chunk-ZVJ5BLO2.js";
+import "../chunk-VG7TBQIY.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
   DEFAULT_ESCALATION_TIMEOUT_MS,
@@ -50,22 +54,38 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-XXQNGV4M.js";
-import "../chunk-43AOLP7E.js";
+} from "../chunk-A3WNZD3P.js";
+import "../chunk-5FR74PWO.js";
+import "../chunk-P43ETTHK.js";
+import "../chunk-H7IXIC72.js";
+import {
+  createSafetyPolicyEngine
+} from "../chunk-5H3GB5BO.js";
+import "../chunk-A2NJGIB3.js";
+import "../chunk-OQE5J4C6.js";
+import {
+  agentSkillToolPolicy
+} from "../chunk-GOXNB3AO.js";
+import {
+  DEFAULT_AUTONOMY_LEVEL
+} from "../chunk-HWUFFB6L.js";
 import {
   RESULT_CONTRACT_REPAIR_LIMIT,
-  createSafetyPolicyEngine,
-  parseResultContract,
+  parseWorkerResultContract,
   resultContractRepairMessages,
   validateResultContract
-} from "../chunk-EKY57CSP.js";
-import "../chunk-22NAGB7X.js";
+} from "../chunk-TTHACPOM.js";
 import {
   classify
 } from "../chunk-AOCYTWAV.js";
 import {
   protectedArtifactMutationBlockReason
 } from "../chunk-MV3K5QF2.js";
+import "../chunk-UL3WSD3F.js";
+import "../chunk-ODFEOB4F.js";
+import "../chunk-OZNBF4L3.js";
+import "../chunk-4BJ5BYCE.js";
+import "../chunk-ECH6PKUQ.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -85,23 +105,6 @@ import {
   deleteInjectedCompileCacheFrom
 } from "../chunk-I4HZDVNP.js";
 import "../chunk-ZI647VB5.js";
-import "../chunk-NILBFAPG.js";
-import "../chunk-FYYLNIL5.js";
-import "../chunk-UL3WSD3F.js";
-import "../chunk-XN3L4EYL.js";
-import "../chunk-VG7TBQIY.js";
-import "../chunk-OQE5J4C6.js";
-import "../chunk-ECH6PKUQ.js";
-import "../chunk-SPULKLCF.js";
-import {
-  agentSkillToolPolicy
-} from "../chunk-GOXNB3AO.js";
-import {
-  DEFAULT_AUTONOMY_LEVEL
-} from "../chunk-HWUFFB6L.js";
-import "../chunk-ODFEOB4F.js";
-import "../chunk-OZNBF4L3.js";
-import "../chunk-4BJ5BYCE.js";
 import "../chunk-6XLNIQDB.js";
 import "../chunk-5B2AEOW5.js";
 import {
@@ -111,56 +114,63 @@ import "../chunk-65DEGPJ6.js";
 import {
   FileKnowledgeBase,
   applyModelCapabilityPatch,
-  getRuntimeRegistry,
   loadPluginRuntimes,
-  registerBuiltinRuntimes,
   registerClioApiProviders,
   resolveModelRuntimeCapabilitiesForModel,
   resolveProviderKnowledgeBaseRoots,
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-DJVECN66.js";
+} from "../chunk-7RFXX52T.js";
 import "../chunk-CFGTUFWB.js";
-import {
-  readSettings,
-  validateSettingsFile
-} from "../chunk-AD2SYQYC.js";
-import "../chunk-4OC57DA6.js";
-import "../chunk-LL4KHSZI.js";
-import "../chunk-4VP4KH3K.js";
+import "../chunk-LU7P4LHA.js";
+import "../chunk-RWSI4YD7.js";
+import "../chunk-IHXBNWMM.js";
 import {
   setGitCommitAttributionEnabled,
   withManagedGitCommitAttributionEnvironment
-} from "../chunk-VEZEGCGW.js";
+} from "../chunk-B5CSFE7B.js";
+import {
+  readSettings,
+  validateSettingsFile
+} from "../chunk-IJ7RPIYJ.js";
 import "../chunk-FQ4SKYE4.js";
-import "../chunk-IKCO5N3L.js";
-import "../chunk-3I7MS7N2.js";
-import "../chunk-IHXBNWMM.js";
-import "../chunk-GEYXPTRF.js";
-import "../chunk-SST6Z5JA.js";
-import "../chunk-FO5ZOVUY.js";
+import "../chunk-ZGVHUX3M.js";
+import "../chunk-TT36MB5S.js";
+import "../chunk-3BINW3FP.js";
 import "../chunk-R346GLFC.js";
+import {
+  AI_AGENT_NAME
+} from "../chunk-6EJMN2Y3.js";
+import {
+  readClioVersion
+} from "../chunk-IWHMRKLL.js";
+import {
+  registerBuiltinRuntimes
+} from "../chunk-NMPKI6XL.js";
+import "../chunk-4DGYLA73.js";
+import "../chunk-LL4KHSZI.js";
 import {
   configureGuardrails,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
 } from "../chunk-4ZG3XFUR.js";
-import {
-  registerFauxFromEnv
-} from "../chunk-FCSXB6T2.js";
+import "../chunk-IIZWH4XA.js";
+import "../chunk-EQ63NRB7.js";
+import "../chunk-SST6Z5JA.js";
+import "../chunk-IKCO5N3L.js";
+import "../chunk-3I7MS7N2.js";
 import "../chunk-APJ265NV.js";
-import "../chunk-YXLYO42X.js";
 import "../chunk-BNAZZHFG.js";
-import {
-  AI_AGENT_NAME
-} from "../chunk-6EJMN2Y3.js";
 import "../chunk-WEPFGWHJ.js";
-import "../chunk-ZGVHUX3M.js";
-import "../chunk-G7MUEIGA.js";
 import {
-  readClioVersion
-} from "../chunk-IWHMRKLL.js";
+  getRuntimeRegistry
+} from "../chunk-NUGM5KR6.js";
+import "../chunk-PT7HYKEM.js";
+import {
+  registerFauxFromEnv
+} from "../chunk-FCSXB6T2.js";
+import "../chunk-YXLYO42X.js";
 import {
   init_esm_shims
 } from "../chunk-3R73A4XB.js";
@@ -940,7 +950,7 @@ function resolveWorkerRuntimeBudget(input) {
 }
 function startWorkerRun(input, emit) {
   assertResponseSchemaRuntime(input);
-  if (input.resultContract !== void 0) parseResultContract(input.resultContract, "WorkerSpec.resultContract");
+  if (input.resultContract !== void 0) parseWorkerResultContract(input.resultContract, "WorkerSpec.resultContract");
   if (input.runtime.id === "claude-sdk") {
     return startClaudeSdkWorkerRun(input, emit);
   }

package/docs/README.md

@@ -4,7 +4,7 @@
 
 # Clio Coder Documentation
 
-These pages document `v0.3.6` of Clio Coder, an open-source coding orchestrator within the [IOWarp](https://iowarp.ai) scientific computing platform, created by the [Gnosis Research Center](https://grc.iit.edu) at the [Illinois Institute of Technology](https://www.iit.edu).
+These pages document `v0.3.7` of Clio Coder, an open-source coding orchestrator within the [IOWarp](https://iowarp.ai) scientific computing platform, created by the [Gnosis Research Center](https://grc.iit.edu) at the [Illinois Institute of Technology](https://www.iit.edu).
 
 They are source-aligned guides: when prose and source disagree, prefer the
 current source, tests, and `CHANGELOG.md`.
@@ -39,6 +39,7 @@ current source, tests, and `CHANGELOG.md`.
 | Advisory validation-contract patterns for scientific artifacts and HPC assumptions | [scientific-validation.md](scientific-validation.md) ([Interactive Blueprint](html/validation_blueprint.html)) |
 | Falsifiable Change Manifest JSON templates, auditability, and `clio-coder evolve` | [evolution.md](evolution.md) ([Interactive Blueprint](html/evolution_blueprint.html)) |
 | Source-first docs workflow, mapping matrix, and alpha wording guidance | [documentation-guide.md](documentation-guide.md) ([Interactive Blueprint](html/documentation_blueprint.html)) |
+| Typed resource catalogs, private synchronization, installation roots, and library CLI | [resource-library.md](resource-library.md) |
 | Interface layout, colors palette, Unicode character vocabulary, and drawing choreography | [tui-design.md](tui-design.md) ([Interactive Blueprint](html/tui_design_blueprint.html)) |
 | NDJSON parent-child socket protocols, watchdog timers, and exit status mapping | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) ([Interactive Blueprint](html/worker_dispatch_blueprint.html)) |
 | Multi-node fleet dispatch: process-safe admission, attested workers, measured routing, activation, agent automation, topologies, and receipts | [fleet-dispatch.md](fleet-dispatch.md) ([Interactive Blueprint](html/fleet_dispatch_blueprint.html)) |
@@ -83,7 +84,7 @@ under `src/`, run `npm run build` again or keep `npm run dev` running.
 ## Release Notes
 
 The release entry point is [../README.md](../README.md); detailed release
-history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.3.6 the supported
+history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.3.7 the supported
 install paths are `npm install -g @iowarp/clio-coder` and a source checkout
 through `npm run install:local`, the deterministic release gate is
 `npm run ci:release`, and live model smoke validation is local/manual and

package/docs/acp.md

@@ -1,6 +1,6 @@
 # Agent Client Protocol (ACP) Server
 
-This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in `v0.3.6`.
+This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in `v0.3.7`.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 

package/docs/alcf-provider.md

@@ -1,7 +1,7 @@
 # ALCF Inference Provider
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive target configurator and Globus OAuth flow diagram is located at [docs/html/alcf_blueprint.html](html/alcf_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive target configurator and Globus OAuth flow diagram is located at [docs/html/alcf_blueprint.html](html/alcf_blueprint.html) (Version: 0.3.8).
 
 Clio can use Argonne's ALCF inference gateway as an OpenAI-compatible target
 backed by Globus OAuth. The runtime id is `alcf`; each configured target points

package/docs/architecture.md

@@ -1,11 +1,11 @@
 # Clio Coder Architecture and Boundaries
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.3.8).
 
 Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
 
-This page is source-code aligned for the current `v0.3.6` development line.
+This page is source-code aligned for the current `v0.3.7` development line.
 
 ---
 

package/docs/artifact-versions.md

@@ -1,6 +1,6 @@
 # Artifact Versions & Serialization Contracts
 
-This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.3.6`.
+This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.3.8`.
 
 ---
 
@@ -10,23 +10,28 @@ Clio Coder strictly versions every persistent or network-transported data struct
 
 | Artifact / Subsystem | Current Version | Symbol / Type & Source Location | Persisted Path / Wire Location | Schema Semantics & Version Differences | Mismatch Handling |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| **Run Receipt** | `15` | `RUN_RECEIPT_INTEGRITY_VERSION = 15`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 15 covers all base provenance fields, routing intent, quality labels, `validationGrounding`, and `capabilityMismatch`. | Fail-closed. Incompatible receipts fail verification and are never read as evidence. |
+| **Run Receipt** | `20` | `RUN_RECEIPT_INTEGRITY_VERSION = 20`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 20 adds `pathProvenance` on dispatch intent and the resolved `pathScope`, over the v19 base of provenance fields, routing intent, quality labels, `validationGrounding`, `capabilityMismatch`, council provenance, and fleet gate provenance. | Fail-closed. A receipt below v20 is reported as retired rather than invalid, is never read as evidence, and is never migrated; a malformed or tampered v20 receipt fails verification. |
 | **Session Ledger** | `3` | `CURRENT_SESSION_FORMAT_VERSION = 3`<br>`src/engine/session.ts:66` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. | Automated migration via `src/domains/session/migrations/` on `/resume`. Earlier unmigratable versions rejected. |
 | **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:22` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
 | **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:23` | Worker attestation descriptor payload | Attestation descriptor for worker runtime environment and hardware facts. | Attestation mismatch causes immediate process termination. |
 | **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:24` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
-| **Fleet Contract** | `1 \| 2 \| 3 \| 4` (Current: `4`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`src/domains/agents/fleet-contract.ts:37, 140` | `.clio-coder/fleets/<name>.yaml`, `.clio-coder/fleets/<name>.yml`, or built-in recipes | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops (`FLEET_LOOP_MAX_ATTEMPTS = 5`) and commit steps; v4 adds declared per-step write boundaries (`writes`). | Reader refuses contracts whose version features it does not support. |
+| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | `.clio-coder/fleets/<name>.yaml`, `.clio-coder/fleets/<name>.yml`, or built-in recipes | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the single-writer declaration. | Reader refuses contracts whose version features it does not support. |
 | **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:98` | Statically compiled DAG representation in dispatch memory and receipts | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | Preflight validation rejects unsupported plan versions. |
 | **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts:51-52` | `<stateDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. Note: `EVAL_ARTIFACT_VERSION = 1` in `src/domains/eval/types.ts:2` is legacy/dead code. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
 | **Trace Database** | `1` | `TRACE_SCHEMA_VERSION = 1`<br>`src/domains/observability/trace-store.ts:23` | `<stateDir>/trace.sqlite` (`meta` table `schema_version`) | Schema version for the 7 SQLite trace mirror tables (`runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, `processes`). | Log warning (`[clio:trace]`), trace writing degrades without failing the parent run. |
 | **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:40` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and cross-process lock state. | Corrupted or unparseable state file causes admission to fail closed. |
 | **Protected Artifact Journal** | `1` | `version: 1` in `interface PendingProtectedArtifactRecord`<br>`src/domains/session/protected-artifact-journal.ts:22` | `<stateDir>/protected-artifact-pending/<key>/<id>.json` | Write-ahead durability records for pending protected artifacts. | Leftover records reconciled during session initialization. |
+| **Fleet Run Record** | `1` | `version: 1` in `interface FleetRunRecord`<br>`src/domains/dispatch/fleet-run.ts` | `<stateDir>/fleet-runs/<runId>.json` | Durable record of one fleet run: contract name, plan hash, static step ids and steps, `--var` values, replayed and settled step results, and the delegation plan hash a `kind: plan` step produced. Read by `fleet run --resume`. | Resume refuses a changed plan hash with a per-step diff and refuses differing `--var` values. |
+| **Durable Assignment Store** | `1` | `version: 1` in `interface AssignmentStoreFile`<br>`DurableAssignmentRecord`<br>`src/domains/dispatch/assignment-store.ts` | `<stateDir>/assignments.json` | Machine-wide logical-dispatch records: assignment id, attempt ids, terminal run id, status, optional fleet verdict owner, and—while running—`processOwner {pid, processBirthToken, acquiredAt}`. The owner is cleared on a true terminal transition. | A live sibling owner keeps the row running; a genuinely dead or legacy ownerless row is reconciled. An unsupported or unreadable store is treated as empty, and malformed records are ignored. |
+| **Checkout Writer Lease** | `1` | `version: 1` in `interface CheckoutWriterLeaseRecord`<br>`src/domains/dispatch/checkout-writer-lease.ts` | `<stateDir>/checkout-writer-leases/<key>.json` (key derived from the canonical checkout path) | Cross-process single-writer lease: checkout path, pid, process birth token, acquisition time. | A live sibling holder is refused with `checkout_writer_lease_held`; a dead owner is reclaimed; a malformed record is treated as absent. |
+| **Out-of-turn Usage Ledger** | unversioned JSONL | `OutOfTurnUsageRow`<br>`src/domains/observability/out-of-turn-usage.ts` | `<stateDir>/usage/out-of-turn.jsonl` | One row per priced `/btw` or `/handoff` call: label, session id, repo identity, timestamp, target, attributed model, provider usage. Bounded ring of `MAX_OUT_OF_TURN_USAGE_ROWS = 1000`, rewritten atomically under the state-file lock. | Unparseable rows are skipped and counted by `usage report`; the session ledger is never affected. |
+| **Library Pins** | unversioned YAML map | `readLibraryPins`<br>`src/domains/resources/library.ts` | `<configDir>/library-pins.yaml` | Typed ref (`skill:x`, `agent:y`, `prompt:p`, `fleet:z`) to `{sha256, sourceUrl}` for every resource `library add` or the Skills Hub installed. | A non-map document reads as empty; an entry whose installed file is missing is reported as available, not installed. |
 
 ---
 
 ## 2. Integrity Verification Contracts
 
-### Receipt Integrity (Version 15)
+### Receipt Integrity (Version 20)
 
 Receipt integrity authenticates that a sealed receipt matches its ledger envelope without modification. Verification reproduces the canonical JSON serialization and computes the SHA-256 digest:
 
@@ -38,9 +43,9 @@ export function computeReceiptDigest(receipt: RunReceiptV15): string {
 ```
 
 Receipt verification checks:
-1. `integrity.version === 15`.
+1. `integrity.version === 20`. A receipt sealed at a lower version is reported as retired rather than invalid: it is intact, but is not read as evidence and is never migrated.
 2. Calculated SHA-256 matches `integrity.digest`.
-3. All optional fields present in the schema (`validationGrounding`, `capabilityMismatch`, `steering`, `gate`, `plan`, `briefing`) conform to the strict v15 specification.
+3. All optional fields present in the schema (`validationGrounding`, `capabilityMismatch`, `steering`, `gate`, `fleetGate`, `council`, `plan`, `briefing`) conform to the strict v20 specification.
 
 ---
 

package/docs/built-in-agents.md

@@ -3,7 +3,7 @@
 Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, mode, tools, optional target/model hints, and thinking level; the Markdown body is the agent instruction text.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.3.8).
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.
 
@@ -34,7 +34,7 @@ Recipe IDs are derived from filenames (e.g., `architect.md` -> `architect`). Rec
 *   **Built-in Protection**: Project agents cannot override any shipped built-ins; they are strictly treated as custom/domain agents.
 *   **Reserved IDs**: The IDs `worker` and `delegate` are strictly reserved for custom/internal contexts and cannot be registered as custom agent IDs.
 *   **Local Ignored Custom Examples**: Local examples (e.g., `benchmark-runner`, `clio-dev`, `implementer`, `scientific-validator`) may exist under `.clio-coder/agents` for documentation or test purposes, but are ignored if they collide with reserved/built-in rules.
-*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Project-level fleet contracts placed at `.clio-coder/fleets/<name>.md` shadow builtin fleets of the same name. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`. Contract v4 requires per-step write boundaries (`writes`).
+*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Library-installed contracts live at `<configDir>/fleets/<name>.md`. Project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`. Contract v4 requires per-step write boundaries (`writes`).
 
 ---
 
@@ -64,12 +64,36 @@ Internal orchestration helpers and internal process agents. They are hidden from
 | `scout` | read, grep, find, ls, context, code_nav, git | Broad repository reconnaissance, codebase orientation, structure and entry-point mapping, and multi-file symbol hunting. | `read-only` | `fast` |
 | `researcher` | read, web_fetch, context | Shadow docs and external-source researcher for coding decisions. | `read-only` | `deep` |
 | `provenance` | read, grep, find, ls, git | Shadow evidence, receipt, diff, and telemetry reader for handoffs. | `read-only` | `balanced` |
+| `oracle` | read, grep, find, ls, code_nav, context | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
 | `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 
+The builtin `architect` also serves as the default author for a version 5 fleet `plan` step. In that role it returns the coordinator-owned `delegation-plan` result shape instead of writing its ordinary plan artifact. It may name only agents from the contract roster. The coordinator supplies the plan step's target or profile to every admitted task.
+
 `scout` is bound by a live-grounding contract: its whole final response is one `scout-report` object whose every finding carries the `claim` it observed and the `path:line` that grounds it, a lead it could not confirm live is simply left out, and wiki or index content is orientation only, never citable as evidence. It has an 18-call exploration phase followed by a tool-free synthesis phase; wide parallel batches cannot consume the synthesis backstop as separate violations. Dispatch labels its answer `reconnaissance output (advisory leads, not validation evidence):`.
 
 Grounding is checked against the run's own reads, not just against the file. The worker records the exact line span every successful read returned, and a cited line must fall inside one. A line that exists in the file but was never read fails, which is what stops an approximated or inferred line number from passing as observation. `grep` and `code_nav` hits are leads: read the file before citing what they point at.
 
+`oracle` is the only shadow agent an operator reaches directly, and only through
+`/oracle <question>`. It never receives a forked transcript. `/oracle` packs a
+bounded digest instead and sends it as dispatch briefing data: the settled
+decisions from the session decision board, the open tasks from the task board,
+the last compaction summary when one exists, and the question. The digest is
+capped at 12 KiB total, with per-section caps of 5120 bytes and 24 rows for
+decisions, 3072 bytes and 24 rows for open tasks, 2048 bytes for the compaction
+summary, and 1536 bytes for the question. Every cap that cuts content appends a
+`[truncated]` marker, so an advisor always knows it is reading a tail-less
+record. Entries are filtered to the active branch before the fold, so a `/tree`
+switch never briefs the advisor on decisions the operator walked away from.
+
+The run is an ordinary singular dispatch with `requestOrigin: "internal"` and
+`autonomy: "read-only"`, so admission, receipts, and the Fleet Runs island apply
+to it exactly as they apply to `/run`. Its `oracle-report` contract carries the
+answer shape: a verdict line, the strongest challenge the advisor can mount, the
+evidence that would change its mind, and the decisions it cited. The rendered
+answer reaches the main agent the way `/share` puts a worker result there, as an
+operator-authored note on the ordinary user-turn path. `/oracle` during an
+in-flight turn is refused rather than queued.
+
 Every contract-bearing agent gets bounded in-worker repair. When the terminal result misses its contract, the worker replays the validator's own reason, the exact accepted shape, and the `path:line` locations this run actually read, then asks for the result again. Two repair rounds is the whole allowance; after that the run fails with `result_contract_exhausted`. This is what keeps a small local model that gathered the right evidence from being failed for a shape mistake nobody told it about.
 
 Two rounds only help when the reason is actionable, so a validator reason names the mistake and shows the value that would have passed. A `mutation-report` with `"validations":[]` is told the array was empty and is given one entry shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, and a report whose entries are malformed is told which keys each entry carries. Naming the requirement alone left a small model re-emitting the same empty array through both rounds.

package/docs/capacity-and-scheduling.md

@@ -1,6 +1,6 @@
 # Capacity Leases & Fleet Scheduling
 
-This document specifies the multi-process capacity leasing protocols, node scheduling models, cross-process transaction locks, and failure recovery mechanics implemented in Clio Coder `v0.3.6`.
+This document specifies the multi-process capacity leasing protocols, node scheduling models, cross-process transaction locks, and failure recovery mechanics implemented in Clio Coder `v0.3.7`.
 
 Source implementations: `src/domains/scheduling/` and `src/domains/dispatch/capacity-lease.ts`.
 

package/docs/commands-and-modes.md

@@ -1,7 +1,7 @@
 # Commands and Modes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.3.6).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.3.8).
 
 
 Clio Coder is a terminal-first alpha harness. This page keeps the command
@@ -131,7 +131,7 @@ Example:
 clio-coder run \
   "Find the test command and summarize the project structure." \
   --target local-lmstudio \
-  --model your-model-id
+  --model qwen3.8-27b
 ```
 
 ## Interactive Slash Commands
@@ -145,17 +145,21 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/quit` | `/quit` | Exit Clio Coder |
 | `/help` | `/help [query]` | Open the interactive help center showing commands and keys |
 | `/skill` | `/skill [name] [task]` | Open the Skills Hub or invoke a skill |
+| `/library` | `/library [kind]` | Open the Skills Hub on a resource library tab |
 | `/prompts` | `/prompts` | List prompt templates |
 | `/extensions` | `/extensions` | List installed extensions |
 | `/interop` | `/interop` | Review other coding agents detected on this machine |
 | `/share` | `/share [runId] \| /share export <path> \| /share import [--dry-run] [--force] <path>` | Share a worker result with the main agent, or export and import Clio archives |
 | `/run` | `/run [--agent-profile <profile>] [--runtime <runtimeId>] [--target <id>] [--model <id>] [--thinking <level>] [--tool-profile <minimal-local\|science-local\|full-agent>] [--require <cap>] [--share] <agent> <task>` | Run a fleet agent |
 | `/delegate` | `/delegate [--share] <agent-id> <task>` | Run an ACP delegation agent |
+| `/btw` | `/btw <question>` | Ask a side question that never enters the session transcript |
+| `/oracle` | `/oracle <question>` | Ask a read-only advisor to challenge a question against this session's settled decisions |
+| `/council` | `/council [--roster <name>] [--rounds <n>] [--synthesis <judge\|vote\|none>] <task>` | Ask a roster of read-only members the same task, with an optional vote or judge synthesis |
 | `/agents` | `/agents` | List Clio agents and ACP delegation agents |
 | `/targets` | `/targets` | Open Settings → Targets: health, use, connect, probe, remove |
 | `/cost` | `/cost` | Show session token and cost totals |
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
-| `/fleet` | `/fleet` | Open Settings → Fleet: defaults, profiles, agent bindings, nodes |
+| `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
 | `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
 | `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
@@ -167,6 +171,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/settings` | `/settings [section]` | Open interactive settings |
 | `/resume` | `/resume` | Resume a past session |
 | `/new` | `/new` | Start a fresh session |
+| `/handoff` | `/handoff <goal>` | Hand this session's working state to a fresh session for a stated goal |
 | `/tree` | `/tree` | Open session tree navigator |
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
@@ -190,6 +195,72 @@ There are no slash-command aliases. `/context compact`, `/quit`, `/model`,
 spellings stay errors that name `/help` instead of guessing which operation the
 operator intended.
 
+`/btw <question>` runs one model round beside the session and renders the answer
+in an overlay. It sends the same compiled message history the next turn would
+send, as read-only input, under a short system instruction saying this is a side
+question, with no tools. Nothing about the round is appended: not the session
+JSONL, not the transcript panel, not the context ledger, not the task board. That
+is the point of it. A fleet run briefs its workers from the transcript, so a
+question the operator asks to orient themselves mid-run would otherwise become
+context every worker inherits. Esc closes the overlay, and cancels the round if it
+is still streaming. `/btw` during an in-flight turn is refused with a notice
+rather than queued, because a side question answered after the run it was asked
+during has already missed its moment. The round's token usage still shows in
+`/cost`, labeled as a side question, because it was a real call and cost real
+money; it is deliberately not counted as a turn.
+
+`/council [--roster <name>] [--rounds <n>] [--synthesis judge|vote|none] <task>`
+asks a roster of two to five read-only members the same task and puts the group on
+the Fleet Runs board as one card. It owns no dispatch path of its own: the command
+builds dispatch-tool arguments and admits them through the tool registry, so a
+supervised autonomy level parks the call and the approval overlay names every
+member's label, target, model, node, round count, and synthesis mode before
+anything runs. Members are pinned to read-only autonomy and the council tool
+surface by admission, exactly as they are for a council the model asks for.
+
+`--roster` names a `workers.rosters` entry. Without it the command takes
+`workers.rosters.default` when that roster exists, and with neither it refuses
+and names the setting to declare. A roster that is the only one configured is
+still not the default: seating a council from whichever roster happens to be
+present would run models the operator never chose. `--rounds` accepts one to
+three and `--synthesis` accepts `judge`, `vote`, or `none`, which are the tool's
+own bounds, enforced where the operator typed them so a council is never refused
+after its plan has already been shown. `/council` during an in-flight turn is
+refused with a notice rather than queued, for the same reason `/fleet run` is: an
+approved plan describes the workspace as it stands. Nothing the members produce
+enters the main agent's context until an operator runs `/share`.
+
+`/handoff <goal>` carries this session's working state into a fresh session for a
+goal the operator states. The goal is required and gated: a goal shorter than 12
+characters is refused, and so is one of a small stoplist of non-goals such as
+"continue", "next", or "resume". Both refusals name the rule they enforce, because
+"keep going" is exactly the instruction a handoff exists to replace.
+
+One model round then runs on the same out-of-turn seam `/btw` uses. It reads the
+compiled message history the next turn would send, sends no tools, and answers
+with JSON validated against a fixed response schema of decisions, facts, files,
+commands, and open questions. Every list and every string is bounded; output over
+a bound is truncated with a visible marker and the document names each bound that
+fired, so nothing is cut silently and an over-eager answer is never a refusal.
+
+Every file path the model names is checked against this session's read ledger and
+never against the filesystem. Paths the session did not touch are dropped and
+listed in the document under their own heading so the operator can see what the
+model invented. Extracted decisions are merged with the session's settled decision
+board, and the board wins. The result is one Markdown document opened for review:
+Enter accepts it, `e` hands it to `$EDITOR`, and Esc cancels the whole handoff with
+nothing written anywhere.
+
+On accept, Clio mints a new session, writes the reviewed document into it as
+bounded data labelled as a handoff from the old session id, and replays the old
+session's skill activations so loaded skills carry forward. The document is never
+written as a fabricated user turn. The old session is left untouched apart from one
+terminal note recording the target session id. A handoff is a session operation
+throughout: it writes no memory promotion candidate and never calls the task-memory
+bank. `/handoff` during an in-flight turn is refused with a notice rather than
+queued, because a document summarizing a session that is still moving would be
+wrong by the time it was read.
+
 The `/resume` picker accepts Page Up and Page Down to move by its 12 visible rows. Arrow keys continue to move one session at a time, and typing continues to filter the list.
 
 Only active commands run. Typing anything command-shaped that the registry does
@@ -256,6 +327,15 @@ operator steering whose run id names a receipt it can read, so a model that
 never dispatched the run does not discard it as unattributed output. A turn
 that only relays a shared note does not trip the unbacked-worker-claim
 advisory.
+A council run shares as a council. `/share <synthesis runId>` brings the whole
+`council-report` in as one bounded block: every final-round member's answer under
+its roster label, each with its verdict when it declared one, then the synthesis
+line naming the mode, the verdict, the tally, and the judge run when there was
+one. `/share <member runId>` brings that one member's answer in under its roster
+label, so a single voice never reaches the main agent as an unattributed one. A
+synthesis run whose sealed text does not parse as a report is shared verbatim
+rather than dropped, because the operator named that run.
+
 `/new` resets the transcript and the pool bare `/share` draws from, so a run
 from the previous session cannot be shared into the new one. Worker tool
 arguments never cross at all: the transcript carries tool names only, the same