@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/bench_hook_latency.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env tsx
+/**
+ * bench_hook_latency — standing, published hook-dispatch latency harness.
+ *
+ * road-to-credible-install Phase 1: the 9.8.0 external review measured
+ * ~1.6 s p50 per PreToolUse dispatch (CLI → bash → tsx → per-concern tsx
+ * re-spawn). The precompiled single-process dispatcher (dist/hooks/
+ * dispatch.js) replaces that chain; THIS harness is the re-runnable proof
+ * and the regression net. An external reviewer runs it from a fresh clone:
+ *
+ *     npm ci && npm run build:cli && npm run build:hooks
+ *     ./scripts-run src/scripts/bench_hook_latency            # measure + print
+ *     ./scripts-run src/scripts/bench_hook_latency --gate     # enforce budget
+ *     ./scripts-run src/scripts/bench_hook_latency --update   # record numbers
+ *
+ * Method (pinned so numbers reproduce):
+ *   - N invocations per hook event (default 50, --runs N) of
+ *     `node dist/hooks/dispatch.js --platform claude --event <e>` with a
+ *     synthetic payload on stdin and a throwaway temp workspace as
+ *     --project-dir (concern state lands there, never in the repo).
+ *   - AGENT_CONFIG_REPLAY=1 (feedback-dir writes off — measures dispatch,
+ *     not audit-trail I/O).
+ *   - Wall-clock per invocation around spawnSync; p50/p95 per event.
+ *
+ * Gate semantics (--gate):
+ *   - pre_tool_use p95 must be ≤ budgets_ms.pre_tool_use.p95_ci
+ *   - every event p95 must be ≤ budgets_ms.any_hook_event.p95_ci
+ *   - when docs/hook-latency.json exists, a p95 regression beyond
+ *     regression_gate.max_regression_pct fails.
+ *   Budgets: src/config/hook-latency-budget.json (pre-registered, owner +
+ *   review date — see the Phase-6 budget-ownership lint).
+ *
+ * Exit codes: 0 green · 1 budget/regression exceeded · 2 internal error.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const BUNDLE = path.join(REPO_ROOT, 'dist', 'hooks', 'dispatch.js');
+const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'hook-latency-budget.json');
+const RESULTS_PATH = path.join(REPO_ROOT, 'docs', 'hook-latency.json');
+
+const EVENTS: readonly string[] = [
+    'pre_tool_use',
+    'post_tool_use',
+    'user_prompt_submit',
+    'stop',
+    'session_start',
+    'session_end',
+];
+
+interface EventResult {
+    event: string;
+    runs: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+}
+
+function percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return 0;
+    const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[Math.max(0, idx)] as number;
+}
+
+function syntheticPayload(event: string, workspace: string): string {
+    // Claude-shaped payload; concerns read tool_name/tool_input for
+    // pre/post_tool_use. A plain Read is the common non-matching case —
+    // the fast path consumers pay on every tool call.
+    return JSON.stringify({
+        session_id: 'bench-hook-latency',
+        cwd: workspace,
+        hook_event_name: event,
+        tool_name: 'Read',
+        tool_input: { file_path: path.join(workspace, 'README.md') },
+    });
+}
+
+export function benchEvent(event: string, runs: number, workspace: string): EventResult {
+    const durations: number[] = [];
+    const payload = syntheticPayload(event, workspace);
+    for (let i = 0; i < runs; i += 1) {
+        const started = performance.now();
+        const proc = spawnSync(
+            process.execPath,
+            [
+                BUNDLE,
+                '--platform',
+                'claude',
+                '--event',
+                event,
+                '--project-dir',
+                workspace,
+            ],
+            {
+                input: payload,
+                encoding: 'utf-8',
+                env: { ...process.env, AGENT_CONFIG_REPLAY: '1' },
+                timeout: 60000,
+            },
+        );
+        const elapsed = performance.now() - started;
+        if (proc.error) {
+            throw new Error(`dispatch failed on ${event}: ${proc.error.message}`);
+        }
+        durations.push(elapsed);
+    }
+    durations.sort((a, b) => a - b);
+    return {
+        event,
+        runs,
+        p50_ms: Math.round(percentile(durations, 50)),
+        p95_ms: Math.round(percentile(durations, 95)),
+        max_ms: Math.round(durations[durations.length - 1] as number),
+    };
+}
+
+function loadJson<T>(p: string): T | null {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8')) as T;
+    } catch {
+        return null;
+    }
+}
+
+interface Budget {
+    budgets_ms: {
+        pre_tool_use: { p95_ci: number };
+        any_hook_event: { p95_ci: number };
+    };
+    regression_gate: { max_regression_pct: number };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const gate = argv.includes('--gate');
+    const update = argv.includes('--update');
+    const runsIdx = argv.indexOf('--runs');
+    const runs = runsIdx >= 0 ? Number.parseInt(argv[runsIdx + 1] ?? '50', 10) : 50;
+
+    if (!fs.existsSync(BUNDLE)) {
+        process.stderr.write(
+            `bench_hook_latency: bundle missing at ${BUNDLE} — run \`npm run build:hooks\` first\n`,
+        );
+        return 2;
+    }
+    const budget = loadJson<Budget>(BUDGET_PATH);
+    if (budget === null) {
+        process.stderr.write(`bench_hook_latency: budget file missing/invalid at ${BUDGET_PATH}\n`);
+        return 2;
+    }
+
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-hook-bench-'));
+    const results: EventResult[] = [];
+    try {
+        for (const event of EVENTS) {
+            const r = benchEvent(event, runs, workspace);
+            results.push(r);
+            process.stdout.write(
+                `${event.padEnd(20)} p50 ${String(r.p50_ms).padStart(5)} ms · p95 ${String(r.p95_ms).padStart(5)} ms · max ${String(r.max_ms).padStart(5)} ms (n=${r.runs})\n`,
+            );
+        }
+    } finally {
+        fs.rmSync(workspace, { recursive: true, force: true });
+    }
+
+    let failed = false;
+    const prior = loadJson<{ results: EventResult[] }>(RESULTS_PATH);
+    for (const r of results) {
+        const anyCap = budget.budgets_ms.any_hook_event.p95_ci;
+        const cap = r.event === 'pre_tool_use' ? budget.budgets_ms.pre_tool_use.p95_ci : anyCap;
+        if (gate && r.p95_ms > cap) {
+            process.stderr.write(
+                `❌  ${r.event}: p95 ${r.p95_ms} ms exceeds the pre-registered budget (${cap} ms)\n`,
+            );
+            failed = true;
+        }
+        if (gate && prior !== null) {
+            const prev = prior.results.find((x) => x.event === r.event);
+            if (prev !== undefined && prev.p95_ms > 0) {
+                const regressionPct = ((r.p95_ms - prev.p95_ms) / prev.p95_ms) * 100;
+                if (regressionPct > budget.regression_gate.max_regression_pct) {
+                    process.stderr.write(
+                        `❌  ${r.event}: p95 regressed ${Math.round(regressionPct)}% vs recorded ` +
+                            `${prev.p95_ms} ms (allowed: ${budget.regression_gate.max_regression_pct}%)\n`,
+                    );
+                    failed = true;
+                }
+            }
+        }
+    }
+
+    if (update) {
+        const doc = {
+            _comment:
+                'Recorded hook-dispatch latency (bench_hook_latency --update). Method pinned in src/scripts/bench_hook_latency.ts; budgets in src/config/hook-latency-budget.json. Re-run from a fresh clone to reproduce.',
+            recorded_at: new Date().toISOString(),
+            node: process.version,
+            platform: `${os.platform()}-${os.arch()}`,
+            hardware_note: 'see hook-latency-budget.json hardware_reference — CI numbers are the gated ones',
+            runs_per_event: runs,
+            results,
+        };
+        fs.writeFileSync(RESULTS_PATH, `${JSON.stringify(doc, null, 4)}\n`);
+        process.stdout.write(`recorded → ${path.relative(REPO_ROOT, RESULTS_PATH)}\n`);
+    }
+
+    if (failed) return 1;
+    process.stdout.write(gate ? '✅  hook-latency budget met\n' : 'ℹ️  measurement only (no gate)\n');
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/bench_quality_run.ts

@@ -126,6 +126,116 @@ export function run_golden_judge(
   });
 }
 
+// ── Export mode (--dump-answers): blinded pairs for an external instrument ──
+//
+// Needed because LLM-paired judging on thin-vs-eager is closed-by-diagnosis
+// (`docs/benchmark.md` § Length-neutral judge RERUN). Any admissible re-open
+// needs the raw answer pairs, whether the instrument is deterministic
+// anchor-scoring against `must_include`/`must_not` or a human judge. Export mode
+// makes NO judge calls, so it costs ~half a full judged run (2 arms, 0 judges).
+
+/** Deterministic per-task coin flip — FNV-1a over `seed:taskId`, low bit.
+ * Reproducible blinding without Math.random, so re-running the export yields
+ * the same A/B assignment and a partially-filled verdicts.csv stays valid. */
+export function blind_flip(taskId: string, seed: number): boolean {
+  const s = `${seed}:${taskId}`;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i += 1) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return (h & 1) === 1;
+}
+
+export interface BlindPair {
+  id: string;
+  /** Which arm was presented as ANSWER A. Belongs in _mapping.json ONLY. */
+  a_arm: 'thin' | 'eager';
+  answer_a: string;
+  answer_b: string;
+}
+
+export function build_blind_pair(
+  task: GoldenTask,
+  thinAnswer: string,
+  eagerAnswer: string,
+  seed: number,
+): BlindPair {
+  const thinIsA = blind_flip(task.id, seed);
+  return {
+    id: task.id,
+    a_arm: thinIsA ? 'thin' : 'eager',
+    answer_a: thinIsA ? thinAnswer : eagerAnswer,
+    answer_b: thinIsA ? eagerAnswer : thinAnswer,
+  };
+}
+
+/** Render the operator-facing pair file. MUST NOT leak the arm mapping —
+ * `tests/scripts/bench_quality_run.test.ts` asserts the blinding invariant. */
+export function render_pair_file(task: GoldenTask, pair: BlindPair): string {
+  const lines: string[] = [`# ${task.id}`, '', '## Request', '', task.prompt, '', '## Rubric', '', task.rubric, ''];
+  if (task.must_include.length) lines.push('## Must satisfy', '', ...task.must_include.map((s) => `- ${s}`), '');
+  if (task.must_not.length) lines.push('## Must avoid', '', ...task.must_not.map((s) => `- ${s}`), '');
+  lines.push(
+    '## Judging rules',
+    '',
+    '- Judge ONLY which answer better satisfies the rubric above.',
+    '- IGNORE length and verbosity. A longer answer is NOT a better answer.',
+    '- `tie` is a valid verdict — do not force a winner.',
+    '- Do NOT open `_mapping.json` until every verdict is recorded.',
+    '',
+    '## ANSWER A',
+    '',
+    pair.answer_a,
+    '',
+    '## ANSWER B',
+    '',
+    pair.answer_b,
+    '',
+    '## Verdict',
+    '',
+    `Append to verdicts.csv — one of: \`${task.id},A\` · \`${task.id},B\` · \`${task.id},tie\``,
+    '',
+  );
+  return lines.join('\n');
+}
+
+/** Write the blinded export: one file per task + the withheld mapping + a CSV stub. */
+export function write_export(
+  dir: string,
+  tasks: GoldenTask[],
+  pairs: BlindPair[],
+  meta: { seed: number; model: string; dry_run: boolean },
+): void {
+  fs.mkdirSync(dir, { recursive: true });
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  for (const pair of pairs) {
+    const task = byId.get(pair.id);
+    if (task === undefined) continue;
+    fs.writeFileSync(path.join(dir, `${pair.id}.md`), render_pair_file(task, pair));
+  }
+  fs.writeFileSync(
+    path.join(dir, '_mapping.json'),
+    JSON.stringify(
+      {
+        generated_by: 'bench_quality_run --dump-answers',
+        warning: 'DO NOT READ until every verdict is recorded in verdicts.csv.',
+        seed: meta.seed,
+        answer_model: meta.model,
+        dry_run: meta.dry_run,
+        threshold: DEFAULT_THRESHOLD,
+        mapping: pairs.map((p) => ({ id: p.id, a_arm: p.a_arm })),
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+  const csv = path.join(dir, 'verdicts.csv');
+  if (!fs.existsSync(csv)) {
+    fs.writeFileSync(csv, `task_id,verdict\n${pairs.map((p) => `${p.id},`).join('\n')}\n`);
+  }
+}
+
 // ── Mock model (--dry-run): deterministic, no API ───────────────────────────
 function mock_answer(_ctx: string, task: GoldenTask): string {
   return `Answer to ${task.id}: ${(task.must_include[0] ?? 'addresses the request')}.`;
@@ -137,16 +247,41 @@ interface Args {
   model: string;
   limit: number | null;
   output: string;
+  dumpAnswers: string | null;
+  seed: number;
 }
 
+const DEFAULT_SEED = 20260729;
+
 function parse_args(argv: string[]): Args | number {
-  const a: Args = { dryRun: false, model: 'claude-sonnet-4-5', limit: null, output: OUT };
+  const a: Args = {
+    dryRun: false,
+    model: 'claude-sonnet-4-5',
+    limit: null,
+    output: OUT,
+    dumpAnswers: null,
+    seed: DEFAULT_SEED,
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--dry-run') a.dryRun = true;
     else if (arg === '--model') a.model = String(argv[(i += 1)] ?? a.model);
     else if (arg === '--output') a.output = String(argv[(i += 1)] ?? a.output);
-    else if (arg === '--limit') {
+    else if (arg === '--dump-answers') {
+      const v = argv[(i += 1)];
+      if (v === undefined || v.startsWith('--')) {
+        process.stderr.write('error: --dump-answers requires a directory path\n');
+        return 1;
+      }
+      a.dumpAnswers = v;
+    } else if (arg === '--seed') {
+      const v = Number(argv[(i += 1)]);
+      if (!Number.isInteger(v)) {
+        process.stderr.write('error: --seed must be an integer\n');
+        return 1;
+      }
+      a.seed = v;
+    } else if (arg === '--limit') {
       const v = Number(argv[(i += 1)]);
       if (!Number.isInteger(v) || v < 1) {
         process.stderr.write('error: --limit must be a positive integer\n');
@@ -154,7 +289,13 @@ function parse_args(argv: string[]): Args | number {
       }
       a.limit = v;
     } else if (arg === '-h' || arg === '--help') {
-      process.stdout.write('usage: bench_quality_run [--dry-run] [--model M] [--limit N] [--output PATH]\n');
+      process.stdout.write(
+        'usage: bench_quality_run [--dry-run] [--model M] [--limit N] [--output PATH]\n' +
+          '                        [--dump-answers DIR] [--seed N]\n\n' +
+          '  --dump-answers DIR  export blinded pairs for an external instrument; makes NO\n' +
+          '                      judge calls (~half the cost of a judged run)\n' +
+          `  --seed N            deterministic A/B blinding seed (default ${String(DEFAULT_SEED)})\n`,
+      );
       return 0;
     } else {
       process.stderr.write(`error: unknown argument: ${arg}\n`);
@@ -214,8 +355,31 @@ function main(argv: string[]): number {
       );
     modelLabel = args.model;
     process.stdout.write(
-      `Live run: ${tasks.length} tasks × 2 arms + 2 judge calls each via ${args.model}. This costs API $.\n`,
+      args.dumpAnswers === null
+        ? `Live run: ${tasks.length} tasks × 2 arms + 2 judge calls each via ${args.model}. This costs API $.\n`
+        : `Live export: ${tasks.length} tasks × 2 arms via ${args.model}, NO judge calls. This costs API $.\n`,
+    );
+  }
+
+  // Export mode: generate both arms, blind them, write the pairs, judge nothing.
+  if (args.dumpAnswers !== null) {
+    let pairs: BlindPair[];
+    try {
+      pairs = tasks.map((task) =>
+        build_blind_pair(task, answer(contexts.thin, task), answer(contexts.eager, task), args.seed),
+      );
+    } catch (e) {
+      process.stderr.write(`error: answer generation failed: ${(e as Error).message}\n`);
+      return 1;
+    }
+    const dir = path.resolve(args.dumpAnswers);
+    write_export(dir, tasks, pairs, { seed: args.seed, model: modelLabel, dry_run: args.dryRun });
+    process.stdout.write(
+      `→ wrote ${pairs.length} blinded pairs to ${dir}\n` +
+        `   Arm mapping withheld in _mapping.json — do not open it until verdicts.csv is complete.\n` +
+        `   Judged nothing: LLM-paired judging is closed-by-diagnosis for this question.\n`,
     );
+    return 0;
   }
 
   let results: PairResult[];

package/src/scripts/build_mcp_catalog.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env tsx
+/**
+ * `consumer_tool_catalog.json` generator — Phase 3 of road-to-credible-install
+ * (MCP hygiene: generated truth, honest stubs).
+ *
+ * The catalog used to be hand-maintained: every tool's name / description /
+ * input_schema had to be kept in sync BY HAND across the JSON file AND its
+ * real handler registration in `mcp_server/tools.ts`. This script derives
+ * the JSON from the actual registries instead of a third hand-edited copy:
+ *
+ *   - implemented tools — `ALLOWLIST` in `mcp_server/tools.ts`. Name,
+ *     description, input_schema, and side_effect all come straight off the
+ *     handler registration.
+ *   - stub-only tools    — `STUB_TOOLS` in `mcp_server/tool_catalog_source.ts`.
+ *     Catalog-listed discovery placeholders with no wired handler.
+ *
+ * Every stub entry's description is prefixed with the literal marker
+ * `[stub — implemented on demand] ` so a client can tell a discovery
+ * placeholder from a real tool without cross-checking `implemented_on`.
+ * Every implemented entry additionally carries an `annotations.readOnlyHint`
+ * derived from its `side_effect`.
+ *
+ * CLI contract (same `--write` / `--strict` shape as
+ * `build_discovery_manifest.ts`):
+ *   --write   regenerate and persist the catalog deterministically (tools
+ *             sorted by name, stable key order, 2-space indent).
+ *   --strict  quality gate on the freshly-built content (no duplicate name
+ *             across the two registries, non-empty tool list); when NOT
+ *             combined with --write, ALSO diffs the fresh content against
+ *             the committed file and fails on any drift — the CI gate that
+ *             catches a hand-edit or a registry change nobody regenerated
+ *             the catalog for.
+ *   --quiet   suppress the stdout summary line.
+ * Bare invocation (no flags) prints the freshly-built JSON to stdout,
+ * mirroring `build_discovery_manifest.ts`'s non-write default.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ALLOWLIST, type ToolSideEffect } from './mcp_server/tools.js';
+import { CATALOG_DESCRIPTION, STUB_TOOLS } from './mcp_server/tool_catalog_source.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'build_mcp_catalog';
+
+// src/scripts/build_mcp_catalog.ts → repo root is two dirs up.
+const _DEFAULT_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+interface ModuleConfig {
+    ROOT: string;
+    CATALOG_PATH: string;
+    PACKAGE_JSON: string;
+}
+
+function _deriveConfig(root: string): ModuleConfig {
+    return {
+        ROOT: root,
+        CATALOG_PATH: path.join(root, 'src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json'),
+        PACKAGE_JSON: path.join(root, 'package.json'),
+    };
+}
+
+const _config: ModuleConfig = _deriveConfig(_DEFAULT_ROOT);
+
+/** Test seam — mirrors `build_discovery_manifest.ts`'s `_setConfigForTest`. */
+export function _setConfigForTest(overrides: Partial<ModuleConfig>): void {
+    Object.assign(_config, overrides);
+}
+
+export function _getConfigForTest(): ModuleConfig {
+    return { ..._config };
+}
+
+export const ROOT = (): string => _config.ROOT;
+export const CATALOG_PATH = (): string => _config.CATALOG_PATH;
+
+/** Literal marker every stub-only description starts with. */
+export const STUB_MARKER = '[stub — implemented on demand] ';
+
+interface CatalogEntryOut {
+    name: string;
+    description: string;
+    side_effect: ToolSideEffect;
+    implemented_on: string[];
+    input_schema: Record<string, unknown>;
+    annotations?: { readOnlyHint: boolean };
+}
+
+function _packageName(): string {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(_config.PACKAGE_JSON, 'utf-8')) as { name?: unknown };
+        return typeof pkg.name === 'string' && pkg.name !== '' ? pkg.name : '@event4u/agent-config';
+    } catch {
+        return '@event4u/agent-config';
+    }
+}
+
+/** Mirror Python `str.__lt__` (code-point ordering — matches ASCII tool names). */
+function _cmpStr(a: string, b: string): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Build the deterministic, name-sorted tool-entry list. Throws on a name collision. */
+export function _buildEntries(): CatalogEntryOut[] {
+    const seen = new Set<string>();
+    const entries: CatalogEntryOut[] = [];
+
+    for (const tool of Object.values(ALLOWLIST)) {
+        if (seen.has(tool.name)) {
+            throw new Error(`build_mcp_catalog: duplicate tool name in ALLOWLIST: ${tool.name}`);
+        }
+        seen.add(tool.name);
+        entries.push({
+            name: tool.name,
+            description: tool.description,
+            side_effect: tool.side_effect,
+            implemented_on: ['stdio'],
+            input_schema: tool.input_schema,
+            annotations: { readOnlyHint: tool.side_effect === 'ro' },
+        });
+    }
+
+    for (const stub of STUB_TOOLS) {
+        if (seen.has(stub.name)) {
+            throw new Error(
+                `build_mcp_catalog: '${stub.name}' is registered both in ALLOWLIST ` +
+                    'and STUB_TOOLS — a tool is implemented or a stub, never both.',
+            );
+        }
+        seen.add(stub.name);
+        entries.push({
+            name: stub.name,
+            description: STUB_MARKER + stub.description,
+            side_effect: stub.side_effect,
+            implemented_on: [],
+            input_schema: stub.input_schema,
+        });
+    }
+
+    entries.sort((a, b) => _cmpStr(a.name, b.name));
+    return entries;
+}
+
+/** Build the full catalog document (unserialized). */
+export function _buildCatalog(): Record<string, unknown> {
+    const entries = _buildEntries();
+    if (entries.length === 0) {
+        throw new Error('build_mcp_catalog: computed zero tool entries — refusing an empty catalog');
+    }
+    return {
+        schema_version: 1,
+        description: CATALOG_DESCRIPTION,
+        install_hint_stdio: `npx -y ${_packageName()} mcp-server`,
+        tools: entries,
+    };
+}
+
+/** Deterministic JSON: 2-space indent, trailing newline. Key order = insertion order above. */
+export function _serialize(catalog: Record<string, unknown>): string {
+    return JSON.stringify(catalog, null, 2) + '\n';
+}
+
+/** Freshly-computed catalog file content — the single function both --write and --strict trust. */
+export function _computeFreshContent(): string {
+    return _serialize(_buildCatalog());
+}
+
+function _relativeToRoot(p: string): string {
+    return path.relative(_config.ROOT, p).split(path.sep).join('/');
+}
+
+interface ParsedArgs {
+    write: boolean;
+    strict: boolean;
+    quiet: boolean;
+}
+
+function _argError(msg: string): never {
+    process.stderr.write(`usage: ${_PROG} [-h] [--write] [--strict] [--quiet]\n`);
+    process.stderr.write(`${_PROG}: error: ${msg}\n`);
+    process.exit(2);
+}
+
+export function parse_args(argv: readonly string[]): ParsedArgs {
+    const out: ParsedArgs = { write: false, strict: false, quiet: false };
+    for (const a of argv) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${_PROG} [-h] [--write] [--strict] [--quiet]\n`);
+            process.exit(0);
+        } else if (a === '--write') {
+            out.write = true;
+        } else if (a === '--strict') {
+            out.strict = true;
+        } else if (a === '--quiet') {
+            out.quiet = true;
+        } else {
+            _argError(`unrecognized arguments: ${a}`);
+        }
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] | null = null): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+
+    let fresh: string;
+    try {
+        fresh = _computeFreshContent();
+    } catch (exc) {
+        process.stderr.write(`${_PROG}: ${(exc as Error).message}\n`);
+        return 1;
+    }
+
+    if (args.write) {
+        fs.mkdirSync(path.dirname(_config.CATALOG_PATH), { recursive: true });
+        fs.writeFileSync(_config.CATALOG_PATH, fresh, 'utf-8');
+        if (!args.quiet) {
+            const toolCount = (JSON.parse(fresh) as { tools: unknown[] }).tools.length;
+            process.stdout.write(
+                `wrote ${_relativeToRoot(_config.CATALOG_PATH)} (${toolCount} tool(s))\n`,
+            );
+        }
+        return 0;
+    }
+
+    if (args.strict) {
+        let onDisk: string | null;
+        try {
+            onDisk = fs.readFileSync(_config.CATALOG_PATH, 'utf-8');
+        } catch {
+            onDisk = null;
+        }
+        if (onDisk !== fresh) {
+            process.stderr.write(
+                `❌ ${_relativeToRoot(_config.CATALOG_PATH)} has drifted from the tool registry ` +
+                    '(ALLOWLIST in mcp_server/tools.ts + STUB_TOOLS in ' +
+                    'mcp_server/tool_catalog_source.ts).\n',
+            );
+            process.stderr.write(`   Run: ./scripts-run src/scripts/${_PROG} --write\n`);
+            return 1;
+        }
+        if (!args.quiet) {
+            process.stdout.write(`${_relativeToRoot(_config.CATALOG_PATH)} is in sync with the tool registry\n`);
+        }
+        return 0;
+    }
+
+    // Bare invocation: print the freshly-built JSON to stdout (dry compute,
+    // no write) — mirrors build_discovery_manifest.ts's non-write default.
+    process.stdout.write(fresh);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}