cool-workflow 0.1.97 → 0.1.98

package/dist/execution-backend/agent.js

@@ -12,6 +12,7 @@ exports.recordedAgentHandle = recordedAgentHandle;
 exports.extractEndpointResult = extractEndpointResult;
 exports.agentHandle = agentHandle;
 exports.prepareAgentSpawn = prepareAgentSpawn;
+exports.reconcileBatchOutcomes = reconcileBatchOutcomes;
 exports.runAgentBatchOutcomes = runAgentBatchOutcomes;
 // Agent-delegation pure helpers + concurrent batch fulfillment for the
 // execution-backend driver layer. Carved out of execution-backend.ts
@@ -259,36 +260,95 @@ function prepareAgentSpawn(request) {
 // `node -e` string — F11). It reads jobs JSON on stdin, spawns ALL concurrently
 // (shell:false, inherited env — the agent's own credentials resolve; CW never
 // reads them), per-job SIGTERM at timeoutMs + SIGKILL at +5s, caps each captured
-// stdout at 32MB, and prints the outcome array when every job has settled. stderr
-// is drained (a full pipe must never wedge a child). A kill yields exitCode null —
-// the no-exit-code refusal. We spawn it BY PATH (shell:false); the path is
-// resolved from this compiled module (dist/execution-backend/agent.js) up to the
-// package's `scripts/children/` dir, which package.json ships in "files".
+// stdout at 32MB, and streams ONE NDJSON line per job the instant it settles.
+// stderr is drained (a full pipe must never wedge a child). A kill yields
+// exitCode null — the no-exit-code refusal. We spawn it BY PATH (shell:false);
+// the path is resolved from this compiled module (dist/execution-backend/agent.js)
+// up to the package's `scripts/children/` dir, which package.json ships in "files".
 const BATCH_DELEGATE_CHILD_SCRIPT = node_path_1.default.resolve(__dirname, "..", "..", "scripts", "children", "batch-delegate-child.js");
+/** Parse the delegate child's NDJSON stdout and reconcile it against `jobs` by
+ *  index. Runs even when `child.error` is set (ENOBUFS from the combined
+ *  output exceeding maxBuffer, ETIMEDOUT from the parent backstop, or a
+ *  nonzero/null exit) — a batch-level failure must fail-close ONLY the jobs
+ *  whose line never fully arrived, never every job in the batch: a job whose
+ *  line already streamed through keeps its REAL outcome.
+ *
+ *  `stdout` is split on the raw newline BYTE, on a Buffer, before any UTF-8
+ *  decoding — never on a decoded string. 0x0A never appears inside a UTF-8
+ *  continuation byte, so this is a safe boundary; decoding is deferred to
+ *  ONE LINE at a time (bounded by the delegate's own 32MB-per-job cap), so
+ *  no single decode ever approaches V8's hard per-string character ceiling
+ *  regardless of how large the COMBINED batch output is. Decoding the whole
+ *  combined buffer as one string up front (the prior approach) could itself
+ *  throw past that ceiling for a large-enough batch — an uncaught crash, not
+ *  a graceful `child.error` — which this line-at-a-time approach avoids by
+ *  construction. The trailing split segment is always dropped before
+ *  parsing (empty from a clean trailing newline, or a line truncated
+ *  mid-write by a hard kill — either way, never a complete line), and one
+ *  corrupt line can never crash the reconciliation of its siblings. */
+function reconcileBatchOutcomes(jobs, child) {
+    const buf = Buffer.isBuffer(child.stdout) ? child.stdout : Buffer.from(String(child.stdout || ""), "utf8");
+    const byIndex = new Map();
+    let lineStart = 0;
+    for (let i = 0; i < buf.length; i++) {
+        if (buf[i] !== 0x0a)
+            continue;
+        const lineBuf = buf.subarray(lineStart, i);
+        lineStart = i + 1;
+        if (lineBuf.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(lineBuf.toString("utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed.i !== "number" || parsed.i < 0 || parsed.i >= jobs.length)
+            continue;
+        byIndex.set(parsed.i, {
+            ...(parsed.spawnError ? { spawnError: parsed.spawnError } : {}),
+            exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : null,
+            stdout: String(parsed.stdout || "")
+        });
+    }
+    const reason = child.error
+        ? (0, util_1.messageOf)(child.error)
+        : typeof child.status === "number" && child.status !== 0
+            ? `batch delegate exited with ${child.status}`
+            : "batch delegate produced no outcome for this job";
+    return jobs.map((_, index) => byIndex.get(index) || { spawnError: `batch delegate failed: ${reason}`, exitCode: null, stdout: "" });
+}
 /** Run a batch of agent spawns concurrently; outcomes index-align with jobs. The
  *  parent backstop timeout (max job timeout + 30s) means even a wedged delegate
- *  child cannot deadlock the drive: on any batch-level failure EVERY job settles
- *  as a fail-closed spawn refusal — never a fabricated completion, never a hang. */
+ *  child cannot deadlock the drive. `maxBuffer` scales with batch size (the
+ *  delegate's own per-job 32MB cap is the real safety bound — no separate outer
+ *  ceiling here, since a flat ceiling that stops scaling with job count is
+ *  exactly what let one verbose batch strand its siblings before this fix).
+ *  Collect-all is a real guarantee even under buffer/timeout pressure: a job
+ *  whose NDJSON line fully streamed through keeps its real outcome regardless
+ *  of what happens to the rest of the batch. */
 function runAgentBatchOutcomes(jobs) {
     if (!jobs.length)
         return [];
     const maxTimeout = Math.max(...jobs.map((job) => job.timeoutMs));
-    const child = (0, node_child_process_1.spawnSync)(process.execPath, [BATCH_DELEGATE_CHILD_SCRIPT], {
-        input: JSON.stringify(jobs),
-        encoding: "utf8",
-        maxBuffer: Math.min(33 * 1024 * 1024 * jobs.length, 512 * 1024 * 1024),
-        timeout: maxTimeout + 30000
-    });
-    if (!child.error && typeof child.status === "number" && child.status === 0) {
-        try {
-            const parsed = JSON.parse(String(child.stdout || ""));
-            if (Array.isArray(parsed) && parsed.length === jobs.length)
-                return parsed;
-        }
-        catch {
-            // fall through to the fail-closed mapping below
-        }
+    // No `encoding` option: keep stdout as a raw Buffer so reconcileBatchOutcomes
+    // can split on the newline byte and decode one line at a time — decoding the
+    // WHOLE combined buffer as one string up front could itself throw past V8's
+    // per-string character ceiling for a large-enough batch (an uncaught crash,
+    // not a graceful child.error). The try/catch below is a second backstop for
+    // any other unexpected native failure at this boundary — a wedged or
+    // over-limit delegate must fail every job closed, never crash the drive.
+    let child;
+    try {
+        child = (0, node_child_process_1.spawnSync)(process.execPath, [BATCH_DELEGATE_CHILD_SCRIPT], {
+            input: JSON.stringify(jobs),
+            maxBuffer: 34 * 1024 * 1024 * jobs.length,
+            timeout: maxTimeout + 30000
+        });
+    }
+    catch (error) {
+        child = { error: error instanceof Error ? error : new Error(String(error)), status: null, stdout: null };
     }
-    const reason = child.error ? (0, util_1.messageOf)(child.error) : `batch delegate exited ${child.status === null ? "without an exit code (timed out or killed)" : `with ${child.status}`}`;
-    return jobs.map(() => ({ spawnError: `batch delegate failed: ${reason}`, exitCode: null, stdout: "" }));
+    return reconcileBatchOutcomes(jobs, child);
 }

package/dist/ledger.js

@@ -0,0 +1,313 @@
+"use strict";
+// Cross-agent handoff ledger — the core mechanism for two agents scoped to two
+// separate repos to hand each other a CHANGE PROPOSAL or a REVIEW VERDICT as
+// verifiable data, not chat. Design: docs/designs/handoff-ledger.md.
+//
+// Stage 1 (human-relay transport): a ledger entry is a self-contained JSON
+// object carrying its own sha256 content digest. The producing side prints one;
+// the operator carries it to the other session; the consuming side VERIFIES it
+// fail-closed (a tampered or malformed entry is refused, never acted on) before
+// turning a proposal into a real PR or recording a verdict.
+//
+// Zero-dependency (only node stdlib). `build*`/`verify*` are pure; the stage-2
+// git transport adds `listLedgerEntries`, a READ-ONLY scan of a shared ledger
+// directory (the working tree of a handoff repo) that verifies every entry
+// fail-closed. No run state, no writes, no network.
+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.computeLedgerDigest = computeLedgerDigest;
+exports.buildLedgerProposal = buildLedgerProposal;
+exports.buildLedgerReview = buildLedgerReview;
+exports.verifyLedgerEntry = verifyLedgerEntry;
+exports.applyLedgerProposal = applyLedgerProposal;
+exports.listLedgerEntries = listLedgerEntries;
+exports.unionLedgerEntries = unionLedgerEntries;
+exports.resolveLedgerInbox = resolveLedgerInbox;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Deterministic JSON with recursively sorted object keys, so the digest is a
+ *  function of content only — never key insertion order. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    const body = keys
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+        .join(",");
+    return `{${body}}`;
+}
+/** sha256 over the canonical content (every field except `id` and `digest`,
+ *  which are derived FROM it). Returns the full `sha256:<hex>` form. */
+function computeLedgerDigest(entry) {
+    const hash = crypto.createHash("sha256");
+    hash.update(stableStringify(entry));
+    return `sha256:${hash.digest("hex")}`;
+}
+/** Content-addressed id: `ldg-` + the first 16 hex chars of the digest. Two
+ *  entries with the same content (and createdAt) get the same id. */
+function deriveId(digest) {
+    return `ldg-${digest.replace(/^sha256:/, "").slice(0, 16)}`;
+}
+function seal(content) {
+    const digest = computeLedgerDigest(content);
+    return { ...content, id: deriveId(digest), digest };
+}
+function buildLedgerProposal(input) {
+    const content = {
+        kind: "proposal",
+        schemaVersion: 1,
+        from: input.from,
+        to: input.to,
+        title: input.title,
+        rationale: input.rationale,
+        targetFiles: [...input.targetFiles],
+        suggestedDiff: input.suggestedDiff || "",
+        createdAt: input.createdAt
+    };
+    return seal(content);
+}
+function buildLedgerReview(input) {
+    const content = {
+        kind: "review",
+        schemaVersion: 1,
+        from: input.from,
+        to: input.to,
+        target: input.target,
+        verdict: input.verdict,
+        findings: [...input.findings],
+        createdAt: input.createdAt
+    };
+    return seal(content);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const PROPOSAL_FIELDS = ["from", "to", "title", "rationale", "targetFiles", "suggestedDiff", "createdAt"];
+const REVIEW_FIELDS = ["from", "to", "target", "verdict", "findings", "createdAt"];
+/** Fail-closed verification. Any structural defect, unknown kind, or digest
+ *  mismatch yields `ok:false` — the caller refuses to act on it. */
+function verifyLedgerEntry(raw) {
+    const checks = [];
+    const fail = (name, code, detail) => {
+        checks.push({ name, pass: false, code, detail });
+        return {
+            ok: false,
+            id: isRecord(raw) && typeof raw.id === "string" ? raw.id : null,
+            kind: isRecord(raw) && typeof raw.kind === "string" ? raw.kind : null,
+            checks,
+            failedChecks: checks.filter((c) => !c.pass).map((c) => ({ name: c.name, code: c.code, detail: c.detail }))
+        };
+    };
+    if (!isRecord(raw))
+        return fail("structure", "ledger-not-object", "entry is not a JSON object");
+    checks.push({ name: "structure", pass: true });
+    const kind = raw.kind;
+    if (kind !== "proposal" && kind !== "review")
+        return fail("kind", "ledger-unknown-kind", `kind must be proposal|review, got ${JSON.stringify(kind)}`);
+    checks.push({ name: "kind", pass: true });
+    if (raw.schemaVersion !== 1)
+        return fail("schema", "ledger-bad-schema", `schemaVersion must be 1, got ${JSON.stringify(raw.schemaVersion)}`);
+    checks.push({ name: "schema", pass: true });
+    if (typeof raw.digest !== "string" || !raw.digest)
+        return fail("digest-present", "ledger-missing-digest", "digest is absent or not a string");
+    checks.push({ name: "digest-present", pass: true });
+    const fields = kind === "proposal" ? PROPOSAL_FIELDS : REVIEW_FIELDS;
+    const content = { kind, schemaVersion: 1 };
+    for (const field of fields) {
+        if (!(field in raw))
+            return fail("fields", "ledger-missing-field", `required field ${field} is absent`);
+        content[field] = raw[field];
+    }
+    if (kind === "review" && raw.verdict !== "APPROVED" && raw.verdict !== "REJECTED") {
+        return fail("verdict", "ledger-bad-verdict", `verdict must be APPROVED|REJECTED, got ${JSON.stringify(raw.verdict)}`);
+    }
+    checks.push({ name: "fields", pass: true });
+    const recomputed = computeLedgerDigest(content);
+    if (recomputed !== raw.digest) {
+        return fail("digest", "ledger-digest-mismatch", `stored digest does not match content (recomputed ${recomputed})`);
+    }
+    checks.push({ name: "digest", pass: true });
+    // Bind the id to the content: it MUST be the content-addressed id derived from
+    // the digest. Without this, `id` is a free, unverified field (it is excluded
+    // from the digest) — a forged entry could set `id` to collide with a legit
+    // one, and any id-keyed de-duplication (`cw ledger list` union) would silently
+    // drop one of them. Fail closed so a spoofed or absent id is refused, not
+    // trusted.
+    const expectedId = deriveId(raw.digest);
+    if (raw.id !== expectedId) {
+        return fail("id", "ledger-id-mismatch", `id ${JSON.stringify(raw.id)} is not the content-addressed id for this digest (expected ${expectedId})`);
+    }
+    checks.push({ name: "id", pass: true });
+    return { ok: true, id: expectedId, kind, checks, failedChecks: [] };
+}
+/** Fail-closed extraction of a proposal's `suggestedDiff` for `git apply`. The
+ *  diff can ONLY escape after the entry verifies: a tampered entry, a review
+ *  (not a proposal), or a proposal with no diff all yield `ok:false` and
+ *  `diff:null`, so `cw ledger apply <file> | git apply` can never feed an
+ *  unverified patch to git. The kernel never shells out to git — turning the
+ *  diff into a patch stays the operator's step (mechanism, not policy). */
+function applyLedgerProposal(raw) {
+    const verified = verifyLedgerEntry(raw);
+    if (!verified.ok) {
+        return { ok: false, id: verified.id, kind: verified.kind, diff: null, failedChecks: verified.failedChecks };
+    }
+    if (verified.kind !== "proposal") {
+        return { ok: false, id: verified.id, kind: verified.kind, diff: null, failedChecks: [{ name: "kind", code: "ledger-not-a-proposal", detail: "apply expects a proposal entry, not a review" }] };
+    }
+    const rec = isRecord(raw) ? raw : {};
+    const diff = typeof rec.suggestedDiff === "string" ? rec.suggestedDiff : "";
+    if (!diff) {
+        return { ok: false, id: verified.id, kind: verified.kind, diff: null, failedChecks: [{ name: "diff", code: "ledger-empty-diff", detail: "proposal carries no suggestedDiff to apply" }] };
+    }
+    return { ok: true, id: verified.id, kind: verified.kind, diff, failedChecks: [] };
+}
+/** Read every `*.json` in `dir`, verify each entry fail-closed, and report.
+ *  `allOk` is false if any entry is tampered, malformed, or unreadable — so the
+ *  receiving side refuses the whole inbox rather than acting on a mixed batch. */
+function listLedgerEntries(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith(".json")).sort();
+    }
+    catch (error) {
+        const entry = { file: dir, id: null, kind: null, from: null, to: null, title: null, target: null, verdict: null, ok: false, failedChecks: [{ name: "dir", code: "ledger-dir-unreadable", detail: error.message }] };
+        return { dir, count: 0, allOk: false, entries: [entry], resolution: resolveLedgerInbox([entry]) };
+    }
+    const entries = names.map((name) => {
+        const file = path.join(dir, name);
+        let raw;
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile()) {
+                return { file: name, id: null, kind: null, from: null, to: null, title: null, target: null, verdict: null, ok: false, failedChecks: [{ name: "file", code: "ledger-entry-not-regular" }] };
+            }
+            raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            return { file: name, id: null, kind: null, from: null, to: null, title: null, target: null, verdict: null, ok: false, failedChecks: [{ name: "parse", code: "ledger-bad-json" }] };
+        }
+        const result = verifyLedgerEntry(raw);
+        const rec = isRecord(raw) ? raw : {};
+        return {
+            file: name,
+            id: result.id,
+            kind: result.kind,
+            from: typeof rec.from === "string" ? rec.from : null,
+            to: typeof rec.to === "string" ? rec.to : null,
+            title: typeof rec.title === "string" ? rec.title : null,
+            target: typeof rec.target === "string" ? rec.target : null,
+            verdict: typeof rec.verdict === "string" ? rec.verdict : null,
+            ok: result.ok,
+            failedChecks: result.failedChecks
+        };
+    });
+    return { dir, count: entries.length, allOk: entries.every((e) => e.ok), entries, resolution: resolveLedgerInbox(entries) };
+}
+/** Union-verify several mirror directories into ONE fail-closed inbox. Verified
+ *  entries are de-duplicated by their content-addressed id (the same entry
+ *  mirrored to N hosts collapses to one, recording every mirror it came from);
+ *  failing entries are kept per-occurrence so every problem in every mirror is
+ *  visible. `allOk` is false if ANY entry in ANY mirror does not verify — a
+ *  tampered mirror fails the whole batch. Safe because entries are immutable and
+ *  content-addressed, so a union is a conflict-free set-union, not a merge. */
+function unionLedgerEntries(dirs) {
+    const byId = new Map();
+    const failures = [];
+    let allOk = true;
+    for (const dir of dirs) {
+        const listed = listLedgerEntries(dir);
+        if (!listed.allOk)
+            allOk = false;
+        for (const entry of listed.entries) {
+            if (entry.ok && entry.id) {
+                const existing = byId.get(entry.id);
+                if (existing) {
+                    if (!existing.dirs.includes(dir))
+                        existing.dirs.push(dir);
+                }
+                else {
+                    byId.set(entry.id, { ...entry, dirs: [dir] });
+                }
+            }
+            else {
+                failures.push({ ...entry, dirs: [dir] });
+            }
+        }
+    }
+    const entries = [...byId.values(), ...failures];
+    return { dirs, count: entries.length, allOk, entries, resolution: resolveLedgerInbox(entries) };
+}
+/** Derive a machine-actionable inbox summary: pair each proposal with the
+ *  review(s) that target it and report whether it is pending, approved,
+ *  rejected, or contested. Only VERIFIED entries take part — a tampered review
+ *  must never resolve a proposal, so a proposal with only a failing review
+ *  stays `pending` (fail-closed). Pure derivation over content-addressed
+ *  entries: no git, no network, no policy (it reports the decision, it does not
+ *  enforce one). */
+function resolveLedgerInbox(entries) {
+    const verified = entries.filter((e) => e.ok);
+    const reviews = verified.filter((e) => e.kind === "review" && e.target);
+    const proposals = verified
+        .filter((e) => e.kind === "proposal" && e.id)
+        .map((p) => {
+        const answering = reviews.filter((r) => r.target === p.id);
+        const verdicts = new Set(answering.map((r) => r.verdict));
+        let resolution;
+        if (answering.length === 0)
+            resolution = "pending";
+        else if (verdicts.size > 1)
+            resolution = "contested";
+        else
+            resolution = verdicts.has("APPROVED") ? "approved" : "rejected";
+        return {
+            id: p.id,
+            title: p.title,
+            resolution,
+            reviews: answering.map((r) => r.id).sort()
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const tally = (s) => proposals.filter((p) => p.resolution === s).length;
+    return {
+        proposals,
+        pending: tally("pending"),
+        approved: tally("approved"),
+        rejected: tally("rejected"),
+        contested: tally("contested")
+    };
+}

package/dist/mcp/tool-call.js

@@ -7,6 +7,7 @@ exports.callTool = callTool;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const orchestrator_1 = require("../orchestrator");
+const ledger_1 = require("../ledger");
 const scheduler_1 = require("../scheduler");
 const triggers_1 = require("../triggers");
 const workbench_1 = require("../workbench");
@@ -294,6 +295,41 @@ function callTool(name, args) {
             return runner.collaborationCommentList(String(args.runId || ""), args);
         case "cw_handoff":
             return runner.collaborationHandoff(String(args.runId || ""), String(args.targetKind || args.kind || ""), String(args.targetId || args.target || ""), args);
+        // ---- Cross-agent handoff ledger (stage 2 MCP surface) ----
+        case "cw_ledger_propose":
+            return (0, ledger_1.buildLedgerProposal)({
+                from: String(args.from || ""),
+                to: String(args.to || ""),
+                title: String(args.title || ""),
+                rationale: String(args.rationale || ""),
+                targetFiles: String(args.files || "").split(",").map((f) => f.trim()).filter(Boolean),
+                suggestedDiff: args.diff === undefined ? undefined : String(args.diff),
+                createdAt: new Date().toISOString()
+            });
+        case "cw_ledger_review": {
+            const verdict = String(args.verdict || "").toUpperCase();
+            if (verdict !== "APPROVED" && verdict !== "REJECTED")
+                throw new Error('verdict must be "approved" or "rejected".');
+            return (0, ledger_1.buildLedgerReview)({
+                from: String(args.from || ""),
+                to: String(args.to || ""),
+                target: String(args.target || ""),
+                verdict,
+                findings: String(args.findings || "").split(",").map((f) => f.trim()).filter(Boolean),
+                createdAt: new Date().toISOString()
+            });
+        }
+        case "cw_ledger_verify":
+            return (0, ledger_1.verifyLedgerEntry)(args.entry);
+        case "cw_ledger_apply":
+            return (0, ledger_1.applyLedgerProposal)(args.entry);
+        case "cw_ledger_list": {
+            // `dirs` (2+) union-verifies mirrors; a single `dir` keeps the original shape.
+            const dirs = Array.isArray(args.dirs) ? args.dirs.map(String).filter(Boolean) : [];
+            if (dirs.length > 1)
+                return (0, ledger_1.unionLedgerEntries)(dirs);
+            return (0, ledger_1.listLedgerEntries)(dirs[0] || String(args.dir || ""));
+        }
         case "cw_review_status":
             return runner.reviewStatus(String(args.runId || ""), args);
         case "cw_review_policy":

package/dist/mcp/tool-definitions.js

@@ -641,6 +641,31 @@ function toolDefinitions() {
             from: stringSchema("From-actor id (defaults to recorder)"),
             reason: stringSchema("Handoff reason")
         }),
+        capabilityTool("ledger.propose", "Build a verifiable cross-agent change proposal entry (digest-sealed JSON).", {
+            from: stringSchema("Proposing agent/repo"),
+            to: stringSchema("Target agent/repo"),
+            title: stringSchema("Short proposal title"),
+            rationale: stringSchema("Why this change"),
+            files: stringSchema("Comma-separated target files"),
+            diff: stringSchema("Suggested unified diff")
+        }),
+        capabilityTool("ledger.review", "Build a verifiable cross-agent review verdict entry (digest-sealed JSON).", {
+            from: stringSchema("Reviewing agent/repo"),
+            to: stringSchema("Target agent/repo"),
+            target: stringSchema("Proposal id or PR ref being judged"),
+            verdict: stringSchema("approved | rejected"),
+            findings: stringSchema("Comma-separated findings")
+        }),
+        capabilityTool("ledger.verify", "Verify a ledger entry against its content digest (fail-closed on tampering).", {
+            entry: objectSchema("The ledger entry object to verify")
+        }),
+        capabilityTool("ledger.apply", "Verify a proposal entry and return its suggestedDiff for `git apply` (fail-closed: no diff unless the entry verifies).", {
+            entry: objectSchema("The proposal entry object to verify and extract the diff from")
+        }),
+        capabilityTool("ledger.list", "Read + verify every entry in a shared ledger directory (fail-closed inbox).", {
+            dir: stringSchema("Path to the ledger directory (a handoff repo working tree)"),
+            dirs: arraySchema("Multiple ledger directories to union-verify as mirrors (2+)")
+        }),
         capabilityTool("review.status", "Read the derived per-target review state + collaboration timeline for a run.", {
             ...runIdSchema(),
             targetKind: stringSchema("Optional target kind filter"),
@@ -876,6 +901,7 @@ function toolDefinitions() {
             question: stringSchema("The question the audited report answers"),
             once: booleanSchema("Advance exactly one step then stop"),
             now: stringSchema("Injected ISO timestamp for deterministic scheduling"),
+            concurrency: numberSchema("Override the round width for parallel() phases (default: the workflow's own limits.maxConcurrentAgents)"),
             cwd: stringSchema("Run workspace")
         }),
         capabilityTool("queue.add", "Enqueue a pending/planned run with explicit ordering policy (lower priority drains first). Plain files; the host still executes workers.", {

package/dist/orchestrator/lifecycle-operations.js

@@ -29,6 +29,7 @@ const workflow_api_1 = require("../workflow-api");
 const observability_1 = require("../observability");
 const compare_1 = require("../compare");
 const loop_expansion_1 = require("../loop-expansion");
+const evidence_grounding_1 = require("../evidence-grounding");
 const dispatch_1 = require("../dispatch");
 const verifier_1 = require("../verifier");
 const trust_audit_1 = require("../trust-audit");
@@ -179,7 +180,14 @@ function plan(appRecord, options) {
     (0, state_1.saveCheckpoint)(run);
     return run;
 }
+/** `options.persistState === false` (concurrent-round callers ONLY — never from
+ *  a CLI/MCP arg bag) skips commitState/saveCheckpoint/writeReport on every
+ *  branch, success or error, so a caller driving many tasks through one
+ *  in-memory `run` can defer the disk flush to a single call at round end
+ *  instead of once per task. Default (absent) preserves today's exact
+ *  per-call persistence. */
 function dispatch(run, options) {
+    const persistState = options.persistState !== false;
     try {
         const manifest = (0, dispatch_1.createDispatchManifest)(run, (0, cli_options_1.numberOption)(options.limit), {
             sandboxProfileId: (0, cli_options_1.stringOption)(options.sandbox) || (0, cli_options_1.stringOption)(options.sandboxProfile) || (0, cli_options_1.stringOption)(options.sandboxProfileId),
@@ -190,10 +198,12 @@ function dispatch(run, options) {
             multiAgentFanoutId: (0, cli_options_1.stringOption)(options.multiAgentFanout || options.multiAgentFanoutId || options.fanout || options["multi-agent-fanout"])
         });
         run.loopStage = "act";
-        if (manifest.dispatchId)
-            (0, commit_1.commitState)(run, `dispatch:${manifest.dispatchId}`);
-        (0, state_1.saveCheckpoint)(run);
-        (0, report_1.writeReport)(run);
+        if (persistState) {
+            if (manifest.dispatchId)
+                (0, commit_1.commitState)(run, `dispatch:${manifest.dispatchId}`);
+            (0, state_1.saveCheckpoint)(run);
+            (0, report_1.writeReport)(run);
+        }
         return manifest;
     }
     catch (error) {
@@ -212,8 +222,10 @@ function dispatch(run, options) {
                 retryable: false,
                 metadata: { sandboxProfileId: (0, cli_options_1.stringOption)(options.sandbox) || (0, cli_options_1.stringOption)(options.sandboxProfile) || (0, cli_options_1.stringOption)(options.sandboxProfileId) }
             }, { persist: false });
-            (0, report_1.writeReport)(run);
-            (0, state_1.saveCheckpoint)(run);
+            if (persistState) {
+                (0, report_1.writeReport)(run);
+                (0, state_1.saveCheckpoint)(run);
+            }
         }
         throw error;
     }
@@ -239,6 +251,10 @@ function recordResult(run, taskId, resultPath, options = {}) {
         const parsedResult = (0, verifier_1.parseResultEnvelope)(rawResult);
         run.loopStage = "adjust";
         (0, verifier_1.validateResultEnvelope)(task, parsedResult);
+        const unresolved = (0, evidence_grounding_1.unresolvedFileEvidence)(parsedResult.evidence, [run.cwd, process.cwd(), run.paths.runDir, node_path_1.default.dirname(absoluteResultPath)]);
+        if (unresolved.length) {
+            throw new Error(`Result cites file evidence that does not resolve on disk: ${unresolved.join(", ")}`);
+        }
         const destination = node_path_1.default.join(run.paths.resultsDir, `${(0, state_1.safeFileName)(taskId)}.md`);
         node_fs_1.default.copyFileSync(absoluteResultPath, destination);
         task.status = "completed";
@@ -327,6 +343,7 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
     // Track 1 fail-closed (opt-in): forward the policy so recordWorkerOutput can
     // park a hop whose telemetry isn't attested. Default (absent) ⇒ flag-and-surface.
     const requireAttestedTelemetry = options.requireAttestedTelemetry === true;
+    const persistState = options.persistState !== false;
     try {
         (0, worker_isolation_1.recordWorkerOutput)(run, workerId, resultPath, { persist: false, agentDelegation, requireAttestedTelemetry });
         if (usage) {
@@ -341,20 +358,25 @@ function recordWorkerOutput(run, workerId, resultPath, options = {}) {
         // and either append the next round or mark the loop done (no-op for non-loop runs).
         maybeExpandLoop(run);
         (0, verifier_1.validateRunGates)(run);
-        (0, commit_1.commitState)(run, `worker:${workerId}:result`);
-        (0, report_1.writeReport)(run);
-        (0, state_1.saveCheckpoint)(run);
+        if (persistState) {
+            (0, commit_1.commitState)(run, `worker:${workerId}:result`);
+            (0, report_1.writeReport)(run);
+            (0, state_1.saveCheckpoint)(run);
+        }
         return (0, report_1.summarizeRun)(run);
     }
     catch (error) {
         run.loopStage = "adjust";
         (0, dispatch_1.updatePhaseStatuses)(run);
-        (0, report_1.writeReport)(run);
-        (0, state_1.saveCheckpoint)(run);
+        if (persistState) {
+            (0, report_1.writeReport)(run);
+            (0, state_1.saveCheckpoint)(run);
+        }
         throw error;
     }
 }
 function recordWorkerFailure(run, workerId, message, options = {}) {
+    const persistState = options.persistState !== false;
     const failure = (0, worker_isolation_1.recordWorkerFailure)(run, workerId, {
         code: String(options.code || "worker-runtime-error"),
         message,
@@ -364,8 +386,10 @@ function recordWorkerFailure(run, workerId, message, options = {}) {
     }, { persist: false, retryCount: typeof options.retryCount === "number" ? Number(options.retryCount) : undefined });
     run.loopStage = "adjust";
     (0, dispatch_1.updatePhaseStatuses)(run);
-    (0, report_1.writeReport)(run);
-    (0, state_1.saveCheckpoint)(run);
+    if (persistState) {
+        (0, report_1.writeReport)(run);
+        (0, state_1.saveCheckpoint)(run);
+    }
     return failure;
 }
 function checkState(runId, options = {}) {