cool-workflow 0.1.81 → 0.1.83

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.81",
+  "version": "0.1.83",
   "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.81",
+  "version": "0.1.83",
   "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.81",
+  "version": "0.1.83",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/candidate-scoring.js

@@ -21,6 +21,8 @@ const state_node_1 = require("./state-node");
 const trust_audit_1 = require("./trust-audit");
 const collaboration_1 = require("./collaboration");
 const compare_1 = require("./compare");
+const gates_1 = require("./gates");
+const validation_1 = require("./validation");
 exports.CANDIDATE_SCHEMA_VERSION = 1;
 /** Verdict thresholds on a score's normalized value [0,1], declared once so the
  *  numbers carry intent instead of being buried as literals in verdictFor(). A
@@ -110,7 +112,10 @@ function getCandidate(run, candidateId) {
     const file = candidateFile(run, candidateId);
     if (!node_fs_1.default.existsSync(file))
         return undefined;
-    const candidate = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    // 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")));
     upsertCandidate(run, candidate);
     return candidate;
 }
@@ -245,10 +250,11 @@ function selectCandidate(run, candidateId, options = {}, scoringOptions = {}) {
         else if (!verifierNode.evidence.length) {
             failures.push(error("candidate-selection-missing-evidence", `Candidate ${candidateId} verifier node has no evidence`));
         }
-        else if (emptyCaptureWarning(run, verifierNode)) {
-            // HARD no-false-green gate (v0.1.43) — kept in SYNC with the commit gate
-            // (commit.ts emptyCaptureWarning): a verifier node whose backing result was
-            // an empty-capture must not be selectable, so selection + commit agree.
+        else if ((0, gates_1.emptyCaptureWarning)(run, verifierNode)) {
+            // HARD no-false-green gate (v0.1.43) — selection and the commit gate now
+            // share ONE emptyCaptureWarning (src/gates.ts), so they CANNOT drift: a
+            // verifier node whose backing result was an empty-capture is unselectable
+            // here for the same reason it is uncommittable, by construction.
             failures.push(error("candidate-selection-empty-capture", `Candidate ${candidateId} verifier node has no real evidence (empty-capture result)`));
         }
     }
@@ -312,7 +318,7 @@ function selectCandidate(run, candidateId, options = {}, scoringOptions = {}) {
             scoreCriteria: bestScore?.criteria,
             verifierNodeId: candidate.verifierNodeId,
             evidenceCount: mergeEvidence(candidate.evidence, verifierNode?.evidence || []).length,
-            sandboxProfileId: sandboxProfileForCandidate(run, candidate),
+            sandboxProfileId: (0, gates_1.sandboxProfileForCandidate)(run, candidate),
             workerId: candidate.workerId,
             commitGateResult: "passed"
         }),
@@ -528,7 +534,10 @@ function loadCandidatesFromDisk(run) {
         .filter((entry) => entry.isDirectory() && entry.name !== "selections")
         .map((entry) => node_path_1.default.join(candidateRoot(run), entry.name, "candidate.json"))
         .filter((file) => node_fs_1.default.existsSync(file))
-        .map((file) => JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+        // 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"))));
 }
 function readScores(run, candidateId) {
     const dir = node_path_1.default.join(candidateDir(run, candidateId), "scores");
@@ -538,7 +547,10 @@ function readScores(run, candidateId) {
         .readdirSync(dir)
         .filter((file) => file.endsWith(".json"))
         .sort()
-        .map((file) => JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), "utf8")));
+        // 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"))));
 }
 function candidateArtifacts(run, candidate) {
     return [
@@ -661,17 +673,6 @@ function error(code, message, options = {}) {
         details: options.details
     };
 }
-/** HARD no-false-green gate (v0.1.43) — kept in SYNC with commit.ts. Traces a
- *  verifier node back to its source result node and returns the empty-capture
- *  marker (set at ingest via isEmptyCapture) when present. Reads ONLY persisted
- *  state, so selection replays deterministically. */
-function emptyCaptureWarning(run, verifierNode) {
-    const resultNodeId = (typeof verifierNode.inputs?.inputNodeId === "string" ? verifierNode.inputs.inputNodeId : undefined) ||
-        verifierNode.parents[0];
-    const resultNode = resultNodeId ? run.nodes?.find((node) => node.id === resultNodeId) : undefined;
-    const warning = resultNode?.metadata?.captureWarning;
-    return typeof warning === "string" && warning ? warning : undefined;
-}
 function mergeCandidates(left, right) {
     const merged = [...left];
     for (const candidate of right) {
@@ -708,13 +709,6 @@ function mergeEvidence(left, right) {
     }
     return merged;
 }
-function sandboxProfileForCandidate(run, candidate) {
-    const worker = candidate.workerId ? (run.workers || []).find((entry) => entry.id === candidate.workerId) : undefined;
-    if (worker?.sandboxProfileId)
-        return worker.sandboxProfileId;
-    const task = candidate.taskId ? (run.tasks || []).find((entry) => entry.id === candidate.taskId) : undefined;
-    return task?.sandboxProfileId;
-}
 function unique(values) {
     return Array.from(new Set(values.filter(Boolean)));
 }

package/dist/capability-core.js

@@ -198,18 +198,16 @@ function flag(value) {
         return false;
     return Boolean(value);
 }
-function withInvocationCwd(args, fn) {
-    const cwd = optionalString(args.cwd);
-    if (!cwd)
-        return fn();
-    const previous = process.cwd();
-    process.chdir(cwd);
-    try {
-        return fn();
-    }
-    finally {
-        process.chdir(previous);
-    }
+// F7: explicit invocation cwd — no more process.chdir bracket.
+// The runner resolves a run from process.cwd() by default; to operate WITH a run's
+// repo as base (run --drive --repo X from anywhere; cross-directory quickstart; run
+// import/export against a target dir) we now pass that base EXPLICITLY —
+// runner.withBaseDir(dir).loadRun(...) for run resolution (see
+// CoolWorkflowRunner.withBaseDir), and invocationCwd(args) to anchor relative path
+// args. Nothing mutates the global process.cwd(), so concurrent in-process callers
+// can no longer corrupt each other's working directory (the former reentrancy hazard).
+function invocationCwd(args) {
+    return node_path_1.default.resolve(optionalString(args.cwd) || process.cwd());
 }
 function runRegistryRefresh(reg, args) {
     return reg.refresh({ scope: scopeOf(args, "repo") });
@@ -277,36 +275,33 @@ function runRerun(reg, runId, args) {
     return reg.rerun(runId, { scope: scopeOf(args, "home"), reason: optionalString(args.reason) });
 }
 function runExportArchive(runner, runId, args) {
-    return withInvocationCwd(args, () => {
-        const output = optionalString(args.output || args.path || args.archive) || `${runId}.cwrun.json`;
-        return (0, run_export_1.exportRun)(runner.loadRun(runId), node_path_1.default.resolve(output));
-    });
+    const base = invocationCwd(args);
+    const output = optionalString(args.output || args.path || args.archive) || `${runId}.cwrun.json`;
+    return (0, run_export_1.exportRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId), node_path_1.default.resolve(base, output));
 }
 function runImportArchive(runner, args) {
-    return withInvocationCwd(args, () => {
-        const archive = optionalString(args.archive || args.path || args.file);
-        if (!archive)
-            throw new Error("run import requires an archive path (positional, --archive, --path, or --file)");
-        const target = optionalString(args.target || args.repo || args.cwd) || process.cwd();
-        const imported = (0, run_export_1.importRun)(node_path_1.default.resolve(archive), node_path_1.default.resolve(target));
-        const registry = new run_registry_1.RunRegistry(node_path_1.default.resolve(target), runner);
-        const registryReport = registry.refresh({ scope: "repo" });
-        return { ...imported, registry: registryReport };
-    });
+    const base = invocationCwd(args);
+    const archive = optionalString(args.archive || args.path || args.file);
+    if (!archive)
+        throw new Error("run import requires an archive path (positional, --archive, --path, or --file)");
+    const target = node_path_1.default.resolve(base, optionalString(args.target || args.repo || args.cwd) || base);
+    const imported = (0, run_export_1.importRun)(node_path_1.default.resolve(base, archive), target);
+    const registry = new run_registry_1.RunRegistry(target, runner.withBaseDir(target));
+    const registryReport = registry.refresh({ scope: "repo" });
+    return { ...imported, registry: registryReport };
 }
 // Read-only: inspect a portable archive's integrity WITHOUT importing it. Routes
 // both surfaces through one shared core entry. The runner is unused (no registry
 // touch — inspection writes nothing) but kept for dispatch-signature symmetry.
 function runInspectArchive(_runner, args) {
-    return withInvocationCwd(args, () => {
-        const archive = optionalString(args.archive || args.path || args.file);
-        if (!archive)
-            throw new Error("run inspect-archive requires an archive path (positional, --archive, --path, or --file)");
-        return (0, run_export_1.inspectArchive)(node_path_1.default.resolve(archive));
-    });
+    const base = invocationCwd(args);
+    const archive = optionalString(args.archive || args.path || args.file);
+    if (!archive)
+        throw new Error("run inspect-archive requires an archive path (positional, --archive, --path, or --file)");
+    return (0, run_export_1.inspectArchive)(node_path_1.default.resolve(base, archive));
 }
 function runVerifyImport(runner, runId, args) {
-    return withInvocationCwd(args, () => (0, run_export_1.verifyImportedRun)(runner.loadRun(runId)));
+    return (0, run_export_1.verifyImportedRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId));
 }
 function queueAdd(reg, args) {
     return reg.queueAdd({
@@ -338,13 +333,12 @@ function queueShow(reg, id) {
 // ---- control-plane scheduling (v0.1.37) -----------------------------------
 function loadSchedulingPolicy(reg) {
     const file = reg.schedulingPolicyPath();
+    // Absent policy => conservative DEFAULT (an unconfigured backend, which §4
+    // permits). But a PRESENT-but-corrupt policy must fail closed: silently
+    // substituting defaults would schedule under settings the operator never
+    // chose while their broken file sits on disk. Let readJson's throw surface it.
     if (node_fs_1.default.existsSync(file)) {
-        try {
-            return { policy: (0, scheduling_1.normalizeSchedulingPolicy)((0, state_1.readJson)(file)), source: "file" };
-        }
-        catch {
-            /* fall through to default */
-        }
+        return { policy: (0, scheduling_1.normalizeSchedulingPolicy)((0, state_1.readJson)(file)), source: "file" };
     }
     return { policy: scheduling_1.DEFAULT_SCHEDULING_POLICY, source: "default" };
 }
@@ -405,8 +399,17 @@ function schedPolicySet(reg, args) {
     const current = loadSchedulingPolicy(reg).policy;
     const patch = {};
     for (const key of ["maxConcurrent", "maxAttempts", "leaseTtlMs", "backoffBaseMs", "backoffFactor", "backoffCapMs"]) {
-        if (args[key] !== undefined)
-            patch[key] = Number(args[key]);
+        if (args[key] === undefined)
+            continue;
+        // Fail closed on a non-numeric flag instead of letting normalizeSchedulingPolicy
+        // silently substitute the DEFAULT (which would report source:"file" + exit 0,
+        // so the operator believes they set a value they didn't). Matches the
+        // Number.isFinite guard the sibling reclaimPolicyFrom already uses.
+        const value = Number(args[key]);
+        if (!Number.isFinite(value)) {
+            throw new Error(`Invalid --${key} "${String(args[key])}": expected a number (e.g. --${key} 4)`);
+        }
+        patch[key] = value;
     }
     const policy = (0, scheduling_1.normalizeSchedulingPolicy)({ ...current, ...patch });
     (0, state_1.writeJson)(reg.schedulingPolicyPath(), policy);
@@ -458,26 +461,25 @@ function planInputsFor(args) {
  *  the golden path runs each verb from the repo dir) — then restores cwd. This lets
  *  `cw run <app> --drive --repo X` work when invoked from anywhere. */
 function runDrive(runner, args) {
-    const cwd0 = process.cwd();
-    try {
-        let runId = optionalString(args.runId || args.run);
-        let repoCwd = optionalString(args.repo);
-        if (!runId) {
-            const appId = String(args.appId || args.workflowId || args.app || "");
-            if (!appId)
-                throw new Error("run --drive requires an app id (or --run <run-id> to continue)");
-            const run = runner.plan(appId, planInputsFor(args));
-            runId = run.id;
-            repoCwd = run.cwd;
-        }
-        if (repoCwd && repoCwd !== process.cwd() && node_fs_1.default.existsSync(repoCwd))
-            process.chdir(repoCwd);
-        return (0, drive_1.drive)(runner, runId, { once: isTrue(args.once), now: optionalString(args.now), args });
-    }
-    finally {
-        if (process.cwd() !== cwd0)
-            process.chdir(cwd0);
+    let runId = optionalString(args.runId || args.run);
+    let repoCwd = optionalString(args.repo);
+    if (!runId) {
+        const appId = String(args.appId || args.workflowId || args.app || "");
+        if (!appId)
+            throw new Error("run --drive requires an app id (or --run <run-id> to continue)");
+        const run = runner.plan(appId, planInputsFor(args));
+        runId = run.id;
+        repoCwd = run.cwd;
     }
+    // The runner resolves the run from its baseDir, so the drive must run WITH the
+    // run's repo as base. Pass it explicitly via withBaseDir (F7 — no process.chdir).
+    const target = repoCwd && node_fs_1.default.existsSync(repoCwd) ? repoCwd : undefined;
+    const driveRunId = runId;
+    return (0, drive_1.drive)(runner.withBaseDir(target), driveRunId, {
+        once: isTrue(args.once),
+        now: optionalString(args.now),
+        args
+    });
 }
 /** The app the one-command quickstart plans when none is named. */
 exports.QUICKSTART_DEFAULT_APP = "architecture-review";
@@ -503,23 +505,16 @@ function quickstart(runner, args) {
     // `--preview`: read-only, deterministic next-step projection (no spawn, no commit).
     // Plan a fresh run (the read-only first verb) then project the next drive step.
     if (isTrue(args.preview)) {
-        const cwd0 = process.cwd();
-        try {
-            let runId = optionalString(args.runId || args.run);
-            let repoCwd = optionalString(args.repo);
-            if (!runId) {
-                const run = runner.plan(appId, planInputsFor(args));
-                runId = run.id;
-                repoCwd = run.cwd;
-            }
-            if (repoCwd && repoCwd !== process.cwd() && node_fs_1.default.existsSync(repoCwd))
-                process.chdir(repoCwd);
-            return (0, drive_1.drivePreview)(runner, runId, args);
-        }
-        finally {
-            if (process.cwd() !== cwd0)
-                process.chdir(cwd0);
+        let runId = optionalString(args.runId || args.run);
+        let repoCwd = optionalString(args.repo);
+        if (!runId) {
+            const run = runner.plan(appId, planInputsFor(args));
+            runId = run.id;
+            repoCwd = run.cwd;
         }
+        const previewRunId = runId;
+        const target = repoCwd && node_fs_1.default.existsSync(repoCwd) ? repoCwd : undefined;
+        return (0, drive_1.drivePreview)(runner.withBaseDir(target), previewRunId, args);
     }
     // Drive end-to-end (or one `--once` step). runDrive plans the run, delegates each
     // worker to the agent backend, and commits — we add only the report write + a
@@ -530,23 +525,15 @@ function quickstart(runner, args) {
     const result = runDrive(runner, { ...args, appId, ...(resume && !resumeRunId ? { once: true } : {}) });
     // Always (re)write the report so the one command yields a report.md on disk, even
     // when the drive blocked/parked (a partial report is still useful triage).
-    const cwd0 = process.cwd();
-    let reportPath = result.reportPath;
-    try {
-        // runDrive restored cwd, so the runs root would resolve against the CALLER's
-        // cwd here — orphaning the run when quickstart is invoked cross-directory
-        // (cwd = plugin dir, --repo elsewhere: the README's headline command). The
-        // run's statePath (<repo>/.cw/runs/<id>/state.json) is authoritative however
-        // the run was planned or continued; chdir to ITS repo BEFORE any run read.
-        const runRepoCwd = node_path_1.default.resolve(node_path_1.default.dirname(result.statePath), "..", "..", "..");
-        if (runRepoCwd !== process.cwd() && node_fs_1.default.existsSync(runRepoCwd))
-            process.chdir(runRepoCwd);
-        reportPath = runner.report(result.runId).path;
-    }
-    finally {
-        if (process.cwd() !== cwd0)
-            process.chdir(cwd0);
-    }
+    //
+    // runDrive restored cwd, so the runs root would resolve against the CALLER's cwd
+    // here — orphaning the run when quickstart is invoked cross-directory (cwd =
+    // plugin dir, --repo elsewhere: the README's headline command). The run's
+    // statePath (<repo>/.cw/runs/<id>/state.json) is authoritative however the run
+    // was planned or continued; resolve to ITS repo BEFORE any run read, reentrant-safe.
+    const runRepoCwd = node_path_1.default.resolve(node_path_1.default.dirname(result.statePath), "..", "..", "..");
+    const reportTarget = node_fs_1.default.existsSync(runRepoCwd) ? runRepoCwd : undefined;
+    const reportPath = runner.withBaseDir(reportTarget).report(result.runId).path;
     let hint;
     if (!agentConfigured) {
         hint =

package/dist/capability-registry.js

@@ -28,6 +28,7 @@ exports.CAPABILITY_REGISTRY = void 0;
 exports.declaredMcpTools = declaredMcpTools;
 exports.declaredCliTokens = declaredCliTokens;
 exports.requiresReason = requiresReason;
+exports.isPayloadProbeOptOut = isPayloadProbeOptOut;
 exports.payloadIdenticalCapabilities = payloadIdenticalCapabilities;
 exports.buildParityReport = buildParityReport;
 // ---------------------------------------------------------------------------
@@ -51,6 +52,14 @@ const BUILTIN_CAPABILITIES = [
         cli: { path: ["list"], jsonMode: "default" },
         mcp: { tool: "cw_list" }
     },
+    {
+        capability: "doctor",
+        summary: "Diagnose the host for setup problems (Node version, agent backend, agent binary on PATH, git, writable home/repo state) and print an actionable fix per check.",
+        entry: "runDoctor",
+        surface: "cli-only",
+        cli: { path: ["doctor"], jsonMode: "flag" },
+        reason: "Environment diagnostics are inherently local to the CLI host — Node version, $PATH, $CW_HOME/cwd writability. An MCP client diagnosing the server process's environment is not meaningful; agents already receive the same readiness facts in their typed results (e.g. status: blocked, agentConfigured). Inspired by `brew doctor`."
+    },
     {
         capability: "init",
         summary: "Scaffold a new workflow definition.",
@@ -428,10 +437,28 @@ function requiresReason(cap) {
         return true;
     return false;
 }
-/** Descriptors for the payload-identity probe: both-surface, identical payloads,
- *  read-only (safe to call on a planned run with just runId-style args). */
+/**
+ * Whether a `surface:"both"` capability is DOCUMENTED out of the payload-identity
+ * probe. The probe defaults capabilities IN (every both-surface, dual-bound verb —
+ * including write/complex-arg verbs) and requires an EXPLICIT, REASONED opt-out to
+ * fall out of scope. A capability escapes the probe only when it carries BOTH
+ * `payloadIdentical: false` AND a non-empty `reason`. A bare `payloadIdentical:
+ * false` with no recorded reason does NOT silently escape — it stays in the probe
+ * set so the undocumented divergence trips the gate (FAIL CLOSED). This mirrors the
+ * `requiresReason`/`reasonlessExceptions` gate, but enforces it at the probe-scope
+ * boundary too, so the marshalling-drift surface cannot be narrowed without a paper
+ * trail.
+ */
+function isPayloadProbeOptOut(cap) {
+    return cap.payloadIdentical === false && !!(cap.reason && cap.reason.trim());
+}
+/** Descriptors for the payload-identity probe. Defaults to EVERY both-surface,
+ *  dual-bound capability (read OR write); a capability is excluded only by a
+ *  documented opt-out (`payloadIdentical: false` + a non-empty `reason`) — see
+ *  `isPayloadProbeOptOut`. Fail-closed: an undocumented `payloadIdentical: false`
+ *  stays in scope so its divergence is caught, not silently excused. */
 function payloadIdenticalCapabilities() {
-    return exports.CAPABILITY_REGISTRY.filter((cap) => cap.surface === "both" && cap.payloadIdentical !== false && cap.cli && cap.mcp);
+    return exports.CAPABILITY_REGISTRY.filter((cap) => cap.surface === "both" && cap.cli && cap.mcp && !isPayloadProbeOptOut(cap));
 }
 function lintRegistry() {
     const issues = [];

package/dist/cli.js

@@ -21,6 +21,7 @@ const multi_agent_operator_ux_1 = require("./multi-agent-operator-ux");
 const multi_agent_eval_1 = require("./multi-agent-eval");
 const state_explosion_1 = require("./state-explosion");
 const evidence_reasoning_1 = require("./evidence-reasoning");
+const doctor_1 = require("./doctor");
 async function main() {
     const args = (0, orchestrator_1.parseArgv)(process.argv.slice(2));
     const runner = new orchestrator_1.CoolWorkflowRunner({
@@ -36,6 +37,16 @@ async function main() {
         case "list":
             printJson(runner.listWorkflows());
             return;
+        case "doctor": {
+            const report = (0, doctor_1.runDoctor)(args.options, process.env, String(args.options.cwd || process.cwd()));
+            if (wantsJson(args.options))
+                printJson(report);
+            else
+                process.stdout.write(`${(0, doctor_1.formatDoctorReport)(report)}\n`);
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
         case "init": {
             const [workflowId] = args.positionals;
             if (!workflowId)
@@ -1281,7 +1292,7 @@ async function main() {
 }
 function required(value, label) {
     if (!value)
-        throw new Error(`Missing ${label}`);
+        throw new Error(`Missing ${label}. Run "cw.js help" for usage.`);
     return value;
 }
 function optionalArg(value) {