@iowarp/clio-coder 0.3.0 → 0.3.1

package/dist/worker/entry.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   createEngineAgent,
   createLoopGuardRegistration,
@@ -6,11 +7,12 @@ import {
   describeCallTarget,
   isLoopGuardSynthesisBackstopReason,
   isReserveAdmittedTool,
+  lockedSynthesisFallbackText,
   patchWorkerRequestPayload,
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-BYEU76JP.js";
+} from "../chunk-DKGKUHFA.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
   DEFAULT_ESCALATION_TIMEOUT_MS,
@@ -32,29 +34,30 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-GNGDQYDU.js";
-import "../chunk-2J63S4SF.js";
-import "../chunk-RQDWMVRB.js";
-import "../chunk-7BHLZB3A.js";
-import "../chunk-TPOCL34A.js";
-import "../chunk-E3NYWENM.js";
+} from "../chunk-7SS2CTV2.js";
+import "../chunk-FST4FYJB.js";
+import "../chunk-BSU2YIWB.js";
+import "../chunk-ZPY3JZ5E.js";
+import "../chunk-N6F52NLF.js";
+import "../chunk-LU4TK2PR.js";
 import {
   RESULT_CONTRACT_REPAIR_LIMIT,
   parseResultContract,
-  resultContractRepairMessage,
+  resultContractRepairMessages,
   validateResultContract
-} from "../chunk-XV4ZJ6ZM.js";
-import "../chunk-26BZQOAD.js";
-import "../chunk-WD6AJM35.js";
+} from "../chunk-GEP36Y4X.js";
+import "../chunk-OLBBMFRD.js";
+import "../chunk-474KN5II.js";
 import {
   ToolNames
-} from "../chunk-QV47YRF4.js";
-import "../chunk-CLJ5HLUD.js";
+} from "../chunk-CGKSTWHD.js";
+import "../chunk-C4PTHK7P.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
   WORKER_RESOURCE_LABEL_MAX,
   WORKER_STDIN_FRAME_MAX_BYTES,
+  canonicalJson,
   encodeControlFrame,
   endpointIdentityHash,
   knownResource,
@@ -62,8 +65,8 @@ import {
   parseAgentLedgerEntry,
   withinFrameBudget,
   workerSpecDigest
-} from "../chunk-BBUH4VAA.js";
-import "../chunk-GOTUR54M.js";
+} from "../chunk-GAEBEQVI.js";
+import "../chunk-TXOTCRLG.js";
 import {
   FileKnowledgeBase,
   applyModelCapabilityPatch,
@@ -78,31 +81,42 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-TKHQ4DGZ.js";
-import "../chunk-D5YD55AR.js";
+} from "../chunk-H6F6BYOH.js";
+import "../chunk-EYOKLTMF.js";
+import "../chunk-IHXBNWMM.js";
+import "../chunk-Q5WJOSJ7.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-JWHCJDCI.js";
+} from "../chunk-KY56HMHH.js";
 import {
   configureGuardrails,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
-} from "../chunk-UHTSULZS.js";
-import "../chunk-5LDRNKX2.js";
-import "../chunk-UGYAX5YI.js";
-import "../chunk-5N2FG33Q.js";
-import "../chunk-VPAWTYLY.js";
-import "../chunk-X3NE4WVW.js";
+} from "../chunk-NMOX6HFD.js";
+import "../chunk-GB6QRBXN.js";
+import "../chunk-3I7MS7N2.js";
+import "../chunk-HQQID6OA.js";
+import "../chunk-R346GLFC.js";
+import "../chunk-WEPFGWHJ.js";
+import "../chunk-BNAZZHFG.js";
 import {
   readClioVersion
-} from "../chunk-DXQNI4PC.js";
+} from "../chunk-IWHMRKLL.js";
+import {
+  init_esm_shims
+} from "../chunk-3R73A4XB.js";
+
+// src/worker/entry.ts
+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";
@@ -648,6 +662,9 @@ function terminalContractViolation(contract, message, cwd, observedReadRanges, o
   if (!isAssistantMessage(message)) return null;
   const text = assistantMessageText(message);
   if (text === null || text.length === 0) return "missing final result";
+  if (text.trim() === lockedSynthesisFallbackText()) {
+    return "the reply after the tool-call lockout held only tool-call markup and was removed; tools are off, so state the final result as plain text";
+  }
   const stopReason = message.stopReason;
   if (shouldRequestStalledTurnContinuation({
     hook: "turn_end",
@@ -775,6 +792,7 @@ function startWorkerRun(input, emit) {
   let workerBoundFailure = null;
   let workerBoundAborted = false;
   let abortWorkerForBound = null;
+  const STOP_AFTER_ANY_TOOL_RESULT = /* @__PURE__ */ Symbol("stop-after-any-tool-result");
   let stopAfterToolResultCallId = null;
   const workerBudget = resolveWorkerRuntimeBudget(input);
   const readReserve = input.allowedTools.includes(ToolNames.Read) ? workerBudget.readReserve : 0;
@@ -810,9 +828,11 @@ function startWorkerRun(input, emit) {
         ...deliveryTools.length > 0 ? { deliveryTools } : {},
         turnSynthesisLockout: workerBudget.synthesis,
         // Once locked, the next model round is forced text-only at the
-        // request level (tool_choice none in onPayload below): the lockout
-        // directive alone relies on model compliance, and measured local
-        // models kept calling tools until the backstop aborted the run.
+        // request level (the tool surface is removed in onPayload below):
+        // the lockout directive alone relies on model compliance, and
+        // measured local models kept calling tools until the backstop
+        // aborted the run, or answered the forced round with tool-call
+        // markup that the loop guard then removed.
         onSynthesisLockout: () => {
           if (workerBudget.synthesis) {
             synthesisToolLock = true;
@@ -823,7 +843,7 @@ function startWorkerRun(input, emit) {
             if (workerBoundFailure === null) {
               workerBoundFailure = `worker agent budget reached (${workerBudget.toolCalls}); synthesis is disabled`;
             }
-            stopAfterToolResultCallId = toolCallId ?? "";
+            stopAfterToolResultCallId = toolCallId ?? STOP_AFTER_ANY_TOOL_RESULT;
           }
         } : {},
         // Forcing the next round to `read` is only correct when reading is
@@ -936,7 +956,8 @@ function startWorkerRun(input, emit) {
         runtimeId: input.runtime.id,
         thinkingLevel: effectiveThinkingLevel,
         ...input.responseSchema !== void 0 ? { responseSchema: input.responseSchema } : {},
-        toolChoiceNone: synthesisToolLock || middlewareChoice.kind === "none",
+        toolSurfaceLocked: synthesisToolLock,
+        toolChoiceNone: middlewareChoice.kind === "none",
         ...middlewareChoice.kind === "required" ? { toolChoiceName: middlewareChoice.toolName } : {}
       });
     },
@@ -944,6 +965,7 @@ function startWorkerRun(input, emit) {
   };
   if (input.sessionId) options.sessionId = input.sessionId;
   const { agent } = createEngineAgent(options);
+  agent.followUpMode = "all";
   abortWorkerForBound = () => agent.abort();
   const unsubscribe = agent.subscribe(async (event) => {
     if (event.type === "turn_start") workerModelRound += 1;
@@ -983,16 +1005,11 @@ function startWorkerRun(input, emit) {
         if (resultContractRepairsQueued < RESULT_CONTRACT_REPAIR_LIMIT) {
           resultContractRepairsQueued += 1;
           synthesisToolLock = true;
-          agent.followUp(
-            taskMessage(
-              resultContractRepairMessage({
-                contract,
-                reason: violation,
-                attempt: resultContractRepairsQueued,
-                anchors: observedReadAnchors()
-              })
-            )
+          const repair = resultContractRepairMessages(
+            { contract, reason: violation, attempt: resultContractRepairsQueued, anchors: observedReadAnchors() },
+            { provider: model.provider, api: model.api, model: model.id }
           );
+          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" } });
@@ -1002,7 +1019,7 @@ function startWorkerRun(input, emit) {
       }
     }
     emit(event);
-    if (stopAfterToolResultCallId !== null && event.type === "message_end" && event.message.role === "toolResult" && (stopAfterToolResultCallId.length === 0 || event.message.toolCallId === stopAfterToolResultCallId)) {
+    if (stopAfterToolResultCallId !== null && event.type === "message_end" && event.message.role === "toolResult" && (stopAfterToolResultCallId === STOP_AFTER_ANY_TOOL_RESULT || event.message.toolCallId === stopAfterToolResultCallId)) {
       stopAfterToolResultCallId = null;
       workerBoundAborted = true;
       abortWorkerForBound?.();
@@ -1017,6 +1034,8 @@ function startWorkerRun(input, emit) {
   const denyReason = (tool, actionClass) => `permission denied by policy: dispatched workers run non-interactively (workers.onPermission=deny); ${tool} requires ${actionClass} confirmation`;
   const failReason = (tool, actionClass) => `permission required for ${tool} (${actionClass}); workers.onPermission=fail ends this run`;
   let activeEscalation = null;
+  const answeredEscalations = /* @__PURE__ */ new Map();
+  const escalationCallKey = (tool, args) => `${tool}\0${canonicalJson(args ?? {})}`;
   const clearActiveEscalation = () => {
     if (activeEscalation) {
       clearTimeout(activeEscalation.timer);
@@ -1027,6 +1046,7 @@ function startWorkerRun(input, emit) {
     const active = activeEscalation;
     if (!active || active.requestId !== requestId) return false;
     clearActiveEscalation();
+    answeredEscalations.set(active.callKey, { decision, requestId });
     if (decision === "approve") {
       emit({
         type: "clio_permission_resolved",
@@ -1093,10 +1113,38 @@ function startWorkerRun(input, emit) {
   const unsubscribePermission = registry.onPermissionRequired((call, decision, meta) => {
     const actionClass = decision.classification.actionClass;
     if (escalationConfig) {
+      const callKey = escalationCallKey(call.tool, call.args);
+      const remembered = answeredEscalations.get(callKey);
+      if (remembered !== void 0) {
+        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",
+          payload: {
+            tool: call.tool,
+            actionClass,
+            mode: "escalate",
+            source: "remembered",
+            requestId: meta.requestId,
+            decision: approved ? "approved" : "denied",
+            reason: reason2
+          }
+        });
+        if (approved) {
+          void registry.resumeParkedCalls({
+            actionClass,
+            requestId: meta.requestId,
+            requestedBy: "escalation:remembered"
+          });
+        } else {
+          registry.cancelParkedCall(meta.requestId, reason2);
+        }
+        return;
+      }
       if (activeEscalation !== null) return;
       const requestId = meta.requestId;
       const timer = setTimeout(() => resolveEscalation(requestId, "deny", "timeout"), escalationConfig.timeoutMs);
-      activeEscalation = { requestId, tool: call.tool, actionClass, timer };
+      activeEscalation = { requestId, tool: call.tool, actionClass, callKey, timer };
       const target = describeCallTarget(call.args).slice(0, 200);
       emit({
         type: "clio_permission_escalated",
@@ -1198,6 +1246,7 @@ function startWorkerRun(input, emit) {
 }
 
 // src/worker/control-lane.ts
+init_esm_shims();
 function emitControlFrame(frame) {
   try {
     process.stderr.write(encodeControlFrame(frame));
@@ -1206,6 +1255,7 @@ function emitControlFrame(frame) {
 }
 
 // src/worker/event-projection.ts
+init_esm_shims();
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1218,14 +1268,16 @@ function projectWorkerEventForStdout(event) {
 }
 
 // src/worker/heartbeat.ts
+init_esm_shims();
 function startWorkerHeartbeat(intervalMs = 1e3) {
-  emitControlFrame({ kind: "heartbeat", at: Date.now() });
-  const id = setInterval(() => emitControlFrame({ kind: "heartbeat", at: Date.now() }), intervalMs);
+  emitControlFrame({ kind: "heartbeat" });
+  const id = setInterval(() => emitControlFrame({ kind: "heartbeat" }), intervalMs);
   id.unref?.();
   return () => clearInterval(id);
 }
 
 // src/worker/ledger-mirror.ts
+init_esm_shims();
 var WORKER_AGENT_LEDGER_POST_CAP = 20;
 function createWorkerAgentLedgerMirror() {
   const bySequence = /* @__PURE__ */ new Map();
@@ -1270,6 +1322,7 @@ function createWorkerAgentLedgerPort(deps) {
 }
 
 // src/worker/ndjson.ts
+init_esm_shims();
 function emitEvent(event) {
   try {
     process.stdout.write(`${JSON.stringify(event)}
@@ -1299,6 +1352,7 @@ function drainStdout(timeoutMs = 2e3) {
 }
 
 // src/worker/resource-facts.ts
+init_esm_shims();
 import { execFileSync } from "node:child_process";
 import { cpus, freemem, hostname, totalmem } from "node:os";
 var GPU_PROBE_TIMEOUT_MS = 1e3;
@@ -1343,6 +1397,7 @@ function observeHostIdentity() {
 }
 
 // src/worker/runtime-registry.ts
+init_esm_shims();
 async function resolveWorkerRuntime(runtimeId) {
   const registry = getRuntimeRegistry();
   registerBuiltinRuntimes(registry);
@@ -1351,6 +1406,7 @@ async function resolveWorkerRuntime(runtimeId) {
 }
 
 // src/worker/stdin-demux.ts
+init_esm_shims();
 function createOrderedSteerHandler(deliver, onAccepted, onRejected) {
   let tail = Promise.resolve();
   return (steer) => {
@@ -1569,6 +1625,7 @@ function createWorkerStdinDemux() {
 }
 
 // src/worker/entry.ts
+process.title = "clio-coder-worker";
 var CHANNEL_CLOSE_EXIT_GRACE_MS = 5e3;
 function configuredNodeLabels() {
   return (process.env.CLIO_CODER_WORKER_LABELS ?? "").split(",").map((label) => label.trim()).filter((label) => label.length > 0);
@@ -1619,6 +1676,7 @@ async function main() {
   process.stdin.on("error", () => demux.eof());
   process.stdin.resume();
   const spec = await demux.readSpec();
+  process.title = `clio-coder-worker:${spec.agentId}`;
   setProtectedModelsProvider(() => spec.protectedModels ?? []);
   const stopHeartbeat = startWorkerHeartbeat();
   const runtime = await resolveWorkerRuntime(spec.runtimeId);

package/docs/README.md

@@ -4,7 +4,7 @@
 
 # Clio Coder Documentation
 
-These pages document `v0.3.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).
+These pages document `v0.3.1` 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,10 +23,11 @@ current source, tests, and `CHANGELOG.md`.
 | 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) |
 | Prompt envelope reuse, provider tool delivery, and bounded tool results | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) ([Interactive Blueprint](html/tools_blueprint.html)) |
-| In-depth reference for all 19 worker tools: parameters, typical payloads, and error examples | [tool-usage.md](tool-usage.md) ([Interactive Blueprint](html/tool_usage_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)) |
 | Built-in agent recipes, discovery roots, frontmatter schema, and dispatch admission | [built-in-agents.md](built-in-agents.md) ([Interactive Blueprint](html/agents_blueprint.html)) |
 | Artifact browsing, receipt verification, dispatch diagnostics, and observability routing | [observability.md](observability.md) ([Interactive Blueprint](html/observability_blueprint.html)) |
+| Where every generated file lands: the working tree, `.clio-coder/`, and the XDG dirs, by audience | [artifact-placement.md](artifact-placement.md) |
 | Evidence directory structures, findings, and operator-approved memory retrieval | [evidence-and-memory.md](evidence-and-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
 | Local YAML eval suites, reports, comparisons, and command evidence | [eval-runner.md](eval-runner.md) ([Interactive Blueprint](html/eval_blueprint.html)) |
 | Prompt and skill resources, extension manifests, and portable share archives | [extensions-and-sharing.md](extensions-and-sharing.md) ([Interactive Blueprint](html/extensions_blueprint.html)) |
@@ -46,12 +47,14 @@ current source, tests, and `CHANGELOG.md`.
 | Version registry and migration policies for all 9 serialized artifact schemas | [artifact-versions.md](artifact-versions.md) |
 | Process exit code taxonomy, `--help` standard, machine-readable JSON streaming, and headless output contracts | [exit-codes-and-output.md](exit-codes-and-output.md) |
 | Actionable error remediation and diagnostics keyed by exact user-facing messages | [troubleshooting.md](troubleshooting.md) |
-| Canonical definitions of 17 core architectural concepts mapped to `src/` types | [glossary.md](glossary.md) |
+| Canonical definitions of 40 core architectural concepts mapped to `src/` types | [glossary.md](glossary.md) |
 | Complete source-to-documentation mapping matrix and subsystem coverage status | [documentation-coverage.md](documentation-coverage.md) |
+| Issue-driven development lifecycle: file-ticket through release, label taxonomy, and dogfooding setup | [development-pipeline.md](development-pipeline.md) |
 | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying | [proactive-memory.md](proactive-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
 | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and CLI trace subcommands | [trace-store.md](trace-store.md) ([Interactive Blueprint](html/trace_blueprint.html)) |
 | Private context index determinism, target smoke matrices, and Clio machinery soak benchmark suite | [evals-internal.md](evals-internal.md) ([Blueprints: evals_internal](html/evals_internal_blueprint.html), [soak](html/soak_blueprint.html)) |
 | Point-in-time inventory of legacy environment variables (Historical Appendix) | [config-knobs-audit.md](config-knobs-audit.md) ([Interactive Blueprint](html/config_knobs_audit_blueprint.html)) |
+| Clock and timestamp conventions: durations, instants, ordering, and formatting | [time-conventions.md](time-conventions.md) |
 
 Every project Clio works in gets its context from a checked-in `CLIO-CODER.md`,
 bootstrapped and maintained by `clio-coder context init`. The root
@@ -74,12 +77,12 @@ 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.0 the supported
-install path is a source checkout through `npm run install:local`, the
-deterministic release gate is `npm run ci:release`, live model smoke
-validation is local/manual and opt-in through `npm run test:live` (add
-`-- --delegation` for opencode/copilot checks), and the package
-is not published to npm.
+history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.3.1 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
+opt-in through `npm run test:live` (add `-- --delegation` for
+opencode/copilot checks).
 
 ## Writing Documentation
 

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.0`.
+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.1`.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 
@@ -30,8 +30,8 @@ The server is invoked via:
 clio-coder acp [--cwd PATH] [--permission-timeout MS]
 ```
 
-- `--cwd PATH`: Sets the initial workspace root directory for ACP sessions.
-- `--permission-timeout MS`: Configures the maximum timeout for delegated permission resolution (defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` ms from `src/core/defaults.ts:40`).
+- `--cwd PATH`: Workspace root the server boots in. Clio changes into the directory before it reads settings, builds project context, or opens a session ledger, so a session opens at that root. A path the process cannot enter exits 2 without starting the server.
+- `--permission-timeout MS`: How long a mediated permission request may wait for the client before it is denied, as a positive whole number of milliseconds. It overrides `delegation.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:143`).
 
 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.
 
@@ -85,12 +85,35 @@ Under `clio-policy` governance:
 The ACP boundary enforces strict isolation rules:
 
 1. **Autonomy Snapshotting**: The autonomy level is snapshotted at `session/new`. A subsequent configuration change on the host does not alter an active remote session's security policy.
-2. **Metadata Namespacing**: Clio-specific extensions travel exclusively within namespaced metadata fields (`ACP_USAGE_META_KEY = "clio.coder/usage"`, `ACP_SESSION_META_KEY = "clio.coder/session"` in `src/engine/acp/types.ts:8-9`). Strict clients (e.g. Zed Serde deserializers) never encounter unmapped top-level keys.
+2. **Metadata Namespacing**: Clio-specific extensions travel exclusively within namespaced metadata fields (`ACP_USAGE_META_KEY = "clio-coder/usage"`, `ACP_SESSION_META_KEY = "clio-coder/session"` in `src/engine/acp/types.ts:8-9`). Strict clients (e.g. Zed Serde deserializers) never encounter unmapped top-level keys.
 3. **No External Outcome Overrides**: External ACP processes cannot self-assert terminal outcome codes (e.g. `worker_final_output_missing` is enforced at Clio's trusted finalization seam).
 
 ---
 
-## 6. Error Taxonomy
+## 6. Delegation Peers in the Transcript
+
+The sections above describe Clio as an ACP server. In the other direction, Clio
+is an ACP client: `/delegate <agent-id> <task>` and any dispatch to an agent id
+configured under `delegation.agents` run the task on an external peer such as
+`codex` or `opencode`.
+
+A delegated peer is a worker like any other on screen. The adapter maps the
+peer's `text_delta` and `message_end` notifications onto the same dispatch event
+stream a local Clio worker publishes, so the peer's answer renders in the chat
+transcript as the same attributed block, with the same fold behavior, the same
+`--share` and `/share` path into the main agent's context, and the same replay
+from a sealed receipt. There is no ACP-specific UI path.
+
+The header is where the difference shows. A local Clio worker names the target
+and model it ran on; a peer runs behind someone else's process and can honestly
+name only the protocol it was reached through, so its header reads `◇ codex
+(acp) · run 7hq2ab`. Its footer reports elapsed and, when the peer reports no
+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.
+
+---
+
+## 7. Error Taxonomy
 
 The ACP subsystem defines four typed error classes (`src/engine/acp/errors.ts`):
 

package/docs/alcf-provider.md

@@ -1,7 +1,7 @@
 # ALCF Inference Provider
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive target configurator and Globus OAuth flow diagram is located at [docs/html/alcf_blueprint.html](html/alcf_blueprint.html) (Version: 0.3.0).
+> **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.1).
 
 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.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.3.1).
 
 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.0` development line.
+This page is source-code aligned for the current `v0.3.1` development line.
 
 ---
 
@@ -37,6 +37,7 @@ Registered domain modules include:
 | evidence | `src/domains/evidence/**` | Forensic evidence bundles, failure attribution. |
 | evolution | `src/domains/evolution/**` | Authority-tiered self-edit manifests and gates. |
 | extensions | `src/domains/extensions/**` | Extension discovery, packaging, and lifecycle. |
+| interop | `src/domains/interop/**` | The agent-kind registry, bounded detection of other coding agents, and consent to wire one as a delegation peer. |
 | lifecycle | `src/domains/lifecycle/**` | Doctor diagnostics, upgrade mechanics, uninstallation. |
 | memory | `src/domains/memory/**` | Approved long-term memory, proactive task intervention. |
 | middleware | `src/domains/middleware/**` | Declarative and programmatic lifecycle hooks and budgets. |
@@ -49,6 +50,26 @@ Registered domain modules include:
 | session | `src/domains/session/**` | Append-only JSONL transcripts, tree navigation, compaction. |
 | share | `src/domains/share/**` | Portable workspace and resource archive export/import. |
 
+The `interop` domain owns one question: which other coding agents are on this
+machine and in this project. `src/domains/interop/registry.ts` is pure data, one
+entry per known agent carrying its binaries, the directories it owns, its skill
+and prompt roots, its instruction filenames, and the ACP launch recipe when it
+has one. Every other module that used to keep its own copy of that list now
+derives it: the skills loader and the prompts loader take their compatibility
+roots from the table, the adoption scanner takes its candidate files from it,
+and the safety path policy takes the foreign directories it refuses to write
+into from it.
+
+The domain owns detection and consent, and nothing else. It never executes a
+foreign agent's work command, never loads a skill, prompt, or rule itself, and
+never reads under a foreign agent's `sessions`, `history`, `cache`, `projects`,
+or `state` directory. Detection resolves binaries with `access(X_OK)` and no
+shell, checks install directories, and runs a bounded `--version` only when the
+caller asks and only for a binary that already resolved; a probe that cannot
+answer reports `unknown` and never `absent`. The one durable configuration write
+is an append to `delegation.agents`, and it happens only after an operator
+decision.
+
 ---
 
 ## Session Routing vs. Persisted Settings

package/docs/artifact-placement.md

@@ -0,0 +1,101 @@
+# Artifact Placement
+
+Every file Clio generates has one home, decided by who reads it. The rule that
+follows from that: **the repo working tree holds files a human asked for.**
+Anything Clio produced on its own initiative lands in the gitignored project
+directory or under the XDG dirs, never beside your source.
+
+This page is the contract. `src/core/artifact-paths.ts` is the code that
+implements the part of it the `artifact` tool owns.
+
+## Three audiences
+
+| Audience | What it means | Where it goes |
+| --- | --- | --- |
+| Human deliverable | A file the user asked to keep, and will read and commit | Repo working tree, at the path the user named |
+| Human transient | Something a human may want to read once; losing it costs nothing | Project-local `.clio-coder/` (gitignored) |
+| Agent-to-agent state | Machine-read plumbing between turns, workers, and sessions | `.clio-coder/` for per-project state; XDG data/state/cache for per-machine state |
+
+A class is human-facing only if a person is expected to open it. A plan an
+agent wrote for its own next step is agent-to-agent state even though it is
+Markdown.
+
+## Placement by class
+
+| Class | Location | Audience |
+| --- | --- | --- |
+| `artifact` tool plan / review / report | `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, `REPORT.md` | Human transient |
+| Any artifact the user named a path for | that path, inside the workspace | Human deliverable |
+| RCA write-ups for shipped fixes | the GitHub issue's closing comment, never a committed file | Human deliverable |
+| Codewiki index | `.clio-coder/codewiki.json` | Agent-to-agent |
+| Markdown wiki | `.clio-coder/wiki/` | Human transient |
+| Session context state | `.clio-coder/state.json` | Agent-to-agent |
+| Task-memory handoffs | `.clio-coder/handoffs/` | Agent-to-agent |
+| Dispatch proposals | `.clio-coder/proposals/` | Agent-to-agent |
+| Compete worktrees | `.clio-coder/worktrees/` | Agent-to-agent |
+| Test scratch | `.clio-coder/test-scratch/` | Agent-to-agent |
+| Evidence bundles | XDG data `evidence/` | Human transient (`clio-coder evidence`) |
+| Approved memory | XDG data `memory/` | Human transient (`clio-coder memory`) |
+| Eval artifacts | XDG data `evals/` | Human transient (`clio-coder eval`) |
+| Session ledgers | XDG state `sessions/` | Agent-to-agent |
+| Dispatch receipts | XDG state `receipts/` | Human transient (`clio-coder trace`) |
+| Audit records | XDG state `audit/` | Human transient |
+| Interview transcripts | XDG state `interviews/` | Agent-to-agent |
+| Harness scratch | XDG state `scratch/` | Agent-to-agent |
+| Caches | XDG cache | Agent-to-agent |
+
+`clio-coder paths` prints the resolved XDG directories for your machine.
+
+## The `artifact` tool default
+
+`artifact(kind: plan|review|report)` without a `path` writes to
+`.clio-coder/artifacts/` under the workspace root. Passing `path` writes exactly
+there instead, working tree included, because a path the user named is a file
+the user asked for. A path that escapes the workspace is refused.
+
+The default is a pure function of `kind`, and has to stay that way. The action
+classifier, the policy engine's write-root check, and the protected-artifacts
+guard all predict where a pathless call will write, from its arguments alone,
+before the tool runs. A default keyed on a session id or a timestamp would make
+that prediction impossible and leave the safety layer guarding a path nobody
+writes. The consequence is one file per kind: a second report overwrites the
+first. Keep several by naming explicit paths.
+
+## `.clio-coder/` and git
+
+`.clio-coder/` is gitignored in full. Everything above that lands there is
+generated, reproducible, and worthless in a diff, and the whole point of the
+contract is that a dogfooding session ends with `git status` clean.
+
+Some `.clio-coder/` content is authored rather than generated, and a project
+that wants it reviewed and shared commits it deliberately by adding negations
+next to the ignore:
+
+```gitignore
+.clio-coder/
+!.clio-coder/fleets/          # fleet contracts: repo-owned dispatch policy
+!.clio-coder/fleets/**
+!.clio-coder/rules/           # path-scoped project rules
+!.clio-coder/rules/**
+!.clio-coder/safety.yaml      # project safety policy
+!.clio-coder/agents/          # project agent recipes
+!.clio-coder/agents/**
+```
+
+This repository commits none of those, so its `.clio-coder/` stays fully
+ignored except the seeded soak fixtures under `benchmarks/soak/fixtures/`,
+which are test inputs rather than session output.
+
+## Finding what was hidden
+
+Hiding transient output from the working tree must not mean losing it.
+
+- `.clio-coder/artifacts/` is a plain directory; open it.
+- `clio-coder evidence` lists and inspects evidence bundles.
+- `clio-coder trace` queries the dispatch trace mirror and its receipts.
+- `clio-coder memory` lists proposed and approved memory.
+- `clio-coder paths` locates every XDG root.
+
+Related: [evidence-and-memory.md](evidence-and-memory.md),
+[trace-store.md](trace-store.md), [observability.md](observability.md),
+[development-pipeline.md](development-pipeline.md) for where RCAs are committed.

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.0`.
+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.1`.
 
 ---