@iowarp/clio-coder 0.3.4 → 0.3.7

package/dist/worker/entry.js

@@ -6,7 +6,6 @@ import {
   createLoopGuardRegistration,
   createProtectedArtifactsRegistration,
   createRegistry,
-  describeCallTarget,
   effectiveToolNames,
   isLoopGuardSynthesisBackstopReason,
   isReserveAdmittedTool,
@@ -17,13 +16,13 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-VMNQ6OZA.js";
+} from "../chunk-QCTRSGHQ.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-2LZI5CAG.js";
+} from "../chunk-XEGB6BCN.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
@@ -34,8 +33,8 @@ import {
   createLoopState,
   observe
 } from "../chunk-UOV2BYIW.js";
-import "../chunk-EDRHSCIE.js";
-import "../chunk-2TZWSW76.js";
+import "../chunk-EELBMBT6.js";
+import "../chunk-WHGPSPT5.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
   DEFAULT_ESCALATION_TIMEOUT_MS,
@@ -43,6 +42,7 @@ import {
   claudeToolsOutsideProfile,
   coerceToolInput,
   createRunEffectsRecorder,
+  describeCallTarget,
   emitClaudeToolPermissionDecision,
   isClaudeCodeSessionId,
   parseWorkerSpec,
@@ -50,23 +50,13 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-ZYKPLLNQ.js";
-import "../chunk-WPQLXFOZ.js";
-import {
-  DEFAULT_AUTONOMY_LEVEL,
-  RESULT_CONTRACT_REPAIR_LIMIT,
-  createSafetyPolicyEngine,
-  parseResultContract,
-  resultContractRepairMessages,
-  validateResultContract
-} from "../chunk-7RXG6QRZ.js";
-import "../chunk-22NAGB7X.js";
+} from "../chunk-CEYBNUGC.js";
+import "../chunk-5FR74PWO.js";
 import {
-  classify
-} from "../chunk-AOCYTWAV.js";
-import {
-  protectedArtifactMutationBlockReason
-} from "../chunk-MV3K5QF2.js";
+  createSafetyPolicyEngine
+} from "../chunk-OBMAI2DP.js";
+import "../chunk-5C77SEEY.js";
+import "../chunk-UND3GU2L.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -86,20 +76,35 @@ import {
   deleteInjectedCompileCacheFrom
 } from "../chunk-I4HZDVNP.js";
 import "../chunk-ZI647VB5.js";
-import "../chunk-NILBFAPG.js";
-import "../chunk-FYYLNIL5.js";
-import "../chunk-UL3WSD3F.js";
+import "../chunk-JNXPYBB4.js";
+import "../chunk-GH5622CP.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-BEY543CS.js";
-import "../chunk-5M54SPOL.js";
+} from "../chunk-GOXNB3AO.js";
+import {
+  DEFAULT_AUTONOMY_LEVEL
+} from "../chunk-HWUFFB6L.js";
+import {
+  RESULT_CONTRACT_REPAIR_LIMIT,
+  parseResultContract,
+  resultContractRepairMessages,
+  validateResultContract
+} from "../chunk-DJNLUABN.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 "../chunk-6XLNIQDB.js";
 import "../chunk-5B2AEOW5.js";
 import {
@@ -118,32 +123,32 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-QWU7ZBO7.js";
+} from "../chunk-VQNODYQ4.js";
 import "../chunk-CFGTUFWB.js";
+import "../chunk-JRIO5UD2.js";
+import "../chunk-IHXBNWMM.js";
+import "../chunk-GEYXPTRF.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-AD2SYQYC.js";
-import "../chunk-4OC57DA6.js";
+} from "../chunk-UHXRNZ2J.js";
+import "../chunk-4DGYLA73.js";
 import "../chunk-LL4KHSZI.js";
-import "../chunk-4VP4KH3K.js";
+import "../chunk-SST6Z5JA.js";
+import "../chunk-FO5ZOVUY.js";
+import "../chunk-R346GLFC.js";
 import {
   setGitCommitAttributionEnabled,
   withManagedGitCommitAttributionEnvironment
-} from "../chunk-VEZEGCGW.js";
+} from "../chunk-D4MDIG46.js";
 import "../chunk-FQ4SKYE4.js";
-import "../chunk-IKCO5N3L.js";
-import "../chunk-3I7MS7N2.js";
-import "../chunk-IHXBNWMM.js";
-import "../chunk-BPGS2WCQ.js";
-import "../chunk-SST6Z5JA.js";
-import "../chunk-FO5ZOVUY.js";
-import "../chunk-R346GLFC.js";
 import {
   configureGuardrails,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
 } from "../chunk-4ZG3XFUR.js";
+import "../chunk-IKCO5N3L.js";
+import "../chunk-3I7MS7N2.js";
 import {
   registerFauxFromEnv
 } from "../chunk-FCSXB6T2.js";
@@ -155,7 +160,7 @@ import {
 } from "../chunk-6EJMN2Y3.js";
 import "../chunk-WEPFGWHJ.js";
 import "../chunk-ZGVHUX3M.js";
-import "../chunk-TTNYS3EA.js";
+import "../chunk-OB5HIGJY.js";
 import {
   readClioVersion
 } from "../chunk-IWHMRKLL.js";
@@ -574,9 +579,10 @@ function permissionResultForDecision(decision, toolUseID, input) {
   if (toolUseID !== void 0) result.toolUseID = toolUseID;
   return result;
 }
-function decideToolUse(input, toolName, toolInput) {
+function decideToolUse(input, toolCallId, toolName, toolInput) {
   return emitClaudeToolPermissionDecision({
     toolName,
+    ...toolCallId !== void 0 ? { toolCallId } : {},
     input: coerceToolInput(toolInput),
     safety: input.safety,
     cwd: input.cwd,
@@ -598,7 +604,7 @@ function decideToolUseOnce(input, toolUseID, toolName, toolInput) {
   return decideClaudeSdkToolUseOnce(
     input.handledToolDecisions,
     toolUseID,
-    () => decideToolUse(input, toolName, toolInput)
+    () => decideToolUse(input, toolUseID, toolName, toolInput)
   );
 }
 function buildCanUseTool(input) {
@@ -977,6 +983,36 @@ function startWorkerRun(input, emit) {
   const deliveryTools = resolveDeliveryTools(input.allowedTools, input.product);
   const middlewareToolChoice = createMiddlewareToolChoiceControl();
   let workerModelRound = 0;
+  const loopGuardRegistration = createLoopGuardRegistration({
+    safety,
+    toolCallCap: workerBudget.hardCap,
+    toolCallSoftLimit: workerBudget.toolCalls,
+    // A worker's blocks all land in one run-long bucket, so the bound on
+    // them is a statement about this run's length, not about a turn.
+    turnBlockBudget: workerLoopBlockBudget(workerBudget.revision?.toolCalls ?? workerBudget.toolCalls),
+    toolCallSoftReadReserve: readReserve,
+    ...deliveryTools.length > 0 ? { deliveryTools } : {},
+    turnSynthesisLockout: workerBudget.synthesis,
+    // Once locked, the next model round is forced text-only at the
+    // request level. The lockout directive alone relies on model compliance.
+    onSynthesisLockout: () => {
+      if (workerBudget.synthesis) synthesisToolLock = true;
+    },
+    ...!workerBudget.synthesis ? {
+      onSoftLimitFinalCallAdmitted: (toolCallId) => {
+        if (workerBoundFailure === null) {
+          workerBoundFailure = `worker agent budget reached (${workerBudget.toolCalls}); synthesis is disabled`;
+        }
+        stopAfterToolResultCallId = toolCallId ?? STOP_AFTER_ANY_TOOL_RESULT;
+      }
+    } : {},
+    // Requiring read is correct only when reading is the whole reserve.
+    ...readReserve > 0 && deliveryTools.length === 0 ? {
+      onSoftReadReserve: () => {
+        middlewareToolChoice.apply([{ kind: "require_tool", toolName: ToolNames.Read }]);
+      }
+    } : {}
+  });
   const registry = createWorkerToolRegistry(
     input.middlewareSnapshot,
     safety,
@@ -995,45 +1031,7 @@ function startWorkerRun(input, emit) {
     // and has no persistence sink. It can still absorb worker-local
     // protect_path effects from snapshot rules for the rest of this run.
     [
-      createLoopGuardRegistration({
-        safety,
-        toolCallCap: workerBudget.hardCap,
-        toolCallSoftLimit: workerBudget.toolCalls,
-        // A worker's blocks all land in one run-long bucket, so the bound on
-        // them is a statement about this run's length, not about a turn.
-        turnBlockBudget: workerLoopBlockBudget(workerBudget.toolCalls),
-        toolCallSoftReadReserve: readReserve,
-        ...deliveryTools.length > 0 ? { deliveryTools } : {},
-        turnSynthesisLockout: workerBudget.synthesis,
-        // Once locked, the next model round is forced text-only at the
-        // request level (the tool surface is removed in onPayload below):
-        // the lockout directive alone relies on model compliance, and
-        // measured local models kept calling tools until the backstop
-        // aborted the run, or answered the forced round with tool-call
-        // markup that the loop guard then removed.
-        onSynthesisLockout: () => {
-          if (workerBudget.synthesis) {
-            synthesisToolLock = true;
-          }
-        },
-        ...!workerBudget.synthesis ? {
-          onSoftLimitFinalCallAdmitted: (toolCallId) => {
-            if (workerBoundFailure === null) {
-              workerBoundFailure = `worker agent budget reached (${workerBudget.toolCalls}); synthesis is disabled`;
-            }
-            stopAfterToolResultCallId = toolCallId ?? STOP_AFTER_ANY_TOOL_RESULT;
-          }
-        } : {},
-        // Forcing the next round to `read` is only correct when reading is
-        // the whole reserve. An agent with delivery tools must be able to
-        // write in its own reserve window, so it gets the steering directive
-        // without the request-level lock.
-        ...readReserve > 0 && deliveryTools.length === 0 ? {
-          onSoftReadReserve: () => {
-            middlewareToolChoice.apply([{ kind: "require_tool", toolName: ToolNames.Read }]);
-          }
-        } : {}
-      }),
+      loopGuardRegistration,
       createProtectedArtifactsRegistration({
         ...input.protectedArtifactState !== void 0 ? { initialState: { artifacts: [...input.protectedArtifactState.artifacts] } } : {}
       })
@@ -1044,6 +1042,7 @@ function startWorkerRun(input, emit) {
   );
   const contractCwd = input.cwd ?? process.cwd();
   let resultContractRepairsQueued = 0;
+  let resultContractRevisionActive = false;
   const pendingReadCitations = /* @__PURE__ */ new Map();
   const observedReadRanges = /* @__PURE__ */ new Map();
   const runEffects = createRunEffectsRecorder(contractCwd);
@@ -1182,9 +1181,24 @@ function startWorkerRun(input, emit) {
       if (violation !== null) {
         if (resultContractRepairsQueued < RESULT_CONTRACT_REPAIR_LIMIT) {
           resultContractRepairsQueued += 1;
-          synthesisToolLock = true;
+          if (!resultContractRevisionActive && workerBudget.revision !== void 0) {
+            resultContractRevisionActive = loopGuardRegistration.extendWorkerToolCallPhase(workerBudget.revision);
+            if (resultContractRevisionActive) {
+              synthesisToolLock = false;
+              middlewareToolChoice.reset();
+              stopAfterToolResultCallId = null;
+            }
+          }
+          const revisionToolsAvailable = resultContractRevisionActive && !synthesisToolLock;
+          if (!revisionToolsAvailable) synthesisToolLock = true;
           const repair = resultContractRepairMessages(
-            { contract, reason: violation, attempt: resultContractRepairsQueued, anchors: observedReadAnchors() },
+            {
+              contract,
+              reason: violation,
+              attempt: resultContractRepairsQueued,
+              anchors: observedReadAnchors(),
+              ...revisionToolsAvailable ? { toolsAvailable: true } : {}
+            },
             { provider: model.provider, api: model.api, model: model.id }
           );
           for (const message of repair) agent.followUp(message);
@@ -1323,7 +1337,7 @@ function startWorkerRun(input, emit) {
       const requestId = meta.requestId;
       const timer = setTimeout(() => resolveEscalation(requestId, "deny", "timeout"), escalationConfig.timeoutMs);
       activeEscalation = { requestId, tool: call.tool, actionClass, callKey, timer };
-      const target = describeCallTarget(call.args).slice(0, 200);
+      const target = describeCallTarget(call.tool, call.args);
       emit({
         type: "clio_permission_escalated",
         payload: {

package/dist/{workspace-G4ZWUIPR.js → workspace-ZJ6BFM3Q.js}

@@ -6,9 +6,9 @@ import {
   probeGitStatusAsync,
   probeWorkspace,
   probeWorkspaceAsync
-} from "./chunk-G4BMMOKF.js";
-import "./chunk-YHZX5GEU.js";
-import "./chunk-EKMEHE4H.js";
+} from "./chunk-HVDIIIQW.js";
+import "./chunk-XAKHZX5N.js";
+import "./chunk-33YXPOE3.js";
 import "./chunk-7CR24IG7.js";
 import "./chunk-3R73A4XB.js";
 export {
@@ -19,4 +19,4 @@ export {
   probeWorkspace,
   probeWorkspaceAsync
 };
-//# sourceMappingURL=workspace-G4ZWUIPR.js.map
+//# sourceMappingURL=workspace-ZJ6BFM3Q.js.map

package/docs/README.md

@@ -4,7 +4,7 @@
 
 # Clio Coder Documentation
 
-These pages document `v0.3.4` 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)) |
@@ -54,7 +55,7 @@ current source, tests, and `CHANGELOG.md`.
 | Issue-driven development lifecycle: file-ticket through release, label taxonomy, and dogfooding setup | [development-pipeline.md](development-pipeline.md) |
 | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying | [proactive-memory.md](proactive-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
 | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and CLI trace subcommands | [trace-store.md](trace-store.md) ([Interactive Blueprint](html/trace_blueprint.html)) |
-| Private context index determinism, target smoke matrices, and Clio machinery soak benchmark suite | [evals-internal.md](evals-internal.md) ([Blueprints: evals_internal](html/evals_internal_blueprint.html), [soak](html/soak_blueprint.html)) |
+| Private context index determinism and target smoke matrices | [evals-internal.md](evals-internal.md) ([Blueprint](html/evals_internal_blueprint.html)) |
 | Point-in-time inventory of legacy environment variables (Historical Appendix) | [config-knobs-audit.md](config-knobs-audit.md) ([Interactive Blueprint](html/config_knobs_audit_blueprint.html)) |
 | Clock and timestamp conventions: durations, instants, ordering, and formatting | [time-conventions.md](time-conventions.md) ([Interactive Blueprint](html/time_conventions_blueprint.html)) |
 | Correct render, PTY, startup, compile-cache, and import-graph measurement endpoints and the 0.3.3 baseline | [performance-methodology.md](performance-methodology.md) |
@@ -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.4 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.4`.
+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.4).
+> **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.7).
 
 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.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.3.7).
 
 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.4` development line.
+This page is source-code aligned for the current `v0.3.7` development line.
 
 ---
 

package/docs/artifact-placement.md

@@ -83,8 +83,7 @@ next to the ignore:
 ```
 
 This repository commits none of those, so its `.clio-coder/` stays fully
-ignored except the seeded soak fixtures under `benchmarks/soak/fixtures/`,
-which are test inputs rather than session output.
+ignored. Benchmark workspaces are temporary external repositories.
 
 ## Finding what was hidden
 

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.4`.
+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.7`.
 
 ---
 
@@ -10,23 +10,27 @@ 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** | `19` | `RUN_RECEIPT_INTEGRITY_VERSION = 19`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 19 covers all base provenance fields, routing intent, quality labels, `validationGrounding`, `capabilityMismatch`, council provenance, and fleet gate provenance. | Fail-closed. Incompatible receipts fail verification and are never read as evidence. |
 | **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. |
+| **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 19)
 
 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 +42,9 @@ export function computeReceiptDigest(receipt: RunReceiptV15): string {
 ```
 
 Receipt verification checks:
-1. `integrity.version === 15`.
+1. `integrity.version === 19`.
 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 v19 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.4).
+> **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.7).
 
 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.4`.
+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`.