@event4u/agent-config 9.14.0 → 9.16.0

package/src/scripts/audit_initial_context.ts

@@ -59,9 +59,22 @@ const MONOLITH_TOOLS = ['.windsurfrules'];
 // costing?" question as the rule/description surfaces, for the MCP slice. The
 // source-of-truth catalog is the one shipped by this package's MCP server.
 const MCP_CATALOG = path.join(REPO_ROOT, 'src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json');
-// This package ships a single MCP server; the accounting is keyed by server so
-// a multi-server consumer surface generalises without a shape change.
+// The catalog is served by TWO transports with two different tool lists, so
+// pricing it once produced a number no client ever loads:
+//
+//   - stdio  (`src/scripts/mcp_server/`) registers only the implemented tools
+//     (`REGISTRY` in mcp_server/tools.ts) — the 12 discovery stubs are
+//     deliberately unregistered (ADR-132), so a local client sees 19.
+//   - worker (`internal/workers/mcp/`) maps EVERY catalog entry into
+//     `tools/list` (`stubs.ts::listTools`), tagging stubs `_meta.stub` and
+//     answering calls with the not_implemented envelope — so it sees 31.
+//
+// Pricing all 31 under one label reported a hybrid client that cannot exist,
+// and made the over-subscription flag fire on a count no local install pays.
+// Keying by transport keeps the per-server shape and makes each number belong
+// to a real client. `implemented_on` in the catalog is what distinguishes them.
 const MCP_SERVER_NAME = 'agent-config';
+const MCP_TRANSPORTS = ['stdio', 'worker'] as const;
 // Soft advisory ceiling on tool count per server. "Few used" cannot be known at
 // audit time (no runtime call data), so over-subscription is a count-based
 // heuristic: many tools => maintainer should review which earn their cost.
@@ -396,24 +409,40 @@ export function mcp_tool_schemas(): Record<string, McpServer> {
         return {};
     }
     const tools = (catalog.tools as unknown[]) ?? [];
-    const priced: McpPriced[] = tools
-        .filter((t): t is Record<string, unknown> => typeof t === 'object' && t !== null && !Array.isArray(t))
-        .map((t) => _measure_tool_schema(t));
-    // priced.sort(key=lambda r: (-int(r["tokens_gpt"]), str(r["name"])))
-    priced.sort(
-        (a, b) => b.tokens_gpt - a.tokens_gpt || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+    const records = tools.filter(
+        (t): t is Record<string, unknown> => typeof t === 'object' && t !== null && !Array.isArray(t),
     );
-    const server: McpServer = {
-        tool_count: priced.length,
-        chars: priced.reduce((acc, r) => acc + r.chars, 0),
-        tokens_gpt: priced.reduce((acc, r) => acc + r.tokens_gpt, 0),
-        tokens_claude: priced.reduce((acc, r) => acc + r.tokens_claude, 0),
-        tokens_gpt_exact: priced.length > 0 ? priced.every((r) => Boolean(r.tokens_gpt_exact)) : true,
-        over_subscription: priced.length > MCP_OVERSUBSCRIPTION_TOOL_CAP,
-        oversubscription_cap: MCP_OVERSUBSCRIPTION_TOOL_CAP,
-        tools: priced.map((r) => ({ name: r.name, tokens_gpt: r.tokens_gpt, chars: r.chars })),
+
+    /** Tools a given transport actually returns from `tools/list`. */
+    const served = (transport: string): Record<string, unknown>[] => {
+        // The Worker serves the whole catalog (stubs included, flagged
+        // `_meta.stub`); stdio serves only what `implemented_on` names.
+        if (transport === 'worker') return records;
+        return records.filter(
+            (t) => Array.isArray(t.implemented_on) && (t.implemented_on as unknown[]).includes(transport),
+        );
     };
-    return { [MCP_SERVER_NAME]: server };
+
+    const out: Record<string, McpServer> = {};
+    for (const transport of MCP_TRANSPORTS) {
+        const priced: McpPriced[] = served(transport).map((t) => _measure_tool_schema(t));
+        // priced.sort(key=lambda r: (-int(r["tokens_gpt"]), str(r["name"])))
+        priced.sort(
+            (a, b) => b.tokens_gpt - a.tokens_gpt || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+        );
+        out[`${MCP_SERVER_NAME} (${transport})`] = {
+            tool_count: priced.length,
+            chars: priced.reduce((acc, r) => acc + r.chars, 0),
+            tokens_gpt: priced.reduce((acc, r) => acc + r.tokens_gpt, 0),
+            tokens_claude: priced.reduce((acc, r) => acc + r.tokens_claude, 0),
+            tokens_gpt_exact:
+                priced.length > 0 ? priced.every((r) => Boolean(r.tokens_gpt_exact)) : true,
+            over_subscription: priced.length > MCP_OVERSUBSCRIPTION_TOOL_CAP,
+            oversubscription_cap: MCP_OVERSUBSCRIPTION_TOOL_CAP,
+            tools: priced.map((r) => ({ name: r.name, tokens_gpt: r.tokens_gpt, chars: r.chars })),
+        };
+    }
+    return out;
 }
 
 export function build(): Record<string, unknown> {
@@ -678,7 +707,12 @@ export function main(argv: string[] | null = null): number {
         const rf = rfVals.length > 0 ? (rfVals[0] as Measure) : ({} as Measure);
         const dc = data.description_catalog as Record<string, Measure>;
         const mcp = (data.mcp_tool_schemas as Record<string, McpServer>) ?? {};
-        const mcp_gpt = Object.values(mcp).reduce((acc, s) => acc + s.tokens_gpt, 0);
+        // MAX, not sum: the entries are two TRANSPORTS of the same server, and
+        // a client connects over exactly one of them. Summing would bill the
+        // 19 implemented tools twice and gate on a client that cannot exist —
+        // the same conflation the per-transport split exists to remove. The
+        // budget is what the worst-case single client actually loads.
+        const mcp_gpt = Object.values(mcp).reduce((acc, s) => Math.max(acc, s.tokens_gpt), 0);
         const checks: Record<string, number> = {
             'rules.gpt': rf.tokens_gpt ?? 0,
             // The always-SCANNED skill descriptions (258 source skills) — the

package/src/scripts/audit_likelihood.ts

@@ -30,6 +30,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_likelihood.py → parent.parent.parent == repo root.
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -38,9 +40,20 @@ export const AUDIT_JSON = path.join(REPORT_DIR, 'auto-rules-audit.json');
 export const AUDIT_MD = path.join(REPORT_DIR, 'auto-rules-audit.md');
 export const LIKELIHOOD_JSON = path.join(REPORT_DIR, 'auto-rules-likelihood.json');
 
+/**
+ * The corpus a rule's trigger terms are scored against.
+ *
+ * The first two globs named the pre-ADR-051 source container, so skills and
+ * commands — by far the largest and most trigger-dense part of the corpus —
+ * contributed nothing. The audit still printed a score for every rule, derived
+ * from contexts + guidelines alone; that biases every score downward and makes
+ * the low-likelihood flag unreliable in the direction that matters (false
+ * "nothing triggers this"). Commands are now one `command.md` leaf per verb
+ * under `src/domains`.
+ */
 const CORPUS_GLOBS: readonly string[] = [
-    '.agent-src.uncondensed/skills/**/SKILL.md',
-    '.agent-src.uncondensed/commands/**/*.md',
+    'src/skills/**/SKILL.md',
+    'src/domains/**/command.md',
     'agents/settings/contexts/**/*.md',
     'docs/guidelines/**/*.md',
 ];
@@ -403,6 +416,22 @@ export function main(): number {
     }
     const rules: Json[] = JSON.parse(fs.readFileSync(AUDIT_JSON, 'utf-8'))['rules'];
     const corpus = build_corpus();
+    // Scope assertion: an empty corpus scores every rule as low-likelihood
+    // while looking exactly like a completed audit.
+    try {
+        assertScanned({
+            gate: 'audit_likelihood',
+            scanned: corpus.size,
+            units: 'distinct corpus token(s)',
+            roots: CORPUS_GLOBS,
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
     const scores = rules.map((r) => score(r, corpus));
     fs.writeFileSync(
         LIKELIHOOD_JSON,

package/src/scripts/audit_user_type_axis.ts

@@ -8,19 +8,22 @@
  * split, byte-identical stdout summary, AND byte-identical generated
  * Markdown report. Stdlib-only — no YAML dependency.
  *
- * Two checks across `.agent-src.uncondensed/skills/`:
+ * Two checks across `src/skills/`:
  *
  *   1. Orphan values — every `recommended_for_user_types` value must have a
- *      `user-types/<value>.yml` config. Orphans are FATAL (exit 1).
+ *      `user-types/<value>.yml` config. Orphans are FATAL (exit 1), subject to
+ *      the recorded violation ratchet.
  *   2. Unused configs — every `user-types/*.yml` should be consumed by at
  *      least one skill. Unused configs are WARN-only (exit 0).
  *
- * NOTE: the retired Python implementation scans only the LEGACY `.agent-src.uncondensed/
- * skills/` root (not the 6.0.0-D `src/skills/` library). This twin replicates
- * that exact root for byte-identical parity. The report path is
- * `agents/reports/user-type-axis-audit.md` (matching the Python constant,
- * which differs from the docstring's `agents/runtime/reports/` mention —
- * latent bug replicated).
+ * NOTE: the retired Python implementation scanned only the pre-ADR-051 source
+ * container, and this twin inherited that root verbatim for byte parity — which
+ * meant it scanned nothing at all once the container was emptied. Repaired
+ * 2026-08-02 to `src/skills`; byte-parity with the .py is deliberately given up
+ * here, because parity with a scan of zero files is not a property worth
+ * keeping. The report path is `agents/reports/user-type-axis-audit.md`
+ * (matching the Python constant, which differs from the docstring's
+ * `agents/runtime/reports/` mention — latent bug replicated).
  *
  * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
@@ -29,11 +32,21 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/audit_user_type_axis.ts → parents[2] of the .py file is repo root.
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-export const SKILLS_ROOT = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+/**
+ * ADR-051 moved skill authoring to `src/skills`. This still named the retired
+ * container, so `_scan_skill_values()` took its `!_isDir` early return and the
+ * audit reported `used=0 orphans=0` — a clean verdict derived from reading
+ * nothing, with all 7 declared user types written off as "unused".
+ */
+export const SKILLS_ROOT = SRC_SKILLS();
 export const USER_TYPES_ROOT = path.join(REPO_ROOT, 'user-types');
 export const REPORT_PATH = path.join(REPO_ROOT, 'agents', 'reports', 'user-type-axis-audit.md');
 
@@ -228,6 +241,24 @@ export function _render_report(
 
 export function main(argv: string[]): number {
     const quiet = argv.includes('--quiet');
+    // Scope assertion: the orphan/unused verdict is a set difference against
+    // the skills corpus, so an unreadable corpus does not yield "no orphans",
+    // it yields a vacuous answer that looks identical to a clean one.
+    const scannedSkills = _isDir(SKILLS_ROOT) ? _rglobSkillMd(SKILLS_ROOT).length : 0;
+    try {
+        assertScanned({
+            gate: 'audit_user_type_axis',
+            scanned: scannedSkills,
+            units: 'skill file(s)',
+            roots: [_relativeToPosix(SKILLS_ROOT, REPO_ROOT)],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
     const declared = _declared_user_types();
     const byValue = _scan_skill_values();
     const used = new Set<string>(byValue.keys());
@@ -242,7 +273,8 @@ export function main(argv: string[]): number {
     if (!quiet) {
         process.stdout.write(
             `user-type-axis audit — declared=${declared.size} ` +
-                `used=${used.size} orphans=${orphans.size} unused=${unused.size}\n`,
+                `used=${used.size} orphans=${orphans.size} unused=${unused.size} ` +
+                `(${scannedSkills} skill file(s) scanned)\n`,
         );
         if (orphans.size > 0) {
             process.stdout.write('  FAIL orphans: ' + _sorted(orphans).join(', ') + '\n');
@@ -253,7 +285,22 @@ export function main(argv: string[]): number {
         process.stdout.write(`  report: ${_relativeToPosix(REPORT_PATH, REPO_ROOT)}\n`);
     }
 
-    return orphans.size > 0 ? 1 : 0;
+    if (orphans.size === 0) {
+        return 0;
+    }
+    const verdict = checkRatchet({
+        gate: 'audit_user_type_axis',
+        actual: orphans.size,
+        repoRoot: REPO_ROOT,
+    });
+    if (verdict.ok) {
+        if (!quiet) {
+            process.stdout.write(`⚠️   ${verdict.message}\n`);
+        }
+        return 0;
+    }
+    process.stderr.write(`❌  ${verdict.message}\n`);
+    return 1;
 }
 
 function _isCliEntry(): boolean {

package/src/scripts/bench_hook_latency.ts

@@ -12,12 +12,20 @@
  *     ./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
+ *     ./scripts-run src/scripts/bench_hook_latency --via-cli  # real consumer path
  *
  * 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).
+ *   - N invocations per hook event (default 50, --runs N) with a synthetic
+ *     payload on stdin and a throwaway temp workspace as --project-dir
+ *     (concern state lands there, never in the repo). Two invocation paths:
+ *       default    — `node dist/hooks/dispatch.js --platform claude
+ *                    --event <e>` (the bare bundle).
+ *       --via-cli  — the EXACT command line `hooks/hooks.json` installs
+ *                    (bash wrapper + project-shim probe +
+ *                    `agent-config dispatch:hook … --native-event …
+ *                    --min-version 1`), i.e. the path consumers actually
+ *                    pay per hook event (road-to-hook-latency-repair
+ *                    Phase 1).
  *   - 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.
@@ -25,11 +33,19 @@
  * 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.
+ *   - when docs/hook-latency.json exists AND its recorded invocation_path
+ *     matches this run's path, a p95 regression beyond
+ *     regression_gate.max_regression_pct fails (mismatched paths skip the
+ *     regression net — absolute budgets still bind).
  *   Budgets: src/config/hook-latency-budget.json (pre-registered, owner +
  *   review date — see the Phase-6 budget-ownership lint).
  *
+ * Baseline history (--baseline "<hardware class>"): appends this run to the
+ * `history` array in docs/hook-latency.json — invocation path, hardware
+ * class, per-event p50/p95 — WITHOUT touching the top-level results the
+ * regression net compares against. Used to commit the pre-fix CLI-path
+ * numbers before the Phase-2 levers landed.
+ *
  * Exit codes: 0 green · 1 budget/regression exceeded · 2 internal error.
  */
 import { spawnSync } from 'node:child_process';
@@ -37,9 +53,13 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUNDLE = path.join(REPO_ROOT, 'dist', 'hooks', 'dispatch.js');
+const CLI_BIN = path.join(REPO_ROOT, 'dist', 'cli', 'agent-config.js');
+const SHIM = path.join(REPO_ROOT, 'agent-config');
+const MANIFEST_PATH = path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml');
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'hook-latency-budget.json');
 const RESULTS_PATH = path.join(REPO_ROOT, 'docs', 'hook-latency.json');
 
@@ -52,6 +72,18 @@ const EVENTS: readonly string[] = [
     'session_end',
 ];
 
+/** snake_case hook event → the platform-native name hooks.json passes. */
+const NATIVE_EVENT: Readonly<Record<string, string>> = {
+    pre_tool_use: 'PreToolUse',
+    post_tool_use: 'PostToolUse',
+    user_prompt_submit: 'UserPromptSubmit',
+    stop: 'Stop',
+    session_start: 'SessionStart',
+    session_end: 'SessionEnd',
+};
+
+export type InvocationPath = 'bundle' | 'cli';
+
 interface EventResult {
     event: string;
     runs: number;
@@ -79,29 +111,49 @@ function syntheticPayload(event: string, workspace: string): string {
     });
 }
 
-export function benchEvent(event: string, runs: number, workspace: string): EventResult {
+/**
+ * The verbatim per-event command `hooks/hooks.json` installs — taken from
+ * build_claude_hook_matrix(), the SAME generator that writes hooks.json and
+ * the consumer settings entries, so the bench cannot drift from the
+ * installed command. The bench sets CLAUDE_PROJECT_DIR to the throwaway
+ * workspace (which carries a symlink to the repo shim, exactly the layout a
+ * shim-carrying project has), so the probe takes the same branch a consumer
+ * pays and concern state stays out of the repo.
+ */
+let _matrixCache: Record<string, string> | null = null;
+function hooksJsonCommand(event: string): string {
+    _matrixCache ??= build_claude_hook_matrix(MANIFEST_PATH);
+    const native = NATIVE_EVENT[event] ?? event;
+    const cmd = _matrixCache[native];
+    if (cmd === undefined) {
+        throw new Error(`no hook-matrix entry for ${event} (${native}) in ${MANIFEST_PATH}`);
+    }
+    return cmd;
+}
+
+export function benchEvent(
+    event: string,
+    runs: number,
+    workspace: string,
+    via: InvocationPath = 'bundle',
+): EventResult {
     const durations: number[] = [];
     const payload = syntheticPayload(event, workspace);
+    const command: [string, string[]] =
+        via === 'cli'
+            ? ['bash', ['-c', hooksJsonCommand(event)]]
+            : [
+                  process.execPath,
+                  [BUNDLE, '--platform', 'claude', '--event', event, '--project-dir', 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 proc = spawnSync(command[0], command[1], {
+            input: payload,
+            encoding: 'utf-8',
+            env: { ...process.env, AGENT_CONFIG_REPLAY: '1', CLAUDE_PROJECT_DIR: workspace },
+            timeout: 60000,
+        });
         const elapsed = performance.now() - started;
         if (proc.error) {
             throw new Error(`dispatch failed on ${event}: ${proc.error.message}`);
@@ -134,9 +186,35 @@ interface Budget {
     regression_gate: { max_regression_pct: number };
 }
 
+interface HistoryEntry {
+    recorded_at: string;
+    invocation_path: InvocationPath;
+    hardware: string;
+    node: string;
+    platform: string;
+    runs_per_event: number;
+    results: EventResult[];
+}
+
+interface ResultsDoc {
+    _comment?: string;
+    invocation_path?: InvocationPath;
+    results: EventResult[];
+    history?: HistoryEntry[];
+    [key: string]: unknown;
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     const gate = argv.includes('--gate');
     const update = argv.includes('--update');
+    const viaCli = argv.includes('--via-cli');
+    const via: InvocationPath = viaCli ? 'cli' : 'bundle';
+    const baselineIdx = argv.indexOf('--baseline');
+    const baselineHardware = baselineIdx >= 0 ? (argv[baselineIdx + 1] ?? null) : null;
+    if (baselineIdx >= 0 && (baselineHardware === null || baselineHardware.startsWith('--'))) {
+        process.stderr.write('bench_hook_latency: --baseline requires a "<hardware class>" label\n');
+        return 2;
+    }
     const runsIdx = argv.indexOf('--runs');
     const runs = runsIdx >= 0 ? Number.parseInt(argv[runsIdx + 1] ?? '50', 10) : 50;
 
@@ -146,6 +224,21 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         );
         return 2;
     }
+    if (viaCli) {
+        // The CLI path exercises shim → dist/cli → bundle; a missing link
+        // would make the hooks.json probe silently `exit 0` and the bench
+        // would time bash startup instead of a dispatch.
+        if (!fs.existsSync(CLI_BIN)) {
+            process.stderr.write(
+                `bench_hook_latency: CLI missing at ${CLI_BIN} — run \`npm run build:cli\` first\n`,
+            );
+            return 2;
+        }
+        if (!fs.existsSync(SHIM)) {
+            process.stderr.write(`bench_hook_latency: repo shim missing at ${SHIM}\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`);
@@ -155,11 +248,23 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-hook-bench-'));
     const results: EventResult[] = [];
     try {
+        if (viaCli) {
+            // Stage the workspace like a real consumer project so the
+            // installed command's probes take the branch consumers pay:
+            //   - node_modules/@event4u/agent-config → the package (bundle
+            //     fast path candidate 1),
+            //   - ./agent-config shim → the CLI fallback (resolved through
+            //     the symlink; the shim self-resolves symlinks).
+            const scope = path.join(workspace, 'node_modules', '@event4u');
+            fs.mkdirSync(scope, { recursive: true });
+            fs.symlinkSync(REPO_ROOT, path.join(scope, 'agent-config'));
+            fs.symlinkSync(path.join(REPO_ROOT, 'src', 'scripts', 'agent-config'), path.join(workspace, 'agent-config'));
+        }
         for (const event of EVENTS) {
-            const r = benchEvent(event, runs, workspace);
+            const r = benchEvent(event, runs, workspace, via);
             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`,
+                `${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}, via ${via})\n`,
             );
         }
     } finally {
@@ -167,7 +272,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 
     let failed = false;
-    const prior = loadJson<{ results: EventResult[] }>(RESULTS_PATH);
+    const prior = loadJson<ResultsDoc>(RESULTS_PATH);
+    const priorPath: InvocationPath = prior?.invocation_path ?? 'bundle';
     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;
@@ -177,7 +283,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             );
             failed = true;
         }
-        if (gate && prior !== null) {
+        if (gate && prior !== null && priorPath === via) {
             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;
@@ -191,20 +297,45 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             }
         }
     }
+    if (gate && prior !== null && priorPath !== via) {
+        process.stdout.write(
+            `ℹ️  regression net skipped — recorded baseline is via ${priorPath}, this run is via ${via}\n`,
+        );
+    }
 
-    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,
-        };
+    if (update || baselineHardware !== null) {
+        const existing = prior ?? ({ results: [] } as ResultsDoc);
+        const history: HistoryEntry[] = existing.history ?? [];
+        if (baselineHardware !== null) {
+            history.push({
+                recorded_at: new Date().toISOString(),
+                invocation_path: via,
+                hardware: baselineHardware,
+                node: process.version,
+                platform: `${os.platform()}-${os.arch()}`,
+                runs_per_event: runs,
+                results,
+            });
+        }
+        const doc: ResultsDoc = update
+            ? {
+                  _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. `history` entries (--baseline) are point-in-time records — the top-level results are the regression base.',
+                  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',
+                  invocation_path: via,
+                  runs_per_event: runs,
+                  results,
+                  ...(history.length > 0 ? { history } : {}),
+              }
+            : { ...existing, history };
         fs.writeFileSync(RESULTS_PATH, `${JSON.stringify(doc, null, 4)}\n`);
-        process.stdout.write(`recorded → ${path.relative(REPO_ROOT, RESULTS_PATH)}\n`);
+        process.stdout.write(
+            `recorded → ${path.relative(REPO_ROOT, RESULTS_PATH)}${update ? '' : ' (history entry only)'}\n`,
+        );
     }
 
     if (failed) return 1;

package/src/scripts/bench_persona_placebo.ts

@@ -29,7 +29,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 import { signTestP } from './second_brain_retrieval.js';
 

package/src/scripts/bench_quality_run.ts

@@ -30,7 +30,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 import { build_thin, RULES_SOURCE } from './project_thin_rules.js';
 import { evaluatePair, type JudgeFn, type JudgeVerdict, type PairResult } from './check_quality_regression.js';

package/src/scripts/build_mcp_catalog.ts

@@ -135,7 +135,18 @@ export function _buildEntries(): CatalogEntryOut[] {
             description: STUB_MARKER + stub.description,
             side_effect: stub.side_effect,
             implemented_on: [],
-            input_schema: stub.input_schema,
+            // A stub ships an EMPTY schema on purpose. `input_schema` exists to
+            // tell a client how to CALL the tool, and no transport permits that
+            // for a stub: the Worker answers with the not_implemented envelope
+            // and stdio never registers it (`REGISTRY` in mcp_server/tools.ts).
+            // A populated schema is therefore always-loaded context that can
+            // never be acted on — 665 GPT tok across the 12 stubs, measured
+            // 2026-08-02. `stub.input_schema` stays in STUB_TOOLS as the design
+            // record for the day the tool is wired; it is simply not shipped
+            // until then. The stub-envelope contract's "byte-identical apart
+            // from implemented_on" promise still holds — both transports read
+            // this same file.
+            input_schema: {},
         });
     }