session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/ux-grill/reconcile.mjs

@@ -37,12 +37,16 @@
  * mistaken import away from filing issues nobody asked for.
  *
  * Exports:
- *   UX_GRILL_LABELS, buildIssueTitle, buildIssueBody, reconcileFindings
+ *   UX_GRILL_LABELS, buildIssueTitle, buildUxGrillIssueBody, reconcileFindings
+ *   buildIssueBody — @deprecated alias of buildUxGrillIssueBody (5.2.0 name),
+ *     removed in 6.0.0
  */
 
 import {
   createFinding as defaultCreateFinding,
+  fingerprintSentinelLine,
   listExistingFindings as defaultListExisting,
+  neutralizeFingerprintSentinel,
   triageDecision,
   updateFinding as defaultUpdateFinding,
 } from '../test-runner/issue-reconcile.mjs';
@@ -69,31 +73,22 @@ const TITLE_MAX_LENGTH = 100;
 const AUTO_SEVERITIES = Object.freeze(['critical', 'high']);
 
 /**
- * Neutralise a fingerprint-sentinel literal in free text (#388 SEC-IR-MED-1).
+ * Neutralise fingerprint-sentinel literals (#388 SEC-IR-MED-1) and strip the
+ * characters `createFinding` rejects at the argv boundary, so a multi-line page
+ * title in a finding message cannot turn into a VALIDATION failure for the whole
+ * reconcile pass.
  *
- * `issue-reconcile.mjs` applies this to `recommendation` only, inside
- * `reconcileFinding` — a body built HERE and handed to `createFinding` is not
- * sanitised by anything, so a finding `message` echoing page text could forge
- * the authoritative `**Fingerprint:**` line and make the next run's
+ * The neutralisation is the SHARED one from `issue-reconcile.mjs` (#1339 P6): a
+ * body built HERE and handed to `createFinding` is not sanitised by anything
+ * else, so a finding `message` echoing page text could otherwise forge the
+ * authoritative `**Fingerprint:**` line and make the next run's
  * `triageDecision` dedup against the wrong issue.
  *
  * @param {unknown} text
  * @returns {string}
  */
-function sanitizeSentinel(text) {
-  return String(text ?? '').replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
-}
-
-/**
- * Strip the characters `createFinding` rejects at the argv boundary, so a
- * multi-line page title in a finding message cannot turn into a VALIDATION
- * failure for the whole reconcile pass.
- *
- * @param {unknown} text
- * @returns {string}
- */
 function oneLine(text) {
-  return sanitizeSentinel(text).replace(/[\n\r\0]+/g, ' ').trim();
+  return neutralizeFingerprintSentinel(text).replace(/[\n\r\0]+/g, ' ').trim();
 }
 
 /**
@@ -144,7 +139,7 @@ export function buildIssueTitle(finding) {
  * @param {string} [context.rubricHash]
  * @returns {string}
  */
-export function buildIssueBody(finding, { runId, rubricHash } = {}) {
+export function buildUxGrillIssueBody(finding, { runId, rubricHash } = {}) {
   const evidence = finding?.evidence ?? {};
   const evidenceLines = Object.entries(evidence)
     .filter(([, value]) => typeof value === 'string' || Array.isArray(value))
@@ -153,7 +148,7 @@ export function buildIssueBody(finding, { runId, rubricHash } = {}) {
   return [
     oneLine(finding?.message) || `${oneLine(finding?.checkId)} at ${oneLine(finding?.locator)}`,
     '',
-    `**Fingerprint:** \`${oneLine(finding?.fingerprint)}\``,
+    fingerprintSentinelLine(oneLine(finding?.fingerprint)),
     `**Severity:** ${oneLine(finding?.severity)}`,
     `**Check:** ${oneLine(finding?.checkId)}`,
     `**Locator:** \`${oneLine(finding?.locator)}\``,
@@ -168,6 +163,37 @@ export function buildIssueBody(finding, { runId, rubricHash } = {}) {
     .join('\n');
 }
 
+/** One stderr line per process for the deprecated alias below, not one per call. */
+let buildIssueBodyDeprecationWarned = false;
+
+/**
+ * Deprecated alias of {@link buildUxGrillIssueBody}, shipped under this name in
+ * 5.2.0.
+ *
+ * @deprecated since 5.3.0 — use buildUxGrillIssueBody; removed in 6.0.0.
+ * Kept one minor cycle (`.claude/rules/development.md` § Package Lifecycle &
+ * Versioning) because `package.json` carries no `exports` map: every packed
+ * `scripts/lib/` export is a public deep-import, and a consumer calling this
+ * name would otherwise get a runtime TypeError, not a compile error. It
+ * delegates to the LOCAL ux-grill body builder — never to the unrelated
+ * `buildIssueBody(finding, fp)` of `test-runner/issue-reconcile.mjs`, whose
+ * finding shape and second argument differ.
+ *
+ * @param {object} finding - a `makeFinding` record
+ * @param {object} [context] - same as {@link buildUxGrillIssueBody}
+ * @returns {string}
+ */
+export function buildIssueBody(finding, context) {
+  if (!buildIssueBodyDeprecationWarned) {
+    buildIssueBodyDeprecationWarned = true;
+    console.warn(
+      '[deprecated] buildIssueBody from scripts/lib/ux-grill/reconcile.mjs is deprecated since 5.3.0 ' +
+        'and will be removed in 6.0.0 — use buildUxGrillIssueBody instead.',
+    );
+  }
+  return buildUxGrillIssueBody(finding, context);
+}
+
 /**
  * Collect every string in a finding's `evidence` that looks like an absolute
  * host path (POSIX `/…` or Windows `C:\…`).
@@ -296,7 +322,7 @@ export async function reconcileFindings({
     }
 
     const title = buildIssueTitle(finding);
-    const body = buildIssueBody(finding, { runId, rubricHash });
+    const body = buildUxGrillIssueBody(finding, { runId, rubricHash });
     const decision = triageDecision({ fingerprint: finding?.fingerprint, title }, candidates);
 
     if (decision.action === 'ignore') {

package/scripts/lib/validate/check-agents-skills.mjs

@@ -11,16 +11,16 @@
  *      inode, or byte-identical).
  *   B. root `plugin.json` — the agent-plugins.org 1.0.0 manifest; its `version`
  *      must equal `package.json`'s and the two existing plugin manifests'.
- *   C. `.agents/skills/<name>/SKILL.md` — one spec-legal mirror per source
- *      skill, no orphans, agentskills.io field list only, description ≤ 1024.
+ *   C. `.agents/skills/<name>/SKILL.md` — one spec-legal mirror per skill or
+ *      command, no orphans, agentskills.io field list only, description ≤ 1024.
  *
  * INDEPENDENCE (load-bearing). This checker deliberately imports NOTHING from
  * `scripts/generate-agents-skills.mjs` and re-derives the spec field list, the
  * 1024 cap and the alias rule from the spec, not from the generator. A
  * generator-vs-generator check only proves the generator is self-consistent —
  * that is how the Cursor `argument-hint` defect survived. The oracles here are
- * the repository's own filesystem (`skills/`, `CLAUDE.md`, `package.json`) and
- * the published field list.
+ * the repository's own filesystem (`skills/`, `commands/`, `CLAUDE.md`,
+ * `package.json`) and the published field list.
  *
  * Usage: node scripts/lib/validate/check-agents-skills.mjs <plugin-root>
  * Exit codes: 0 — all checks passed · 1 — one or more failures.
@@ -195,6 +195,7 @@ console.log('');
 console.log('--- Check C: .agents/skills/ portable mirror ---');
 {
   const skillsDir = join(pluginRoot, 'skills');
+  const commandsDir = join(pluginRoot, 'commands');
   const mirrorDir = join(pluginRoot, '.agents', 'skills');
 
   const sourceSkills = existsSync(skillsDir) && statSync(skillsDir).isDirectory()
@@ -204,12 +205,21 @@ console.log('--- Check C: .agents/skills/ portable mirror ---');
       .filter((n) => existsSync(join(skillsDir, n, 'SKILL.md')))
       .sort()
     : [];
+  const sources = new Map(sourceSkills.map((name) => [name, `skills/${name}/SKILL.md`]));
+  if (existsSync(commandsDir) && statSync(commandsDir).isDirectory()) {
+    for (const entry of readdirSync(commandsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md') || /^[._]/.test(entry.name)) continue;
+      // Commands own public names when an internal skill has the same name.
+      sources.set(entry.name.slice(0, -3), `commands/${entry.name}`);
+    }
+  }
+  const sourceNames = [...sources.keys()].sort();
 
   if (!existsSync(mirrorDir)) {
-    if (sourceSkills.length === 0) {
-      pass('no skills/ and no .agents/skills/ — nothing to mirror');
+    if (sourceNames.length === 0) {
+      pass('no skill or command sources and no .agents/skills/ — nothing to mirror');
     } else {
-      fail(`.agents/skills/ is missing but ${sourceSkills.length} source skill(s) exist `
+      fail(`.agents/skills/ is missing but ${sourceNames.length} source entry(s) exist `
         + '(remedy: node scripts/generate-agents-skills.mjs)');
     }
   } else {
@@ -218,12 +228,12 @@ console.log('--- Check C: .agents/skills/ portable mirror ---');
       .map((e) => e.name)
       .sort();
 
-    const missing = sourceSkills.filter((n) => !mirrored.includes(n));
-    const orphans = mirrored.filter((n) => !sourceSkills.includes(n));
-    if (missing.length === 0) pass(`every source skill has a mirror (${sourceSkills.length})`);
-    else fail(`${missing.length} source skill(s) have no mirror: ${missing.join(', ')}`);
+    const missing = sourceNames.filter((n) => !mirrored.includes(n));
+    const orphans = mirrored.filter((n) => !sources.has(n));
+    if (missing.length === 0) pass(`every source entry has a mirror (${sourceNames.length})`);
+    else fail(`${missing.length} source entry(s) have no mirror: ${missing.join(', ')}`);
     if (orphans.length === 0) pass('no orphan mirrors');
-    else fail(`${orphans.length} orphan mirror(s) with no source skill: ${orphans.join(', ')}`);
+    else fail(`${orphans.length} orphan mirror(s) with no skill or command source: ${orphans.join(', ')}`);
 
     let fmFail = 0;
     let keyFail = 0;
@@ -303,8 +313,9 @@ console.log('--- Check C: .agents/skills/ portable mirror ---');
         }
       }
 
-      if (!body.includes(`skills/${name}/SKILL.md`)) {
-        fail(`.agents/skills/${name}/SKILL.md body does not cite the canonical skills/${name}/SKILL.md `
+      const canonical = sources.get(name);
+      if (canonical && !body.includes(canonical)) {
+        fail(`.agents/skills/${name}/SKILL.md body does not cite the canonical ${canonical} `
           + '— the mirror is a pointer, and a pointer with no target is dead weight');
         pointerFail += 1;
       }
@@ -314,7 +325,7 @@ console.log('--- Check C: .agents/skills/ portable mirror ---');
     if (keyFail === 0 && mirrored.length > 0) pass('all mirrors use only agentskills.io spec fields');
     if (descFail === 0 && mirrored.length > 0) pass(`all mirror descriptions are non-empty and ≤ ${DESCRIPTION_MAX} chars`);
     if (sizeFail === 0 && mirrored.length > 0) pass(`all mirrors ≤ ${MIRROR_MAX_BYTES} bytes (total ${totalBytes} bytes)`);
-    if (pointerFail === 0 && mirrored.length > 0) pass('all mirrors cite their canonical SKILL.md');
+    if (pointerFail === 0 && mirrored.length > 0) pass('all mirrors cite their canonical source');
   }
 }
 

package/scripts/lib/validate/check-banner-parity.mjs

@@ -46,8 +46,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { HISTORICAL_GUARD_BANNER } from '../historical-guard.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories whose markdown quotes the banner as coordinator-facing prose. */
 const SCAN_DIRS = Object.freeze(['skills', 'commands']);
@@ -365,7 +365,7 @@ export function runCheckBannerParity(pluginRoot) {
   return inspection.toolError ? 2 : 1;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const pluginRoot = process.argv[2];
   if (!pluginRoot) {

package/scripts/lib/validate/check-cursor-adapter.mjs

@@ -6,11 +6,11 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import yaml from 'js-yaml';
 
 import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** agentskills.io caps a skill/command description at 1024 characters. */
 const DESCRIPTION_MAX = 1024;
@@ -177,6 +177,7 @@ function runCli(pluginRoot) {
     } else {
       const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
       fail(`Cursor adapter wrappers are stale${detail ? `: ${detail}` : ''}`);
+      console.log('        Remedy: node scripts/generate-cursor-adapter.mjs');
     }
   }
 
@@ -259,6 +260,6 @@ function runCli(pluginRoot) {
 }
 
 // Direct invocation only — importing this module must not run the CLI.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   runCli(process.argv[2]);
 }

package/scripts/lib/validate/check-dead-bridge.mjs

@@ -22,12 +22,12 @@
 // or process.exit — the isMain guard at the bottom is the only side-effecting
 // path. The Quality wave imports runCheckDeadBridge directly for unit tests.
 
-import { pathToFileURL } from 'node:url';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { DETECTORS } from './dead-bridge-detectors.mjs';
 import * as corpus from './dead-bridge-corpus.mjs';
 import { listRepoFiles } from './repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const DEFAULT_EXTS = ['.mjs', '.md'];
 
@@ -191,7 +191,7 @@ export function runCheckDeadBridge(pluginRoot) {
 
 // CLI entry — only when executed directly, never on import (keeps the exports
 // safe to import from tests without triggering process.exit).
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const pluginRoot = process.argv[2];
   if (!pluginRoot) {

package/scripts/lib/validate/check-doc-cli-commands.mjs

@@ -65,9 +65,9 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { listRepoFiles } from './repo-files.mjs';
 import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories walked for documentation. Mirrors check-vcs-repo-flag.mjs. */
 const SCAN_DIRS = Object.freeze([
@@ -461,7 +461,7 @@ export function runCheckDocCliCommands(pluginRoot) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const args = process.argv.slice(2).filter((arg) => arg !== '--json');
   const root = path.resolve(args[0] || process.cwd());

package/scripts/lib/validate/check-entry-guard.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+/**
+ * check-entry-guard.mjs — census of SYMLINK-FRAGILE ESM entry guards.
+ *
+ * ## The defect class (#1371)
+ *
+ * A module that runs `main()` only when invoked as a CLI compares "the module I
+ * am" against "the script Node was told to run". The two are not the same kind
+ * of path: Node resolves `import.meta.url` to the **realpath**, while
+ * `process.argv[1]` is the path **as typed**. With a symlink anywhere in the
+ * invocation path — a `node_modules/.bin/` shim, a `~/bin` convenience link, a
+ * plugin directory symlinked into `~/.claude/plugins/`, or `/tmp` itself (a
+ * symlink to `/private/tmp` on macOS) — the comparison is false.
+ *
+ * The failure mode is the worst shape a defect can have: `main()` never runs,
+ * nothing is printed, and the process exits 0. Every caller reads that as
+ * success.
+ *
+ * The fix is `isMainModule()` from `scripts/lib/is-main-module.mjs`, which
+ * realpaths BOTH sides. This check is the recurrence guard: it fails the build
+ * when a new hand-written comparison appears.
+ *
+ * ## Oracle
+ *
+ * Over every tracked `.mjs` under `scripts/` + `hooks/` (via `git ls-files`,
+ * so an untracked scratch file is never a finding):
+ *
+ *   1. strip comments (line comments, trailing `//`, and block comments),
+ *   2. split the remainder into statement fragments on `;{}`,
+ *   3. inside each fragment mentioning `process.argv[1]`, apply two oracles:
+ *      a. **comparison form** — take every `===` / `!==` comparison and its two
+ *         operands (bounded to the adjacent `&&` / `||` segment) and FAIL when
+ *         one operand mentions `process.argv[1]` and the other mentions
+ *         `import.meta.url` or `__filename`;
+ *      b. **bare-basename form** — FAIL on `process.argv[1].endsWith('x.mjs')`
+ *         (plus the `?.`, `String(...)` and `(argv[1] || '')` receiver
+ *         variants) against a `.mjs`/`.js`/`.cjs` string literal. This form has
+ *         no comparison operator at all, so oracle (a) never saw it.
+ *   4. In both cases, a fragment wrapping either side in a `realpath*` call is
+ *      the safe idiom and must not be flagged.
+ *
+ * Both oracles are anchored on a SYNTAX shape, which is what keeps prose out of
+ * the census: `scripts/validate-plugin.mjs`,
+ * `scripts/lib/vault-consolidate-fs.mjs`, `hooks/post-edit-import-probe.mjs`
+ * and this file's own header all MENTION a broken idiom inside a comment and
+ * are excluded by step 1 without needing an allowlist entry.
+ * `scripts/lib/baseline-archetypes.mjs` (`await import(process.argv[1])`) is a
+ * deliberate cross-process trick that is neither a comparison nor a basename
+ * test — out of scope for this check.
+ *
+ * `scripts/lib/ecosystem-wizard.mjs` (bare `argv[1].endsWith(...)`) and
+ * `scripts/lib/fetch-baseline.mjs` (a hybrid `===`-plus-`endsWith` guard, which
+ * needed the ALLOWLIST below) were the two hand-written guards this check was
+ * built to catch (#1371); both were fixed to `isMainModule()` in #1378. Oracle
+ * (b) was added afterwards because reverting the FIRST of them was caught by
+ * nothing: the bare form was outside oracle (a) by construction, and neither
+ * file's symlink smoke test reproduced its own regression (a same-named file
+ * behind a symlinked DIRECTORY still ends with the basename). The allowlist is
+ * empty — kept as a frozen mechanism (see its docblock) rather than deleted,
+ * since the next hand-written exception is exactly what would re-populate it.
+ *
+ * `scripts/lib/is-main-module.mjs` itself is excluded: it is the fix, and its
+ * docblock quotes every variant it replaces.
+ *
+ * ## Mode: BLOCKING
+ *
+ * Unlike the WARN-only censuses in validate-plugin (`check-unwired-features`,
+ * `check-learning-provenance`, `check-vcs-repo-flag`), this one blocks. It can
+ * do so honestly because the backlog was drained to zero in the same change
+ * that introduced it — a blocking gate is only dishonest when it is red on
+ * arrival for work nobody intends to do.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
+
+/**
+ * Files whose `process.argv[1]` comparison the oracle flags but which are NOT
+ * the defect class. Every entry carries the reason it is exempt; a stale entry
+ * (one the oracle no longer flags) is itself reported, so this list cannot rot
+ * into a silent suppression.
+ *
+ * Empty since #1378: the one entry this list ever carried
+ * (`scripts/lib/fetch-baseline.mjs`, whose hybrid guard's `endsWith(basename)`
+ * fallback made it non-fragile) was removed when that file was fixed to
+ * `isMainModule()` instead of being kept as a hand-verified exception. The
+ * mechanism is retained rather than deleted: the stale-entry check below only
+ * fires for an entry that is PRESENT and no longer flagged, so an empty object
+ * never trips it, and a future hand-written exception can still be recorded
+ * here.
+ *
+ * @type {Record<string, string>}
+ */
+const ALLOWLIST = {};
+
+/** The one module allowed to contain every broken variant: it documents them. */
+const SELF_EXEMPT = 'scripts/lib/is-main-module.mjs';
+
+/**
+ * Remove comments while preserving character offsets (so line numbers survive).
+ *
+ * A thin wrapper over the shared lexer `maskSource` in `keepLiterals` mode:
+ * string, template and regex literals are skipped INTACT. That is load-bearing
+ * twice over — the V1 idiom \`file://${process.argv[1]}\` carries a `//` that a
+ * naive scanner reads as a line comment, and a regex literal must be recognised
+ * as one (#1383: a `/` the lexer read as a division let the regex body's `/*`
+ * open a block comment that blanked the guard below it — a fail-open miss, for
+ * a quote-bearing regex, a `/[/*]/` character class, and a regex after a keyword
+ * alike).
+ *
+ * @param {string} src module source
+ * @returns {string} same length, comment bytes replaced by spaces
+ */
+export function stripComments(src) {
+  return maskSource(src, { keepLiterals: true });
+}
+
+/**
+ * A `.endsWith('<something>.mjs')` call with a module-basename-shaped literal.
+ * Scanned rather than matched in one shot so the RECEIVER can be judged from the
+ * text preceding each hit — a `.endsWith()` on anything other than
+ * `process.argv[1]` is not this defect class.
+ */
+const ENDS_WITH_LITERAL = /endsWith\(\s*(['"`])([^'"`]*)\1\s*\)/g;
+
+/**
+ * The receiver chain, whitespace-stripped, that makes an `.endsWith()` call a
+ * test on the invocation path. Deliberately unanchored at the START so an outer
+ * wrapper (`String(...)`, `path.basename(...)`) still matches; anchored at the
+ * END so only the call immediately downstream of `process.argv[1]` counts.
+ */
+const ARGV_RECEIVER_TAIL = /process\.argv\[1\](?:\|\|''|\|\|"")?\)*\??\.$/;
+
+/**
+ * Findings for one module body.
+ *
+ * `kind` distinguishes the two oracles: `comparison` is the
+ * `argv[1] === import.meta.url` family, `basename` the bare
+ * `argv[1].endsWith('x.mjs')` family. Both are symlink-fragile; only the remedy
+ * wording differs.
+ *
+ * @param {string} src module source
+ * @returns {Array<{line: number, text: string, kind: 'comparison'|'basename'}>} one per fragile guard
+ */
+export function findFragileGuards(src) {
+  // Template substitutions are rewritten `${x}` → `$(x)` BEFORE the fragment
+  // split: the V1 idiom `import.meta.url === \`file://${process.argv[1]}\`` puts
+  // braces INSIDE the comparison, so splitting on `{}` would tear the statement
+  // in two and the most common variant of the defect class (12 of 50 files at
+  // ca214376) would never be seen. Length is preserved so line numbers survive.
+  const stripped = stripComments(src).replace(/\$\{([^{}]*)\}/g, (_m, inner) => `$(${inner})`);
+  const findings = [];
+  let cursor = 0;
+  for (const fragment of stripped.split(/[;{}]/)) {
+    const fragStart = cursor;
+    cursor += fragment.length + 1;
+    if (!fragment.includes('process.argv[1]')) continue;
+
+    /** @type {(offset: number) => number} 1-based line of an offset in `fragment` */
+    const lineAt = (offset) =>
+      stripped.slice(0, Math.min(fragStart + offset, stripped.length)).split('\n').length;
+
+    if (!/import\.meta\.url|__filename/.test(fragment)) {
+      // Oracle (b): no self-path mention at all, so the comparison oracle below
+      // cannot see this fragment. The bare basename test lives exactly here.
+      if (!/realpath/i.test(fragment)) {
+        ENDS_WITH_LITERAL.lastIndex = 0;
+        let m;
+        while ((m = ENDS_WITH_LITERAL.exec(fragment)) !== null) {
+          if (!/\.(?:mjs|js|cjs)$/.test(m[2])) continue;
+          const receiver = fragment.slice(0, m.index).replace(/\s+/g, '');
+          if (!ARGV_RECEIVER_TAIL.test(receiver)) continue;
+          findings.push({
+            line: lineAt(m.index),
+            text: `process.argv[1]…${m[0]}`,
+            kind: 'basename',
+          });
+          break; // one finding per statement is enough to act on
+        }
+      }
+      continue;
+    }
+
+    const parts = fragment.split(/===|!==/);
+    for (let k = 0; k < parts.length - 1; k++) {
+      const left = parts[k].split(/&&|\|\|/).pop() ?? '';
+      const right = parts[k + 1].split(/&&|\|\|/)[0] ?? '';
+      const mentionsArgv = /process\.argv\[1\]/.test(left) || /process\.argv\[1\]/.test(right);
+      const mentionsSelf =
+        /import\.meta\.url|__filename/.test(left) || /import\.meta\.url|__filename/.test(right);
+      if (!mentionsArgv || !mentionsSelf) continue;
+      if (/realpath/i.test(left) || /realpath/i.test(right)) continue; // the safe idiom
+      const line = lineAt(parts.slice(0, k + 1).join('===').length || 0);
+      findings.push({
+        line,
+        text: `${left.trim()} === ${right.trim()}`.replace(/\s+/g, ' '),
+        kind: 'comparison',
+      });
+      break; // one finding per statement is enough to act on
+    }
+  }
+  return findings;
+}
+
+/**
+ * Tracked `.mjs` files under `scripts/` and `hooks/`.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @returns {string[]} repo-relative POSIX paths
+ */
+function trackedModules(repoRoot) {
+  // Pathspecs are DIRECTORIES, not `scripts/**/*.mjs`: git's wildmatch requires
+  // `**` to consume at least one path component, so a `scripts/**/*.mjs` spec
+  // silently drops every top-level `scripts/*.mjs` AND all of `hooks/*.mjs` —
+  // measured 2026-09-16: 61 files matched vs 176 actually tracked. The extension
+  // filter therefore lives here, where it cannot be wrong about that.
+  //
+  // Re-measured 2026-09-17 (the 61/176 pair no longer reproduces at any scope I
+  // could reconstruct, so it is kept as-dated rather than edited):
+  // `git ls-files -- 'scripts/**/*.mjs' 'hooks/**/*.mjs' | wc -l` → 422 against
+  // `git ls-files -- scripts hooks | grep -c '\.mjs$'` → 508. Direction of the
+  // trap is unchanged; only the magnitude moved.
+  const out = execFileSync('git', ['ls-files', '--', 'scripts', 'hooks'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return out
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.endsWith('.mjs'));
+}
+
+/**
+ * Run the census.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @returns {Promise<number>} 0 clean · 1 findings · 2 tool error
+ */
+export async function runCheckEntryGuard(repoRoot) {
+  let files;
+  try {
+    files = trackedModules(repoRoot);
+  } catch (err) {
+    console.log(`  FAIL: cannot enumerate tracked modules: ${err.message}`);
+    console.log('');
+    console.log('Results: 0 passed, 1 failed');
+    return 2;
+  }
+
+  let failed = 0;
+  const flagged = new Set();
+  for (const rel of files) {
+    if (rel === SELF_EXEMPT) continue;
+    let body;
+    try {
+      body = readFileSync(path.join(repoRoot, rel), 'utf8');
+    } catch {
+      continue; // deleted between ls-files and read — not this check's business
+    }
+    const findings = findFragileGuards(body);
+    if (findings.length === 0) continue;
+    flagged.add(rel);
+    if (rel in ALLOWLIST) continue;
+    for (const f of findings) {
+      const why =
+        f.kind === 'basename'
+          ? 'a basename test answers "was a file with this name run?", never "was THIS ' +
+            'module run" — it is true for any same-named file (a sibling copy, a ' +
+            'vendored duplicate, a fixture) and resolves no path at all, so main() ' +
+            'fires or stays silent for reasons unrelated to identity'
+          : '`import.meta.url` is the realpath, `process.argv[1]` is the path as typed, ' +
+            'so the guard is false under any symlinked invocation and main() silently ' +
+            'never runs (exit 0, no output)';
+      console.log(
+        `  FAIL: ${rel}:${f.line} — symlink-fragile entry guard \`${f.text}\`: ${why}. ` +
+          'Use `isMainModule(import.meta.url)` from scripts/lib/is-main-module.mjs',
+      );
+      failed++;
+    }
+  }
+
+  const censused = new Set(files);
+  for (const [rel, reason] of Object.entries(ALLOWLIST)) {
+    if (flagged.has(rel)) continue;
+    // Not present at all (a fixture repo, a fork that deleted the file) is not
+    // rot — only an entry whose file IS censused and no longer flagged is.
+    if (!censused.has(rel)) continue;
+    console.log(
+      `  FAIL: ${rel} — stale allowlist entry: the oracle no longer flags this file, ` +
+        `so the exemption (“${reason}”) suppresses nothing. Remove it.`,
+    );
+    failed++;
+  }
+
+  if (failed === 0) {
+    console.log(
+      `  PASS: censused ${files.length} tracked module(s) under scripts/ + hooks/ — ` +
+        `0 symlink-fragile entry guard(s), ${Object.keys(ALLOWLIST).length} allowlisted`,
+    );
+  }
+  console.log('');
+  console.log(`Results: ${failed === 0 ? 1 : 0} passed, ${failed} failed`);
+  return failed === 0 ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const usage =
+    'Usage: check-entry-guard.mjs [<repo-root>]\n' +
+    'Exit: 0 clean · 1 symlink-fragile entry guard(s) found · 2 tool error';
+  if (argv.includes('--help')) {
+    console.log(usage);
+    process.exitCode = 0;
+  } else {
+    const positional = argv.filter((a) => !a.startsWith('--'));
+    const unknown = argv.filter((a) => a.startsWith('--') && a !== '--help');
+    if (unknown.length > 0) {
+      console.error(`Unknown flag(s): ${unknown.join(', ')}\n${usage}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = await runCheckEntryGuard(path.resolve(positional[0] ?? process.cwd()));
+    }
+  }
+}

package/scripts/lib/validate/check-guard-requires-parity.mjs

@@ -14,8 +14,8 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse } from '@babel/parser';
+import { isMainModule } from '../is-main-module.mjs';
 
 const HOOKS_RELATIVE_DIR = 'hooks';
 const MODULE_RELATIVE_PREFIX = 'scripts/lib';
@@ -1137,7 +1137,7 @@ export function runCheckGuardRequiresParity(pluginRoot) {
   return inspection.toolError ? 2 : 1;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const pluginRoot = process.argv[2];
   if (!pluginRoot) {