@iowarp/clio-coder 0.3.8 → 0.4.0

package/dist/worker/entry.js

@@ -16,28 +16,32 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-WLFILSD5.js";
+} from "../chunk-HJJTYUHX.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-7RGZWPB6.js";
+} from "../chunk-QLL7ILRG.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
   WORKSPACE_SCOPE,
   isSubset
-} from "../chunk-VCBR6CU7.js";
+} from "../chunk-5PSMVOLM.js";
 import {
   createLoopState,
   observe
 } from "../chunk-UOV2BYIW.js";
-import "../chunk-PMDBGQSJ.js";
-import "../chunk-XN3L4EYL.js";
-import "../chunk-SPULKLCF.js";
-import "../chunk-KTYTFRMB.js";
-import "../chunk-ZVJ5BLO2.js";
+import "../chunk-BMS5RKQY.js";
+import "../chunk-QSNYB6ZV.js";
+import "../chunk-QDC3K2U3.js";
+import "../chunk-YPI3QQCF.js";
+import "../chunk-HWHKMHUA.js";
+import "../chunk-LQ3DZAMX.js";
+import "../chunk-NHCZP4K7.js";
+import "../chunk-36EJLSQQ.js";
+import "../chunk-BKFJHQCA.js";
 import "../chunk-VG7TBQIY.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
@@ -46,46 +50,36 @@ import {
   claudeToolsOutsideProfile,
   coerceToolInput,
   createRunEffectsRecorder,
-  describeCallTarget,
   emitClaudeToolPermissionDecision,
   isClaudeCodeSessionId,
+  nodeResultContractFilesystem,
   parseWorkerSpec,
   runtimeSpeaksResponseSchemaDialect,
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-A3WNZD3P.js";
-import "../chunk-5FR74PWO.js";
-import "../chunk-P43ETTHK.js";
-import "../chunk-H7IXIC72.js";
+} from "../chunk-J4W7KFM7.js";
+import "../chunk-SJ5ZKQ4S.js";
+import "../chunk-2JDWVJND.js";
+import "../chunk-GKF55TAZ.js";
 import {
   createSafetyPolicyEngine
-} from "../chunk-5H3GB5BO.js";
-import "../chunk-A2NJGIB3.js";
+} from "../chunk-32KWKNSF.js";
+import {
+  describeCallTarget
+} from "../chunk-TVHHYFHE.js";
+import "../chunk-42FMPA75.js";
+import "../chunk-H7IXIC72.js";
+import "../chunk-5LXZXPKX.js";
 import "../chunk-OQE5J4C6.js";
 import {
+  DEFAULT_AUTONOMY_LEVEL,
   agentSkillToolPolicy
-} from "../chunk-GOXNB3AO.js";
-import {
-  DEFAULT_AUTONOMY_LEVEL
-} from "../chunk-HWUFFB6L.js";
-import {
-  RESULT_CONTRACT_REPAIR_LIMIT,
-  parseWorkerResultContract,
-  resultContractRepairMessages,
-  validateResultContract
-} from "../chunk-TTHACPOM.js";
-import {
-  classify
-} from "../chunk-AOCYTWAV.js";
-import {
-  protectedArtifactMutationBlockReason
-} from "../chunk-MV3K5QF2.js";
-import "../chunk-UL3WSD3F.js";
-import "../chunk-ODFEOB4F.js";
+} from "../chunk-RAPCMZL4.js";
+import "../chunk-CY6FY24N.js";
 import "../chunk-OZNBF4L3.js";
 import "../chunk-4BJ5BYCE.js";
-import "../chunk-ECH6PKUQ.js";
+import "../chunk-6XLNIQDB.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -103,13 +97,24 @@ import {
 } from "../chunk-CMZWFGD2.js";
 import {
   deleteInjectedCompileCacheFrom
-} from "../chunk-I4HZDVNP.js";
-import "../chunk-ZI647VB5.js";
-import "../chunk-6XLNIQDB.js";
+} from "../chunk-PQEFIJ36.js";
+import "../chunk-HHV2GANA.js";
+import {
+  RESULT_CONTRACT_REPAIR_LIMIT,
+  classify,
+  parseWorkerResultContract,
+  resultContractRepairMessages,
+  validateResultContract
+} from "../chunk-DYJP44XW.js";
+import {
+  protectedArtifactMutationBlockReason
+} from "../chunk-GCSMB2KY.js";
+import "../chunk-UL3WSD3F.js";
+import "../chunk-ECH6PKUQ.js";
 import "../chunk-5B2AEOW5.js";
 import {
   ToolNames
-} from "../chunk-CGKSTWHD.js";
+} from "../chunk-K6BSR66V.js";
 import "../chunk-65DEGPJ6.js";
 import {
   FileKnowledgeBase,
@@ -121,24 +126,24 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-7RFXX52T.js";
+} from "../chunk-DQITNCXG.js";
 import "../chunk-CFGTUFWB.js";
-import "../chunk-LU7P4LHA.js";
-import "../chunk-RWSI4YD7.js";
+import "../chunk-P3FOHJT4.js";
+import "../chunk-UM7N4G5A.js";
+import "../chunk-ZGVHUX3M.js";
+import "../chunk-HLW2MRKE.js";
+import "../chunk-76ONBSIA.js";
+import "../chunk-R346GLFC.js";
 import "../chunk-IHXBNWMM.js";
-import {
-  setGitCommitAttributionEnabled,
-  withManagedGitCommitAttributionEnvironment
-} from "../chunk-B5CSFE7B.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-IJ7RPIYJ.js";
+} from "../chunk-VFA6GDY5.js";
+import {
+  setGitCommitAttributionEnabled,
+  withManagedGitCommitAttributionEnvironment
+} from "../chunk-BBVJUZHB.js";
 import "../chunk-FQ4SKYE4.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";
@@ -147,29 +152,29 @@ import {
 } from "../chunk-IWHMRKLL.js";
 import {
   registerBuiltinRuntimes
-} from "../chunk-NMPKI6XL.js";
-import "../chunk-4DGYLA73.js";
+} from "../chunk-6DB53AJS.js";
+import "../chunk-GXNLGKAB.js";
 import "../chunk-LL4KHSZI.js";
 import {
   configureGuardrails,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
 } from "../chunk-4ZG3XFUR.js";
-import "../chunk-IIZWH4XA.js";
-import "../chunk-EQ63NRB7.js";
+import "../chunk-HI63TFOG.js";
+import "../chunk-BBVYXMFO.js";
 import "../chunk-SST6Z5JA.js";
 import "../chunk-IKCO5N3L.js";
 import "../chunk-3I7MS7N2.js";
 import "../chunk-APJ265NV.js";
-import "../chunk-BNAZZHFG.js";
+import "../chunk-BYP5D4HI.js";
 import "../chunk-WEPFGWHJ.js";
 import {
   getRuntimeRegistry
 } from "../chunk-NUGM5KR6.js";
-import "../chunk-PT7HYKEM.js";
+import "../chunk-VO2LKSTM.js";
 import {
   registerFauxFromEnv
-} from "../chunk-FCSXB6T2.js";
+} from "../chunk-UOSL25KY.js";
 import "../chunk-YXLYO42X.js";
 import {
   init_esm_shims
@@ -180,14 +185,10 @@ init_esm_shims();
 
 // src/engine/worker-runtime.ts
 init_esm_shims();
-import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
 // src/engine/claude/sdk-runtime.ts
 init_esm_shims();
-import {
-  query
-} from "@anthropic-ai/claude-agent-sdk";
 
 // src/engine/worker-tools.ts
 init_esm_shims();
@@ -309,6 +310,46 @@ function attestedToolSignature(input) {
   );
 }
 
+// src/engine/claude/sdk-module.ts
+init_esm_shims();
+var CLAUDE_AGENT_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+var CLAUDE_AGENT_SDK_VERSION = "0.3.186";
+var CLAUDE_AGENT_SDK_INSTALL_COMMAND = `npm install ${CLAUDE_AGENT_SDK_PACKAGE}@${CLAUDE_AGENT_SDK_VERSION}`;
+var ClaudeAgentSdkUnavailableError = class extends Error {
+  code = "CLAUDE_AGENT_SDK_UNAVAILABLE";
+  packageName = CLAUDE_AGENT_SDK_PACKAGE;
+  installCommand = CLAUDE_AGENT_SDK_INSTALL_COMMAND;
+  constructor(cause) {
+    super(
+      `The claude-sdk runtime needs the optional package ${CLAUDE_AGENT_SDK_PACKAGE}, which is not installed. Install it with \`${CLAUDE_AGENT_SDK_INSTALL_COMMAND}\` (or reinstall clio-coder without \`--omit=optional\`), then select the target again. Every other runtime works without it.`,
+      cause === void 0 ? void 0 : { cause }
+    );
+    this.name = "ClaudeAgentSdkUnavailableError";
+  }
+};
+var MISSING_MODULE_CODES = /* @__PURE__ */ new Set([
+  "ERR_MODULE_NOT_FOUND",
+  "MODULE_NOT_FOUND",
+  "ERR_PACKAGE_PATH_NOT_EXPORTED"
+]);
+function isMissingModuleError(error) {
+  const code = error?.code;
+  return typeof code === "string" && MISSING_MODULE_CODES.has(code);
+}
+var realLoader = async () => await import("@anthropic-ai/claude-agent-sdk");
+var loader = realLoader;
+var cached = null;
+async function loadClaudeAgentSdk() {
+  if (cached) return cached;
+  try {
+    cached = await loader();
+    return cached;
+  } catch (error) {
+    if (isMissingModuleError(error)) throw new ClaudeAgentSdkUnavailableError(error);
+    throw error;
+  }
+}
+
 // src/engine/claude/sdk-runtime.ts
 var DEFAULT_CLAUDE_TOOLS = { type: "preset", preset: "claude_code" };
 function sdkUserTextMessage(text, shouldQuery) {
@@ -601,8 +642,8 @@ function decideToolUse(input, toolCallId, toolName, toolInput) {
   });
 }
 function decideClaudeSdkToolUseOnce(handled, toolUseID, decide) {
-  const cached = toolUseID ? handled.get(toolUseID) : void 0;
-  if (cached) return cached;
+  const cached2 = toolUseID ? handled.get(toolUseID) : void 0;
+  if (cached2) return cached2;
   const decision = decide();
   if (toolUseID) handled.set(toolUseID, decision);
   return decision;
@@ -744,6 +785,7 @@ function startClaudeSdkWorkerRun(input, emit) {
     let responseId;
     emit({ type: "agent_start" });
     try {
+      const { query } = await loadClaudeAgentSdk();
       queryHandle = query({ prompt: buildClaudeSdkPrompt(input), options });
       for await (const sdkMessage of queryHandle) {
         if (sdkMessage.type === "system" && sdkMessage.subtype === "init") {
@@ -873,18 +915,7 @@ function terminalContractViolation(contract, message, cwd, observedReadRanges, o
     // Repair rounds judge shape and grounding only. Network posture belongs to
     // the orchestrator's sealed validation, which runs again on the receipt.
     networkAllowed: true,
-    filesystem: {
-      readFile(filePath) {
-        try {
-          return readFileSync(filePath, "utf8");
-        } catch {
-          return null;
-        }
-      },
-      pathExists(filePath) {
-        return existsSync(filePath);
-      }
-    }
+    filesystem: nodeResultContractFilesystem()
   });
   return validation.conformance === "pass" ? null : validation.reason ?? "invalid result";
 }

package/docs/README.md

@@ -4,7 +4,7 @@
 
 # Clio Coder Documentation
 
-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).
+These pages document `v0.4.0` 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`.
@@ -23,6 +23,7 @@ current source, tests, and `CHANGELOG.md`.
 | Safety posture, default-deny Bash, project policy, damage-control rules, and typed validation | [safety-model.md](safety-model.md) ([Interactive Blueprint](html/safety_blueprint.html)) |
 | Source layout, compile-time boundaries, domain loading, and runtime data flow | [architecture.md](architecture.md) ([Interactive Blueprint](html/architecture_blueprint.html)) |
 | Why the dispatch domain is not split, which invariants cross the obvious seams, and why direct subpath imports are permitted | [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md) ([Interactive Blueprint](html/dispatch_rationale_blueprint.html)) |
+| Typed dispatch intent: the producer and persisted-contract compatibility tables, refusal reason codes, and the legacy-inference retirement criterion | [dispatch-typed-intent.md](dispatch-typed-intent.md) |
 | Prompt envelope reuse, provider tool delivery, and bounded tool results | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) ([Interactive Blueprints: prompt_envelope](html/prompt_envelope_blueprint.html), [tools](html/tools_blueprint.html)) |
 | In-depth reference for all 20 worker tools: parameters, typical payloads, and error examples | [tool-usage.md](tool-usage.md) ([Interactive Blueprint](html/tool_usage_blueprint.html)) |
 | Developer guide to implementing custom model runtimes and inference server integrations | [provider-adapter-cookbook.md](provider-adapter-cookbook.md) ([Interactive Blueprint](html/provider_adapter_blueprint.html)) |
@@ -84,7 +85,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.7 the supported
+history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.4.0 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.7`.
+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.4.0`.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 
@@ -11,7 +11,11 @@ Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
 
 The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
-An example localhost client lives in `apps/workbench` and is unreleased.
+The source tree includes the `apps/workbench` localhost desktop client. Its ACP
+adapter supports session browsing and deletion, safe settings, target probes,
+usage, recovery, evaluation inventory, routing and dispatch inspection, toolchain
+status, agent attribution, and the live fleet event strip. The workbench is a
+source application and is not included in the published CLI package.
 
 ```mermaid
 graph LR
@@ -31,6 +35,10 @@ The server is invoked via:
 clio-coder acp [--cwd PATH] [--permission-timeout MS]
 ```
 
+`clio-coder --acp [--cwd PATH] [--permission-timeout MS]` is an exact alias;
+both spellings reach the same command dispatcher, option parser, stdout guard,
+and server boot path.
+
 - `--cwd PATH`: Workspace root the server boots in. The path is resolved and then canonicalized with `fs.realpath`, so a symlinked launch root, a trailing slash, and a `/.` suffix all name the same workspace. Clio changes into that canonical path before it reads settings, builds project context, or opens a session ledger, so a session opens at that root. A path that does not exist or that the process cannot enter exits 2 without starting the server. The canonical path is the server's workspace identity for its whole life: `session/new` must carry a `cwd` that canonicalizes to the same path, and nothing after boot ever changes the process directory.
 - `--permission-timeout MS`: The server-side fail-safe ceiling for one mediated permission request, as a whole number from 1 through Node's maximum schedulable timer delay (`2147483647`) milliseconds. Values outside that range are refused before the protocol server starts. If the timer wins, the approval expires, the active turn is aborted, every parked call for that turn is settled only so execution can unwind, and `session/prompt` fails with `permission_expired`. Expiry is audited as `expired`, never as a human denial, and no denial result is fed into a continuing model loop. The flag overrides `delegation.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:149`). A client may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
 
@@ -59,7 +67,7 @@ These are every method the server answers (`src/engine/acp/server.ts`). Anything
 | `clio-coder/targets/list` | Client → Server | Lists bounded, credential-free target/model summaries from configuration and the in-memory cache without network traffic. |
 | `clio-coder/targets/probe` | Client → Server | Explicitly probes one configured target through the provider domain and returns only a closed health result. |
 | `session/request_permission` | Server → Client | Requests permission from the client for a gated tool operation. |
-| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The only v1 kind is `safety.loopBlocked`. |
+| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The v1 allowlist is `safety.loopBlocked` plus `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, and `dispatch.failed`. |
 
 `agentCapabilities.loadSession` is `true`. All non-standard methods are advertised only under `agentCapabilities._meta`; a strict generic ACP v1 client sees the standard new/load/prompt/cancel/permission surface, ignores namespaced result metadata, and receives no non-standard notification unless it explicitly opts into a recognized event kind.
 
@@ -263,6 +271,19 @@ name only the protocol it was reached through, so its header reads `◇ codex
 token usage, the count of mediated tool calls in place of a token count; a peer
 that does report usage gets the same `tok` unit a local worker does.
 
+### Typed intent on a delegated dispatch
+
+A dispatch to a delegation agent accepts typed intent and renders the declared
+scope into the plan approval artifact, so an operator sees what the peer was
+told to work on before it starts. The declaration grants nothing on this
+transport: the peer runs its own tool surface and Clio mediates no per-tool
+call, so a resolved write boundary would be a claim nothing enforces and is
+refused outright rather than accepted and left unenforced. Declare `read_roots`
+and `relevant_paths` to bound what the peer is asked to look at; run the writing
+half of the work on a native or `claude-sdk` worker. The compatibility rules and
+reason codes are the same as for any other producer; see
+[dispatch-typed-intent.md](dispatch-typed-intent.md).
+
 ---
 
 ## 8. Error Taxonomy

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.8).
+> **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.4.0).
 
 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.8).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.4.0).
 
 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.7` development line.
+This page is source-code aligned for the current `v0.4.0` 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.8`.
+This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.4.0`.
 
 ---
 
@@ -11,6 +11,9 @@ 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** | `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. |
+| **Dispatch Intent** | `2` | `DISPATCH_INTENT_VERSION = 2`, `DISPATCH_INTENT_SUPPORTED_VERSIONS = [2]`<br>`src/domains/dispatch/intent-compatibility.ts` | Inside the resolved dispatch plan artifact, the `JobSpec`/`DispatchRequest`, and the sealed run receipt | Typed model- and producer-declared scope: `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and declared-id `verification`, plus the `pathProvenance` binding every policy-bearing path to the field that declared it. Version 2 adds `pathProvenance` over the v1 path-and-output shape. | Fail-closed, never migrated. The supported set is a membership list, not a range: any other version is refused with `intent_version_unsupported` and the caller restates the fields on a fresh dispatch call. Omitted intent is accepted through the separately tracked legacy inference path; contradictory intent is a terminal refusal. See [dispatch-typed-intent.md](dispatch-typed-intent.md). |
+| **Dispatch Path Scope Provenance** | `1` | `version: 1` in `interface DispatchPathScopeProvenance`<br>`src/domains/dispatch/path-scope.ts` | `pathScope` on the sealed run receipt | Resolved policy-bearing paths with per-field provenance (`declared`/`derived`/`inferred`), source, and confidence. Never carries the task or briefing prose an inferred path came from. | Sealed inside the receipt integrity digest; shares the receipt's fail-closed policy. |
+| **Resolved Dispatch Plan Artifact** | `3` | `version: 3` in `interface ResolvedDispatchPlanArtifact`<br>`src/tools/dispatch-plan.ts:122` | Trusted admission-time tool argument, rendered and hashed into the plan approval | Pinned agent/target/model/node per task plus the sealed `intent` and admission-resolved `resolvedVerification`. The rendered artifact carries `intent_sha256` for a declared task and the full inferred scope table for a legacy one. | Fail-closed. Any version but 3 parses as `null`, as does any task whose `intent` is not a normalized v2 intent; the call falls back to unresolved admission rather than executing a half-understood plan. |
 | **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. |
@@ -18,6 +21,11 @@ Clio Coder strictly versions every persistent or network-transported data struct
 | **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`. |
+| **Prompt Manifest** | `2` | `PROMPT_MANIFEST_VERSION = 2`<br>`src/domains/session/prompt-manifest.ts:30` | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` | Per-session record of the compiled system prompt: fragment ids, relative paths, content hashes, section token estimates, and the composition hash. Version 2 is the stable-prefix-first ordering with one `# Memory` header and records `contextWindowSource` beside the window the prompt states (#249). | Additive. A record without a `version` field predates the field and reads as version 1, so a 0.3.8 manifest still parses; the version explains the single `promptRecompiled` entry a resumed session's first compile writes. |
+| **Eval Verdict Envelope** | `clio.eval.verdict.v1` | `EVAL_VERDICT_SCHEMA_V1`<br>`src/domains/eval/schema/verdict.ts:1` | Inside the Eval Artifact at `<stateDir>/evals/<evalId>.json` | Fail-closed verdict identity with ledger- and receipt-sourced performance metrics, per-scenario pass and distribution aggregates, and serving-configuration provenance (#252). One pass decision: the code grader's outcome is part of `result.pass`. | Fail-closed. `eval compare` refuses serving-configuration drift unless explicitly allowed; an artifact without a parseable verdict envelope is rejected rather than read as passing. |
+| **Behavioral Scenario & Result** | `clio.eval.scenario.v1`, `clio.eval.behavior.v1` | `EVAL_BEHAVIOR_SCENARIO_SCHEMA_V1`, `EVAL_BEHAVIOR_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral.ts:4-5` | Suite v2 task declarations; additive sibling inside the Eval Artifact | Versioned behavioral contract: bounded expected and forbidden rules across tool choice, exploration, delegation, safety comprehension, claim grounding, denied-tool recovery, completion behavior, and task correctness, with deterministic judge inputs canonicalized from transcript, tool, receipt, and grader facts (#156). References the unchanged `clio.eval.verdict.v1` identity. | Fail-closed. `unknown`, `unmeasured`, `behavioral_failure`, and `infrastructure_failure` stay distinct; a malformed, partial, contradictory, or cross-linked verdict cannot parse as a pass. Existing artifact readers are unaffected because the sibling is additive. |
+| **Behavioral Metrics Projection** | `clio.eval.behavior.metrics.v1` | `EVAL_BEHAVIOR_METRICS_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral-metrics.ts:4` | Additive role- and target/model-bound projection inside the Eval Artifact | Ten sourced metric families (correctness, safety, label violations, tool-call efficiency, unnecessary exploration, delegation quality, unsupported claims, tokens, latency, cost, and repeat variability) with coverage, min/max, p90, population variance, and standard deviation per distribution (#161). | Unmeasured observations stay typed `null` and never become zero violations. A baseline hard metric that becomes unmeasured fails the comparison closed, and `--metric` filtering cannot hide a hard failure. |
+| **Execution Envelope** | `clio.eval.execution-envelope.v1` | `EVAL_EXECUTION_ENVELOPE_SCHEMA_V1`<br>`src/domains/eval/schema/execution-envelope.ts:1` | On every new behavioral result inside the Eval Artifact | Strictly parsed binding of prompt fragment ids, versions, and content hashes, composition hash, recipe identity and content hash, target, wire model, runtime, thinking level, tool signature, autonomy, policy hashes, project-context provenance, and corpus id and version (#164). Suites declare which matrix dimensions may vary. | Fail-closed. Comparisons mark rows incomparable on any undeclared envelope drift, refuse one-sided envelopes and within-run variance, and name every prompt- or recipe-affected corpus result. |
 | **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. |

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.8).
+> **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.4.0).
 
 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.
 

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.7`.
+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.4.0`.
 
 Source implementations: `src/domains/scheduling/` and `src/domains/dispatch/capacity-lease.ts`.
 
@@ -8,19 +8,51 @@ Source implementations: `src/domains/scheduling/` and `src/domains/dispatch/capa
 
 ## 1. Capacity Model & Admission Invariants
 
-Fleet dispatch manages compute resources across local and remote execution nodes as a unified capacity pool. Dispatched workers must acquire a durable capacity lease before they are spawned.
+Fleet dispatch manages compute resources across local and remote execution nodes as a unified capacity pool. Dispatched workers must acquire a durable capacity lease before they are spawned. Admission checks global, node, and inference-endpoint limits independently.
 
 ```mermaid
 graph TD
     req[Dispatch Request] --> lock[Acquire Cross-Process Lock: dispatch-admission.json.lock]
     lock --> reap[Reap Expired Leases & Dead PIDs]
-    reap --> check[Check Capacity Limits: global & per-node]
+    reap --> check[Check Capacity Limits: global, per-node, and per-endpoint]
     check -->|Within Limits| grant[Grant Capacity Lease & Write State]
     check -->|Limits Exceeded| queue[Queue / Reject Request]
     grant --> unlock[Release Lock]
     unlock --> spawn[Spawn Worker Process]
 ```
 
+| Dimension | Identity | Limit resolution |
+| :--- | :--- | :--- |
+| Global | All dispatches using the state directory. | `budget.concurrency: auto` remains four. |
+| Node | The local node or one configured fleet node. | The configured node limit applies. An unset local node cap remains unbounded. |
+| Inference endpoint | A normalized scheme, host, port, and base path. | A target's `maxConcurrentRequests` override wins, then a probe in this process, then a persisted probe from an earlier process, then one slot for other local-native targets. vLLM and SGLang remain unbounded. |
+
+The conventional final `/v1` mount and a trailing slash normalize to the same endpoint. Host aliases are not collapsed because Clio cannot prove they address the same server. For example, `http://localhost:8080/` and `http://127.0.0.1:8080/v1` remain distinct, while two target descriptors that use the same normalized URL share one endpoint limit.
+
+llama.cpp discovery reads `total_slots` from cached probe results. A router can expose the selected worker's value from `/props?model=<id>` even when router `/props` has no slot count. The selected model's `/v1/models` argv supplies a `--parallel` fallback. LM Studio defaults to one slot when its REST response supplies no concurrency fact. Ollama defaults to one unless `OLLAMA_NUM_PARALLEL` is visible to the local process.
+
+The endpoint set is resolved from the configured targets as well as the probed statuses, so it is the same set a second after boot as it is a minute later. An endpoint that resolves to no limit is not checked at all, and "not checked" is not a conservative answer.
+
+### Persisted Slot Discovery
+
+A probe learns a fact about a server, not about the process that asked, so a discovered slot count is written to disk and read back as a prior by the next process.
+
+- **Path**: `<stateDir>/endpoint-slots.json` (`src/domains/providers/endpoint-slots-store.ts:endpointSlotsPath()`)
+- **Version**: `version: 1`, one record per canonical endpoint key
+- **Transaction lock**: `<stateDir>/endpoint-slots.json.lock` (`withStateFileLock`)
+- **Staleness bound**: 24 hours, overridable per process with `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS`
+
+```typescript
+export interface DiscoveredEndpointSlots {
+  endpointKey: string;   // Canonical inference endpoint identifier
+  runtimeId: string;     // Runtime that observed the count
+  slots: number;         // Discovered parallel slot count
+  observedAt: string;    // ISO-8601 observation timestamp
+}
+```
+
+Three things bound what a record may claim. A record older than the staleness bound is ignored and pruned by the next write, so a server restarted with a smaller `--parallel` cannot keep over-admitting against yesterday's number. A record written by a different runtime for the same host and port is ignored, because a different inference server is a different scheduler. A probe in this process always wins over the record, and `maxConcurrentRequests` wins over both. A well-formed record that fails any of these checks falls back to the conservative default rather than to a guess.
+
 ### State Storage & Format
 
 All capacity state is stored in a single durable JSON file:
@@ -49,6 +81,7 @@ export interface CapacityLease {
   leaseId: string;              // Unique lease identifier
   assignmentId: string;         // Owning dispatch assignment ID
   nodeId: string;               // Execution node identifier ("local" or remote ID)
+  endpointKey?: string;         // Canonical inference endpoint identifier
   ownerPid: number;             // Process ID of the orchestrator/worker owner
   processBirthToken: string;    // OS-level token preventing PID reuse collisions
   acquiredAt: string;           // ISO-8601 acquisition timestamp
@@ -59,6 +92,32 @@ export interface CapacityLease {
 }
 ```
 
+The orchestrator's active model stream is registered in memory against the same endpoint key, so its own turn consumes one endpoint slot before a worker is admitted. This foreground count is not written to `dispatch-admission.json`; process exit releases it. Durable leases and held reservation members carry `endpointKey`, and held members count their peak per wave for the endpoint just as they do for a node.
+
+Execution-plan waves also honor the endpoint bound. A plan with four available worker positions targeting one two-slot server packs at most two of them into a wave, or one when the orchestrator already holds the other slot. Endpoint saturation is refused rather than queued, because an endpoint-specific request queue would hold a dispatch open behind a stream whose length nobody knows. The refusal names the endpoint, both slot counts, why one slot is already gone, and the moves that actually free capacity:
+
+```text
+dispatch: admission denied: endpoint '192.168.86.141:8080' capacity reached (1/1 slots): 1 foreground stream holds the slot; reduce the same-wave worker count, set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
+```
+
+That remedy is shared by all three paths that can refuse for this reason: lease acquisition (`src/domains/dispatch/capacity-lease.ts`), the admission gate (`src/domains/dispatch/admission.ts`), and reservation preflight (`src/domains/dispatch/reservation-store.ts`). The `1/1` above is the common local case rather than an example: a llama.cpp router started with `--parallel 1` discovers one slot, so any dispatch raised while the orchestrator is streaming is refused before a worker process starts.
+
+### What `/council` Needs on a Single-GPU Setup
+
+A council seats two to five members and runs the whole roster in one wave, so it needs at least two endpoint slots at once, plus a third if the orchestrator's own turn is streaming to the same server. It cannot answer a capacity denial by dispatching fewer members, which is why its denial says so instead of offering that move:
+
+```text
+dispatch: admission denied: endpoint 'mini:8080' capacity exceeded (2/1 slots): no active lease, held reservation, or foreground stream currently holds a slot; a council runs its whole roster in one wave and cannot go below 2 members, so set this target's maxConcurrentRequests to the slot count the server was started with, collect in-flight runs, or point workers at a second server
+```
+
+On a single-GPU box there are three ways to make `/council` work, in order of preference:
+
+1. Start the server with enough slots and let discovery find them. `llama-server --parallel 4` is discovered as four slots and persisted, so every later process sees four without re-probing.
+2. Set `maxConcurrentRequests` on the target when the server's real concurrency is higher than what it advertises. It overrides every discovered value.
+3. Point some roster members at a second server. Members on different endpoints do not compete for the same slots.
+
+A server genuinely started with one slot cannot run a council, and admitting one anyway would put two workers plus the orchestrator through a scheduler with room for one. The denial is the correct outcome; the fix is on the server or in the roster.
+
 ### Constants & Operational Bounds
 
 | Constant | Value | Description | Source Reference |