cool-workflow 0.2.3 → 0.2.4

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.2.3",
+  "version": "0.2.4",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

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

package/dist/cli/dispatch.js

@@ -27,6 +27,7 @@ const capability_table_1 = require("../core/capability-table");
 const parseargv_1 = require("./parseargv");
 Object.defineProperty(exports, "KNOWN_COMMANDS", { enumerable: true, get: function () { return parseargv_1.KNOWN_COMMANDS; } });
 const io_1 = require("./io");
+const cli_args_1 = require("../core/util/cli-args");
 function firstPositional(args, index = 0) {
     return args.positionals[index];
 }
@@ -38,7 +39,7 @@ function firstPositional(args, index = 0) {
  *     `--json`/`--format json`.
  *   - `"human"` — always prints `result.text`; there is no JSON form. */
 function renderCliResult(result, jsonMode, options) {
-    const useJson = jsonMode === "default" || (jsonMode === "flag" && (0, io_1.wantsJson)(options));
+    const useJson = jsonMode === "default" || (jsonMode === "flag" && (0, cli_args_1.wantsJson)(options));
     if (useJson && result.json !== undefined) {
         (0, io_1.printJson)(result.json);
     }

package/dist/cli/io.js

@@ -1,8 +1,12 @@
 "use strict";
 // cli/io.ts — shared CLI input/output helpers.
 //
-// Byte-exact port of src/cli/io.ts in the old build. Pure + zero-dep: arg
-// coercion + JSON stdout. See SPEC/cli-surface.md "Shared io helpers".
+// Byte-exact port of src/cli/io.ts in the old build. Pure + zero-dep JSON
+// stdout, plus one impure TTY-aware help formatter. See SPEC/cli-surface.md
+// "Shared io helpers". Arg-coercion helpers (`required`/`optionalArg`/
+// `wantsJson`) moved to core/util/cli-args.ts (architecture-review P2) —
+// wiring/capability-table/*.ts needed them directly, and a cli/-layer file
+// may not be imported by wiring/ (scripts/purity-gate.js's layer rule).
 //
 // MILESTONE 11 (reporting/observability) adds `styledHelp` — the one
 // place `formatHelp()`'s plain text gets its "Cool Workflow" header
@@ -11,10 +15,7 @@
 // shell/term.ts's env/TTY read.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.styledHelp = styledHelp;
-exports.required = required;
-exports.optionalArg = optionalArg;
 exports.printJson = printJson;
-exports.wantsJson = wantsJson;
 const help_1 = require("../core/format/help");
 const safe_json_1 = require("../core/format/safe-json");
 const term_1 = require("../shell/term");
@@ -24,17 +25,6 @@ function styledHelp() {
     const text = (0, help_1.formatHelp)();
     return text.replace(/^Cool Workflow\n/, `${(0, term_1.bold)("Cool Workflow")}\n`);
 }
-/** Require a positional/option value or fail with a copy-pasteable recovery tip. */
-function required(value, label) {
-    if (!value) {
-        throw new Error(`Missing ${label}.\n  Tip: find run ids with "cw run list" or create one with "cw quickstart"`);
-    }
-    return value;
-}
-/** Normalize an optional CLI arg to a trimmed non-empty string, else undefined. */
-function optionalArg(value) {
-    return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
 /** Machine payload to stdout (stdout = data; never colored, never chrome).
  *  Byte-capped via safeJsonStringify — an aggregate result too large to be
  *  useful (or large enough to blow V8's string limit) prints a small
@@ -42,7 +32,3 @@ function optionalArg(value) {
 function printJson(value) {
     process.stdout.write(`${(0, safe_json_1.safeJsonStringify)(value)}\n`);
 }
-/** True when the caller asked for JSON output (`--json` or `--format json`). */
-function wantsJson(options) {
-    return Boolean(options.json || options.format === "json");
-}

package/dist/core/capability-data.js

@@ -257,8 +257,8 @@ exports.MCP_TOOL_DATA = [
     { tool: "cw_sched_reset", capability: "sched.reset", requiredArgs: [], properties: ["cwd", "id"], description: "Reset a parked entry to ready (operator recovery)." },
     { tool: "cw_sched_policy_show", capability: "sched.policy.show", requiredArgs: [], properties: ["cwd"], description: "Show the scheduling policy (file or default)." },
     { tool: "cw_sched_policy_set", capability: "sched.policy.set", requiredArgs: [], properties: ["cwd", "maxConcurrent", "maxAttempts", "leaseTtlMs", "backoffBaseMs", "backoffFactor", "backoffCapMs"], description: "Set scheduling policy fields (concurrency/attempts/backoff/TTL)." },
-    { tool: "cw_gc_plan", capability: "gc.plan", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots"], description: "Dry-run plan of run reclamation (per-kind bytes + capability downgrade); frees nothing." },
-    { tool: "cw_gc_run", capability: "gc.run", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "limit", "actor"], description: "Execute the write-ahead reclamation transaction (skeleton -> tombstone -> fsync -> free)." },
+    { tool: "cw_gc_plan", capability: "gc.plan", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "keepCommits"], description: "Dry-run plan of run reclamation (per-kind bytes + capability downgrade); frees nothing." },
+    { tool: "cw_gc_run", capability: "gc.run", requiredArgs: [], properties: ["cwd", "scope", "runId", "reclaimAfterArchiveDays", "keepScratch", "keepSnapshots", "keepCommits", "limit", "actor"], description: "Execute the write-ahead reclamation transaction (skeleton -> tombstone -> fsync -> free)." },
     { tool: "cw_gc_verify", capability: "gc.verify", requiredArgs: ["runId"], properties: ["cwd", "scope", "runId"], description: "Re-prove a reclaimed run: skeleton-complete, tombstone chain untampered, artifacts reconstructable." },
     { tool: "cw_clones_list", capability: "clones.list", requiredArgs: [], properties: [], description: "List the cached remote-source checkouts that --link/URL reviews populate (origin URL, kind, commit, age, bytes). Read-only." },
     { tool: "cw_clones_gc", capability: "clones.gc", requiredArgs: [], properties: ["olderThanDays", "all"], description: "Reclaim cached remote-source checkouts: a TTL sweep (--older-than-days, default 30) or --all. Deletes only inside the clones cache." },

package/dist/core/format/help.js

@@ -228,7 +228,12 @@ const COMMAND_HELP_ROWS = {
  *  capability-table rows that now support `--json`/`--format json`
  *  (io.ts's wantsJson) — the flag existed but was never documented here —
  *  and for a `--quiet` Flags row, a new CLI spelling of the existing
- *  CW_DRIVE_PROGRESS=0 env var (see cli/entry.ts). */
+ *  CW_DRIVE_PROGRESS=0 env var (see cli/entry.ts); and for a `--resume`
+ *  Flags row (architecture-review-driven fix), documenting the existing
+ *  `--resume --run <id>` continuation flag (shell/pipeline-cli.ts's
+ *  quickstartRun) that previously existed only in code comments and an
+ *  auto-generated continue hint — a user who never happened to type it
+ *  first had no way to discover it via `cw help`. */
 function formatHelp() {
     const moreCommandsLines = wrapPipeJoined(exports.MORE_COMMANDS_TOKENS, MORE_COMMANDS_WRAP_WIDTH);
     const lines = [
@@ -253,6 +258,7 @@ function formatHelp() {
         "  --no-color             Disable ANSI color (also honors NO_COLOR / FORCE_COLOR)",
         "  --json                 Print JSON for commands that support it",
         "  --quiet                Suppress [drive] progress lines (not agent output)",
+        "  --resume --run <id>    Continue an interrupted run to completion",
         "",
         "More commands",
         ...moreCommandsLines,

package/dist/core/util/cli-args.js

@@ -0,0 +1,33 @@
+"use strict";
+// core/util/cli-args.ts — shared CLI argv / MCP tool-call arg-coercion
+// helpers: required(), optionalArg(), wantsJson().
+//
+// Pure. No fs, no child_process, no net, no process.env, no Date.now(), no
+// Math.random().
+//
+// Moved out of cli/io.ts (architecture-review P2): a cli/-layer file may
+// not be imported by wiring/ (see scripts/purity-gate.js's layer rule),
+// but every wiring/capability-table/*.ts slice called these three pure
+// functions directly to coerce its own handler's args. Shared by CLI argv
+// (cli/dispatch.ts, the wiring slices) AND MCP tool-call args (the same
+// wiring slices' MCP handler bodies) — see core/util/numeric-flag.ts for
+// the same CLI/MCP-shared framing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.required = required;
+exports.optionalArg = optionalArg;
+exports.wantsJson = wantsJson;
+/** Require a positional/option value or fail with a copy-pasteable recovery tip. */
+function required(value, label) {
+    if (!value) {
+        throw new Error(`Missing ${label}.\n  Tip: find run ids with "cw run list" or create one with "cw quickstart"`);
+    }
+    return value;
+}
+/** Normalize an optional CLI arg to a trimmed non-empty string, else undefined. */
+function optionalArg(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/** True when the caller asked for JSON output (`--json` or `--format json`). */
+function wantsJson(options) {
+    return Boolean(options.json || options.format === "json");
+}

package/dist/core/version.js

@@ -7,7 +7,7 @@ exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA
 // `cw version` output does not change bytes just because the code under it
 // was rebuilt. See SPEC/cli-surface.md "Exact outputs > Version" and
 // conformance/cases/version-basic.case.js (regex `/^\d+\.\d+\.\d+\n$/`).
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.2.3";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.2.4";
 // State-kernel schema version constants (SPEC/state-core.md "Version
 // constants"). Pinned to the old build's src/version.ts byte-for-byte.
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;

package/dist/shell/drive.js

@@ -717,6 +717,14 @@ function prepareConcurrentOutcomes(ctx, batch) {
     }
     if (jobs.length) {
         emitProgress(`⇉ concurrent round: ${jobs.length} agent${jobs.length > 1 ? "s" : ""} spawning in parallel, may take minutes…`);
+        // Every task above that reached "pending" got dispatched (workerId
+        // assigned) in the round-cached run object, but nothing durable was
+        // written for it — unlike the serial path's own dispatch branch, which
+        // always checkpoints immediately. Flush now, BEFORE the batch's long
+        // spawn window opens: a crash mid-spawn (which can run for minutes)
+        // then leaves state.json correctly showing these tasks as dispatched,
+        // instead of losing the dispatch entirely.
+        (0, run_store_1.saveCheckpoint)(loadRun(ctx));
     }
     const settled = (0, agent_1.runAgentBatchOutcomes)(jobs);
     const outcomes = new Map();
@@ -896,14 +904,14 @@ function driveOneRound(ctx, options, steps, emitPhaseProgress) {
  *  finishes its own bookkeeping first. A SECOND signal means the caller
  *  wants out right now, not a graceful stop, and force-exits immediately
  *  with the conventional 128+signum code. */
-function createStopSignalController() {
+function createStopSignalController(runId) {
     let interruptedBy;
     let stopSignalHits = 0;
     const onStopSignal = (signal) => {
         stopSignalHits += 1;
         if (stopSignalHits === 1) {
             interruptedBy = signal;
-            emitProgress(`received ${signal} — stopping after the current step (run again with the same run id to resume)`);
+            emitProgress(`received ${signal} — stopping after the current step (resume: cw run resume ${runId} --drive)`);
             return;
         }
         // A second signal means the caller wants out right now, not a graceful stop.
@@ -952,11 +960,11 @@ function finalizeDriveResult(ctx, options, steps, plannedWorkers, maxIter, exhau
     if (interruptedBy) {
         exhaustedMaxIterations = false;
         if (!alreadyComplete) {
-            steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive interrupted by ${interruptedBy} — run again with the same run id to resume` }));
+            steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive interrupted by ${interruptedBy} — resume: cw run resume ${ctx.runId} --drive` }));
         }
     }
     else if (exhaustedMaxIterations) {
-        steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive reached max iteration limit (${maxIter}) before a terminal state` }));
+        steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive reached max iteration limit (${maxIter}) before a terminal state — resume: cw run resume ${ctx.runId} --drive` }));
     }
     const statusInputs = {
         once: Boolean(options.once),
@@ -1002,7 +1010,7 @@ function drive(runId, cwd, options = {}) {
     const maxIter = (0, drive_decide_1.maxIterations)(plannedWorkers, (0, loop_expansion_1.maxLoopExpansion)(run0), ctx.policy);
     const emitPhaseProgress = createPhaseProgressEmitter();
     let exhaustedMaxIterations = !options.once;
-    const stopSignal = createStopSignalController();
+    const stopSignal = createStopSignalController(runId);
     stopSignal.install();
     try {
         for (let i = 0; i < maxIter; i++) {
@@ -1051,7 +1059,7 @@ async function driveAsync(runId, cwd, options = {}) {
     const maxIter = (0, drive_decide_1.maxIterations)(plannedWorkers, (0, loop_expansion_1.maxLoopExpansion)(run0), ctx.policy);
     const emitPhaseProgress = createPhaseProgressEmitter();
     let exhaustedMaxIterations = !options.once;
-    const stopSignal = createStopSignalController();
+    const stopSignal = createStopSignalController(runId);
     stopSignal.install();
     try {
         for (let i = 0; i < maxIter; i++) {

package/dist/shell/execution-backend/agent.js

@@ -87,14 +87,23 @@ const AGENT_PROVIDER_KEY_ENV_RE = /^(CW_|ANTHROPIC_|OPENAI_|GEMINI_|DEEPSEEK_|CO
  *  worker.agent-env trust-audit event. */
 function buildAgentChildEnv(policy, baseEnv = process.env) {
     const env = (0, local_1.buildChildEnv)(policy, baseEnv);
+    // deny must win here too: buildChildEnv already applied it above, but the
+    // provider-key/USER re-add below exists specifically to put vars BACK
+    // that buildChildEnv's readonly/locked-down defaults strip — without this
+    // check that re-add silently overrode an operator's explicit deny (e.g.
+    // deny:["AWS_SECRET_ACCESS_KEY"] still forwarded it, since AWS_ matches
+    // AGENT_PROVIDER_KEY_ENV_RE).
+    const denied = new Set(policy.env.deny || []);
     const forwarded = [];
     for (const key of Object.keys(baseEnv)) {
+        if (denied.has(key))
+            continue;
         if (AGENT_PROVIDER_KEY_ENV_RE.test(key)) {
             env[key] = baseEnv[key];
             forwarded.push(key);
         }
     }
-    if (baseEnv.USER !== undefined && env.USER === undefined) {
+    if (!denied.has("USER") && baseEnv.USER !== undefined && env.USER === undefined) {
         env.USER = baseEnv.USER;
         forwarded.push("USER");
     }

package/dist/shell/execution-backend/local.js

@@ -19,16 +19,21 @@ function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function buildChildEnv(policy, baseEnv = process.env) {
-    if (policy.env.inherit)
-        return { ...baseEnv };
-    const env = {};
-    if (baseEnv.PATH !== undefined)
-        env.PATH = baseEnv.PATH;
-    if (baseEnv.HOME !== undefined)
-        env.HOME = baseEnv.HOME;
-    for (const name of policy.env.expose || []) {
-        if (baseEnv[name] !== undefined)
-            env[name] = baseEnv[name];
+    // deny must win regardless of inherit: a custom profile combining
+    // inherit:true with deny:[...] (a valid, normalized combination — see
+    // sandbox-profile.ts's normalizeEnv) means "everything EXCEPT these".
+    // An early return on inherit before this loop ran meant deny was
+    // silently skipped whenever inherit was true.
+    const env = policy.env.inherit ? { ...baseEnv } : {};
+    if (!policy.env.inherit) {
+        if (baseEnv.PATH !== undefined)
+            env.PATH = baseEnv.PATH;
+        if (baseEnv.HOME !== undefined)
+            env.HOME = baseEnv.HOME;
+        for (const name of policy.env.expose || []) {
+            if (baseEnv[name] !== undefined)
+                env[name] = baseEnv[name];
+        }
     }
     for (const name of policy.env.deny || []) {
         delete env[name];

package/dist/shell/pipeline-cli.js

@@ -159,6 +159,24 @@ function planInputsFor(args) {
 function invocationCwd(args) {
     return typeof args.cwd === "string" && args.cwd.trim() ? path.resolve(args.cwd) : process.cwd();
 }
+/** Same as invocationCwd, but ALSO falls back to `--repo` before
+ *  process.cwd() -- for resolving an EXISTING run's directory specifically
+ *  (loadRunFromCwd's target), never for a fresh plan()'s repo input (see
+ *  planRun's own comment on why THAT path deliberately never auto-fills
+ *  repo from cwd). A caller resuming a run they didn't originally start
+ *  from this exact directory (the common case: `cw run resume <id>
+ *  --drive` or `cw quickstart <app> --resume --run <id>` typed from
+ *  wherever the terminal happens to be, not necessarily the run's own
+ *  --repo) must not have that already-known fact silently discarded in
+ *  favor of process.cwd() -- this mirrors the --preview branch's own
+ *  repoCwd fallback a few lines below, which already gets this right. */
+function existingRunCwd(args) {
+    if (typeof args.cwd === "string" && args.cwd.trim())
+        return path.resolve(args.cwd);
+    if (typeof args.repo === "string" && args.repo.trim())
+        return path.resolve(args.repo);
+    return process.cwd();
+}
 /** True for a value that counts as "not supplied" — byte-exact to the old
  *  build's cli-options.isMissing (undefined / null / empty string). */
 function isMissingInput(value) {
@@ -239,7 +257,7 @@ async function runDriveStep(args) {
         incremental: Boolean(args.incremental),
     };
     if (existingRunId) {
-        const cwd = invocationCwd(args);
+        const cwd = existingRunCwd(args);
         const run = (0, run_store_1.loadRunFromCwd)(existingRunId, cwd);
         return (0, drive_1.driveAsync)(existingRunId, run.cwd, options);
     }
@@ -502,7 +520,7 @@ async function quickstartRun(args) {
     };
     let run;
     if (existingRunId) {
-        run = (0, run_store_1.loadRunFromCwd)(existingRunId, invocationCwd(args));
+        run = (0, run_store_1.loadRunFromCwd)(existingRunId, existingRunCwd(args));
     }
     else {
         run = (0, pipeline_1.plan)(resolveWorkflowAppForPlan(appId), planInputsFor(args));

package/dist/shell/reclamation-io.js

@@ -472,6 +472,31 @@ function planReclamation(run, policy = {}) {
             }
         }
     }
+    // (3) Superseded, non-verifier-gated commit snapshots. Each commitState()
+    // call embeds the FULL run into commits/<id>.json, so these grow without
+    // bound (both in count and per-file size) with no reclamation path today.
+    // Only the run's LATEST commit and any verifier-gated commit (the actual
+    // audit-significant milestones) are kept — an intermediate, non-gated
+    // "checkpoint" commit's only value is as a point-in-time snapshot, and
+    // state.json (not commits/) is the source of truth for resume. Not
+    // reconstructable (no recipe): a commit snapshot is a genuine
+    // point-in-time capture, not a projection derivable from retained data.
+    let reclaimedCommitSnapshot = false;
+    if (!policy.keepCommits) {
+        const commits = run.commits || [];
+        for (let i = 0; i < commits.length - 1; i++) {
+            const commit = commits[i];
+            if (commit.verifierGated)
+                continue;
+            if (!commit.snapshotPath || !fs.existsSync(commit.snapshotPath))
+                continue;
+            const bytes = dirBytes(commit.snapshotPath);
+            if (bytes <= 0)
+                continue;
+            freeable.push({ path: rel(commit.snapshotPath), absPath: commit.snapshotPath, kind: "commit-snapshot", bytes });
+            reclaimedCommitSnapshot = true;
+        }
+    }
     // Determinism (HARD constraint): sort by path BEFORE anything hashes it,
     // so tombstoneHash is reproducible across hosts regardless of
     // fs.readdirSync's filesystem-dependent order.
@@ -484,7 +509,15 @@ function planReclamation(run, policy = {}) {
     }
     let capability = "re-runnable";
     let capabilityReason = "scratch-only-reclaimed";
-    if (reclaimedSnapshot && reconstructableSnapshot) {
+    // A reclaimed commit snapshot is never reconstructable (a genuine
+    // point-in-time capture, no recipe) — it caps capability at "verify-only"
+    // regardless of what node-snapshot reclamation achieved, same as an
+    // unreconstructable node snapshot would.
+    if (reclaimedCommitSnapshot) {
+        capability = "verify-only";
+        capabilityReason = "snapshot-reclaimed-no-reconstruction";
+    }
+    else if (reclaimedSnapshot && reconstructableSnapshot) {
         capability = "re-runnable-by-reconstruction";
         capabilityReason = "inputs-and-expectdigest-retained";
     }
@@ -595,13 +628,22 @@ function commitTombstone(run, tombstone) {
 function prepareFree(run, tombstone) {
     const runDir = run.paths.runDir;
     const scratchDirs = tombstone.freed.filter((f) => f.kind === "scratch").map((f) => (0, fs_atomic_1.realResolve)(path.join(runDir, f.path)));
-    if (!scratchDirs.length)
+    const commitSnapshotPaths = tombstone.freed.filter((f) => f.kind === "commit-snapshot").map((f) => (0, fs_atomic_1.realResolve)(path.join(runDir, f.path)));
+    if (!scratchDirs.length && !commitSnapshotPaths.length)
         return;
     const repointed = new Set();
     for (const scratchDir of scratchDirs) {
         for (const id of repointResultNodeArtifacts(run, scratchDir))
             repointed.add(id);
     }
+    // Unlike scratch (which has a retained "result" artifact to repoint to),
+    // a reclaimed commit snapshot has no surviving alternative — its OWN
+    // StateNode's "snapshot" artifact (recordCommitNode, shell/commit.ts) is
+    // the only reference to it, so it is stripped outright rather than
+    // repointed. node.outputs.snapshotPath (a plain metadata string, not an
+    // artifact the check below inspects) is left as a historical record,
+    // same as commit.snapshotPath itself staying in state.json.
+    stripCommitSnapshotArtifacts(run, commitSnapshotPaths);
     persistRunDurable(run);
     for (const node of run.nodes || []) {
         for (const artifact of node.artifacts || []) {
@@ -613,6 +655,9 @@ function prepareFree(run, tombstone) {
                     throw new ReclamationError("repoint-incomplete", `node ${node.id} artifact ${artifact.id} still references freed scratch path ${artifact.path}`, { nodeId: node.id, artifactId: artifact.id, path: artifact.path });
                 }
             }
+            if (commitSnapshotPaths.includes(resolved)) {
+                throw new ReclamationError("repoint-incomplete", `node ${node.id} artifact ${artifact.id} still references freed commit snapshot ${artifact.path}`, { nodeId: node.id, artifactId: artifact.id, path: artifact.path });
+            }
         }
     }
     for (const nodeId of repointed) {
@@ -682,6 +727,28 @@ function repointResultNodeArtifacts(run, freedScratchDir) {
     }
     return changedIds;
 }
+/** Removes the "snapshot" artifact entry from any node that references one
+ *  of `freedCommitSnapshotPaths` — there is no retained alternative to
+ *  repoint to (unlike a scratch dir's "result" copy), so the reference is
+ *  dropped outright. StateArtifact.path is a required string, so the
+ *  artifact entry is filtered out rather than nulled. */
+function stripCommitSnapshotArtifacts(run, freedCommitSnapshotPaths) {
+    if (!freedCommitSnapshotPaths.length)
+        return [];
+    const freedSet = new Set(freedCommitSnapshotPaths);
+    const changedIds = [];
+    for (const node of run.nodes || []) {
+        if (!node.artifacts || !node.artifacts.length)
+            continue;
+        const before = node.artifacts.length;
+        node.artifacts = node.artifacts.filter((artifact) => !artifact.path || !freedSet.has((0, fs_atomic_1.realResolve)(artifact.path)));
+        if (node.artifacts.length !== before) {
+            node.updatedAt = new Date().toISOString();
+            changedIds.push(node.id);
+        }
+    }
+    return changedIds;
+}
 /** Execute the write-ahead, fail-closed reclamation transaction. */
 function runReclamation(run, options = {}) {
     const skeleton = extractSkeleton(run);
@@ -827,7 +894,7 @@ function gcPlan(host, options = {}) {
         let plan;
         try {
             const run = host.loadRun(record.repo, record.runId);
-            plan = planReclamation(run, { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots });
+            plan = planReclamation(run, { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots, keepCommits: policy.keepCommits });
         }
         catch {
             entries.push({
@@ -871,6 +938,7 @@ function gcPlan(host, options = {}) {
             reclaimAfterArchiveDays: policy.reclaimAfterArchiveDays ?? 0,
             keepSnapshots: Boolean(policy.keepSnapshots),
             keepScratch: Boolean(policy.keepScratch),
+            keepCommits: Boolean(policy.keepCommits),
             reclaimStates: policy.reclaimStates && policy.reclaimStates.length ? policy.reclaimStates : ["completed", "failed"],
         },
         total: entries.length,
@@ -911,8 +979,8 @@ function gcRun(host, options = {}) {
             const result = runReclamation(run, {
                 now: nowIso,
                 actor: options.actor,
-                policy: { reclaimAfterArchiveDays: policy.reclaimAfterArchiveDays, keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots },
-                reclaimPolicy: { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots },
+                policy: { reclaimAfterArchiveDays: policy.reclaimAfterArchiveDays, keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots, keepCommits: policy.keepCommits },
+                reclaimPolicy: { keepScratch: policy.keepScratch, keepSnapshots: policy.keepSnapshots, keepCommits: policy.keepCommits },
             });
             reclaimed.push({
                 runId: record.runId,
@@ -1004,7 +1072,7 @@ function gcVerify(host, runId, options = {}) {
 function formatGcPlan(result) {
     const lines = [
         `GC Plan (${result.scope}): ${result.eligibleCount}/${result.total} eligible, ${result.bytesToFree} byte(s) would be freed [DRY-RUN, frees nothing]`,
-        `  policy: reclaimAfterArchiveDays=${result.policy.reclaimAfterArchiveDays} keepScratch=${result.policy.keepScratch} keepSnapshots=${result.policy.keepSnapshots}`,
+        `  policy: reclaimAfterArchiveDays=${result.policy.reclaimAfterArchiveDays} keepScratch=${result.policy.keepScratch} keepSnapshots=${result.policy.keepSnapshots} keepCommits=${result.policy.keepCommits}`,
     ];
     for (const entry of result.entries) {
         if (entry.eligible) {

package/dist/shell/registry-cli.js

@@ -297,6 +297,10 @@ function gcPolicyOverridesFrom(options) {
         overrides.keepSnapshots = Boolean(options.keepSnapshots);
     if (options["keep-snapshots"] !== undefined)
         overrides.keepSnapshots = Boolean(options["keep-snapshots"]);
+    if (options.keepCommits !== undefined)
+        overrides.keepCommits = Boolean(options.keepCommits);
+    if (options["keep-commits"] !== undefined)
+        overrides.keepCommits = Boolean(options["keep-commits"]);
     if (options.state !== undefined)
         overrides.reclaimStates = Array.isArray(options.state) ? options.state : [options.state];
     return overrides;

package/dist/shell/run-registry-io.js

@@ -87,6 +87,7 @@ exports.DEFAULT_RUN_REGISTRY_POLICY = {
     reclaimStates: ["completed", "failed"],
     keepSnapshots: false,
     keepScratch: false,
+    keepCommits: false,
     maxReclaimRuns: 0,
     maxReclaimBytes: 0,
 };