session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -12,18 +12,12 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-// The pi projection is IMPORTED, not copied: pi-hook-bridge.mjs is the runtime
-// that actually rewrites `hook_event_name` for every Pi event, so it is the one
-// source of truth for which pi event becomes which Claude event (#953). A local
-// literal here was a second copy of the same 5 pairs — it could drift silently,
-// and the validator would then certify a projection the runtime does not use.
-// Deliberately NOT the same for `cursorEventMap` below: nothing at runtime
-// projects Cursor events (Cursor calls the handlers directly), so the
-// validator's copy is the only witness there. Even if a runtime source existed,
-// reading Check 3's expectation from the artefact it checks would make the
-// check self-certifying — the "undocumented pi-native event" test at
-// tests/scripts/check-hooks-symmetry.test.mjs would become unreachable. Keep
-// cursorEventMap validator-owned; do not "helpfully" collapse it too.
+// The pi and cursor projections are IMPORTED, not copied: the runtime bridges
+// rewrite `hook_event_name` for every native event, so they are the source of
+// truth for which native event becomes which Claude event (#953). A local
+// literal here was a second copy — it could drift silently, and the validator
+// would then certify a projection the runtime does not use.
+import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
 import { PI_TO_CANONICAL_EVENT } from '../pi-hook-bridge.mjs';
 
 const PLUGIN_ROOT = process.argv[2];
@@ -40,7 +34,19 @@ const DOCUMENTED_ASYMMETRIES = {
   // Events from hooks.json/hooks-codex.json that are intentionally absent in hooks-cursor.json
   cursorMissingFromMain: ['SessionStart', 'SessionEnd', 'PostToolUse', 'PostToolUseFailure', 'PostToolBatch', 'Stop', 'SubagentStart', 'SubagentStop', 'CwdChanged', 'PreToolUse'],
   // Events unique to hooks-cursor.json (Cursor IDE-specific)
-  cursorOnly: ['afterFileEdit', 'beforeShellExecution'],
+  cursorOnly: [
+    'afterFileEdit',
+    'afterShellExecution',
+    'beforeShellExecution',
+    'postToolUse',
+    'postToolUseFailure',
+    'preToolUse',
+    'sessionEnd',
+    'sessionStart',
+    'stop',
+    'subagentStart',
+    'subagentStop',
+  ],
   // Claude/Codex events with no Pi-native v1 mapping yet.
   piMissingFromMain: ['PostToolUseFailure', 'PostToolBatch', 'SubagentStart', 'SubagentStop', 'CwdChanged'],
   // Pi-native extension events that map onto Claude/Codex hook events.
@@ -48,23 +54,10 @@ const DOCUMENTED_ASYMMETRIES = {
   // validator checks hooks-pi.json against is the SAME object pi-hook-bridge.mjs
   // applies to live payloads, so the two cannot drift apart.
   piEventMap: PI_TO_CANONICAL_EVENT,
-  // Cursor-IDE-native events projected onto the logical Claude events they
-  // correspond to. WITHOUT this projection Check 6 compared a FOREIGN event
-  // namespace against hooks.json: not one key matched, the per-event loop
-  // `continue`d on every iteration, and hooks-cursor.json reported
-  // "handler sets match hooks.json (documented asymmetries: 0)" while missing
-  // 20 of 22 handlers — a vacuum-true PASS. Check 6's projection guard now
-  // fails closed PER declared event (#946), so dropping a single entry from
-  // this map is caught too, not only the loss of every projection: the first
-  // version tested `sharedEvents.length === 0`, under which removing just
-  // `afterFileEdit` left the run green and merely moved cursor's documented-
-  // asymmetry count from 12 to 8.
-  // afterFileEdit fires AFTER the edit (hooks-cursor.json `note`,
-  // docs/cursor-setup.md) → it projects onto PostToolUse, never PreToolUse.
-  cursorEventMap: {
-    beforeShellExecution: 'PreToolUse',
-    afterFileEdit: 'PostToolUse',
-  },
+  // Bound to the runtime constant (see the import comment): the projection this
+  // validator checks hooks-cursor.json against is the SAME object
+  // cursor-hook-bridge.mjs applies to live payloads (#919 closed).
+  cursorEventMap: CURSOR_TO_CANONICAL_EVENT,
   // Check 6 (#942): handlers wired on a Claude event but intentionally absent
   // from the SAME logical event on a counterpart manifest. Checks 1-3 compare
   // event KEYS and Check 4 handler EXISTENCE — a handler wired on only one
@@ -159,21 +152,9 @@ const DOCUMENTED_ASYMMETRIES = {
         'pre-bash-issue-budget.mjs',    // #946
       ],
     },
-    // Cursor is NOT wired (#919) and will not be: hooks-cursor.json is a
-    // mapping REFERENCE, not live enforcement. Every handler expects Claude
-    // Code payload shapes (tool_name === 'Bash', tool_input.command) and emits
-    // a Claude PreToolUse envelope; fed a Cursor payload enforce-commands.mjs
-    // short-circuits at gate G1 and writes 0 bytes to stdout AND stderr with
-    // exit 0, so the harness sees no decision and the command runs. Cursor
-    // needs an input/output adapter like scripts/lib/pi-hook-bridge.mjs; none
-    // exists. Operator decision 2026-07-31 — gap registered, not closed:
-    // #919 (Cursor no-op) tracks the adapter, #946 the allowlist-provenance
-    // rule that every entry here names its issue. These entries exist so the
-    // gap is MACHINE-readable (Check 6 counts them) rather than prose-only.
+    // Cursor is wired through scripts/lib/cursor-hook-bridge.mjs (#919 closed).
+    // Remaining gaps are tools Cursor does not expose, not missing adapters.
     cursor: {
-      // #919: beforeShellExecution → PreToolUse. Only enforce-commands.mjs is
-      // mapped at all; the other eight PreToolUse handlers have no Cursor
-      // mapping whatsoever.
       PreToolUse: [
         // pre-task-scope-disjoint (#1020): NOT ported by construction. The hook
         // matches the `Agent` dispatch tool, which this platform does not have —
@@ -191,24 +172,9 @@ const DOCUMENTED_ASYMMETRIES = {
         // tests/hooks/pre-auq-clarity-wiring.test.mjs, which goes red then.
         'pre-auq-clarity.mjs',
         'pre-task-scope-disjoint.mjs',
-        'skill-invocation-telemetry.mjs',    // #919
-        'enforce-scope.mjs',                 // #919
-        'config-protection.mjs',             // #919
-        'pre-bash-destructive-guard.mjs',    // #919
-        'pre-bash-staging-fence.mjs',        // #919
-        'pre-bash-memory-propose-audit.mjs', // #919
-        'pre-bash-sessions-ledger-guard.mjs',// #919 (#958 — needs tool_name === 'Bash')
-        'pre-bash-templates-first.mjs',      // #919
-        'pre-bash-issue-budget.mjs',         // #919
-      ],
-      // #919: afterFileEdit → PostToolUse. Cursor maps enforce-scope.mjs here
-      // (post-hoc warning only); none of Claude's four PostToolUse handlers
-      // has a Cursor mapping.
-      PostToolUse: [
-        'post-edit-validate.mjs',          // #919
-        'post-tooluse-frontend-slop.mjs',  // #919
-        'post-bash-write-verify.mjs',      // #919 (#942 class — needs tool_name === 'Bash')
-        'loop-guard.mjs',                  // #919
+        // skill-invocation-telemetry: Cursor has no Skill tool — the matcher
+        // can never fire. Commands Read skills/*/SKILL.md instead.
+        'skill-invocation-telemetry.mjs',
       ],
     },
   },
@@ -358,7 +324,7 @@ function extractHandlersByEvent(json) {
       const hookList = m.hooks || [];
       for (const h of hookList) {
         const cmd = h.command || h.script || '';
-        const match = cmd.match(/(?:hooks\/|\$\{?CLAUDE_PLUGIN_ROOT\}?\/hooks\/|\$\{?CODEX_PLUGIN_ROOT\}?\/hooks\/|\$\{?PI_PLUGIN_ROOT\}?\/hooks\/)([\w/-]+\.mjs)/);
+        const match = cmd.match(/(?:hooks\/|\$\{?CLAUDE_PLUGIN_ROOT\}?\/hooks\/|\$\{?CODEX_PLUGIN_ROOT\}?\/hooks\/|\$\{?PI_PLUGIN_ROOT\}?\/hooks\/|\$\{?CURSOR_PLUGIN_ROOT\}?\/hooks\/)([\w/-]+\.mjs)/);
         if (match) handlers.add(match[1]);
       }
     }

package/scripts/lib/validate/check-playwright-mcp-canary.mjs

@@ -36,8 +36,9 @@
  *   - Verify non-scanned file extensions (e.g. .yaml) are not processed
  */
 
-import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { listRepoFiles } from './repo-files.mjs';
 
 const pluginRoot = process.argv[2];
 if (!pluginRoot) {
@@ -86,26 +87,6 @@ const SCAN_ROOTS = [
 
 const SCAN_EXTENSIONS = ['.md', '.mjs', '.js', '.ts'];
 
-/**
- * Recursively walk a directory and return all file paths with the allowed extensions.
- * @param {string} dir
- * @returns {string[]}
- */
-function walk(dir) {
-  const results = [];
-  if (!existsSync(dir)) return results;
-  for (const name of readdirSync(dir)) {
-    const full = join(dir, name);
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      results.push(...walk(full));
-    } else if (SCAN_EXTENSIONS.some((ext) => name.endsWith(ext))) {
-      results.push(full);
-    }
-  }
-  return results;
-}
-
 const violations = [];
 
 for (const rel of SCAN_ROOTS) {
@@ -114,7 +95,17 @@ for (const rel of SCAN_ROOTS) {
     pass(`${rel}/ does not exist yet (no scan needed)`);
     continue;
   }
-  const files = walk(absDir);
+  // The index, not the filesystem (#1143). This walk carried NO exclusion set
+  // — not even `node_modules` — while SCAN_EXTENSIONS covers .mjs/.js/.ts, so
+  // a vendored copy of the very package this canary forbids (a gitignored
+  // `skills/playwright-driver/node_modules/@playwright/mcp`) would be read as
+  // repo source and fail a BLOCKING gate on someone else's code.
+  // Honest scope note: unlike the other scanners migrated with it, this one is
+  // NOT exposed to the `.claude/worktrees/` case — measured 2026-08-26, its
+  // three SCAN_ROOTS are fixed deep subdirectories that a worktree cannot land
+  // in, and on-disk vs index counts were identical (2/2, 3/3, 2/2). The
+  // gitignored-vendored-tree case above is the reason it moved.
+  const files = listRepoFiles(pluginRoot, { dirs: [rel], exts: SCAN_EXTENSIONS });
   let fileViolations = 0;
   for (const file of files) {
     const text = readFileSync(file, 'utf8');

package/scripts/lib/validate/check-plugin-monitors.mjs

@@ -13,7 +13,8 @@
  *   7. Each name is unique within the array
  *   8. Array contains an entry named "ecosystem-health"
  *   9. Array contains an entry named "convergence-monitor"
- *  10. The 2 referenced watcher scripts exist on filesystem
+ *  10. Array contains an entry named "wave-transcript-tail" (#1114)
+ *  11. The 3 referenced watcher scripts exist on filesystem
  *
  * Path resolution note:
  *   experimental.monitors value "./monitors/monitors.json" is repo-root-relative
@@ -50,11 +51,16 @@ let failed = 0;
 function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
 function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
 
-const REQUIRED_MONITOR_NAMES = ['ecosystem-health', 'convergence-monitor'];
+const REQUIRED_MONITOR_NAMES = [
+  'ecosystem-health',
+  'convergence-monitor',
+  'wave-transcript-tail',
+];
 const REQUIRED_FIELDS = ['name', 'command', 'description'];
 const REQUIRED_SCRIPTS = [
   'scripts/lib/ecosystem-health.mjs',
   'scripts/lib/convergence-monitor.mjs',
+  'scripts/lib/wave-transcript-tail.mjs',
 ];
 
 // ---------------------------------------------------------------------------
@@ -177,7 +183,7 @@ if (dups.length === 0) {
 }
 
 // ---------------------------------------------------------------------------
-// Checks 8-9: required monitor names present
+// Checks 8-10: required monitor names present
 // ---------------------------------------------------------------------------
 
 for (const required of REQUIRED_MONITOR_NAMES) {
@@ -189,7 +195,7 @@ for (const required of REQUIRED_MONITOR_NAMES) {
 }
 
 // ---------------------------------------------------------------------------
-// Check 10: referenced watcher scripts exist on disk
+// Check 11: referenced watcher scripts exist on disk
 // ---------------------------------------------------------------------------
 
 for (const scriptRel of REQUIRED_SCRIPTS) {

package/scripts/lib/validate/check-test-value-bans.mjs

@@ -122,6 +122,7 @@
 import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { join, isAbsolute, relative } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { isGitToplevel } from './repo-files.mjs';
 
 // ---------------------------------------------------------------------------
 // argv
@@ -184,9 +185,32 @@ const CARVE_OUT_MARKER = '// integrity-anchor:';
 const MAGIC_COMMENT = '// @test-value-bans-allowed';
 const MAGIC_COMMENT_SCAN_LINES = 5;
 
-/** B2 heuristic: how many toContain/toMatch calls make a .md-reading file suspect. */
+/** B2 heuristic: how many toContain/toMatch calls make a .md read suspect. */
 const PROSE_ASSERT_THRESHOLD = 3;
 
+/** A line that reads a `.md` file — the B2 trigger. */
+const MD_READ_CALL = /readFileSync\(/;
+const MD_READ_TARGET = /\.md\b/;
+
+/** A prose assertion — the B2 population. */
+const PROSE_ASSERT = /\.(?:toContain|toMatch)\(/g;
+
+/**
+ * Count prose assertions in `lines[from, to)`.
+ * @param {string[]} lines
+ * @param {number} from inclusive
+ * @param {number} to exclusive
+ * @returns {number}
+ */
+function countProseAsserts(lines, from, to) {
+  let n = 0;
+  for (let i = from; i < to; i++) {
+    const m = lines[i].match(PROSE_ASSERT);
+    if (m) n += m.length;
+  }
+  return n;
+}
+
 const B1_PATTERNS = [
   {
     name: 'toHaveLength',
@@ -343,6 +367,62 @@ function trackedTestFiles() {
     .filter((rel) => /^tests\/.*\.test\.mjs$/.test(rel));
 }
 
+/**
+ * Line ranges this commit actually ADDS or CHANGES, per repo-relative path,
+ * from `git diff --cached -U0`.
+ *
+ * Why (#1148, HR-101): `--stdin` scopes the scan to staged FILES, not staged
+ * LINES. Touching one line of a 1400-line test file therefore surfaced every
+ * pre-existing finding in it — a warning that fires on work the committer did
+ * not do, which teaches the committer to ignore the warning. The repo-wide
+ * census is not lost by this: the CI job `test-value-bans` runs the scanner
+ * unscoped over `$CI_PROJECT_DIR` (.gitlab-ci.yml), so an old prose pin is
+ * still reported there — just not at the moment someone edits a neighbouring
+ * line.
+ *
+ * Returns `null` when there is no index to consult (not a git top level, git
+ * absent, command failed). A null gate is INERT, never empty: failing open is
+ * the only safe direction for an advisory that must not invent silence.
+ *
+ * @returns {Map<string, Array<[number, number]>> | null}
+ */
+function stagedLineRanges() {
+  if (!isGitToplevel(repoRoot)) return null;
+  let out;
+  try {
+    out = execFileSync('git', ['diff', '--cached', '-U0', '--no-color'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+  /** @type {Map<string, Array<[number, number]>>} */
+  const ranges = new Map();
+  /** @type {string | null} */
+  let current = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      // The POST-image path: a rename stages under its new name, and a
+      // deletion stages as /dev/null (no post-image lines to judge).
+      const target = line.slice(4).trim();
+      current = target === '/dev/null' ? null : target.replace(/^b\//, '').replace(/\\/g, '/');
+      if (current && !ranges.has(current)) ranges.set(current, []);
+      continue;
+    }
+    if (!current || !line.startsWith('@@')) continue;
+    const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!m) continue;
+    const start = Number(m[1]);
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    if (count === 0) continue; // pure deletion — no post-image line exists
+    ranges.get(current).push([start, start + count - 1]);
+  }
+  return ranges;
+}
+
 /** Newline-separated paths from stdin (staged-only mode). */
 function stdinFiles() {
   let raw;
@@ -641,18 +721,44 @@ function scanContent(relPath, content, denyHooks = new Set()) {
   });
 
   // --- B2: suspected prose pin -------------------------------------------
-  const mdReadLine = lines.findIndex((l) => /readFileSync\(/.test(l) && /\.md\b/.test(l));
-  if (mdReadLine !== -1) {
-    const proseAsserts = (content.match(/\.(?:toContain|toMatch)\(/g) ?? []).length;
-    if (proseAsserts >= PROSE_ASSERT_THRESHOLD) {
+  // ONE finding per .md read, counted over the population that read can reach
+  // (#1148). v1 reported the line of the FIRST .md read beside a WHOLE-FILE
+  // assert count — two different populations with no causal relation, so the
+  // reported location was never the location of anything counted.
+  // Live proof: tests/unit/vault-mirror.test.mjs was filed at :1077 on
+  // 2026-08-23 and reported :1415 three days later with the same 52 asserts.
+  // Nothing happened at line 1077; the first .md read simply moved 338 lines.
+  //
+  // A read's population = its enclosing it()/test() block when it has one,
+  // else the whole file — a module-scope read IS visible file-wide, so there
+  // the file is the causally correct scope, not a fallback.
+  // Ceiling (BV-004): testBlocks() segments it()/test() only, so a read at
+  // describe() scope also counts file-wide. That over-includes in the same
+  // direction v1 always did; revisit if a describe-scoped .md read is ever
+  // reported with a count no single test could produce.
+  {
+    const blocks = testBlocks(lines);
+    /** Segments already reported — a block holding two .md reads reports once. */
+    const reportedSegments = new Set();
+    lines.forEach((line, idx) => {
+      if (!MD_READ_CALL.test(line) || !MD_READ_TARGET.test(line)) return;
+      const block = blocks.find((b) => idx >= b.start && idx < b.end);
+      const key = block ? `block:${block.start}` : 'file';
+      if (reportedSegments.has(key)) return;
+      const [from, to] = block ? [block.start, block.end] : [0, lines.length];
+      const proseAsserts = countProseAsserts(lines, from, to);
+      if (proseAsserts < PROSE_ASSERT_THRESHOLD) return;
+      reportedSegments.add(key);
       findings.push({
         file: relPath,
-        line: mdReadLine + 1,
+        line: idx + 1,
         ban: 'B2-prose-pin-suspected',
-        match: `readFileSync on .md + ${proseAsserts} toContain/toMatch asserts`,
+        match: `readFileSync on .md + ${proseAsserts} toContain/toMatch asserts in ${
+          block ? 'this test' : 'this file'
+        }`,
         hint: B2_HINT,
       });
-    }
+    });
   }
 
   // --- B3: bare exit-code allow assertion on a deny-capable hook ----------
@@ -748,23 +854,59 @@ for (const rel of candidates) {
   findings.push(...scanContent(rel, content, denyHooks));
 }
 
+// Under --stdin (the pre-commit path) judge only the lines this commit
+// touches; without it (the CI path) keep the repo-wide census. See
+// stagedLineRanges() for why the two paths differ.
+const stagedScope = flags.has('--stdin') ? stagedLineRanges() : null;
+let suppressed = 0;
+const reported = stagedScope
+  ? findings.filter((f) => {
+      const ranges = stagedScope.get(f.file);
+      const inHunk = Boolean(ranges) && ranges.some(([a, b]) => f.line >= a && f.line <= b);
+      if (!inHunk) suppressed++;
+      return inHunk;
+    })
+  : findings;
+
 const counts = {
-  'B1-exact-count': findings.filter((f) => f.ban === 'B1-exact-count').length,
-  'B2-prose-pin-suspected': findings.filter((f) => f.ban === 'B2-prose-pin-suspected').length,
-  'B3-bare-hook-exit-code': findings.filter((f) => f.ban === 'B3-bare-hook-exit-code').length,
+  'B1-exact-count': reported.filter((f) => f.ban === 'B1-exact-count').length,
+  'B2-prose-pin-suspected': reported.filter((f) => f.ban === 'B2-prose-pin-suspected').length,
+  'B3-bare-hook-exit-code': reported.filter((f) => f.ban === 'B3-bare-hook-exit-code').length,
   'B4-hook-decision-contract-copy': findings.filter(
     (f) => f.ban === 'B4-hook-decision-contract-copy',
   ).length,
-  'B5-date-time-bomb': findings.filter((f) => f.ban === 'B5-date-time-bomb').length,
+  'B5-date-time-bomb': reported.filter((f) => f.ban === 'B5-date-time-bomb').length,
 };
 
 if (jsonMode) {
-  console.log(JSON.stringify({ advisory: true, scanned, counts, findings }, null, 2));
-} else if (findings.length === 0) {
-  if (!quiet) console.log(`check-test-value-bans: 0 findings across ${scanned} test file(s) — advisory`);
+  console.log(
+    JSON.stringify(
+      {
+        advisory: true,
+        scanned,
+        counts,
+        stagedScope: { applied: stagedScope !== null, suppressed },
+        findings: reported,
+      },
+      null,
+      2,
+    ),
+  );
+} else if (reported.length === 0) {
+  if (!quiet) {
+    console.log(`check-test-value-bans: 0 findings across ${scanned} test file(s) — advisory`);
+    // Never suppress silently: an empty result that had findings behind it is
+    // a different fact from an empty result that did not (HR-106).
+    if (stagedScope !== null && suppressed > 0) {
+      console.log(
+        `  (${suppressed} pre-existing finding(s) outside this commit's staged hunks not shown — ` +
+          'the CI job test-value-bans reports the repo-wide census)',
+      );
+    }
+  }
 } else {
-  console.log(`check-test-value-bans: ${findings.length} advisory finding(s) across ${scanned} test file(s)`);
-  for (const f of findings) {
+  console.log(`check-test-value-bans: ${reported.length} advisory finding(s) across ${scanned} test file(s)`);
+  for (const f of reported) {
     console.log(`  ${f.ban}  ${f.file}:${f.line}  ${f.match}`);
   }
   if (counts['B1-exact-count'] > 0) console.log(`  B1 hint: ${B1_HINT}`);
@@ -772,6 +914,12 @@ if (jsonMode) {
   if (counts['B3-bare-hook-exit-code'] > 0) console.log(`  B3 hint: ${B3_HINT}`);
   if (counts['B4-hook-decision-contract-copy'] > 0) console.log(`  B4 hint: ${B4_HINT}`);
   if (counts['B5-date-time-bomb'] > 0) console.log(`  B5 hint: ${B5_HINT}`);
+  if (stagedScope !== null && suppressed > 0) {
+    console.log(
+      `  (${suppressed} pre-existing finding(s) outside this commit's staged hunks not shown — ` +
+        'the CI job test-value-bans reports the repo-wide census)',
+    );
+  }
   console.log('  (advisory — this check never blocks; see .claude/rules/testing.md § Lint-Enforceable Test Bans)');
 }