cool-workflow 0.2.4 → 0.2.6

package/dist/shell/run-store.js

@@ -44,14 +44,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureRunDirs = exports.createRunPaths = void 0;
+exports.createRunPaths = void 0;
+exports.ensureRunDirs = ensureRunDirs;
 exports.hashArtifactFile = hashArtifactFile;
 exports.loadRunStateFile = loadRunStateFile;
 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;
@@ -60,9 +64,32 @@ const path = __importStar(require("node:path"));
 const fs_atomic_1 = require("./fs-atomic");
 const run_paths_1 = require("../core/state/run-paths");
 Object.defineProperty(exports, "createRunPaths", { enumerable: true, get: function () { return run_paths_1.createRunPaths; } });
-Object.defineProperty(exports, "ensureRunDirs", { enumerable: true, get: function () { return run_paths_1.ensureRunDirs; } });
 const migrations_1 = require("../core/state/migrations");
 const hash_1 = require("../core/hash");
+/** `mkdirSync` (recursive) every dir this run needs. Missing optional dir
+ *  fields fall back to `path.join(runDir, "<name>")`, matching the old
+ *  build's defensive default (a RunPaths loaded from an old/partial
+ *  state.json may be missing an optional key). */
+function ensureRunDirs(paths) {
+    const dirs = [
+        paths.runDir,
+        paths.tasksDir,
+        paths.resultsDir,
+        paths.dispatchesDir,
+        paths.artifactsDir,
+        paths.commitsDir,
+        paths.stateNodesDir,
+        paths.feedbackDir,
+        paths.auditDir || path.join(paths.runDir, "audit"),
+        paths.workersDir || path.join(paths.runDir, "workers"),
+        paths.candidatesDir || path.join(paths.runDir, "candidates"),
+        paths.multiAgentDir || path.join(paths.runDir, "multi-agent"),
+        paths.blackboardDir || path.join(paths.runDir, "blackboard"),
+        paths.topologiesDir || path.join(paths.runDir, "topologies"),
+    ];
+    for (const dir of dirs)
+        fs.mkdirSync(dir, { recursive: true });
+}
 /** Read the file at artifact.path and stamp sha256 (the core `sha256:`+hex
  *  form) + sizeBytes onto the StateArtifact. A missing/unreadable file is
  *  silently skipped so hashing an absent artifact never throws. Byte-exact
@@ -185,6 +212,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 +244,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) {
@@ -237,7 +417,7 @@ function compactCheckpoint(run) {
  *  same primitive. */
 function createRun(runDir, runId, workflowId, cwd) {
     const paths = (0, run_paths_1.createRunPaths)(runDir);
-    (0, run_paths_1.ensureRunDirs)(paths);
+    ensureRunDirs(paths);
     const seed = {
         id: runId,
         cwd,

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);

package/dist/shell/state-explosion-cli.js

@@ -176,7 +176,10 @@ function showStateExplosionSummary(run, options = {}) {
 // ---------------------------------------------------------------------
 function loadRun(runId, options = {}) {
     const cwd = options.cwd ? path.resolve(String(options.cwd)) : process.cwd();
-    return (0, run_store_1.loadRunFromCwd)(runId, cwd);
+    const run = (0, run_store_1.loadRunFromCwd)(runId, cwd);
+    if (options.__cwWorkbenchReadOnlyProjection === true)
+        run.__cwWorkbenchReadOnlyProjection = true;
+    return run;
 }
 /** `cw summary refresh <run-id> [--json]` — refresh also runs `writeReport`
  *  + `saveCheckpoint` in the old build; `writeReport` (report.md) is a

package/dist/shell/telemetry-demo.js

@@ -219,7 +219,7 @@ function runBundleDemo(options = {}) {
     const runId = "demo-bundle-run";
     const runDir = path.join(workdir, ".cw", "runs", runId);
     const paths = (0, run_paths_1.createRunPaths)(runDir);
-    (0, run_paths_1.ensureRunDirs)(paths);
+    (0, run_store_1.ensureRunDirs)(paths);
     const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
     const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
     const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();

package/dist/shell/telemetry-ledger-io.js

@@ -94,31 +94,43 @@ function loadTelemetryLedger(run) {
 /** Append one attestation record DURABLY to the append-only chain,
  *  linking it to the prior record (or genesis). Returns the committed
  *  record. Throws `TelemetryLedgerCorruptError` if the file on disk is
- *  present but unparseable — never silently re-genesis. */
+ *  present but unparseable — never silently re-genesis.
+ *
+ *  The whole load->append->write is held under `withFileLock` (like every
+ *  other read-modify-write in this codebase — see `recordTrustAuditEvent`).
+ *  `writeJson` REPLACES the file, so without the lock two processes
+ *  appending for the same run at once both read the same N-record ledger,
+ *  both compute a record at chain position N+1, and the last atomic rename
+ *  WINS — silently dropping the loser's record. The surviving chain still
+ *  links correctly, so the loss is invisible to `verifyTelemetryLedger`.
+ *  The `prevHash` and chain position MUST be read from the ledger loaded
+ *  INSIDE the lock so the record links to the true current tail. */
 function appendTelemetryAttestation(run, input) {
-    const ledger = loadTelemetryLedger(run);
-    const now = input.now || new Date().toISOString();
-    const prevHash = ledger.records.length ? ledger.records[ledger.records.length - 1].recordHash : (0, telemetry_ledger_1.genesisPrevHash)(run.id);
-    const base = {
-        schemaVersion: 1,
-        runId: run.id,
-        recordId: (0, telemetry_ledger_1.recordId)(ledger.records.length + 1),
-        recordedAt: now,
-        workerId: input.workerId,
-        taskId: input.taskId,
-        promptDigest: input.promptDigest,
-        reportedUsageDigest: (0, telemetry_ledger_1.reportedUsageDigest)(input.reportedUsage),
-        ...(input.reportedUsage ? { reportedUsage: input.reportedUsage } : {}),
-        usageSignature: input.usageSignature,
-        ...(input.resultDigest ? { resultDigest: input.resultDigest } : {}),
-        attestation: input.attestation,
-        attestationReason: input.attestationReason,
-        prevHash,
-    };
-    const record = { ...base, recordHash: (0, telemetry_ledger_1.computeRecordHash)(base) };
-    ledger.records.push(record);
-    (0, fs_atomic_1.writeJson)(telemetryLedgerPath(run), ledger, { durable: true });
-    return record;
+    return (0, fs_atomic_1.withFileLock)(telemetryLedgerPath(run), () => {
+        const ledger = loadTelemetryLedger(run);
+        const now = input.now || new Date().toISOString();
+        const prevHash = ledger.records.length ? ledger.records[ledger.records.length - 1].recordHash : (0, telemetry_ledger_1.genesisPrevHash)(run.id);
+        const base = {
+            schemaVersion: 1,
+            runId: run.id,
+            recordId: (0, telemetry_ledger_1.recordId)(ledger.records.length + 1),
+            recordedAt: now,
+            workerId: input.workerId,
+            taskId: input.taskId,
+            promptDigest: input.promptDigest,
+            reportedUsageDigest: (0, telemetry_ledger_1.reportedUsageDigest)(input.reportedUsage),
+            ...(input.reportedUsage ? { reportedUsage: input.reportedUsage } : {}),
+            usageSignature: input.usageSignature,
+            ...(input.resultDigest ? { resultDigest: input.resultDigest } : {}),
+            attestation: input.attestation,
+            attestationReason: input.attestationReason,
+            prevHash,
+        };
+        const record = { ...base, recordHash: (0, telemetry_ledger_1.computeRecordHash)(base) };
+        ledger.records.push(record);
+        (0, fs_atomic_1.writeJson)(telemetryLedgerPath(run), ledger, { durable: true });
+        return record;
+    });
 }
 /** Re-prove the whole telemetry chain for a run, reading from disk.
  *  Absent -> present:false/verified:true (nothing to prove). Corrupt ->