@iowarp/clio-coder 0.3.9 → 0.4.1

package/dist/worker/entry.js

@@ -16,28 +16,32 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-R7LNVMCS.js";
+} from "../chunk-QMXC4JB7.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-GAYUJ7LE.js";
+} from "../chunk-JA5QWE4Z.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-7OBGU7UB.js";
+import "../chunk-ABLSQ6JX.js";
+import "../chunk-PBP4B7XR.js";
+import "../chunk-JZWT5J3Y.js";
+import "../chunk-I66EAJFY.js";
 import "../chunk-VG7TBQIY.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
@@ -46,43 +50,37 @@ import {
   claudeToolsOutsideProfile,
   coerceToolInput,
   createRunEffectsRecorder,
-  describeCallTarget,
   emitClaudeToolPermissionDecision,
   isClaudeCodeSessionId,
+  nodeResultContractFilesystem,
   parseWorkerSpec,
   runtimeSpeaksResponseSchemaDialect,
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-4H6ULJ3H.js";
-import "../chunk-VPTUJU4P.js";
-import "../chunk-2JDWVJND.js";
-import "../chunk-H7IXIC72.js";
-import "../chunk-7C6RYZGQ.js";
+} from "../chunk-2VG7KLYV.js";
+import "../chunk-7EPLI7VL.js";
+import "../chunk-6DWBAZ5U.js";
+import "../chunk-PVAMAVBB.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-IXJT6DCX.js";
 import {
-  protectedArtifactMutationBlockReason
-} from "../chunk-MV3K5QF2.js";
+  describeCallTarget
+} from "../chunk-TVHHYFHE.js";
+import "../chunk-42FMPA75.js";
+import "../chunk-H7IXIC72.js";
+import "../chunk-VN3SHNBN.js";
+import "../chunk-OQE5J4C6.js";
 import {
   DEFAULT_AUTONOMY_LEVEL,
   agentSkillToolPolicy
-} from "../chunk-RAPCMZL4.js";
-import "../chunk-UL3WSD3F.js";
-import "../chunk-ODFEOB4F.js";
+} from "../chunk-FSP7CMNU.js";
+import "../chunk-R23Z6K6I.js";
 import "../chunk-OZNBF4L3.js";
 import "../chunk-4BJ5BYCE.js";
-import "../chunk-ECH6PKUQ.js";
+import "../chunk-6XLNIQDB.js";
+import "../chunk-U2WB7TZS.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -97,16 +95,27 @@ import {
   toolSignatureOf,
   withinFrameBudget,
   workerSpecDigest
-} from "../chunk-CMZWFGD2.js";
+} from "../chunk-VAVR4IJY.js";
 import {
   deleteInjectedCompileCacheFrom
-} from "../chunk-I4HZDVNP.js";
-import "../chunk-ZI647VB5.js";
-import "../chunk-6XLNIQDB.js";
+} from "../chunk-2LEAKD4C.js";
+import "../chunk-HHV2GANA.js";
+import {
+  RESULT_CONTRACT_REPAIR_LIMIT,
+  classify,
+  parseWorkerResultContract,
+  resultContractRepairMessages,
+  validateResultContract
+} from "../chunk-IG7BCQBA.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 +127,27 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-MIX5N5AC.js";
+} from "../chunk-UEDMSP56.js";
 import "../chunk-CFGTUFWB.js";
-import "../chunk-LU7P4LHA.js";
-import "../chunk-AEYBF3TB.js";
+import "../chunk-72GZI5EV.js";
+import "../chunk-CWVRRIEI.js";
+import "../chunk-MQXIVJ35.js";
+import "../chunk-R346GLFC.js";
+import "../chunk-PMZVFWSR.js";
+import "../chunk-HLW2MRKE.js";
+import "../chunk-BTK3SSSK.js";
 import "../chunk-IHXBNWMM.js";
-import {
-  setGitCommitAttributionEnabled,
-  withManagedGitCommitAttributionEnvironment
-} from "../chunk-B5CSFE7B.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-PNY46YEY.js";
-import "../chunk-FQ4SKYE4.js";
-import "../chunk-ZGVHUX3M.js";
-import "../chunk-RKRLDWD3.js";
-import "../chunk-KV2AOLDF.js";
+} from "../chunk-EIMVLWB3.js";
+import "../chunk-D7E7WCDF.js";
+import "../chunk-HJWWJ6IL.js";
+import {
+  setGitCommitAttributionEnabled,
+  withManagedGitCommitAttributionEnvironment
+} from "../chunk-JIEGK6UF.js";
+import "../chunk-EBY63B7G.js";
 import {
   AI_AGENT_NAME
 } from "../chunk-6EJMN2Y3.js";
@@ -143,29 +156,30 @@ import {
 } from "../chunk-IWHMRKLL.js";
 import {
   registerBuiltinRuntimes
-} from "../chunk-JEQQR47K.js";
-import "../chunk-XDOQXGFO.js";
+} from "../chunk-QKIFBZKT.js";
+import "../chunk-BWW4HLO4.js";
 import "../chunk-LL4KHSZI.js";
 import {
   configureGuardrails,
+  guardrailValuesFromSettings,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
-} from "../chunk-4ZG3XFUR.js";
-import "../chunk-774ILSRL.js";
-import "../chunk-EQ63NRB7.js";
-import "../chunk-SST6Z5JA.js";
+} from "../chunk-NLFAQR7Z.js";
+import "../chunk-CDNVLKUX.js";
+import "../chunk-WNP7O5WZ.js";
+import "../chunk-336NSSKI.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-VO2LKSTM.js";
+import "../chunk-O42A54GG.js";
 import {
   registerFauxFromEnv
-} from "../chunk-UOSL25KY.js";
+} from "../chunk-VXMFAE2W.js";
 import "../chunk-YXLYO42X.js";
 import {
   init_esm_shims
@@ -176,14 +190,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 +315,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 +647,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;
@@ -672,7 +722,7 @@ function startClaudeSdkWorkerRun(input, emit) {
     },
     () => {
       budgetFailure = true;
-      emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+      emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
       abort();
     },
     resolveDeliveryTools(allowedToolSet, input.product)
@@ -697,7 +747,7 @@ function startClaudeSdkWorkerRun(input, emit) {
     if (hookInput.hook_event_name !== "PostToolBatch" || !budgetGate?.phaseReached()) return { continue: true };
     if (input.budget?.synthesis === false) {
       budgetFailure = true;
-      emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+      emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
       return { continue: false, stopReason: `worker agent budget reached (${input.budget.toolCalls})` };
     }
     return {
@@ -740,6 +790,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 +920,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";
 }
@@ -958,8 +998,8 @@ function startWorkerRun(input, emit) {
   }
   registerClioApiProviders();
   const workerSettings = validateSettingsFile().settings;
-  setGlobalDefaultMaxOutputTokens(workerSettings.defaults.maxTokens);
-  configureGuardrails(workerSettings.guardrails);
+  setGlobalDefaultMaxOutputTokens(workerSettings.chat.maxOutputTokens);
+  configureGuardrails(guardrailValuesFromSettings(workerSettings));
   const fauxModel = registerFauxFromEnv();
   const agentSkillPolicy = input.allowedTools.includes(ToolNames.Context) && input.noSkills !== true ? agentSkillToolPolicy(input.agentSkills ?? []) : void 0;
   const activeWorkerTools = workerProviderSupportsTools(input) ? input.allowedTools : [];
@@ -1072,13 +1112,13 @@ function startWorkerRun(input, emit) {
   );
   const telemetry = {
     onStart(event) {
-      emit({ type: "clio_tool_start", payload: event });
+      emit({ type: "clio_coder_tool_start", payload: event });
     },
     onFinish(event) {
-      emit({ type: "clio_tool_finish", payload: event });
+      emit({ type: "clio_coder_tool_finish", payload: event });
       if (event.outcome !== "blocked" || typeof event.reason !== "string") return;
       if (isWorkerToolCallCapSynthesisReason(event.reason)) {
-        emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+        emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
         if (workerBoundFailure === null) {
           workerBoundFailure = event.reason;
           process.stderr.write(`[worker] ${event.reason}
@@ -1088,7 +1128,7 @@ function startWorkerRun(input, emit) {
       }
       if (isWorkerToolCallCapExceededReason(event.reason) || isLoopGuardSynthesisBackstopReason(event.reason)) {
         emit({
-          type: "clio_run_outcome",
+          type: "clio_coder_run_outcome",
           payload: {
             outcomeCode: isLoopGuardSynthesisBackstopReason(event.reason) ? "loop_guard_tools_disabled_exhausted" : "worker_tool_call_cap_exhausted"
           }
@@ -1207,7 +1247,7 @@ function startWorkerRun(input, emit) {
           for (const message of repair) agent.followUp(message);
         } else if (workerBoundFailure === null) {
           workerBoundFailure = `result contract failed after ${RESULT_CONTRACT_REPAIR_LIMIT} bounded repair rounds: ${violation}`;
-          emit({ type: "clio_run_outcome", payload: { outcomeCode: "result_contract_exhausted" } });
+          emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "result_contract_exhausted" } });
           process.stderr.write(`[worker] ${workerBoundFailure}
 `);
         }
@@ -1244,7 +1284,7 @@ function startWorkerRun(input, emit) {
     answeredEscalations.set(active.callKey, { decision, requestId });
     if (decision === "approve") {
       emit({
-        type: "clio_permission_resolved",
+        type: "clio_coder_permission_resolved",
         payload: {
           tool: active.tool,
           actionClass: active.actionClass,
@@ -1267,7 +1307,7 @@ function startWorkerRun(input, emit) {
     const denialContext = source === "timeout" ? "escalation timed out with no operator decision" : "operator denied";
     const reason = effectiveFail ? `permission required for ${active.tool} (${active.actionClass}); ${denialContext} and workers fallback=fail ends this run` : `permission denied by ${source === "timeout" ? "escalation timeout fallback" : "operator"}: ${active.tool} requires ${active.actionClass} confirmation`;
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: active.tool,
         actionClass: active.actionClass,
@@ -1292,7 +1332,7 @@ function startWorkerRun(input, emit) {
     const active = activeEscalation;
     if (!active) return;
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: active.tool,
         actionClass: active.actionClass,
@@ -1314,7 +1354,7 @@ function startWorkerRun(input, emit) {
         const approved = remembered.decision === "approve";
         const reason2 = approved ? `operator approved an identical ${call.tool} call earlier in this run (request ${remembered.requestId}); the answer stands without a new prompt` : `permission denied by operator: an identical ${call.tool} call was already denied earlier in this run (request ${remembered.requestId}); the answer stands, so do not repeat this call`;
         emit({
-          type: "clio_permission_resolved",
+          type: "clio_coder_permission_resolved",
           payload: {
             tool: call.tool,
             actionClass,
@@ -1342,7 +1382,7 @@ function startWorkerRun(input, emit) {
       activeEscalation = { requestId, tool: call.tool, actionClass, callKey, timer };
       const target = describeCallTarget(call.tool, call.args);
       emit({
-        type: "clio_permission_escalated",
+        type: "clio_coder_permission_escalated",
         payload: {
           requestId,
           tool: call.tool,
@@ -1363,7 +1403,7 @@ function startWorkerRun(input, emit) {
     }
     const reason = onPermission === "fail" ? failReason(call.tool, actionClass) : denyReason(call.tool, actionClass);
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: call.tool,
         actionClass,
@@ -1864,7 +1904,7 @@ async function main() {
     process.stderr.write(`[worker] residency ${notice.kind}: ${notice.message}
 `);
     if (notice.kind === "will-not-fit") {
-      emitEvent({ type: "clio_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
+      emitEvent({ type: "clio_coder_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
     }
   });
   const demux = createWorkerStdinDemux();
@@ -1953,7 +1993,7 @@ async function main() {
   demux.onSteer(
     createOrderedSteerHandler(
       (text) => handle.steer?.(text) ?? false,
-      ({ text, sequence }) => emitEvent({ type: "clio_steer_received", payload: { chars: text.trim().length, sequence } }),
+      ({ text, sequence }) => emitEvent({ type: "clio_coder_steer_received", payload: { chars: text.trim().length, sequence } }),
       (reason) => process.stderr.write(`[worker] dropped steer: ${reason}
 `)
     )

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,8 +35,12 @@ 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`.
+- `--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`). The shipped Workbench treats the remaining ACP request window as a hard ceiling on its own approval budget, projects that duration onto the Workbench clock, escalates immediately when the remaining window is shorter than its escalation delay, and cancels without publishing a card if the window has already elapsed. Other clients may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
 
 Transport frames are JSON-RPC 2.0 messages serialized over `stdin`/`stdout`. All logging and diagnostic output is strictly routed to `stderr` to preserve standard I/O framing integrity.
 
@@ -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. |