cool-workflow 0.1.97 → 0.1.98

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "author": {
     "name": "COOLWHITE LLC"

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/capability-core.js

@@ -86,6 +86,7 @@ const telemetry_demo_1 = require("./telemetry-demo");
 const state_1 = require("./state");
 const run_export_1 = require("./run-export");
 const result_normalize_1 = require("./result-normalize");
+const cli_options_1 = require("./orchestrator/cli-options");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const scheduling_1 = require("./scheduling");
@@ -553,6 +554,7 @@ const DRIVE_RUNTIME_KEYS = [
     "agent-timeout-ms",
     "resume",
     "incremental",
+    "concurrency",
     // Remote-source flags (v0.1.91): materialized into a local checkout in the capability
     // layer, never passed to plan as inputs (the resolved sourceUrl/sourceCommit ARE inputs).
     "link",
@@ -592,6 +594,7 @@ function runDrive(runner, args) {
         once: isTrue(args.once),
         now: optionalString(args.now),
         incremental: isTrue(args.incremental),
+        concurrency: (0, cli_options_1.numberOption)(args.concurrency),
         args
     });
 }

package/dist/capability-registry.js

@@ -467,7 +467,13 @@ const BUILTIN_CAPABILITIES = [
     { capability: "comment.list", summary: "List append-only comments for a run (optionally one target).", entry: "collaborationCommentList", surface: "both", cli: { path: ["comment", "list"], caseTokens: ["comment"], jsonMode: "flag" }, mcp: { tool: "cw_comment_list", requiredArgs: ["runId"] } },
     { capability: "handoff", summary: "Record an ownership transfer (from-actor → to-actor) of a run/task.", entry: "collaborationHandoff", surface: "both", cli: { path: ["handoff"], jsonMode: "default" }, mcp: { tool: "cw_handoff", requiredArgs: ["runId", "targetKind|kind", "targetId|target", "to|toActor"] } },
     { capability: "review.status", summary: "Read the derived per-target review state + collaboration timeline for a run.", entry: "reviewStatus", surface: "both", cli: { path: ["review", "status"], caseTokens: ["review"], jsonMode: "flag" }, mcp: { tool: "cw_review_status", requiredArgs: ["runId"] } },
-    { capability: "review.policy", summary: "Set the run's review-gate policy (required approvals, authorized roles, self-approval rule).", entry: "reviewPolicy", surface: "both", cli: { path: ["review", "policy"], caseTokens: ["review"], jsonMode: "default" }, mcp: { tool: "cw_review_policy", requiredArgs: ["runId"] } }
+    { capability: "review.policy", summary: "Set the run's review-gate policy (required approvals, authorized roles, self-approval rule).", entry: "reviewPolicy", surface: "both", cli: { path: ["review", "policy"], caseTokens: ["review"], jsonMode: "default" }, mcp: { tool: "cw_review_policy", requiredArgs: ["runId"] } },
+    // ---- Cross-agent handoff ledger (stage 2, MCP surface + git transport) --
+    { capability: "ledger.propose", summary: "Build a verifiable cross-agent change proposal entry (printed as JSON).", entry: "buildLedgerProposal", surface: "both", cli: { path: ["ledger", "propose"], caseTokens: ["ledger", "propose"], jsonMode: "default" }, mcp: { tool: "cw_ledger_propose", requiredArgs: ["from", "to", "title", "rationale"] }, payloadIdentical: false, reason: "Mints a fresh entry each call: createdAt is the wall-clock instant and the id/digest are derived from it, so the output is inherently non-deterministic and a byte-identity probe does not apply. Both surfaces call the same buildLedgerProposal core; round-trip + fail-closed behavior is covered by ledger-verify-smoke." },
+    { capability: "ledger.review", summary: "Build a verifiable cross-agent review verdict entry (printed as JSON).", entry: "buildLedgerReview", surface: "both", cli: { path: ["ledger", "review"], caseTokens: ["ledger", "review"], jsonMode: "default" }, mcp: { tool: "cw_ledger_review", requiredArgs: ["from", "to", "target", "verdict"] }, payloadIdentical: false, reason: "Mints a fresh timestamped/digested verdict each call — non-deterministic output, same reasoning as ledger.propose. Both surfaces call the same buildLedgerReview core." },
+    { capability: "ledger.verify", summary: "Verify a ledger entry against its content digest (fail-closed on tampering).", entry: "verifyLedgerEntry", surface: "both", cli: { path: ["ledger", "verify"], caseTokens: ["ledger", "verify"], jsonMode: "default" }, mcp: { tool: "cw_ledger_verify", requiredArgs: ["entry"] }, payloadIdentical: false, reason: "The entry arrives by --file/stdin on the CLI and as an `entry` argument over MCP; there is no shared arg-bag the byte-identity probe can feed both. Both surfaces call the same verifyLedgerEntry core; ledger-verify-smoke proves the fail-closed contract." },
+    { capability: "ledger.apply", summary: "Verify a proposal entry and return its suggestedDiff for `git apply` (fail-closed: no diff unless the entry verifies as a proposal).", entry: "applyLedgerProposal", surface: "both", cli: { path: ["ledger", "apply"], caseTokens: ["ledger", "apply"], jsonMode: "default" }, mcp: { tool: "cw_ledger_apply", requiredArgs: ["entry"] }, payloadIdentical: false, reason: "The entry arrives by --file/stdin on the CLI and as an `entry` argument over MCP; there is no shared arg-bag the byte-identity probe can feed both. Both surfaces call the same applyLedgerProposal core (a fail-closed wrapper over verifyLedgerEntry); ledger-apply-smoke proves the diff only escapes a verified proposal." },
+    { capability: "ledger.list", summary: "Read + verify every entry in one or more shared ledger directories (fail-closed inbox; 2+ dirs union-verify mirrors).", entry: "listLedgerEntries", surface: "both", cli: { path: ["ledger", "list"], caseTokens: ["ledger", "list"], jsonMode: "default" }, mcp: { tool: "cw_ledger_list", requiredArgs: ["dir|dirs"] }, payloadIdentical: false, reason: "Output depends on the on-disk contents of the named ledger directory/directories, which the generic payload probe does not populate. Both surfaces call the same listLedgerEntries/unionLedgerEntries core; ledger-verify-smoke covers the fail-closed inbox and the multi-mirror union." }
 ];
 /** The capability registry — the single source of truth, deduplicated by
  *  capability id (last declaration wins). Derived directly from the table above:

package/dist/cli/command-surface.js

@@ -54,6 +54,7 @@ const registry_1 = require("./handlers/registry");
 const multi_agent_1 = require("./handlers/multi-agent");
 const run_1 = require("./handlers/run");
 const collaboration_1 = require("./handlers/collaboration");
+const ledger_1 = require("./handlers/ledger");
 const blackboard_1 = require("./handlers/blackboard");
 const eval_1 = require("./handlers/eval");
 const node_1 = require("./handlers/node");
@@ -427,6 +428,9 @@ async function runCli(argv = process.argv.slice(2)) {
         case "review":
             (0, collaboration_1.handleReview)(args, runner);
             return;
+        case "ledger":
+            (0, ledger_1.handleLedger)(args, runner);
+            return;
         case "loop": {
             (0, io_1.printJson)(scheduler.create({ ...args.options, kind: "loop" }));
             return;

package/dist/cli/handlers/ledger.js

@@ -0,0 +1,169 @@
+"use strict";
+// `cw ledger propose|review|verify` — the cross-agent handoff ledger CLI surface.
+// A proposing agent prints a proposal or a review verdict as a verifiable JSON
+// entry; the receiving side verifies it fail-closed before acting. See
+// docs/cross-agent-ledger.7.md and docs/designs/handoff-ledger.md.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleLedger = handleLedger;
+const fs = __importStar(require("fs"));
+const ledger_1 = require("../../ledger");
+const io_1 = require("../io");
+/** Coerce a repeatable/comma-joined list option to a clean string[]. */
+function listOption(value) {
+    const parts = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+    return parts.map((p) => String(p).trim()).filter(Boolean);
+}
+function stringOption(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function handleLedger(args, _runner) {
+    const [subcommand] = args.positionals;
+    const opts = args.options;
+    switch (subcommand) {
+        case "propose": {
+            const entry = (0, ledger_1.buildLedgerProposal)({
+                from: (0, io_1.required)(stringOption(opts.from), "--from <agent/repo>"),
+                to: (0, io_1.required)(stringOption(opts.to), "--to <agent/repo>"),
+                title: (0, io_1.required)(stringOption(opts.title), "--title <text>"),
+                rationale: (0, io_1.required)(stringOption(opts.rationale), "--rationale <text>"),
+                targetFiles: listOption(opts.files),
+                // Do NOT trim the diff: it is a unified patch (payload, not a label), and
+                // trimming strips the trailing newline `git apply` requires — a trimmed
+                // diff is a corrupt patch. Presence is detected with a trimmed test, but
+                // the bytes are passed through verbatim (matching the MCP propose path).
+                suggestedDiff: typeof opts.diff === "string" && opts.diff.trim() ? opts.diff : undefined,
+                createdAt: nowIso()
+            });
+            (0, io_1.printJson)(entry);
+            return;
+        }
+        case "review": {
+            const verdictRaw = (0, io_1.required)(stringOption(opts.verdict), "--verdict <approved|rejected>").toUpperCase();
+            if (verdictRaw !== "APPROVED" && verdictRaw !== "REJECTED") {
+                throw new Error('--verdict must be "approved" or "rejected".');
+            }
+            const entry = (0, ledger_1.buildLedgerReview)({
+                from: (0, io_1.required)(stringOption(opts.from), "--from <agent/repo>"),
+                to: (0, io_1.required)(stringOption(opts.to), "--to <agent/repo>"),
+                target: (0, io_1.required)(stringOption(opts.target), "--target <proposal-id|pr-ref>"),
+                verdict: verdictRaw,
+                findings: listOption(opts.findings),
+                createdAt: nowIso()
+            });
+            (0, io_1.printJson)(entry);
+            return;
+        }
+        case "verify": {
+            const file = stringOption(opts.file);
+            let text;
+            try {
+                // --file <path>, else read the entry from stdin (fd 0).
+                text = fs.readFileSync(file || 0, "utf8");
+            }
+            catch (error) {
+                throw new Error(`Cannot read ledger entry${file ? ` from ${file}` : " from stdin"}: ${error.message}`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // A non-JSON input is itself a fail-closed refusal, not a crash.
+                (0, io_1.printJson)({ ok: false, id: null, kind: null, checks: [{ name: "parse", pass: false, code: "ledger-bad-json" }], failedChecks: [{ name: "parse", code: "ledger-bad-json" }] });
+                process.exitCode = 1;
+                return;
+            }
+            const result = (0, ledger_1.verifyLedgerEntry)(parsed);
+            (0, io_1.printJson)(result);
+            // Fail-closed: a tampered/malformed entry exits non-zero so
+            // `cw ledger verify <file> && open-pr` cannot proceed on a lie.
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case "apply": {
+            const file = stringOption(opts.file);
+            let text;
+            try {
+                // --file <path>, else read the entry from stdin (fd 0), same as verify.
+                text = fs.readFileSync(file || 0, "utf8");
+            }
+            catch (error) {
+                throw new Error(`Cannot read ledger entry${file ? ` from ${file}` : " from stdin"}: ${error.message}`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                (0, io_1.printJson)({ ok: false, id: null, kind: null, diff: null, failedChecks: [{ name: "parse", code: "ledger-bad-json" }] });
+                process.exitCode = 1;
+                return;
+            }
+            const result = (0, ledger_1.applyLedgerProposal)(parsed);
+            (0, io_1.printJson)(result);
+            // Fail-closed: the diff only comes out (ok:true) when the proposal verifies,
+            // so `cw ledger apply <file> | git apply` never feeds git an unverified patch.
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case "list": {
+            // `--dir` is repeatable: 2+ dirs union-verify multiple mirrors into one
+            // inbox; a single --dir keeps the original single-directory output (POLA).
+            const dirs = Array.isArray(opts.dir) ? opts.dir.map(String).filter(Boolean) : [];
+            if (dirs.length > 1) {
+                const union = (0, ledger_1.unionLedgerEntries)(dirs);
+                (0, io_1.printJson)(union);
+                if (!union.allOk)
+                    process.exitCode = 1;
+                return;
+            }
+            const dir = (0, io_1.required)(dirs[0] || stringOption(opts.dir), "--dir <ledger-directory>");
+            const result = (0, ledger_1.listLedgerEntries)(dir);
+            (0, io_1.printJson)(result);
+            // Fail-closed inbox: refuse the whole batch if any entry does not verify.
+            if (!result.allOk)
+                process.exitCode = 1;
+            return;
+        }
+        default:
+            throw new Error("Usage: cw ledger propose|review|verify|apply|list [options]");
+    }
+}

package/dist/drive.js

@@ -43,6 +43,8 @@ const observability_1 = require("./observability");
 const loop_expansion_1 = require("./loop-expansion");
 const telemetry_attestation_1 = require("./telemetry-attestation");
 const state_1 = require("./state");
+const commit_1 = require("./commit");
+const report_1 = require("./orchestrator/report");
 const trust_audit_1 = require("./trust-audit");
 const compare_1 = require("./compare");
 exports.DRIVE_SCHEMA_VERSION = 1;
@@ -183,7 +185,7 @@ function buildAgentRequest(ctx, run, task, manifest, preparedOutcome) {
  *  fulfill step then settles it through runBackend instead of spawning again,
  *  so the concurrent round and the serial step share EVERY envelope/accept
  *  branch by construction. */
-function processSelectedTask(ctx, selected, preparedOutcome) {
+function processSelectedTask(ctx, selected, preparedOutcome, deferPersist = false) {
     const { runner, runId } = ctx;
     let run = runner.loadRun(runId);
     // 1. DISPATCH (only a fresh pending task; a running task is a retry on its scope).
@@ -191,7 +193,7 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
     let workerId = selected.workerId;
     let dispatched = false;
     if (selected.status === "pending") {
-        const manifest = runner.dispatch(runId, { limit: 1, backend: selected.agentType || "agent" });
+        const manifest = runner.dispatch(runId, { limit: 1, backend: selected.agentType || "agent", ...(deferPersist ? { persistState: false } : {}) });
         const task = manifest.tasks.find((entry) => entry.id === selected.id) || manifest.tasks[0];
         if (!task || !task.workerId) {
             return step("dispatch", "failed", { runId, taskId: selected.id, phase: selected.phase, reason: "dispatch produced no worker scope" });
@@ -216,10 +218,10 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
         emitProgress(`↺ ${selected.label || selected.id} (${selected.phase}) — accepting cached result`);
         try {
             node_fs_1.default.writeFileSync(manifest.resultPath, node_fs_1.default.readFileSync(cachePath, "utf8"), "utf8");
-            runner.recordWorkerOutput(runId, workerId, manifest.resultPath, {});
+            runner.recordWorkerOutput(runId, workerId, manifest.resultPath, deferPersist ? { persistState: false } : {});
         }
         catch (error) {
-            return handleHop(ctx, selected, workerId, `result cache rejected: ${error instanceof Error ? error.message : String(error)}`);
+            return handleHop(ctx, selected, workerId, `result cache rejected: ${error instanceof Error ? error.message : String(error)}`, deferPersist);
         }
         return step("accept", "ok", {
             runId,
@@ -233,7 +235,7 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
     // CHILD run and bind its report back as this task's result. Leaf work is still
     // external-agent delegation at every level; CW imports no model SDK here.
     if (selected.subWorkflow) {
-        return runSubWorkflow(ctx, run, selected, workerId, manifest);
+        return runSubWorkflow(ctx, run, selected, workerId, manifest, deferPersist);
     }
     emitProgress(`→ ${selected.label || selected.id} (${selected.phase}) — ${dispatched ? "dispatched, " : ""}spawning agent, may take minutes…`);
     const envelope = (0, execution_backend_1.runBackend)(buildAgentRequest(ctx, run, selected, manifest, preparedOutcome));
@@ -242,16 +244,17 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
     const reportedUsage = handle?.metadata?.reportedUsage;
     const usageSignature = handle?.metadata?.usageSignature;
     if (envelope.status !== "completed") {
-        return handleHop(ctx, selected, workerId, `agent hop ${envelope.status}: ${envelope.result.summary}`);
+        return handleHop(ctx, selected, workerId, `agent hop ${envelope.status}: ${envelope.result.summary}`, deferPersist);
     }
     // 3. ACCEPT — the SEPARATE recordWorkerOutput layer validates + records result.md.
     //    A missing result.md is a failed hop (pre-checked so no terminal side effect);
     //    an invalid result.md throws at validation BEFORE any state mutation.
     if (!manifest.resultPath || !node_fs_1.default.existsSync(manifest.resultPath)) {
-        return handleHop(ctx, selected, workerId, "agent produced no result.md");
+        return handleHop(ctx, selected, workerId, "agent produced no result.md", deferPersist);
     }
     try {
         runner.recordWorkerOutput(runId, workerId, manifest.resultPath, {
+            ...(deferPersist ? { persistState: false } : {}),
             agentDelegation: {
                 handle: handle,
                 model: reportedModel,
@@ -270,7 +273,7 @@ function processSelectedTask(ctx, selected, preparedOutcome) {
         });
     }
     catch (error) {
-        return handleHop(ctx, selected, workerId, `result.md rejected: ${error instanceof Error ? error.message : String(error)}`);
+        return handleHop(ctx, selected, workerId, `result.md rejected: ${error instanceof Error ? error.message : String(error)}`, deferPersist);
     }
     if (cachePath && manifest.resultPath && node_fs_1.default.existsSync(manifest.resultPath)) {
         writeResultCache(cachePath, node_fs_1.default.readFileSync(manifest.resultPath, "utf8"));
@@ -404,41 +407,61 @@ function writeResultCache(file, content) {
  *  collect-all: a failed/hung/dirty hop never aborts its siblings, every hop
  *  settles and is recorded (failures park via the same retryOrPark). */
 function driveConcurrentRound(ctx, limit) {
-    const run = ctx.runner.loadRun(ctx.runId);
-    const selected = selectDriveTask(run);
-    const gate = terminalOrConfigStep(ctx, run, selected);
-    if (gate)
-        return [gate];
-    const phase = (0, dispatch_1.firstRunnablePhase)(run);
-    const width = Math.max(1, Math.floor(limit) || 1);
-    const batch = run.tasks
-        .filter((task) => phase.taskIds.includes(task.id) && (task.status === "pending" || task.status === "running"))
-        .slice(0, width)
-        .map((task) => task.id);
-    // Phase A+B: dispatch every batch task (sequential — dispatch mutates state),
-    // then collect ALL spawn-style child outcomes in one concurrent window. The
-    // token-budget gate ran at round entry; it is NOT re-checked between accepts —
-    // the spawns already happened, and refusing to RECORD finished work would
-    // discard real results (collect-all + never-claw-back). Overshoot is bounded
-    // by the round width; the next round blocks.
-    const prepared = prepareConcurrentOutcomes(ctx, batch);
-    // Phase C: settle + accept in deterministic batch order, regardless of the
-    // wall-clock order the children finished in.
-    const steps = [];
-    for (const taskId of batch) {
-        const failStep = prepared.failSteps.get(taskId);
-        if (failStep) {
-            steps.push(failStep);
-            continue;
+    // The whole round runs inside ONE cached in-memory run object (loadWithCache —
+    // reentrant, so a sub-workflow task's recursive drive() call cannot clobber this
+    // scope's cache). Every dispatch/accept in the round defers its own state.json
+    // write (persistState:false / deferPersist) and mutates that SAME shared object;
+    // the round flushes to disk exactly ONCE at the end instead of once per task —
+    // was O(N) full-state durable rewrites per round (measured: dominates wall time
+    // at scale), now O(1). A crash mid-round loses that round's dispatch/accept
+    // bookkeeping (bounded by the round width, i.e. limits.maxConcurrentAgents) and
+    // forces a safe-but-wasteful re-dispatch/re-spawn on the next drive — never
+    // disk corruption or double-counting, since the atomic-rename+fsync write
+    // itself is untouched; only the write FREQUENCY changed.
+    return ctx.runner.loadWithCache(() => {
+        const run = ctx.runner.loadRun(ctx.runId);
+        const selected = selectDriveTask(run);
+        const gate = terminalOrConfigStep(ctx, run, selected);
+        if (gate)
+            return [gate];
+        const phase = (0, dispatch_1.firstRunnablePhase)(run);
+        const width = Math.max(1, Math.floor(limit) || 1);
+        const batch = run.tasks
+            .filter((task) => phase.taskIds.includes(task.id) && (task.status === "pending" || task.status === "running"))
+            .slice(0, width)
+            .map((task) => task.id);
+        // Phase A+B: dispatch every batch task (sequential — dispatch mutates state),
+        // then collect ALL spawn-style child outcomes in one concurrent window. The
+        // token-budget gate ran at round entry; it is NOT re-checked between accepts —
+        // the spawns already happened, and refusing to RECORD finished work would
+        // discard real results (collect-all + never-claw-back). Overshoot is bounded
+        // by the round width; the next round blocks.
+        const prepared = prepareConcurrentOutcomes(ctx, batch);
+        // Phase C: settle + accept in deterministic batch order, regardless of the
+        // wall-clock order the children finished in.
+        const steps = [];
+        for (const taskId of batch) {
+            const failStep = prepared.failSteps.get(taskId);
+            if (failStep) {
+                steps.push(failStep);
+                continue;
+            }
+            // Re-read per task: a prior accept in this round mutated state (the SAME
+            // cached object — no disk round-trip until the round-end flush below).
+            const freshRun = ctx.runner.loadRun(ctx.runId);
+            const fresh = freshRun.tasks.find((task) => task.id === taskId);
+            if (!fresh || (fresh.status !== "pending" && fresh.status !== "running"))
+                continue;
+            steps.push(processSelectedTask(ctx, fresh, prepared.outcomes.get(taskId), true));
         }
-        // Re-read per task: a prior accept in this round mutated state.
-        const freshRun = ctx.runner.loadRun(ctx.runId);
-        const fresh = freshRun.tasks.find((task) => task.id === taskId);
-        if (!fresh || (fresh.status !== "pending" && fresh.status !== "running"))
-            continue;
-        steps.push(processSelectedTask(ctx, fresh, prepared.outcomes.get(taskId)));
-    }
-    return steps.length > 0 ? steps : [driveStep(ctx)];
+        if (steps.length > 0) {
+            const settledRun = ctx.runner.loadRun(ctx.runId);
+            (0, commit_1.commitState)(settledRun, `concurrent-round:${batch.length}-tasks`);
+            (0, report_1.writeReport)(settledRun);
+            (0, state_1.saveCheckpoint)(settledRun);
+        }
+        return steps.length > 0 ? steps : [driveStep(ctx)];
+    });
 }
 /** Dispatch each batch task and run every spawn-style agent child concurrently
  *  (one batch delegate child, per-job timeout kill). Returns outcomes keyed by
@@ -457,7 +480,7 @@ function prepareConcurrentOutcomes(ctx, batch) {
             continue;
         let workerId = task.workerId;
         if (task.status === "pending") {
-            const manifest = runner.dispatch(runId, { limit: 1, backend: task.agentType || "agent" });
+            const manifest = runner.dispatch(runId, { limit: 1, backend: task.agentType || "agent", persistState: false });
             const dispatchedTask = manifest.tasks.find((entry) => entry.id === task.id) || manifest.tasks[0];
             if (!dispatchedTask || !dispatchedTask.workerId) {
                 failSteps.set(taskId, step("dispatch", "failed", { runId, taskId, phase: task.phase, reason: "dispatch produced no worker scope" }));
@@ -499,7 +522,7 @@ function prepareConcurrentOutcomes(ctx, batch) {
 }
 /** A failed agent hop: charge one attempt and (reuse v0.1.37 retryOrPark) either
  *  retry on the SAME worker scope next step, or PARK past the retry budget. */
-function handleHop(ctx, task, workerId, reason) {
+function handleHop(ctx, task, workerId, reason, deferPersist = false) {
     const persisted = ctx.runner.showWorker(ctx.runId, workerId).retryCount || 0;
     const prior = Math.max(ctx.attempts.get(task.id) || 0, persisted);
     const entry = {
@@ -520,7 +543,8 @@ function handleHop(ctx, task, workerId, reason) {
         ctx.runner.recordWorkerFailure(ctx.runId, workerId, decided.parkedReason || reason, {
             code: "agent-delegation-parked",
             retryable: false,
-            retryCount: attempts
+            retryCount: attempts,
+            ...(deferPersist ? { persistState: false } : {})
         });
         return step("park", "parked", {
             runId: ctx.runId,
@@ -532,7 +556,7 @@ function handleHop(ctx, task, workerId, reason) {
         });
     }
     // Retryable: leave the task running (scope reused) for the next step.
-    (0, worker_isolation_1.recordWorkerRetryAttempt)(ctx.runner.loadRun(ctx.runId), workerId, decided.attempts || prior + 1, reason);
+    (0, worker_isolation_1.recordWorkerRetryAttempt)(ctx.runner.loadRun(ctx.runId), workerId, decided.attempts || prior + 1, reason, deferPersist ? { persist: false } : {});
     return step("fulfill", "failed", {
         runId: ctx.runId,
         taskId: task.id,
@@ -565,17 +589,17 @@ function renderSubInputs(spec, parentInputs) {
  *  own telemetry/audit live in the child run; the parent records ONE honest
  *  `worker.sub-workflow` cross-link (child run id + report digest + child audit
  *  verdict) — nothing is summed or fabricated. */
-function runSubWorkflow(ctx, run, selected, workerId, manifest) {
+function runSubWorkflow(ctx, run, selected, workerId, manifest, deferPersist = false) {
     const spec = selected.subWorkflow;
     const parentApp = run.workflow.id;
     // Fail-closed BEFORE planning a child (no child state minted when refused).
     if (ctx.depth + 1 > exports.MAX_SUB_WORKFLOW_DEPTH) {
-        return handleHop(ctx, selected, workerId, `sub-workflow depth limit exceeded (> ${exports.MAX_SUB_WORKFLOW_DEPTH})`);
+        return handleHop(ctx, selected, workerId, `sub-workflow depth limit exceeded (> ${exports.MAX_SUB_WORKFLOW_DEPTH})`, deferPersist);
     }
     // Include the CURRENT app on the path, so a direct self-cycle (A→A) is caught at
     // depth 0 — before any child run dir is minted.
     if ([...ctx.visitedAppIds, parentApp].includes(spec.appId)) {
-        return handleHop(ctx, selected, workerId, `sub-workflow cycle detected: ${[...ctx.visitedAppIds, parentApp, spec.appId].join(" -> ")}`);
+        return handleHop(ctx, selected, workerId, `sub-workflow cycle detected: ${[...ctx.visitedAppIds, parentApp, spec.appId].join(" -> ")}`, deferPersist);
     }
     // Deterministic child run id derived from the parent run + task (no clock/random).
     const childRunId = `sub-${run.id}-${(0, state_1.safeFileName)(selected.id)}`;
@@ -592,7 +616,7 @@ function runSubWorkflow(ctx, run, selected, workerId, manifest) {
         childRun = ctx.runner.plan(spec.appId, childInputs);
     }
     catch (error) {
-        return handleHop(ctx, selected, workerId, `sub-workflow plan failed (${spec.appId}): ${errMessage(error)}`);
+        return handleHop(ctx, selected, workerId, `sub-workflow plan failed (${spec.appId}): ${errMessage(error)}`, deferPersist);
     }
     const childResult = drive(ctx.runner, childRun.id, {
         now: ctx.now,
@@ -603,7 +627,7 @@ function runSubWorkflow(ctx, run, selected, workerId, manifest) {
         visitedAppIds: [...ctx.visitedAppIds, parentApp]
     });
     if (childResult.status !== "complete") {
-        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} did not complete (status: ${childResult.status})`);
+        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} did not complete (status: ${childResult.status})`, deferPersist);
     }
     // Bind the child's bytes: the rendered report (default) or the verdict result.
     const finalChild = ctx.runner.loadRun(childRun.id);
@@ -616,15 +640,15 @@ function runSubWorkflow(ctx, run, selected, workerId, manifest) {
         childBytes = node_fs_1.default.existsSync(finalChild.paths.report) ? node_fs_1.default.readFileSync(finalChild.paths.report, "utf8") : undefined;
     }
     if (childBytes === undefined) {
-        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} produced no ${spec.bindResult || "report"}`);
+        return handleHop(ctx, selected, workerId, `sub-workflow ${spec.appId} produced no ${spec.bindResult || "report"}`, deferPersist);
     }
     // Accept through the SAME path as any other result (verifier/schema/evidence gate).
     try {
         node_fs_1.default.writeFileSync(manifest.resultPath, childBytes, "utf8");
-        ctx.runner.recordWorkerOutput(run.id, workerId, manifest.resultPath, {});
+        ctx.runner.recordWorkerOutput(run.id, workerId, manifest.resultPath, deferPersist ? { persistState: false } : {});
     }
     catch (error) {
-        return handleHop(ctx, selected, workerId, `sub-workflow result rejected by parent gate: ${errMessage(error)}`);
+        return handleHop(ctx, selected, workerId, `sub-workflow result rejected by parent gate: ${errMessage(error)}`, deferPersist);
     }
     // Honest cross-link (provenance only — never fails the accepted hop): one
     // worker.sub-workflow audit event on the parent pins the child run + report digest
@@ -730,6 +754,7 @@ function drive(runner, runId, options = {}) {
             return; // only the first not-yet-complete phase is "active"
         }
     };
+    let exhaustedMaxIterations = !options.once;
     for (let i = 0; i < maxIterations; i++) {
         const width = concurrency > 1 ? concurrency : autoWidth(runner.loadRun(runId));
         const roundSteps = width > 1 ? driveConcurrentRound(ctx, width) : [driveStep(ctx)];
@@ -751,27 +776,39 @@ function drive(runner, runId, options = {}) {
         // reuses the run we just advanced; goes to stderr via emitProgress so stdout is clean.
         emitPhaseProgress(runner.loadRun(runId));
         const last = roundSteps[roundSteps.length - 1];
-        if (options.once)
+        if (options.once) {
+            exhaustedMaxIterations = false;
             break;
-        if (last && (last.status === "complete" || last.status === "parked" || last.status === "blocked"))
+        }
+        if (last && (last.status === "complete" || last.status === "parked" || last.status === "blocked")) {
+            exhaustedMaxIterations = false;
             break;
+        }
     }
     const run = runner.loadRun(runId);
     const completedWorkers = countCompleted(run);
     const parkedWorkers = countParked(run);
     const committed = (run.commits || []).find((commit) => commit.reason && commit.reason.startsWith("agent-delegation-drive"));
     const last = steps[steps.length - 1];
+    if (exhaustedMaxIterations) {
+        steps.push(step("blocked", "blocked", {
+            runId,
+            reason: `drive reached max iteration limit (${maxIterations}) before a terminal state`
+        }));
+    }
     const status = options.once
         ? completedWorkers === plannedWorkers && committed
             ? "complete"
             : last && (last.status === "parked" || last.status === "blocked")
                 ? last.status
                 : "in-progress"
-        : parkedWorkers > 0 || (last && last.status === "parked")
-            ? "parked"
-            : last && last.status === "blocked"
-                ? "blocked"
-                : "complete";
+        : exhaustedMaxIterations
+            ? "blocked"
+            : parkedWorkers > 0 || (last && last.status === "parked")
+                ? "parked"
+                : last && last.status === "blocked"
+                    ? "blocked"
+                    : "complete";
     return {
         schemaVersion: 1,
         runId,