cool-workflow 0.1.95 → 0.1.96

package/dist/state-explosion/size.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = exports.STATE_EXPLOSION_SCHEMA_VERSION = void 0;
+exports.computeStateSize = computeStateSize;
+exports.computeStateSizeWithGraph = computeStateSizeWithGraph;
+const multi_agent_operator_ux_1 = require("../multi-agent-operator-ux");
+exports.STATE_EXPLOSION_SCHEMA_VERSION = 1;
+exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = {
+    graphNodes: 40,
+    graphEdges: 60,
+    blackboardMessages: 25,
+    blackboardRecords: 40,
+    collapseBucket: 6,
+    totalRecords: 80
+};
+function computeStateSize(run, thresholds = exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS) {
+    return computeStateSizeWithGraph(run, thresholds, (0, multi_agent_operator_ux_1.buildMultiAgentOperatorGraph)(run));
+}
+function computeStateSizeWithGraph(run, thresholds, graph) {
+    const ma = run.multiAgent || { runs: [], roles: [], groups: [], memberships: [], fanouts: [], fanins: [] };
+    const bb = run.blackboard || { topics: [], messages: [], contexts: [], artifacts: [], snapshots: [], decisions: [] };
+    const counts = {
+        multiAgentRuns: (ma.runs || []).length,
+        roles: (ma.roles || []).length,
+        groups: (ma.groups || []).length,
+        memberships: (ma.memberships || []).length,
+        fanouts: (ma.fanouts || []).length,
+        fanins: (ma.fanins || []).length,
+        topics: (bb.topics || []).length,
+        messages: (bb.messages || []).length,
+        contexts: (bb.contexts || []).length,
+        artifacts: (bb.artifacts || []).length,
+        snapshots: (bb.snapshots || []).length,
+        decisions: (bb.decisions || []).length,
+        graphNodes: graph.nodes.length,
+        graphEdges: graph.edges.length
+    };
+    const total = counts.multiAgentRuns +
+        counts.roles +
+        counts.groups +
+        counts.memberships +
+        counts.fanouts +
+        counts.fanins +
+        counts.topics +
+        counts.messages +
+        counts.contexts +
+        counts.artifacts +
+        counts.snapshots +
+        counts.decisions;
+    const reasons = [];
+    if (counts.graphNodes > thresholds.graphNodes)
+        reasons.push(`graph has ${counts.graphNodes} nodes (> ${thresholds.graphNodes})`);
+    if (counts.graphEdges > thresholds.graphEdges)
+        reasons.push(`graph has ${counts.graphEdges} edges (> ${thresholds.graphEdges})`);
+    if (counts.messages > thresholds.blackboardMessages)
+        reasons.push(`blackboard has ${counts.messages} messages (> ${thresholds.blackboardMessages})`);
+    const bbRecords = counts.topics + counts.messages + counts.contexts + counts.artifacts + counts.snapshots + counts.decisions;
+    if (bbRecords > thresholds.blackboardRecords)
+        reasons.push(`blackboard has ${bbRecords} records (> ${thresholds.blackboardRecords})`);
+    if (total > thresholds.totalRecords)
+        reasons.push(`run has ${total} multi-agent records (> ${thresholds.totalRecords})`);
+    return { ...counts, total, compactionRecommended: reasons.length > 0, reasons: reasons.sort() };
+}

package/dist/state-explosion.js

@@ -3,8 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stateExplosionReportLines = exports.formatBlackboardDigest = exports.formatCompactGraph = exports.formatStateExplosionReport = exports.fingerprintStrings = exports.GRAPH_VIEWS = exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = exports.STATE_EXPLOSION_SCHEMA_VERSION = void 0;
-exports.computeStateSize = computeStateSize;
+exports.stateExplosionReportLines = exports.formatBlackboardDigest = exports.formatCompactGraph = exports.formatStateExplosionReport = exports.fingerprintStrings = exports.GRAPH_VIEWS = exports.STATE_EXPLOSION_SCHEMA_VERSION = exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = exports.computeStateSizeWithGraph = exports.computeStateSize = void 0;
 exports.summarizeBlackboardDigest = summarizeBlackboardDigest;
 exports.buildCompactGraph = buildCompactGraph;
 exports.buildStateExplosionReport = buildStateExplosionReport;
@@ -21,15 +20,11 @@ const multi_agent_operator_ux_1 = require("./multi-agent-operator-ux");
 const trust_audit_1 = require("./trust-audit");
 const evidence_reasoning_1 = require("./evidence-reasoning");
 const helpers_1 = require("./state-explosion/helpers");
-exports.STATE_EXPLOSION_SCHEMA_VERSION = 1;
-exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS = {
-    graphNodes: 40,
-    graphEdges: 60,
-    blackboardMessages: 25,
-    blackboardRecords: 40,
-    collapseBucket: 6,
-    totalRecords: 80
-};
+const size_1 = require("./state-explosion/size");
+Object.defineProperty(exports, "computeStateSize", { enumerable: true, get: function () { return size_1.computeStateSize; } });
+Object.defineProperty(exports, "computeStateSizeWithGraph", { enumerable: true, get: function () { return size_1.computeStateSizeWithGraph; } });
+Object.defineProperty(exports, "DEFAULT_STATE_EXPLOSION_THRESHOLDS", { enumerable: true, get: function () { return size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS; } });
+Object.defineProperty(exports, "STATE_EXPLOSION_SCHEMA_VERSION", { enumerable: true, get: function () { return size_1.STATE_EXPLOSION_SCHEMA_VERSION; } });
 exports.GRAPH_VIEWS = [
     "full",
     "compact",
@@ -79,65 +74,17 @@ function graphKey(view, options) {
         view,
         options.focus || "",
         options.depth === undefined ? "" : String(options.depth),
-        thresholdsKey(options.thresholds || exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS)
+        thresholdsKey(options.thresholds || size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS)
     ].join("\0");
 }
 // ---------------------------------------------------------------------------
-// State size
+// State size (implementation in state-explosion/size.ts)
 // ---------------------------------------------------------------------------
-function computeStateSize(run, thresholds = exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS) {
-    return computeStateSizeWithGraph(run, thresholds, (0, multi_agent_operator_ux_1.buildMultiAgentOperatorGraph)(run));
-}
-function computeStateSizeWithGraph(run, thresholds, graph) {
-    const ma = run.multiAgent || { runs: [], roles: [], groups: [], memberships: [], fanouts: [], fanins: [] };
-    const bb = run.blackboard || { topics: [], messages: [], contexts: [], artifacts: [], snapshots: [], decisions: [] };
-    const counts = {
-        multiAgentRuns: (ma.runs || []).length,
-        roles: (ma.roles || []).length,
-        groups: (ma.groups || []).length,
-        memberships: (ma.memberships || []).length,
-        fanouts: (ma.fanouts || []).length,
-        fanins: (ma.fanins || []).length,
-        topics: (bb.topics || []).length,
-        messages: (bb.messages || []).length,
-        contexts: (bb.contexts || []).length,
-        artifacts: (bb.artifacts || []).length,
-        snapshots: (bb.snapshots || []).length,
-        decisions: (bb.decisions || []).length,
-        graphNodes: graph.nodes.length,
-        graphEdges: graph.edges.length
-    };
-    const total = counts.multiAgentRuns +
-        counts.roles +
-        counts.groups +
-        counts.memberships +
-        counts.fanouts +
-        counts.fanins +
-        counts.topics +
-        counts.messages +
-        counts.contexts +
-        counts.artifacts +
-        counts.snapshots +
-        counts.decisions;
-    const reasons = [];
-    if (counts.graphNodes > thresholds.graphNodes)
-        reasons.push(`graph has ${counts.graphNodes} nodes (> ${thresholds.graphNodes})`);
-    if (counts.graphEdges > thresholds.graphEdges)
-        reasons.push(`graph has ${counts.graphEdges} edges (> ${thresholds.graphEdges})`);
-    if (counts.messages > thresholds.blackboardMessages)
-        reasons.push(`blackboard has ${counts.messages} messages (> ${thresholds.blackboardMessages})`);
-    const bbRecords = counts.topics + counts.messages + counts.contexts + counts.artifacts + counts.snapshots + counts.decisions;
-    if (bbRecords > thresholds.blackboardRecords)
-        reasons.push(`blackboard has ${bbRecords} records (> ${thresholds.blackboardRecords})`);
-    if (total > thresholds.totalRecords)
-        reasons.push(`run has ${total} multi-agent records (> ${thresholds.totalRecords})`);
-    return { ...counts, total, compactionRecommended: reasons.length > 0, reasons: reasons.sort() };
-}
 function stateSizeFor(run, thresholds, context) {
     const key = thresholdsKey(thresholds);
     let size = context.stateSizes.get(key);
     if (!size) {
-        size = computeStateSizeWithGraph(run, thresholds, fullGraphFor(run, context));
+        size = (0, size_1.computeStateSizeWithGraph)(run, thresholds, fullGraphFor(run, context));
         context.stateSizes.set(key, size);
     }
     return size;
@@ -321,7 +268,7 @@ function summarizeBlackboardDigest(run, blackboardId) {
     ]);
     const fingerprint = (0, helpers_1.fingerprintRecords)([...topics, ...messages, ...contexts, ...artifacts, ...decisions]);
     return {
-        schemaVersion: exports.STATE_EXPLOSION_SCHEMA_VERSION,
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
         runId: run.id,
         id: `blackboard-digest${boardId ? `:${boardId}` : ""}`,
         scope: "blackboard",
@@ -368,7 +315,7 @@ function buildCompactGraph(run, view = "compact", options = {}) {
     return buildCompactGraphWithContext(run, view, options, createStateExplosionBuildContext());
 }
 function buildCompactGraphWithContext(run, view, options, context) {
-    const thresholds = options.thresholds || exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
+    const thresholds = options.thresholds || size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
     const key = graphKey(view, { ...options, thresholds });
     const cached = context.graphRecords.get(key);
     if (cached)
@@ -517,7 +464,7 @@ function finalizeGraphRecord(run, view, options, full, built) {
         ...built.syntheticNodes.filter((s) => s.blockedReason).map((s) => s.blockedReason)
     ]);
     return {
-        schemaVersion: exports.STATE_EXPLOSION_SCHEMA_VERSION,
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
         runId: run.id,
         id: `graph-${view}${options.focus ? `:focus:${(0, helpers_1.slug)(options.focus)}` : ""}`,
         scope: "run",
@@ -754,7 +701,7 @@ function buildOperatorDigestWithContext(run, thresholds, context) {
         ...compact.syntheticNodes.map((syn) => syn.expansionCommand)
     ]);
     return {
-        schemaVersion: exports.STATE_EXPLOSION_SCHEMA_VERSION,
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
         runId: run.id,
         id: "operator-digest",
         scope: "run",
@@ -817,7 +764,7 @@ function buildStateExplosionReport(run, options = {}) {
     return buildStateExplosionReportWithContext(run, options, createStateExplosionBuildContext());
 }
 function buildStateExplosionReportWithContext(run, options, context) {
-    const thresholds = options.thresholds || exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
+    const thresholds = options.thresholds || size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
     const stateSize = stateSizeFor(run, thresholds, context);
     const compactGraph = buildCompactGraphWithContext(run, "compact", { thresholds }, context);
     const criticalPathGraph = buildCompactGraphWithContext(run, "critical-path", { thresholds }, context);
@@ -847,7 +794,7 @@ function buildStateExplosionReportWithContext(run, options, context) {
         ? `node scripts/cw.js summary refresh ${run.id}`
         : operatorDigest.nextAction;
     return {
-        schemaVersion: exports.STATE_EXPLOSION_SCHEMA_VERSION,
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
         runId: run.id,
         generatedAt: new Date().toISOString(),
         stateSize,
@@ -887,7 +834,7 @@ function currentEntryFingerprint(run, entry, records) {
  *  BSD: mechanism (check + refresh); policy (when to call) is at the call site. */
 function maybeCompactRun(run) {
     try {
-        const size = computeStateSize(run);
+        const size = (0, size_1.computeStateSize)(run);
         if (size.compactionRecommended) {
             refreshStateExplosionSummaries(run);
         }
@@ -900,7 +847,7 @@ function summariesDir(run) {
     return node_path_1.default.join(run.paths.runDir, "summaries");
 }
 function refreshStateExplosionSummaries(run, options = {}) {
-    const thresholds = options.thresholds || exports.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
+    const thresholds = options.thresholds || size_1.DEFAULT_STATE_EXPLOSION_THRESHOLDS;
     const context = createStateExplosionBuildContext();
     const dir = summariesDir(run);
     node_fs_1.default.mkdirSync(dir, { recursive: true });
@@ -923,7 +870,7 @@ function refreshStateExplosionSummaries(run, options = {}) {
     const compactGraph = buildCompactGraphWithContext(run, "compact", { thresholds }, context);
     const reportPath = node_path_1.default.join(dir, "state-explosion-report.json");
     const index = {
-        schemaVersion: exports.STATE_EXPLOSION_SCHEMA_VERSION,
+        schemaVersion: size_1.STATE_EXPLOSION_SCHEMA_VERSION,
         runId: run.id,
         id: "multi-agent-summary-index",
         scope: "run",

package/dist/state.js

@@ -70,6 +70,7 @@ function ensureRunDirs(paths) {
 function loadRunFromCwd(runId, cwd = process.cwd()) {
     if (!runId)
         throw new Error("Missing run id");
+    assertSafeRunId(runId);
     const statePath = node_path_1.default.join(cwd, ".cw", "runs", runId, "state.json");
     const result = loadRunStateFile(statePath, { dryRun: true });
     if (result.report.status === "unsupported") {
@@ -98,8 +99,11 @@ function migrateRunStateFile(statePath, options = {}) {
 }
 function saveCheckpoint(run) {
     run.updatedAt = new Date().toISOString();
-    // state.json is the single source of truth — write it DURABLY (v0.1.40).
-    writeJson(run.paths.state, run, { durable: true });
+    // state.json is the single source of truth — write it DURABLY with a lock
+    // so concurrent processes never lose an update (v0.1.95).
+    withFileLock(run.paths.state, () => {
+        writeJson(run.paths.state, run, { durable: true });
+    });
 }
 /** Compact a run checkpoint by stripping empty optional arrays and null values
  *  that don't carry semantic meaning (v0.1.60). The normalization layer
@@ -245,6 +249,12 @@ function isContainedPath(candidate, allowed) {
 // per-run reclamation chain) so a concurrent writer can never lose a record.
 // O_EXCL (`wx`) is portable (no native flock); a stale holder is stolen so a
 // crashed process can never wedge the store forever.
+//
+// v0.1.95: the lock mtime is refreshed immediately before fn() runs, and
+// verified AFTER fn() returns — if another process stole the lock mid-operation
+// (the stale check fired and it overwrote our lock), the holder refuses to
+// release and throws. This guards long-running RMW operations (e.g. GC over a
+// large run) against mid-operation theft.
 // ---------------------------------------------------------------------------
 const FILE_LOCK_STALE_MS = 30_000;
 function sleepSync(ms) {
@@ -254,11 +264,12 @@ function sleepSync(ms) {
 function withFileLock(targetPath, fn) {
     const lock = `${targetPath}.lock`;
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(lock), { recursive: true });
+    const pid = String(process.pid);
     let acquired = false;
     for (let attempt = 0; attempt < 240 && !acquired; attempt++) {
         try {
             const fd = node_fs_1.default.openSync(lock, "wx");
-            node_fs_1.default.writeFileSync(fd, `${process.pid}@${new Date().toISOString()}\n`, "utf8");
+            node_fs_1.default.writeFileSync(fd, `${pid}@${new Date().toISOString()}\n`, "utf8");
             node_fs_1.default.closeSync(fd);
             acquired = true;
         }
@@ -272,19 +283,45 @@ function withFileLock(targetPath, fn) {
                 }
             }
             catch {
-                continue; // lock vanished between open and stat — retry immediately
+                continue;
             }
             sleepSync(25);
         }
     }
     if (!acquired)
         throw new Error(`could not acquire file lock for ${targetPath}`);
+    // Refresh mtime right before the critical section
     try {
-        return fn();
+        node_fs_1.default.utimesSync(lock, new Date(), new Date());
+    }
+    catch { /* best-effort */ }
+    try {
+        const result = fn();
+        // Verify lock was not stolen during fn(). The lock content may have changed
+        // if another process opened it with wx after stealing it. If our PID is not
+        // in the lock file, the lock was stolen — do NOT release the stolen lock
+        // (the thief owns it now, and releasing would corrupt its operation).
+        try {
+            const current = node_fs_1.default.readFileSync(lock, "utf8");
+            if (!current.startsWith(pid + "@")) {
+                throw new Error(`File lock for ${targetPath} was stolen during the critical section ` +
+                    `(lock now owned by another process). The operation may have lost ` +
+                    `cross-process isolation — increase FILE_LOCK_STALE_MS or split the work.`);
+            }
+        }
+        catch (checkError) {
+            if (checkError instanceof Error && checkError.message.includes("stolen"))
+                throw checkError;
+            /* lock vanished — another process already released it, nothing to clean up */
+        }
+        return result;
     }
     finally {
         try {
-            node_fs_1.default.rmSync(lock, { force: true });
+            // Only release if we still own the lock
+            const current = node_fs_1.default.readFileSync(lock, "utf8");
+            if (current.startsWith(pid + "@"))
+                node_fs_1.default.rmSync(lock, { force: true });
         }
         catch {
             /* releasing a missing lock is fine */
@@ -299,7 +336,8 @@ function safeFileName(value) {
  *  runs directory via a separator or a `..`/`.` component (path traversal). A
  *  real run id is `${workflowId}-${stamp}-${suffix}` (createRunId), and a
  *  workflow id is alnum-bounded [a-z0-9.-] (validateWorkflowId) — all within
- *  [A-Za-z0-9._-]. Because the charset already forbids any separator, the whole
+ *  [A-Za-z0-9._:-]. Sub-workflow ids also include `:` from the task id prefix.
+ *  Because the charset already forbids any separator, the whole
  *  id is ONE path component, so the only values that could traverse are the
  *  components `.` and `..` themselves; an embedded `..` (e.g. a workflow id like
  *  `v1..2`) is a safe directory name and is allowed. A separator, an absolute
@@ -309,8 +347,8 @@ function assertSafeRunId(value, context = "run id") {
     if (typeof value !== "string" || value.length === 0) {
         throw new Error(`Invalid ${context}: expected a non-empty string`);
     }
-    if (!/^[A-Za-z0-9._-]+$/.test(value) || value === "." || value === "..") {
-        throw new Error(`Unsafe ${context}: ${JSON.stringify(value)} must be a single path segment ([A-Za-z0-9._-], not '.' or '..')`);
+    if (!/^[A-Za-z0-9._:-]+$/.test(value) || value === "." || value === "..") {
+        throw new Error(`Unsafe ${context}: ${JSON.stringify(value)} must be a single path segment ([A-Za-z0-9._:-], not '.' or '..')`);
     }
     return value;
 }

package/dist/trust-audit.js

@@ -11,6 +11,8 @@ exports.recordTrustAuditEvent = recordTrustAuditEvent;
 exports.recordSandboxPathDecision = recordSandboxPathDecision;
 exports.recordSandboxPolicyDecision = recordSandboxPolicyDecision;
 exports.recordHostAttestation = recordHostAttestation;
+exports.setAuditEventCache = setAuditEventCache;
+exports.clearAuditEventCache = clearAuditEventCache;
 exports.listTrustAuditEvents = listTrustAuditEvents;
 exports.searchAuditEvents = searchAuditEvents;
 exports.summarizeTrustAudit = summarizeTrustAudit;
@@ -300,9 +302,25 @@ function recordHostAttestation(run, input) {
         source: "host-attested"
     });
 }
+// Per-request event log cache (v0.1.95). When set, readEvents returns
+// memoized results keyed by event log path. Clears after each request.
+let _eventLogCache = null;
+function setAuditEventCache(cache) {
+    _eventLogCache = cache;
+}
+function clearAuditEventCache() {
+    _eventLogCache = null;
+}
 function listTrustAuditEvents(run) {
     const audit = ensureTrustAudit(run);
-    return readEventsRaw(audit.eventLogPath).events.sort(compareEvents);
+    if (_eventLogCache) {
+        const cached = _eventLogCache.get(audit.eventLogPath);
+        if (cached)
+            return cached;
+    }
+    const events = readEventsRaw(audit.eventLogPath).events.sort(compareEvents);
+    _eventLogCache?.set(audit.eventLogPath, events);
+    return events;
 }
 /** Search audit events by kind, worker, or candidate (v0.1.65).
  *  Filters are AND-ed; empty filters match all. */
@@ -515,7 +533,14 @@ function auditRoot(run) {
     return run.paths.auditDir || node_path_1.default.join(run.paths.runDir, "audit");
 }
 function readEvents(eventLogPath) {
-    return readEventsRaw(eventLogPath).events.sort(compareEvents);
+    if (_eventLogCache) {
+        const cached = _eventLogCache.get(eventLogPath);
+        if (cached)
+            return cached;
+    }
+    const events = readEventsRaw(eventLogPath).events.sort(compareEvents);
+    _eventLogCache?.set(eventLogPath, events);
+    return events;
 }
 function workerRows(events, run) {
     const workerIds = unique([...(run.workers || []).map((worker) => worker.id), ...events.map((event) => event.workerId || "")]).sort();

package/dist/util/fingerprint.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintStrings = fingerprintStrings;
+exports.fingerprintRecords = fingerprintRecords;
+// Deterministic content fingerprint — the single canonical implementation.
+// Replaces duplicated copies in observability.ts and run-registry.ts (v0.1.95).
+// Pure function of its arguments; never imports run state or high-level modules.
+const node_crypto_1 = __importDefault(require("node:crypto"));
+function fingerprintStrings(values) {
+    const hash = node_crypto_1.default.createHash("sha256");
+    hash.update(JSON.stringify([...values].sort()));
+    return `sha256:${hash.digest("hex").slice(0, 32)}`;
+}
+function fingerprintRecords(records) {
+    return fingerprintStrings(records.map((r) => `${r.id}:${r.status || ""}`).sort());
+}

package/dist/util/fingerprint.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Unit test for the canonical fingerprint utility (v0.1.95).
+// Pure function — no run state or tmpdir needed.
+const strict_1 = require("node:assert/strict");
+const node_test_1 = require("node:test");
+const fingerprint_1 = require("../util/fingerprint");
+(0, node_test_1.test)("fingerprintStrings returns a sha256: prefix", () => {
+    const fp = (0, fingerprint_1.fingerprintStrings)(["a", "b"]);
+    (0, strict_1.ok)(fp.startsWith("sha256:"), "must have sha256: prefix");
+    (0, strict_1.equal)(fp.length, 32 + "sha256:".length, "must be 32 hex chars");
+});
+(0, node_test_1.test)("fingerprintStrings is deterministic and order-independent", () => {
+    const a = (0, fingerprint_1.fingerprintStrings)(["b", "a", "c"]);
+    const b = (0, fingerprint_1.fingerprintStrings)(["c", "b", "a"]);
+    (0, strict_1.equal)(a, b, "same values in different order must produce same fingerprint");
+});
+(0, node_test_1.test)("fingerprintStrings produces distinct values for different inputs", () => {
+    const a = (0, fingerprint_1.fingerprintStrings)(["x"]);
+    const b = (0, fingerprint_1.fingerprintStrings)(["y"]);
+    (0, strict_1.ok)(a !== b, "different inputs must produce different fingerprints");
+});
+(0, node_test_1.test)("fingerprintRecords uses id:status sorted", () => {
+    const a = (0, fingerprint_1.fingerprintRecords)([{ id: "b", status: "ok" }, { id: "a", status: "fail" }]);
+    const b = (0, fingerprint_1.fingerprintRecords)([{ id: "a", status: "fail" }, { id: "b", status: "ok" }]);
+    (0, strict_1.equal)(a, b, "records in different order must produce same fingerprint");
+});

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.95";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.96";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

@@ -85,7 +85,18 @@ class WorkbenchHost {
             if ((req.method || "GET").toUpperCase() !== "GET") {
                 return this.send(res, 405, { error: "read-only: only GET is permitted" }, { Allow: "GET" });
             }
+            // Optional token auth (CW_WORKBENCH_TOKEN). When set, every request must
+            // carry the token as an Authorization: Bearer header or ?token= query param.
+            // Off by default — single-user loopback is already gated by the OS boundary.
             const url = new URL(req.url || "/", `http://${this.host}`);
+            const requiredToken = (process.env.CW_WORKBENCH_TOKEN || "").trim();
+            if (requiredToken) {
+                const bearer = (req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim();
+                const queryToken = url.searchParams.get("token") || "";
+                if (bearer !== requiredToken && queryToken !== requiredToken) {
+                    return this.send(res, 401, { error: "unauthorized: token mismatch" });
+                }
+            }
             const route = decodeURIComponent(url.pathname);
             if (route === "/" || route === "/index.html")
                 return this.sendAsset(res, "index.html");

package/dist/workbench.js

@@ -110,23 +110,25 @@ function buildPanels(runner, runId) {
  *  never fabricated. */
 function buildWorkbenchRunView(runner, runId) {
     const id = String(runId || "");
-    let resolved = true;
-    let error;
-    try {
-        runner.loadRun(id);
-    }
-    catch (caught) {
-        resolved = false;
-        error = caught instanceof Error ? caught.message : String(caught);
-    }
-    return {
-        schemaVersion: 1,
-        surface: "workbench",
-        runId: id,
-        resolved,
-        ...(error ? { error } : {}),
-        panels: buildPanels(runner, id)
-    };
+    return runner.loadWithCache((r) => {
+        let resolved = true;
+        let error;
+        try {
+            r.loadRun(id);
+        }
+        catch (caught) {
+            resolved = false;
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        return {
+            schemaVersion: 1,
+            surface: "workbench",
+            runId: id,
+            resolved,
+            ...(error ? { error } : {}),
+            panels: buildPanels(r, id)
+        };
+    });
 }
 // ---------------------------------------------------------------------------
 // Cross-run entry (v0.1.28 Run Registry) — composed from already-declared

package/dist/worker-isolation.js

@@ -393,7 +393,31 @@ function recordWorkerRetryAttempt(run, workerId, attempts, reason, options = {})
 function validateWorkerBoundary(run, workerId, options = {}) {
     const scope = requireWorkerScope(run, workerId);
     const rawPath = String(options.path || scope.resultPath);
-    return (0, sandbox_profile_1.validateSandboxWrite)(sandboxPolicyForBoundary(run, scope, options), rawPath, workerId);
+    const policy = sandboxPolicyForBoundary(run, scope, options);
+    const violation = (0, sandbox_profile_1.validateSandboxWrite)(policy, rawPath, workerId);
+    if (!violation) {
+        // Write paths are enforced by CW at this boundary. Command and network limits
+        // are declared in the sandbox policy but enforced by the execution backend
+        // (the host/container runtime). Record the policy split transparently so the
+        // audit trail shows what CW checked vs what was delegated to the host.
+        (0, trust_audit_1.recordTrustAuditEvent)(run, {
+            kind: "worker.sandbox-boundary",
+            decision: "allowed",
+            source: "cw-validated",
+            workerId,
+            taskId: scope.taskId,
+            sandboxProfileId: policy.id,
+            policyRef: `execute=${policy.execute.mode} network=${policy.network.mode} env.inherit=${policy.env.inherit}`,
+            command: policy.execute.mode,
+            networkTarget: policy.network.mode,
+            metadata: {
+                enforced_by_cw: ["write-paths"],
+                delegated_to_host: ["execute", "network", "env"],
+                env_inherit: policy.env.inherit
+            }
+        });
+    }
+    return violation;
 }
 function summarizeWorkers(run) {
     const workers = listWorkerScopes(run);

package/docs/agent-delegation-drive.7.md

@@ -27,6 +27,52 @@ HTTP API. Any API key comes from the agent's *own* inherited env; CW never reads
 or keeps a record of it. Adding a provider SDK to `package.json` would lose the
 neutral-audit moat and is the red line.
 
+## Architecture — the boundary (core ↔ agent backend ↔ wrappers)
+
+The core gives only an INTERFACE: the `agent` execution backend plus a small
+text/process contract. The four vendors (claude / codex / gemini / deepseek)
+live OUTSIDE the core as out-of-process wrapper scripts in `scripts/agents/` —
+pure config, never imported by `src/`, behind the same seam.
+
+```text
+                       user
+                       │  cw -q "…" -codex   (headline shortcut; also -claude/-gemini/-deepseek)
+                       ▼
+┌──────────── CW core  (src/ — zero runtime deps, imports NO model SDK, holds NO key) ───────────┐
+│                                                                                                │
+│  command-surface.ts        agent-config.ts                 execution-backend  ("agent" driver) │
+│  -codex → builtin:codex ─► builtin:<name> ─►               runAgentProcess:                     │
+│                            node <dir>/<name>-agent.js       spawnSync(binary, args, shell:false)│
+│                            {{input}} {{result}}            · inherits env  · captures stdout    │
+│                            (builtin-templates.json: DATA)  · records handle{process}+attestation│
+└───────────────────────────────────────┬───────────────────────────────────────────────────────┘
+     THE SEAM  (text / process contract) │
+       in : argv  {{input}}=worker input.md   {{result}}=worker result.md
+       out: wrapper writes result.md + ONE stdout JSON line {model,usage,result} → parseAgentReport
+                                         │
+   ── red line ──  core never reads a key; each wrapper resolves its OWN key from inherited env
+                                         │
+┌──────── external wrappers  (scripts/agents/*.js — "CONFIG, not a CW runtime dependency") ───────┐
+│   claude-p-agent.js     codex-agent.js      gemini-opencode-agent.js    deepseek-agent.js       │
+│        │                     │                        └──────────┬──────────────┘              │
+│        ▼                     ▼                                   ▼  (3-line shims)              │
+│   claude -p            codex exec                          opencode-agent.js                    │
+│   (Anthropic CLI)      (-c effort, sandbox)               opencode run --model …                │
+│                                                           (deepseek + gemini keys live here)    │
+└─────────────────────────────────────────────────────────────────────────────────────────────────┘
+   Add a vendor = drop a wrapper script + one line in builtin-templates.json — NO core edit.
+```
+
+Each box maps to one source seam: the flag map lives in `command-surface.ts`
+(`-codex` → `builtin:codex`); `agent-config.ts` expands `builtin:<name>` into
+`node <dir>/<name>-agent.js {{input}} {{result}}` by reading
+`builtin-templates.json` (the registry is DATA, not a kernel literal); the
+`agent` driver's `runAgentProcess` does the `spawnSync` and reads back the one
+stdout JSON line via `parseAgentReport`. So the four vendors are **delegated
+agent wrappers, not an event-"hook" system**. The seam is generic: any
+`CW_AGENT_COMMAND="node my-agent.js {{input}} {{result}}"` or a configured HTTP
+endpoint plugs in the same way — the four builtins are just bundled examples.
+
 ## Operator-chosen model is policy; agent-reported model is the attestation
 
 Any model id CW passes **into** the agent invocation (`CW_AGENT_MODEL`
@@ -250,7 +296,22 @@ The built-in templates are:
 claude and codex run their own CLIs; gemini and deepseek route through opencode
 (where their keys live), each proven by a local, deterministic wrapper smoke
 (override the model with CW_GEMINI_MODEL / CW_DEEPSEEK_MODEL). GLM stays an
-external agent command or HTTP endpoint. CW still imports no model SDK.
+external agent command or HTTP endpoint. CW still imports no model SDK. The same
+headline shortcuts pick these builtins on the top-level CLI: `cw -q "..."
+-claude` / `-codex` / `-gemini` / `-deepseek`.
+
+The codex wrapper caps codex's reasoning effort for CW runs so a heavy
+`model_reasoning_effort = "high"` in the user's `~/.codex/config.toml` does not
+make every read/grep turn slow. It passes `codex exec -c
+model_reasoning_effort=<effort>` (default `low`) for THAT run only — the user's
+interactive codex is untouched. Raise it with `CW_CODEX_REASONING_EFFORT`
+(`low` | `medium` | `high`).
+
+When an agent hop fails, CW core keeps only the child's stdout + exit code, so a
+bare `failed (exit 1)` hid the real cause (a relay 5xx, an auth error, a killed
+run). Each wrapper now also drops the failed child's stderr to
+`<run>/workers/<worker>/logs/agent-stderr.log`, so the reason is readable after
+the fact without changing the recorded, byte-stable evidence.
 
 ## Compatibility
 
@@ -346,3 +407,5 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.1.94
 
 0.1.95
+
+0.1.96