cool-workflow 0.2.2 → 0.2.4

package/dist/shell/pipeline-cli.js

@@ -52,6 +52,8 @@ exports.recordResultRun = recordResultRun;
 exports.commitRun = commitRun;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const readlinePromises = __importStar(require("node:readline/promises"));
+const numeric_flag_1 = require("../core/util/numeric-flag");
 const pipeline_1 = require("./pipeline");
 const workflow_app_loader_1 = require("./workflow-app-loader");
 const drive_1 = require("./drive");
@@ -157,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) {
@@ -223,8 +243,11 @@ function runDrivePreview(args) {
     return (0, drive_1.drivePreview)(runId, cwd, args);
 }
 /** `cw run <app|--run id> --drive [--once]` — plans a fresh run (unless
- *  `--run` continues an existing one) and drives it. */
-function runDriveStep(args) {
+ *  `--run` continues an existing one) and drives it. Uses driveAsync (not
+ *  the plain synchronous drive()) so a live multi-round run actually
+ *  responds to Ctrl-C/SIGTERM instead of silently ignoring it — see
+ *  shell/drive.ts's driveAsync doc comment. */
+async function runDriveStep(args) {
     const existingRunId = String(args.runId || args.run || "");
     const options = {
         once: Boolean(args.once),
@@ -234,9 +257,9 @@ 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.drive)(existingRunId, run.cwd, options);
+        return (0, drive_1.driveAsync)(existingRunId, run.cwd, options);
     }
     const appId = String(args.appId || args.app || args.positionalApp || "");
     if (!appId)
@@ -245,7 +268,7 @@ function runDriveStep(args) {
         args.repo = invocationCwd(args);
     const app = (0, workflow_app_loader_1.loadWorkflowApp)(appId);
     const run = (0, pipeline_1.plan)(app, planInputsFor(args));
-    return (0, drive_1.drive)(run.id, run.cwd, options);
+    return (0, drive_1.driveAsync)(run.id, run.cwd, options);
 }
 /** `cw quickstart [app] --check` — read-only preflight: does the app
  *  resolve, is the repo readable/writable, is a question set, is an
@@ -385,6 +408,21 @@ function remoteQuickstartCheck(appId, args, candidate) {
     const nextCommand = `cw quickstart ${shellWord(appId)} --link ${shellWord(validation.url)}${question ? ` --question ${shellWord(question)}` : ""}`;
     return { schemaVersion: 1, mode: "check", ok, appId, repo: validation.url, checks, nextCommand };
 }
+/** Prompts `Question: ` on STDERR (stdout stays data-only, matching the
+ *  Rule of Silence) and reads one line from stdin. Returns the trimmed
+ *  answer, or `undefined` for a blank line. Callers must only invoke this
+ *  when `process.stdin.isTTY` — it would otherwise block forever on a
+ *  piped/CI invocation. */
+async function promptForQuestion() {
+    const rl = readlinePromises.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question("Question: ");
+        return answer.trim() || undefined;
+    }
+    finally {
+        rl.close();
+    }
+}
 /** `cw quickstart [app] --question ...` — composes plan -> runDrive ->
  *  report in one call. Default app is architecture-review. `--check` is a
  *  read-only preflight that never plans/drives/writes (see
@@ -392,7 +430,7 @@ function remoteQuickstartCheck(appId, args, candidate) {
  *  projection (never drives), `--resume` advances one step (no --run) or
  *  continues a named run to completion (--run <id>) — both ported byte-for-
  *  byte from the old build's src/capability-core.ts quickstart(). */
-function quickstartRun(args) {
+async function quickstartRun(args) {
     const appId = String(args.appId || args.app || args.workflowId || QUICKSTART_DEFAULT_APP);
     // Remote source: a `--link <url>` — or a URL passed to `--repo`/`-dir` — is
     // materialized to a LOCAL checkout HERE (capability/shell layer). Cloning is
@@ -406,6 +444,37 @@ function quickstartRun(args) {
         args.repo = invocationCwd(args);
     if (Boolean(args.check))
         return quickstartCheck(appId, args, remoteCandidate);
+    // `--resume`: a discoverability flag over the existing continuation. With no
+    // `--run`, advance exactly ONE step (reuse the `--once` path) and print a
+    // copy-pasteable continue line; with `--run <id>`, continue that run to
+    // completion (the default drive). It adds no new execution path. Byte-exact to
+    // the old build's src/capability-core.ts quickstart(). Hoisted above the TTY
+    // prompt below: `existingRunId` is the one fact (mirrored at both the
+    // `--preview` branch's `if (!previewRunId)` and the main path's `if
+    // (existingRunId) {...} else { run = plan(...) }`) that decides whether THIS
+    // invocation plans a fresh run at all — an existing run never needs a
+    // question, no matter which mode (--preview/--resume/plain) is asking for it.
+    const resume = Boolean(args.resume);
+    const existingRunId = String(args.runId || args.run || "");
+    const resumeRunId = resume && existingRunId ? existingRunId : undefined;
+    // On an interactive TTY with no --question, ask for one instead of
+    // failing closed with "Missing required input: question" (byte-behavior
+    // port of the old build's TTY prompt — SPEC/cli-surface.md:34,502). A
+    // blank/empty answer leaves `question` unset, same as never passing
+    // --question at all — plan()'s own required-input check still fails
+    // closed for an app that declares `question` required. Never fires
+    // under --check (returned above; --check reports a missing question as
+    // a preflight issue, not something to prompt for), off a TTY (a piped
+    // invocation must never block on stdin), or when `existingRunId` is set
+    // (a `--preview --run <id>` or `--resume --run <id>` continues an
+    // already-planned run and never calls `plan()` again, so it never
+    // needs a question — prompting there would block on stdin for no
+    // reason; a review on this cycle caught exactly that regression).
+    if (process.stdin.isTTY && !existingRunId && !(typeof args.question === "string" && args.question.trim())) {
+        const answer = await promptForQuestion();
+        if (answer)
+            args.question = answer;
+    }
     // Materialize the remote NOW — after `--check` (never fetches) and before any
     // plan/drive — so the core only ever sees the local checkout. Fails closed: a
     // bad URL / blocked scheme / missing git / fetch failure throws here.
@@ -424,14 +493,6 @@ function quickstartRun(args) {
         if (remoteSource.ref)
             args.sourceRef = remoteSource.ref;
     }
-    // `--resume`: a discoverability flag over the existing continuation. With no
-    // `--run`, advance exactly ONE step (reuse the `--once` path) and print a
-    // copy-pasteable continue line; with `--run <id>`, continue that run to
-    // completion (the default drive). It adds no new execution path. Byte-exact to
-    // the old build's src/capability-core.ts quickstart().
-    const resume = Boolean(args.resume);
-    const existingRunId = String(args.runId || args.run || "");
-    const resumeRunId = resume && existingRunId ? existingRunId : undefined;
     // `--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. Never drives.
@@ -459,12 +520,12 @@ 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));
     }
-    const result = (0, drive_1.drive)(run.id, run.cwd, options);
+    const result = await (0, drive_1.driveAsync)(run.id, run.cwd, options);
     const finalRun = (0, run_store_1.loadRunFromCwd)(run.id, run.cwd);
     (0, report_1.writeReport)(finalRun);
     // Tamper-evident provenance: bind the remote origin (url@sha) into the run's
@@ -560,7 +621,7 @@ function dispatchRun(args) {
             const v = args[kebab] ?? args[camel];
             return typeof v === "string" && v.trim() ? v : undefined;
         };
-        const manifest = (0, dispatch_1.createDispatchManifest)(run, args.limit !== undefined ? Number(args.limit) : undefined, {
+        const manifest = (0, dispatch_1.createDispatchManifest)(run, (0, numeric_flag_1.requiredNumberFlag)(args.limit, "--limit"), {
             sandboxProfileId: typeof args.sandbox === "string" ? args.sandbox : undefined,
             sandbox: typeof args.sandbox === "string" ? args.sandbox : undefined,
             backendId: typeof args.backend === "string" ? args.backend : undefined,
@@ -649,29 +710,33 @@ function recordResultRun(args) {
  *  still leaves the run's report/state current on disk. */
 function commitRun(args) {
     const runId = String(args.runId);
-    const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
-    const allowCheckpoint = Boolean(args.allowUnverifiedCheckpoint || args["allow-unverified-checkpoint"]);
-    const hasGateOption = Boolean(args.verifier || args.verifierNode || args["verifier-node"] || args.candidate || args.selection);
-    try {
-        const commit = (0, commit_1.commitState)(run, {
-            reason: typeof args.reason === "string" && args.reason ? args.reason : "manual",
-            verifierNodeId: (typeof args.verifier === "string" && args.verifier) ||
-                (typeof args.verifierNode === "string" && args.verifierNode) ||
-                (typeof args["verifier-node"] === "string" && args["verifier-node"]) ||
-                undefined,
-            candidateId: typeof args.candidate === "string" ? args.candidate : undefined,
-            selectionId: typeof args.selection === "string" ? args.selection : undefined,
-            verifierGated: hasGateOption || !allowCheckpoint,
-            allowUnverifiedCheckpoint: allowCheckpoint,
-            source: "cli",
-        });
-        (0, report_1.writeReport)(run);
-        (0, run_store_1.saveCheckpoint)(run);
-        return { runId: run.id, commit };
-    }
-    catch (error) {
-        (0, report_1.writeReport)(run);
-        (0, run_store_1.saveCheckpoint)(run);
-        throw error;
-    }
+    // Hold the state.json lock across the whole load -> commit -> save (both the
+    // success and the fail-closed catch persist) so a concurrent run mutation
+    // cannot drop this commit (lost-update class, matching dispatchRun/recordResultRun).
+    return (0, run_store_1.withRunStateLock)(runId, invocationCwd(args), (run) => {
+        const allowCheckpoint = Boolean(args.allowUnverifiedCheckpoint || args["allow-unverified-checkpoint"]);
+        const hasGateOption = Boolean(args.verifier || args.verifierNode || args["verifier-node"] || args.candidate || args.selection);
+        try {
+            const commit = (0, commit_1.commitState)(run, {
+                reason: typeof args.reason === "string" && args.reason ? args.reason : "manual",
+                verifierNodeId: (typeof args.verifier === "string" && args.verifier) ||
+                    (typeof args.verifierNode === "string" && args.verifierNode) ||
+                    (typeof args["verifier-node"] === "string" && args["verifier-node"]) ||
+                    undefined,
+                candidateId: typeof args.candidate === "string" ? args.candidate : undefined,
+                selectionId: typeof args.selection === "string" ? args.selection : undefined,
+                verifierGated: hasGateOption || !allowCheckpoint,
+                allowUnverifiedCheckpoint: allowCheckpoint,
+                source: "cli",
+            });
+            (0, report_1.writeReport)(run);
+            (0, run_store_1.saveCheckpoint)(run);
+            return { runId: run.id, commit };
+        }
+        catch (error) {
+            (0, report_1.writeReport)(run);
+            (0, run_store_1.saveCheckpoint)(run);
+            throw error;
+        }
+    });
 }

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) {
@@ -639,6 +684,16 @@ function freeBulk(run, tombstone) {
     let freedBytes = 0;
     for (const entry of tombstone.freed) {
         const abs = path.join(runDir, entry.path);
+        // planReclamation always derives entry.path as a relative path already
+        // confined under runDir, but a tampered/imported state.json could carry a
+        // worker/artifact path that resolves outside it — re-check containment
+        // right before the recursive delete so that can never turn into an
+        // out-of-tree rmSync.
+        if (!(0, fs_atomic_1.isContainedPath)(abs, runDir)) {
+            throw new ReclamationError("unsafe-free-path", `refusing to free path outside the run directory: ${entry.path}`, {
+                path: entry.path,
+            });
+        }
         const before = dirBytes(abs);
         fs.rmSync(abs, { recursive: true, force: true });
         freedBytes += before;
@@ -672,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);
@@ -817,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({
@@ -861,13 +938,14 @@ 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,
         eligibleCount,
         bytesToFree,
         entries,
-        nextAction: eligibleCount ? "node scripts/cw.js gc run" : "node scripts/cw.js run search",
+        nextAction: eligibleCount ? "cw gc run" : "cw run search",
     };
 }
 function gcRun(host, options = {}) {
@@ -901,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,
@@ -936,7 +1014,7 @@ function gcRun(host, options = {}) {
         reclaimed,
         refused,
         totalBytesFreed,
-        nextAction: reclaimed.length ? "node scripts/cw.js gc verify <run-id>" : "node scripts/cw.js gc plan",
+        nextAction: reclaimed.length ? "cw gc verify <run-id>" : "cw gc plan",
     };
 }
 function gcVerify(host, runId, options = {}) {
@@ -952,7 +1030,7 @@ function gcVerify(host, runId, options = {}) {
             capability: "re-runnable",
             chainLength: 0,
             checks: [{ name: "located", pass: false, code: "not-reclaimed", detail: "run source not found" }],
-            nextAction: "node scripts/cw.js registry refresh" + (scope === "home" ? " --scope home" : ""),
+            nextAction: "cw registry refresh" + (scope === "home" ? " --scope home" : ""),
         };
     }
     const run = host.loadRun(located.record.repo, runId);
@@ -985,7 +1063,7 @@ function gcVerify(host, runId, options = {}) {
         tombstoneHash: last?.tombstoneHash,
         chainLength: result.tombstones.length,
         checks,
-        nextAction: verified ? "node scripts/cw.js run show " + runId : "node scripts/cw.js gc plan",
+        nextAction: verified ? "cw run show " + runId : "cw gc plan",
     };
 }
 // ---------------------------------------------------------------------------
@@ -994,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

@@ -82,6 +82,7 @@ exports.clonesListCli = clonesListCli;
 exports.clonesGcCli = clonesGcCli;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const numeric_flag_1 = require("../core/util/numeric-flag");
 const run_registry_io_1 = require("./run-registry-io");
 const pipeline_1 = require("./pipeline");
 const workflow_app_loader_1 = require("./workflow-app-loader");
@@ -186,16 +187,16 @@ function runSearchCli(options = {}) {
         since: optionalString(options.since),
         until: optionalString(options.until),
         includeArchived: options.includeArchived === undefined ? undefined : Boolean(options.includeArchived),
-        limit: options.limit === undefined ? undefined : Number(options.limit),
-        offset: options.offset === undefined ? undefined : Number(options.offset),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
+        offset: (0, numeric_flag_1.requiredNumberFlag)(options.offset, "--offset"),
     });
 }
 function runListCli(options = {}) {
     return new run_registry_io_1.RunRegistry(resolveCwd(options)).list({
         scope: scopeOf(options, "home"),
         includeArchived: options.includeArchived === undefined ? undefined : Boolean(options.includeArchived),
-        limit: options.limit === undefined ? undefined : Number(options.limit),
-        offset: options.offset === undefined ? undefined : Number(options.offset),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
+        offset: (0, numeric_flag_1.requiredNumberFlag)(options.offset, "--offset"),
     });
 }
 function runShowCli(runId, options = {}) {
@@ -205,21 +206,21 @@ function runShowCli(runId, options = {}) {
  *  is read-only and byte-identical to the registry resume payload; with
  *  `--drive`/`--once` the SAME run (nothing re-planned) is handed to the
  *  real drive loop and the payload gains a `drive: DriveResult` field. */
-function runResumeCli(runId, options = {}) {
+async function runResumeCli(runId, options = {}) {
     const base = new run_registry_io_1.RunRegistry(resolveCwd(options)).resume(runId, {
         scope: scopeOf(options, "home"),
-        limit: options.limit === undefined ? undefined : Number(options.limit),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
     });
     if (!options.drive && !options.once)
         return base;
-    const drive = (0, pipeline_cli_1.runDriveStep)({ ...options, runId: base.runId, repo: base.repo, once: Boolean(options.once) });
+    const drive = await (0, pipeline_cli_1.runDriveStep)({ ...options, runId: base.runId, repo: base.repo, once: Boolean(options.once) });
     return { ...base, drive };
 }
 function runArchiveCli(runId, options = {}) {
     const registry = new run_registry_io_1.RunRegistry(resolveCwd(options));
     if (!runId) {
-        const olderThanDays = Number(options.olderThanDays ?? options["older-than-days"]);
-        if (!Number.isFinite(olderThanDays))
+        const olderThanDays = (0, numeric_flag_1.requiredNumberFlag)(options.olderThanDays ?? options["older-than-days"], "--older-than-days");
+        if (olderThanDays === undefined)
             throw new Error("Missing run id (or --older-than-days N for the retention policy path).");
         const states = Array.isArray(options.state) ? options.state : options.state ? [options.state] : undefined;
         return registry.archiveByPolicy({
@@ -253,8 +254,8 @@ function historyCli(options = {}) {
         scope: scopeOf(options, "home"),
         app: optionalString(options.app),
         status: optionalString(options.status),
-        limit: options.limit === undefined ? undefined : Number(options.limit),
-        offset: options.offset === undefined ? undefined : Number(options.offset),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
+        offset: (0, numeric_flag_1.requiredNumberFlag)(options.offset, "--offset"),
     });
 }
 function queueAddCli(options = {}) {
@@ -263,7 +264,7 @@ function queueAddCli(options = {}) {
         appId: optionalString(options.app || options.appId),
         workflowId: optionalString(options.workflow || options.workflowId),
         repo: optionalString(options.repo),
-        priority: options.priority === undefined ? undefined : Number(options.priority),
+        priority: (0, numeric_flag_1.requiredNumberFlag)(options.priority, "--priority"),
         note: optionalString(options.note),
         id: optionalString(options.id),
     });
@@ -276,7 +277,7 @@ function queueShowCli(id, options = {}) {
 }
 function queueDrainCli(options = {}) {
     return new run_registry_io_1.RunRegistry(resolveCwd(options)).queueDrain({
-        limit: options.limit === undefined ? undefined : Number(options.limit),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
         repo: optionalString(options.repo),
     });
 }
@@ -285,8 +286,9 @@ function queueDrainCli(options = {}) {
 // ---------------------------------------------------------------------
 function gcPolicyOverridesFrom(options) {
     const overrides = {};
-    if (options.reclaimAfterArchiveDays !== undefined)
-        overrides.reclaimAfterArchiveDays = Number(options.reclaimAfterArchiveDays);
+    const reclaimAfterArchiveDays = (0, numeric_flag_1.requiredNumberFlag)(options.reclaimAfterArchiveDays, "--reclaimAfterArchiveDays");
+    if (reclaimAfterArchiveDays !== undefined)
+        overrides.reclaimAfterArchiveDays = reclaimAfterArchiveDays;
     if (options.keepScratch !== undefined)
         overrides.keepScratch = Boolean(options.keepScratch);
     if (options["keep-scratch"] !== undefined)
@@ -295,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;
@@ -316,7 +322,7 @@ function gcRunCli(runId, options = {}) {
         policy: gcPolicyOverridesFrom(options),
         now: optionalString(options.now),
         actor: optionalString(options.actor),
-        limit: options.limit === undefined ? undefined : Number(options.limit),
+        limit: (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit"),
     });
 }
 function gcVerifyCli(runId, options = {}) {
@@ -331,7 +337,7 @@ function orphansGcCli(options = {}) {
     const registry = new run_registry_io_1.RunRegistry(resolveCwd(options));
     return (0, reclamation_io_1.gcOrphanRuns)(registry, {
         scope: scopeOf(options, "home"),
-        minAgeMinutes: options.minAgeMinutes !== undefined ? Number(options.minAgeMinutes) : options["min-age-minutes"] !== undefined ? Number(options["min-age-minutes"]) : undefined,
+        minAgeMinutes: (0, numeric_flag_1.requiredNumberFlag)(options.minAgeMinutes ?? options["min-age-minutes"], "--min-age-minutes"),
         all: Boolean(options.all),
         now: optionalString(options.now),
     });

package/dist/shell/remote-source.js

@@ -310,9 +310,12 @@ function fetchArchiveBytes(rawUrl, sanitizedUrl, dest, opts) {
 }
 /** List an archive's entry NAMES WITHOUT extracting (the zip-slip/tar-slip name guard runs on
  *  this). Symlinks/specials and decompression bombs are caught separately (below). */
-function listArchive(file, isZip) {
+function listArchive(file, isZip, timeoutMs) {
     const cmd = isZip ? ["unzip", "-Z1", "--", file] : ["tar", "-tf", file];
-    const result = (0, node_child_process_1.spawnSync)(cmd[0], cmd.slice(1), { encoding: "utf8" });
+    // Same unset-timeout hazard as a hung local/container task (post-v0.2.2
+    // robustness hardening): a pathological archive must not hang the CLI
+    // forever with no kill path. Matches git()'s own fallback below.
+    const result = (0, node_child_process_1.spawnSync)(cmd[0], cmd.slice(1), { encoding: "utf8", timeout: timeoutMs || 120000 });
     if (result.status !== 0) {
         // Distinguish "unzip not installed" (ENOENT) from "archive is corrupt" — never conflate the
         // two (a corrupt .tar mislabeled .zip used to surface a bogus "unzip not found").
@@ -338,10 +341,10 @@ function assertNoTraversal(entries, sanitizedUrl) {
 /** Declared uncompressed size, read WITHOUT extracting — gzip's ISIZE trailer for `.tar.gz`/
  *  `.tgz`, or `unzip -l`'s total for `.zip`. Best-effort (undefined when unknown); the
  *  post-extraction walk is authoritative. Lets us reject a bomb BEFORE it fills the disk. */
-function declaredUncompressedSize(file, isZip) {
+function declaredUncompressedSize(file, isZip, timeoutMs) {
     try {
         if (isZip) {
-            const r = (0, node_child_process_1.spawnSync)("unzip", ["-l", "--", file], { encoding: "utf8" });
+            const r = (0, node_child_process_1.spawnSync)("unzip", ["-l", "--", file], { encoding: "utf8", timeout: timeoutMs || 120000 });
             if (r.status !== 0)
                 return undefined;
             const lines = String(r.stdout || "").trim().split(/\r?\n/);
@@ -421,15 +424,17 @@ function downloadArchive(rawUrl, sanitizedUrl, opts) {
         const commit = (0, node_crypto_1.createHash)("sha256").update(node_fs_1.default.readFileSync(tmpFile)).digest("hex"); // content address
         // Bomb defense (BEFORE extracting, to avoid filling the disk): reject a declared
         // uncompressed size over the cap. assertSafeTree re-checks the ACTUAL size afterward.
-        const declared = declaredUncompressedSize(tmpFile, isZip);
+        const declared = declaredUncompressedSize(tmpFile, isZip, opts.timeoutMs);
         if (declared !== undefined && declared > MAX_EXTRACTED_BYTES) {
             throw new Error(`refusing archive ${sanitizedUrl}: declared uncompressed size ${declared} exceeds ${MAX_EXTRACTED_BYTES} bytes (possible decompression bomb)`);
         }
-        assertNoTraversal(listArchive(tmpFile, isZip), sanitizedUrl);
+        assertNoTraversal(listArchive(tmpFile, isZip, opts.timeoutMs), sanitizedUrl);
         const extractDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(staging, "x-"));
+        // Same unset-timeout hazard as above: extraction runs on downloaded,
+        // attacker-influenced bytes and must not hang forever.
         const ex = isZip
-            ? (0, node_child_process_1.spawnSync)("unzip", ["-q", "-o", "-d", extractDir, "--", tmpFile], { encoding: "utf8" })
-            : (0, node_child_process_1.spawnSync)("tar", ["-xf", tmpFile, "-C", extractDir], { encoding: "utf8" });
+            ? (0, node_child_process_1.spawnSync)("unzip", ["-q", "-o", "-d", extractDir, "--", tmpFile], { encoding: "utf8", timeout: opts.timeoutMs || 120000 })
+            : (0, node_child_process_1.spawnSync)("tar", ["-xf", tmpFile, "-C", extractDir], { encoding: "utf8", timeout: opts.timeoutMs || 120000 });
         if (ex.status !== 0)
             throw new Error(`could not extract archive ${sanitizedUrl}: ${String(ex.stderr || "").trim() || `exit ${ex.status}`}`);
         // Fail closed on symlinks/specials and on an over-cap actual extracted size.