mandrel 2.59.0 → 2.61.0

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

@@ -1,24 +1,8 @@
 /**
- * verify-credit.js — decide whether a Story `verify[]` entry has already been
- * paid for by the delivery's single credited full-suite run (Story #5174).
- *
- * A Story's `verify[]` is meant to be *scoped* entries plus the one credited
- * full-suite run the worker makes just before the hand-off push
- * (`helpers/deliver-digest.md` § 5). When a `verify[]` entry is itself a
- * full-suite command, running it spends a second whole-suite spawn for a
- * result the credited run already established — and the close gate chain then
- * makes a third. This module is the read side of that credit: given the
- * entry's command it consults **the same stamp close consults** and reports
- * the entry as credited instead of telling the caller to spawn it.
- *
- * It only ever *reads*. Nothing here writes a capture stamp or an evidence
- * record — an entry that is not covered by a fresh stamp or a credited
- * `test` evidence record (Story #5313: a green bare `npm test` deposits one)
- * is reported `spawn: true` and runs for real, so the credit can never
- * manufacture a pass.
- *
- * @see .agents/scripts/lib/coverage-capture.js (`isCoverageFresh`)
- * @see .agents/scripts/lib/validation-evidence.js (`shouldSkip`)
+ * Report a full-suite `verify[]` entry as credited when the stamp or `test`
+ * evidence close consults already covers it, instead of respawning the suite.
+ * Read-only: an uncovered entry is `spawn: true`, so credit never
+ * manufactures a pass.
  */
 
 import { getQuality, resolveConfig } from '../config-resolver.js';
@@ -31,34 +15,17 @@ import {
   treeFingerprint,
 } from '../validation-evidence.js';
 
-/**
- * The shape a `verify[]` array is supposed to have, stated once so the
- * warning a caller surfaces and the prose in `deliver-digest.md` § 5 say the
- * same thing.
- * @type {string}
- */
+/** @type {string} */
 export const FULL_SUITE_SHAPE_WARNING =
   'verify[] should be scoped entries plus the single credited full-suite run ' +
   '(deliver-digest.md § 5) — a full-suite command listed in verify[] is ' +
   'reported credited against that run, never respawned.';
 
-/** Package managers whose `test` script means "the whole suite". */
 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.
- */
+/** Filter flags that scope a bare-looking `node --test`; `=value` form too. */
 const NARROWING_FLAGS = Object.freeze([
   '--test-name-pattern',
   '--test-skip-pattern',
@@ -66,10 +33,6 @@ const NARROWING_FLAGS = Object.freeze([
 ]);
 
 /**
- * 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}
  */
@@ -82,11 +45,8 @@ function hasNarrowingFlag(tokens) {
 }
 
 /**
- * Split a Story `verify[]` line into its command and its tier tag.
- *
- * Story bodies write entries as `` `<command>` (<tier>) `` — the tier is
- * planning metadata, not part of the command, and leaving it attached would
- * make every entry look scoped.
+ * Strip a trailing `(<tier>)` tag, which would otherwise make every entry
+ * look scoped.
  *
  * @param {string} entry
  * @returns {{ command: string, tier: string|null }}
@@ -99,12 +59,8 @@ export function parseVerifyEntry(entry) {
 }
 
 /**
- * Is this command a whole-suite run?
- *
- * Deliberately narrow. A false positive here would report a *scoped* command
- * as credited without ever running it, which is how a gate stops gating — so
- * anything carrying its own positional argument (`npm test -- tests/x.js`,
- * `node --test tests/x.js`) is scoped by construction.
+ * Deliberately narrow: a false positive credits a scoped command without
+ * running it. Any positional argument or narrowing flag means scoped.
  *
  * @param {string} command
  * @returns {boolean}
@@ -115,13 +71,9 @@ 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.
     const rest = tokens.slice(1);
     return rest.length > 0 && rest.every((t) => t.startsWith('-'));
   }
@@ -129,14 +81,10 @@ export function isFullSuiteCommand(command) {
   if (!PACKAGE_MANAGERS.has(tokens[0])) return false;
   const rest = tokens[1] === 'run' ? tokens.slice(2) : tokens.slice(1);
   if (rest.length === 0 || !FULL_SUITE_SCRIPTS.has(rest[0])) return false;
-  // `npm test -- <path>` narrows the run; only a bare invocation is the suite.
   return rest.length === 1;
 }
 
 /**
- * Read HEAD from a worktree. `null` when the tree cannot be read — which
- * routes to `spawn`, never to a credit.
- *
  * @param {string} cwd
  * @param {Function} gitSpawnFn
  * @returns {string|null}
@@ -149,15 +97,12 @@ function readHeadSha(cwd, gitSpawnFn) {
 }
 
 /**
- * Decide how a single `verify[]` entry should be executed.
- *
  * @param {object} input
- * @param {string} input.command — the entry's command (tier tag already off).
+ * @param {string} input.command — tier tag already off.
  * @param {number|string} input.storyId
- * @param {string} input.worktree — ABSOLUTE path to the Story worktree.
- * @param {string} [input.cwd] — main checkout (evidence keyspace root).
- *   Defaults to `worktree`.
- * @param {object} [deps] — test seams; every one defaults to the real impl.
+ * @param {string} input.worktree — ABSOLUTE path.
+ * @param {string} [input.cwd] — evidence keyspace root; defaults to `worktree`.
+ * @param {object} [deps] — test seams.
  * @returns {{
  *   command: string, fullSuite: boolean, credited: boolean, spawn: boolean,
  *   mode: 'capture'|'evidence'|null, reason: string, warning: string|null
@@ -215,10 +160,8 @@ export function resolveVerifyCredit(
     stampReason = freshness?.reason ?? 'unknown';
   }
 
-  // Story #5313 — a green bare `npm test` deposits the `test` evidence record
-  // close reads, so a stale (or absent) capture stamp is not the last word:
-  // the evidence keyspace is consulted in both modes before spawning. When it
-  // credits nothing either, capture mode reports the stamp's own reason.
+  // A stale stamp is not the last word: a green `npm test` deposits `test`
+  // evidence, consulted in both modes before spawning.
   const verdict = readTestEvidence({
     storyId,
     worktree,
@@ -239,9 +182,7 @@ export function resolveVerifyCredit(
 }
 
 /**
- * Consult the `test` evidence record for the worktree's HEAD — the record a
- * green bare `npm test` deposits (Story #5313) and `evidence-gate.js` wrote
- * before it. Total: an unreadable HEAD is `no-head`, never a credit.
+ * An unreadable HEAD is `no-head`, never a credit.
  *
  * @param {{ storyId: number|string, worktree: string, cwd: string, gitSpawnFn: Function, shouldSkipImpl: Function, hashCommandConfigImpl: Function, treeFingerprintImpl: Function }} args
  * @returns {{ skip: boolean, reason: string }}
@@ -274,9 +215,7 @@ function readTestEvidence({
 }
 
 /**
- * Classify a whole `verify[]` array in one pass.
- *
- * @param {string[]} entries — raw `verify[]` lines, tier tags included.
+ * @param {string[]} entries — raw lines, tier tags included.
  * @param {{ storyId: number|string, worktree: string, cwd?: string }} context
  * @param {object} [deps]
  * @returns {Array<ReturnType<typeof resolveVerifyCredit> & { tier: string|null }>}

package/.agents/scripts/lib/orchestration/worktree-dirty.js

@@ -1,13 +1,5 @@
 /**
- * lib/orchestration/worktree-dirty.js — "does this branch's checkout carry
- * uncommitted changes?" (Story #5238).
- *
- * Its own module because the light path's diff backstop is otherwise a pure
- * join over two committed-state git reads, and this is the one question there
- * that needs a third read of a *working tree*. Keeping it here leaves
- * {@link module:lib/orchestration/light-backstop} the thin join it claims to
- * be, and gives the probe its own place to be tested against every way a git
- * read can fail.
+ * Does a branch's checkout carry uncommitted changes?
  *
  * @module lib/orchestration/worktree-dirty
  */
@@ -16,8 +8,6 @@ import { gitSpawn } from '../git-utils.js';
 import { parseWorktreePorcelain } from '../worktree/inspector.js';
 
 /**
- * The stdout of a successful git read, or `null` when it cannot be trusted.
- *
  * @param {{ status?: number, stdout?: unknown }|null|undefined} result
  * @returns {string|null}
  */
@@ -27,12 +17,7 @@ function readableStdout(result) {
 }
 
 /**
- * Locate the checkout that has `branch` checked out, or `null` when no
- * checkout does.
- *
- * `git worktree list --porcelain` enumerates **every** checkout including the
- * main one, so a repository working on the branch directly (no separate
- * worktree) is found by this same lookup rather than by a second fallback path.
+ * `worktree list` includes the main checkout, so no second fallback is needed.
  *
  * @param {{ branch: string, cwd: string, gitFn: typeof gitSpawn }} args
  * @returns {string|null}
@@ -47,19 +32,9 @@ function resolveBranchCheckout({ branch, cwd, gitFn }) {
 }
 
 /**
- * Does the checkout holding `branch` have uncommitted changes?
- *
- * **Why the light path asks.** Its diff backstop measures `base...head`, which
- * is committed state, so a run that implemented and did not commit measures an
- * empty change set — and the refusal then told the agent its scope was
- * unverifiable and to escalate, when the actual fix was `git commit`. Measured
- * in the consumer: the refusal signal is stamped 12:14:06Z and the branch's
- * only commit 12:15:19Z (issue #5237).
- *
- * Total, and deliberately asymmetric: every unreadable surface — a failed
- * `worktree list`, a branch no checkout holds, a failed `status`, a throwing
- * git — answers `false`. A probe that cannot see the tree must not be able to
- * talk a refusal into friendlier guidance than the evidence supports.
+ * The light backstop diffs committed state, so uncommitted work reads as an
+ * empty change set; this lets the refusal say "commit" instead. Every
+ * unreadable surface answers `false` — a blind probe must not soften a refusal.
  *
  * @param {{ branch: string, cwd?: string, gitFn?: typeof gitSpawn }} args
  * @returns {boolean}

package/.agents/scripts/lib/path-security.js

@@ -1,15 +1,12 @@
 import path from 'node:path';
 
 /**
- * Assert that `target` resolves inside `root`. Prevents "../" traversal and
- * absolute-path escapes in configuration-supplied paths.
+ * Reject `..` traversal and absolute escapes in config-supplied paths.
  *
  * @param {string} root    absolute path of the containing directory
  * @param {string} target  absolute path to validate
- * @param {string} label   human-readable identifier for the error message
- * @param {{ allowEmpty?: boolean }} [opts]
- *   - `allowEmpty`: when false, `path.relative(root, target) === ''` is also
- *     rejected (target equals root). Default: true.
+ * @param {string} label   identifier for the error message
+ * @param {{ allowEmpty?: boolean }} [opts] false also rejects target === root.
  * @returns {string} the path relative to `root`
  * @throws {Error} when target escapes root
  */

package/.agents/scripts/lib/plan-phase-cleanup.js

@@ -1,28 +1,8 @@
 /**
- * plan-phase-cleanup.js — Post-phase temp-file cleanup for `/mandrel-plan`.
- *
- * The spec and decompose phases write several run-scoped temp files under
- * the per-run tree (`temp/run-<id>/planner-context.json`,
- * `temp/run-<id>/techspec.md`, etc. — see `lib/config/temp-paths.js`). The
- * workflow .md previously told the operator to `Remove-Item` those files by
- * name at the end of each phase, which rots: adding a new temp file in the
- * script required a synchronized markdown edit, and missed edits left
- * orphaned files accumulating in `temp/`.
- *
- * The wrapper scripts now call `cleanupPhaseTempFiles()` directly. The set
- * of artifact basenames a phase creates is the contract of this module —
- * when a new temp file is introduced, extend `PHASE_TEMP_BASENAMES` here
- * and both the spec and decompose wrappers delete it automatically.
- *
- * Cleanup is best-effort: missing files are fine (`ENOENT` is ignored),
- * unexpected errors are swallowed with a console warning so a failed rm
- * never sinks a successful phase.
- *
- * Migration note (Epic #1030 Story #1040): the legacy flat layout
- * (`temp/planner-context-for-<id>.json` etc.) has been retired. The
- * resolver now delegates to `runArtifactPath` from
- * `lib/config/temp-paths.js`, which yields `temp/run-<id>/<basename>`
- * under the configured `tempRoot`.
+ * plan-phase-cleanup.js — delete a `/mandrel-plan` phase's run-scoped temp
+ * files. `PHASE_TEMP_BASENAMES` is the contract: extend it when a phase adds
+ * a temp file. Best-effort — ENOENT is ignored and other errors only warn,
+ * so a failed rm never sinks a successful phase.
  */
 
 import fs from 'node:fs/promises';
@@ -30,10 +10,7 @@ import path from 'node:path';
 import { runArtifactPath } from './config/temp-paths.js';
 import { PROJECT_ROOT, resolveConfig } from './config-resolver.js';
 
-/**
- * Map of phase → artifact basenames (no path components). The per-run
- * directory prefix is supplied by `runArtifactPath` at resolution time.
- */
+/** Phase → artifact basenames; `runArtifactPath` supplies the run dir. */
 export const PHASE_TEMP_BASENAMES = Object.freeze({
   spec: Object.freeze([
     'planner-context.json',
@@ -41,13 +18,9 @@ export const PHASE_TEMP_BASENAMES = Object.freeze({
     'acceptance-spec.md',
   ]),
   decompose: Object.freeze(['decomposer-context.json', 'tickets.json']),
-  // Epic #4474 (PR3) — the collapsed `plan-persist.js` surface owns every
-  // plan-phase artifact and deletes them ONLY at terminal success (after
-  // the `agent::ready` flip), fixing the mid-pipeline deletion defect where
-  // per-phase cleanup removed artifacts a `--force`/`--resume` re-persist
-  // was still entitled to reuse.
-  // `plan-metrics.json` stays deliberately excluded (PR1) — the ledger
-  // must survive cleanup so the whole plan run is visible in one stream.
+  // Deleted only at terminal persist success, so a `--force`/`--resume`
+  // re-persist can still reuse them. `plan-metrics.json` is deliberately
+  // excluded: the ledger must survive to show the whole run.
   persist: Object.freeze([
     'planner-context.json',
     'techspec.md',
@@ -58,8 +31,6 @@ export const PHASE_TEMP_BASENAMES = Object.freeze({
 });
 
 /**
- * Resolve the concrete paths a phase owns for a given Epic.
- *
  * @param {'spec'|'decompose'} phase
  * @param {number} epicId
  * @param {string} [repoRoot]
@@ -72,9 +43,7 @@ export function resolvePhaseTempPaths(phase, epicId, repoRoot = PROJECT_ROOT) {
       `[plan-phase-cleanup] Unknown phase "${phase}". Expected one of: ${Object.keys(PHASE_TEMP_BASENAMES).join(', ')}.`,
     );
   }
-  // Thread the resolved config so we honour `project.paths.tempRoot`
-  // overrides; fall back to the helper's default when the resolver itself
-  // throws (zero-config callers — unit tests).
+  // Honour `tempRoot` overrides; zero-config callers fall back to defaults.
   let config;
   try {
     config = resolveConfig({ cwd: repoRoot });
@@ -83,20 +52,11 @@ export function resolvePhaseTempPaths(phase, epicId, repoRoot = PROJECT_ROOT) {
   }
   return basenames.map((basename) => {
     const rel = runArtifactPath(epicId, basename, config);
-    // `runArtifactPath` yields a path under `tempRoot` (relative when
-    // tempRoot is itself relative — the framework default). Rebase
-    // relative paths against `repoRoot` so callers always receive an
-    // absolute path — matches the pre-migration contract that
-    // downstream `fs.unlink` relies on. Already-absolute results pass
-    // through untouched.
     return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel);
   });
 }
 
 /**
- * Delete the temp files a phase owns for the given Epic. Idempotent:
- * missing files are ignored; other errors are logged but do not throw.
- *
  * @param {{
  *   phase: 'spec'|'decompose',
  *   epicId: number,

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

@@ -1,23 +1,7 @@
 /**
- * preflight-runner.js — Shared preflight wrapper around the checks registry.
- *
- * This module is the single implementation of the "run the registry, fail
- * fast on blockers, log auto-fixes" pattern. The consumer entry points
- * (`single-story-close.js`, `mandrel-update-preflight.js`, the npm test wrapper, and
- * the bootstrap scripts) call `runPreflight({ scope })` instead of
- * re-implementing the same assemble+run+format+exit-2 dance.
- *
- * Exit-code contract (shared by every consumer):
- *   - 0 → no blocker findings (warnings/info may have been printed).
- *   - 2 → at least one `severity: 'blocker'` finding survived after
- *         auto-fixes. The wrapper prints a human-readable blocker table
- *         (`id · summary · fixCommand`) before returning. Code 2 is the
- *         project-wide "preflight refused" reservation — see
- *         `.agents/workflows/helpers/deliver-story.md` for the rationale.
- *
- * Auto-fixes are logged via `logFixes` before the blocker check so the
- * operator sees the "we corrected X" line even when a separate blocker
- * later trips the exit. Auto-fixes never themselves block.
+ * preflight-runner.js — run the checks registry, log auto-fixes (which never
+ * block) before the blocker table, and report `blocked` so the consumer
+ * exits {@link PREFLIGHT_REFUSED_EXIT_CODE}.
  */
 
 import { runChecks } from './checks/index.js';
@@ -29,15 +13,9 @@ import { Logger } from './Logger.js';
  * @property {Array<object>} findings  Unfixed findings (any severity).
  * @property {Array<object>} fixed     Findings that were auto-corrected.
  * @property {boolean} blocked         True iff `findings` contains a
- *   `severity: 'blocker'`. When `true`, the consumer must exit with code 2.
+ *   `severity: 'blocker'`; the consumer must then exit 2.
  */
 
-/**
- * Default logger adapter — routes info/warn/error through the project
- * Logger. Kept as a module-local constant so the runner has a single seam
- * tests can swap with a spy that captures lines without going through
- * Logger's stdout/stderr.
- */
 const DEFAULT_LOGGER = {
   info: (msg) => Logger.info(msg),
   warn: (msg) => Logger.warn(msg),
@@ -45,26 +23,14 @@ const DEFAULT_LOGGER = {
 };
 
 /**
- * Run preflight checks for `scope` against an assembled state probe.
- *
- * The consumer surface is intentionally tiny: pass a `scope` string and
- * (optionally) a `cwd`. The runner handles state assembly, the autoFix
- * flag, finding/fix routing, and pretty-print of the blocker table.
- *
  * @param {object} opts
- * @param {string} opts.scope          Consumer surface — `'story-close'`,
- *   `'npm-test'`, `'diagnose'`, etc.
- * @param {boolean} [opts.autoFix=true] Forwarded to `runChecks`. Defaults
- *   to `true` because every wiring call site at this Story's level wants
- *   auto-correction (the `retro` consumer that needs `autoFix:false` does
- *   NOT use this helper — it calls `runChecks` directly).
+ * @param {string} opts.scope          e.g. `'story-close'`, `'npm-test'`.
+ * @param {boolean} [opts.autoFix=true]
  * @param {string} [opts.cwd=process.cwd()]
- * @param {object} [opts.probes]       Test-only probe injection forwarded
- *   to `assembleState`. Production callers omit this.
- * @param {object} [opts.registry]     Test-only — bypass `loadRegistry()`.
- * @param {string} [opts.dir]          Test-only fixture directory.
+ * @param {object} [opts.probes]       Test-only.
+ * @param {object} [opts.registry]     Test-only.
+ * @param {string} [opts.dir]          Test-only.
  * @param {{ info?: Function, warn?: Function, error?: Function }} [opts.logger]
- *   Defaults to the project Logger. Tests pass a spy that captures lines.
  * @returns {Promise<PreflightResult>}
  */
 export async function runPreflight({
@@ -79,9 +45,7 @@ export async function runPreflight({
   if (!scope || typeof scope !== 'string') {
     throw new Error('runPreflight: scope is required');
   }
-  // `retro` is reserved by the runner and is never a preflight scope.
-  // Catch it here so the failure mode is obvious instead of routing into
-  // the runner's autoFix throw.
+  // `retro` is read-only; fail here rather than in runChecks' autoFix throw.
   if (scope === 'retro') {
     throw new Error(
       'runPreflight: retro scope is read-only — call runChecks directly',
@@ -99,18 +63,12 @@ export async function runPreflight({
   const blockers = findings.filter((f) => f.severity === 'blocker');
   const blocked = blockers.length > 0;
   if (blocked) logBlockers(scope, blockers, logger);
-  // Surface non-blocker findings as well so operators see warnings/info.
   const nonBlockerFindings = findings.filter((f) => f.severity !== 'blocker');
   if (nonBlockerFindings.length > 0) logNonBlockers(nonBlockerFindings, logger);
   return { findings, fixed, blocked };
 }
 
-/**
- * Pick the logger method for `level` — falls back through the project
- * Logger if the supplied logger is missing the level. Keeps the
- * console-allowlist test happy (no direct console.* fallback here) and
- * still lets tests swap the entire logger out.
- */
+/** Falls back to the project Logger — never to `console.*` directly. */
 function pick(logger, level) {
   if (logger && typeof logger[level] === 'function') {
     return (msg) => logger[level](msg);
@@ -119,8 +77,6 @@ function pick(logger, level) {
 }
 
 /**
- * Print the auto-fixed findings as a one-line-per-fix summary.
- *
  * @param {Array<object>} fixed
  * @param {object} [logger]
  */
@@ -134,9 +90,6 @@ function logFixes(fixed, logger = DEFAULT_LOGGER) {
 }
 
 /**
- * Print the blocker table the operator sees on `exit 2`. Each row carries
- * `id · summary · fixCommand`; details (if present) wrap underneath.
- *
  * @param {string} scope
  * @param {Array<object>} blockers
  * @param {object} [logger]
@@ -152,10 +105,7 @@ function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
     '  --------------------------  --------  ----------------------------------------',
   );
   for (const b of blockers) {
-    // Pad short IDs to align the column; never TRUNCATE — the operator
-    // needs the full id to find the check module on disk and to grep the
-    // codebase for the failure mode. Long ids just push the severity
-    // column right, which is fine for terminal output.
+    // Pad, never truncate — the operator needs the full id to find the check.
     const id = String(b.id).padEnd(26);
     const sev = String(b.severity).padEnd(8);
     error(`  ${id}  ${sev}  ${b.summary ?? ''}`);
@@ -175,8 +125,6 @@ function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
 }
 
 /**
- * Print warning/info findings as one line each. These never block.
- *
  * @param {Array<object>} findings
  * @param {object} [logger]
  */
@@ -188,9 +136,5 @@ function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
   }
 }
 
-/**
- * The reserved exit code for "preflight refused". Re-exported so consumer
- * scripts can `process.exit(PREFLIGHT_REFUSED_EXIT_CODE)` instead of
- * hard-coding the magic number.
- */
+/** Project-wide "preflight refused" exit code. */
 export const PREFLIGHT_REFUSED_EXIT_CODE = 2;

package/.agents/scripts/lib/process-group.js

@@ -0,0 +1,143 @@
+/**
+ * process-group.js — kill spawned children as whole process groups:
+ * `child.kill()` on `npm` misses the `node --test` workers it forks.
+ * Parent SIGINT/SIGTERM is forwarded by a prepended handler, so the suite
+ * dies before the lock's release handler runs (a `setsid` leader never gets
+ * the terminal's Ctrl-C). win32 has no groups and degrades to the child.
+ * The kill path never throws.
+ */
+
+export const TIMEOUT_EXIT_CODE = 124;
+
+const FORWARDED_SIGNALS = Object.freeze(['SIGINT', 'SIGTERM']);
+
+/**
+ * `detached` on win32 opens a new console instead.
+ *
+ * @param {string} [platform]
+ * @returns {{ detached?: boolean }}
+ */
+export function groupSpawnOptions(platform = process.platform) {
+  return platform === 'win32' ? {} : { detached: true };
+}
+
+/**
+ * @param {{ pid?: number, kill?: (signal?: string) => void }} child
+ * @param {string} [signal]
+ * @param {{ platform?: string, killFn?: (pid: number, signal: string) => void }} [opts]
+ * @returns {boolean}
+ */
+function killProcessGroup(
+  child,
+  signal = 'SIGKILL',
+  { platform = process.platform, killFn = process.kill.bind(process) } = {},
+) {
+  const pid = child?.pid;
+  if (platform !== 'win32' && Number.isInteger(pid) && pid > 0) {
+    try {
+      killFn(-pid, signal);
+      return true;
+    } catch {
+      // The group is gone (or was never ours) — try the child itself.
+    }
+  }
+  try {
+    child?.kill?.(signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** child → the signal its group receives when this process is signalled. */
+const supervised = new Map();
+let detachForwarding = null;
+
+/**
+ * A remaining listener (the lock's release handler) re-raises; with none,
+ * re-raise here so the process still dies as asked.
+ *
+ * @param {NodeJS.Process} processImpl
+ * @param {string} signal
+ */
+function forwardSignal(processImpl, signal) {
+  for (const [child, childSignal] of supervised) {
+    killProcessGroup(child, childSignal);
+  }
+  supervised.clear();
+  stopForwarding();
+  if (processImpl.listenerCount(signal) > 0) return;
+  try {
+    processImpl.kill(processImpl.pid, signal);
+  } catch {
+    // A process that cannot signal itself is already on its way out.
+  }
+}
+
+function startForwarding(processImpl) {
+  if (detachForwarding) return;
+  const handlers = FORWARDED_SIGNALS.map((signal) => {
+    const handler = () => forwardSignal(processImpl, signal);
+    processImpl.prependListener(signal, handler);
+    return [signal, handler];
+  });
+  detachForwarding = () => {
+    for (const [signal, handler] of handlers) processImpl.off(signal, handler);
+  };
+}
+
+function stopForwarding() {
+  const detach = detachForwarding;
+  detachForwarding = null;
+  detach?.();
+}
+
+/**
+ * Kill the group on timeout, abort or parent signal; `release()` on exit.
+ *
+ * @param {{ pid?: number, kill?: (signal?: string) => void }} child
+ * @param {{
+ *   timeoutMs?: number,
+ *   abortSignal?: AbortSignal,
+ *   signalOnParentSignal?: string,
+ *   processImpl?: NodeJS.Process,
+ *   killOptions?: { platform?: string, killFn?: Function },
+ * }} [opts] `signalOnParentSignal`: SIGKILL for a bare suite, SIGTERM for a
+ *   child with its own cleanup (a capture holding the lock).
+ * @returns {{ readonly timedOut: boolean, release: () => void }}
+ */
+export function superviseGroup(
+  child,
+  {
+    timeoutMs,
+    abortSignal,
+    signalOnParentSignal = 'SIGKILL',
+    processImpl = process,
+    killOptions,
+  } = {},
+) {
+  let timedOut = false;
+  supervised.set(child, signalOnParentSignal);
+  startForwarding(processImpl);
+  const timer =
+    Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          killProcessGroup(child, 'SIGKILL', killOptions);
+        }, timeoutMs)
+      : null;
+  const onAbort = () => killProcessGroup(child, 'SIGTERM', killOptions);
+  abortSignal?.addEventListener('abort', onAbort, { once: true });
+  if (abortSignal?.aborted) onAbort();
+  return {
+    get timedOut() {
+      return timedOut;
+    },
+    release() {
+      if (timer) clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', onAbort);
+      supervised.delete(child);
+      if (supervised.size === 0) stopForwarding();
+    },
+  };
+}