fix(gates): give the in-process ESLint ratchets the parser stack headroom pnpm lint already has (#10464)

* fix(gates): give the in-process ESLint ratchets the parser stack headroom `pnpm lint` already has

`check:slot-lookup` and `check:query-options-erasure` drive ESLint through its
Node API, so neither inherits the `--stack-size=4000` the root `lint` script
puts on ESLint's CLI entry. Measured on this tree: the gates' own ESLint channel
fails to parse `packages/spec/src/migrations/registry.ts` 10/10 runs at the
default V8 stack and 0/10 with the flag; the gates' whole-population runs failed
2 in 14 at the default stack, which is why every red read as a flake.

Both gates now re-exec themselves once with the flag, following the re-exec
precedent in `scripts/pm/check-governed-merges.mjs`. The headroom lives in the
gate rather than in a script line so it cannot be dropped by invoking the gate
a different way.

A self-test asserts the current `registry.ts` still parses through the gate's
own channel -- a parse, never a pinned depth or a pinned stack size, because
that file gains a step per breaking protocol major and any number would expire
at the next one.

Part of #10449

* fix(gates): make the headroom adoption check immune to a commented-out call

Found by ablating the check itself: commenting out
`ensureStackHeadroom(...)` left the identifier in the source, so the regex
still matched and the self-test reported the gate as armed at exactly the
moment it stopped being armed. Strip whole-line comments before testing.

* refactor(gates): use the repo's shared js-comment-mask instead of a private strip

scripts/js-comment-mask.mjs is 'the ONE answer' to comment-or-code and exists
precisely to retire per-gate copies of this logic (#9367). stripComments
rather than maskComments: this check reports gate names, never offsets.
Ablation re-run against it -- a commented-out ensureStackHeadroom() call is
still caught.

* style(gates): arm the headroom before the constant block, not inside it

Pure reordering -- the re-exec already ran before any linting; this just stops
it splitting the two gates' constant blocks in half.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

scripts/check-query-options-erasure-ratchet.mjs

@@ -98,6 +98,25 @@ import eslintConfig, {
   QUERY_OPTIONS_ANY_MESSAGE,
 } from '../eslint.config.mjs';
 import { checkGuardAdoption, collectFatalMessages, lintFilesStrict } from './eslint-fatal-guard.mjs';
+import {
+  HEADROOM_CANARY_FILE,
+  PARSER_STACK_SIZE_KB,
+  STACK_FLAG,
+  STACK_REARM_GUARD,
+  canaryParseFailures,
+  checkHeadroomAdoption,
+  ensureStackHeadroom,
+  formatCanaryFailure,
+  osThreadStackKb,
+  stackRearmPlan,
+} from './eslint-stack-headroom.mjs';
+
+// This gate lints IN-PROCESS, so it does not inherit the `--stack-size` the
+// root `lint` script puts on ESLint's CLI entry, and this repo's deepest file
+// does not parse without it (#10449). Re-exec once, before any linting --
+// including before `--self-test`, whose headroom assertion below is only a fact
+// about the gate if the self-test runs on the same stack the gate does.
+ensureStackHeadroom(fileURLToPath(import.meta.url));
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(__dirname, '..');
@@ -443,6 +462,77 @@ async function selfTest() {
     for (const problem of checkGuardAdoption(repoRoot)) assert(false, problem);
   }
 
+  // -- 5. Parser headroom: the population's deepest file must actually PARSE. --
+  //
+  // The fatal guard above makes an unparseable file LOUD. This makes it not
+  // happen. Both gates lint in-process, so neither inherits the `--stack-size`
+  // the root `lint` script puts on ESLint's CLI entry, and #10449 is what that
+  // gap costs: `packages/spec/src/migrations/registry.ts` stopped parsing on
+  // the default V8 stack, so both gates started failing on a file the author
+  // never touched -- INTERMITTENTLY, because the verdict depends on the other
+  // files in the same run, which is what let every red be re-run away as a
+  // flake for a day.
+  //
+  // ⭐ Why this asserts a PARSE and not a number. `registry.ts` is an ADR-0087
+  // D3 forever artifact that gains a step per breaking protocol major, so its
+  // AST depth only ever rises. A pinned depth or a pinned minimum stack would
+  // be true today and quietly wrong at the next major -- the same defect
+  // arriving a fourth time. Asking "does the file the gate must read still read
+  // at the headroom the gate actually has" re-measures the real question every
+  // run and cannot expire.
+  //
+  // And it is an EARLY warning, not a restatement of the gate: measured on the
+  // tree that filed #10449, this single-file parse failed 10/10 runs at the
+  // default stack while the gates' own whole-population runs failed 2/14. The
+  // narrow scope is the worst case, so this trips a full margin before the
+  // population run starts reddening other people's PRs.
+  {
+    assert(
+      stackRearmPlan({ execArgv: [], env: {}, flagSupported: true }).rearm === true,
+      'a plain run must re-exec itself with parser headroom',
+    );
+    assert(
+      stackRearmPlan({ execArgv: [STACK_FLAG], env: {}, flagSupported: true }).rearm === false,
+      'a run that already carries --stack-size must not re-exec again',
+    );
+    assert(
+      stackRearmPlan({ execArgv: [], env: { [STACK_REARM_GUARD]: '1' }, flagSupported: true }).rearm === false,
+      'the guard variable must stop a second re-exec -- otherwise a rearm is a spawn loop',
+    );
+    assert(
+      stackRearmPlan({ execArgv: [], env: {}, flagSupported: false }).rearm === false,
+      'a node that rejects the flag must degrade, not spawn a child that cannot start',
+    );
+
+    // The flag is on THIS process, so what follows is measured with the
+    // headroom rather than merely alongside a flag on some command line.
+    assert(
+      process.execArgv.some((a) => a.startsWith('--stack-size')),
+      `this self-test is running without --stack-size (execArgv: ${JSON.stringify(process.execArgv)}). ` +
+      'ensureStackHeadroom() did not re-exec, so the parse proved below is not the one the gate gets.',
+    );
+
+    // Above the OS thread stack V8 runs off the real stack and SIGSEGVs instead
+    // of throwing a clean RangeError, so headroom that crosses it converts a
+    // loud gate into a crash. Read the real limit rather than pinning one.
+    const osStackKb = osThreadStackKb();
+    if (osStackKb !== null) {
+      assert(
+        PARSER_STACK_SIZE_KB < osStackKb,
+        `PARSER_STACK_SIZE_KB (${PARSER_STACK_SIZE_KB}) is not below this machine's ` +
+        `thread stack (ulimit -s = ${osStackKb} KB). At or above it V8 SIGSEGVs instead of ` +
+        'throwing, which turns every parse failure into an unexplained crash.',
+      );
+    }
+
+    const canaryFatals = await canaryParseFailures(eslint, { repoRoot });
+    assert(canaryFatals.length === 0, formatCanaryFailure(canaryFatals));
+
+    // Importing the headroom module is not arming it, and a gate that quietly
+    // stopped arming it looks exactly like one that never lost the flag.
+    for (const problem of checkHeadroomAdoption(repoRoot)) assert(false, problem);
+  }
+
   // A missing config block must ABORT, never report clean.
   assert(eslintConfig.some(carriesRule), 'the config must carry the query-options rule');
 
@@ -454,7 +544,8 @@ async function selfTest() {
   console.log(
     `✓ self-test: ${reports.length} reporting shape(s), ${silent.length} silent counterpart(s), ` +
     `grandfathering + test-glob channels proved in both directions, ${cases.length} ratchet case(s), ` +
-    `fatal-parse guard proved both ways over real ESLint output, both gates still routed through it.`,
+    `fatal-parse guard proved both ways over real ESLint output, both gates still routed through it, ` +
+    `and ${HEADROOM_CANARY_FILE} parses at --stack-size=${PARSER_STACK_SIZE_KB} through this gate's own channel.`,
   );
 }
 

scripts/check-slot-lookup-ratchet.mjs

@@ -46,6 +46,13 @@ import { ESLint } from 'eslint';
 
 import eslintConfig, { SLOT_LOOKUP_ANY_MESSAGE } from '../eslint.config.mjs';
 import { lintFilesStrict } from './eslint-fatal-guard.mjs';
+import { ensureStackHeadroom } from './eslint-stack-headroom.mjs';
+
+// This gate lints IN-PROCESS, so it does not inherit the `--stack-size` the
+// root `lint` script puts on ESLint's CLI entry, and this repo's deepest file
+// does not parse without it (#10449). Re-exec once, before any linting, so the
+// gate carries its own headroom whatever spelling invoked it.
+ensureStackHeadroom(fileURLToPath(import.meta.url));
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(__dirname, '..');