cool-workflow 0.1.96 → 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.96",
+  "version": "0.1.98",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.96",
+  "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.96",
+  "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.96",
+  "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.96",
+  "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.96",
+  "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.96",
+  "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.96",
+  "version": "0.1.98",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/candidate-scoring.js

@@ -115,7 +115,7 @@ function getCandidate(run, candidateId) {
     // Fail-closed integrity boundary (F4/F5): validate the parsed record against
     // its type def BEFORE upserting it as a trusted CandidateRecord. A corrupt or
     // forged candidate.json must throw here rather than flow into the run.
-    const candidate = (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+    const candidate = (0, validation_1.validateCandidateRecord)((0, state_1.readJson)(file));
     upsertCandidate(run, candidate);
     return candidate;
 }
@@ -537,7 +537,7 @@ function loadCandidatesFromDisk(run) {
         // Fail-closed integrity boundary (F4/F5): each candidate.json is validated
         // against CandidateRecord before it merges into the run; a corrupt record
         // throws rather than entering the candidate set as a trusted cast.
-        .map((file) => (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8"))));
+        .map((file) => (0, validation_1.validateCandidateRecord)((0, state_1.readJson)(file)));
 }
 function readScores(run, candidateId) {
     const dir = node_path_1.default.join(candidateDir(run, candidateId), "scores");
@@ -550,7 +550,7 @@ function readScores(run, candidateId) {
         // Fail-closed integrity boundary (F4/F5): a score file is validated against
         // CandidateScore before it can feed ranking/selection. A corrupt score must
         // throw, not silently widen the normalized/verdict surface the gate reads.
-        .map((file) => (0, validation_1.validateCandidateScore)(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), "utf8"))));
+        .map((file) => (0, validation_1.validateCandidateScore)((0, state_1.readJson)(node_path_1.default.join(dir, file))));
 }
 function candidateArtifacts(run, candidate) {
     return [

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");
@@ -288,7 +289,12 @@ function runExportArchive(runner, runId, args) {
     // offline. Default falls back to the same env the verify gate reads, so a single
     // configured key both attests at record-time and travels with the export.
     const trustPublicKey = optionalString(args["with-trust-key"] || args.withTrustKey || args.trustKey || args.pubkey) || process.env.CW_AGENT_ATTEST_PUBKEY;
-    return (0, run_export_1.exportRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId), node_path_1.default.resolve(base, output), { trustPublicKey });
+    const resolvedOutput = node_path_1.default.resolve(base, output);
+    const sysDirs = /^\/(etc|bin|sbin|usr|Library|System|Applications|boot|dev|proc|sys|root|var\/log|var\/run)\//;
+    if (sysDirs.test(resolvedOutput)) {
+        throw new Error(`Refusing to write archive to a system directory: ${output}`);
+    }
+    return (0, run_export_1.exportRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId), resolvedOutput, { trustPublicKey });
 }
 function runImportArchive(runner, args) {
     const base = invocationCwd(args);
@@ -548,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",
@@ -587,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/cli/handlers/scheduling.js

@@ -77,7 +77,13 @@ function handleRoutine(args, triggers) {
             return;
         case "fire": {
             const kind = (0, io_1.required)(idOrKind, "trigger kind");
-            const payload = payloadPath ? JSON.parse(node_fs_1.default.readFileSync(payloadPath, "utf8")) : args.options;
+            let payload;
+            try {
+                payload = payloadPath ? JSON.parse(node_fs_1.default.readFileSync(payloadPath, "utf8")) : args.options;
+            }
+            catch (e) {
+                throw new Error(`Failed to parse payload${payloadPath ? ` file "${payloadPath}"` : ""}: ${String(e && e.message || e)}`);
+            }
             (0, io_1.printJson)(triggers.fire(kind, payload));
             return;
         }