mandrel 2.53.0 → 2.55.0

package/.agents/scripts/lib/orchestration/verify-credit.js

@@ -42,6 +42,39 @@ const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
 /** Script names that mean "the whole suite" rather than a scoped subset. */
 const FULL_SUITE_SCRIPTS = new Set(['test', 'test:coverage']);
 
+/**
+ * Flags that narrow a runner's work to a subset of the suite (Story #5278).
+ *
+ * A positional path is not the only way to scope a run: Node's test runner
+ * takes filter flags that select a fraction of the tests while the argv still
+ * reads as a bare `node --test`. Crediting one of those against the full-suite
+ * stamp reports a filtered run as the whole suite — the exact false positive
+ * {@link isFullSuiteCommand} exists to refuse. Matched by prefix so both
+ * spellings (`--test-only`, `--test-name-pattern=x`, `--test-name-pattern x`)
+ * are caught.
+ */
+const NARROWING_FLAGS = Object.freeze([
+  '--test-name-pattern',
+  '--test-skip-pattern',
+  '--test-only',
+]);
+
+/**
+ * Does any token narrow the run to a subset of the suite? Pure helper for
+ * {@link isFullSuiteCommand}, split out so that function's own branching stays
+ * inside its committed cyclomatic budget.
+ *
+ * @param {string[]} tokens
+ * @returns {boolean}
+ */
+function hasNarrowingFlag(tokens) {
+  return tokens.some((token) =>
+    NARROWING_FLAGS.some(
+      (flag) => token === flag || token.startsWith(`${flag}=`),
+    ),
+  );
+}
+
 /**
  * Split a Story `verify[]` line into its command and its tier tag.
  *
@@ -76,6 +109,10 @@ export function isFullSuiteCommand(command) {
     .split(/\s+/)
     .filter(Boolean);
   if (tokens.length === 0) return false;
+  // A narrowing flag scopes the run wherever it appears — before the package
+  // manager's `--` as much as after it — so the probe runs over the whole
+  // token list rather than per-branch below.
+  if (hasNarrowingFlag(tokens)) return false;
 
   if (tokens[0] === 'node') {
     // `node --test` with no path argument walks the default test globs.

package/.agents/scripts/lib/pinned-override-notes.js

@@ -20,30 +20,13 @@
 /** A `"//"` key that documents a pinned override, e.g. `overrides.js-yaml`. */
 const OVERRIDE_NOTE_KEY = /^overrides\.(.+)$/;
 
-/**
- * Extract every semver range that appears literally in a note's prose.
- *
- * Deliberately permissive about the surrounding words — a note is prose, and
- * pinning its phrasing would make it unwritable. What matters is only that
- * the range it quotes is the range in force.
- *
- * Not exported: it is an implementation detail of the audit below, and its
- * behaviour is observable through that — a note quoting only bare versions
- * yields no `stale-note`, a note quoting a mismatched range yields one.
- *
- * @param {string} text
- * @returns {string[]}
- */
-function quotedRanges(text) {
-  if (typeof text !== 'string') return [];
-  return [...text.matchAll(/[\^~]\d+\.\d+\.\d+/g)].map((m) => m[0]);
-}
+import { resolvePin, scoreNote } from './pinned-override-resolve.js';
 
 /**
  * Audit one package document's pinned-override notes.
  *
- * Two findings per documented override, each naming the drift rather than
- * just asserting a mismatch:
+ * Findings per documented override, each naming the drift rather than just
+ * asserting a mismatch:
  *   - `lockstep` — `overrides.<name>` and `dependencies.<name>` disagree. The
  *     companion note declares they must not; a split silently gives the
  *     direct and transitive resolutions different floors.
@@ -51,50 +34,55 @@ function quotedRanges(text) {
  *     force, so its stated version is behind the pin it describes. A note
  *     quoting no range at all is not scored: prose that names no version
  *     cannot go stale.
+ *   - `unsupported-shape` — the note's key resolves to something that is not a
+ *     range (a nested override object, or a `$name` reference to a dependency
+ *     that does not exist). Distinct from `orphan-note`: the pin is *there*,
+ *     the note just does not name it, and telling an author to "delete the note
+ *     or restore the pin" would be wrong advice.
  *
  * @param {{ '//'?: Record<string,string>, overrides?: Record<string,string>, dependencies?: Record<string,string> }} pkg
  * @returns {{ findings: Array<{ kind: string, name: string, detail: string }>, checked: string[] }}
  */
 export function auditPinnedOverrideNotes(pkg) {
-  const notes = pkg?.['//'] ?? {};
   const overrides = pkg?.overrides ?? {};
   const dependencies = pkg?.dependencies ?? {};
   const findings = [];
   const checked = [];
 
-  for (const [key, text] of Object.entries(notes)) {
-    const match = OVERRIDE_NOTE_KEY.exec(key);
-    if (!match) continue;
-    const name = match[1];
-    const pinned = overrides[name];
-    if (typeof pinned !== 'string') {
-      findings.push({
-        kind: 'orphan-note',
-        name,
-        detail: `"//"["${key}"] documents an override that no longer exists in the overrides block. Delete the note or restore the pin — a safety note for a pin nobody has is read as though the pin were still there.`,
-      });
-      continue;
-    }
-    checked.push(name);
-
-    const direct = dependencies[name];
-    if (typeof direct === 'string' && direct !== pinned) {
-      findings.push({
-        kind: 'lockstep',
-        name,
-        detail: `overrides.${name} is "${pinned}" but dependencies.${name} is "${direct}". The "//" note declares these move in lockstep; a split gives the direct and transitive resolutions different floors.`,
-      });
-    }
-
-    const quoted = quotedRanges(text);
-    if (quoted.length > 0 && !quoted.includes(pinned)) {
-      findings.push({
-        kind: 'stale-note',
-        name,
-        detail: `"//"["${key}"] quotes ${quoted.map((q) => `"${q}"`).join(', ')} but the pin in force is "${pinned}". The note is what tells the next author whether a bump is safe, so it must state the version it is describing.`,
-      });
-    }
+  for (const { key, name, text } of documentedOverrides(pkg)) {
+    const resolved = resolvePin({ overrides, dependencies, name });
+    if (isCheckable(resolved)) checked.push(name);
+    findings.push(
+      ...scoreNote({ key, name, text, resolved, direct: dependencies[name] }),
+    );
   }
 
   return { findings, checked };
 }
+
+/**
+ * The `"//"` entries that document an override, as `{ key, name, text }`.
+ * Every other note in the block — a peer-dependency rationale, say — is not
+ * this gate's business and is skipped rather than scored.
+ *
+ * @param {object} pkg
+ * @returns {Array<{ key: string, name: string, text: unknown }>}
+ */
+function documentedOverrides(pkg) {
+  return Object.entries(pkg?.['//'] ?? {})
+    .map(([key, text]) => ({ key, text, match: OVERRIDE_NOTE_KEY.exec(key) }))
+    .filter((entry) => entry.match !== null)
+    .map(({ key, text, match }) => ({ key, text, name: match[1] }));
+}
+
+/**
+ * Was the note's override resolved to a range at all? Only then does the name
+ * belong in `checked` — the list is what tells a caller which pins this gate
+ * actually stands behind.
+ *
+ * @param {{ kind: string }} resolved
+ * @returns {boolean}
+ */
+function isCheckable(resolved) {
+  return resolved.kind !== 'missing' && resolved.kind !== 'unsupported';
+}

package/.agents/scripts/lib/pinned-override-resolve.js

@@ -0,0 +1,212 @@
+/**
+ * pinned-override-resolve.js — resolve a documented override, and score its note.
+ *
+ * The reading half of `pinned-override-notes.js` next door: how an
+ * `overrides` entry resolves to the range it actually imposes, and which
+ * findings that range earns against the note describing it. The audit loop
+ * stays there; everything a single note is judged by lives here.
+ *
+ * Pure: no filesystem, no npm, no network. The caller supplies the parsed
+ * package document.
+ */
+
+/**
+ * npm's own reference syntax inside an `overrides` block: `"js-yaml": "$js-yaml"`
+ * means "whatever `dependencies.js-yaml` says". It is the sanctioned way to
+ * express the lockstep coupling these notes describe, so reading it as a
+ * literal range — which is what a bare string compare does — flagged the fix as
+ * the defect: `"$js-yaml" !== "^4.3.2"` produced a `lockstep` finding against a
+ * pair that npm guarantees can never split, and a `stale-note` against a note
+ * quoting the range actually in force.
+ */
+const OVERRIDE_REFERENCE = /^\$(.*)$/;
+
+/**
+ * A semver **range**, not only a caret/tilde one. The old pattern required a
+ * `^` or `~` prefix, so a note describing an exact pin (`"1.2.3"`) quoted a
+ * version the matcher could not see: `quoted` came back empty, the staleness
+ * check short-circuits on an empty list, and the note was silently exempt from
+ * the guarantee it exists to provide.
+ */
+const SEMVER_RANGE = /(?:[\^~]|>=?|<=?|=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g;
+
+/**
+ * Extract every semver range that appears literally in a note's prose.
+ *
+ * Deliberately permissive about the surrounding words — a note is prose, and
+ * pinning its phrasing would make it unwritable. What matters is only that
+ * the range it quotes is the range in force.
+ *
+ * Not exported: it is an implementation detail of the audit below, and its
+ * behaviour is observable through that — a note quoting only bare versions
+ * yields no `stale-note`, a note quoting a mismatched range yields one.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function quotedRanges(text) {
+  if (typeof text !== 'string') return [];
+  return [...text.matchAll(SEMVER_RANGE)].map((m) => m[0]);
+}
+
+/**
+ * Look a dotted note key up in the `overrides` tree.
+ *
+ * An `overrides` value may be a nested object — `{"foo": {"bar": "1.2.3"}}`
+ * scopes the `bar` override to `foo`'s subtree — so `overrides.foo.bar` names a
+ * real pin two levels down. The exact key is tried first at every level,
+ * because package names legitimately contain dots (`lodash.merge`), and only
+ * then is the key split.
+ *
+ * @param {unknown} node
+ * @param {string} dottedName
+ * @returns {{ found: boolean, value?: unknown }}
+ */
+function lookupOverride(node, dottedName) {
+  if (!node || typeof node !== 'object') return { found: false };
+  if (Object.hasOwn(node, dottedName)) {
+    return { found: true, value: node[dottedName] };
+  }
+  const parts = dottedName.split('.');
+  for (let i = 1; i < parts.length; i += 1) {
+    const child = node[parts.slice(0, i).join('.')];
+    const hit = lookupOverride(child, parts.slice(i).join('.'));
+    if (hit.found) return hit;
+  }
+  return { found: false };
+}
+
+/**
+ * Resolve the range a documented override actually imposes.
+ *
+ * @param {object} params
+ * @returns {{ kind: 'missing'|'pinned'|'reference'|'unsupported', range?: string,
+ *   raw?: unknown, referenced?: string, detail?: string }}
+ */
+export function resolvePin({ overrides, dependencies, name }) {
+  const hit = lookupOverride(overrides, name);
+  if (!hit.found) return { kind: 'missing' };
+  if (typeof hit.value !== 'string') {
+    return {
+      kind: 'unsupported',
+      raw: hit.value,
+      detail:
+        'resolves to a nested override object rather than a range. Key the note at the leaf ' +
+        '(e.g. "overrides.<parent>.<name>") so the range it describes is the one checked.',
+    };
+  }
+  const reference = OVERRIDE_REFERENCE.exec(hit.value);
+  return reference
+    ? resolveReference({
+        raw: hit.value,
+        target: reference[1] || name,
+        dependencies,
+      })
+    : { kind: 'pinned', range: hit.value };
+}
+
+/**
+ * Resolve npm's `"$name"` reference to the direct range it points at.
+ *
+ * @param {{ raw: string, target: string, dependencies: object }} params
+ * @returns {{ kind: 'reference'|'unsupported', range?: string, raw?: string,
+ *   referenced: string, detail?: string }}
+ */
+function resolveReference({ raw, target, dependencies }) {
+  const direct = dependencies[target];
+  if (typeof direct !== 'string') {
+    return {
+      kind: 'unsupported',
+      raw,
+      referenced: target,
+      detail: `references "${raw}", but dependencies.${target} does not exist, so npm has nothing to resolve the override to.`,
+    };
+  }
+  return { kind: 'reference', range: direct, referenced: target };
+}
+
+/**
+ * Score one documented override against its note. Split out of the loop above
+ * so each finding's rationale sits next to the condition that raises it.
+ *
+ * @param {{ key: string, name: string, text: unknown, resolved: object,
+ *   direct: string|undefined }} params
+ * @returns {Array<{ kind: string, name: string, detail: string }>}
+ */
+export function scoreNote({ key, name, text, resolved, direct }) {
+  const refusal = refuseNote({ key, name, resolved });
+  if (refusal) return [refusal];
+  return [
+    ...scoreLockstep({ name, resolved, direct }),
+    ...scoreStaleness({ key, name, text, range: resolved.range }),
+  ];
+}
+
+/**
+ * The two ways a note names nothing checkable: the pin is gone, or the key
+ * resolves to something that is not a range. They are deliberately different
+ * findings — telling an author to "delete the note or restore the pin" when the
+ * pin is right there, one level down, is wrong advice.
+ *
+ * @param {{ key: string, name: string, resolved: object }} params
+ * @returns {{ kind: string, name: string, detail: string }|null}
+ */
+function refuseNote({ key, name, resolved }) {
+  if (resolved.kind === 'missing') {
+    return {
+      kind: 'orphan-note',
+      name,
+      detail: `"//"["${key}"] documents an override that no longer exists in the overrides block. Delete the note or restore the pin — a safety note for a pin nobody has is read as though the pin were still there.`,
+    };
+  }
+  if (resolved.kind === 'unsupported') {
+    return {
+      kind: 'unsupported-shape',
+      name,
+      detail: `"//"["${key}"] ${resolved.detail}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Does the override range still agree with the direct one? A `$name` override
+ * IS `dependencies[name]`, so npm cannot split the pair the note is warning
+ * about and there is nothing to compare.
+ *
+ * @param {{ name: string, resolved: object, direct: string|undefined }} params
+ * @returns {Array<object>}
+ */
+function scoreLockstep({ name, resolved, direct }) {
+  const split =
+    resolved.kind === 'pinned' &&
+    typeof direct === 'string' &&
+    direct !== resolved.range;
+  if (!split) return [];
+  return [
+    {
+      kind: 'lockstep',
+      name,
+      detail: `overrides.${name} is "${resolved.range}" but dependencies.${name} is "${direct}". The "//" note declares these move in lockstep; a split gives the direct and transitive resolutions different floors. npm's own "$${name}" reference is the way to make the split impossible.`,
+    },
+  ];
+}
+
+/**
+ * Does the note still state the range in force? A note quoting no range at all
+ * is not scored: prose that names no version cannot go stale.
+ *
+ * @param {{ key: string, name: string, text: unknown, range: string }} params
+ * @returns {Array<object>}
+ */
+function scoreStaleness({ key, name, text, range }) {
+  const quoted = quotedRanges(text);
+  if (quoted.length === 0 || quoted.includes(range)) return [];
+  return [
+    {
+      kind: 'stale-note',
+      name,
+      detail: `"//"["${key}"] quotes ${quoted.map((q) => `"${q}"`).join(', ')} but the range in force is "${range}". The note is what tells the next author whether a bump is safe, so it must state the version it is describing.`,
+    },
+  ];
+}

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -265,6 +265,14 @@ function toOrigin(value) {
  * than mid-sweep. The resolved `SKILL.md` path is attached as
  * `skillPath` so the harness reads the file the check actually found.
  *
+ * The two failures get **different** messages (Story #5285). A well-formed id
+ * that resolves nowhere is a skill to author; a malformed one is an id to
+ * fix, and telling the operator to author `../../secrets/SKILL.md` would be
+ * advice they cannot take. A config validated against the shipped schema
+ * never reaches the malformed branch — the `pattern` rejects it first — but
+ * this resolver also runs over hand-assembled contracts in tests and over
+ * configs loaded past a degraded validator, so the branch is real.
+ *
  * @param {object | undefined} seam
  * @param {string} envName Environment name, for the error message.
  * @param {{ repoRoot?: string }} options
@@ -276,6 +284,16 @@ function resolveSignInSeam(seam, envName, options) {
 
   const repoRoot = options.repoRoot ?? PROJECT_ROOT;
   const found = resolveSkillFile(repoRoot, seam.skill);
+  if (found?.reason === 'invalid-id') {
+    throw new Error(
+      `qa: environment \`${envName}\` declares signInSeam.skill ` +
+        `\`${seam.skill}\`, which is not a well-formed skill id. ` +
+        'An id is two or more lowercase segments of letters, digits, `.`, ' +
+        '`_` or `-` joined by `/` — e.g. `stack/qa/acme-sso`. Traversals, ' +
+        'absolute paths, backslashes and uppercase segments are rejected ' +
+        'outright, so no skills root was searched. Correct the id.',
+    );
+  }
   if (found === null) {
     throw new Error(
       `qa: environment \`${envName}\` declares signInSeam.skill ` +

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

@@ -102,6 +102,44 @@ 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.
+ */
+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.
+ *
+ * @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)) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'ESRCH' ? false : true;
+  }
+}
+
 /**
  * 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` +
@@ -265,7 +303,11 @@ function tryCreateLock(lockPath, ownerId, fsImpl = fs) {
  *                                         `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 }
+ * @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 }
  *          | { acquired: false, reason: 'contended' | 'error', detail?: string }}
  */
 export function acquireSweepLock({
@@ -277,6 +319,8 @@ export function acquireSweepLock({
   heartbeatMs,
   setIntervalFn = setInterval,
   clearIntervalFn = clearInterval,
+  killFn,
+  processImpl = process,
 } = {}) {
   if (typeof lockPath !== 'string' || lockPath.length === 0) {
     return {
@@ -294,6 +338,8 @@ export function acquireSweepLock({
     heartbeatMs: heartbeatMs ?? heartbeatIntervalFor(timeoutMs),
     setIntervalFn,
     clearIntervalFn,
+    killFn,
+    processImpl,
   };
   try {
     if (
@@ -321,16 +367,56 @@ export function acquireSweepLock({
  * @param {number} timeoutMs
  * @returns {boolean}
  */
-function tryStaleTakeover({ lockPath, ownerId, fsImpl, nowFn }, timeoutMs) {
+function tryStaleTakeover(
+  { lockPath, ownerId, fsImpl, nowFn, killFn },
+  timeoutMs,
+) {
   const observed = readLockIdentity(lockPath, fsImpl);
   if (observed === null) return false;
-  if (!isLockStale(observed.mtimeMs, nowFn(), timeoutMs)) return false;
+  if (
+    !isHolderStale({ lockPath, fsImpl, nowFn, killFn, observed, timeoutMs })
+  ) {
+    return false;
+  }
   return (
     breakStaleLock(lockPath, observed, fsImpl) &&
     tryCreateLock(lockPath, ownerId, fsImpl)
   );
 }
 
+/**
+ * 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.
+ *
+ * @param {{ lockPath: string, fsImpl: object, nowFn: () => number, killFn?: Function, observed: {mtimeMs: number}, timeoutMs: number }} args
+ * @returns {boolean}
+ */
+function isHolderStale({
+  lockPath,
+  fsImpl,
+  nowFn,
+  killFn,
+  observed,
+  timeoutMs,
+}) {
+  if (isHolderAlive(readLockHolderPid(lockPath, fsImpl), killFn) === false) {
+    return true;
+  }
+  return isLockStale(observed.mtimeMs, nowFn(), timeoutMs);
+}
+
 /**
  * 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
@@ -362,10 +448,23 @@ function breakStaleLock(lockPath, observed, fsImpl) {
  * 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.
+ *
+ * @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).
  */
-function refreshLockMtime({ lockPath, ownerId, fsImpl, nowFn }) {
+export function refreshLockSync({
+  lockPath,
+  ownerId,
+  fsImpl = fs,
+  nowFn = Date.now,
+}) {
   if (readLockOwner(lockPath, fsImpl) !== ownerId) return false;
   try {
     const stamp = new Date(nowFn());
@@ -398,7 +497,7 @@ function startHeartbeat(holder) {
     }
   };
   timer = setIntervalFn(() => {
-    if (!refreshLockMtime(holder)) stop();
+    if (!refreshLockSync(holder)) stop();
   }, heartbeatMs);
   if (timer && typeof timer.unref === 'function') timer.unref();
   return stop;
@@ -424,22 +523,83 @@ function unlinkIfOwned(lockPath, ownerId, fsImpl) {
 }
 
 function buildAcquired(holder) {
-  const { lockPath, ownerId, fsImpl } = holder;
+  const { lockPath, ownerId, fsImpl, processImpl = process } = holder;
   const stopHeartbeat = startHeartbeat(holder);
   let released = false;
+  let detachSignals = () => {};
   const release = () => {
     if (released) return;
     released = true;
     stopHeartbeat();
+    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 process.once === 'function') {
-    process.once('exit', exitCleanup);
+  if (typeof processImpl?.once === 'function') {
+    processImpl.once('exit', exitCleanup);
   }
-  return { acquired: true, release, ownerId };
+  detachSignals = attachSignalRelease(processImpl, release);
+  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.
+ *
+ * @param {object} processImpl
+ * @param {() => void} release
+ * @returns {() => void} detach
+ */
+function attachSignalRelease(processImpl, release) {
+  if (
+    typeof processImpl?.once !== 'function' ||
+    typeof processImpl?.off !== 'function' ||
+    typeof processImpl?.kill !== 'function'
+  ) {
+    return () => {};
+  }
+  const handlers = RELEASE_ON_SIGNALS.map((signal) => {
+    const handler = () => {
+      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 {
+        // A process that cannot signal itself is already on its way out.
+      }
+    };
+    processImpl.once(signal, handler);
+    return [signal, handler];
+  });
+  return () => {
+    for (const [signal, handler] of handlers) {
+      try {
+        processImpl.off(signal, handler);
+      } catch {
+        // Best-effort: a seam may not implement removal.
+      }
+    }
+  };
 }
 
 const DEFAULT_WAIT_MS = 8_000;
@@ -501,6 +661,8 @@ export async function acquireLockWithWait({
   heartbeatMs,
   setIntervalFn = setInterval,
   clearIntervalFn = clearInterval,
+  killFn,
+  processImpl,
 } = {}) {
   const deadline = nowFn() + Math.max(0, waitMs);
   for (;;) {
@@ -513,6 +675,8 @@ export async function acquireLockWithWait({
       heartbeatMs,
       setIntervalFn,
       clearIntervalFn,
+      killFn,
+      processImpl,
     });
     if (res.acquired) return res;
     // A hard error will not resolve by retrying — surface it immediately.