session-orchestrator 3.22.0 → 3.24.0

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// check-cursor-adapter.mjs — Ensure Cursor-native commands, skills, and hooks stay wired.
+// Usage: check-cursor-adapter.mjs <plugin-root>
+// Exit 0 = all checks passed, 1 = at least one failure.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-cursor-adapter.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+console.log('--- Check 1: generated Cursor command and skill wrappers ---');
+
+const generator = join(pluginRoot, 'scripts', 'generate-cursor-adapter.mjs');
+if (!existsSync(generator)) {
+  fail('scripts/generate-cursor-adapter.mjs exists');
+} else {
+  const result = spawnSync(process.execPath, [generator, '--check'], {
+    cwd: pluginRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status === 0) {
+    pass('.cursor/commands and .cursor/skills are up to date with commands/ and skills/');
+  } else {
+    const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+    fail(`Cursor adapter wrappers are stale${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+console.log('');
+console.log('--- Check 2: .cursor/hooks.json native manifest ---');
+
+const hooksPath = join(pluginRoot, '.cursor', 'hooks.json');
+if (!existsSync(hooksPath)) {
+  fail('.cursor/hooks.json exists');
+} else {
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(readFileSync(hooksPath, 'utf8'));
+    pass('.cursor/hooks.json is valid JSON');
+  } catch (err) {
+    fail(`.cursor/hooks.json is not valid JSON: ${err.message}`);
+    hooksJson = null;
+  }
+
+  if (hooksJson) {
+    if (hooksJson.version === 1) {
+      pass('.cursor/hooks.json version is 1');
+    } else {
+      fail('.cursor/hooks.json version must be 1');
+    }
+
+    const declared = Object.keys(hooksJson.hooks || {});
+    const expected = Object.keys(CURSOR_TO_CANONICAL_EVENT);
+    const missing = expected.filter((event) => !declared.includes(event));
+    const extra = declared.filter((event) => !expected.includes(event));
+    if (missing.length === 0 && extra.length === 0) {
+      pass(`.cursor/hooks.json events match CURSOR_TO_CANONICAL_EVENT (${expected.length})`);
+    } else {
+      if (missing.length > 0) fail(`.cursor/hooks.json missing events: ${missing.join(', ')}`);
+      if (extra.length > 0) fail(`.cursor/hooks.json extra events: ${extra.join(', ')}`);
+    }
+
+    const bridgeRef = 'scripts/lib/cursor-hook-bridge.mjs';
+    const allPointAtBridge = declared.every((event) => {
+      const entries = Array.isArray(hooksJson.hooks[event]) ? hooksJson.hooks[event] : [];
+      return entries.some((entry) => typeof entry.command === 'string' && entry.command.includes(bridgeRef) && entry.command.includes(`--event ${event}`));
+    });
+    if (allPointAtBridge) {
+      pass('.cursor/hooks.json commands invoke cursor-hook-bridge.mjs with --event');
+    } else {
+      fail('.cursor/hooks.json commands must invoke scripts/lib/cursor-hook-bridge.mjs --event <name>');
+    }
+  }
+}
+
+console.log('');
+console.log('--- Check 3: Cursor hook bridge module ---');
+
+const bridgePath = join(pluginRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs');
+if (existsSync(bridgePath)) {
+  pass('scripts/lib/cursor-hook-bridge.mjs exists');
+} else {
+  fail('scripts/lib/cursor-hook-bridge.mjs exists');
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

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

@@ -27,6 +27,7 @@ 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';
 
 const DEFAULT_EXTS = ['.mjs', '.md'];
 
@@ -90,10 +91,31 @@ function walk(absDir, exts) {
  * }}
  */
 export function buildRepoContext(pluginRoot) {
+  /**
+   * Enumerate `absDir` from the git INDEX when it lies inside the plugin
+   * root, falling back to the raw walk otherwise (#1143). The walk cannot see
+   * `.gitignore`, so a worktree created under this repo's own
+   * `.claude/worktrees/` convention — or any vendored/generated tree, since
+   * this walk carries no exclusion set at all — enters the detector corpus as
+   * repository content. A detector then reads a PEER checkout's copy of a
+   * skill or rule file and counts it as an independent bridge.
+   *
+   * The containment guard matters: a corpus entry outside the root has no
+   * index to consult, and an `ls-files` pathspec of `../..` is an error, not
+   * an empty answer.
+   * @param {string} absDir
+   * @param {string[] | null} exts
+   * @returns {string[]}
+   */
+  const listUnder = (absDir, exts) => {
+    const rel = path.relative(pluginRoot, absDir);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return walk(absDir, exts);
+    return listRepoFiles(pluginRoot, { dirs: [rel], exts });
+  };
   return {
     pluginRoot,
-    listMdFiles: (absDir) => walk(absDir, ['.md']),
-    listFiles: (absDir, exts = DEFAULT_EXTS) => walk(absDir, exts),
+    listMdFiles: (absDir) => listUnder(absDir, ['.md']),
+    listFiles: (absDir, exts = DEFAULT_EXTS) => listUnder(absDir, exts),
     readText: (absPath) => readFileSync(absPath, 'utf8'),
     exists: (absPath) => existsSync(absPath),
   };

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

@@ -62,10 +62,12 @@
  * Verified against glab 1.91.0 / gh 2.86.0 (2026-08-15).
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+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';
 
 /** Directories walked for documentation. Mirrors check-vcs-repo-flag.mjs. */
 const SCAN_DIRS = Object.freeze([
@@ -79,12 +81,6 @@ const SCAN_DIRS = Object.freeze([
   'templates',
 ]);
 
-/** Never descend into these. */
-const EXCLUDED_DIRS = Object.freeze(['node_modules', '.git', 'dist', 'build', 'coverage']);
-
-/** Fence languages whose body is shell. Anything else is prose. */
-const SHELL_LANGS = Object.freeze(new Set(['bash', 'sh', 'shell', 'console', 'zsh']));
-
 /** The CLIs this check knows how to interrogate. */
 const BINS = Object.freeze(['gh', 'glab']);
 
@@ -205,44 +201,23 @@ export function extractCandidates(body) {
   const candidates = [];
   /** @type {{line: number, text: string}[]} */
   const shellLines = [];
-  /** @type {{marker: string, length: number, shell: boolean} | null} */
-  let fence = null;
 
-  const lines = body.split('\n');
-  for (let index = 0; index < lines.length; index += 1) {
-    const raw = lines[index];
-    const fenceMatch = raw.match(/^\s*(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/);
-    if (fenceMatch) {
-      const marker = fenceMatch[1][0];
-      const length = fenceMatch[1].length;
-      const lang = fenceMatch[2].toLowerCase();
-      if (fence === null) {
-        fence = { marker, length, shell: SHELL_LANGS.has(lang) };
-        continue;
-      }
-      // A closing fence uses the same char, is at least as long, and has no info string.
-      if (marker === fence.marker && length >= fence.length && lang === '') {
-        fence = null;
-        continue;
-      }
-      // Otherwise it is fence content (a nested fence inside a wider one).
-    }
-
-    if (fence !== null) {
-      if (!fence.shell) continue;
+  forEachLine(body, (raw, { lineNumber, inFence, lang }) => {
+    if (inFence) {
+      if (!SHELL_LANGS.has(lang)) return;
       const stripped = raw.replace(/^\s*[$❯>]\s+/, '');
-      if (/^\s*#/.test(stripped)) continue;
-      shellLines.push({ line: index + 1, text: stripped });
-      continue;
+      if (/^\s*#/.test(stripped)) return;
+      shellLines.push({ line: lineNumber, text: stripped });
+      return;
     }
 
     for (const span of raw.matchAll(/`([^`]+)`/g)) {
       const text = span[1].trim();
       if (/^(?:gh|glab)\s/.test(text)) {
-        candidates.push({ line: index + 1, text, channel: 'inline-span' });
+        candidates.push({ line: lineNumber, text, channel: 'inline-span' });
       }
     }
-  }
+  });
 
   for (const entry of joinContinuations(shellLines)) {
     candidates.push({ line: entry.line, text: entry.text, channel: 'shell-fence' });
@@ -296,28 +271,6 @@ function probeHelp(bin, group, cache) {
   return entry;
 }
 
-/**
- * Recursively collect `.md` files.
- *
- * @param {string} directory
- * @param {string[]} acc
- * @returns {string[]}
- */
-function walk(directory, acc = []) {
-  if (!existsSync(directory)) return acc;
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    if (entry.isSymbolicLink()) continue;
-    if (EXCLUDED_DIRS.includes(entry.name)) continue;
-    const fullPath = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      walk(fullPath, acc);
-      continue;
-    }
-    if (entry.isFile() && path.extname(entry.name) === '.md') acc.push(fullPath);
-  }
-  return acc;
-}
-
 /** @param {string} text @returns {string} */
 function clampSnippet(text) {
   const flat = text.replace(/\s+/g, ' ').trim();
@@ -358,13 +311,20 @@ export function inspectDocCliCommands(pluginRoot) {
   /** @type {string[]} */
   let files;
   try {
-    files = SCAN_DIRS.flatMap((dir) => walk(path.join(pluginRoot, dir)));
-    for (const entry of readdirSync(pluginRoot, { withFileTypes: true })) {
-      if (entry.isFile() && path.extname(entry.name) === '.md') {
-        files.push(path.join(pluginRoot, entry.name));
-      }
-    }
-    files.sort();
+    // The index, not the filesystem (#1143). A `readdirSync` walk cannot see
+    // `.gitignore`, so every ignored artefact under a scan root entered this
+    // census as if it were documentation: measured 2026-08-26 on a clean
+    // checkout with NO worktree present, 4 such files —  `.claude/STATE.md`
+    // (per-session mutable state) and three gitignored `docs/specs/*.md`. A
+    // worktree under this repo's own `.claude/worktrees/` convention would
+    // add a complete second copy of every scanned doc on top of that.
+    // One enumeration covers both populations this check has always scanned:
+    // the SCAN_DIRS subtrees, and the repo-root `.md` files at depth 0.
+    const scanDirs = new Set(SCAN_DIRS);
+    files = listRepoFiles(pluginRoot, { exts: ['.md'] }).filter((absolute) => {
+      const segments = path.relative(pluginRoot, absolute).split(path.sep);
+      return segments.length === 1 || scanDirs.has(segments[0]);
+    });
   } catch (error) {
     findings.push({
       kind: 'tool-error',

package/scripts/lib/validate/check-hooks-emit-event-guard.mjs

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+/**
+ * check-hooks-emit-event-guard.mjs — every `emitEvent(...)` call site under
+ * `hooks/**\/*.mjs` must sit lexically inside a `try {} catch {}`, because
+ * `emitEvent()` THROWS `EventValidationError` on a malformed record
+ * (`scripts/lib/events.mjs`, #1177). An unguarded call site turns a
+ * telemetry-shape defect into an uncaught exception inside a
+ * PreToolUse/PostToolUse/Stop/SessionEnd/SessionStart hook — several of
+ * which are deny-capable. Per `.claude/rules/` "moving a guard from
+ * exit-code signalling to stdout-JSON inverts its failure direction": an
+ * aborted hook process writes no `permissionDecision` envelope at all, which
+ * several harnesses read as fail-OPEN (no decision → default allow) rather
+ * than fail-closed. #1183.
+ *
+ * SCOPE. `hooks/` is out of the file-scope this checker's OWNING task may
+ * edit (see the dispatching wave's FILE-SCOPE) — this checker only REPORTS,
+ * it never fixes. Five pre-existing unguarded call sites were census'd at
+ * HEAD 2ccea0f2 (2026-09-02, GitLab #1183) and were BASELINED below; all
+ * five were fixed in the same wave that added the reason/staleness
+ * discipline described next (FX-C, MED-3), so `BASELINE_UNGUARDED` is EMPTY
+ * on arrival. It stays a `Map<key, reason>`, not a bare `Set`, so the NEXT
+ * addition carries a reason from day one — mirroring
+ * `check-unwired-features.mjs`'s `ALLOWLIST` precedent verbatim: "Add an
+ * entry to `ALLOWLIST` keyed by the FULL dotted key path, whose value is a
+ * non-empty reason naming the actual consumer ... Every entry needs a
+ * reason — an empty or whitespace-only one is itself reported
+ * (`allowlist-missing-reason`) ... The list also drains itself: an entry is
+ * reported as `allowlist-stale` both when its key has left every config
+ * surface AND when the key stops triggering a finding (i.e. it finally got
+ * wired), so a fixed key does not leave a permanent exemption behind." Any
+ * unguarded call NOT in the baseline is a genuine regression and FAILs the
+ * build; a baseline entry whose site is now guarded or gone FAILs as
+ * `baseline-stale`; an entry with an empty reason FAILs as
+ * `baseline-missing-reason`. A baselined-but-still-unguarded site (a valid,
+ * reasoned entry that still matches) reports as a WARN, never a FAIL, so
+ * this checker can ship blocking-by-default without going red on arrival.
+ *
+ * METHOD (BV-001.5 substitution). A real AST scope-walk via `@babel/parser`
+ * (`sourceType: 'module'`, `topLevelAwait` + `importMeta` plugins — the same
+ * combination `check-guard-requires-parity.mjs` already parses every hook
+ * with), not brace-depth counting over source text. Brace-depth counting is
+ * fooled by a `{`/`}` inside a string, template literal, regex literal or
+ * comment; a real parser is immune to that class entirely, and
+ * `@babel/parser` is already an installed `dependencies` entry (not just
+ * `devDependencies`) used for the identical domain — reasoning about the
+ * lexical nesting of `hooks/**\/*.mjs`.
+ *
+ * GUARD DEFINITION. An `emitEvent(...)` `CallExpression` counts as guarded
+ * when walking its AST ancestor chain OUTWARD reaches a `TryStatement` —
+ * entered via its `.block` property specifically (not `.handler` /
+ * `.finalizer`: sitting INSIDE a catch or finally block is not "guarded by"
+ * that try) AND carrying a non-null `.handler` (an actual `catch` clause — a
+ * bare `try {} finally {}` does not swallow the throw, so it doesn't count
+ * either) — BEFORE crossing a function boundary (`FunctionDeclaration`,
+ * `FunctionExpression`, `ArrowFunctionExpression`, `ObjectMethod`,
+ * `ClassMethod`, `ClassPrivateMethod`). Crossing a function boundary first
+ * means the call can only be guarded by ITS OWN function's try, never by an
+ * outer function's — this is what makes the textbook false-negative case
+ * (`await helper()` inside an outer `try`, where `helper()` itself calls
+ * `emitEvent()` unguarded) correctly report unguarded rather than a false
+ * negative from naive text-proximity matching.
+ *
+ * NAMED CEILING (BV-004): a hook file that fails to parse under the plugin
+ * set above is reported as a tool-error FAIL for that file — never silently
+ * skipped, because a parse failure hiding a finding is worse than a loud
+ * one. REVISIT if `hooks/` ever needs syntax outside `topLevelAwait` +
+ * `importMeta` (e.g. decorators) — this repo's own ESLint config would need
+ * the same addition first, so the two drift together, not silently.
+ *
+ * Usage: check-hooks-emit-event-guard.mjs <repo-root>
+ * Output: `  PASS: …` / `  WARN: …` / `  FAIL: …` lines (two leading
+ * spaces), then `Results: N passed, M failed`. Exit 0 = clean (WARNs do not
+ * fail the build), 1 = at least one NEW (non-baselined) finding, 2 = tool
+ * error.
+ *
+ * Import-safety: importing this module MUST NOT execute anything — the
+ * isMain guard at the bottom is the only side-effecting path.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse } from '@babel/parser';
+import { listRepoFiles } from './repo-files.mjs';
+
+// ---------------------------------------------------------------------------
+// Baseline — Map<key, reason>, keyed on
+// `<repo-relative-file>::<event-type-literal>` rather than a line number:
+// `hooks/` churns under other waves in this repo's normal operation, and a
+// line-number key would silently stop matching (or worse, mismatch a
+// DIFFERENT call) on any unrelated edit above a baselined site. A static
+// string-literal first argument (as every real emitEvent() call in this
+// repo uses) makes the key stable.
+//
+// Empty on arrival (MED-3, FX-C, 2026-09-02): the five sites census'd at
+// HEAD 2ccea0f2 (#1183) were guarded in the same wave that added this Map
+// plus the baseline-stale / baseline-missing-reason detection below. A
+// future addition MUST carry a non-empty reason naming the linked issue —
+// an empty reason fails as `baseline-missing-reason`, and an entry whose
+// site is later guarded (or removed) fails as `baseline-stale` rather than
+// lingering as a silent, permanent WARN exemption.
+// ---------------------------------------------------------------------------
+
+const BASELINE_UNGUARDED = new Map();
+
+const HOOKS_DIR_REL = 'hooks';
+
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'ObjectMethod',
+  'ClassMethod',
+  'ClassPrivateMethod',
+]);
+
+/** AST metadata keys that are never worth descending into (no code nesting). */
+const SKIP_KEYS = new Set([
+  'loc',
+  'start',
+  'end',
+  'extra',
+  'tokens',
+  'comments',
+  'errors',
+  'leadingComments',
+  'trailingComments',
+  'innerComments',
+]);
+
+/**
+ * Parse a source module with the same syntax family used by this repository
+ * for `hooks/**\/*.mjs` (mirrors `check-guard-requires-parity.mjs`).
+ *
+ * @param {string} source
+ * @param {string} filename
+ * @returns {import('@babel/parser').ParseResult<import('@babel/types').File>}
+ */
+function parseModule(source, filename) {
+  return parse(source, {
+    sourceType: 'module',
+    sourceFilename: filename,
+    errorRecovery: false,
+    plugins: ['topLevelAwait', 'importMeta'],
+  });
+}
+
+/**
+ * @param {{node: any, key: string | number}[]} ancestors outer→inner
+ * @returns {boolean}
+ */
+function isGuardedByTry(ancestors) {
+  for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+    const { node, key } = ancestors[i];
+    if (FUNCTION_TYPES.has(node.type)) return false; // own function's scope — stop here
+    if (node.type === 'TryStatement' && key === 'block' && node.handler !== null && node.handler !== undefined) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {any} callNode a CallExpression node
+ * @returns {string | null} the first argument's literal string value, else null
+ */
+function eventTypeLiteral(callNode) {
+  const arg = callNode.arguments?.[0];
+  return arg && arg.type === 'StringLiteral' ? arg.value : null;
+}
+
+/**
+ * Find every `emitEvent(...)` call site in `source` and classify each as
+ * guarded/unguarded per {@link isGuardedByTry}.
+ *
+ * @param {string} source
+ * @param {string} filename repo-relative path, used only for parse error messages
+ * @returns {{line: number, guarded: boolean, eventType: string | null}[]}
+ */
+export function findEmitEventCalls(source, filename) {
+  const ast = parseModule(source, filename);
+  const calls = [];
+
+  /**
+   * @param {any} node
+   * @param {{node: any, key: string | number}[]} ancestors
+   */
+  function visit(node, ancestors) {
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item, ancestors);
+      return;
+    }
+    if (!node || typeof node !== 'object' || typeof node.type !== 'string') return;
+
+    if (
+      node.type === 'CallExpression' &&
+      node.callee?.type === 'Identifier' &&
+      node.callee.name === 'emitEvent'
+    ) {
+      calls.push({
+        line: node.loc?.start?.line ?? 0,
+        guarded: isGuardedByTry(ancestors),
+        eventType: eventTypeLiteral(node),
+      });
+    }
+
+    for (const [key, child] of Object.entries(node)) {
+      if (SKIP_KEYS.has(key)) continue;
+      if (child && typeof child === 'object') {
+        ancestors.push({ node, key });
+        visit(child, ancestors);
+        ancestors.pop();
+      }
+    }
+  }
+
+  visit(ast.program, []);
+  return calls;
+}
+
+/**
+ * @typedef {{kind: 'unguarded', file: string, line: number, eventType: string | null, baselined: boolean}} UnguardedFinding
+ * @typedef {{kind: 'baseline-stale' | 'baseline-missing-reason', key: string, message: string}} BaselineFinding
+ * @typedef {UnguardedFinding | BaselineFinding} Finding
+ */
+
+/**
+ * @param {string} repoRoot
+ * @param {{baseline?: Map<string, string>}} [options] `baseline` defaults to
+ *   the module-level `BASELINE_UNGUARDED` (empty in production); injectable
+ *   so tests can exercise `baseline-stale` / `baseline-missing-reason`
+ *   against a synthetic map without mutating the shipped baseline.
+ * @returns {{findings: Finding[], parseErrors: {file: string, message: string}[]}}
+ */
+export function scanHooksEmitEventGuard(repoRoot, { baseline = BASELINE_UNGUARDED } = {}) {
+  const files = listRepoFiles(repoRoot, { dirs: [HOOKS_DIR_REL], exts: ['mjs'] });
+  /** @type {Finding[]} */
+  const findings = [];
+  /** @type {{file: string, message: string}[]} */
+  const parseErrors = [];
+  /** @type {Set<string>} baseline keys that matched a real unguarded call site this scan */
+  const flagged = new Set();
+
+  for (const absFile of files) {
+    const rel = path.relative(repoRoot, absFile).split(path.sep).join('/');
+    let source;
+    try {
+      source = readFileSync(absFile, 'utf8');
+    } catch (err) {
+      parseErrors.push({ file: rel, message: `unreadable: ${err?.message ?? String(err)}` });
+      continue;
+    }
+    if (!source.includes('emitEvent(')) continue; // cheap textual pre-filter
+
+    let calls;
+    try {
+      calls = findEmitEventCalls(source, rel);
+    } catch (err) {
+      parseErrors.push({ file: rel, message: err?.message ?? String(err) });
+      continue;
+    }
+
+    for (const call of calls) {
+      if (call.guarded) continue;
+      const key = `${rel}::${call.eventType ?? `L${call.line}`}`;
+      const isBaselined = baseline.has(key);
+      if (isBaselined) {
+        flagged.add(key);
+        const reason = baseline.get(key);
+        if (String(reason ?? '').trim() === '') {
+          findings.push({
+            kind: 'baseline-missing-reason',
+            key,
+            message: 'baseline entry has no reason — name the linked issue or remove the entry',
+          });
+        }
+      }
+      findings.push({
+        kind: 'unguarded',
+        file: rel,
+        line: call.line,
+        eventType: call.eventType,
+        baselined: isBaselined,
+      });
+    }
+  }
+
+  // Mirrors check-unwired-features.mjs's ALLOWLIST drain (see the header
+  // quote above): a baseline entry that no longer matches ANY unguarded call
+  // site this scan found — because the site is now guarded, or gone
+  // entirely — is stale and must be removed, not left as a permanent
+  // exemption.
+  for (const key of baseline.keys()) {
+    if (flagged.has(key)) continue;
+    findings.push({
+      kind: 'baseline-stale',
+      key,
+      message: 'baseline entry no longer matches an unguarded call site (guarded or removed) — remove the entry',
+    });
+  }
+
+  return { findings, parseErrors };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the check against a repo root, printing the validate-plugin line
+ * vocabulary.
+ *
+ * @param {string} repoRoot
+ * @param {{baseline?: Map<string, string>}} [options] forwarded to
+ *   {@link scanHooksEmitEventGuard} — see its JSDoc for why this is
+ *   injectable (test-only; the CLI entrypoint below never passes it).
+ * @returns {number} 0 = clean (baselined WARNs allowed), 1 = new finding(s), 2 = tool error
+ */
+export function runCheckHooksEmitEventGuard(repoRoot, options) {
+  console.log('--- Check: hooks emitEvent() try/catch guard (#1183) ---');
+
+  const { findings, parseErrors } = scanHooksEmitEventGuard(repoRoot, options);
+
+  if (parseErrors.length > 0) {
+    for (const e of parseErrors) console.log(`  FAIL: ${e.file} — ${e.message}`);
+    console.log('');
+    console.log(`Results: 0 passed, ${parseErrors.length} failed`);
+    return 2;
+  }
+
+  const unguarded = findings.filter((f) => f.kind === 'unguarded');
+  const baselineIssues = findings.filter((f) => f.kind === 'baseline-stale' || f.kind === 'baseline-missing-reason');
+
+  const newUnguarded = unguarded.filter((f) => !f.baselined);
+  const baselinedUnguarded = unguarded.filter((f) => f.baselined);
+
+  if (newUnguarded.length === 0 && baselineIssues.length === 0) {
+    console.log(
+      baselinedUnguarded.length === 0
+        ? '  PASS: every hooks/**/*.mjs emitEvent() call site is try/catch-guarded'
+        : `  PASS: no NEW unguarded emitEvent() call sites (${baselinedUnguarded.length} pre-existing, baselined — see #1183)`,
+    );
+  }
+  for (const f of baselinedUnguarded) {
+    console.log(
+      `  WARN: ${f.file}:${f.line} — emitEvent('${f.eventType ?? '?'}') not inside a try/catch (pre-existing, baselined #1183 — out of this checker's file-scope to fix)`,
+    );
+  }
+  for (const f of newUnguarded) {
+    console.log(
+      `  FAIL: ${f.file}:${f.line} — emitEvent('${f.eventType ?? '?'}') not inside a try/catch — a throw here aborts the hook process`,
+    );
+  }
+  for (const f of baselineIssues) {
+    console.log(`  FAIL: ${f.key} — ${f.message} (${f.kind})`);
+  }
+
+  const failCount = newUnguarded.length + baselineIssues.length;
+  console.log('');
+  console.log(`Results: ${failCount === 0 ? 1 : 0} passed, ${failCount} failed`);
+  return failCount > 0 ? 1 : 0;
+}
+
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  const root = process.argv[2];
+  if (!root) {
+    console.error('Usage: check-hooks-emit-event-guard.mjs <repo-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckHooksEmitEventGuard(path.resolve(root)));
+}