@iowarp/clio-coder 0.3.9 → 0.4.0

package/dist/worker/entry.js

@@ -16,28 +16,32 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-R7LNVMCS.js";
+} from "../chunk-HJJTYUHX.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-GAYUJ7LE.js";
+} from "../chunk-QLL7ILRG.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
   WORKSPACE_SCOPE,
   isSubset
-} from "../chunk-HAY4ZE2P.js";
+} from "../chunk-5PSMVOLM.js";
 import {
   createLoopState,
   observe
 } from "../chunk-UOV2BYIW.js";
-import "../chunk-CA42X6KT.js";
-import "../chunk-OEDBCISO.js";
-import "../chunk-5DQRIYDZ.js";
-import "../chunk-VKBMFOYV.js";
-import "../chunk-O6I4CIEU.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,43 +50,36 @@ import {
   claudeToolsOutsideProfile,
   coerceToolInput,
   createRunEffectsRecorder,
-  describeCallTarget,
   emitClaudeToolPermissionDecision,
   isClaudeCodeSessionId,
+  nodeResultContractFilesystem,
   parseWorkerSpec,
   runtimeSpeaksResponseSchemaDialect,
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-4H6ULJ3H.js";
-import "../chunk-VPTUJU4P.js";
+} from "../chunk-J4W7KFM7.js";
+import "../chunk-SJ5ZKQ4S.js";
 import "../chunk-2JDWVJND.js";
-import "../chunk-H7IXIC72.js";
-import "../chunk-7C6RYZGQ.js";
+import "../chunk-GKF55TAZ.js";
 import {
   createSafetyPolicyEngine
-} from "../chunk-N3PBVRTZ.js";
-import "../chunk-A2NJGIB3.js";
-import "../chunk-OQE5J4C6.js";
-import {
-  RESULT_CONTRACT_REPAIR_LIMIT,
-  classify,
-  parseWorkerResultContract,
-  resultContractRepairMessages,
-  validateResultContract
-} from "../chunk-S4COXYBG.js";
+} from "../chunk-32KWKNSF.js";
 import {
-  protectedArtifactMutationBlockReason
-} from "../chunk-MV3K5QF2.js";
+  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-RAPCMZL4.js";
-import "../chunk-UL3WSD3F.js";
-import "../chunk-ODFEOB4F.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,
@@ -100,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,
@@ -118,23 +126,24 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-MIX5N5AC.js";
+} from "../chunk-DQITNCXG.js";
 import "../chunk-CFGTUFWB.js";
-import "../chunk-LU7P4LHA.js";
-import "../chunk-AEYBF3TB.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-PNY46YEY.js";
+} from "../chunk-VFA6GDY5.js";
+import {
+  setGitCommitAttributionEnabled,
+  withManagedGitCommitAttributionEnvironment
+} from "../chunk-BBVJUZHB.js";
 import "../chunk-FQ4SKYE4.js";
-import "../chunk-ZGVHUX3M.js";
-import "../chunk-RKRLDWD3.js";
-import "../chunk-KV2AOLDF.js";
 import {
   AI_AGENT_NAME
 } from "../chunk-6EJMN2Y3.js";
@@ -143,21 +152,21 @@ import {
 } from "../chunk-IWHMRKLL.js";
 import {
   registerBuiltinRuntimes
-} from "../chunk-JEQQR47K.js";
-import "../chunk-XDOQXGFO.js";
+} from "../chunk-6DB53AJS.js";
+import "../chunk-GXNLGKAB.js";
 import "../chunk-LL4KHSZI.js";
 import {
   configureGuardrails,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
 } from "../chunk-4ZG3XFUR.js";
-import "../chunk-774ILSRL.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
@@ -176,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();
@@ -305,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) {
@@ -597,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;
@@ -740,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") {
@@ -869,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.9).
+> **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.9).
+> **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.9`.
+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. |

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.9).
+> **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`.
 
@@ -25,12 +25,34 @@ graph TD
 | :--- | :--- | :--- |
 | 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, followed by cached probe discovery. Other local-native targets default to one slot. vLLM and SGLang remain 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:
@@ -72,13 +94,29 @@ 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 two moves that actually free capacity:
+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): the orchestrator's own turn holds one; collect in-flight runs or point workers at a second server
+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 is the exact text on 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.
+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
 

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.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.4.0).
 
 
 Clio Coder is a terminal-first alpha harness. This page keeps the command
@@ -46,11 +46,18 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder auth login [target-or-runtime] [--api-key <value>]` | Add credentials through the supported flow. |
 | `clio-coder auth logout [target-or-runtime]` | Remove stored credentials. |
 | `clio-coder doctor [--fix] [--json]` | Diagnose state; with `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict and are not migrated. |
+| `clio-coder tools list [--json]` | List the pinned external tool registry and whether each program resolves from `PATH`, Clio's vendored data directory, or nowhere. |
+| `clio-coder tools status <id> [--json] [--reset-profile]` | Inspect one registered tool. `--reset-profile` applies only to yazi's generated profile. |
+| `clio-coder tools install <id> [--force] [--json]` | Download the platform asset, verify every declared checksum, and atomically vendor it. |
+| `clio-coder tools remove <id>\|--all [--json]` | Remove Clio-vendored copies without touching a program found on `PATH`. |
+| `clio-coder panes install` | Alias for `clio-coder tools install herdr`. |
 | `clio-coder reset [--state\|--data\|--cache\|--auth\|--config\|--all] [--dry-run] [--force]` | Reset selected Clio Coder state. `--state` is the default level. |
 | `clio-coder uninstall [--dry-run] [--remove-binary] [--force]` | Remove Clio Coder state and print uninstall guidance. |
 | `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
 | `clio-coder agents [--json] [--all]` | List discovered agent specs. |
-| `clio-coder fleet list\|run\|status\|drain\|resume` | List `.clio-coder/fleets/*.md` contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
+| `clio-coder fleet list\|run\|status\|drain\|resume` | List fleet contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
+| `clio-coder fleet view <runId\|fleetRootId> [--follow]` | Read the append-only run journal after verifying receipt trust. A fleet root prints its durable step index. `--follow` requires an interactive terminal and one run id. |
+| `clio-coder fleet view --watch <selection-file>` | Follow the run id currently named by the selection file and retarget when it changes. This is the operator-pulled watch surface used by the pane integration. |
 | `clio-coder dev components [list] [--json]` | List behavior-affecting harness components. |
 | `clio-coder dev components snapshot --out <path>` | Write a component snapshot JSON file. |
 | `clio-coder dev components diff --from <a> --to <b> [--json]` | Compare component snapshots. |
@@ -105,6 +112,15 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--tool-profile <name>` | Restrict dispatched-agent tools: `minimal-local`, `science-local`, or `full-agent`. |
 | `--require <capability>` | Require a target capability for dispatch. Repeatable. |
 | `--steer-channel <path>` | Read live steering lines from a FIFO or an appended regular file to steer the active run. |
+| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `panes.enabled`. |
+| `--no-panes` | Disable pane integration for this invocation. It overrides `panes.enabled`. |
+
+`--with-panes` is an explicit first-class launch mode, not permission to start a
+pane server. Clio confirms `HERDR_ENV=1`, connects to an existing socket, and
+pings it before registering pane tools. The fleet watch pane runs
+`fleet view --watch` against a selection file. Clio writes only the selected run
+id, while the viewer reads journals itself, so dispatch remains independent of
+the pane host and a second terminal can use the same journal surface directly.
 
 ### Headless Session Continuity
 
@@ -164,6 +180,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/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 |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
+| `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane |
 | `/thinking` | `/thinking [level]` | Set the chat thinking level, or open Settings → Orchestrator |
 | `/output` | `/output [verbosity]` | Set transcript detail (minimal, default, verbose), or open Settings → Terminal |
 | `/model` | `/model [pattern]` | Open model selector or set a model |
@@ -195,6 +212,14 @@ There are no slash-command aliases. `/context compact`, `/quit`, `/model`,
 spellings stay errors that name `/help` instead of guessing which operation the
 operator intended.
 
+`/model` never changes routing on its own. Both spellings, the picker and
+`/model <pattern>`, resolve the swap and then ask where it lands: `Apply this
+session`, `Apply and save globally`, or `Cancel`. Session is the default and
+touches no file, so a mid-conversation experiment dies with the session that
+made it; global is the same write the settings center performs, and it is the
+only one a later launch inherits. Cancel leaves the model where it was. A
+thinking level named in the pattern follows the same choice.
+
 `/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
@@ -277,6 +302,10 @@ it is never sent to the model. That covers spellings removed outright, such as
 behavior where an unrecognized spelling reached the model as prose and was answered
 conversationally, which left the operator believing a command had run when nothing had.
 
+A headless `clio-coder run "/typo"` refuses the same way. The verdict is reached
+before boot, so no session is opened and no turn is spent; the diagnostic names
+the token on stderr and the run exits `2`, the usage-error code.
+
 Command-shaped means one word of letters, digits, hyphens, or colons after the slash, so
 paths such as `/home/user/notes.md` still reach the model unchanged. One word
 followed by prose is treated as a command, because `/status please` and `/tmp is