session-orchestrator 4.0.0 → 4.0.1

package/scripts/lib/validate/confidential-names.mjs

@@ -15,12 +15,33 @@
  * names and REDACTS any match from its output (a CP11 hit printed verbatim to the
  * public CI log would be a WORSE leak than the one being guarded).
  *
- * Contract:
- *   loadConfidentialNames({ namesPath, deps? }) → string[] | null
+ * Contract (#1250 + #1264 — TWO entry points; the discriminated one is ADDITIVE):
+ *   loadConfidentialNames({ namesPath, deps? })    → string[] | null   (4.0.0 shape)
+ *   inspectConfidentialNames({ namesPath, deps? }) → { status, names } (discriminated)
  *
- *   - `namesPath` empty/whitespace/non-string → null (no list configured; SILENT —
- *     this is the default for the ~99% of hosts without a list).
- *   - file missing / unreadable / malformed-JSON / non-array → null + one stderr WARN.
+ *   status ∈ 'ok' | 'empty' | 'all-dropped' | 'missing' | 'malformed' | 'unconfigured'
+ *   names  is the validated list for 'ok', and `[]` for every other status.
+ *
+ *   `loadConfidentialNames` is the 4.0.0 PUBLIC contract and is preserved verbatim
+ *   (`string[] | null`, null-collapsing): `package.json` carries no `exports` map,
+ *   so a consumer repo can deep-import this module and a PATCH release must not
+ *   break it. It is a thin wrapper over `inspectConfidentialNames`, which reports
+ *   the class the older shape collapsed into `null` — exactly the distinction
+ *   CP11's fail-closed verdict turns on: 'unconfigured' and 'empty' are operator
+ *   choices (inactive, PASS), while 'missing', 'malformed' and 'all-dropped' mean
+ *   a configured guard could not run (fail closed). The scanner had to re-read and
+ *   re-classify the file to recover a class the loader already knew; it no longer does.
+ *
+ *   - `namesPath` empty/whitespace/non-string → 'unconfigured' (SILENT — this is
+ *     the default for the ~99% of hosts without a list).
+ *   - file missing → 'missing' + one stderr WARN.
+ *   - unreadable / malformed-JSON / non-array → 'malformed' + one stderr WARN.
+ *   - readable, well-formed, parsed array of length 0 → 'empty'. The operator
+ *     deliberately wrote `[]` to switch CP11 off; that is a silent PASS.
+ *   - readable, well-formed, parsed array NON-empty but every entry dropped by
+ *     validation → 'all-dropped'. Distinct from 'empty' on purpose: the operator
+ *     INTENDED names here, so a guard that ends up with zero patterns must fail
+ *     closed rather than pass silently (W4 finding F3).
  *   - Each entry is validated: it must be a non-empty string within a length cap
  *     (MAX_NAME_LENGTH — a ReDoS/DoS guard against a manipulated host-local file;
  *     a real customer/repo name never exceeds it). Entries failing either check
@@ -29,11 +50,16 @@
  *   - Result is CACHED per process, keyed by namesPath (the scanner reads it once).
  *
  * Privacy: this module never writes the list anywhere; it only reads the operator's
- * host-local file. WARN messages carry the file PATH (the operator's own config
- * path, shown transiently on their terminal) but NEVER the confidential names.
+ * host-local file. WARN messages carry NEITHER the confidential names NOR the file
+ * PATH — only `basename(namesPath)` (W4 finding F1). The full path is host-local
+ * (`/Users/<name>/…`), and these WARNs fire on exactly the branches the scanner turns
+ * into a `FAIL` + exit 1 — output an operator pastes into a PUBLIC CI log, where the
+ * path would leak the very shape CP1 exists to block. The scanner's own
+ * `disabledReason` strings have always been path-free; the loader now matches them.
  */
 
 import { readFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
 
 /**
  * Max characters for a single confidential name. A real customer / repo name is
@@ -43,7 +69,7 @@ import { readFileSync, existsSync } from 'node:fs';
  */
 const MAX_NAME_LENGTH = 256;
 
-/** Per-process cache: namesPath → (string[] | null). */
+/** Per-process cache: namesPath → `{ status, names }` (shared by BOTH entry points). */
 const _cache = new Map();
 
 /**
@@ -63,14 +89,18 @@ const DEFAULT_DEPS = {
 
 /**
  * Parse + validate the raw JSON body into a list of confidential names.
- * Returns null when the body is malformed or yields zero usable entries.
+ *
+ * Distinguishes THREE zero-name outcomes, because the caller's verdict differs
+ * between them: 'malformed' (unparseable or not an array), 'empty' (a parsed array
+ * of length 0 — the operator deliberately switched CP11 off) and 'all-dropped'
+ * (the operator DID list entries, and validation rejected every one of them).
  *
  * @param {string} raw
- * @param {string} namesPath
+ * @param {string} label - basename of the names file, for WARN text (never the path)
  * @param {{ warn: (msg: string) => void }} d
- * @returns {string[]|null}
+ * @returns {{ status: 'ok'|'empty'|'all-dropped'|'malformed', names: string[] }}
  */
-function parseNames(raw, namesPath, d) {
+function parseNames(raw, label, d) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -78,19 +108,20 @@ function parseNames(raw, namesPath, d) {
     // Fix 3 (security-reviewer): NEVER embed err.message — V8's JSON.parse error
     // text echoes the first ~10 chars of the file body, which for a confidential-
     // names file is a would-be confidential-name prefix. Log only the error CLASS
-    // (err.name, e.g. SyntaxError) + the path. Keeps the module-docstring invariant
-    // ("WARN messages … NEVER the confidential names") true.
+    // (err.name, e.g. SyntaxError) + the file BASENAME (never the host-local path,
+    // W4 finding F1). Keeps the module-docstring invariant ("WARN messages … NEVER
+    // the confidential names") true.
     d.warn(
-      `WARN validate/confidential-names: malformed JSON in ${namesPath} (${err.name}); CP11 inactive\n`,
+      `WARN validate/confidential-names: malformed JSON in ${label} (${err.name}); CP11 inactive\n`,
     );
-    return null;
+    return { status: 'malformed', names: [] };
   }
 
   if (!Array.isArray(parsed)) {
     d.warn(
-      `WARN validate/confidential-names: ${namesPath} must be a JSON array of strings; ignoring the list (CP11 inactive)\n`,
+      `WARN validate/confidential-names: ${label} must be a JSON array of strings; ignoring the list (CP11 inactive)\n`,
     );
-    return null;
+    return { status: 'malformed', names: [] };
   }
 
   const names = [];
@@ -115,55 +146,89 @@ function parseNames(raw, namesPath, d) {
     // Deliberately omit the offending entries — logging them would leak the very
     // confidential names the list exists to keep host-local. COUNTS only.
     d.warn(
-      `WARN validate/confidential-names: ignored ${ignoredInvalid} invalid and ${ignoredOversized} oversized (>${MAX_NAME_LENGTH} chars) name entr(ies) in ${namesPath}\n`,
+      `WARN validate/confidential-names: ignored ${ignoredInvalid} invalid and ${ignoredOversized} oversized (>${MAX_NAME_LENGTH} chars) name entr(ies) in ${label}\n`,
     );
   }
 
-  return names.length > 0 ? names : null;
+  if (names.length > 0) return { status: 'ok', names };
+  // F3 (W4 panel, fail-open): a file whose entries were ALL dropped by validation
+  // is NOT the operator's `[]` opt-out — they listed names and meant them to bind.
+  // Collapsing both into 'empty' made the scanner treat a corrupted list as a
+  // deliberate opt-out and PASS silently with CP11 inactive.
+  return parsed.length > 0
+    ? { status: 'all-dropped', names: [] }
+    : { status: 'empty', names: [] };
 }
 
 /**
- * Load and validate the host-local confidential-names list. Defensive — never throws.
+ * Load and validate the host-local confidential-names list, reporting WHY the list
+ * is unusable when it is. Defensive — never throws.
  *
  * @param {object} opts
  * @param {string|null|undefined} opts.namesPath - absolute path to the names JSON, or
  *   empty/absent when no list is configured.
  * @param {Partial<typeof DEFAULT_DEPS>} [opts.deps] - injected fs / warn (tests).
- * @returns {string[]|null} the validated names, or null when unconfigured/unusable.
+ * @returns {{ status: 'ok'|'empty'|'all-dropped'|'missing'|'malformed'|'unconfigured', names: string[] }}
+ *   the validated names under `status: 'ok'`; `names` is `[]` for every other status.
  */
-export function loadConfidentialNames({ namesPath, deps = {} } = {}) {
+export function inspectConfidentialNames({ namesPath, deps = {} } = {}) {
   const d = { ...DEFAULT_DEPS, ...deps };
 
   // Unconfigured → no list, no noise. This is the normal case for public repos
   // and for any host that has not opted into confidential-name scanning.
   if (typeof namesPath !== 'string' || namesPath.trim() === '') {
-    return null;
+    return { status: 'unconfigured', names: [] };
   }
 
   if (_cache.has(namesPath)) {
     return _cache.get(namesPath);
   }
 
-  let result = null; // default when the file is missing/unreadable/unusable
+  // Default when the file is missing; the read/parse branches below overwrite it.
+  let result = { status: 'missing', names: [] };
   try {
     if (!d.existsSync(namesPath)) {
       d.warn(
-        `WARN validate/confidential-names: confidential-names-file is set but the file does not exist: ${namesPath}; CP11 inactive\n`,
+        `WARN validate/confidential-names: confidential-names-file is set but the file does not exist: ${basename(namesPath)}; CP11 inactive\n`,
       );
     } else {
       const raw = d.readFileSync(namesPath, 'utf8');
-      result = parseNames(raw, namesPath, d);
+      result = parseNames(raw, basename(namesPath), d);
     }
   } catch (err) {
     // Fix 3 (security-reviewer): log the error CLASS, not err.message. A filesystem
     // error rarely embeds file content, but keeping the invariant uniform ("the WARN
-    // carries only counts / err-class + the path, never file body") removes the last
-    // err.message sink in this module.
+    // carries only counts / err-class + the file basename, never the path and never
+    // file body") removes the last err.message sink in this module.
     d.warn(
-      `WARN validate/confidential-names: failed to read confidential-names file at ${namesPath} (${err.name}); CP11 inactive\n`,
+      `WARN validate/confidential-names: failed to read confidential-names file ${basename(namesPath)} (${err.name}); CP11 inactive\n`,
     );
+    // An unreadable file is NOT 'missing' — existsSync said it is there. It shares
+    // the 'malformed' verdict (configured but unusable → the caller fails closed).
+    result = { status: 'malformed', names: [] };
   }
 
   _cache.set(namesPath, result);
   return result;
 }
+
+/**
+ * The 4.0.0 PUBLIC contract, preserved verbatim: the validated names, or `null`
+ * whenever no usable list could be loaded (unconfigured, missing, malformed,
+ * empty, all-dropped alike). `package.json` has no `exports` map, so a consumer
+ * repo may deep-import this function; a PATCH release must not change its shape.
+ *
+ * In-tree callers that need to distinguish an operator OPT-OUT from a guard that
+ * FAILED TO RUN must use `inspectConfidentialNames` instead — that distinction is
+ * precisely what this return type cannot express.
+ *
+ * @param {object} opts
+ * @param {string|null|undefined} opts.namesPath
+ * @param {Partial<typeof DEFAULT_DEPS>} [opts.deps]
+ * @returns {string[] | null}
+ */
+export function loadConfidentialNames({ namesPath, deps = {} } = {}) {
+  // Shares the one cache entry: inspect() keys it, this derives from the result.
+  const { names } = inspectConfidentialNames({ namesPath, deps });
+  return names.length > 0 ? names : null;
+}

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

@@ -178,6 +178,37 @@ function walk(absDir, matches, exclude, acc = []) {
   return acc;
 }
 
+/**
+ * Error codes that mean "this tracked path is not in the working tree" — a
+ * sparse checkout, or a deletion staged from somewhere else. Both are ordinary
+ * repository states, so the path is dropped from the census silently.
+ *
+ * Every OTHER stat error (EACCES on an unreadable parent, EIO, ELOOP, ENAMETOOLONG)
+ * describes a filesystem the caller cannot enumerate. Swallowing those returned a
+ * SHORTER census that looked exactly like a smaller repository, which is the
+ * failure mode a scanner can neither see nor report.
+ */
+const ABSENT_FROM_WORKTREE = Object.freeze(['ENOENT', 'ENOTDIR']);
+
+/**
+ * True when `absolute` is a regular file present in the working tree; false
+ * when it is absent for one of the {@link ABSENT_FROM_WORKTREE} reasons.
+ * Rethrows every other stat error.
+ *
+ * @param {string} absolute
+ * @returns {boolean}
+ */
+function isPresentFile(absolute) {
+  try {
+    return statSync(absolute).isFile();
+  } catch (err) {
+    if (ABSENT_FROM_WORKTREE.includes(/** @type {NodeJS.ErrnoException} */ (err).code)) {
+      return false;
+    }
+    throw err;
+  }
+}
+
 /**
  * Resolve the `dirs` option to absolute directories under `root`.
  * `'.'` (or an empty list) means the root itself.
@@ -212,33 +243,36 @@ export function listRepoFiles(root, options = {}) {
 
   if (isGitToplevel(root, env)) {
     const pathspecs = dirs && dirs.length > 0 ? dirs.filter((d) => d !== '.') : [];
+    /** @type {string | null} */
+    let out = null;
     try {
-      const out = execFileSync('git', ['ls-files', '-z', '--', ...pathspecs], {
+      out = execFileSync('git', ['ls-files', '-z', '--', ...pathspecs], {
         cwd: root,
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'ignore'],
         maxBuffer: 64 * 1024 * 1024,
         env,
       });
+    } catch {
+      // fall through to the walk — a git that answered rev-parse but failed
+      // ls-files leaves us with no index to trust.
+      //
+      // This catch covers the `ls-files` INVOCATION only. The census below is
+      // deliberately outside it: a stat error there is not "git has no index",
+      // and folding the two together would turn an unreadable working tree
+      // into a silent full-repo re-walk.
+      //
+      // `out` keeps its `null` initialiser here — no reassignment, so the
+      // `out !== null` test below is the single place the two paths diverge.
+    }
+    if (out !== null) {
       return out
         .split('\0')
         .filter(Boolean)
         .map((rel) => path.join(root, rel))
         .filter(matches)
-        // 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.
-        .filter((absolute) => {
-          try {
-            return statSync(absolute).isFile();
-          } catch {
-            return false;
-          }
-        })
+        .filter(isPresentFile)
         .sort();
-    } catch {
-      // fall through to the walk — a git that answered rev-parse but failed
-      // ls-files leaves us with no index to trust.
     }
   }
 

package/scripts/release.mjs

@@ -121,12 +121,10 @@ export const SURFACES = [
     patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/],
   },
   {
-    // Root `plugin.json` — the agent-plugins.org 1.0.0 manifest, added in 4.0.0. It is a
-    // FOURTH manifest carrying the version, and it was missing from this table on the 4.0.0
-    // cut: `--set-version` bumped the other three and `validate-plugin` then failed with
-    // "plugin.json version '3.24.0' != package.json version '4.0.0'". Exactly the incident
-    // class the table exists for, caught one gate later than it should have been.
-    file: 'plugin.json',
+    // Cursor's native manifest replaces the root Agent Plugins manifest so
+    // Codex can load its own component paths and cache version independently.
+    // It remains a required version surface for every release.
+    file: '.cursor-plugin/plugin.json',
     patterns: [/"version":\s*"(\d+\.\d+\.\d+)"/],
   },
   {
@@ -191,6 +189,14 @@ export const SURFACES = [
     patterns: [/data-metric="version"[^>]*>(\d+\.\d+\.\d+)</g],
     checkOnly: true,
   },
+  {
+    // The German landing page (2026-09-07 redesign) mirrors the EN metric cells
+    // one-to-one; same single writer (scripts/site-numbers.mjs --write), so it is
+    // checkOnly for the same reason as site/index.html above.
+    file: 'site/de/index.html',
+    patterns: [/data-metric="version"[^>]*>(\d+\.\d+\.\d+)</g],
+    checkOnly: true,
+  },
   {
     file: 'site/llms.txt',
     patterns: [/Version:\s*(\d+\.\d+\.\d+)/],
@@ -362,7 +368,18 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // tests/scripts/site-numbers.test.mjs, which forbids ANY vX.Y.Z and the current
 // package version outside a `data-metric` cell on EVERY shipped page, and
 // exempts exactly the lines marked `site-numbers:historical`.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|docs\/|tests\/|skills\/npm-publish\/|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|commands\/release\.md)/;
+// 4.0.1 (measured 2026-09-07): the 4.0.0 sweep would have flagged five files whose only literal
+// is PROSE HISTORY of the major ("moved out of agents/ in 4.0.0", "removed in 4.0.0",
+// "releases 4.0.0 would have blocked on itself") — CLAUDE.md, its generated twin AGENTS.md,
+// CONTRIBUTING.md, NOTICE and .husky/pre-push. None of them is a version SURFACE (no
+// `"version":`, badge or `vX.Y.Z` form), so they join the history allowlist rather than being
+// reworded to dodge the sweep.
+// Four more prose-history files surfaced once the detail line stopped truncating at five hits
+// (same 2026-09-07 sweep): site/llms-full.txt ("The v4.0.0 release REMOVES public surfaces" — its
+// version SURFACE is checked separately by the SURFACES row, so the sweep on it is redundant),
+// skills/architecture/references/domain-model.md ("Merged here in v4.0.0"), skills/autopilot/SKILL.md
+// ("4.0.0 — see docs/migration-v4.md") and templates/_shared/journey-manifest.md ("Retired … in 4.0.0").
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|templates\/_shared\/journey-manifest\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -443,28 +460,95 @@ export const MIN_PACKED_ENTRIES = 400;
 // ---------------------------------------------------------------------------
 
 /**
- * Is EVERY occurrence of `literal` on this line a dependency range (`^X.Y.Z` / `~X.Y.Z`)?
+ * A regex matching `literal` as a VERSION TOKEN, not as a substring.
+ *
+ * THE BUG (measured 2026-09-07, mid-release): the sweep matched the previous tag `4.0.0`
+ * inside `>=24.0.0` — `package.json`'s own engines field and a `scripts/lib/` string that
+ * quotes it — so a release could not be cut without either rewording an engines constraint or
+ * widening the allowlist over two files that carry no version surface at all. The boundary is
+ * therefore part of WHAT IS SWEPT FOR, not an allowlist row: `24.0.0`, `14.0.0` and `4.0.0.1`
+ * are different literals, at every path, forever.
+ *
+ * @param {string} literal — the previous release version
+ * @returns {RegExp} global regex; `4.0.0` matches only when not preceded by `[0-9.]` and not
+ *   continued by a further numeric component (`(?!\.?[0-9])`).
+ */
+function versionTokenRegex(literal) {
+  return new RegExp(`(?<![0-9.])${literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?!\\.?[0-9])`, 'g');
+}
+
+/**
+ * Is EVERY token occurrence of `literal` on this line a dependency range (`^X.Y.Z` / `~X.Y.Z`)?
  *
  * One bare occurrence anywhere on the line is enough to call the whole line drift — a comment
- * that also happens to mention a ranged dep must not be excused by that mention.
+ * that also happens to mention a ranged dep must not be excused by that mention. Occurrences are
+ * counted with {@link versionTokenRegex}, so `>=24.0.0` is not an occurrence of `4.0.0` here
+ * either — otherwise a line pinning `^4.0.0` beside an engines constraint would read as drift.
  *
  * @param {string} content — the matching line's text
- * @param {string} literal — the previous release version, matched literally
+ * @param {string} literal — the previous release version, matched as a token
  * @returns {boolean}
  */
 export function isDependencyRangeOnly(content, literal) {
-  let from = 0;
+  const re = versionTokenRegex(literal);
   let seen = 0;
-  for (;;) {
-    const at = content.indexOf(literal, from);
-    if (at === -1) break;
+  for (let m = re.exec(content); m; m = re.exec(content)) {
     seen += 1;
-    if (!(at > 0 && (content[at - 1] === '^' || content[at - 1] === '~'))) return false;
-    from = at + literal.length;
+    const before = m.index > 0 ? content[m.index - 1] : '';
+    if (before !== '^' && before !== '~') return false;
   }
   return seen > 0;
 }
 
+/** Lockfiles whose dependency entries are third-party history, never our surface. */
+const LOCKFILE_BASENAMES = new Set(['package-lock.json', 'npm-shrinkwrap.json']);
+
+/** Code files in which a `//`, `*`, `/*` or `#` line is comment prose, never a version surface. */
+const CODE_COMMENT_EXTENSIONS = new Set(['.mjs', '.js', '.cjs', '.ts', '.sh']);
+
+/**
+ * Is this `path:line:content` row version HISTORY rather than a stale surface?
+ *
+ * Three classes, all measured on the 4.0.1 cut (2026-09-07) as FALSE POSITIVES of the raw
+ * substring sweep, and all expressed as PREDICATES for the same reason the range carve-out
+ * above is one: a per-path allowlist row fixes the instance and leaves the class open.
+ *
+ * 1. **Dependency range** — `^X.Y.Z` / `~X.Y.Z` (see {@link isDependencyRangeOnly}).
+ * 2. **Lockfile dependency entry** — `package-lock.json` carried 72 hits for `4.0.0`, every one
+ *    a third-party package version or an engines range. Our OWN entry there is still swept: the
+ *    root package's `"version"` line, which npm writes in the `packages[""]` record at the top
+ *    of the file. NAMED CEILING (BV-004): "at the top" is read as `line <= 20`, which covers
+ *    every lockfileVersion-3 file npm writes today (the root record starts at line 5). Revisit
+ *    trigger: a lockfile whose root `"version"` sits below line 20 — then key on the enclosing
+ *    JSON path instead of the line number.
+ * 3. **Comment prose in a code file** — `// (pre-4.0.0 checkouts, …)` and a `* since 4.0.0`
+ *    docblock line. No SURFACES pattern is ever a comment (every one is `"version": "X.Y.Z"`,
+ *    `vX.Y.Z` or a badge), so excusing comment lines cannot mask a stale surface.
+ *
+ * @param {string} file — repo-relative path
+ * @param {number} line — 1-based line number
+ * @param {string} content — the matching line's text
+ * @param {string} prevTag — the previous release literal being swept for
+ * @returns {boolean} true = history, skip the row
+ */
+function isHistoryRow(file, line, content, prevTag) {
+  if (!versionTokenRegex(prevTag).test(content)) return true;
+  if (isDependencyRangeOnly(content, prevTag)) return true;
+  const base = file.split('/').pop();
+  if (LOCKFILE_BASENAMES.has(base)) {
+    const isRootVersionLine = line <= 20 && new RegExp(`"version":\\s*"${prevTag.replace(/\./g, '\\.')}"`).test(content);
+    return !isRootVersionLine;
+  }
+  const dot = base.lastIndexOf('.');
+  const ext = dot === -1 ? '' : base.slice(dot);
+  if (CODE_COMMENT_EXTENSIONS.has(ext)) {
+    const trimmed = content.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) return true;
+    if (ext === '.sh' && trimmed.startsWith('#')) return true;
+  }
+  return false;
+}
+
 /**
  * Drift sweep verdict over a grep-shaped result (`-l` file list or `-n` line hits).
  *
@@ -488,6 +572,13 @@ export function isDependencyRangeOnly(content, literal) {
  * written as one (see SURFACES above: every pattern is an exact `"version": "X.Y.Z"`, `vX.Y.Z`
  * or badge form), so the predicate cannot mask a stale surface.
  *
+ * THREE FURTHER CLASSES are history for the same reason, all measured 2026-09-07 mid-release
+ * and all decided by {@link isHistoryRow}, never by an allowlist row: a literal that is only a
+ * SUBSTRING of a longer version (`4.0.0` inside `>=24.0.0`), a `package-lock.json` /
+ * `npm-shrinkwrap.json` row that is not the root package's own `"version"` line (72 of the 72
+ * lockfile hits on that cut were third-party), and COMMENT PROSE in a code file
+ * (`// (pre-4.0.0 checkouts, …)`). See that function for each one's ceiling.
+ *
  * Accepts BOTH `git grep` output shapes. A bare `path` (from `-l`) carries no content and is
  * therefore always a hit — the fail-closed reading, unchanged, and the shape {@link collectDriftHits}
  * emits for a file it could not READ. `path:line:content` (from `-n`)
@@ -510,13 +601,13 @@ export function evaluateDriftSweep(grep, prevTag, allowlist) {
     const withContent = row.match(/^(.+?):(\d+):(.*)$/);
     const file = withContent ? withContent[1] : row;
     if (allowlist.test(file)) continue;
-    if (withContent && isDependencyRangeOnly(withContent[3], prevTag)) continue;
+    if (withContent && isHistoryRow(file, Number(withContent[2]), withContent[3], prevTag)) continue;
     if (!hits.includes(file)) hits.push(file);
   }
   return {
     ok: hits.length === 0,
     detail: hits.length
-      ? `still carry ${prevTag}: ${hits.slice(0, 5).join(', ')}`
+      ? `still carry ${prevTag} (${hits.length} file(s)): ${hits.slice(0, 5).join(', ')}${hits.length > 5 ? ', …' : ''}`
       : `no file outside the allowlist still carries ${prevTag} (tracked + untracked-not-ignored)`,
   };
 }