@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -21,6 +21,9 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const activeWorkstreamStore = require("./active-workstream-store.cjs");
 const { createSharedPointerAdapter, createSessionScopedPointerAdapter, createMemoryPointerAdapter, getActiveWorkstream: getStoredActiveWorkstream, peekActiveWorkstream: peekStoredActiveWorkstream, setActiveWorkstream: setStoredActiveWorkstream, clearActiveWorkstream: clearStoredActiveWorkstream, diagnoseUnresolvedActiveWorkstream: diagnoseUnresolvedStoredActiveWorkstream, } = activeWorkstreamStore;
 // Track .planning/.lock files held by this process so they can be removed on exit.
@@ -97,11 +100,27 @@ const PLANNING_LOCK_RETRY_ERRNOS = new Set([
     'ENOENT', // Docker overlay-fs: parent dir transiently missing during race
     'ESTALE', // NFS: stale file handle (self-resolves on retry)
 ]);
+/**
+ * #4257: the ONE owner of the env workstream discriminator `planningDir`
+ * itself applies when handed no `ws` argument. `planningPaths(cwd)` — and
+ * therefore every workstream-scoped `PlanningSnapshot` read — resolves its
+ * base through exactly this read, and the CLI bootstrap has already folded
+ * the stored active-workstream pointer into the env by the time any
+ * diagnostic runs (`resolveActiveWorkstream` → `applyResolvedWorkstreamEnv`,
+ * `active-workstream-store.cjs`). Exposed so a consumer that needs to NAME
+ * the scope those reads used (W002's warning message, via the snapshot's
+ * `workstream` field) derives it from the same resolution point instead of
+ * growing a second env read site that can drift (the #612 PR-2
+ * two-readers-two-bases lesson).
+ */
+function resolveEnvWorkstream() {
+    return process.env['GSD_WORKSTREAM'] ?? null;
+}
 function planningDir(cwd, ws, project) {
     if (project === undefined)
         project = process.env['GSD_PROJECT'] ?? null;
     if (ws === undefined)
-        ws = process.env['GSD_WORKSTREAM'] ?? null;
+        ws = resolveEnvWorkstream();
     // Reject path separators and traversal components in project/workstream names
     const BAD_SEGMENT = /[/\\]|\.\./;
     if (project && BAD_SEGMENT.test(project)) {
@@ -175,6 +194,87 @@ function worktreesOptedOutUnguarded(cwd) {
     }
     return false;
 }
+/**
+ * #612: resolve `phase_id_convention` with the SAME workstream->root federation
+ * config-loader uses (config-loader.cts:618/:649) — the workstream config wins,
+ * the root config is the fallback.
+ *
+ * Why this exists rather than `loadConfig(cwd)['phase_id_convention']`: as of
+ * #2997 (aa7697fe, in `next`), loadConfig surfaces `phase_id_convention` in
+ * its resolved `_baseConfig` — the "loadConfig drops keys it does not know"
+ * rationale this comment used to give is stale. The surviving reasons for the
+ * direct read are (1) the workstream->root federation below, a standalone
+ * resolution this function needs to run against a GIVEN cwd rather than
+ * whatever base a `loadConfig(cwd)` call elsewhere would federate from, and
+ * (2) convention-ENUM validation, which is still #612 PR-4 work — this
+ * function returns the raw string unvalidated, same as the now-surfaced
+ * resolved key would. #2997 surfacing the key makes consuming it from
+ * resolved config (instead of re-reading config.json here) a natural PR-4
+ * consolidation, not this PR's scope. Cycles were never the obstacle.
+ *
+ * Why federation matters here specifically: the phase-id readers were splitting
+ * on this value from two different bases — one resolving from the workstream
+ * directory, one from the root — so a workstream repo got the widened ROADMAP
+ * read with the narrow directory read, or the reverse, and reported every phase
+ * either missing from disk or malformed on disk. One resolver, one answer.
+ *
+ * The workstream is `planningDir`'s own `ws` parameter, forwarded, so this
+ * shares the canonical resolution (and its GSD_PROJECT/GSD_WORKSTREAM
+ * handling). Root is consulted as a fallback only when a workstream is active,
+ * matching config-loader; a project-scoped directory stands alone. Returns null
+ * when unset, absent, or unreadable — every caller treats null as "not the
+ * bracket convention".
+ *
+ * #2761 B1 (trek-e review): `ws` is a PARAMETER, not read from the environment
+ * here. It was omitted at first on the reasoning that "the active workstream is
+ * whatever planningDir resolves" — true only for the env-driven caller. A
+ * caller that iterates workstreams passes the name as an ARGUMENT (it cannot
+ * set `GSD_WORKSTREAM` per iteration), and `planningDir` falls back to the env
+ * only when `ws` is `undefined`, so an argument-driven call resolved this
+ * convention from the ROOT config while reading that workstream's ROADMAP. Two
+ * consequences, both reproduced: a workstream that explicitly declares its OWN
+ * convention had it ignored — the root's value decided how the workstream's
+ * roadmap was parsed, so flipping ONLY the root config changed which milestone
+ * a workstream extracted; and `--workstream foo` disagreed with
+ * `GSD_WORKSTREAM=foo` on the same repo.
+ *
+ * `undefined` (the default) keeps `planningDir`'s env fallback, so every
+ * pre-#2761 call site is byte-identical; `null` means "explicitly no
+ * workstream". Same discriminator `planningDir` and `getMilestonePhaseFilter`
+ * already carry.
+ *
+ * SCOPE: this governs the #612 bracket-selection reads ONLY. The shipped
+ * milestone-prefixed W021 gate keeps its own root-only read — re-basing a
+ * legacy convention's gate onto a different config is a behaviour change to a
+ * shipped check, in both directions, and is not part of read tolerance.
+ */
+function resolvePhaseIdConvention(cwd, ws) {
+    const readFrom = (dir) => {
+        const configPath = node_path_1.default.join(dir, 'config.json');
+        if (!node_fs_1.default.existsSync(configPath))
+            return null;
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+            const value = parsed['phase_id_convention'];
+            return typeof value === 'string' && value !== '' ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const scoped = planningDir(cwd, ws);
+    const root = planningRoot(cwd);
+    if (scoped === root)
+        return readFrom(root);
+    // Root is a fallback only when a WORKSTREAM is active — config-loader falls
+    // back to the root config under `if (ws)` and not otherwise, so a
+    // project-scoped directory stands alone. Detected by suppressing the
+    // workstream segment rather than re-reading the environment.
+    const projectOnly = planningDir(cwd, null);
+    if (scoped === projectOnly)
+        return readFrom(scoped);
+    return readFrom(scoped) ?? readFrom(root);
+}
 // Sorted list of workstream directory names under `<root>/.planning/workstreams`,
 // or `[]` when the project is flat (no workstreams dir). Single source of truth
 // for the "workstream mode" detection shared by the #1912/#2028 fail-safe guards
@@ -200,6 +300,31 @@ function listAvailableWorkstreams(cwd) {
 function quickDirFrom(planningBase) {
     return node_path_1.default.join(planningBase, 'quick');
 }
+// #4256: the todos directory — deliberately ROOT-SCOPED, unlike every other
+// planningPaths key. Todos are shared project state by construction: the
+// migrateToWorkstreams contract keeps them among the shared files that "stay
+// in place" at .planning/todos/ (workstream.cts), and every workflow writer
+// writes that literal cwd-relative root path. The six todos readers
+// previously hand-composed `path.join(planningDir(cwd), 'todos', ...)`,
+// which silently re-scoped to .planning/workstreams/<ws>/todos/ — a
+// directory nothing creates — under a workstream, so todos went invisible
+// and audit-open passed the milestone-close gate vacuously. Same
+// two-composers-of-one-path shape the `debug` (#3149) and `quick` (#2142)
+// keys were introduced to eliminate (DEFECT.GENERATIVE-FIX).
+//
+// Exported as its own function pair (not only as a `planningPaths` key)
+// because `audit.cts`'s `scanTodos`/`cmdAuditAcknowledge` consume an
+// already-resolved todos base rather than a `cwd`, mirroring how #2142
+// exported `quickDirFrom` for `scanQuickTasks`. `todosDir` takes NO ws/project
+// parameter — todos have no workstream- or project-scoped form anywhere, so
+// there is no discriminator to thread. This is also the single root #4327's
+// future filename-containment guard should enforce against.
+function todosDirFrom(planningBase) {
+    return node_path_1.default.join(planningBase, 'todos');
+}
+function todosDir(cwd) {
+    return todosDirFrom(planningRoot(cwd));
+}
 function planningPaths(cwd, ws) {
     const base = planningDir(cwd, ws);
     return {
@@ -216,6 +341,11 @@ function planningPaths(cwd, ws) {
         debug: node_path_1.default.join(base, 'debug'),
         // #2142: quick-task directory, composed via the shared quickDirFrom helper.
         quick: quickDirFrom(base),
+        // #4256: todos directory — deliberately ROOT-scoped while the rest of
+        // this record follows the active workstream/project (todos are shared
+        // project state per the migrateToWorkstreams contract), composed via the
+        // shared todosDir helper so this key and every direct caller agree.
+        todos: todosDir(cwd),
     };
 }
 /**
@@ -449,40 +579,30 @@ function describeUnresolvedWorkstreamReason(reason) {
         return 'the name is not a valid workstream name';
     return "its workstream directory doesn't exist (it may have been renamed or removed)";
 }
-/**
- * Locate the CONTEXT.md file in a phase directory, handling both the bare
- * form (`CONTEXT.md`) and the padded-prefix convention (`NN-CONTEXT.md`,
- * `NN.N-CONTEXT.md`, etc.) used by gsd-discuss-phase output.
- *
- * Returns the filename (not the full path) of the first match, or null if
- * no CONTEXT.md exists in the directory.
- *
- * Canonical dual-form predicate extracted here to eliminate the 5-site
- * duplication that previously existed across init.cjs, roadmap.cjs,
- * core.cjs, gap-checker.cjs (#3739).
- *
- * @param absDirOrFiles - Absolute path to the phase directory,
- *   OR an already-read files array (avoids a redundant readdirSync at call sites
- *   that already hold a directory listing).
- */
 function findContextMdIn(absDirOrFiles) {
-    try {
-        const files = Array.isArray(absDirOrFiles)
-            ? absDirOrFiles
-            : node_fs_1.default.readdirSync(absDirOrFiles);
+    const matchIn = (files) => {
         if (files.includes('CONTEXT.md'))
             return 'CONTEXT.md';
         return files.find((f) => f.endsWith('-CONTEXT.md')) ?? null;
+    };
+    if (Array.isArray(absDirOrFiles)) {
+        return matchIn(absDirOrFiles);
+    }
+    try {
+        const files = node_fs_1.default.readdirSync(absDirOrFiles);
+        return { file: matchIn(files), files, scope: SCOPE.COMPLETE };
     }
     catch (err) {
-        // #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
-        // ("nothing there") keeps the long-standing null contract the callers rely
-        // on; every other error (EACCES, EIO, …) is a real read failure that must
-        // propagate — otherwise an unreadable phase dir is silently reported as
-        // "no CONTEXT.md" and the discuss/plan gates wrongly skip context.
-        if (err.code === 'ENOENT')
-            return null;
-        throw err;
+        // #1883 / #4014: distinguish genuine absence from a permission/I-O
+        // failure. ENOENT ("nothing there") keeps the long-standing "real empty"
+        // contract callers rely on; every other error (EACCES, EIO, …) is a real
+        // read failure — reported as SCOPE.UNREADABLE rather than thrown, so a
+        // caller no longer needs its own try/catch to keep an unreadable phase
+        // dir from being silently reported the same as "no CONTEXT.md".
+        if (err.code === 'ENOENT') {
+            return { file: null, files: [], scope: SCOPE.COMPLETE };
+        }
+        return { file: null, files: [], scope: SCOPE.UNREADABLE };
     }
 }
 module.exports = {
@@ -493,9 +613,13 @@ module.exports = {
     createMemoryPointerAdapter,
     planningDir,
     planningRoot,
+    resolveEnvWorkstream,
+    resolvePhaseIdConvention,
     listAvailableWorkstreams,
     planningPaths,
     quickDirFrom,
+    todosDirFrom,
+    todosDir,
     withPlanningLock,
     getActiveWorkstream,
     peekActiveWorkstream,

package/gsd-core/bin/lib/pristine-baseline.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * #4145: hash-first recovery for gsd-pristine/ baselines stored at an
+ * unexpected path.
+ *
+ * Some installs hold a pristine snapshot whose SHA-256 equals the hash recorded
+ * in backup-meta.json.pristine_hashes for a manifest-keyed file, but at a path
+ * that is not `path.join(pristineDir, relPath)` — e.g. stored without the
+ * `gsd-core/` top-level segment by an earlier release's writer. Both readers
+ * (verify-reapply-patches.cjs verifyFile and install.js saveLocalPatches)
+ * resolved strictly by that join, missed the snapshot, and reported
+ * ok_no_baseline / fell into regeneration that can never satisfy the recorded
+ * outgoing hash — a self-perpetuating gap.
+ *
+ * Hash equality with the recorded pristine_hashes entry is the same authority
+ * the #3657 drift guard already trusts, so a match cannot be the wrong
+ * baseline regardless of which release wrote it or where under gsd-pristine/
+ * it lives. This module owns the shared scan so the two readers cannot drift
+ * apart again (two private strict joins drifting is exactly the bug class).
+ *
+ * ADR-457: runtime module in src/*.cts, compiled to
+ * gsd-core/bin/lib/pristine-baseline.cjs.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256File = sha256File;
+exports.findPristineByHash = findPristineByHash;
+exports.findPristineInGit = findPristineInGit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * SHA-256 hex digest of a file's raw bytes. Byte-for-byte the same digest
+ * install.js fileHash() records into manifests and backup-meta.json.
+ */
+function sha256File(absPath) {
+    return node_crypto_1.default.createHash('sha256').update(node_fs_1.default.readFileSync(absPath)).digest('hex');
+}
+function walkSorted(dir, relPrefix, results) {
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // absent or unreadable — nothing to scan here
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        // Never follow symlinks: gsd-pristine/ is installer-authored plain files;
+        // a link here is not a baseline and must not redirect the walk out of the
+        // tree (same posture as migration 004's walker).
+        if (entry.isSymbolicLink())
+            continue;
+        const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            walkSorted(node_path_1.default.join(dir, entry.name), rel, results);
+        }
+        else if (entry.isFile()) {
+            results.push(rel);
+        }
+    }
+}
+/**
+ * Find the first file under `pristineDir` (deterministic sorted walk) whose
+ * SHA-256 equals `recordedHash`, as a pristineDir-relative POSIX path.
+ *
+ * - `skip` is never returned — a single POSIX relPath string or a Set of them.
+ *   Callers pass the canonical path(s) they (or other files in the same run)
+ *   already own, so a file sitting at a canonical path is never adopted
+ *   through the scan. For the installer's relocation this is what prevents a
+ *   byte-identical canonical belonging to ANOTHER modified file from being
+ *   "rescued" away (relocated and deleted at its home path).
+ * - Multiple matches are byte-identical by sha-256 authority; sorted order
+ *   makes the choice deterministic.
+ * - Returns null when pristineDir is absent/unreadable or nothing matches.
+ */
+function findPristineByHash(pristineDir, recordedHash, skip) {
+    if (!pristineDir || typeof recordedHash !== 'string' || recordedHash.length === 0) {
+        return null;
+    }
+    const skipSet = skip instanceof Set ? skip : new Set(skip !== undefined ? [skip] : []);
+    const rels = [];
+    walkSorted(pristineDir, '', rels);
+    for (const rel of rels) {
+        if (skipSet.has(rel))
+            continue;
+        try {
+            if (sha256File(node_path_1.default.join(pristineDir, rel)) === recordedHash) {
+                return rel;
+            }
+        }
+        catch {
+            // unreadable candidate — keep scanning
+        }
+    }
+    return null;
+}
+/**
+ * #4135: recover a pristine baseline from the config dir's OWN git history,
+ * anchored by the recorded pristine_hashes entry.
+ *
+ * The #3407 promotion rule keeps only regeneration candidates byte-identical
+ * across the whole version span, so a multi-version update leaves
+ * gsd-pristine/ holding exactly the files upstream did NOT change — near-zero
+ * coverage precisely where upstream churned the most. On a git-managed config
+ * dir the outgoing bytes often still exist in history (the workflow's
+ * documented Option A), and pristine_hashes is the same authority every other
+ * resolution tier trusts: a blob whose SHA-256 equals the recorded hash cannot
+ * be the wrong baseline. This is read-only recovery (git log / git show only).
+ *
+ * Guarantees:
+ * - Only an EXACT sha-256 match with the recorded hash is ever returned.
+ * - Newest-first commit order (git log default) makes multi-match resolution
+ *   deterministic; byte-identical matches are interchangeable anyway.
+ * - Any failure (git absent, not a repository, empty history, unreadable
+ *   blob, subprocess timeout) yields null — never a throw — so the caller's
+ *   OK_NO_BASELINE posture is the universal fallback.
+ * - The walk is bounded: at most GIT_MAX_COMMITS_PER_FILE commits per file.
+ */
+const GIT_MAX_COMMITS_PER_FILE = 100;
+/** Per-subprocess bound in ms — an unbounded git call is an indefinite hang. */
+const GIT_SUBPROCESS_TIMEOUT_MS = 10_000;
+/** git log --format=%H output cap; 100 full shas are ~4 KB, this is headroom. */
+const GIT_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+function isCleanRelativePosixPath(relPath) {
+    if (!relPath || relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) {
+        return false;
+    }
+    const segments = relPath.split('/');
+    return segments.every((seg) => seg.length > 0 && seg !== '.' && seg !== '..');
+}
+function gitExec(gitDir, args) {
+    return (0, node_child_process_1.execFileSync)('git', args, {
+        cwd: gitDir,
+        encoding: 'utf8',
+        timeout: GIT_SUBPROCESS_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER_BYTES,
+        // windowsHide (#685): a console-window flash per git call would spam the
+        // user on Windows for what is a background, read-only history walk.
+        windowsHide: true,
+        // stderr is discarded: "file absent in commit" is an expected walk outcome,
+        // not operator-visible diagnostics.
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+function findPristineInGit(gitDir, relPath, recordedHash) {
+    if (!gitDir || typeof relPath !== 'string' || typeof recordedHash !== 'string'
+        || recordedHash.length === 0 || !isCleanRelativePosixPath(relPath)) {
+        return null;
+    }
+    let commits;
+    try {
+        const logOutput = gitExec(gitDir, ['log', '--format=%H', '--', relPath]).trim();
+        if (!logOutput)
+            return null;
+        commits = logOutput.split('\n').slice(0, GIT_MAX_COMMITS_PER_FILE);
+    }
+    catch {
+        return null; // git absent, not a repository, or the walk failed
+    }
+    for (const commit of commits) {
+        if (!/^[0-9a-f]{40}$/i.test(commit))
+            continue;
+        try {
+            const blob = gitExec(gitDir, ['show', `${commit}:${relPath}`]);
+            if (sha256String(blob) === recordedHash) {
+                return blob;
+            }
+        }
+        catch {
+            // blob absent in this commit (rename/add boundary) — keep walking
+        }
+    }
+    return null;
+}
+/** sha256 of a utf8 string, matching how manifest hashes are recorded. */
+function sha256String(content) {
+    return node_crypto_1.default.createHash('sha256').update(content, 'utf8').digest('hex');
+}

package/gsd-core/bin/lib/prohibition-enforcement.cjs

@@ -362,6 +362,93 @@ function childEnv() {
 const NODE_TEST_TIMEOUT_MS = 30_000;
 const ESLINT_TIMEOUT_MS = 60_000;
 const CHECK_MAX_BUFFER = 16 * 1024 * 1024;
+/** Windows `taskkill` resolved by ABSOLUTE path — never a bare PATH-resolved name. A project
+ * directory used as the child's `cwd` could otherwise contain a planted `taskkill.exe`/`.bat`
+ * that Windows executable resolution picks up ahead of the real one (#3660 review, minor-9).
+ * Returns null (never a hardcoded fallback, per tests/hardcoded-paths.test.cjs) when neither env
+ * var is set -- not expected on a real Windows host (both are set by the OS itself), but a
+ * hostile/stripped env should degrade to "skip the reap" rather than guess a system path. */
+function taskkillPath() {
+    const root = process.env.SystemRoot || process.env.windir;
+    return root ? node_path_1.default.join(root, 'System32', 'taskkill.exe') : null;
+}
+/**
+ * Reap the process TREE rooted at `pid` after THIS call's own bound killed it (#3660: `node --test`
+ * forks a per-file WORKER by default since Node 22 — `execFileSync`'s `timeout` signals only the
+ * direct child/runner, never the worker, which is reparented to PID 1 and can busy-loop forever).
+ *
+ * POSIX: the child was spawned `detached` (its own process group, pgid === pid), so `-pid` addresses
+ * the whole group. ESRCH (group already gone) is swallowed — the subject may have exited on its own
+ * between the timeout firing and this call.
+ *
+ * Windows has no process-group equivalent; `taskkill /PID <pid> /T /F` walks the live process tree by
+ * parent-PID instead, which does not require the parent PID to still be alive. A non-zero exit means
+ * "nothing left to kill" (already gone, or never had descendants) — not a failure, so it is never
+ * escalated; there is no portable stronger primitive to escalate TO.
+ *
+ * Never throws — this runs from a `catch`/`finally` path and must not itself become the error.
+ */
+function reapDescendants(pid) {
+    if (typeof pid !== 'number' || pid <= 0)
+        return; // defensive: never signal pid 0 (self) or negative
+    if (process.platform === 'win32') {
+        const exe = taskkillPath();
+        if (!exe)
+            return; // no safe absolute path available -- best-effort, skip rather than guess
+        try {
+            // 5s bound (DEFECT.UNBOUNDED-SUBPROCESS): a local OS command, not a network call -- if
+            // taskkill itself hangs, this function's own "never throws" contract already treats that
+            // identically to any other failure (swallowed below), so a bounded timeout costs nothing
+            // and just prevents a stuck taskkill from blocking the caller forever.
+            (0, node_child_process_1.spawnSync)(exe, ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, timeout: 5_000 });
+        }
+        catch {
+            // best-effort: a missing taskkill.exe (or a timeout) is not this call's problem to escalate
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // Swallows ESRCH (group already gone -- nothing to reap) and any other errno (e.g. EPERM) --
+        // this helper never throws regardless of cause; see the function's own doc comment above.
+    }
+}
+/**
+ * `execFileSync`, with descendant reaping layered on top. Same contract (same return value, throws
+ * the identical error) EXCEPT that when — and ONLY when — this call's OWN timeout killed the child,
+ * any descendants the child forked are also reaped.
+ *
+ * Gated on `error.code === 'ETIMEDOUT'`, NOT `error.signal`. `signal` is the field Node's own docs
+ * describe for this purpose, but it is not reliably populated across platforms/Node versions: on one
+ * real Linux CI run (Node 24) a genuine timeout-kill threw `{ signal: null, code: 'ETIMEDOUT',
+ * status: 7 }` — `signal` was simply absent, `code` was the only reliable marker (confirmed empirically
+ * before landing this; a macOS/Node run separately showed `signal: 'SIGTERM'` for the identical
+ * scenario, so neither field alone is safe to rely on everywhere — `code` was the one constant).
+ * Gating strictly on the timeout code (rather than reaping on every throw) matters: an ordinary
+ * non-zero exit (a real test/lint failure) has no `ETIMEDOUT` code — the child exited on its own, so a
+ * reap there would fire on every red run for no reason and, on POSIX, risks signalling a process group
+ * whose pgid was *already* recycled by something unrelated in the time since (the #3660 review's
+ * Blocker-3 defect in the prior attempt at this fix, PR #3681). Only the timeout-kill path is targeted.
+ *
+ * Spawns `detached` on POSIX so the reap above can address the whole process group; omitted on
+ * Windows (no such flag there — `@types/node`'s `ExecFileSyncOptions` doesn't declare `detached`
+ * either, hence the cast below, though libuv honors it identically to `spawnSync`).
+ */
+function execFileSyncReaping(file, args, options) {
+    const spawnOptions = process.platform === 'win32' ? options : { ...options, detached: true };
+    try {
+        return (0, node_child_process_1.execFileSync)(file, args, spawnOptions);
+    }
+    catch (e) {
+        const err = e;
+        if (typeof err.pid === 'number' && err.code === 'ETIMEDOUT') {
+            reapDescendants(err.pid);
+        }
+        throw e;
+    }
+}
 /** Resolve the effective timeout: only a POSITIVE override is honored — `0` (which Node treats as
  * "no timeout") or a negative value falls back to the bounded default, so the subprocess is ALWAYS
  * bounded (a `timeoutMs: 0` injection can never disable the bound). */
@@ -378,7 +465,7 @@ function posTimeout(timeoutMs, def) {
  */
 function runNodeTestWithSubject(check, cwd, subject, timeoutMs) {
     try {
-        return (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
+        return execFileSyncReaping(process.execPath, buildNodeTestArgs(check), {
             cwd,
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -398,7 +485,7 @@ function defaultRunCheck(check, cwd, timeoutMs) {
         if (check.kind === 'node-test') {
             let out = '';
             try {
-                out = (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
+                out = execFileSyncReaping(process.execPath, buildNodeTestArgs(check), {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],
@@ -422,7 +509,7 @@ function defaultRunCheck(check, cwd, timeoutMs) {
                 return { passed: false }; // eslint not installed -> fail closed, never throw
             let json = '';
             try {
-                json = (0, node_child_process_1.execFileSync)(process.execPath, [eslintCli, ...buildLintArgs(check)], {
+                json = execFileSyncReaping(process.execPath, [eslintCli, ...buildLintArgs(check)], {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],
@@ -482,7 +569,7 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
                 return { provenFailFirst: false }; // eslint not installed -> fail closed, never throw
             let json = '';
             try {
-                json = (0, node_child_process_1.execFileSync)(process.execPath, [eslintCli, ...buildLintArgs({ ...check, target: fixture })], {
+                json = execFileSyncReaping(process.execPath, [eslintCli, ...buildLintArgs({ ...check, target: fixture })], {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],