fix(scripts): route every entry guard through one symlink-correct predicate

The `invokedDirectly` guard was hand-typed in ELEVEN distinct spellings
across 33 files in `scripts/` (the card estimated ~8), and nine of them
were wrong in the same invisible direction: node resolves symlinks for
the module graph but leaves `process.argv[1]` as the caller typed it, so
a script reached through a symlink compared two different paths, answered
false, and did nothing -- exit 0, no output.

Measured on origin/main, 31 of 33 went inert through a symlink. The one
that matters most is the governed-surface register:

  scripts/pm/check-governed-merges.mjs --test AGENTS.md
    direct  : exit=3, "GOVERNED -- no seat arms auto-merge"
    symlink : exit=0, no output

and EXIT_TEST_NOT_GOVERNED is 0, so through a symlink the register's
"this PR is GOVERNED" answer and its "NOT governed, ordinary queue
landing applies" clearance are the same exit code.

- adds `scripts/invoked-as.mjs` -- one predicate, pinned by a self-test
  that drives a real probe through a real symlink, a differently-named
  symlink, a percent-encoding path, `node <dir>`, and both import
  directions. Aligned leg-for-leg with the sibling predicate in
  `packages/cli/src/utils/invocation.ts`.
- rewrites all 33 sites to `isEntrypoint(import.meta.url)`.
- adds `check:entry-guard`, the class-closing gate: only `invoked-as.mjs`
  may read `process.argv[1]`, so a twelfth spelling cannot be typed.

Three self-tests copy their own source into a synthetic checkout and
spawn it there; they now carry the sibling module too.

Part of #10086

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

Author: claude

.github/workflows/lint.yml

@@ -152,6 +152,26 @@ jobs:
       - name: Raw control-byte guard
         run: pnpm check:nul-bytes
 
+      # Every `scripts/**` entry guard goes through ONE predicate (#10086).
+      # The hand-typed forms of "did node run me, or did someone import me?"
+      # had drifted into ELEVEN spellings across 33 files, and NINE were wrong
+      # in the same invisible direction: node resolves symlinks for the module
+      # graph but leaves `process.argv[1]` as the caller typed it, so a script
+      # reached through a symlink compared two different paths, answered false,
+      # and did NOTHING — exit 0, no output. The CI wrappers here hold the
+      # child's exit STATUS only, so an inert child read as a green gate; the
+      # governed-surface register (`scripts/pm/check-governed-merges.mjs`) was
+      # among the affected, where the inert run and its "NOT governed, ordinary
+      # queue landing applies" verdict are the SAME exit code.
+      # The sweep alone would not have held — nothing stopped a twelfth
+      # spelling. This gate is the part that closes the class: only
+      # `scripts/invoked-as.mjs` may read `process.argv[1]`, and that module's
+      # own self-test drives a real probe through a real symlink. Rationale and
+      # the rejected behavioural-sweep alternative: the gate script's header.
+      # Scans ~115 files, no spawns; ~0.2s.
+      - name: scripts/ entry guards go through one predicate
+        run: pnpm check:entry-guard
+
       # Stack-collection enumerations vs the schema (#6242). `stack.zod.ts`
       # decides which collections a stack may declare; eight other enumerations
       # of that same set are hand-maintained (the map-format list, the

package.json

@@ -34,6 +34,7 @@
     "check:i18n-coverage": "node scripts/check-i18n-coverage.mjs --self-test && node scripts/check-i18n-coverage.mjs",
     "check:app-nav-i18n": "pnpm --filter @objectstack/cli run check:app-nav-i18n",
     "check:nul-bytes": "node scripts/check-nul-bytes.mjs --self-test && node scripts/check-nul-bytes.mjs",
+    "check:entry-guard": "node scripts/check-entry-guard.mjs --self-test && node scripts/check-entry-guard.mjs",
     "check:stack-collection-maps": "node scripts/check-stack-collection-maps.mjs --self-test && node scripts/check-stack-collection-maps.mjs",
     "check:doc-authoring": "node scripts/check-doc-authoring.mjs --self-test && node scripts/check-doc-authoring.mjs",
     "check:doc-anchors": "node scripts/check-doc-anchors.mjs --self-test && node scripts/check-doc-anchors.mjs",

scripts/check-adr-0087-registration.mjs

@@ -305,6 +305,7 @@ import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'nod
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isEntrypoint } from './invoked-as.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '..');
@@ -3640,6 +3641,9 @@ function selfTest() {
     };
     const copy = 'scripts/check-adr-0087-registration.mjs';
     w(copy, readFileSync(fileURLToPath(import.meta.url), 'utf8'));
+    // The entry guard is imported from `scripts/invoked-as.mjs`, so the sibling
+    // travels with the copy or the fixture dies on ERR_MODULE_NOT_FOUND.
+    w('scripts/invoked-as.mjs', readFileSync(new URL('./invoked-as.mjs', import.meta.url), 'utf8'));
     w(
       'importer.mjs',
       "import { readDisposition } from './scripts/check-adr-0087-registration.mjs';\n" +
@@ -3710,7 +3714,7 @@ function selfTest() {
 // the I1/I2 self-test assertions pin BOTH halves of the separation -- silent as
 // an import, unchanged as an entry point.
 
-if (resolve(process.argv[1] ?? '') === resolve(fileURLToPath(import.meta.url))) {
+if (isEntrypoint(import.meta.url)) {
   const argv = process.argv.slice(2);
   const readFlag = (name) => {
     const i = argv.indexOf(name);

scripts/check-adr-links.mjs

@@ -109,7 +109,7 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { isEntrypoint } from './invoked-as.mjs';
 
 const ADR_DIR = 'docs/adr';
 
@@ -457,7 +457,7 @@ function selfTest() {
 /* Run only when invoked as a program. The extractor is exported so a future
  * caller (or a REPL session chasing a false positive) can import it without the
  * import itself sweeping the repo. */
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isEntrypoint(import.meta.url)) {
   if (process.argv.includes('--self-test')) selfTest();
   else runCheck();
 }

scripts/check-agent-model-declared.mjs

@@ -83,6 +83,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync,
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isEntrypoint } from './invoked-as.mjs';
 
 const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const AGENTS_DIR = '.claude/agents';
@@ -562,6 +563,6 @@ function main() {
   );
 }
 
-if (resolve(process.argv[1] ?? '') === resolve(fileURLToPath(import.meta.url))) {
+if (isEntrypoint(import.meta.url)) {
   main();
 }

scripts/check-console-injection.mjs

@@ -77,6 +77,7 @@ import {
   readSpecBlob,
   readStamp,
 } from './console-spec-probes.mjs';
+import { isEntrypoint } from './invoked-as.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -474,7 +475,7 @@ function selfTest() {
 // evaluate() from a script exited 0 with "no console dist" and never reached the
 // caller's code.
 const invokedDirectly =
-  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  isEntrypoint(import.meta.url);
 
 if (!invokedDirectly) {
   // imported as a module — expose evaluate() and do nothing else

scripts/check-cross-repo-closer-outcome.mjs

@@ -109,8 +109,8 @@ import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { isMap, isSeq, parseDocument } from 'yaml';
+import { isEntrypoint } from './invoked-as.mjs';
 
 const WORKFLOW = '.github/workflows/cross-repo-issue-closer.yml';
 const JOB = 'close-foreign-issues';
@@ -1146,7 +1146,7 @@ async function selfTest() {
 // reverse-verification route needs `extractScript` / `judge` pointed at another
 // tree (a pre-fix checkout), and a module that runs its gate on import would
 // silently judge THIS repo instead and print a pass about the wrong subject.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isEntrypoint(import.meta.url)) {
   if (process.argv.includes('--self-test')) await selfTest();
   else if (process.argv.includes('--list')) list();
   else await main();

scripts/check-doc-anchors.mjs

@@ -119,10 +119,10 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import Slugger from 'github-slugger';
 
 import { stripCodeSpans, stripFencedBlocks } from './check-adr-links.mjs';
+import { isEntrypoint } from './invoked-as.mjs';
 
 /**
  * The page population this gate sweeps, as the repo-relative glob it really
@@ -604,7 +604,7 @@ function selfTest() {
 /* Run only when invoked as a program — the extractor and the slug helpers are
  * exported so a caller chasing a false positive can import them without the
  * import itself sweeping the repo. */
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isEntrypoint(import.meta.url)) {
   if (process.argv.includes('--self-test')) selfTest();
   else runCheck();
 }

scripts/check-docs-image-tag.mjs

@@ -117,6 +117,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isEntrypoint } from './invoked-as.mjs';
 
 /**
  * The package whose `version` every concrete pin below must equal.
@@ -736,7 +737,7 @@ function main() {
 // check-kernel-hook-pairs). Nothing about what this gate ASSERTS changes: both
 // `check:docs-image-tag` invocations run this file directly, where argv[1] is this
 // file and the branch is taken exactly as before.
-if (resolve(process.argv[1] ?? '') === resolve(fileURLToPath(import.meta.url))) {
+if (isEntrypoint(import.meta.url)) {
   if (process.argv.includes('--self-test')) {
     await selfTest();
   } else {

scripts/check-docs-redirects.mjs

@@ -104,6 +104,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } f
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isEntrypoint } from './invoked-as.mjs';
 
 /** The docs site's `baseUrl` (apps/docs/lib/source.ts). */
 const DOCS_BASE = '/docs';
@@ -689,7 +690,7 @@ async function main() {
  * `firstMatchingSource` are exported so a sibling gate can ask "would Fumadocs
  * serve this /docs/... URL?" without the import itself checking the redirect
  * table (and calling `process.exit` out from under its caller). */
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isEntrypoint(import.meta.url)) {
   if (process.argv.includes('--self-test')) {
     await selfTest();
   } else {