cool-workflow 0.2.2 → 0.2.4

package/dist/shell/fs-atomic.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeJson = writeJson;
+exports.writeTextDurable = writeTextDurable;
 exports.readJson = readJson;
 exports.safeFileName = safeFileName;
 exports.assertSafeRunId = assertSafeRunId;
@@ -55,19 +56,22 @@ const path = __importStar(require("node:path"));
 // + "\n", written via temp-file + optional fsync + rename (atomic).
 // ---------------------------------------------------------------------------
 let atomicWriteCounter = 0;
-/** Atomic, optionally-durable JSON write. ORDER IS THE SAFETY PROPERTY: write
- *  the full bytes to a unique temp file, optionally fsync it, close, then
- *  rename over the target. `rename(2)` is atomic on POSIX, so a reader always
- *  sees either the old bytes or the new bytes, never a torn file. On a rename
- *  failure the temp file is removed (best-effort) and the error is rethrown —
- *  the old bytes at `file` are never touched. */
-function writeJson(file, value, options = {}) {
+/** Shared core of `writeJson`/`writeTextDurable`: write `contents` to a
+ *  unique temp file, optionally fsync it, close, then rename over `file`.
+ *  ORDER IS THE SAFETY PROPERTY — `rename(2)` is atomic on POSIX, so a
+ *  reader always sees either the old bytes or the new bytes, never a torn
+ *  file. On a rename failure the temp file is removed (best-effort) and
+ *  the error is rethrown — the old bytes at `file` are never touched. */
+function writeBytesAtomic(file, contents, durable) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const tmp = `${file}.tmp.${process.pid}.${atomicWriteCounter++}`;
-    const fd = fs.openSync(tmp, "w");
+    // 0o600: this is run/ledger/registry state, not a file meant to be shared
+    // with other local users. rename(2) preserves the mode set at creation, so
+    // this covers the final file too.
+    const fd = fs.openSync(tmp, "w", 0o600);
     try {
-        fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-        if (options.durable)
+        fs.writeFileSync(fd, contents, "utf8");
+        if (durable)
             fs.fsyncSync(fd);
     }
     finally {
@@ -85,7 +89,7 @@ function writeJson(file, value, options = {}) {
         }
         throw error;
     }
-    if (options.durable) {
+    if (durable) {
         try {
             const dirFd = fs.openSync(path.dirname(file), "r");
             try {
@@ -100,6 +104,17 @@ function writeJson(file, value, options = {}) {
         }
     }
 }
+/** Atomic, optionally-durable JSON write — see `writeBytesAtomic`. */
+function writeJson(file, value, options = {}) {
+    writeBytesAtomic(file, `${JSON.stringify(value, null, 2)}\n`, Boolean(options.durable));
+}
+/** Same atomic-write contract as `writeJson` (temp file + optional fsync +
+ *  rename), but for exact pre-built text instead of a value to serialize —
+ *  used by callers replacing an NDJSON-style file (e.g. a repaired
+ *  trust-audit event log) where the caller already has the final bytes. */
+function writeTextDurable(file, text, options = {}) {
+    writeBytesAtomic(file, text, Boolean(options.durable));
+}
 /** Read + JSON.parse a file. Throws `File not found: <file>` when absent,
  *  `Invalid JSON in <file>: <message>` on a parse error. */
 function readJson(file) {
@@ -172,7 +187,7 @@ function isContainedPath(candidate, allowed) {
 // ---------------------------------------------------------------------------
 function durableAppendFileSync(file, data) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    const fd = fs.openSync(file, "a");
+    const fd = fs.openSync(file, "a", 0o600);
     try {
         fs.writeFileSync(fd, data, "utf8");
         fs.fsyncSync(fd);
@@ -184,11 +199,14 @@ function durableAppendFileSync(file, data) {
 // ---------------------------------------------------------------------------
 // withFileLock — portable advisory cross-process lock.
 //
-// Lock file: `<targetPath>.lock`, created with O_EXCL (`wx`), body
-// `"<pid>@<ISO>\n"`. Up to 240 tries; on EEXIST, a lock whose mtime is older
-// than FILE_LOCK_STALE_MS (30_000) is stolen (deleted) and retried AT ONCE;
-// else sleep 25ms (Atomics.wait busy-safe sleep) and retry. Any non-EEXIST
-// open error is rethrown. No lock after 240 tries throws
+// Lock file: `<targetPath>.lock`, created by hard-linking a per-attempt temp
+// file onto the lock path (single-winner `link(2)`), body `"<pid>@<ISO>\n"`.
+// Up to 240 tries; on EEXIST, a lock whose mtime is older than
+// FILE_LOCK_STALE_MS (30_000) is stolen — judged and deleted only while
+// holding the single-winner `<lock>.steal` guard (see
+// stealStaleLockUnderGuard) — and retried AT ONCE; else sleep 25ms
+// (Atomics.wait busy-safe sleep) and retry. Any non-EEXIST link error is
+// rethrown. No lock after 240 tries throws
 // `could not acquire file lock for <targetPath>`.
 //
 // Right before fn() the lock mtime is refreshed (utimesSync, best-effort).
@@ -198,6 +216,17 @@ function durableAppendFileSync(file, data) {
 // only when still owned by this pid.
 // ---------------------------------------------------------------------------
 const FILE_LOCK_STALE_MS = 30_000;
+// A lock stale for this long is stolen regardless of what `isLockOwnerAlive`
+// says — the fallback for the one case a liveness check cannot resolve: the
+// recorded pid has been recycled by an unrelated live process, which would
+// otherwise make a dead owner's pid look "alive" forever and wedge the lock
+// permanently. 10x the normal window keeps this astronomically unlikely to
+// fire against a genuinely still-working holder.
+const FILE_LOCK_FORCE_STALE_MS = FILE_LOCK_STALE_MS * 10;
+// A steal guard older than this belongs to a stealer that crashed inside the
+// guarded window (which is a handful of syscalls, microseconds for any live
+// process) — remove it so stealing cannot wedge forever.
+const FILE_LOCK_STEAL_GUARD_STALE_MS = FILE_LOCK_STALE_MS;
 // Lock paths this process holds right now. A nested withFileLock on the
 // SAME target runs its fn directly (re-entrant) instead of waiting on its
 // own lock file until the 240 tries run out — that lets a whole
@@ -207,6 +236,132 @@ const HELD_LOCKS = new Set();
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/** Whether the pid recorded in a lock body ("<pid>@<ISO>\n") is still a
+ *  live process on this machine. Locks here are local-advisory only (no
+ *  network-shared run directories in this tool's model), so
+ *  `process.kill(pid, 0)` — signal 0 delivers nothing, it just probes
+ *  existence/permission — gives a direct, same-instant answer, unlike
+ *  mtime, which is a snapshot a caller can act on after it is already
+ *  outdated. This is the property that actually closes the steal race: a
+ *  lock belonging to a currently running process can never pass this
+ *  check, no matter how a mtime-based timing window lines up, because its
+ *  owner really is alive right now. Malformed content or a missing pid is
+ *  treated as "not verifiably alive" so the mtime-only path still applies.
+ *  `EPERM` (a process with that pid exists but this process cannot signal
+ *  it) is treated as alive — the conservative, never-wrongly-steal
+ *  direction. */
+function isLockOwnerAlive(lockBody) {
+    const match = /^(\d+)@/.exec(lockBody);
+    if (!match)
+        return false;
+    const pid = Number(match[1]);
+    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");
+    }
+}
+/** Steal a stale lock, serialized through a single-winner guard file.
+ *
+ *  Every earlier steal design judged the lock and then deleted it as two
+ *  separate steps with no exclusion around them, and every narrowing of
+ *  that gap (content-equality re-read, liveness gate, unlinkSync over
+ *  rmSync) still lost a CI run eventually: under load, the judging
+ *  process can be preempted between its last read and its unlink, a
+ *  concurrent stealer completes the whole steal-and-reacquire in that
+ *  gap, and the sleeper's unlink then removes the NEW owner's lock —
+ *  two processes end up inside the critical section (reproduced in PR
+ *  #420's CI on arm64 Node 22, trial 10, after the linkSync acquire fix
+ *  landed). The gap cannot be closed from the judging side; POSIX has no
+ *  compare-and-delete.
+ *
+ *  So close it by exclusion instead: only the holder of `<lock>.steal`
+ *  (acquired with the same single-winner linkSync used for the lock
+ *  itself) may judge and delete. While the judged lock file still
+ *  exists, no waiter can link-acquire the lock path, so nothing can
+ *  replace the lock between a guard-held verdict and the unlink; and no
+ *  second stealer exists to double-delete. Before the unlink, the
+ *  verdict is additionally pinned to the exact file it judged (same
+ *  inode, same mtime) — insurance for the force-stale path, where an
+ *  owner release + fresh re-acquire between the guard's stat and read
+ *  could otherwise slip through.
+ *
+ *  A guard whose holder crashed inside the guarded window (microseconds
+ *  of syscalls for any live process) is removed after
+ *  FILE_LOCK_STEAL_GUARD_STALE_MS so stealing cannot wedge; that cleanup
+ *  is itself a plain stat-and-unlink, but reintroducing the original
+ *  race through it needs a crashed stealer AND two cleaners AND a fresh
+ *  guard all colliding inside one syscall-wide window — compounded odds
+ *  the hot path never sees.
+ *
+ *  Returns true when this process held the guard and rendered a verdict
+ *  (steal done or judged-not-stale) — the caller should retry the
+ *  acquire at once. Returns false when the guard was busy — the caller
+ *  should back off like ordinary contention. */
+function stealStaleLockUnderGuard(lock, pid, attempt) {
+    const guard = `${lock}.steal`;
+    try {
+        const guardAge = Date.now() - fs.statSync(guard).mtimeMs;
+        if (guardAge > FILE_LOCK_STEAL_GUARD_STALE_MS)
+            fs.unlinkSync(guard);
+    }
+    catch {
+        /* no guard, or another cleaner beat us to it */
+    }
+    const tmp = `${guard}.${pid}.${attempt}.tmp`;
+    let haveGuard = false;
+    try {
+        fs.writeFileSync(tmp, `${pid}@${new Date().toISOString()}\n`, { mode: 0o600 });
+        fs.linkSync(tmp, guard);
+        haveGuard = true;
+    }
+    catch {
+        /* EEXIST — another stealer holds the guard */
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    if (!haveGuard)
+        return false;
+    try {
+        // Re-judge INSIDE the guard: only what is verified here counts.
+        const judged = fs.statSync(lock);
+        const age = Date.now() - judged.mtimeMs;
+        if (age <= FILE_LOCK_STALE_MS)
+            return true;
+        const body = fs.readFileSync(lock, "utf8");
+        if (!(age > FILE_LOCK_FORCE_STALE_MS || !isLockOwnerAlive(body)))
+            return true;
+        // Pin the verdict to the exact file it judged: a lock re-acquired in
+        // the stat->read gap is a NEW inode (every acquire links a fresh tmp
+        // file) with a fresh mtime, so either check catches it.
+        const current = fs.statSync(lock);
+        if (current.ino === judged.ino && current.mtimeMs === judged.mtimeMs) {
+            fs.unlinkSync(lock);
+        }
+    }
+    catch {
+        /* lock vanished — nothing left to steal */
+    }
+    finally {
+        try {
+            fs.unlinkSync(guard);
+        }
+        catch {
+            /* guard already cleaned up */
+        }
+    }
+    return true;
+}
 /** Run `fn` while holding an advisory lock for `targetPath`; always released
  *  (unless the lock was stolen mid-operation, in which case releasing would
  *  corrupt the thief's critical section, so it is deliberately NOT released).
@@ -221,27 +376,61 @@ function withFileLock(targetPath, fn) {
     const pid = String(process.pid);
     let acquired = false;
     for (let attempt = 0; attempt < 240 && !acquired; attempt++) {
+        // Acquire via `linkSync`, not `open(lock, "wx")`: directly testing the
+        // retry loop under contention showed `open(O_CREAT|O_EXCL)` is NOT
+        // reliably single-winner on every Node version this runs on — under
+        // CI load (reproduced on Node 18, both x64 and arm64), two separate
+        // processes could each `open(wx)` + write + read back and each see
+        // ONLY ITS OWN content, meaning the OS was not actually serializing
+        // the two creates against each other (see
+        // test/fs-atomic-lock-steal-race-smoke.js for the reproduction). A
+        // readback-verification pass added on top of `open(wx)` still could
+        // not close this, because the underlying create itself was the
+        // unreliable step, not just the later unlink. `link(2)`'s exclusivity
+        // guarantee is the older, more battle-tested primitive precisely for
+        // this class of lockfile race (classic Unix "lock via link" idiom) —
+        // stress-tested directly (24-process contention, 15/15 trials) with
+        // zero double-winners where the same rig reproduced `open(wx)`
+        // double-winners within a handful of trials.
+        const tmp = `${lock}.${pid}.${attempt}.tmp`;
+        let linkError = null;
         try {
-            const fd = fs.openSync(lock, "wx");
-            fs.writeFileSync(fd, `${pid}@${new Date().toISOString()}\n`, "utf8");
-            fs.closeSync(fd);
+            fs.writeFileSync(tmp, `${pid}@${new Date().toISOString()}\n`, { mode: 0o600 });
+            fs.linkSync(tmp, lock);
             acquired = true;
         }
         catch (error) {
-            if (!(error && typeof error === "object" && error.code === "EEXIST")) {
-                throw error;
-            }
+            linkError = error;
+        }
+        finally {
             try {
-                if (Date.now() - fs.statSync(lock).mtimeMs > FILE_LOCK_STALE_MS) {
-                    fs.rmSync(lock, { force: true });
-                    continue;
-                }
+                fs.unlinkSync(tmp);
             }
             catch {
-                continue;
+                /* already gone, or the link consumed it — either is fine */
             }
-            sleepSync(25);
         }
+        if (acquired)
+            break;
+        if (!(linkError && typeof linkError === "object" && linkError.code === "EEXIST")) {
+            throw linkError;
+        }
+        try {
+            const age = Date.now() - fs.statSync(lock).mtimeMs;
+            if (age > FILE_LOCK_STALE_MS) {
+                // The steal itself runs under a single-winner guard lock — see
+                // stealStaleLockUnderGuard for why judging staleness and deleting
+                // the lock without one can never be made safe from here.
+                if (stealStaleLockUnderGuard(lock, pid, attempt))
+                    continue;
+                // Guard was busy — another process is mid-steal. Back off like
+                // ordinary contention instead of hot-spinning the attempt budget.
+            }
+        }
+        catch {
+            continue;
+        }
+        sleepSync(25);
     }
     if (!acquired)
         throw new Error(`could not acquire file lock for ${targetPath}`);

package/dist/shell/man-cli.js

@@ -47,6 +47,7 @@ exports.ManPageNotFoundError = void 0;
 exports.readManPage = readManPage;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const fs_atomic_1 = require("./fs-atomic");
 class ManPageNotFoundError extends Error {
     topic;
     constructor(topic) {
@@ -77,6 +78,11 @@ function readManPage(topic) {
     const docsDir = path.join(pluginRoot(), "docs");
     const candidates = [path.join(docsDir, `${topic}.7.md`), path.join(docsDir, `${topic}.md`), path.join(docsDir, topic)];
     for (const candidate of candidates) {
+        // A topic containing `..` or an absolute-path escape must never resolve
+        // outside docsDir — this bare third candidate would otherwise read any
+        // file on disk (e.g. `cw man ../../../../etc/passwd`).
+        if (!(0, fs_atomic_1.isContainedPath)(candidate, docsDir))
+            continue;
         try {
             if (fs.statSync(candidate).isFile())
                 return fs.readFileSync(candidate, "utf8");

package/dist/shell/metrics-cli.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.metricsShowCli = metricsShowCli;
 exports.metricsSummaryCli = metricsSummaryCli;
 const path = __importStar(require("node:path"));
+const numeric_flag_1 = require("../core/util/numeric-flag");
 const run_store_1 = require("./run-store");
 const observability_1 = require("./observability");
 const run_registry_io_1 = require("./run-registry-io");
@@ -78,7 +79,7 @@ function metricsSummaryCli(args) {
     const cwd = invocationCwd(args);
     const scope = args.scope === "home" ? "home" : "repo";
     const registry = new run_registry_io_1.RunRegistry(cwd);
-    const limit = args.limit === undefined ? undefined : Number(args.limit);
+    const limit = (0, numeric_flag_1.requiredNumberFlag)(args.limit, "--limit");
     const listing = registry.list({ scope, includeArchived: true, limit });
     const inputs = [];
     let unreadableRuns = 0;