cool-workflow 0.2.3 → 0.2.5

package/dist/shell/reclamation-io.js

@@ -472,6 +472,32 @@ function planReclamation(run, policy = {}) {
             }
         }
     }
+    // (3) Superseded, non-verifier-gated commit snapshots. Each commitState()
+    // call writes only the commit's own small record into commits/<id>.json
+    // (not the whole run), but these files still add up over a long run 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. Treated as not reconstructable (no recipe)
+    // on purpose, kept conservative: a commit snapshot is not offered a
+    // projection path 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 +510,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 +629,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,12 +656,15 @@ 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) {
         try {
             const fresh = (0, node_store_1.snapshotNode)(run, nodeId, { persist: false });
-            const { freshness } = (0, node_snapshot_1.loadNodeSnapshot)(run, fresh);
+            const { freshness } = (0, node_snapshot_1.loadNodeSnapshot)(run, fresh, fs.existsSync);
             if (freshness === "absent") {
                 throw new ReclamationError("repoint-incomplete", `re-pointed node ${nodeId} snapshot is absent (dangling artifact)`, { nodeId });
             }
@@ -682,6 +728,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 +895,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 +939,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 +980,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 +1073,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-export.js

@@ -113,6 +113,17 @@ function importRun(exportPath, targetDir) {
     if (!(0, fs_atomic_1.isContainedPath)(runDir, runsRoot)) {
         throw new Error(`Run id escapes the runs directory: ${JSON.stringify(raw.run.id)}`);
     }
+    // Validate the run shape BEFORE the deref and before any dir/file is written.
+    // A truncated archive can be missing run.paths (or carry non-string
+    // runDir/cwd); without this guard the deref throws a raw TypeError, or a
+    // present-but-shapeless paths half-restores the run dir with a broken rebase.
+    // Fail closed as an invalid archive instead.
+    if (!raw.run.paths ||
+        typeof raw.run.paths !== "object" ||
+        typeof raw.run.paths.runDir !== "string" ||
+        typeof raw.run.cwd !== "string") {
+        throw new Error("Invalid run export: run.paths.runDir and run.cwd must be strings");
+    }
     const oldRunDir = raw.run.paths.runDir;
     const oldCwd = raw.run.cwd;
     const paths = (0, run_paths_1.createRunPaths)(runDir);
@@ -293,7 +304,7 @@ function reportSectionEmbedsResult(reportMd, taskId, expected) {
  *  (with the bundle's embedded public key) the ed25519 signatures.
  *  Never throws — every failure is a structured check and a false `ok`.
  *
- *  Key precedence is bundle > argument > environment. */
+ *  Key precedence is argument > bundle > environment. */
 function verifyReportBundle(archivePath, options = {}) {
     const inspect = inspectArchive(archivePath);
     const failedChecks = inspect.checks.filter((check) => !check.pass).map((check) => ({ name: check.name, code: check.code }));
@@ -333,8 +344,39 @@ function verifyReportBundle(archivePath, options = {}) {
     catch {
         /* inspect already recorded the parse failure; treat key as absent */
     }
-    const trustKeySource = bundleKey ? "bundle" : options.pubkey ? "argument" : process.env.CW_AGENT_ATTEST_PUBKEY ? "environment" : "none";
-    const trustKey = (0, telemetry_attestation_1.resolveTrustPublicKey)(bundleKey || options.pubkey || process.env.CW_AGENT_ATTEST_PUBKEY);
+    // Key precedence: an explicit operator --pubkey/options.pubkey WINS over a
+    // bundle-embedded key. A bundle carries its own key so it verifies OFFLINE,
+    // but that key must never OVERRIDE a key the operator pinned by hand — else a
+    // bundle re-signed with an attacker's OWN key (and embedding that key) would
+    // verify green against itself. When the operator pins a key AND the bundle
+    // embeds a DIFFERENT one, fail closed with a clear trust-key-mismatch rather
+    // than silently trusting the bundle's own key.
+    const resolvedArg = (0, telemetry_attestation_1.resolveTrustPublicKey)(options.pubkey);
+    const resolvedBundle = (0, telemetry_attestation_1.resolveTrustPublicKey)(bundleKey);
+    const resolvedEnv = (0, telemetry_attestation_1.resolveTrustPublicKey)(process.env.CW_AGENT_ATTEST_PUBKEY);
+    let trustKey;
+    let trustKeySource;
+    let trustKeyConflict = false;
+    if (options.pubkey) {
+        trustKey = resolvedArg;
+        trustKeySource = "argument";
+        if (resolvedArg && resolvedBundle && normalizePem(resolvedArg) !== normalizePem(resolvedBundle)) {
+            trustKeyConflict = true;
+            failedChecks.push({ name: "trust-key", code: "trust-key-mismatch" });
+        }
+    }
+    else if (bundleKey) {
+        trustKey = resolvedBundle;
+        trustKeySource = "bundle";
+    }
+    else if (process.env.CW_AGENT_ATTEST_PUBKEY) {
+        trustKey = resolvedEnv;
+        trustKeySource = "environment";
+    }
+    else {
+        trustKey = undefined;
+        trustKeySource = "none";
+    }
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cw-verify-bundle-"));
     let telemetryVerified = false;
     let trustAuditVerified = false;
@@ -421,7 +463,7 @@ function verifyReportBundle(archivePath, options = {}) {
         schemaVersion: 1,
         archivePath,
         runId: inspect.runId,
-        ok: inspect.ok && telemetryVerified && trustAuditVerified && signaturesFailed === 0 && reportFindingsOk && !strictShortfall && !extractShortfall && !unsignedShortfall,
+        ok: inspect.ok && telemetryVerified && trustAuditVerified && signaturesFailed === 0 && reportFindingsOk && !strictShortfall && !extractShortfall && !unsignedShortfall && !trustKeyConflict,
         archiveOk: inspect.ok,
         telemetryVerified,
         trustAuditVerified,
@@ -675,6 +717,12 @@ function toArchivePath(value) {
 function safeArchiveBasename(value) {
     return value.replace(/[^A-Za-z0-9._-]/g, "_") || "artifact";
 }
+/** Compare two PEM public keys byte-for-byte after dropping whitespace, so a
+ *  benign line-wrap or trailing-newline difference does not read as a key
+ *  change, but a truly different key (different base64 body) does. */
+function normalizePem(pem) {
+    return (pem || "").replace(/\s+/g, "");
+}
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }

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,
 };

package/dist/shell/run-store.js

@@ -51,7 +51,10 @@ exports.checkRunStateFile = checkRunStateFile;
 exports.migrateRunStateFile = migrateRunStateFile;
 exports.assertNotSuspectedDataLoss = assertNotSuspectedDataLoss;
 exports.loadRunFromCwd = loadRunFromCwd;
+exports.resolveRunDir = resolveRunDir;
 exports.withRunStateLock = withRunStateLock;
+exports.withDriveLock = withDriveLock;
+exports.withDriveLockAsync = withDriveLockAsync;
 exports.saveCheckpoint = saveCheckpoint;
 exports.compactCheckpoint = compactCheckpoint;
 exports.createRun = createRun;
@@ -185,6 +188,22 @@ function loadRunFromCwd(runId, cwd = process.cwd()) {
     assertNotSuspectedDataLoss(runId, result);
     return result.run;
 }
+/** The canonical run directory for `runId` under `cwd` — the SAME
+ *  deterministic location loadRunFromCwd resolves `state.json` in (it too
+ *  ignores any stored `paths.runDir`). Guards an empty/unsafe id and throws
+ *  the exact `Run not found: <runId>` loadRunFromCwd throws, but via a plain
+ *  `existsSync` so it adds no `state.json` READ and never creates the run dir
+ *  for a nonexistent run. Used by the drive mutex, which needs the directory
+ *  before it can acquire, without perturbing read accounting. */
+function resolveRunDir(runId, cwd = process.cwd()) {
+    if (!runId)
+        throw new Error("Missing run id");
+    (0, fs_atomic_1.assertSafeRunId)(runId);
+    const runDir = path.join(cwd, ".cw", "runs", runId);
+    if (!fs.existsSync(path.join(runDir, "state.json")))
+        throw new Error(`Run not found: ${runId}`);
+    return runDir;
+}
 /** 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
@@ -201,6 +220,143 @@ function withRunStateLock(runId, cwd, fn) {
     const probe = loadRunFromCwd(runId, cwd);
     return (0, fs_atomic_1.withFileLock)(probe.paths.state, () => fn(loadRunFromCwd(runId, cwd)));
 }
+// ---------------------------------------------------------------------------
+// withDriveLock — a run-scoped DRIVE mutex, held across a WHOLE drive() call.
+//
+// The state.json write lock (withFileLock) covers only the instant of a
+// write; a concurrent round loads the run once, spawns agents for MINUTES,
+// then flushes the object it loaded at round start. A second drive on the
+// same run therefore clobbers this one's flush (lost update) and both drives
+// mint the same worker id from an in-memory count (double dispatch). This
+// mutex closes both: only one process advances a run at a time.
+//
+// It is held far too long for withFileLock's 30s stale-steal window, so it is
+// NEVER time-stale-stolen. A lock whose recorded pid is a LIVE process refuses
+// (fail closed — never a silent double-drive); a lock whose owner is GONE (a
+// crashed prior drive) or this process's own leaked lock is stolen so a crash
+// can never wedge the run. Lock body is `"<pid>@<ISO>\n"`, the same shape as
+// the fs-atomic lock, acquired with the same single-winner `link(2)` idiom.
+// ---------------------------------------------------------------------------
+/** Drive-lock paths this process holds right now. A nested drive() on the
+ *  SAME run id (sub-workflows use a DIFFERENT run id, so this should not
+ *  happen — defensive) re-enters instead of self-refusing. */
+const HELD_DRIVE_LOCKS = new Set();
+function driveLockPath(runDir) {
+    return path.join(runDir, "drive.lock");
+}
+/** True when `pid` names a live process on this machine. `process.kill(pid,
+ *  0)` delivers no signal — it only probes existence/permission. `EPERM` (the
+ *  pid exists but is not signalable by us) counts as ALIVE, the conservative
+ *  never-wrongly-steal direction; a malformed/absent pid is "not alive". */
+function driveLockOwnerAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return Boolean(error && typeof error === "object" && error.code === "EPERM");
+    }
+}
+function readDriveLockPid(lock) {
+    try {
+        const match = /^(\d+)@/.exec(fs.readFileSync(lock, "utf8"));
+        return match ? Number(match[1]) : 0;
+    }
+    catch {
+        return 0; // vanished or unreadable — treat as no owner
+    }
+}
+/** Acquire the drive mutex for `runId`'s run directory. Returns a release
+ *  function (a no-op when this call re-entered a lock already held in-process).
+ *  Throws a fail-closed refusal — naming the resume command — when another
+ *  LIVE process holds it. */
+function acquireDriveLock(runDir, runId) {
+    const lock = driveLockPath(runDir);
+    const key = path.resolve(lock);
+    if (HELD_DRIVE_LOCKS.has(key))
+        return () => { };
+    fs.mkdirSync(runDir, { recursive: true });
+    const pid = process.pid;
+    const body = `${pid}@${new Date().toISOString()}\n`;
+    const refuse = (ownerPid) => new Error(`Run ${runId} is already being driven by another process (pid ${ownerPid || "unknown"}). ` +
+        `Wait for it to finish, or if it has crashed remove ${lock}, then resume: cw run resume ${runId} --drive`);
+    let acquired = false;
+    // A live owner refuses at once; only a stealable (dead-owner / own-leak) lock
+    // loops to re-acquire, so this never hot-spins for a genuinely busy run.
+    for (let attempt = 0; attempt < 3 && !acquired; attempt++) {
+        const tmp = `${lock}.${pid}.${attempt}.tmp`;
+        try {
+            fs.writeFileSync(tmp, body, { mode: 0o600 });
+            fs.linkSync(tmp, lock);
+            acquired = true;
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && error.code === "EEXIST")) {
+                throw error;
+            }
+            const ownerPid = readDriveLockPid(lock);
+            // Stealable: our own leaked lock, or an owner that is no longer alive.
+            if (ownerPid === pid || !driveLockOwnerAlive(ownerPid)) {
+                try {
+                    fs.unlinkSync(lock);
+                }
+                catch {
+                    /* another process took it first — the next attempt re-judges */
+                }
+                continue;
+            }
+            throw refuse(ownerPid);
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* the link consumed it, or it is already gone */
+            }
+        }
+    }
+    if (!acquired)
+        throw refuse(readDriveLockPid(lock));
+    HELD_DRIVE_LOCKS.add(key);
+    return () => {
+        HELD_DRIVE_LOCKS.delete(key);
+        try {
+            // Release only while we still own it (a force-stale steal by a later
+            // process must not have its lock removed by us).
+            if (fs.readFileSync(lock, "utf8").startsWith(`${pid}@`))
+                fs.rmSync(lock, { force: true });
+        }
+        catch {
+            /* already released/removed */
+        }
+    };
+}
+/** Run `fn` while holding the run-scoped drive mutex (see the block comment
+ *  above); always released, even on throw. Synchronous callers (drive()). */
+function withDriveLock(runDir, runId, fn) {
+    const release = acquireDriveLock(runDir, runId);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}
+/** Async form of `withDriveLock` — releases only AFTER `fn`'s promise
+ *  settles, so driveAsync()'s awaited multi-round loop stays inside the lock
+ *  for its whole lifetime. */
+async function withDriveLockAsync(runDir, runId, fn) {
+    const release = acquireDriveLock(runDir, runId);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
 /** 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/scheduler-io.js

@@ -74,12 +74,18 @@ class Scheduler {
     create(options) {
         const kind = normalizeKind(options.kind);
         const now = new Date();
-        const intervalMinutes = numberOption(options.intervalMinutes || options.interval);
+        // Fail closed on a bad number rather than silently clamping a typo into a
+        // runaway: interval is a whole number of 0 or more (0 = due now, a real
+        // supported value), maxRuns a whole number more than 0, jitter/delay 0 or
+        // more, ttlDays more than 0. Use `??` (not `||`) when picking the option so
+        // an explicit 0 is kept -- for interval a valid "due now", not swallowed
+        // into the default 1; for the others kept and then rejected.
+        const intervalMinutes = requireNonNegativeInt(options.intervalMinutes ?? options.interval, "interval");
         const cron = stringOption(options.cron);
-        const delayMinutes = numberOption(options.delayMinutes || options.delay);
-        const jitterSeconds = numberOption(options.jitterSeconds) ?? 0;
+        const delayMinutes = requireNonNegative(options.delayMinutes ?? options.delay, "delay");
+        const jitterSeconds = requireNonNegative(options.jitterSeconds, "jitterSeconds") ?? 0;
         const nextRunAt = computeInitialNextRunAt({ kind, now, intervalMinutes, cron, delayMinutes, jitterSeconds });
-        const ttlDays = numberOption(options.ttlDays) ?? DEFAULT_TTL_DAYS;
+        const ttlDays = requirePositive(options.ttlDays, "ttlDays") ?? DEFAULT_TTL_DAYS;
         const task = {
             id: createScheduleId(kind),
             kind,
@@ -95,7 +101,7 @@ class Scheduler {
             intervalMinutes,
             cron,
             jitterSeconds,
-            maxRuns: numberOption(options.maxRuns),
+            maxRuns: requirePositiveInt(options.maxRuns, "maxRuns"),
             runCount: 0,
         };
         return this.locked(() => {
@@ -125,7 +131,7 @@ class Scheduler {
         const store = this.load();
         let changed = false;
         for (const task of store.tasks) {
-            if (task.status === "active" && new Date(task.expiresAt).getTime() <= now.getTime()) {
+            if (task.status === "active" && reachedBy(task.expiresAt, now)) {
                 task.status = "expired";
                 task.updatedAt = now.toISOString();
                 changed = true;
@@ -133,7 +139,7 @@ class Scheduler {
         }
         if (changed)
             this.save(store);
-        const dueTasks = store.tasks.filter((task) => task.status === "active" && new Date(task.nextRunAt).getTime() <= now.getTime());
+        const dueTasks = store.tasks.filter((task) => task.status === "active" && reachedBy(task.nextRunAt, now));
         if (dueTasks.length) {
             for (const task of dueTasks) {
                 const alreadyRecorded = task.lastDueAt && new Date(task.lastDueAt).getTime() >= new Date(task.nextRunAt).getTime();
@@ -219,6 +225,7 @@ class Scheduler {
         if (!fs.existsSync(this.storePath))
             return { schemaVersion: 1, tasks: [], history: [] };
         const value = (0, fs_atomic_1.readJson)(this.storePath);
+        ensureKnownSchemaVersion(value, "schedule");
         return {
             schemaVersion: 1,
             tasks: Array.isArray(value.tasks) ? value.tasks : [],
@@ -353,6 +360,64 @@ function numberOption(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+// Number guards for create(): an absent option (undefined/null/bare flag) is
+// left undefined for the caller's default; a GIVEN option that is out of
+// bounds throws a clear, named refusal (fail closed) instead of being clamped.
+function requirePositiveInt(value, name) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a whole number more than 0`);
+    }
+    return parsed;
+}
+// interval only: a whole number of 0 or more. 0 means "due now" (nextRunAt is
+// this moment) and is a real, supported value, so it must pass; a negative or
+// non-whole interval is the typo we fail closed on.
+function requireNonNegativeInt(value, name) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a whole number of 0 or more`);
+    }
+    return parsed;
+}
+function requirePositive(value, name) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a number more than 0`);
+    }
+    return parsed;
+}
+function requireNonNegative(value, name) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a number of 0 or more`);
+    }
+    return parsed;
+}
+// Fail closed on a store written by a newer/unknown runtime: forcing it to v1
+// would silently drop fields it does not understand. A missing schemaVersion is
+// treated as legacy v1 for backward tolerance.
+function ensureKnownSchemaVersion(value, store) {
+    const version = value.schemaVersion;
+    if (version !== undefined && version !== 1) {
+        throw new Error(`Unsupported ${store} store schemaVersion: ${String(version)}`);
+    }
+}
+// A stored date that parses to NaN is corrupt. `NaN <= now` is false, which
+// would make such a task silently never fire and never expire; fail closed by
+// treating a corrupt date as already reached (due / expired), never inert.
+function reachedBy(iso, now) {
+    const at = new Date(iso).getTime();
+    return Number.isNaN(at) || at <= now.getTime();
+}
 class DesktopSchedulerDaemon {
     cwd;
     intervalSeconds;
@@ -369,11 +434,36 @@ class DesktopSchedulerDaemon {
         (0, fs_atomic_1.writeJson)(inboxPath, { schemaVersion: 1, checkedAt, due });
         return { checkedAt, dueCount: due.length, dueIds: due.map((task) => task.id), inboxPath };
     }
+    /** One tick, guarded. A long-running daemon must survive a transient
+     *  failure — chiefly file-lock contention when a concurrent `cw schedule`
+     *  command holds tasks.json (withFileLock gives up after ~6s). Returns
+     *  true to keep going, false to stop the daemon cleanly.
+     *  - lock contention → warn to STDERR (stdout stays pure NDJSON), keep going;
+     *  - any other error (e.g. a corrupt tasks.json) → one `cw:` line + stop,
+     *    a clean fail-closed shutdown instead of a raw stack dump. */
+    safeTick() {
+        try {
+            process.stdout.write(`${JSON.stringify(this.tick())}\n`);
+            return true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/could not acquire file lock/i.test(message)) {
+                process.stderr.write(`cw: schedule daemon: skipped a tick (${message})\n`);
+                return true;
+            }
+            process.stderr.write(`cw: ${message}\n`);
+            process.exitCode = 1;
+            return false;
+        }
+    }
     async run() {
         fs.mkdirSync(path.join(this.cwd, ".cw", "schedules"), { recursive: true });
-        process.stdout.write(`${JSON.stringify(this.tick())}\n`);
-        setInterval(() => {
-            process.stdout.write(`${JSON.stringify(this.tick())}\n`);
+        if (!this.safeTick())
+            return;
+        const timer = setInterval(() => {
+            if (!this.safeTick())
+                clearInterval(timer);
         }, Math.max(1, this.intervalSeconds) * 1000);
     }
 }
@@ -465,6 +555,7 @@ class RoutineTriggerBridge {
         if (!fs.existsSync(this.storePath))
             return { schemaVersion: 1, triggers: [], events: [], nextTriggerSeq: 0 };
         const value = (0, fs_atomic_1.readJson)(this.storePath);
+        ensureKnownSchemaVersion(value, "routine");
         const triggers = Array.isArray(value.triggers) ? value.triggers : [];
         const maxExisting = triggers.reduce((max, trigger) => {
             const n = Number((String(trigger.id).match(/(\d+)$/) || [])[1] || 0);