@event4u/agent-config 9.16.0 → 9.18.0

package/src/scripts/_cli/cmd_handoff.ts

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+/**
+ * `agent-config handoff` — pick a recent session, generate a handoff,
+ * seed a fresh session (road-to-agent-handoff-resume Phase 4).
+ *
+ * Default TTY flow: numbered picker over the unified session list
+ * (chat-history primary; Claude-transcript + Codex-session adapters),
+ * then the Phase-2 deterministic generator writes
+ * `agents/runtime/state/handoff-context.md`, which the Phase-3
+ * session_start hook injects into the NEXT session exactly once.
+ *
+ * Flags:
+ *   --list             print the sessions and exit
+ *   --json             with --list: machine-readable output
+ *   --session <id>     skip the picker (exact id or unique prefix)
+ *   --print            emit the handoff to stdout instead of the state
+ *                      file (legacy copy-paste mode)
+ *   --launch <host>    spawn a fresh interactive host session after
+ *                      generating (claude: hook-seeded; codex: handoff as
+ *                      initial prompt — no hook surface there)
+ *   --llm              narrative-polish seam; v1: clear not-implemented error
+ *   --root <path>      repo root override (default: cwd)
+ *
+ * Exit codes: 0 ok · 1 no sessions / session not found · 2 invocation error
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import process from 'node:process';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    build_handoff,
+    handoff_target_path,
+    LlmPolishNotImplementedError,
+    write_handoff,
+} from './handoff_generate.js';
+import { list_handoff_sessions } from './handoff_sessions.js';
+import type { HandoffSession } from './handoff_sessions.js';
+
+const PROG = 'agent-config handoff';
+const USAGE = `usage: ${PROG} [--list] [--json] [--session <id>] [--print] [--launch <host>] [--llm] [--root <path>]`;
+
+const _HELP = `${USAGE}
+
+Pick a recent session, generate a deterministic handoff, and seed a fresh
+session with it. Without flags (in a TTY): numbered picker, then the handoff
+lands in agents/runtime/state/handoff-context.md and auto-injects into the
+next session on hook-capable hosts.
+
+options:
+  --list             print the recent sessions and exit
+  --json             with --list: JSON output
+  --session <id>     generate for this session id (exact or unique prefix)
+  --print            print the handoff to stdout (no state file)
+  --launch <host>    start a fresh interactive session (claude | codex)
+  --llm              optional LLM polish — not implemented in v1
+  --root <path>      repo root (default: current directory)
+  -h, --help         show this help
+
+exit codes:
+  0  handoff generated (or list printed)
+  1  no sessions found / session id not found
+  2  invocation error (bad flag, non-TTY without --session, unsupported host)
+`;
+
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`exit ${code}`);
+    }
+}
+
+// ---------------------------------------------------------------------
+// launch adapter table (v1: claude + codex live, gemini stubbed)
+// ---------------------------------------------------------------------
+
+export interface LaunchAdapter {
+    supports_launch: boolean;
+    /** 'hook' = state file + session_start injection; 'initial-prompt' = argv. */
+    seeding: 'hook' | 'initial-prompt';
+    build_argv: (handoffText: string) => string[];
+}
+
+export const LAUNCH_ADAPTERS: Record<string, LaunchAdapter> = {
+    claude: {
+        supports_launch: true,
+        seeding: 'hook',
+        build_argv: () => ['claude'],
+    },
+    codex: {
+        // Codex is a bundle host without hooks — seed via the initial prompt.
+        supports_launch: true,
+        seeding: 'initial-prompt',
+        build_argv: (handoffText: string) => ['codex', handoffText],
+    },
+    gemini: {
+        supports_launch: false,
+        seeding: 'hook',
+        build_argv: () => ['gemini'],
+    },
+};
+
+// ---------------------------------------------------------------------
+// options + seams
+// ---------------------------------------------------------------------
+
+export interface Opts {
+    list: boolean;
+    json: boolean;
+    session: string | null;
+    print: boolean;
+    launch: string | null;
+    llm: boolean;
+    root: string | null;
+}
+
+type Runner = (cmd: string[]) => number;
+
+export interface MainOptions {
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    /** TTY availability override (default: stdin AND stdout are TTYs). */
+    isTTY?: boolean;
+    /** Picker input; returns the raw line or null on read failure. */
+    readLine?: (prompt: string) => string | null;
+    /** Interactive child spawn (default: spawnSync stdio-inherit). */
+    runner?: Runner;
+}
+
+function _default_runner(cmd: string[]): number {
+    const r = spawnSync(cmd[0] as string, cmd.slice(1), { stdio: 'inherit' });
+    if (r.error) {
+        process.stderr.write(`${PROG}: cannot run ${cmd[0]}: ${String(r.error)}\n`);
+        return 127;
+    }
+    return r.status ?? 1;
+}
+
+/**
+ * Synchronous /dev/tty line read (never fd 0 — EAGAIN under go-task
+ * `interactive: true` silently auto-aborts a fd-0 prompt).
+ */
+function _tty_read_line(prompt: string): string | null {
+    try {
+        process.stdout.write(prompt);
+        const fd = fs.openSync('/dev/tty', 'rs');
+        try {
+            const buf = Buffer.alloc(1);
+            let line = '';
+            for (;;) {
+                let n = 0;
+                try {
+                    n = fs.readSync(fd, buf, 0, 1, null);
+                } catch (exc) {
+                    const code = (exc as NodeJS.ErrnoException).code;
+                    if (code === 'EAGAIN' || code === 'EINTR') continue;
+                    return null;
+                }
+                if (n === 0) break;
+                const ch = buf.toString('utf-8');
+                if (ch === '\n') break;
+                line += ch;
+            }
+            return line;
+        } finally {
+            fs.closeSync(fd);
+        }
+    } catch {
+        return null;
+    }
+}
+
+// ---------------------------------------------------------------------
+// arg parsing (hand-rolled, house style — no commander in _cli/)
+// ---------------------------------------------------------------------
+
+function _argError(err: (t: string) => void, message: string): never {
+    err(`${USAGE}\n${PROG}: error: ${message}\n`);
+    throw new ArgparseExit(2);
+}
+
+export function _parse(argv: string[], err: (t: string) => void): Opts {
+    const opts: Opts = {
+        list: false,
+        json: false,
+        session: null,
+        print: false,
+        launch: null,
+        llm: false,
+        root: null,
+    };
+    let i = 0;
+    const takeValue = (flag: string): string => {
+        const arg = argv[i] as string;
+        const eq = arg.indexOf('=');
+        if (eq >= 0) return arg.slice(eq + 1);
+        i += 1;
+        const value = argv[i];
+        if (value === undefined) _argError(err, `argument ${flag}: expected one argument`);
+        return value;
+    };
+    while (i < argv.length) {
+        const arg = argv[i] as string;
+        const flag = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+        switch (flag) {
+            case '-h':
+            case '--help':
+                process.stdout.write(_HELP);
+                throw new ArgparseExit(0);
+            case '--list':
+                opts.list = true;
+                break;
+            case '--json':
+                opts.json = true;
+                break;
+            case '--print':
+                opts.print = true;
+                break;
+            case '--llm':
+                opts.llm = true;
+                break;
+            case '--session':
+                opts.session = takeValue('--session');
+                break;
+            case '--launch':
+                opts.launch = takeValue('--launch');
+                break;
+            case '--root':
+                opts.root = takeValue('--root');
+                break;
+            default:
+                _argError(err, `unrecognized arguments: ${arg}`);
+        }
+        i += 1;
+    }
+    return opts;
+}
+
+// ---------------------------------------------------------------------
+// rendering
+// ---------------------------------------------------------------------
+
+function _fmt_date(iso: string | null): string {
+    if (!iso) return 'unknown-date';
+    return iso.slice(0, 16).replace('T', ' ');
+}
+
+export function render_session_line(s: HandoffSession, index: number): string {
+    const branch = s.branch ? ` · ${s.branch}` : '';
+    return `${String(index + 1).padStart(2)}. ${_fmt_date(s.endedAt ?? s.startedAt)} · ${s.source}${branch} · ${s.summary}`;
+}
+
+function _render_list(sessions: HandoffSession[], json: boolean): string {
+    if (json) return JSON.stringify(sessions, null, 2) + '\n';
+    return sessions.map((s, i) => render_session_line(s, i)).join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------
+
+export function main(argv: string[] | null = null, options: MainOptions = {}): number {
+    const out = options.out ?? ((t: string): void => void process.stdout.write(t));
+    const err = options.err ?? ((t: string): void => void process.stderr.write(t));
+    const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const readLine = options.readLine ?? _tty_read_line;
+    const runner = options.runner ?? _default_runner;
+
+    let opts: Opts;
+    try {
+        opts = _parse(argv ?? process.argv.slice(2), err);
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) return exc.code;
+        throw exc;
+    }
+
+    // The bash dispatcher strips a global `--root` and exports it as
+    // AGENT_CONFIG_PROJECT_ROOT instead — honor both channels.
+    const envRoot =
+        process.env.AGENT_CONFIG_ROOT_OVERRIDE === '1'
+            ? process.env.AGENT_CONFIG_PROJECT_ROOT || null
+            : null;
+    const root = path.resolve(opts.root ?? envRoot ?? process.cwd());
+    const sessions = list_handoff_sessions({ cwd: root });
+
+    if (opts.list) {
+        if (sessions.length === 0) {
+            out('no recent sessions found for this repo\n');
+            return 1;
+        }
+        out(_render_list(sessions, opts.json));
+        return 0;
+    }
+
+    if (sessions.length === 0) {
+        err(`${PROG}: no recent sessions found for this repo\n`);
+        return 1;
+    }
+
+    if (opts.launch && !(opts.launch in LAUNCH_ADAPTERS)) {
+        err(`${USAGE}\n${PROG}: error: unknown --launch host '${opts.launch}' (claude | codex)\n`);
+        return 2;
+    }
+    const adapter = opts.launch ? (LAUNCH_ADAPTERS[opts.launch] as LaunchAdapter) : null;
+    if (opts.launch && adapter && !adapter.supports_launch) {
+        err(`${PROG}: --launch ${opts.launch} is not supported yet (hook injection already works there)\n`);
+        return 2;
+    }
+
+    // resolve the session — flag, or picker in a TTY
+    let picked: HandoffSession | undefined;
+    if (opts.session) {
+        const matches = sessions.filter((s) => s.id === opts.session || s.id.startsWith(opts.session as string));
+        if (matches.length === 0) {
+            err(`${PROG}: session '${opts.session}' not found — run --list\n`);
+            return 1;
+        }
+        if (matches.length > 1) {
+            err(`${PROG}: session prefix '${opts.session}' is ambiguous (${matches.length} matches)\n`);
+            return 2;
+        }
+        picked = matches[0];
+    } else if (isTTY) {
+        out('Recent sessions:\n');
+        out(_render_list(sessions, false));
+        const raw = readLine(`Pick a session [1-${sessions.length}]: `);
+        const n = Number((raw ?? '').trim());
+        if (!Number.isInteger(n) || n < 1 || n > sessions.length) {
+            err(`${PROG}: invalid selection\n`);
+            return 2;
+        }
+        picked = sessions[n - 1];
+    } else {
+        out(_render_list(sessions, false));
+        err(`${PROG}: non-interactive invocation needs --session <id> (list above)\n`);
+        return 2;
+    }
+    if (!picked) return 2;
+
+    let text: string;
+    try {
+        text = build_handoff(picked, { cwd: root, llm: opts.llm });
+    } catch (exc) {
+        if (exc instanceof LlmPolishNotImplementedError) {
+            err(`${PROG}: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
+    if (opts.print) {
+        out(text);
+        return 0;
+    }
+
+    if (adapter && adapter.seeding === 'initial-prompt') {
+        // no state file on this path — nothing would consume it
+        out(`launching ${opts.launch} with the handoff as initial prompt…\n`);
+        return runner(adapter.build_argv(text));
+    }
+
+    // Only the most recent handoff persists — a second `handoff` run before
+    // the next session start replaces the unconsumed file (by design; the
+    // hook consumes exactly one).
+    const existed = fs.existsSync(handoff_target_path(root));
+    const target = write_handoff(text, { cwd: root });
+    if (existed) out('note: replaced an unconsumed handoff — only the most recent one persists.\n');
+    out(`handoff written: ${target}\n`);
+    out('start a new session — the handoff will be injected automatically (hook-capable hosts).\n');
+
+    if (adapter) {
+        out(`launching ${opts.launch}…\n`);
+        return runner(adapter.build_argv(text));
+    }
+    return 0;
+}
+
+// ---------------------------------------------------------------------
+// entry guard (symlink-safe; same shape as cmd_analyze_session.ts —
+// under the cli-delegate bundle the argv-URL compare matches the bundle)
+// ---------------------------------------------------------------------
+
+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;
+    }
+    // Symlinked invocation (installed projection, /var → /private/var):
+    // compare realpaths so the entry guard still fires.
+    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.exitCode = main();
+}

package/src/scripts/_cli/cmd_route_audit.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config route:audit [--last N] [--record] [--weekly] [--json]` —
+ * replay the shared router matcher over the last N USER prompts of the
+ * repo-local chat-history log and render matched-vs-unmatched per prompt.
+ * Read-only over the inputs; no LLM call; deterministic.
+ *
+ * Measurement level (ADR-126): trigger matching only — what the host actually
+ * invoked on those turns is NOT measured here. "Should-have-matched" is the
+ * human reviewer's judgment over this table, not a computed verdict.
+ *
+ * `--record` appends one JSONL record per audited prompt to the opt-in
+ * routing recorder (`telemetry.routing_recorder.enabled`, default OFF —
+ * disabled means zero file IO and a silent exit contribution). The record is
+ * PII-excluded by construction: it carries a truncated sha256 of the prompt,
+ * never the prompt text, plus matched rule ids / trigger labels and an
+ * enforcement join against `agents/runtime/state/rule-trips.json` where a
+ * same-named hook concern exists. Delete-and-rerun rebuilds it from chat
+ * history — losing it changes no answer (state-store test, ADR-124 § 6).
+ *
+ * `--weekly` renders the rolling last-7-days picture from the recorder log.
+ * Resolver authority note: this instrument is corpus-growth raw material for
+ * `internal/bench/layer1-resolver-PREREG.md` (its P2 condition) as a side
+ * effect only — the PREREG stays the sole authority over any resolver
+ * revival; nothing here builds or scores a resolver.
+ *
+ * Exit codes: 0 rendered (even when the recorder is disabled), 1 no prompts /
+ * no records to audit, 2 invocation or IO error.
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { match_prompt, type Router } from '../_lib/router_match.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+import { read_entries } from '../chat_history.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
+
+// cache-version: v1 — rebuildable audit log: delete-and-rerun rebuilds it from
+// chat history (`route:audit --record`); losing it changes no answer.
+export const RECORDER_REL = 'agents/runtime/state/routing-telemetry.jsonl';
+const RULE_TRIPS_REL = 'agents/runtime/state/rule-trips.json';
+export const RECORD_SCHEMA_VERSION = 1;
+
+export const MEASUREMENT_HEADER =
+    'Measurement level: trigger matching only — what the host actually invokes is NOT measured here (ADR-126).';
+export const PREREG_AUTHORITY_LINE =
+    'Resolver authority: internal/bench/layer1-resolver-PREREG.md — this corpus feeds its P2 condition as a side effect; nothing here revives a resolver.';
+
+function recorder_path(): string {
+    return process.env['AGENT_ROUTING_TELEMETRY_FILE'] ?? path.join(REPO_ROOT, RECORDER_REL);
+}
+
+export function recorder_enabled(): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: REPO_ROOT }) as Record<string, unknown>;
+        const t = settings['telemetry'];
+        if (t === null || typeof t !== 'object' || Array.isArray(t)) return false;
+        const rr = (t as Record<string, unknown>)['routing_recorder'];
+        if (rr === null || typeof rr !== 'object' || Array.isArray(rr)) return false;
+        const enabled = (rr as Record<string, unknown>)['enabled'];
+        return enabled === true || enabled === 'true' || enabled === 'on' || enabled === 'yes';
+    } catch {
+        return false; // unparseable means disabled — default-off doctrine
+    }
+}
+
+interface AuditedPrompt {
+    prompt: string;
+    matched: { rule: string; tier: string; triggers: string[] }[];
+}
+
+function _trigger_label(trigger: Record<string, unknown>): string {
+    for (const kind of ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern']) {
+        if (kind in trigger) return `${kind}: ${String(trigger[kind])}`;
+    }
+    return JSON.stringify(trigger);
+}
+
+export function audit_prompts(router: Router, prompts: string[]): AuditedPrompt[] {
+    return prompts.map((prompt) => {
+        const result = match_prompt(router, prompt, 'full', null, null);
+        const byRule = new Map<string, { tier: string; triggers: string[] }>();
+        for (const mt of result.matched_triggers) {
+            const id = String(mt.rule);
+            const entry = byRule.get(id) ?? { tier: mt.tier.replace('_', '-'), triggers: [] };
+            entry.triggers.push(_trigger_label(mt.trigger as Record<string, unknown>));
+            byRule.set(id, entry);
+        }
+        const matched = [...byRule.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([rule, v]) => ({ rule, tier: v.tier, triggers: v.triggers }));
+        return { prompt, matched };
+    });
+}
+
+/** Last N user prompts from the repo chat-history log, oldest first. */
+export function load_user_prompts(last: number, history_path?: string | null): string[] {
+    let entries: Array<{ t?: unknown; text?: unknown }> = [];
+    try {
+        entries = read_entries({ path: history_path ?? null }) as Array<{ t?: unknown; text?: unknown }>;
+    } catch {
+        return [];
+    }
+    const prompts: string[] = [];
+    for (const e of entries) {
+        if (e === null || typeof e !== 'object') continue;
+        if (e.t !== 'user' || typeof e.text !== 'string') continue;
+        const text = e.text.trim();
+        // Host-injected meta turns are not user prompts (same filter as the
+        // handoff session reader).
+        if (text === '' || text.startsWith('<') || text.startsWith('Caveat:')) continue;
+        prompts.push(text);
+    }
+    return prompts.slice(-last);
+}
+
+interface TripsDoc {
+    concerns?: Record<string, { block?: number; warn?: number }>;
+}
+
+function _load_trips(): TripsDoc {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, RULE_TRIPS_REL), 'utf-8')) as TripsDoc;
+    } catch {
+        return {};
+    }
+}
+
+export function build_records(audits: AuditedPrompt[], now_iso: string): Record<string, unknown>[] {
+    const trips = _load_trips();
+    return audits.map((a) => {
+        const enforcement_trips: Record<string, { block: number; warn: number }> = {};
+        for (const m of a.matched) {
+            const concern = trips.concerns?.[m.rule];
+            if (concern) {
+                enforcement_trips[m.rule] = { block: concern.block ?? 0, warn: concern.warn ?? 0 };
+            }
+        }
+        // PII-exclusion-by-construction: no free-form prompt field exists in
+        // this record type — only a truncated digest and closed-shape labels.
+        return {
+            schema_version: RECORD_SCHEMA_VERSION,
+            ts: now_iso,
+            prompt_sha16: crypto.createHash('sha256').update(a.prompt).digest('hex').slice(0, 16),
+            matched: a.matched,
+            enforcement_trips,
+        };
+    });
+}
+
+export function append_records(records: Record<string, unknown>[], target: string): number {
+    if (process.env['AGENT_CONFIG_REPLAY'] === '1') return 0; // replay mode: no state writes
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const fd = fs.openSync(target, 'a', 0o644);
+    try {
+        for (const r of records) fs.writeSync(fd, JSON.stringify(r) + '\n');
+        fs.fsyncSync(fd);
+    } finally {
+        fs.closeSync(fd);
+    }
+    return records.length;
+}
+
+export function render_weekly(target: string, now: Date): { text: string; records: number } {
+    let lines: string[] = [];
+    try {
+        lines = fs.readFileSync(target, 'utf-8').split('\n').filter(Boolean);
+    } catch {
+        lines = [];
+    }
+    const cutoff = now.getTime() - 7 * 24 * 60 * 60 * 1000;
+    const perRule = new Map<string, number>();
+    let inWindow = 0;
+    for (const line of lines) {
+        let rec: { ts?: string; matched?: { rule: string }[] };
+        try {
+            rec = JSON.parse(line) as typeof rec;
+        } catch {
+            continue;
+        }
+        const ts = Date.parse(rec.ts ?? '');
+        if (Number.isNaN(ts) || ts < cutoff) continue;
+        inWindow += 1;
+        for (const m of rec.matched ?? []) {
+            perRule.set(m.rule, (perRule.get(m.rule) ?? 0) + 1);
+        }
+    }
+    const out: string[] = [MEASUREMENT_HEADER, ''];
+    out.push(`routing recorder — rolling 7-day window (${inWindow} recorded prompt(s))`);
+    if (inWindow === 0) {
+        out.push('  (no records in the window — enable telemetry.routing_recorder and run `route:audit --record`)');
+    } else {
+        const rows = [...perRule.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+        for (const [rule, n] of rows) out.push(`  ${String(n).padStart(4)} × ${rule}`);
+    }
+    out.push('');
+    out.push(PREREG_AUTHORITY_LINE);
+    return { text: out.join('\n') + '\n', records: inWindow };
+}
+
+export function main(argv: string[]): number {
+    const args = [...argv];
+    const as_json = args.includes('--json');
+    const weekly = args.includes('--weekly');
+    const record = args.includes('--record');
+    let last = 10;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] as string;
+        if (a === '--last') last = Number(args[++i] ?? '10') || 10;
+        else if (a.startsWith('--last=')) last = Number(a.slice('--last='.length)) || 10;
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: agent-config route:audit [--last N] [--record] [--weekly] [--json]\n');
+            return 0;
+        }
+    }
+
+    if (weekly) {
+        const { text, records } = render_weekly(recorder_path(), new Date());
+        process.stdout.write(text);
+        return records === 0 ? 1 : 0;
+    }
+
+    let router: Router;
+    try {
+        router = JSON.parse(fs.readFileSync(ROUTER_JSON, 'utf-8')) as Router;
+    } catch (e) {
+        process.stderr.write(`route:audit: cannot read ${ROUTER_JSON}: ${String(e)}\n`);
+        return 2;
+    }
+    const prompts = load_user_prompts(last);
+    if (prompts.length === 0) {
+        process.stdout.write(MEASUREMENT_HEADER + '\n\n');
+        process.stdout.write('no user prompts found in the chat-history log — nothing to audit\n');
+        return 1;
+    }
+    const audits = audit_prompts(router, prompts);
+
+    let recorded = 0;
+    let recorder_note = '';
+    if (record) {
+        if (recorder_enabled()) {
+            recorded = append_records(build_records(audits, new Date().toISOString()), recorder_path());
+            recorder_note = `recorded ${recorded} prompt(s) to ${RECORDER_REL}`;
+        } else {
+            recorder_note = 'recorder disabled (telemetry.routing_recorder.enabled is off — default) — nothing written';
+        }
+    }
+
+    if (as_json) {
+        process.stdout.write(
+            JSON.stringify(
+                { measurement_level: MEASUREMENT_HEADER, audited: audits.length, recorded, prompts: audits },
+                null,
+                2,
+            ) + '\n',
+        );
+        return 0;
+    }
+    const out: string[] = [MEASUREMENT_HEADER, ''];
+    out.push(`audited the last ${audits.length} user prompt(s) — matched rules per prompt`);
+    out.push('(should-have-matched is the reviewer\'s judgment over this table, not a computed verdict)');
+    out.push('');
+    audits.forEach((a, i) => {
+        const shown = a.prompt.length > 100 ? a.prompt.slice(0, 97) + '...' : a.prompt;
+        out.push(`${String(i + 1).padStart(3)}. ${JSON.stringify(shown)}`);
+        if (a.matched.length === 0) {
+            out.push('       → (no trigger matched — kernel only)');
+        } else {
+            for (const m of a.matched) {
+                out.push(`       → ${m.rule} [${m.tier}] (${m.triggers.join(' · ')})`);
+            }
+        }
+    });
+    if (recorder_note) {
+        out.push('');
+        out.push(recorder_note);
+    }
+    process.stdout.write(out.join('\n') + '\n');
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
+    process.exitCode = main(process.argv.slice(2));
+}