session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/test-runner/issue-reconcile.mjs

@@ -22,10 +22,17 @@
  *   triageDecision(finding, candidates)
  *     → {action: 'create'|'update'|'ignore', target?, reason: string, confidence: number}
  *
+ *   buildIssueBody(finding, fp) → string
+ *
+ *   neutralizeFingerprintSentinel(text) → string
+ *   fingerprintSentinelLine(fp) → string
+ *     The one shared sentinel writer + neutraliser, also used by
+ *     ux-grill/reconcile.mjs (#1339 P6).
+ *
  *   ReconcileError
  *
  * Security:
- *   - #388 (SEC-IR-MED-1): sentinel injection hardening — sanitizeRecommendation()
+ *   - #388 (SEC-IR-MED-1): sentinel injection hardening — neutralizeFingerprintSentinel()
  *     strips **Fingerprint:** literals from free-text fields before they are
  *     embedded in the body (before the authoritative sentinel line is appended).
  *   - #389 (SEC-IR-LOW-1): maxBuffer set to 4 MB on every execFile call;
@@ -126,39 +133,64 @@ function validateFinding(finding) {
 // ---------------------------------------------------------------------------
 
 /**
- * Sanitize free-text recommendation fields before embedding in the issue body.
- * Replaces any literal `**Fingerprint:**` with `__Fingerprint__` to prevent
- * a crafted recommendation from spoofing the authoritative fingerprint sentinel
- * line that is appended by buildIssueBody().
+ * Neutralise every `**Fingerprint:**` literal in untrusted text by rewriting it
+ * to `__Fingerprint__`. The ONE copy of this neutralisation: this module's
+ * {@link buildIssueBody} and `ux-grill/reconcile.mjs` both route free text
+ * through it (#1339 P6), so a hardening added here reaches both producers.
  *
- * Context: glab parses issue bodies as Markdown. If `recommendation` contained
+ * Context: glab parses issue bodies as Markdown. If a free-text field contained
  * `**Fingerprint:** <attacker-hash>`, a grep for the fingerprint sentinel in
  * listExistingFindings() would match the spoofed value instead of the real one,
  * bypassing dedup. Replacing the literal prevents the attack without altering
- * the semantic meaning of the recommendation text.
+ * the semantic meaning of the text.
+ *
+ * @param {unknown} text - coerced with `String(text ?? '')`
+ * @returns {string}
+ */
+export function neutralizeFingerprintSentinel(text) {
+  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
+  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
+  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
+  return String(text ?? '').replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+}
+
+/**
+ * The authoritative dedup sentinel line, in the exact shape
+ * {@link extractFingerprintFromBody} reads. The caller passes an
+ * already-trusted value; this function does not sanitise it.
+ *
+ * @param {string} fp - 16-char hex fingerprint
+ * @returns {string}
+ */
+export function fingerprintSentinelLine(fp) {
+  return `**Fingerprint:** \`${fp}\``;
+}
+
+/**
+ * Sanitize free-text recommendation fields before embedding in the issue body
+ * (#388 SEC-IR-MED-1) — {@link neutralizeFingerprintSentinel} for a non-empty
+ * string, anything else returned unchanged (a `null` description is dropped by
+ * buildIssueBody's line filter rather than rendered as an empty line).
  *
  * @param {string|undefined|null} text
  * @returns {string|undefined|null}
  */
 function sanitizeRecommendation(text) {
   if (!text || typeof text !== 'string') return text;
-  // gi flag: case-insensitive match so **fingerprint:** and **FINGERPRINT:** variants
-  // are also neutralized. Sanitizer is intentionally broader than the case-sensitive
-  // extractor regex — this is the correct asymmetry (#388 SEC-IR-MED-1).
-  return text.replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
+  return neutralizeFingerprintSentinel(text);
 }
 
 /**
  * Render untrusted text as the content of ONE inline Markdown code span:
- * sentinel literals neutralised (sanitizeRecommendation), line breaks and NUL
- * folded to a space, backticks turned into `'` — so a page-controlled locator
- * can neither close its code span nor start a new body line.
+ * sentinel literals neutralised, line breaks and NUL folded to a space,
+ * backticks turned into `'` — so a page-controlled locator can neither close
+ * its code span nor start a new body line.
  *
  * @param {unknown} text
  * @returns {string}
  */
 function codeSpanContent(text) {
-  return sanitizeRecommendation(String(text ?? ''))
+  return neutralizeFingerprintSentinel(text)
     .replace(/[\r\n\0]+/g, ' ')
     .replace(/`/g, "'");
 }
@@ -218,7 +250,7 @@ export function buildIssueBody(finding, fp) {
     '',
     safeRecommendation ? `**Recommendation:** ${safeRecommendation}` : null,
     '',
-    `**Fingerprint:** \`${fp}\``,
+    fingerprintSentinelLine(fp),
     `**Severity:** ${finding.severity}`,
     `**Check:** ${finding.checkId}`,
     `**Locator:** \`${codeSpanContent(finding.locator)}\``,

package/scripts/lib/tmux-layout/telemetry-stats.mjs

@@ -2,7 +2,8 @@
  * scripts/lib/tmux-layout/telemetry-stats.mjs
  *
  * Aggregator stub for /tmux-layout telemetry promotion gate (#563).
- * Reads .orchestrator/metrics/events.jsonl and computes:
+ * Reads the events ledger — active file AND every rotated archive (#1407) —
+ * and computes:
  *   - invocation count (total + per layout)
  *   - completion rate (completed / invoked) — promotion gate threshold 80%
  *   - top-K degradation reasons
@@ -13,26 +14,68 @@
  *   - CLI: `node scripts/lib/tmux-layout/telemetry-stats.mjs` (emits JSON to stdout)
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { readEventsWithRotations } from '../events.mjs';
 import { isMainModule } from '../is-main-module.mjs';
 
 const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
+/** Every event this module reports on carries this prefix. */
+const TMUX_EVENT_PREFIX = 'tmux-layout.';
+
+/**
+ * Read the tmux-layout events ACROSS rotation boundaries, together with the
+ * honesty verdict of that read.
+ *
+ * WHY THE ENVELOPE (#1407 acceptance criterion 3): the stats below are an
+ * ALL-TIME rate. Reading only the active file silently redefines "all time" as
+ * "since the last rotation", and a genuinely missing archive would then look
+ * identical to a quiet week. `complete === false` says which of the two it is;
+ * the CLI prints it and never computes over a partial set in silence.
+ *
+ * THREE states (#1423): `complete === null` is a THIRD reading — no source
+ * existed at all, so `invocations: 0` is UNMEASURED, not a measured zero, and
+ * `meetsPromotionGate: false` below rests on nothing. The CLI names that case
+ * separately; folding it into `false` would report a gap nobody found, folding
+ * it into `true` would report a measurement nobody took.
+ *
+ * CEILING (BV-004): `readEventsWithRotations` loads the active file and every
+ * archive fully into memory — up to ~60 MB transient at the default
+ * `max-size-mb: 10` / `max-backups: 5`. Acceptable here because this is a COLD
+ * ops path: a hand-run CLI / promotion-gate check, never a hook and never on
+ * the session path. Revisit if this module gains a hot-path caller or if
+ * `max-size-mb` is raised past ~100.
+ *
+ * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
+ * @returns {{events: Array<object>, complete: boolean|null, gaps: Array<object>,
+ *            notices: Array<object>}}
+ */
+export function readTmuxEventsEnvelope(eventsPath = EVENTS_PATH) {
+  const { events, gaps, complete, notices } = readEventsWithRotations(undefined, {
+    filePath: eventsPath,
+  });
+  return {
+    events: events.filter(
+      (rec) => rec && typeof rec.event === 'string' && rec.event.startsWith(TMUX_EVENT_PREFIX),
+    ),
+    complete,
+    gaps,
+    notices: notices ?? [],
+  };
+}
+
 /**
- * Read events.jsonl and return tmux-layout-related events.
+ * Read the events ledger and return tmux-layout-related events.
+ *
+ * Thin array-returning view of {@link readTmuxEventsEnvelope} — the shape every
+ * existing caller expects. Use the envelope when the completeness of the read
+ * matters to the answer.
  *
  * @param {string} [eventsPath=.orchestrator/metrics/events.jsonl]
  * @returns {Array<object>}  parsed event records (filtered to tmux-layout.* events)
  */
 export function readTmuxEvents(eventsPath = EVENTS_PATH) {
-  if (!existsSync(eventsPath)) return [];
-  const raw = readFileSync(eventsPath, 'utf-8');
-  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
-  return lines
-    .map((l) => {
-      try { return JSON.parse(l); } catch { return null; }
-    })
-    .filter((rec) => rec && typeof rec.event === 'string' && rec.event.startsWith('tmux-layout.'));
+  return readTmuxEventsEnvelope(eventsPath).events;
 }
 
 /**
@@ -95,7 +138,23 @@ export function computeStats(events) {
 
 // CLI entry-point — emit stats as JSON to stdout when run directly
 if (isMainModule(import.meta.url)) {
-  const events = readTmuxEvents();
+  const { events, complete, gaps } = readTmuxEventsEnvelope();
   const stats = computeStats(events);
-  console.log(JSON.stringify(stats, null, 2));
+  if (complete === null) {
+    // NOT MEASURED — a different sentence from "incomplete" (#1423): no active
+    // file and no archive means the zeros below were never observed.
+    console.error(
+      'WARN: no events source was readable (no active file, no archive) — the stats below are UNMEASURED, not zero',
+    );
+  } else if (!complete) {
+    // A gap, never an empty window: diagnostics on stderr (cli-design.md),
+    // the machine-readable verdict in the JSON below.
+    const detail = gaps
+      .map((g) => `${g.kind}:${path.basename(String(g.archived_as ?? 'unknown'))}`)
+      .join(', ');
+    console.error(
+      `WARN: events ledger incomplete — the all-time rate below is computed over a PARTIAL set (${gaps.length} gap(s): ${detail})`,
+    );
+  }
+  console.log(JSON.stringify({ ...stats, ledgerComplete: complete, ledgerGaps: gaps }, null, 2));
 }

package/scripts/lib/user-invocable-skills.mjs

@@ -102,11 +102,31 @@ function normaliseScalar(text) {
  * than inventing a fifth dialect. Because the demotion is the surprising half,
  * each one emits exactly one stderr WARN naming the file.
  *
+ * The same normalisation governs the SIBLING boolean marker
+ * `disable-model-invocation` (the Cursor and Codex adapters read it with this
+ * predicate). The WARN therefore names the key it was asked about rather than a
+ * hard-coded `user-invocable`: measured 2026-09-18, a `disable-model-invocation:
+ * yes` demotion reported `user-invocable: "yes"`, sending the operator to a
+ * line that does not exist in that file.
+ *
+ * The NOUN follows the key too (#1388 P10). Naming the key while hard-coding
+ * "is NOT a slash-command marker" told a `disable-model-invocation: yes` author
+ * that his value failed to be something it never was — a correct key with a
+ * wrong subject reads as a broken diagnostic. The default phrase is unchanged
+ * for `user-invocable`, so the four existing call sites see identical text.
+ *
  * @param {unknown} value the raw frontmatter value
  * @param {string} [file] path named in the WARN when a truthy-looking value is demoted
+ * @param {string} [key] frontmatter key named in the WARN (default `user-invocable`)
  * @returns {boolean}
  */
-export function isUserInvocableValue(value, file) {
+const MARKER_NOUN = Object.freeze({
+  'user-invocable': 'a slash-command marker',
+  'disable-model-invocation': 'a model-invocation opt-out marker',
+});
+const DEFAULT_MARKER_NOUN = 'a boolean marker';
+
+export function isUserInvocableValue(value, file, key = 'user-invocable') {
   if (value === true) return true;
   if (typeof value !== 'string') return false;
   const token = normaliseScalar(value);
@@ -114,8 +134,8 @@ export function isUserInvocableValue(value, file) {
   if (TRUTHY_LOOKALIKE.test(token)) {
     const where = file ? `${file}: ` : '';
     process.stderr.write(
-      `WARN ${where}user-invocable: ${JSON.stringify(value)} is NOT a slash-command marker — `
-        + 'only `true` is (YAML 1.2 reads yes/on/1 as strings). Write `user-invocable: true`.\n',
+      `WARN ${where}${key}: ${JSON.stringify(value)} is NOT ${MARKER_NOUN[key] ?? DEFAULT_MARKER_NOUN} — `
+        + `only \`true\` is (YAML 1.2 reads yes/on/1 as strings). Write \`${key}: true\`.\n`,
     );
   }
   return false;

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-cursor-adapter.mjs

@@ -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');
     }
   }
 

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

@@ -76,6 +76,7 @@ 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
@@ -102,50 +103,20 @@ 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) {
-  const out = src.split('');
-  let i = 0;
-  let mode = 'code';
-  while (i < src.length) {
-    const two = src.slice(i, i + 2);
-    if (mode === 'code') {
-      if (two === '//') mode = 'line';
-      else if (two === '/*') mode = 'block';
-      else if (src[i] === '`' || src[i] === "'" || src[i] === '"') {
-        // Skip OVER the literal to its closing delimiter, leaving the contents
-        // intact. This is load-bearing, not hygiene: the V1 idiom is
-        // \`file://${process.argv[1]}\` and the `//` in `file://` reads as a line
-        // comment to a naive scanner, which blanks the rest of the line and
-        // makes the most common variant of the defect class invisible.
-        const quote = src[i];
-        i++;
-        while (i < src.length && src[i] !== quote) {
-          if (src[i] === '\\') i++;
-          i++;
-        }
-        i++;
-        continue;
-      }
-    }
-    if (mode === 'line') {
-      if (src[i] === '\n') mode = 'code';
-      else out[i] = ' ';
-    } else if (mode === 'block') {
-      if (src[i] !== '\n') out[i] = ' ';
-      if (two === '*/') {
-        out[i] = ' ';
-        out[i + 1] = ' ';
-        i += 2;
-        mode = 'code';
-        continue;
-      }
-    }
-    i++;
-  }
-  return out.join('');
+  return maskSource(src, { keepLiterals: true });
 }
 
 /**
@@ -153,16 +124,8 @@ export function stripComments(src) {
  * 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.
- *
- * The quote characters are spelled `\x27` / `\x22` / `\x60` rather than
- * literally, and that is load-bearing for THIS file specifically: `stripComments`
- * below has no notion of a regex literal, so a bare `'` inside one reads as the
- * start of a string and desynchronises the scanner for the rest of the module —
- * measured 2026-09-17, a literal-quote version of this regex made the census
- * report a line-comment 40 lines further down as a finding. Same rule applies to
- * every regex added to this module.
  */
-const ENDS_WITH_LITERAL = /endsWith\(\s*([\x27\x22\x60])([^\x27\x22\x60]*)\1\s*\)/g;
+const ENDS_WITH_LITERAL = /endsWith\(\s*(['"`])([^'"`]*)\1\s*\)/g;
 
 /**
  * The receiver chain, whitespace-stripped, that makes an `.endsWith()` call a
@@ -170,7 +133,7 @@ const ENDS_WITH_LITERAL = /endsWith\(\s*([\x27\x22\x60])([^\x27\x22\x60]*)\1\s*\
  * 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\](?:\|\|\x27\x27|\|\|\x22\x22)?\)*\??\.$/;
+const ARGV_RECEIVER_TAIL = /process\.argv\[1\](?:\|\|''|\|\|"")?\)*\??\.$/;
 
 /**
  * Findings for one module body.