session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/validate/check-rules.mjs

@@ -60,9 +60,9 @@
 //           Order and duplicates are irrelevant (a glob list is matched
 //           any-of), so the comparison is over the sorted unique set.
 //           NOT flagged: `paths:` alone. It is the form the native
-//           documentation prescribes and the form the primary downstream
-//           consumer uses exclusively (projects-baseline: 26 rule files, all
-//           `paths:`, 0 `globs:` — rule-loader.mjs module doc). The
+//           documentation prescribes, and the primary downstream consumer
+//           (projects-baseline) carries `paths:` on every scoped rule —
+//           measured count: docs/baseline.md. The
 //           `globs:`-is-canonical preference for VENDORED rules is a separate,
 //           warn-level concern already owned by
 //           scripts/lib/validate-vendored-rules.mjs (~:289, issue #742) and is
@@ -330,8 +330,10 @@ for (const name of mdFiles.sort()) {
         '("rules without a paths field are loaded unconditionally and apply to all files" — ' +
         'code.claude.com/docs/en/memory § Path-specific rules). `globs:` is the Cursor field name, so this rule ' +
         'is scoped for rule-loader.mjs and Cursor but loads ALWAYS-ON in Claude Code — a silent instruction-budget ' +
-        'failure (#1108). Add a paths: key carrying the same patterns as globs: (keep globs: — it stays the ' +
-        'canonical form for vendored rules, validate-vendored-rules.mjs #742).',
+        'failure (#1108). Add a paths: key carrying the same patterns as globs:. Under .claude/rules/ paths: is ' +
+        'the canonical scope key (docs/rule-authoring.md) — keep globs: alongside it only if this rule is ALSO ' +
+        'vendored out through rules/, where globs: is the vendored form (#742); otherwise paths: alone is enough ' +
+        'and globs: can be dropped.',
     );
   } else if (!parity.ok && parity.kind === 'divergent') {
     fail(

package/scripts/lib/validate/check-skill-links.mjs

@@ -20,7 +20,7 @@
  * citations, not intra-surface markdown links. Different predicate, different blind spot.
  *
  * WHAT IT CHECKS
- *   For every `.md` under the scanned surfaces, every inline link `[text](target)` whose target is
+ *   For every `.md`/`.mdc` under the scanned surfaces, every inline link `[text](target)` whose target is
  *   relative (not http(s):, not mailto:, not `#anchor`, not an absolute path) must exist on disk,
  *   resolved against the LINKING FILE's own directory. A `#fragment` suffix is stripped before the
  *   existence check — anchors are out of scope (no heading index here); the path half is not.
@@ -42,6 +42,7 @@
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, relative, sep } from 'node:path';
+import { isMainModule } from '../is-main-module.mjs';
 
 /**
  * Surfaces whose markdown is instruction, i.e. read and acted on.
@@ -52,8 +53,36 @@ import { join, dirname, resolve, relative, sep } from 'node:path';
  * `-/issues/N` renderer links now carved out by `SKIP_TARGET`, two of them genuinely dangling
  * links to PRDs that had been archived to the private Meta-Vault. Both classes were resolved
  * before the widening, so the widening itself lands at 0 findings.
+ *
+ * `.cursor/rules` joined in the 3ebf0e9d fix-pass, with its yield stated honestly: that surface
+ * ships in the npm tarball and is symlinked into consumer repos by `scripts/cursor-install.mjs`,
+ * and it carried two citations of `commands/{go,close}.md` after those files were folded into
+ * their skills. Measured 2026-09-17: `.cursor/rules/*.mdc` contain ZERO `[text](target)` links
+ * (`grep -rnoE '\[[^]]*\]\([^)]+\)' .cursor/rules/` → no matches), so the widening adds 9 files
+ * and 0 checked links today and would NOT by itself have caught that defect — those citations are
+ * INLINE-CODE (`` `commands/go.md` ``), which this checker deliberately skips (see DELIBERATE
+ * NON-CHECKS). It is a forward guard for the day a real link is authored there, not the catcher
+ * for the backticked-citation class.
+ *
+ * That last clause read "and that class has no gate in this repo" until #1384 P3, when it stopped
+ * being true: `check-skill-script-paths.mjs` — which DOES judge complete inline-code spans against
+ * `MARKDOWN_CITATION_RE` — took the same two roots and `.mdc` into its own `SCAN_DIRS`, and is
+ * blocking via `scripts/validate-plugin.mjs`. Measured 2026-09-18: its corpus went 295 → 329 files
+ * and it reported the `commands/{go,close}.md` class of defect (4 blocking findings on first run).
+ * So the division of labour is: LINKS here, backticked CITATIONS there — neither surface is
+ * ungated.
+ */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs', '.cursor/rules']);
+
+/**
+ * File extensions this checker treats as instruction markdown.
+ *
+ * `.mdc` is Cursor's own rule extension and is the ONLY reason `.cursor/rules`
+ * is scannable at all: every file there is `<nnn>-<name>.mdc`, so a `.md`-only
+ * filter would have added the directory to {@link SCAN_DIRS} and enumerated
+ * zero files — a widening that looks live and checks nothing.
  */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs']);
+export const MD_EXTENSIONS = Object.freeze(['.md', '.mdc']);
 
 /** Path segments that end the walk: vendored or machine-owned trees, never instruction. */
 export const PRUNE_DIRS = new Set(['node_modules', '.git', 'coverage', 'dist', '.pnpm']);
@@ -108,8 +137,8 @@ function fencedLineNumbers(text) {
  * and the check would report clean on the tree that carries the defect. This repo has the incident
  * on record (`.claude/rules/measurement-discipline.md` § "A `git grep` drift sweep cannot see
  * untracked files": a release sweep passed, then failed after the commit, from the same working
- * tree with no edit in between). The cost of the filesystem walk is that a gitignored `.md` under
- * these four directories would also be checked — there are none, and one would be a finding worth
+ * tree with no edit in between). The cost of the filesystem walk is that a gitignored markdown file
+ * under these directories would also be checked — there are none, and one would be a finding worth
  * seeing anyway.
  *
  * @param {string} repoRoot
@@ -125,7 +154,7 @@ export function listMarkdown(repoRoot, { dirs = SCAN_DIRS } = {}) {
     let entries;
     try { entries = readdirSync(abs, { recursive: true, withFileTypes: true }); } catch { continue; }
     for (const e of entries) {
-      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      if (!e.isFile() || !MD_EXTENSIONS.some((ext) => e.name.endsWith(ext))) continue;
       // parentPath is absolute; make the record repo-relative with POSIX separators.
       const rel = relative(repoRoot, join(e.parentPath ?? abs, e.name));
       const posix = sep === '/' ? rel : rel.split(sep).join('/');
@@ -190,4 +219,4 @@ function main() {
   process.stdout.write(`  PASS: ${checked} relative link(s) in ${files} markdown file(s) resolve\n`);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main();
+if (isMainModule(import.meta.url)) main();

package/scripts/lib/validate/check-skill-script-paths.mjs

@@ -11,6 +11,16 @@
  * #1241 adds blocking repo-rooted `.md` paths quoted as complete inline-code
  * spans, with the same annotations and fence handling. Scan roots stay fixed.
  *
+ * ## The runtime-artefact carve-out needs BOTH halves
+ *
+ * A missing citation is excused as a runtime artefact only when it sits under
+ * a harness STATE root ({@link RUNTIME_STATE_PREFIXES}) *and* git ignores it.
+ * The git half alone is not the claim it looks like: `.gitignore` also
+ * declines to track real local documents (`docs/specs/`, `docs/_private/`) and
+ * build output (`coverage/`, `node_modules/`), so "git ignores it" would have
+ * silenced a typo in a `docs/specs/…` citation forever — in the very check
+ * whose subject is "ships in the tarball, target missing".
+ *
  * ## Why
  *
  * Prose is not executed. A skill body that tells the coordinator to run
@@ -98,14 +108,60 @@
  * @module scripts/lib/validate/check-skill-script-paths
  */
 
+import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
-/** Documentation roots whose prose is treated as a claim about the repo. */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs']);
+/**
+ * Documentation roots whose prose is treated as a claim about the repo.
+ *
+ * `.claude/rules` and `.cursor/rules` joined in #1384 P3. Both are instruction
+ * corpora loaded by every session, and both cite repo paths in backticks with
+ * exactly the grammar {@link MARKDOWN_CITATION_RE} already judges — but until
+ * this widening neither had a gate. The real incident:
+ * `.cursor/rules/010-session-workflow.mdc` kept citing `commands/go.md` and
+ * `commands/close.md` after `3ebf0e9d` folded those files into their skills,
+ * and that surface SHIPS (npm tarball, symlinked into consumer repos by
+ * `scripts/cursor-install.mjs`). Same widening, mirrored in
+ * `check-skill-links.mjs` § SCAN_DIRS.
+ *
+ * `rules` and `output-styles` joined in #1384 P3 for the same reason one step
+ * further out: both are in `package.json` `files[]`, so both SHIP to every
+ * consumer, and neither had a gate. The census that motivated it (whole-repo
+ * probe, 2026-09-18 @ 20a4cbff) found 6 dangling citations across them —
+ * `output-styles/wave-summary.md` cited `hooks/on-stop.sh` for a file that has
+ * been `.mjs` for two migrations, and `rules/opt-in-stack/*` cited
+ * consumer-side example paths with no marker.
+ *
+ * `CHANGELOG.md` stays OUT, and root files are not a scan root at all: a
+ * changelog cites the paths a release TOUCHED, so a path deleted afterwards is
+ * still a correct historical statement — 88 such hits, all correct by
+ * construction. Annotating them would be noise on every future entry.
+ */
+export const SCAN_DIRS = Object.freeze([
+  'skills',
+  'commands',
+  'agents',
+  'docs',
+  'rules',
+  'output-styles',
+  '.claude/rules',
+  '.cursor/rules',
+]);
+
+/**
+ * Extensions treated as instruction markdown.
+ *
+ * `.mdc` is Cursor's own rule extension and is the ONLY reason `.cursor/rules`
+ * is scannable at all: every file there is `<nnn>-<name>.mdc`, so a `.md`-only
+ * filter would have added the directory to {@link SCAN_DIRS} and enumerated
+ * zero files — a widening that looks live and checks nothing. Same constant,
+ * same reason, as `check-skill-links.mjs` § MD_EXTENSIONS.
+ */
+export const MD_EXTENSIONS = Object.freeze(['.md', '.mdc']);
 
 /**
  * A cited script path. One regex, one alternation, reused for every
@@ -114,8 +170,35 @@ export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs'])
  * `hooks/**.sh`. `hooks/**.mjs` is deliberately NOT part of this grammar —
  * the `.mjs` half of the citation surface stays exactly `scripts/`, matching
  * every existing annotation and fence-skip test unchanged.
+ *
+ * Ceiling (BV-004, #1390 P2): the match is UNANCHORED on the left, so a path
+ * NESTED under another directory is read from its `scripts/` / `hooks/`
+ * segment onward. `templates/shared/hooks/check-csp-single-source.sh` is judged
+ * as `hooks/check-csp-single-source.sh` — a path nobody cited. That cuts both
+ * ways: a finding names the truncated tail (fail-closed noise), and a nested
+ * path whose tail HAPPENS to exist at the repo root passes although the cited
+ * file is missing (fail-open).
+ *
+ * A lookbehind cannot tell the two readings apart, because the character
+ * before the tail is `/` in both: `templates/shared/hooks/…` is a real
+ * subdirectory, while `$PLUGIN_ROOT/scripts/…`, `${CLAUDE_PLUGIN_ROOT}/…`,
+ * `../../scripts/…` and `…/blob/main/hooks/…` all resolve to the plugin root,
+ * so their tail IS the right repo-rooted path. Only the prefix token's meaning
+ * differs, and the regex cannot evaluate a variable. Measured 2026-09-19 @
+ * 8f6ac022 (prose lines of every SCAN_DIRS file, fences skipped — `forEachLine`
+ * + this regex, the character before each hit): 1505 hits in 351 files, 42
+ * preceded by `/` — 16 variable-rooted, 21 relative, 5 literal, and of those
+ * five exactly ONE is a genuine nested directory (the CSP hook above, in
+ * `rules/opt-in-stack/security-web.md`). A `(?<![\w./}-])` guard would drop 37
+ * correctly-judged citations to fix one.
+ *
+ * Escape hatch until then: the nested citation carries
+ * `<!-- path-check: example -->` (or `planned #<iid>`), which the one live
+ * occurrence already does. Revisit when a second real nested-path citation
+ * appears that the annotation cannot reasonably cover — then the grammar needs
+ * a list of known plugin-root prefixes, not a lookbehind.
  */
-const CITATION_RE = /scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
+const CITATION_RE =/scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
 
 /**
  * A complete inline-code span, including spans delimited by multiple backticks.
@@ -166,6 +249,107 @@ export function isPlaceholderCitation(citedPath) {
   return PLACEHOLDER_FRAGMENTS.some((fragment) => lower.includes(fragment));
 }
 
+/**
+ * The per-harness STATE roots. A missing citation may be excused as a runtime
+ * artefact ONLY from inside one of these — and only when git also ignores it
+ * (see {@link isRuntimeArtifact}).
+ *
+ * Each is a harness's own session-state directory: `.orchestrator/` (this
+ * plugin's ledgers, locks and metrics), plus the four harness mirrors that
+ * carry a per-session `STATE.md` / `wave-scope.json` / `filescopes/` —
+ * `.claude/`, `.codex/`, `.cursor/` (all three gitignored file-by-file in this
+ * repo's `.gitignore`) and `.pi/` (`skills/_shared/platform-tools.md` § Pi;
+ * absent from this checkout, listed so the Pi harness is covered wherever the
+ * plugin is installed).
+ *
+ * Ceiling (BV-004): exactly these five prefixes, and ONLY in conjunction with
+ * the git test. `.gitignore` here also declines to track real, hand-authored
+ * documents that simply do not ship (`docs/specs/`, `docs/_private/`) and
+ * whole build outputs (`coverage/`, `node_modules/`) — a typo in a
+ * `docs/specs/…` citation is a defect this check exists to catch, so those
+ * must keep REPORTING. Revisit when a harness adds a sixth state root, or
+ * when a state root stops being a dot-directory at the repo root.
+ */
+export const RUNTIME_STATE_PREFIXES = Object.freeze([
+  '.orchestrator/',
+  '.claude/',
+  '.codex/',
+  '.cursor/',
+  '.pi/',
+]);
+
+/**
+ * Does `citedPath` live under a harness state root?
+ *
+ * Necessary but NOT sufficient for the runtime-artefact carve-out — the git
+ * test in {@link gitIgnoredPaths} is the second half. `.claude/rules/x.md` is
+ * under a state root and TRACKED, so it still reports.
+ *
+ * @param {string} citedPath repo-relative POSIX path
+ * @returns {boolean}
+ */
+export function isRuntimeStatePath(citedPath) {
+  return RUNTIME_STATE_PREFIXES.some((prefix) => citedPath.startsWith(prefix));
+}
+
+/**
+ * Which of `candidates` git IGNORES — one half of the runtime-artefact test
+ * (the other is {@link isRuntimeStatePath}).
+ *
+ * The rules corpora widened into by #1384 P3 cite paths that never exist in a
+ * checkout and are not supposed to: `.cursor/STATE.md`, `.orchestrator/…`
+ * ledgers, per-session state files. Rather than a hand-kept name list (which
+ * would rot the moment a new ledger is added, and which nothing measures), the
+ * test is MECHANICAL and matches the repo's own definition: a path the
+ * repository declines to track, which does not exist, is by construction
+ * written at runtime — so there is nothing for a citation gate to catch.
+ *
+ * That predicate alone is too wide, which is why the prefix half exists: "git
+ * ignores it" and "it is written at runtime" are not the same claim. Measured
+ * 2026-09-18, `gitIgnoredPaths` matched `docs/specs/foo.md`,
+ * `docs/_private/x.md`, `coverage/report.md` and `node_modules/x/y.mjs` just
+ * as readily as `.orchestrator/metrics/events.jsonl` — real local documents
+ * whose dead citations this check must still report.
+ *
+ * ONE `git check-ignore --stdin` for the whole run, never one per path: the
+ * corpus carries hundreds of citations and a per-path spawn would dominate the
+ * check's runtime.
+ *
+ * Fails OPEN toward REPORTING (the safe direction here): a missing `git`, a
+ * non-git root, or exit 128 yields an empty set, so every absent citation is
+ * still reported and no real defect is suppressed by a tooling failure. Exit 1
+ * means "none of them are ignored" and is NOT an error.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @param {string[]} candidates repo-relative POSIX paths (already known absent)
+ * @returns {Set<string>} the subset git ignores
+ */
+export function gitIgnoredPaths(repoRoot, candidates) {
+  const unique = [...new Set(candidates)].filter((p) => p.length > 0 && !p.includes('\n'));
+  if (unique.length === 0) return new Set();
+  let stdout;
+  try {
+    stdout = execFileSync('git', ['check-ignore', '--stdin'], {
+      cwd: repoRoot,
+      input: `${unique.join('\n')}\n`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 8 * 1024 * 1024,
+    });
+  } catch (error) {
+    // Exit 1 = nothing matched, and git still wrote (empty) stdout. Anything
+    // else (128, ENOENT, non-git root) leaves `stdout` undefined → empty set.
+    if (error?.status !== 1) return new Set();
+    stdout = typeof error.stdout === 'string' ? error.stdout : '';
+  }
+  return new Set(
+    String(stdout)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean),
+  );
+}
+
 /** The annotation marker, in any of its three classes. */
 const ANNOTATION_RE = /<!--\s*path-check:\s*([^>]*?)\s*-->/;
 
@@ -274,10 +458,20 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
     existing: 0,
     annotated: 0,
     placeholders: 0,
+    runtimeArtifacts: 0,
     findings: 0,
     warnings: 0,
   };
 
+  /**
+   * Citations that are absent AND unannotated — judged only after the corpus
+   * loop, when the single `git check-ignore` call can separate a dead
+   * reference from a path written at runtime.
+   *
+   * @type {{file: string, citation: {line: number, path: string}}[]}
+   */
+  const pending = [];
+
   /** @type {string[]} */
   let files;
   try {
@@ -290,7 +484,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
     // honours `.gitignore`, so the #1143 exposure a bare `readdirSync` walk
     // would reintroduce (a worktree under `.claude/worktrees/`, gitignored
     // `docs/specs/*.md`) stays closed — see that module's header.
-    files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs, exts: ['.md'] });
+    files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs, exts: MD_EXTENSIONS });
   } catch (error) {
     findings.push({
       kind: 'tool-error',
@@ -389,30 +583,48 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
       }
       if (marker && !marker.ok) continue; // already reported as bad-annotation
 
-      // `.mjs` and `.md` are blocking.
-      // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
-      const isSh = path.extname(citation.path) === '.sh';
-      const severity = isSh && !strictSh ? 'warn' : 'fail';
-      if (severity === 'warn') summary.warnings += 1;
-      findings.push({
-        kind: 'missing-path',
-        file: relative,
-        line: citation.line,
-        path: citation.path,
-        annotation: null,
-        message:
-          (isSh
-            ? severity === 'warn'
-              ? `\`${citation.path}\` does not exist (advisory — .sh citations do not block ` +
-                'validate-plugin until re-run with --strict-sh; see #1187) — '
-              : `\`${citation.path}\` does not exist (--strict-sh) — `
-            : `\`${citation.path}\` does not exist — `) +
-          'create it, fix the path, or annotate the citation with ' +
-          '`<!-- path-check: planned #<iid> | historical | example -->` on this line or the ' +
-          'line directly above',
-        severity,
-      });
+      // Deferred, not reported yet: the runtime-artefact test below needs ONE
+      // `git check-ignore` for the whole corpus, not one per citation.
+      pending.push({ file: relative, citation });
+    }
+  }
+
+  // BOTH halves, never one: under a harness state root AND untracked by git.
+  // Only state-root candidates are even offered to git, so the subprocess
+  // shrinks to the paths that could possibly qualify.
+  const ignored = gitIgnoredPaths(
+    pluginRoot,
+    pending.map((p) => p.citation.path).filter(isRuntimeStatePath),
+  );
+
+  for (const { file: relative, citation } of pending) {
+    if (isRuntimeStatePath(citation.path) && ignored.has(citation.path)) {
+      summary.runtimeArtifacts += 1;
+      continue;
     }
+    // `.mjs` and `.md` are blocking.
+    // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
+    const isSh = path.extname(citation.path) === '.sh';
+    const severity = isSh && !strictSh ? 'warn' : 'fail';
+    if (severity === 'warn') summary.warnings += 1;
+    findings.push({
+      kind: 'missing-path',
+      file: relative,
+      line: citation.line,
+      path: citation.path,
+      annotation: null,
+      message:
+        (isSh
+          ? severity === 'warn'
+            ? `\`${citation.path}\` does not exist (advisory — .sh citations do not block ` +
+              'validate-plugin until re-run with --strict-sh; see #1187) — '
+            : `\`${citation.path}\` does not exist (--strict-sh) — `
+          : `\`${citation.path}\` does not exist — `) +
+        'create it, fix the path, or annotate the citation with ' +
+        '`<!-- path-check: planned #<iid> | historical | example -->` on this line or the ' +
+        'line directly above',
+      severity,
+    });
   }
 
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
@@ -461,7 +673,7 @@ export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {})
   return inspection.ok ? 0 : 1;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const strictSh = process.argv.includes('--strict-sh');
   const args = process.argv.slice(2).filter((arg) => arg !== '--json' && arg !== '--strict-sh');

package/scripts/lib/validate/check-test-git-config-target.mjs

@@ -110,7 +110,8 @@
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 /** Only this directory is scanned — a mutation in `scripts/` is production intent. */
 const SCAN_DIR = 'tests';
@@ -487,43 +488,24 @@ export function insideStringLiteral(body, index) {
  * "no cwd" measured as a cwd. `inCommentLine` cannot serve here: it answers a
  * question about a whole LINE, while this one runs inside a call expression.
  *
+ * Delegates to the shared lexer {@link maskSource} in `keepLiterals` mode
+ * (#1388). The hand-rolled walker this replaced had no REGEX-LITERAL branch,
+ * so a call tail carrying one — measured 2026-09-18:
+ * `wrapperHasCwd(", undefined, { env: /\/*$/.source, cwd: dir }")` — read the
+ * regex's `/*` as a block-comment opener, swallowed the rest of the tail and
+ * returned `false`: a false alarm from this check.
+ *
+ * One behavioural difference the callers must honour: `maskSource` blanks a
+ * comment to SPACES (length-preserving) where this function used to collapse
+ * it to a single space. {@link wrapperHasCwd} judges its second positional
+ * textually against `second !== ''`, so that difference was checked rather
+ * than assumed — see the measurement recorded at that test.
+ *
  * @param {string} text
- * @returns {string} same length semantics, comments blanked to one space
+ * @returns {string} same length, comment bytes blanked to spaces
  */
 export function stripComments(text) {
-  let out = '';
-  /** @type {string|null} */
-  let quote = null;
-  for (let i = 0; i < text.length; i += 1) {
-    const ch = text[i];
-    if (quote !== null) {
-      out += ch;
-      if (ch === '\\') {
-        out += text[i + 1] ?? '';
-        i += 1;
-      } else if (ch === quote) quote = null;
-      continue;
-    }
-    if (ch === "'" || ch === '"' || ch === '`') {
-      quote = ch;
-      out += ch;
-      continue;
-    }
-    if (ch === '/' && text[i + 1] === '*') {
-      const end = text.indexOf('*/', i + 2);
-      i = end === -1 ? text.length : end + 1;
-      out += ' ';
-      continue;
-    }
-    if (ch === '/' && text[i + 1] === '/') {
-      const end = text.indexOf('\n', i);
-      i = end === -1 ? text.length : end - 1;
-      out += ' ';
-      continue;
-    }
-    out += ch;
-  }
-  return out;
+  return maskSource(text, { keepLiterals: true });
 }
 
 /**
@@ -549,6 +531,14 @@ export function wrapperHasCwd(tail) {
   const clean = stripComments(tail);
   const m = /^\s*,\s*/.exec(clean);
   if (m) {
+    // NO `.trim()` here, and that is measured rather than assumed (#1388): the
+    // shared lexer blanks a comment to SPACES where the local stripper used to
+    // delete it, so a comment-only tail LOOKS like it would arrive as truthy
+    // whitespace. It cannot — the `\s*` above is greedy and consumes every
+    // blanked byte, leaving `second === ''`. Measured 2026-09-18 over
+    // `, /* no cwd */`, `, /* a */ /* b */`, `,\n // note\n`,
+    // `, /* x */ undefined`, `, undefined /* y */`: all `false`, `, /* c */ dir`
+    // → `true`. A `.trim()` would be dead code; the case is pinned by a test.
     const second = clean.slice(m[0].length);
     if (second !== '' && !/^(?:undefined|null)\b/.test(second) && !/^,/.test(second)) return true;
   }
@@ -810,7 +800,7 @@ export function runCheckTestGitConfigTarget(pluginRoot) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith('--')));

package/scripts/lib/validate/check-unicode-safety.mjs

@@ -35,7 +35,7 @@
 import { readFileSync, readdirSync, statSync, existsSync, writeFileSync } from 'node:fs';
 import { join, extname, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // File enumeration — git ls-files primary, recursive fs walk fallback.
@@ -535,7 +535,7 @@ export function runCheckUnicodeSafety(pluginRoot, opts = {}) {
 
 // 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 args = process.argv.slice(2);
   const flags = new Set(args.filter((a) => a.startsWith('--')));