mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/single-story-sweep/sweep-lock.js

@@ -1,44 +1,11 @@
 /**
  * single-story-sweep/sweep-lock.js
  *
- * Story #2011: best-effort cross-session lock for the
- * `single-story-sweep` step in `single-story-init.js`. Without a lock,
- * two concurrent `/single-story-deliver` invocations can each compute
- * candidate sets, then each call `executeCleanup` against branches the
- * other was about to act on — producing the "story-2004 toggles in and
- * out of `git worktree list`" pattern observed during Story #2007's
- * session.
- *
- * The lock primitive is a single-file rendezvous:
- *
- *   - `acquireSweepLock({ lockPath, timeoutMs })` opens the file with
- *     `wx` so concurrent attempts fail at the syscall layer (atomic
- *     create-or-error).
- *   - A stale lockfile (mtime older than `timeoutMs`) is treated as
- *     expired and replaced — protects against operators who Ctrl-C
- *     mid-init.
- *   - The returned `release` callback unlinks the file. A process
- *     `'exit'` listener also unlinks as a belt-and-braces guard.
- *
- * The lock is never load-bearing: the caller (`single-story-init.js`)
- * skips the sweep when the lock is contended and continues with init.
- * That matches the existing "sweep never blocks init" contract.
- *
- * **Story #5112 — a live holder is never mistaken for a crashed one.**
- * The critical section this guards (per-candidate `gh pr view`, `getTicket`,
- * `push --delete`) is unbounded, so a healthy sweep can easily outlive the
- * 60 s staleness threshold. Three changes close that:
- *
- *   1. **Heartbeat.** The holder refreshes the lockfile mtime on an
- *      unref'd interval below `timeoutMs`, so an alive holder never reads
- *      stale no matter how long its critical section runs.
- *   2. **Identity-checked steal.** A stale-breaker re-stats before it
- *      unlinks and only removes the *exact* file it observed (same
- *      dev/ino/mtime). Two concurrent breakers therefore yield exactly one
- *      acquisition — the loser cannot unlink the winner's fresh lockfile.
- *   3. **Owner-checked release.** `release()` unlinks only a lockfile whose
- *      owner line still matches this holder, so a late release never drops
- *      someone else's lock.
+ * Best-effort cross-process lockfile (atomic `wx` create) for the merged-branch
+ * sweep. Never load-bearing: a contended caller skips or proceeds. A live
+ * holder is never mistaken for a crashed one: it heartbeats its mtime, a
+ * stale-breaker removes only the exact file it observed (dev/ino/mtime), and
+ * release unlinks only a lockfile still stamped with its owner.
  */
 
 import fs from 'node:fs';
@@ -46,38 +13,17 @@ import path from 'node:path';
 
 const DEFAULT_TIMEOUT_MS = 60_000;
 
-/**
- * Floor for the heartbeat interval. Below this the refresh cost starts to
- * matter for a short critical section, and no `timeoutMs` this framework
- * configures is small enough to need it.
- */
 const MIN_HEARTBEAT_MS = 1_000;
 
-/**
- * Divisor applied to `timeoutMs` to derive the default heartbeat interval.
- * Three refreshes per staleness window means two consecutive missed refreshes
- * (a stalled event loop, a slow disk) still do not make a live holder look
- * dead.
- */
+// Three refreshes per staleness window: two missed refreshes (stalled loop,
+// slow disk) still do not make a live holder look dead.
 const HEARTBEAT_DIVISOR = 3;
 
-/**
- * Canonical filename for the merged-branch sweep lock. One critical section
- * (`sweepMergedBranches` over `story-*`) reached by two entry points —
- * `single-story-init.js` and `boot-sweep.js` — so it gets one lockfile.
- * Before Story #5112 they used `single-story-sweep.lock` and
- * `boot-sweep.lock` respectively and could therefore run the same reap
- * concurrently, each acting on branches the other was mid-delete on. Callers
- * resolve it through {@link resolveSweepLockPath} rather than by name.
- */
+// One critical section reached from single-story-init and boot-sweep, so one
+// lockfile; both MUST resolve it through resolveSweepLockPath.
 const MERGED_BRANCH_SWEEP_LOCK_FILENAME = 'merged-branch-sweep.lock';
 
 /**
- * Resolve the one merged-branch sweep lock path. Both sweep entry points
- * MUST route through this helper — that is what makes "one critical section,
- * one lock" checkable rather than a convention two files can silently drift
- * apart on.
- *
  * @param {{ cwd: string, tempRoot?: string }} args
  * @returns {string} absolute path to the shared lockfile.
  */
@@ -86,13 +32,8 @@ export function resolveSweepLockPath({ cwd, tempRoot = 'temp' } = {}) {
 }
 
 /**
- * Derive the heartbeat interval for a given staleness threshold. Module-
- * private: the contract that matters ("strictly below `timeoutMs`") is
- * observable at the `setIntervalFn` seam {@link acquireSweepLock} accepts, so
- * a test pins it there rather than reaching past the public surface.
- *
  * @param {number} timeoutMs
- * @returns {number}
+ * @returns {number} an interval strictly below `timeoutMs`.
  */
 function heartbeatIntervalFor(timeoutMs) {
   const derived = Math.floor(
@@ -102,35 +43,19 @@ function heartbeatIntervalFor(timeoutMs) {
   return Math.max(MIN_HEARTBEAT_MS, derived);
 }
 
-/**
- * Signals whose default disposition kills the process. A holder that takes
- * one MUST drop its lockfile before it dies: the `'exit'` guard in
- * {@link buildAcquired} never runs for a signal Node has not been asked to
- * handle, so before Story #5278 a Ctrl-C during a full suite left a lockfile
- * behind that every sibling then had to wait `timeoutMs` to break.
- */
+// Node runs no 'exit' handler for an unhandled fatal signal, so the holder
+// must drop its lockfile on these itself.
 const RELEASE_ON_SIGNALS = Object.freeze(['SIGINT', 'SIGTERM']);
 
 /**
- * Is `pid` a process this host is still running?
- *
- * `kill(pid, 0)` performs the permission and existence checks without
- * delivering a signal. Three outcomes matter:
- *
- *   - it returns → the process exists and is ours: **alive**;
- *   - `EPERM` → the process exists but belongs to another user: **alive**
- *     (an existence check that we are not allowed to complete is not
- *     evidence of death);
- *   - `ESRCH` → no such process: **dead**.
- *
- * A pid that cannot be read at all resolves to `null` — "unknown", which
- * leaves the mtime heuristic in charge exactly as before.
+ * `kill(pid, 0)`: returns → alive; `EPERM` → alive (exists, not ours);
+ * `ESRCH` → dead. Also used by the full-suite waiter queue.
  *
  * @param {number|null} pid
  * @param {(pid: number, signal: number) => void} [killFn]
  * @returns {boolean|null} `null` when the pid is unknown.
  */
-function isHolderAlive(pid, killFn = process.kill.bind(process)) {
+export function isHolderAlive(pid, killFn = process.kill.bind(process)) {
   if (!Number.isInteger(pid) || pid <= 0) return null;
   try {
     killFn(pid, 0);
@@ -141,20 +66,12 @@ function isHolderAlive(pid, killFn = process.kill.bind(process)) {
 }
 
 /**
- * Read the lockfile's *identity* — the tuple that distinguishes "the file I
- * observed" from "a different file that now sits at the same path". `dev` +
- * `ino` change when a lockfile is unlinked and re-created, and `mtimeMs`
- * changes on every heartbeat, so a steal that re-checks all three cannot
- * remove a lock some other process created (or refreshed) in the interim.
- *
- * Returns `null` when the file is absent or stat fails ("no holder").
+ * `dev`+`ino` change on re-create and `mtimeMs` on every heartbeat, so a
+ * steal that re-checks all three cannot remove a lock created or refreshed in
+ * the interim.
  *
  * @param {string} lockPath
  * @param {object} [fsImpl]
- * Module-private: the two readers that need it (the stale takeover and the
- * `readLockMtime` projection below) both live here, and nothing outside this
- * primitive should be reasoning about a lockfile's inode.
- *
  * @returns {{ mtimeMs: number, ino: number|null, dev: number|null }|null}
  */
 function readLockIdentity(lockPath, fsImpl = fs) {
@@ -170,21 +87,12 @@ function readLockIdentity(lockPath, fsImpl = fs) {
   }
 }
 
-/**
- * Pure: read the lockfile mtime. Returns `null` when the file is absent or
- * stat fails (treat as "no holder"). The mtime projection of
- * {@link readLockIdentity}. Exported for tests.
- */
+/** Lockfile mtime, or `null` when absent (no holder). */
 export function readLockMtime(lockPath, fsImpl = fs) {
   return readLockIdentity(lockPath, fsImpl)?.mtimeMs ?? null;
 }
 
 /**
- * Read the owner id a lockfile was created with (its first line). Returns
- * `null` when the file is absent, unreadable, or empty. Module-private — the
- * owner line is an implementation detail of this primitive; callers observe
- * ownership through which acquire wins and which `release()` is a no-op.
- *
  * @param {string} lockPath
  * @param {object} [fsImpl]
  * @returns {string|null}
@@ -200,14 +108,8 @@ function readLockOwner(lockPath, fsImpl = fs) {
 }
 
 /**
- * Read the pid a lockfile was created by (its third line — see
- * {@link tryCreateLock}'s body format). Returns `null` when the file is
- * absent, unreadable, or its pid line is not a positive integer.
- *
- * Exists so a *waiting* caller can name the holder in its wait line: a bounded
- * wait with no attribution is indistinguishable from a hang, and the pid is
- * the one field an operator can act on (`ps`, `kill`). Reading it is
- * advisory — a `null` just means the wait line says less.
+ * The holder pid (third line), so a waiter can name who it waits on.
+ * Advisory: `null` just means the wait line says less.
  *
  * @param {string} lockPath
  * @param {object} [fsImpl]
@@ -224,10 +126,7 @@ export function readLockHolderPid(lockPath, fsImpl = fs) {
 }
 
 /**
- * Pure: do two identity tuples describe the same lockfile instance? A `null`
- * on either side is "not the same" — an absent file is never the file we
- * observed. Module-private, like {@link readLockIdentity} it compares:
- * nothing outside this primitive should reason about a lockfile's inode.
+ * A `null` on either side is never "the same".
  *
  * @param {ReturnType<typeof readLockIdentity>} a
  * @param {ReturnType<typeof readLockIdentity>} b
@@ -238,23 +137,14 @@ function sameLockIdentity(a, b) {
   return a.mtimeMs === b.mtimeMs && a.ino === b.ino && a.dev === b.dev;
 }
 
-/**
- * Pure: is the lockfile mtime older than `timeoutMs`? A `null` mtime
- * (no file) returns `false` — the lock isn't held, there's nothing to
- * be stale. Exported for tests.
- */
+/** A `null` mtime (no file) is never stale. */
 export function isLockStale(mtime, nowMs, timeoutMs) {
   if (mtime === null) return false;
   return nowMs - mtime > timeoutMs;
 }
 
 /**
- * Attempt to atomically create the lockfile. Returns `true` on success,
- * `false` when another process holds it. Any other I/O error throws.
- *
- * Uses `fs.openSync(path, 'wx')` — the `'wx'` flag combination is
- * `O_CREAT | O_EXCL | O_WRONLY` which fails with `EEXIST` if the file
- * already exists. Atomic on POSIX and on Windows ReFS/NTFS.
+ * `wx` = O_CREAT|O_EXCL: `false` on EEXIST, any other error throws.
  */
 function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
   fsImpl.mkdirSync(path.dirname(lockPath), { recursive: true });
@@ -277,37 +167,20 @@ function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
 }
 
 /**
- * Acquire the sweep lock. Returns one of:
- *
- *   - `{ acquired: true, release: () => void, ownerId }`
- *   - `{ acquired: false, reason: 'contended' | 'error', detail?: string }`
- *
- * When a stale lockfile is found (mtime older than `timeoutMs`), it is
- * unlinked and a fresh acquire is retried once. If the retry also
- * loses the race (another caller acquired between the unlink and the
- * retry), the caller gets `acquired: false, reason: 'contended'` and
- * may decide to skip the sweep — same as a fresh contention.
+ * Single attempt, with one stale-takeover retry.
  *
  * @param {object} opts
- * @param {string} opts.lockPath           Absolute path to the lockfile.
+ * @param {string} opts.lockPath
  * @param {number} [opts.timeoutMs=60000]  Stale-lock threshold.
- * @param {string} [opts.ownerId]          Identifier persisted into the
- *                                         lockfile body for postmortem;
- *                                         defaults to a pid+timestamp
- *                                         string.
- * @param {object} [opts.nowFn]            `() => number` (ms epoch);
- *                                         injection seam for tests.
- * @param {object} [opts.fsImpl]           Node `fs` shim for tests.
- * @param {number} [opts.heartbeatMs]      Mtime-refresh interval for a live
- *                                         holder; defaults to a third of
- *                                         `timeoutMs`. `0` disables it.
- * @param {Function} [opts.setIntervalFn]  Timer seam for tests.
- * @param {Function} [opts.clearIntervalFn] Timer seam for tests.
- * @param {Function} [opts.killFn]        `process.kill` seam for the holder
- *                                        liveness probe (Story #5278).
- * @param {object} [opts.processImpl]     `process` seam for the
- *                                        release-on-signal handlers.
- * @returns {{ acquired: true, release: () => void, refresh: () => boolean, ownerId: string }
+ * @param {string} [opts.ownerId]          Persisted for postmortem.
+ * @param {object} [opts.nowFn]
+ * @param {object} [opts.fsImpl]
+ * @param {number} [opts.heartbeatMs]      Defaults to `timeoutMs / 3`; `0` disables.
+ * @param {Function} [opts.setIntervalFn]
+ * @param {Function} [opts.clearIntervalFn]
+ * @param {Function} [opts.killFn]        Holder liveness probe seam.
+ * @param {object} [opts.processImpl]     Seam for release-on-signal.
+ * @returns {{ acquired: true, release: () => void, ownerId: string }
  *          | { acquired: false, reason: 'contended' | 'error', detail?: string }}
  */
 export function acquireSweepLock({
@@ -359,9 +232,8 @@ export function acquireSweepLock({
 }
 
 /**
- * Take over a lockfile whose holder looks dead. Returns `true` only when this
- * call both removed the exact stale file it observed *and* won the re-create,
- * so two concurrent breakers yield exactly one acquisition.
+ * `true` only when this call removed the exact stale file it observed and won
+ * the re-create, so concurrent breakers yield one acquisition.
  *
  * @param {{ lockPath: string, ownerId: string, fsImpl: object, nowFn: () => number }} holder
  * @param {number} timeoutMs
@@ -385,20 +257,9 @@ function tryStaleTakeover(
 }
 
 /**
- * Is the observed holder dead enough to take over? Story #5278 adds the
- * holder's **pid** as a way to answer "yes" *sooner* — never as a way to
- * answer "no".
- *
- *   - pid **dead** (`ESRCH`) → stale immediately, whatever the mtime says. A
- *     crashed or Ctrl-C'd holder no longer costs every sibling a full
- *     `timeoutMs` wait for a lockfile nobody is behind.
- *   - anything else (alive, or an unreadable pid) → the mtime heuristic
- *     decides, byte-for-byte the pre-#5278 rule.
- *
- * Deliberately one-directional. Letting a live pid *veto* the mtime rule
- * would make a hung holder immortal and would break the reclaim contract the
- * full-suite lock depends on; keeping the holder's mtime advancing while it
- * works is the heartbeat's job (`refreshLockSync`), not this predicate's.
+ * A dead pid makes the holder stale immediately; otherwise mtime decides.
+ * One-directional on purpose: a live pid never vetoes the mtime rule, or a
+ * hung holder would be immortal.
  *
  * @param {{ lockPath: string, fsImpl: object, nowFn: () => number, killFn?: Function, observed: {mtimeMs: number}, timeoutMs: number }} args
  * @returns {boolean}
@@ -418,12 +279,8 @@ function isHolderStale({
 }
 
 /**
- * Unlink a stale lockfile — but only when it is still byte-for-byte the
- * instance the caller observed. Returns `true` when this call removed that
- * exact file, `false` when the file changed underneath us (a heartbeat, or
- * another breaker's replacement) or the unlink failed. A `false` return means
- * "someone else owns this now": the caller reports contended rather than
- * racing on.
+ * Unlink only if the file is still the observed instance; `false` means
+ * someone else owns it now.
  *
  * @param {string} lockPath
  * @param {ReturnType<typeof readLockIdentity>} observed
@@ -443,28 +300,13 @@ function breakStaleLock(lockPath, observed, fsImpl) {
 }
 
 /**
- * Refresh a held lockfile's mtime so a long critical section never reads
- * stale to a concurrent acquirer. Refuses to touch a lockfile whose owner
- * line is no longer ours — after a steal the file belongs to someone else and
- * bumping its mtime would keep *their* lock alive on our behalf.
- *
- * **The synchronous refresh entry point (Story #5278).** The interval-driven
- * heartbeat below only fires when the holder's event loop gets a turn, which
- * a `spawnSync` critical section never gives it. A caller on such a stack
- * calls this directly — immediately before it blocks — so the lock it is
- * about to sit on carries a current mtime rather than the one it was created
- * with minutes earlier.
+ * Refuses a lockfile no longer ours, or we would keep a thief's lock alive.
  *
  * @param {{ lockPath: string, ownerId: string, fsImpl?: object, nowFn?: () => number }} holder
  * @returns {boolean} `true` when the refresh landed; `false` when the lock is
  *   no longer ours (the caller stops heartbeating).
  */
-export function refreshLockSync({
-  lockPath,
-  ownerId,
-  fsImpl = fs,
-  nowFn = Date.now,
-}) {
+function refreshLockSync({ lockPath, ownerId, fsImpl = fs, nowFn = Date.now }) {
   if (readLockOwner(lockPath, fsImpl) !== ownerId) return false;
   try {
     const stamp = new Date(nowFn());
@@ -475,11 +317,7 @@ export function refreshLockSync({
   }
 }
 
-/**
- * Start the holder's mtime heartbeat. Returns a `stop()` that is safe to call
- * repeatedly. The timer is unref'd where the platform supports it, so a
- * forgotten release can never hold the process open.
- */
+/** Unref'd so a forgotten release never holds the process open. */
 function startHeartbeat(holder) {
   const { heartbeatMs, setIntervalFn, clearIntervalFn } = holder;
   if (!(heartbeatMs > 0) || typeof setIntervalFn !== 'function') {
@@ -493,7 +331,7 @@ function startHeartbeat(holder) {
     try {
       clearIntervalFn(handle);
     } catch {
-      // Best-effort: a fake timer seam may not implement clear.
+      // A fake timer seam may not implement clear.
     }
   };
   timer = setIntervalFn(() => {
@@ -504,11 +342,6 @@ function startHeartbeat(holder) {
 }
 
 /**
- * Drop a lockfile, but only when it is still stamped with `ownerId`. A
- * lockfile another holder created after ours was stolen (or stale-broken) is
- * theirs — dropping it would hand a third caller a lock the current holder
- * still believes it owns.
- *
  * @param {string} lockPath
  * @param {string} ownerId
  * @param {object} fsImpl
@@ -518,7 +351,7 @@ function unlinkIfOwned(lockPath, ownerId, fsImpl) {
   try {
     fsImpl.unlinkSync(lockPath);
   } catch {
-    // Already gone — nothing to do.
+    // Already gone.
   }
 }
 
@@ -534,8 +367,6 @@ function buildAcquired(holder) {
     detachSignals();
     unlinkIfOwned(lockPath, ownerId, fsImpl);
   };
-  // Belt-and-braces: process exit also clears the lockfile so a
-  // crashed run doesn't leave a stale-but-not-yet-old artifact behind.
   const exitCleanup = () => release();
   if (typeof processImpl?.once === 'function') {
     processImpl.once('exit', exitCleanup);
@@ -544,25 +375,13 @@ function buildAcquired(holder) {
   return {
     acquired: true,
     release,
-    refresh: () => refreshLockSync(holder),
     ownerId,
   };
 }
 
 /**
- * Drop the lock on SIGINT / SIGTERM, then re-raise so the process still dies
- * the way its caller asked it to (Story #5278).
- *
- * The `'exit'` guard above does not cover this: Node only runs `'exit'`
- * handlers for a signal it has been asked to handle, so an unhandled Ctrl-C
- * terminates the process with the lockfile still on disk. Registering here
- * changes only *cleanup*, never the outcome — the handler removes itself and
- * re-sends the same signal, so with no other listener the process dies under
- * the default disposition and exits 128 + signum (130 for SIGINT), exactly as
- * it did before.
- *
- * Returns a detach callback so a released holder stops intercepting signals
- * it no longer has anything to clean up for.
+ * Drop the lock on SIGINT/SIGTERM, then re-raise: only cleanup changes, the
+ * process still dies under the default disposition (exit 128 + signum).
  *
  * @param {object} processImpl
  * @param {() => void} release
@@ -578,10 +397,8 @@ function attachSignalRelease(processImpl, release) {
   }
   const handlers = RELEASE_ON_SIGNALS.map((signal) => {
     const handler = () => {
+      // release() already detached us, so the re-raise cannot loop back.
       release();
-      // `release()` has already detached every handler, so this re-raise
-      // reaches the default disposition (or another listener) rather than
-      // looping back into us.
       try {
         processImpl.kill(processImpl.pid, signal);
       } catch {
@@ -596,7 +413,7 @@ function attachSignalRelease(processImpl, release) {
       try {
         processImpl.off(signal, handler);
       } catch {
-        // Best-effort: a seam may not implement removal.
+        // A seam may not implement removal.
       }
     }
   };
@@ -606,9 +423,6 @@ const DEFAULT_WAIT_MS = 8_000;
 const DEFAULT_POLL_MS = 150;
 
 /**
- * Promise-based delay. Injectable so tests can drive the wait loop on a fake
- * clock without a real timer.
- *
  * @param {number} ms
  * @returns {Promise<void>}
  */
@@ -619,33 +433,22 @@ function defaultSleep(ms) {
 }
 
 /**
- * Bounded-wait wrapper over {@link acquireSweepLock}.
- *
- * `acquireSweepLock` is single-attempt on purpose: a *skipped* sweep is
- * harmless, so the sweep caller proceeds immediately on contention. The
- * post-land tail is the opposite case — proceeding immediately IS the race
- * two concurrent closes hit on a shared main checkout — so this wrapper
- * polls the primitive with short backoff up to `waitMs` before giving up.
- *
- * It is still **never load-bearing**: on `waitMs` exhaustion it returns
- * `{ acquired: false, reason: 'contended-after-wait' }` and the caller is
- * expected to proceed anyway. The bounded wait is a best-effort collision
- * damper, not a mutual-exclusion guarantee. A hard I/O error short-circuits
- * the loop (spinning would just re-hit it).
+ * Polls {@link acquireSweepLock} up to `waitMs` — a collision damper for the
+ * post-land tail, not mutual exclusion: on exhaustion the caller proceeds
+ * anyway. A hard I/O error returns immediately.
  *
  * @param {object} opts
  * @param {string} opts.lockPath
- * @param {number} [opts.waitMs]     Max total time to wait for the lock.
- * @param {number} [opts.pollMs]     Delay between acquire attempts.
- * @param {number} [opts.timeoutMs]  Stale-lock expiry, forwarded to the
- *                                   underlying acquire.
+ * @param {number} [opts.waitMs]
+ * @param {number} [opts.pollMs]
+ * @param {number} [opts.timeoutMs]  Stale-lock expiry.
  * @param {string} [opts.ownerId]
  * @param {() => number} [opts.nowFn]
  * @param {(ms: number) => Promise<void>} [opts.sleepFn]
  * @param {object} [opts.fsImpl]
- * @param {number} [opts.heartbeatMs]      Forwarded to the underlying acquire.
- * @param {Function} [opts.setIntervalFn]  Forwarded to the underlying acquire.
- * @param {Function} [opts.clearIntervalFn] Forwarded to the underlying acquire.
+ * @param {number} [opts.heartbeatMs]
+ * @param {Function} [opts.setIntervalFn]
+ * @param {Function} [opts.clearIntervalFn]
  * @returns {Promise<{ acquired: true, release: () => void, ownerId: string }
  *          | { acquired: false, reason: 'contended-after-wait' | 'error', detail?: string }>}
  */
@@ -679,7 +482,6 @@ export async function acquireLockWithWait({
       processImpl,
     });
     if (res.acquired) return res;
-    // A hard error will not resolve by retrying — surface it immediately.
     if (res.reason === 'error') return res;
     if (nowFn() >= deadline) {
       return { acquired: false, reason: 'contended-after-wait' };