mandrel 2.36.0 → 2.37.0

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -29,8 +29,9 @@
  *                       a claim back from whoever took over).
  *
  * Provider contract (a subset of `ITicketingProvider`):
- *   - `getTicket(id)`            → `{ assignees: string[], ... }`
- *   - `updateTicket(id, { assignees })` writes the assignee list.
+ *   - `getTicket(id)`               → `{ assignees: string[], ... }`
+ *   - `updateTicket(id, { assignees })`    replaces the assignee list.
+ *   - `updateTicket(id, { addAssignees })` appends to it (Story #5112).
  */
 
 /**
@@ -128,11 +129,13 @@ function normaliseOpts(op, opts) {
  *                                     operator out, `acquired: false`,
  *                                     `owner: <foreign>`, `reason: 'lost-race'`.
  *
- * Every claiming write is verified: GitHub's assignee PATCH is not a
+ * Every claiming write is verified: GitHub's assignee write is not a
  * compare-and-set, so two runs that both read the ticket unassigned will both
  * write themselves. {@link claimAndVerify} re-reads after the write and refuses
  * (fail-closed) when a foreign login is present, so the loser of a simultaneous
- * claim never proceeds as though it holds the lease.
+ * claim never proceeds as though it holds the lease. Story #5112 made the
+ * first claim **additive** so that verify can actually see the collision —
+ * see {@link claimAndVerify}.
  *
  * @param {object} opts
  * @param {object} opts.provider              Ticketing provider.
@@ -199,7 +202,7 @@ export async function acquireLease(opts) {
  *
  * The assignee write is not atomic — GitHub offers no compare-and-set on the
  * assignees surface — so two runs that both observed the ticket unassigned (or
- * a stale foreign claim) will both PATCH themselves in. Without a check the
+ * a stale foreign claim) will both write themselves in. Without a check the
  * loser of that race returns `acquired: true` and marches into the worktree
  * the winner is already building. The verify closes that window: it re-reads
  * with `fresh: true` (bypassing any provider cache so it sees the other run's
@@ -208,9 +211,16 @@ export async function acquireLease(opts) {
  * returns `acquired: false` / `reason: 'lost-race'` so the fail-closed caller
  * refuses. A clean read (assignees exactly `[operator]`) confirms the claim.
  *
- * It does not eliminate the race — two writes still happen — but it makes the
- * outcome deterministic: exactly one operator survives as the sole assignee,
- * and the other is told it lost.
+ * **The write must be additive for the verify to work (Story #5112).** With
+ * the replacing PATCH this used unconditionally, a simultaneous claim
+ * *evicted* the other operator rather than joining it, so the co-assignment
+ * the `lost-race` branch keys on was a state the PATCH could never produce:
+ * each run read a clean `[self]` on verify and both proceeded. Claiming an
+ * unowned ticket therefore goes through the additive assignees endpoint
+ * (`addAssignees`), which makes the collision observable and lets exactly one
+ * claimer survive. The replacing form stays for the two cases that genuinely
+ * mean "replace": the `--steal` transfer of a foreign claim, and the loser's
+ * own back-out below.
  *
  * @param {object} args
  * @param {object} args.provider              Ticketing provider.
@@ -220,6 +230,21 @@ export async function acquireLease(opts) {
  * @param {string} args.reason                Success reason when the claim holds.
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  */
+/**
+ * The assignee mutation a claim writes. Additive when the ticket has no
+ * previous owner — that is what makes a simultaneous claim show up as a
+ * co-assignment {@link claimAndVerify} can detect. Replacing only for a
+ * steal, where evicting the previous owner *is* the intent.
+ *
+ * @param {string} operator
+ * @param {string|null} previousOwner
+ * @returns {{ addAssignees: string[] }|{ assignees: string[] }}
+ */
+function claimMutation(operator, previousOwner) {
+  if (previousOwner === null) return { addAssignees: [operator] };
+  return { assignees: [operator] };
+}
+
 async function claimAndVerify({
   provider,
   ticketId,
@@ -227,7 +252,7 @@ async function claimAndVerify({
   previousOwner,
   reason,
 }) {
-  await provider.updateTicket(ticketId, { assignees: [operator] });
+  await provider.updateTicket(ticketId, claimMutation(operator, previousOwner));
 
   const after = await provider.getTicket(ticketId, { fresh: true });
   const assignees = Array.isArray(after?.assignees) ? after.assignees : [];

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -81,7 +81,9 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
-  'parked-follow-ons',
+  // `parked-follow-ons` retired in Story #5114 with the module that was its
+  // only writer. A kind the reader still recognises but nothing emits is the
+  // same dead wiring in a new place.
   // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
   // Story #831 — story-init upserts a `story-init` comment that

package/.agents/scripts/lib/preflight-runner.js

@@ -124,7 +124,7 @@ function pick(logger, level) {
  * @param {Array<object>} fixed
  * @param {object} [logger]
  */
-export function logFixes(fixed, logger = DEFAULT_LOGGER) {
+function logFixes(fixed, logger = DEFAULT_LOGGER) {
   const info = pick(logger, 'info');
   info(`[preflight] auto-fixed ${fixed.length} finding(s):`);
   for (const f of fixed) {
@@ -141,7 +141,7 @@ export function logFixes(fixed, logger = DEFAULT_LOGGER) {
  * @param {Array<object>} blockers
  * @param {object} [logger]
  */
-export function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
+function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
   const error = pick(logger, 'error');
   error(
     `[preflight] ${scope}: ${blockers.length} blocker finding(s) — refusing to proceed.`,
@@ -180,7 +180,7 @@ export function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
  * @param {Array<object>} findings
  * @param {object} [logger]
  */
-export function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
+function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
   const warn = pick(logger, 'warn');
   for (const f of findings) {
     warn(`[preflight] ${f.severity}: ${f.id} — ${f.summary ?? ''}`);

package/.agents/scripts/lib/qa/qa-session.js

@@ -36,7 +36,7 @@ import path from 'node:path';
 import { tempRootFrom } from '../config/temp-paths.js';
 
 /** Directory segment (under `tempRoot`) that holds every QA session ledger. */
-export const QA_LEDGER_DIRNAME = 'qa';
+const QA_LEDGER_DIRNAME = 'qa';
 
 /**
  * Triaged dispositions, mirrored from the `disposition` enum in

package/.agents/scripts/lib/runtime-deps/manifest.js

@@ -26,13 +26,7 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
  * `.agents/scripts/lib/runtime-deps/`; the manifest sits at the `.agents/`
  * root, three directories up.
  */
-export const MANIFEST_PATH = path.resolve(
-  HERE,
-  '..',
-  '..',
-  '..',
-  'runtime-deps.json',
-);
+const MANIFEST_PATH = path.resolve(HERE, '..', '..', '..', 'runtime-deps.json');
 
 /**
  * @typedef {object} RuntimeDepsManifest

package/.agents/scripts/lib/runtime-deps/scan-imports.js

@@ -26,9 +26,10 @@
 import fs from 'node:fs';
 import { builtinModules } from 'node:module';
 import path from 'node:path';
+import { stripJsComments } from '../source-text/strip-js-comments.js';
 
 /** Node builtins, with and without the `node:` prefix. */
-export const BUILTIN_MODULES = new Set([
+const BUILTIN_MODULES = new Set([
   ...builtinModules,
   ...builtinModules.map((m) => `node:${m}`),
 ]);
@@ -71,62 +72,6 @@ const SIDE_EFFECT = /^\s*import\s*['"]([^'"]+)['"]/gm;
 // `require(...)` and dynamic `import(...)` may appear mid-expression.
 const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
 
-/**
- * Remove `//` line comments and block comments while preserving string and
- * template literals (which carry the import specifiers we extract). A
- * char-by-char state machine is used rather than a regex so that comment
- * markers inside string literals (e.g. a `https://` URL) are not mistaken
- * for comments, and example import syntax inside *comments* (e.g. a
- * `// require('x')` doc line) does not register as a phantom dependency.
- *
- * @param {string} source
- * @returns {string}
- */
-export function stripComments(source) {
-  let out = '';
-  let i = 0;
-  const n = source.length;
-  while (i < n) {
-    const ch = source[i];
-    const next = source[i + 1];
-    // Enter a string / template literal — copy verbatim until it closes.
-    if (ch === '"' || ch === "'" || ch === '`') {
-      const quote = ch;
-      out += ch;
-      i += 1;
-      while (i < n) {
-        const c = source[i];
-        out += c;
-        if (c === '\\') {
-          // Copy the escaped char too, then continue.
-          if (i + 1 < n) out += source[i + 1];
-          i += 2;
-          continue;
-        }
-        i += 1;
-        if (c === quote) break;
-      }
-      continue;
-    }
-    // Line comment — drop to end of line (keep the newline).
-    if (ch === '/' && next === '/') {
-      i += 2;
-      while (i < n && source[i] !== '\n') i += 1;
-      continue;
-    }
-    // Block comment — drop until the closing `*/`.
-    if (ch === '/' && next === '*') {
-      i += 2;
-      while (i < n && !(source[i] === '*' && source[i + 1] === '/')) i += 1;
-      i += 2;
-      continue;
-    }
-    out += ch;
-    i += 1;
-  }
-  return out;
-}
-
 /**
  * Extract the set of third-party top-level package names imported by a
  * single source string.
@@ -136,7 +81,7 @@ export function stripComments(source) {
  */
 export function extractThirdPartyImports(source) {
   const found = new Set();
-  const cleaned = stripComments(source);
+  const cleaned = stripJsComments(source);
   for (const re of [STATIC_FROM, SIDE_EFFECT, CALL_FORM]) {
     re.lastIndex = 0;
     let match = re.exec(cleaned);

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