cool-workflow 0.2.1 → 0.2.3

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)
@@ -316,7 +318,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 +333,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.

package/dist/shell/report-cli.js

@@ -43,9 +43,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportBundleCli = reportBundleCli;
 exports.reportVerifyBundleCli = reportVerifyBundleCli;
+exports.formatReportVerifyBundle = formatReportVerifyBundle;
 const path = __importStar(require("node:path"));
 const run_export_1 = require("./run-export");
 const run_store_1 = require("./run-store");
+const term_1 = require("./term");
 function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
@@ -99,3 +101,46 @@ function reportVerifyBundleCli(args) {
         requireSignatures: Boolean(args["require-signatures"] || args.requireSignatures || args.requireSigs),
     });
 }
+/** `cw report verify-bundle`'s human render (default; `--json` prints
+ *  `ReportBundleVerification` verbatim instead). Mirrors `doctor`'s
+ *  checks-list-then-verdict shape (`shell/doctor.ts`'s
+ *  `formatDoctorReport`) rather than `demo bundle`'s narrative one
+ *  (`shell/telemetry-demo.ts`'s `formatBundleDemo`) — verify-bundle is a
+ *  flat set of pass/fail checks on one already-sealed archive, not a
+ *  multi-step forge-and-catch demonstration. */
+function formatReportVerifyBundle(r) {
+    const lines = [(0, term_1.bold)(`cw report verify-bundle ${r.archivePath}`), ""];
+    const checks = [
+        [r.archiveOk, "archive intact — file digests match, no tamper"],
+        [r.telemetryVerified, "telemetry hash chain verifies"],
+        [r.trustAuditVerified, "trust-audit chain verifies"],
+        [r.reportFindingsVerified, "report.md matches every signed result"],
+    ];
+    for (const [ok, label] of checks)
+        lines.push(`  ${(0, term_1.doctorGlyph)(ok ? "ok" : "fail")} ${label}`);
+    const sigDetail = r.signatureKeyProvided
+        ? `${r.signaturesReverified}/${r.signaturesChecked} signature(s) reverified (key source: ${r.trustKeySource})`
+        : "no public key available — signatures not checked";
+    lines.push(`  trust: ${r.trustLevel} — ${sigDetail}`);
+    if (r.reportExtractedTo)
+        lines.push(`  report.md extracted to: ${r.reportExtractedTo}`);
+    if (r.failedChecks.length > 0) {
+        lines.push("");
+        lines.push("  Failed checks");
+        for (const c of r.failedChecks) {
+            // Most check sites in run-export.ts's verifyReportBundle set `code`
+            // to a short slug (e.g. "digest-mismatch"); the top-level restore
+            // catch-all sets it to the caught error's full message instead
+            // (run-export.ts's "restore" failedChecks.push) — too long/sentence-
+            // shaped to cram into "name [code]" without reading as a run-on.
+            // Give it its own indented line instead.
+            const isSlug = c.code !== undefined && c.code.length <= 40 && !c.code.includes(" ");
+            lines.push(`    - ${c.name}${isSlug ? ` [${c.code}]` : ""}`);
+            if (c.code !== undefined && !isSlug)
+                lines.push(`      ${c.code}`);
+        }
+    }
+    lines.push("");
+    lines.push(`${(0, term_1.doctorGlyph)(r.ok ? "ok" : "fail")} ${r.ok ? "bundle verifies" : "bundle verification FAILED"}`);
+    return lines.join("\n");
+}

package/dist/shell/report.js

@@ -59,13 +59,14 @@ const telemetry_ledger_io_1 = require("./telemetry-ledger-io");
 const multi_agent_io_1 = require("./multi-agent-io");
 const coordinator_io_1 = require("./coordinator-io");
 const multi_agent_operator_ux_1 = require("./multi-agent-operator-ux");
+const collate_1 = require("../core/util/collate");
 function formatInputList(value) {
     if (Array.isArray(value))
         return value.join("; ");
     return value ? String(value) : "";
 }
 function formatCounts(counts) {
-    const entries = Object.entries(counts).sort(([a], [b]) => a.localeCompare(b));
+    const entries = Object.entries(counts).sort(([a], [b]) => (0, collate_1.stableCompare)(a, b));
     if (!entries.length)
         return "none";
     return entries.map(([k, v]) => `${k}=${v}`).join(", ");
@@ -337,7 +338,8 @@ function writeReport(run) {
         "| Phase | Status | Completed | Total |",
         "| --- | --- | ---: | ---: |",
         ...run.phases.map((phase) => {
-            const phaseTasks = run.tasks.filter((t) => phase.taskIds.includes(t.id));
+            const taskIds = new Set(phase.taskIds);
+            const phaseTasks = run.tasks.filter((t) => taskIds.has(t.id));
             const completed = phaseTasks.filter((t) => t.status === "completed").length;
             return `| ${phase.name} | ${phase.status} | ${completed} | ${phaseTasks.length} |`;
         }),

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

@@ -207,10 +207,25 @@ function clampInt(value, fallback, min) {
     return Math.max(min, Math.floor(n));
 }
 let queueCounter = 0;
-function queueId() {
-    queueCounter += 1;
+/** Byte format is `q-${stamp14}-${NNN}` (SPEC/scheduling-registry.md "Id
+ *  formats"), unchanged. `queueCounter` alone is not enough to keep ids
+ *  unique: it resets to 0 for every fresh `cw` process, so two SEPARATE
+ *  processes calling `queue add` within the same second both compute
+ *  `queueCounter === 1` and mint the IDENTICAL id — `sched lease` then
+ *  keys grants by id, so both queue entries get treated as one, breaking
+ *  through `maxConcurrent`. `existingIds` is the current queue file's ids
+ *  (read inside queueAdd's own file lock, so this sees every entry any
+ *  earlier-completed `queue add` — same process or not — has already
+ *  saved); bumping past any collision against that real, shared state
+ *  keeps ids unique across processes without changing the format. */
+function queueId(existingIds) {
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
-    return `q-${stamp}-${String(queueCounter).padStart(3, "0")}`;
+    let candidate;
+    do {
+        queueCounter += 1;
+        candidate = `q-${stamp}-${String(queueCounter).padStart(3, "0")}`;
+    } while (existingIds && existingIds.has(candidate));
+    return candidate;
 }
 function isRunLifecycleState(value) {
     return (typeof value === "string" &&
@@ -397,7 +412,7 @@ class RunRegistry {
             const entries = this.loadQueueEntries();
             const entry = {
                 schemaVersion: 1,
-                id: options.id || queueId(),
+                id: options.id || queueId(new Set(entries.map((e) => e.id))),
                 runId: options.runId,
                 appId: options.appId,
                 workflowId: options.workflowId,
@@ -462,6 +477,13 @@ class RunRegistry {
             const result = (0, run_store_1.loadRunStateFile)(statePath, { dryRun: true });
             if (result.report.status === "unsupported")
                 return null;
+            // Bulk scans (refreshRegistry, below) call deriveRecord directly and
+            // tolerate a null the same way as missing/unsupported — one bad run
+            // must not stop a listing of everything else. Single-run lookups
+            // (deriveRecordForRun, below) re-check this same condition WITHOUT
+            // swallowing it, so `cw run show`/`archive`/`rerun` on THIS run
+            // specifically get a clear reason instead of a misleading "not found."
+            (0, run_store_1.assertNotSuspectedDataLoss)(path.basename(runDir), result);
             run = result.run;
         }
         catch {
@@ -609,7 +631,7 @@ class RunRegistry {
             if (staleRuns.length || missingRuns.length)
                 status = "stale";
         }
-        const refreshCmd = scope === "home" ? "node scripts/cw.js registry refresh --scope home" : "node scripts/cw.js registry refresh";
+        const refreshCmd = scope === "home" ? "cw registry refresh --scope home" : "cw registry refresh";
         return {
             schemaVersion: 1,
             scope,
@@ -624,7 +646,7 @@ class RunRegistry {
             },
             index: current,
             counts: current.counts,
-            nextAction: status === "valid" ? "node scripts/cw.js run search" : refreshCmd,
+            nextAction: status === "valid" ? "cw run search" : refreshCmd,
         };
     }
     search(raw = {}) {
@@ -657,7 +679,7 @@ class RunRegistry {
             offset: query.offset,
             limit: query.limit,
             records: page,
-            nextAction: report.freshness.status === "valid" ? "node scripts/cw.js run show <run-id>" : "node scripts/cw.js registry refresh",
+            nextAction: report.freshness.status === "valid" ? "cw run show <run-id>" : "cw registry refresh",
         };
     }
     list(options = {}) {
@@ -680,7 +702,7 @@ class RunRegistry {
                 resolvedFrom: located.from,
                 repo: located.record.repo,
                 record: located.record,
-                nextAction: located.record.archived ? "node scripts/cw.js run resume " + runId : "node scripts/cw.js run show " + runId,
+                nextAction: located.record.archived ? "cw run resume " + runId : "cw run show " + runId,
             };
         }
         const persisted = this.findPersisted(runId, scope);
@@ -691,10 +713,11 @@ class RunRegistry {
             freshness: "missing",
             repo: persisted?.repo,
             persisted,
-            nextAction: "node scripts/cw.js registry refresh" + (scope === "home" ? " --scope home" : ""),
+            nextAction: "cw registry refresh" + (scope === "home" ? " --scope home" : ""),
         };
     }
     locate(runId, scope) {
+        (0, fs_atomic_1.assertSafeRunId)(runId);
         const here = this.deriveRecordForRun(this.repoRoot, runId);
         if (here)
             return { record: here, from: "repo" };
@@ -711,9 +734,35 @@ class RunRegistry {
     }
     deriveRecordForRun(repo, runId) {
         const runDir = path.join(this.repoRunsDir(repo), runId);
-        if (!fs.existsSync(path.join(runDir, "state.json")))
+        const statePath = path.join(runDir, "state.json");
+        if (!fs.existsSync(statePath))
             return null;
-        return this.deriveRecord(repo, runDir);
+        const record = this.deriveRecord(repo, runDir);
+        if (record)
+            return record;
+        // deriveRecord returned null even though state.json existed a moment
+        // ago: it failed to parse, was flagged unsupported, tripped
+        // suspected-data-loss corroboration, or (a narrow race) a concurrent
+        // process deleted it in between. Re-derive without swallowing so a
+        // genuine corruption reaches THIS single-run lookup (backing `cw run
+        // show`/`archive`/`rerun`) instead of the misleading "not found" a bulk
+        // scan is content with — but if the file is ACTUALLY gone by the time
+        // we check again, that is genuinely missing, not corrupt, and must
+        // resolve to null like everywhere else, never a raw "File not found"
+        // exception surfacing from this fallback re-read.
+        try {
+            const result = (0, run_store_1.loadRunStateFile)(statePath, { dryRun: true });
+            if (result.report.status === "unsupported") {
+                throw new Error(`Run state for ${runId} is corrupt (fail closed): ${result.report.errors.join("; ") || "unsupported run state"}. Restore ${statePath} from a backup, or remove the run directory to start over.`);
+            }
+            (0, run_store_1.assertNotSuspectedDataLoss)(runId, result);
+            return record;
+        }
+        catch (error) {
+            if (!fs.existsSync(statePath))
+                return null;
+            throw error;
+        }
     }
     findPersisted(runId, scope) {
         for (const s of scope === "home" ? ["home", "repo"] : ["repo"]) {
@@ -725,6 +774,7 @@ class RunRegistry {
         return undefined;
     }
     loadRun(repo, runId) {
+        (0, fs_atomic_1.assertSafeRunId)(runId);
         const statePath = path.join(this.repoRunsDir(repo), runId, "state.json");
         if (!fs.existsSync(statePath))
             throw new Error(`Run not found: ${runId}`);
@@ -732,6 +782,7 @@ class RunRegistry {
         if (result.report.status === "unsupported") {
             throw new Error(`Unsupported run state for ${runId}: ${result.report.errors.join("; ")}`);
         }
+        (0, run_store_1.assertNotSuspectedDataLoss)(runId, result);
         return result.run;
     }
     resume(runId, options = {}) {
@@ -752,23 +803,23 @@ class RunRegistry {
         const nextActions = [];
         if (nextTasks.length) {
             nextActions.push({
-                command: `node scripts/cw.js dispatch ${runId} --cwd ${record.repo}`,
+                command: `cw dispatch ${runId} --cwd ${record.repo}`,
                 reason: `Continue ${nextTasks.length} pending/running task(s) from durable state.`,
             });
             nextActions.push({
-                command: `node scripts/cw.js multi-agent step ${runId} --cwd ${record.repo}`,
+                command: `cw multi-agent step ${runId} --cwd ${record.repo}`,
                 reason: "Take one deterministic host step without spawning agents.",
             });
         }
         else if (record.derivedLifecycle === "failed") {
             nextActions.push({
-                command: `node scripts/cw.js run rerun ${runId}`,
+                command: `cw run rerun ${runId}`,
                 reason: "Run terminated as failed with no runnable tasks; rerun as a new linked run.",
             });
         }
         else {
             nextActions.push({
-                command: `node scripts/cw.js status ${runId} --cwd ${record.repo} --json`,
+                command: `cw status ${runId} --cwd ${record.repo} --json`,
                 reason: "No runnable tasks remain; inspect status.",
             });
         }
@@ -807,7 +858,14 @@ class RunRegistry {
             }
             (0, fs_atomic_1.writeJson)(file, overlay, { durable: true });
         });
-        const record = this.deriveRecord(repo, located.record.runDir);
+        // deriveRecordForRun (not a bare deriveRecord(...)!) so a run that
+        // became corrupt/unsupported/suspected-data-loss in the narrow window
+        // between locate() above and this re-fetch gets the same clear,
+        // specific error every other single-run lookup gets, instead of a raw
+        // TypeError from a non-null assertion on a surprise null.
+        const record = this.deriveRecordForRun(repo, runId);
+        if (!record)
+            throw new Error(`Cannot archive: run ${runId} state became unavailable while archiving (fail closed).`);
         return {
             runId,
             repo,
@@ -877,8 +935,8 @@ class RunRegistry {
             pendingTasks: newRun.tasks.filter((t) => t.status === "pending").length,
             provenance,
             nextActions: [
-                { command: `node scripts/cw.js run resume ${newRun.id}`, reason: "Continue the new linked run." },
-                { command: `node scripts/cw.js run show ${runId}`, reason: "The original failed run is preserved for audit." },
+                { command: `cw run resume ${newRun.id}`, reason: "Continue the new linked run." },
+                { command: `cw run show ${runId}`, reason: "The original failed run is preserved for audit." },
             ],
         };
     }
@@ -918,7 +976,7 @@ class RunRegistry {
             limit,
             repos: index.repos,
             entries,
-            nextAction: report.freshness.status === "valid" ? "node scripts/cw.js run show <run-id>" : "node scripts/cw.js registry refresh --scope home",
+            nextAction: report.freshness.status === "valid" ? "cw run show <run-id>" : "cw registry refresh --scope home",
         };
     }
 }

package/dist/shell/run-store.js

@@ -49,7 +49,9 @@ exports.hashArtifactFile = hashArtifactFile;
 exports.loadRunStateFile = loadRunStateFile;
 exports.checkRunStateFile = checkRunStateFile;
 exports.migrateRunStateFile = migrateRunStateFile;
+exports.assertNotSuspectedDataLoss = assertNotSuspectedDataLoss;
 exports.loadRunFromCwd = loadRunFromCwd;
+exports.withRunStateLock = withRunStateLock;
 exports.saveCheckpoint = saveCheckpoint;
 exports.compactCheckpoint = compactCheckpoint;
 exports.createRun = createRun;
@@ -97,21 +99,108 @@ function migrateRunStateFile(statePath, options = {}) {
     }
     return result;
 }
+/** ONLY tasksDir/commitsDir (plus the audit event log, checked separately
+ *  below) — deliberately NOT every directory a run's `paths` can carry.
+ *  Verified empirically (via test/run-fixture-compat-smoke.js's real
+ *  fixtures) that several other candidate directories are unsafe signals:
+ *  a plain `cw status`/`cw graph` READ already writes cache/derived files
+ *  as a side effect — `audit/summary.json` + `audit/index.json`
+ *  (summarizeTrustAudit, called from the status/report path) are non-empty
+ *  the moment ANY read touches the run, and `blackboard/`/`candidates/`/
+ *  `topologies/` subdirectories get created (though left empty) the same
+ *  way. Using those as "real content" signals would refuse to load a
+ *  perfectly healthy, merely-already-viewed-once run — report.md is the
+ *  same story (a derived rendering of state, not independent evidence).
+ *  tasksDir/commitsDir are the two directories confirmed to hold content
+ *  ONLY from genuine task-dispatch/commit actions, never from an
+ *  otherwise-read-only command. */
+function contentDirs(paths) {
+    return [paths.tasksDir, paths.commitsDir];
+}
+/** True when the run directory already holds real task/commit files, or a
+ *  non-empty audit event log — i.e. this was NOT a brand-new run dir. Used
+ *  only to corroborate `report.suspectedDataLoss`: a bare
+ *  `{workflow, paths}`-less state.json is unremarkable for a run dir that
+ *  has nothing else in it either (e.g. a run whose creation crashed before
+ *  anything else was written), but is a strong corruption signal when real
+ *  content already sits next to it. A directory entry must not START WITH
+ *  "." to count — cw never writes dot-prefixed names into these
+ *  directories, so incidental filesystem debris (a stray `.DS_Store`) never
+ *  by itself makes a genuinely fresh run look corrupted. */
+function hasPreexistingRunContent(run) {
+    for (const dir of contentDirs(run.paths)) {
+        try {
+            if (fs.readdirSync(dir).some((name) => !name.startsWith(".")))
+                return true;
+        }
+        catch {
+            /* missing dir — not a signal either way */
+        }
+    }
+    try {
+        const eventLogPath = run.audit?.eventLogPath;
+        if (eventLogPath && fs.statSync(eventLogPath).size > 0)
+            return true;
+    }
+    catch {
+        /* missing/empty audit log — not a signal */
+    }
+    return false;
+}
+/** Throws when `result.report.suspectedDataLoss` is true AND the run
+ *  directory already has real content on disk — see
+ *  `hasPreexistingRunContent`. Shared by every state.json reader
+ *  (`loadRunFromCwd` here, `RunRegistry.loadRun` in run-registry-io.ts) so
+ *  a corrupted/wiped state.json is refused the same way regardless of
+ *  which entry point reached it. */
+function assertNotSuspectedDataLoss(runId, result) {
+    if (result.report.suspectedDataLoss && hasPreexistingRunContent(result.run)) {
+        throw new Error(`Refusing to load run ${runId}: state.json is missing its core fields (workflow, paths), but the run directory already has task, commit, or other content on disk. This looks like state.json was corrupted, truncated, or replaced by something outside cw, not a new run. Restore state.json from a backup, or remove the run directory to start over.`);
+    }
+}
 /** Refuses an empty id with `Missing run id`; loads
  *  `<cwd>/.cw/runs/<runId>/state.json` (dry-run — never writes); throws
- *  `Unsupported CW run state: <errors joined by "; ">` on an unsupported
- *  verdict; else returns the migrated WorkflowRun in memory. */
+ *  `Run not found: <runId>` when no such run directory has a state.json
+ *  (every caller — report, status, audit, eval snapshot, and more — used
+ *  to leak the raw `readJson` message, "File not found: <absolute
+ *  path>/state.json", which named neither the run nor a next step, and
+ *  didn't contain any of the words `cli/entry.ts`'s `recoveryHint` scans
+ *  for, so no `Try: cw run list` line ever appeared); throws `Unsupported
+ *  CW run state: <errors joined by "; ">` on an unsupported verdict;
+ *  refuses a state.json that lost its core fields (workflow, paths) while
+ *  the run dir still has real content next to it, rather than silently
+ *  returning it as a fresh empty run; else returns the migrated
+ *  WorkflowRun in memory. */
 function loadRunFromCwd(runId, cwd = process.cwd()) {
     if (!runId)
         throw new Error("Missing run id");
     (0, fs_atomic_1.assertSafeRunId)(runId);
     const statePath = path.join(cwd, ".cw", "runs", runId, "state.json");
+    if (!fs.existsSync(statePath))
+        throw new Error(`Run not found: ${runId}`);
     const result = loadRunStateFile(statePath, { dryRun: true });
     if (result.report.status === "unsupported") {
         throw new Error(`Unsupported CW run state: ${result.report.errors.join("; ")}`);
     }
+    assertNotSuspectedDataLoss(runId, result);
     return result.run;
 }
+/** Hold the state.json lock over a WHOLE load -> change -> save cycle.
+ *  A bare loadRunFromCwd + saveCheckpoint pair leaves a window where two
+ *  processes both load the same state and the later save silently drops
+ *  the earlier change (the same lost-update class PR #339 fixed for
+ *  queue.json / triggers.json). `fn` gets the run loaded UNDER the lock;
+ *  saveCheckpoint calls inside `fn` re-enter the same lock (withFileLock
+ *  is re-entrant in-process) and write exactly as before. The probe load
+ *  runs BEFORE the lock so an unknown run id throws the exact
+ *  loadRunFromCwd error without first creating the run directory as a
+ *  lock-file side effect — and it supplies `paths.state`, the same lock
+ *  target saveCheckpoint uses. Keep `fn` short: a critical section past
+ *  30s can be stolen as a stale lock. */
+function withRunStateLock(runId, cwd, fn) {
+    const probe = loadRunFromCwd(runId, cwd);
+    return (0, fs_atomic_1.withFileLock)(probe.paths.state, () => fn(loadRunFromCwd(runId, cwd)));
+}
 /** state.json is the single source of truth — set `updatedAt`, then write
  *  it DURABLY with a lock so concurrent processes never lose an update. */
 function saveCheckpoint(run) {

package/dist/shell/scheduling-io.js

@@ -67,6 +67,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const fs_atomic_1 = require("./fs-atomic");
 const run_registry_io_1 = require("./run-registry-io");
+const numeric_flag_1 = require("../core/util/numeric-flag");
 exports.SCHEDULING_SCHEMA_VERSION = 1;
 /** Conservative fail-closed defaults: serial, bounded retries, exponential backoff. */
 exports.DEFAULT_SCHEDULING_POLICY = {
@@ -232,14 +233,7 @@ function loadSchedulingPolicy(registry) {
     return { schemaVersion: 1, policy: normalizeSchedulingPolicy(parsed), source: "file" };
 }
 function numericFlag(options, key) {
-    if (!(key in options))
-        return undefined;
-    const raw = options[key];
-    const n = Number(raw);
-    if (!Number.isFinite(n)) {
-        throw new Error(`Invalid --${key} "${raw}": expected a number (e.g. --${key} 4)`);
-    }
-    return n;
+    return (0, numeric_flag_1.requiredNumberFlag)(options[key], `--${key}`);
 }
 function schedPlanCli(options = {}) {
     const registry = new run_registry_io_1.RunRegistry(resolveCwd(options));
@@ -250,7 +244,7 @@ function schedLeaseCli(options = {}) {
     const registry = new run_registry_io_1.RunRegistry(resolveCwd(options));
     const now = nowIso(options);
     const policy = loadSchedulingPolicy(registry).policy;
-    const limit = options.limit === undefined ? undefined : Number(options.limit);
+    const limit = (0, numeric_flag_1.requiredNumberFlag)(options.limit, "--limit");
     return (0, fs_atomic_1.withFileLock)(registry.queueFilePath(), () => {
         const { entries, leases } = applyLease(registry.loadQueueEntries(), policy, now, limit);
         registry.saveQueueEntries(entries);
@@ -305,16 +299,21 @@ function schedPolicyShowCli(options = {}) {
 }
 function schedPolicySetCli(options = {}) {
     const registry = new run_registry_io_1.RunRegistry(resolveCwd(options));
-    const current = loadSchedulingPolicy(registry).policy;
     const patch = {};
     for (const key of ["maxConcurrent", "maxAttempts", "leaseTtlMs", "backoffBaseMs", "backoffFactor", "backoffCapMs"]) {
         const value = numericFlag(options, key);
         if (value !== undefined)
             patch[key] = value;
     }
-    const policy = normalizeSchedulingPolicy({ ...current, ...patch });
-    (0, fs_atomic_1.writeJson)(registry.schedulingPolicyPath(), policy);
-    return { schemaVersion: 1, policy, source: "file" };
+    // Read-modify-write under the policy file's own lock: two concurrent
+    // `sched policy set` calls patching different fields must not drop each
+    // other's write.
+    return (0, fs_atomic_1.withFileLock)(registry.schedulingPolicyPath(), () => {
+        const current = loadSchedulingPolicy(registry).policy;
+        const policy = normalizeSchedulingPolicy({ ...current, ...patch });
+        (0, fs_atomic_1.writeJson)(registry.schedulingPolicyPath(), policy);
+        return { schemaVersion: 1, policy, source: "file" };
+    });
 }
 function isTrue(value) {
     return value === true || value === "true" || value === "1";