session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/validate/check-validator-registration.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * check-validator-registration.mjs — every `scripts/lib/validate/check-*.mjs`
+ * must be referenced by basename from at least one of the three surfaces
+ * that actually RUN a validator (`scripts/validate-plugin.mjs`,
+ * `.husky/pre-commit`, `.gitlab-ci.yml`), or declare itself deliberately
+ * standalone. #1184.
+ *
+ * THE CLASS. A checker with real detection logic and zero callers is built
+ * work nobody ever runs — this repo's own `check-unwired-features.mjs`
+ * census exists for a sibling shape of the same problem (config keys nobody
+ * reads); this checker is that same discipline applied to the checkers
+ * directory itself. `scripts/validate-plugin.mjs` is the canonical local
+ * runner (`runCheck('check-foo.mjs')`); `.husky/pre-commit` and
+ * `.gitlab-ci.yml` are the two OTHER surfaces some checkers wire into
+ * directly instead of (or in addition to) the orchestrator —
+ * `check-owner-leakage.mjs`, `check-test-fixture-shapes.mjs` and
+ * `check-test-value-bans.mjs` all do this (verified live at HEAD 2ccea0f2).
+ *
+ * OPT-OUT. A checker that is deliberately CLI-only (invoked by a human or a
+ * different tool, never by these three surfaces) declares itself with a
+ * header-comment marker: `// registration: standalone <reason>`. The marker
+ * makes the checker report PASS as "standalone", not merely silence a
+ * warning — the same shape of inline self-declared exemption
+ * `check-untracked-test-deps.mjs`'s `IGNORE_MARKER` and
+ * `check-dead-bridge.mjs`'s `:ignore` marker already use in this directory.
+ *
+ * ORACLE. A plain substring match of the checker's own basename (e.g.
+ * `"check-foo.mjs"`) against the COMMENT-STRIPPED text of the three surface
+ * files — the same granularity `runCheck('check-foo.mjs')` calls and
+ * `.husky`/CI script lines already use to name a checker. MEASURED (HEAD
+ * 2ccea0f2, all 33 live `check-*.mjs` basenames): zero basenames are a
+ * substring of another, so this match cannot cross-attribute one checker's
+ * registration to a different one.
+ *
+ * COMMENT-STRIPPING (HIGH, qa review, #1184 FX-C). A basename referenced
+ * ONLY inside a `//`/`#` line comment or a `/* *\/` block comment is NOT a
+ * real registration — the surface text is stripped of comments (quote-aware,
+ * so a `#`/`//` INSIDE a string — a URL fragment, a shell parameter
+ * expansion `${VAR#pattern}` — is never mistaken for a comment start) before
+ * matching. MEASURED before this fix: a fixture whose only reference to
+ * `check-ghost.mjs` sat in `// runCheck('check-ghost.mjs'); // DISABLED`
+ * reported `registered: true` (exit 0) — commenting a checker OUT silently
+ * kept it PASSing. `scripts/validate-plugin.mjs` uses `//`+`/* *\/` (js);
+ * `.husky/pre-commit` and `.gitlab-ci.yml` use `#` (sh/yaml) — see
+ * {@link commentStyleForSurface}. The checker's OWN
+ * `// registration: standalone` header marker is read from the CHECKER file
+ * directly (never from a surface text) and is unaffected by this stripping.
+ *
+ * NAMED CEILING (BV-004): a checker referenced only in prose (a `.md` doc, a
+ * skill body) and nowhere in the three RUN surfaces above still reports
+ * UNREGISTERED — being documented is not being run. REVISIT if a fourth run
+ * surface (a new CI job file, a different git hook) is ever added: extend
+ * `RUN_SURFACES`, do not special-case it here. The comment stripper's own
+ * quote-tracking is a single flat state — an escaped quote (`\"`) inside a
+ * double-quoted string is not honoured, and a template-literal's `${...}`
+ * interpolation is not walked separately. Both failure directions lean
+ * toward treating MORE text as "inside a string" than a real parser would,
+ * which can only make the stripper MISS a comment (false "still
+ * registered"), never manufacture a false UNREGISTERED — the direction this
+ * checker's own false-positive history (the paragraph above) already
+ * measured as the live hazard.
+ *
+ * Usage: check-validator-registration.mjs <repo-root>
+ * Output: `  PASS: …` / `  FAIL: …` lines (two leading spaces), then
+ * `Results: N passed, M failed`. Exit 0 = every checker registered or
+ * standalone, 1 = at least one unregistered checker, 2 = tool error.
+ *
+ * Import-safety: importing this module MUST NOT execute anything — the
+ * isMain guard at the bottom is the only side-effecting path.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
+
+/** Marker line inside a checker's own header — declares deliberate CLI-only status. */
+export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
+
+/** The three surfaces that actually RUN a validator (not merely mention it). */
+const RUN_SURFACES = Object.freeze([
+  path.join('scripts', 'validate-plugin.mjs'),
+  path.join('.husky', 'pre-commit'),
+  path.join('.gitlab-ci.yml'),
+]);
+
+const VALIDATE_DIR_REL = path.join('scripts', 'lib', 'validate');
+
+/**
+ * Comment style for a RUN_SURFACES path, keyed on extension rather than
+ * position — avoids a silent index-drift if `RUN_SURFACES` is ever
+ * reordered. `.mjs` gets JS-shaped comments (`//`, `/* *\/`, quotes
+ * `'`/`"`/`` ` ``); everything else (`.husky/pre-commit` has no extension,
+ * `.gitlab-ci.yml`) gets shell/YAML-shaped comments (`#` only, quotes
+ * `'`/`"`).
+ *
+ * @param {string} rel repo-relative surface path
+ * @returns {{lineComment: string, blockComment: boolean, quoteChars: string[]}}
+ */
+function commentStyleForSurface(rel) {
+  return rel.endsWith('.mjs')
+    ? { lineComment: '//', blockComment: true, quoteChars: ['"', "'", '`'] }
+    : { lineComment: '#', blockComment: false, quoteChars: ['"', "'"] };
+}
+
+/**
+ * Strip comments from `text` so a checker basename mentioned only inside a
+ * comment is never read as a real registration. Quote-aware: walks `'`/`"`
+ * (and, for the js style, `` ` ``) spans without inspecting their contents,
+ * so a comment marker INSIDE a string (a URL fragment `#frag`, a shell
+ * parameter expansion `${VAR#pattern}`) is left untouched rather than
+ * truncating the line early. See the header NAMED CEILING for what this
+ * quote-tracking deliberately does not attempt.
+ *
+ * @param {string} text
+ * @param {{lineComment: string, blockComment: boolean, quoteChars: string[]}} style
+ * @returns {string}
+ */
+export function stripComments(text, { lineComment, blockComment, quoteChars }) {
+  let out = '';
+  let i = 0;
+  let inQuote = null;
+  while (i < text.length) {
+    const ch = text[i];
+    if (inQuote) {
+      out += ch;
+      if (ch === '\\' && i + 1 < text.length) {
+        out += text[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === inQuote) inQuote = null;
+      i += 1;
+      continue;
+    }
+    if (quoteChars.includes(ch)) {
+      inQuote = ch;
+      out += ch;
+      i += 1;
+      continue;
+    }
+    if (blockComment && ch === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+      continue;
+    }
+    if (text.startsWith(lineComment, i)) {
+      const nl = text.indexOf('\n', i);
+      i = nl === -1 ? text.length : nl; // keep the newline itself, drop the comment text
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * @typedef {{basename: string, registered: boolean, standalone: boolean, surfaces: string[]}} RegistrationResult
+ */
+
+/**
+ * @param {string} repoRoot
+ * @returns {RegistrationResult[]} sorted by basename
+ */
+export function scanValidatorRegistration(repoRoot) {
+  // "Exists in this directory, tracked or not" (#1248) — a checker written but
+  // not yet staged is precisely the one most likely to be unregistered, and the
+  // bare git index cannot see it. `enumerateRepoFiles` still honours
+  // `.gitignore`, so no ignored tree enters the census (#1143).
+  const checkerFiles = enumerateRepoFiles({
+    repoRoot,
+    dirs: [VALIDATE_DIR_REL],
+    exts: ['mjs'],
+  }).filter((f) => /^check-.*\.mjs$/.test(path.basename(f)));
+
+  // Comment-stripped before matching (HIGH, #1184 FX-C): a basename
+  // referenced only inside a `//`/`#`/`/* *\/` comment is NOT a real
+  // registration — see the header's COMMENT-STRIPPING paragraph.
+  const surfaceTexts = RUN_SURFACES.map((rel) => {
+    const abs = path.join(repoRoot, rel);
+    try {
+      const raw = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+      return stripComments(raw, commentStyleForSurface(rel));
+    } catch {
+      return '';
+    }
+  });
+
+  /** @type {RegistrationResult[]} */
+  const results = [];
+  for (const abs of checkerFiles) {
+    const basename = path.basename(abs);
+    let source = '';
+    try {
+      source = readFileSync(abs, 'utf8');
+    } catch {
+      /* unreadable — no marker can be found, no surface reference can save it either */
+    }
+    const standalone = STANDALONE_MARKER.test(source);
+    const surfaces = RUN_SURFACES.filter((_, i) => surfaceTexts[i].includes(basename));
+    results.push({ basename, registered: surfaces.length > 0, standalone, surfaces });
+  }
+  return results.sort((a, b) => a.basename.localeCompare(b.basename));
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the check against a repo root, printing the validate-plugin line
+ * vocabulary.
+ *
+ * @param {string} repoRoot
+ * @returns {number} 0 = every checker registered or standalone, 1 = finding(s), 2 = tool error
+ */
+export function runCheckValidatorRegistration(repoRoot) {
+  console.log('--- Check: validator registration (check-*.mjs must be wired or standalone) ---');
+
+  const results = scanValidatorRegistration(repoRoot);
+  let pass = 0;
+  let fail = 0;
+
+  for (const r of results) {
+    if (r.standalone) {
+      console.log(`  PASS: ${r.basename} — declared standalone (registration: standalone)`);
+      pass += 1;
+    } else if (r.registered) {
+      console.log(`  PASS: ${r.basename} — referenced in ${r.surfaces.join(', ')}`);
+      pass += 1;
+    } else {
+      console.log(
+        `  FAIL: ${r.basename} — referenced by NEITHER scripts/validate-plugin.mjs, .husky/pre-commit, NOR .gitlab-ci.yml, and carries no "registration: standalone" marker`,
+      );
+      fail += 1;
+    }
+  }
+
+  console.log('');
+  console.log(`Results: ${pass} passed, ${fail} failed`);
+  return fail > 0 ? 1 : 0;
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  const root = process.argv[2];
+  if (!root) {
+    console.error('Usage: check-validator-registration.mjs <repo-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckValidatorRegistration(path.resolve(root)));
+}

package/scripts/lib/validate/check-vcs-repo-flag.mjs

@@ -194,6 +194,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
 
 /** Directories whose content is scanned. Root-level `*.md` is added separately. */
 const SCAN_DIRS = Object.freeze([
@@ -224,9 +225,6 @@ const DOC_EXTENSIONS = Object.freeze(['.md']);
 /** Code extensions (comment + string-literal rules apply). */
 const CODE_EXTENSIONS = Object.freeze(['.mjs', '.js', '.cjs']);
 
-/** Fence languages whose body is shell. Anything else is prose. */
-const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
-
 /**
  * Real top-level subcommands, harvested from `gh --help` / `glab --help`
  * (gh 2.86.0 / glab 1.91.0, 2026-08-14). Filter 4: a token that is not in this
@@ -576,33 +574,13 @@ export function scanMarkdown(relative, body, tally) {
   const findings = [];
   /** @type {{line: number, text: string}[]} */
   const shellLines = [];
-  /** @type {{marker: string, length: number, shell: boolean} | null} */
-  let fence = null;
 
-  const lines = body.split('\n');
-  for (let index = 0; index < lines.length; index += 1) {
-    const raw = lines[index];
-    const fenceMatch = raw.match(/^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/);
-    if (fenceMatch) {
-      const marker = fenceMatch[1][0];
-      const length = fenceMatch[1].length;
-      const lang = fenceMatch[2].toLowerCase();
-      if (fence === null) {
-        fence = { marker, length, shell: SHELL_LANGS.has(lang) };
-        continue;
-      }
-      // A closing fence uses the same char, is at least as long, and has no info string.
-      if (marker === fence.marker && length >= fence.length && lang === '') {
-        fence = null;
-        continue;
-      }
-      // Otherwise it is fence content (a nested fence inside a wider one).
-    }
-    if (fence === null || !fence.shell) continue;
+  forEachLine(body, (raw, { lineNumber, inFence, lang }) => {
+    if (!inFence || !SHELL_LANGS.has(lang)) return;
     const stripped = raw.replace(/^\s*[$❯>]\s+/, '');
-    if (/^\s*#/.test(stripped)) continue;
-    shellLines.push({ line: index + 1, text: stripped });
-  }
+    if (/^\s*#/.test(stripped)) return;
+    shellLines.push({ line: lineNumber, text: stripped });
+  });
 
   for (const entry of joinContinuations(shellLines)) {
     for (const hit of extractBareInvocations(entry.text, tally)) {

package/scripts/lib/validate/enumerate-repo-files.mjs

@@ -0,0 +1,317 @@
+/**
+ * scripts/lib/validate/enumerate-repo-files.mjs
+ *
+ * ONE enumerator for the scanners whose question is **"does this file exist in
+ * the repository right now?"** — GitLab #1248.
+ *
+ * ## The three populations, and why this is a third one
+ *
+ * `./repo-files.mjs` already answers two questions, and this module answers a
+ * third rather than duplicating either:
+ *
+ *   | function                    | population                                          |
+ *   |-----------------------------|-----------------------------------------------------|
+ *   | `listRepoFiles()`           | what git TRACKS — "will ship / is versioned"        |
+ *   | `listOnDiskFiles()`         | what the filesystem HOLDS minus a name list         |
+ *   | `enumerateRepoFiles()` here | **exists under these roots, tracked or not, minus what `.gitignore` excludes** |
+ *
+ * Pick deliberately. A scanner asking "is this file versioned / will it ship?"
+ * (a packaging check, a tarball manifest) MUST keep `listRepoFiles()`. A
+ * scanner asking "is this file PRESENT, so is the citation pointing at it
+ * dead?" belongs here — for it, the index is the wrong oracle.
+ *
+ * ## Why the index is the wrong oracle for an existence check (#1248)
+ *
+ * MEASURED in a clone (Wave-1 D6, 2026-09-06): an UNTRACKED
+ * `skills/zz-probe/SKILL.md` citing `scripts/does-not-exist.mjs` made
+ * `check-skill-script-paths.mjs` report `1 passed, 0 failed` BEFORE
+ * `git add -A` and `0 passed, 1 failed` AFTER — same working tree, same
+ * defect, no edit in between. The moment a defect is most likely to exist (a
+ * brand-new, not-yet-staged skill or checker) is exactly the moment the index
+ * cannot see it, so the check reports clean on the tree that carries the bug.
+ * `.claude/rules/measurement-discipline.md` § "A `git grep` drift sweep cannot
+ * see untracked files" is the same incident class on the release sweep.
+ *
+ * ## Why NOT a bare `readdirSync` walk
+ *
+ * The naive repair — swap `git ls-files` for a filesystem walk with a fixed
+ * prune list — reintroduces the MEASURED regression #1143 that put
+ * `repo-files.mjs` there in the first place: a walk cannot see `.gitignore`,
+ * so a gitignored worktree under `.claude/worktrees/<name>` drops a COMPLETE
+ * second checkout into the census (measured with one peer worktree present:
+ * +755 `.md`, +1209 `.mjs`, 133 MB, and a peer's copy of a rule file counted
+ * as an independent document). MEASURED here 2026-09-06 @ `befdda47` on a
+ * clean tree with `.claude/worktrees/` empty:
+ *
+ *     git ls-files                          -- skills commands agents docs → 287 .md
+ *     git ls-files --cached --others
+ *                  --exclude-standard       -- (same dirs)                 → 287 .md
+ *     listOnDiskFiles() walk, EXCLUDED_DIRS -- (same dirs)                 → 290 .md
+ *
+ * The 3-file surplus of the walk is entirely gitignored content
+ * (`docs/specs/2026-04-04-plan-skill-design.md`,
+ * `docs/specs/2026-04-16-bootstrap-gate-design.md`,
+ * `docs/specs/2026-05-26-parallel-aware-sessions-design.md`) — private design
+ * notes that would enter the census as if they were repository documentation.
+ * So the oracle is `--cached --others --exclude-standard`: it sees the
+ * untracked file #1248 is about AND honours `.gitignore`, which no prune list
+ * can approximate.
+ *
+ * ## The failure contract: absent is not unreadable (#1248 follow-up)
+ *
+ * The population above is "exists under these roots". Deciding whether a path
+ * EXISTS costs one `statSync`, and that `statSync` can fail for two
+ * fundamentally different reasons which an earlier version of this module
+ * collapsed into one bare `catch { continue }`:
+ *
+ *   | stat error                        | what it means                                   | this module |
+ *   |-----------------------------------|-------------------------------------------------|-------------|
+ *   | `ENOENT`                          | git lists it, the checkout lacks it — sparse checkout, a deletion staged elsewhere | SKIP (contributes zero files) |
+ *   | `ENOTDIR`                         | a parent component is a file, so the path cannot exist either | SKIP (same class) |
+ *   | `EACCES` / `EPERM`                | the file EXISTS; this process may not look at it | THROW {@link RepoEnumerationError} |
+ *   | `ELOOP` / `EIO` / `ENAMETOOLONG` / anything else | the answer is unknown              | THROW {@link RepoEnumerationError} |
+ *
+ * The skip set is deliberately the same two codes `listRepoFiles()` documents
+ * in its own filter comment ("a tracked path can be absent from the working
+ * tree"), narrowed from a catch-all to exactly the codes that mean ABSENT.
+ * Every other code means the enumerator does not know whether the file is
+ * there, and a census that silently omits a file it could not look at reports
+ * a SMALLER population than the truth — with no signal that it did.
+ *
+ * That silence had a measured consequence. `collectDriftHits()` in
+ * `scripts/release.mjs` sweeps every enumerated file for the previous release
+ * literal; with `README.md` unreadable, the swallow made the sweep read ZERO
+ * files, return `status 1` ("no match"), and `evaluateDriftSweep()` reported
+ * `ok: true` — a release gate passing on a file it could not open. Fail-closed
+ * is one line there, and it was already written:
+ *
+ *     } catch (err) {
+ *       return { status: 128, stdout: '', stderr: `enumerateRepoFiles failed: ${err && err.message}` };
+ *
+ * (`scripts/release.mjs:576-578`; `evaluateDriftSweep` maps any status outside
+ * {0,1} to `ok: false` — "sweep is inconclusive".) So THROWING is what turns
+ * an unreadable file into an inconclusive sweep instead of a clean one.
+ *
+ * NAMED CEILING (BV-004): only the git path fails closed. The non-git fallback
+ * walks through `listOnDiskFiles()`, whose `readdirSync` walk skips an
+ * unreadable sub-tree by design and cannot report it — see
+ * {@link enumerateRepoFiles}. Revisit trigger: the first consumer that needs
+ * fail-closed enumeration on a NON-git root (a tarball export, a vendored
+ * copy); the answer then is an error-collecting walk in `repo-files.mjs`, not
+ * a second stat pass here.
+ *
+ * ## NAMED CEILING (BV-004)
+ *
+ * The `prune` list is a fixed set of path segments / repo-relative prefixes,
+ * NOT a `.gitignore` parser — it is only load-bearing on the FALLBACK path
+ * (a root that is not a git top level: a tarball export, a vendored copy, a
+ * tmpdir fixture). On the primary path git already applies the real ignore
+ * rules and the prune list is a cheap second filter. REVISIT if a scanner
+ * ever needs this on a non-git root whose ignored trees are not covered by
+ * the default prune set — then reach for a real ignore parser, do not grow
+ * this list a sixth time.
+ *
+ * @module scripts/lib/validate/enumerate-repo-files
+ */
+
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+
+import { EXCLUDED_DIRS, isGitToplevel, listOnDiskFiles } from './repo-files.mjs';
+
+/**
+ * Environment handed to `git`. An allowlist rather than `process.env`: an
+ * inherited `GIT_DIR` / `GIT_WORK_TREE` (set by any hook that spawned us)
+ * would silently re-point `ls-files` at a DIFFERENT repository, and the result
+ * would look like a plausible file list. Same allowlist as
+ * `repo-files.mjs`, which is not exported there.
+ */
+const GIT_ENV_ALLOWLIST = Object.freeze(['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ']);
+
+/**
+ * Path segments (or repo-relative path prefixes) never enumerated — reused
+ * from `repo-files.mjs` rather than retyped, so an addition there reaches this
+ * module too.
+ *
+ * Deliberately NOT extended with this repo's own ignored trees
+ * (`.orchestrator/tmp/`, `.claude/worktrees/`): on the primary path `git` has
+ * already applied the real ignore rules — measured, `.orchestrator/tmp/` is
+ * `.gitignore:122` — so such an entry would be dead weight there, and naming
+ * an untracked path in a module a test imports is itself a finding
+ * (`check-untracked-test-deps.mjs` R2). A caller scanning a NON-git root whose
+ * ignored subtree a basename cannot express passes it via `prune` instead —
+ * that is what the prefix form is for.
+ */
+export const DEFAULT_PRUNE = EXCLUDED_DIRS;
+
+/**
+ * `stat` error codes that mean the path is ABSENT from the working tree, and
+ * are therefore skipped rather than raised. See the module header's failure
+ * table for why the set is exactly these two and not a catch-all.
+ */
+const ABSENT_STAT_CODES = Object.freeze(new Set(['ENOENT', 'ENOTDIR']));
+
+/**
+ * Raised when a path git listed could not be RESOLVED — the file may well be
+ * there and this process could not look at it (`EACCES`, `EPERM`, `ELOOP`,
+ * `EIO`, …). Callers are expected to fail closed on it: an enumeration that
+ * threw describes no population at all.
+ *
+ * @property {string} code the underlying `stat` error code (`EACCES`, …)
+ * @property {string} path the absolute path that could not be resolved
+ */
+export class RepoEnumerationError extends Error {
+  /**
+   * @param {string} message
+   * @param {{code?: string, path?: string, cause?: unknown}} details
+   */
+  constructor(message, { code, path: target, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'RepoEnumerationError';
+    this.code = code;
+    this.path = target;
+  }
+}
+
+/**
+ * True when `relative` (POSIX, repo-relative) is inside a pruned tree.
+ * A prune entry matches either a whole path SEGMENT (`node_modules`) or a
+ * repo-relative path PREFIX (`.orchestrator/tmp`).
+ *
+ * @param {string} relative repo-relative POSIX path
+ * @param {string[]} prune
+ * @returns {boolean}
+ */
+function isPruned(relative, prune) {
+  const segments = relative.split('/');
+  for (const entry of prune) {
+    if (entry.includes('/')) {
+      if (relative === entry || relative.startsWith(`${entry}/`)) return true;
+    } else if (segments.includes(entry)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** @returns {NodeJS.ProcessEnv} the allowlisted git environment */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = {};
+  for (const key of GIT_ENV_ALLOWLIST) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  return env;
+}
+
+/**
+ * Normalise `exts` into a predicate over an absolute path.
+ * @param {string[] | null | undefined} exts extensions, with or without the dot
+ * @returns {(absolute: string) => boolean}
+ */
+function extFilter(exts) {
+  if (!exts || exts.length === 0) return () => true;
+  const set = new Set(exts.map((e) => (e.startsWith('.') ? e : `.${e}`)));
+  return (absolute) => set.has(path.extname(absolute));
+}
+
+/**
+ * Files that EXIST under `dirs` — tracked or not — minus gitignored content
+ * and minus `prune`.
+ *
+ * Drop-in shaped like `listRepoFiles()`: absolute paths, sorted, deduplicated,
+ * never throwing for a missing directory (it contributes zero files).
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot absolute repository root
+ * @param {string[]} [options.dirs] repo-relative directories to scan (default: the whole root)
+ * @param {string[] | null} [options.exts] extensions to keep (default: every file)
+ * @param {string[]} [options.prune] path segments / repo-relative prefixes to skip
+ *   (default: {@link DEFAULT_PRUNE}; REPLACES the default when given, so pass
+ *   `[...DEFAULT_PRUNE, 'extra']` to extend it rather than to swap it)
+ * @param {(target: string) => import('node:fs').Stats} [options.stat] injection
+ *   seam for tests (default: `statSync`) — the same shape `collectDriftHits()`
+ *   uses for its `enumerate`/`read` seams
+ * @returns {string[]} absolute paths, sorted
+ * @throws {RepoEnumerationError} when a listed path can neither be resolved
+ *   nor proven absent (`EACCES`, `EPERM`, `ELOOP`, …) — see the module header's
+ *   failure table. Only the git path raises; the non-git fallback walk cannot.
+ */
+export function enumerateRepoFiles({
+  repoRoot,
+  dirs,
+  exts = null,
+  prune = DEFAULT_PRUNE,
+  stat = statSync,
+} = {}) {
+  const matches = extFilter(exts);
+  const pruneList = [...prune];
+  const env = gitEnv();
+
+  if (isGitToplevel(repoRoot, env)) {
+    const pathspecs = dirs && dirs.length > 0 ? dirs.filter((d) => d !== '.') : [];
+    try {
+      // `--cached --others --exclude-standard` = tracked PLUS untracked, minus
+      // everything `.gitignore`/`.git/info/exclude` excludes. `--deduplicate`
+      // is deliberately not used: it needs git >= 2.31 and the Set below is
+      // free. See the module header for why this beats both a bare
+      // `ls-files` (#1248) and a bare walk (#1143).
+      const out = execFileSync(
+        'git',
+        ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', ...pathspecs],
+        {
+          cwd: repoRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          maxBuffer: 64 * 1024 * 1024,
+          env,
+        },
+      );
+      const found = new Set();
+      for (const rel of out.split('\0')) {
+        if (!rel) continue;
+        if (isPruned(rel, pruneList)) continue;
+        const absolute = path.join(repoRoot, rel);
+        if (!matches(absolute)) continue;
+        // A tracked path can be absent from the working tree (sparse checkout,
+        // a deletion staged elsewhere). A scanner that then read it would
+        // report a tool-error for a file nobody removed — so ABSENT is skipped.
+        // Anything else means the file may be there and we could not look:
+        // fail closed rather than shrink the census in silence (header table).
+        let entry;
+        try {
+          entry = stat(absolute);
+        } catch (err) {
+          const code = err && err.code;
+          if (ABSENT_STAT_CODES.has(code)) continue;
+          throw new RepoEnumerationError(
+            `cannot stat ${absolute} (${code || 'unknown error'}): the file may exist and could not be read — enumeration is inconclusive`,
+            { code, path: absolute, cause: err },
+          );
+        }
+        if (!entry.isFile()) continue;
+        found.add(absolute);
+      }
+      return [...found].sort();
+    } catch (err) {
+      // A resolution failure is NOT a reason to retry with a weaker oracle:
+      // the walk would skip the same unreadable entry silently and hand back a
+      // census that looks complete. Only a git/`ls-files` failure falls
+      // through — there we have no index to trust in the first place.
+      if (err instanceof RepoEnumerationError) throw err;
+      // fall through to the walk — a git that answered rev-parse but failed
+      // ls-files leaves us with no index to trust.
+    }
+  }
+
+  // Non-git root (tarball export, vendored copy, tmpdir fixture): the walk in
+  // `repo-files.mjs` is the reuse — it already skips symlinks and unreadable
+  // sub-trees. It excludes by directory BASENAME only, so prefix-shaped prune
+  // entries are re-applied here.
+  const basenamePrune = pruneList.filter((entry) => !entry.includes('/'));
+  return listOnDiskFiles(repoRoot, { dirs, exts, exclude: basenamePrune }).filter((absolute) => {
+    const rel = path.relative(repoRoot, absolute).split(path.sep).join('/');
+    return !isPruned(rel, pruneList);
+  });
+}