mandrel 2.35.0 → 2.37.0

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

@@ -23,6 +23,22 @@
  * 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.
  */
 
 import fs from 'node:fs';
@@ -31,18 +47,135 @@ import path from 'node:path';
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
- * Pure: read the lockfile mtime. Returns `null` when the file is
- * absent or stat fails (treat as "no holder"). Exported for tests.
+ * 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.
  */
-export function readLockMtime(lockPath, fsImpl = fs) {
+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.
+ */
+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.
+ */
+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.
+ */
+export function resolveSweepLockPath({ cwd, tempRoot = 'temp' } = {}) {
+  return path.resolve(cwd, tempRoot, MERGED_BRANCH_SWEEP_LOCK_FILENAME);
+}
+
+/**
+ * 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}
+ */
+function heartbeatIntervalFor(timeoutMs) {
+  const derived = Math.floor(
+    (Number.isFinite(timeoutMs) ? timeoutMs : DEFAULT_TIMEOUT_MS) /
+      HEARTBEAT_DIVISOR,
+  );
+  return Math.max(MIN_HEARTBEAT_MS, derived);
+}
+
+/**
+ * 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").
+ *
+ * @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) {
   try {
     const stat = fsImpl.statSync(lockPath);
-    return stat.mtimeMs;
+    return {
+      mtimeMs: stat.mtimeMs,
+      ino: stat.ino ?? null,
+      dev: stat.dev ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+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}
+ */
+function readLockOwner(lockPath, fsImpl = fs) {
+  try {
+    const raw = fsImpl.readFileSync(lockPath, 'utf8');
+    const first = String(raw).split('\n', 1)[0];
+    return first.length > 0 ? first : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * 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.
+ *
+ * @param {ReturnType<typeof readLockIdentity>} a
+ * @param {ReturnType<typeof readLockIdentity>} b
+ * @returns {boolean}
+ */
+function sameLockIdentity(a, b) {
+  if (!a || !b) return false;
+  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
@@ -103,6 +236,11 @@ function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
  * @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.
  * @returns {{ acquired: true, release: () => void, ownerId: string }
  *          | { acquired: false, reason: 'contended' | 'error', detail?: string }}
  */
@@ -112,6 +250,9 @@ export function acquireSweepLock({
   ownerId,
   nowFn = Date.now,
   fsImpl = fs,
+  heartbeatMs,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
 } = {}) {
   if (typeof lockPath !== 'string' || lockPath.length === 0) {
     return {
@@ -121,22 +262,21 @@ export function acquireSweepLock({
     };
   }
   const id = ownerId ?? `pid-${process.pid}-${nowFn()}`;
+  const holder = {
+    lockPath,
+    ownerId: id,
+    fsImpl,
+    nowFn,
+    heartbeatMs: heartbeatMs ?? heartbeatIntervalFor(timeoutMs),
+    setIntervalFn,
+    clearIntervalFn,
+  };
   try {
-    if (tryCreateLock(lockPath, id, fsImpl)) {
-      return buildAcquired(lockPath, id, fsImpl);
-    }
-    // Contended. Check for stale and retry once if so.
-    const mtime = readLockMtime(lockPath, fsImpl);
-    if (isLockStale(mtime, nowFn(), timeoutMs)) {
-      try {
-        fsImpl.unlinkSync(lockPath);
-      } catch {
-        // Race: another holder may have refreshed the lock between
-        // our stat and our unlink. Fall through and report contended.
-      }
-      if (tryCreateLock(lockPath, id, fsImpl)) {
-        return buildAcquired(lockPath, id, fsImpl);
-      }
+    if (
+      tryCreateLock(lockPath, id, fsImpl) ||
+      tryStaleTakeover(holder, timeoutMs)
+    ) {
+      return buildAcquired(holder);
     }
     return { acquired: false, reason: 'contended' };
   } catch (err) {
@@ -148,16 +288,126 @@ export function acquireSweepLock({
   }
 }
 
-function buildAcquired(lockPath, ownerId, fsImpl) {
+/**
+ * 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.
+ *
+ * @param {{ lockPath: string, ownerId: string, fsImpl: object, nowFn: () => number }} holder
+ * @param {number} timeoutMs
+ * @returns {boolean}
+ */
+function tryStaleTakeover({ lockPath, ownerId, fsImpl, nowFn }, timeoutMs) {
+  const observed = readLockIdentity(lockPath, fsImpl);
+  if (observed === null) return false;
+  if (!isLockStale(observed.mtimeMs, nowFn(), timeoutMs)) return false;
+  return (
+    breakStaleLock(lockPath, observed, fsImpl) &&
+    tryCreateLock(lockPath, ownerId, fsImpl)
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param {string} lockPath
+ * @param {ReturnType<typeof readLockIdentity>} observed
+ * @param {object} fsImpl
+ * @returns {boolean}
+ */
+function breakStaleLock(lockPath, observed, fsImpl) {
+  if (!sameLockIdentity(observed, readLockIdentity(lockPath, fsImpl))) {
+    return false;
+  }
+  try {
+    fsImpl.unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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.
+ *
+ * @returns {boolean} `true` when the refresh landed; `false` when the lock is
+ *   no longer ours (the caller stops heartbeating).
+ */
+function refreshLockMtime({ lockPath, ownerId, fsImpl, nowFn }) {
+  if (readLockOwner(lockPath, fsImpl) !== ownerId) return false;
+  try {
+    const stamp = new Date(nowFn());
+    fsImpl.utimesSync(lockPath, stamp, stamp);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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.
+ */
+function startHeartbeat(holder) {
+  const { heartbeatMs, setIntervalFn, clearIntervalFn } = holder;
+  if (!(heartbeatMs > 0) || typeof setIntervalFn !== 'function') {
+    return () => {};
+  }
+  let timer = null;
+  const stop = () => {
+    if (timer === null) return;
+    const handle = timer;
+    timer = null;
+    try {
+      clearIntervalFn(handle);
+    } catch {
+      // Best-effort: a fake timer seam may not implement clear.
+    }
+  };
+  timer = setIntervalFn(() => {
+    if (!refreshLockMtime(holder)) stop();
+  }, heartbeatMs);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return stop;
+}
+
+/**
+ * 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
+ */
+function unlinkIfOwned(lockPath, ownerId, fsImpl) {
+  if (readLockOwner(lockPath, fsImpl) !== ownerId) return;
+  try {
+    fsImpl.unlinkSync(lockPath);
+  } catch {
+    // Already gone — nothing to do.
+  }
+}
+
+function buildAcquired(holder) {
+  const { lockPath, ownerId, fsImpl } = holder;
+  const stopHeartbeat = startHeartbeat(holder);
   let released = false;
   const release = () => {
     if (released) return;
     released = true;
-    try {
-      fsImpl.unlinkSync(lockPath);
-    } catch {
-      // Already gone — nothing to do.
-    }
+    stopHeartbeat();
+    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.
@@ -209,6 +459,9 @@ function defaultSleep(ms) {
  * @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.
  * @returns {Promise<{ acquired: true, release: () => void, ownerId: string }
  *          | { acquired: false, reason: 'contended-after-wait' | 'error', detail?: string }>}
  */
@@ -221,6 +474,9 @@ export async function acquireLockWithWait({
   nowFn = Date.now,
   sleepFn = defaultSleep,
   fsImpl = fs,
+  heartbeatMs,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
 } = {}) {
   const deadline = nowFn() + Math.max(0, waitMs);
   for (;;) {
@@ -230,6 +486,9 @@ export async function acquireLockWithWait({
       ownerId,
       nowFn,
       fsImpl,
+      heartbeatMs,
+      setIntervalFn,
+      clearIntervalFn,
     });
     if (res.acquired) return res;
     // A hard error will not resolve by retrying — surface it immediately.

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -13,7 +13,7 @@ import path from 'node:path';
  * @param {string} rootDir
  * @returns {string[]} absolute paths
  */
-export function walkSkillFiles(rootDir) {
+function walkSkillFiles(rootDir) {
   const out = [];
   if (!fs.existsSync(rootDir)) return out;
   const stack = [rootDir];

package/.agents/scripts/lib/source-text/strip-js-comments.js

@@ -0,0 +1,115 @@
+// .agents/scripts/lib/source-text/strip-js-comments.js
+/**
+ * The one string-literal-aware JavaScript comment stripper.
+ *
+ * Several guards in this repository grep source text for a pattern that must
+ * appear in real code rather than in a docblock — a CLI citation, an import
+ * specifier, a schema path. Each grew its own stripper, and the four
+ * implementations disagreed on what a stripped block comment leaves behind:
+ * one preserved newlines only, one deleted the comment outright (losing line
+ * numbers), one blanked it to whitespace, and one used a regex that did not
+ * honour string literals at all. A fix to any of them silently missed the
+ * others, and a guard whose own rationale mentions the pattern it greps for
+ * can satisfy itself if the stripping is wrong.
+ *
+ * **Semantics: comment bodies become equivalent whitespace.** Every character
+ * of a comment is replaced by a space except newlines, which survive. That is
+ * the most information-preserving of the four behaviours and the only one that
+ * is safe for all of them:
+ *
+ *   - line and column positions are unchanged, so a guard can report a
+ *     `file:line` that matches the original source;
+ *   - a regex looking for code cannot match comment text, because none
+ *     survives;
+ *   - the output is the same length as the input, so byte offsets hold.
+ *
+ * String and template literals are copied through verbatim, so a `//` inside a
+ * URL or a `/*` inside a message is not mistaken for a comment opener. Escape
+ * sequences are honoured, so an escaped quote does not end the literal early.
+ *
+ * An unterminated comment or literal runs to end of input rather than
+ * throwing: this is a lint helper reading files that may be mid-edit, and a
+ * crash there would be a worse failure than a slightly over-stripped tail.
+ *
+ * Builtins only — no dependency, so the guards that run before a consumer's
+ * install can use it.
+ */
+
+/**
+ * Replace every non-newline character of `text` with a space.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function blank(text) {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+/**
+ * Index just past the string or template literal opening at `start`.
+ * Runs to end of input when the literal is never closed.
+ *
+ * @param {string} text
+ * @param {number} start - index of the opening quote
+ * @returns {number}
+ */
+function endOfLiteral(text, start) {
+  const quote = text[start];
+  let i = start + 1;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    i += 1;
+  }
+  return text.length;
+}
+
+/**
+ * Strip JavaScript comments, replacing their bodies with equivalent
+ * whitespace so line numbers, columns and byte offsets all survive.
+ *
+ * @param {string} source - JavaScript source text. Nullish is treated as empty.
+ * @returns {string} the source with every comment body blanked to whitespace
+ */
+export function stripJsComments(source) {
+  const text = String(source ?? '');
+  let out = '';
+  let i = 0;
+
+  while (i < text.length) {
+    const two = text.slice(i, i + 2);
+
+    if (two === '//') {
+      const newline = text.indexOf('\n', i);
+      const stop = newline === -1 ? text.length : newline;
+      out += blank(text.slice(i, stop));
+      i = stop;
+      continue;
+    }
+
+    if (two === '/*') {
+      const close = text.indexOf('*/', i + 2);
+      const stop = close === -1 ? text.length : close + 2;
+      out += blank(text.slice(i, stop));
+      i = stop;
+      continue;
+    }
+
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const stop = endOfLiteral(text, i);
+      out += text.slice(i, stop);
+      i = stop;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+}

package/.agents/scripts/lib/test-isolate/runner.js

@@ -58,7 +58,7 @@ const NODE_TEST_BASE = [
  * @param {typeof spawn} [opts.spawnFn]
  * @returns {Promise<IsolatedResult>}
  */
-export function runFileIsolated({
+function runFileIsolated({
   repoRoot,
   file,
   envOutDir,
@@ -195,7 +195,7 @@ function sanitizeEnv(source) {
  * @param {typeof spawn} [opts.spawnFn]
  * @returns {Promise<{ results: SuiteResult[], exitCode: number, stdout: string, stderr: string }>}
  */
-export function runSuite({
+function runSuite({
   repoRoot,
   files,
   concurrency = 8,
@@ -266,7 +266,7 @@ export function runSuite({
  * @param {(r: IsolatedResult) => void} [opts.onResult]
  * @returns {Promise<IsolatedResult[]>}
  */
-export async function runIsolatedPool({
+async function runIsolatedPool({
   repoRoot,
   files,
   envOutDir,

package/.agents/scripts/lib/test-runner-contract.js

@@ -90,13 +90,20 @@ export const TEST_RUNNER_FLAGS = Object.freeze([
  * the spawns `runTierPreflight` actually issues — which is the thing that
  * has to be true.
  */
+const STATE_PROBE_ONLY = Object.freeze(['.agents/scripts/test-wrapper.js']);
+
 const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
   full: Object.freeze([
-    '.agents/scripts/test-wrapper.js',
+    ...STATE_PROBE_ONLY,
     '.agents/scripts/validate-skills.js',
   ]),
-  quick: Object.freeze(['.agents/scripts/test-wrapper.js']),
-  integration: Object.freeze(['.agents/scripts/test-wrapper.js']),
+  quick: STATE_PROBE_ONLY,
+  integration: STATE_PROBE_ONLY,
+  // Story #5111: the `e2e` tier gets the state probe like every other
+  // non-full tier. An absent entry is not a neutral default — the lookup
+  // below falls through to `[]`, so a tier missing from this map runs *no*
+  // preflight at all and the omission is invisible in a green run.
+  e2e: STATE_PROBE_ONLY,
 });
 
 /**
@@ -108,7 +115,7 @@ const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
  * executes, which the npm hook does not under `ignore-scripts=true`.
  *
  * @param {object} [opts]
- * @param {'full' | 'quick' | 'integration'} [opts.tier]
+ * @param {'full' | 'quick' | 'integration' | 'e2e'} [opts.tier]
  * @param {string} [opts.repoRoot] Absolute repository root.
  * @param {typeof spawnSync} [opts.spawn] Injected in tests.
  * @param {string} [opts.execPath] Node binary to spawn; injected in tests.
@@ -127,8 +134,9 @@ export function runTierPreflight({
       stdio: 'inherit',
     });
     if (run.error) throw run.error;
-    const status = run.status ?? 1;
-    if (status !== 0) return status;
+    // A signal-killed child reports `status: null`; treat that as the
+    // reserved failure code rather than letting it read as "not zero, no code".
+    if (run.status !== 0) return run.status ?? 1;
   }
   return 0;
 }