@event4u/agent-config 9.29.0 → 9.31.0

package/src/scripts/_lib/subagent_response.ts

@@ -21,12 +21,38 @@ export interface Finding {
     mutating?: boolean;
 }
 
+// ── Committed envelope size caps (road-to-token-economy-dispatch Phase 6.1) ──
+// The envelope is the ONLY return channel: a worker's full result lands on
+// disk (runtime artifact dir, gitignored) and the envelope carries paths +
+// verdict + a BOUNDED summary. Without caps, transcript-shaped output flows
+// back into the orchestrator context and refunds the isolation win — the
+// measured spawn floor is ~251k tokens; a capped envelope is ≤ ~3k. Caps are
+// validator ERRORS, never silent truncation (never-silent discipline): an
+// oversized envelope is rejected loudly and the author shortens it.
+/** Max chars for the summary — bounded prose, not a transcript. */
+export const MAX_SUMMARY_CHARS = 2000;
+/** Max chars for one line-shaped field (handoff, a risk, a finding title). */
+export const MAX_RESPONSE_LINE_CHARS = 240;
+/** Max entries per array (findings, risks, artifact_paths) — mirrors the capsule. */
+export const MAX_RESPONSE_ENTRIES = 40;
+/** Max chars for one artifact path ref. Mirrors the capsule's ref cap. */
+export const MAX_ARTIFACT_REF_CHARS = 200;
+/** Committed max for the WHOLE serialized envelope (~3k tokens ceiling). */
+export const MAX_ENVELOPE_CHARS = 12000;
+
 export interface SubagentResponse {
     summary: string;
     findings: Finding[];
     risks: string[];
     confidence: Confidence;
     handoff: string;
+    /**
+     * Where the worker's FULL results live on disk (runtime artifact dir,
+     * gitignored) — the orchestrator consumes from these paths on demand,
+     * never via wholesale transcript ingestion (Phase 6.1/6.2). Ref tokens
+     * only, capped like every other array.
+     */
+    artifact_paths?: string[];
     /**
      * Premises the worker acted on, `{statement, basis, epistemic_state}` —
      * the same shape and the same validator as the CHECKPOINT capsule
@@ -74,6 +100,55 @@ export function validateResponse(input: unknown): ValidationResult {
             }
         }
     }
+    // ── Committed size caps (Phase 6.1) — errors, never silent truncation ──
+    if (typeof r.summary === 'string' && r.summary.length > MAX_SUMMARY_CHARS) {
+        errors.push(`summary is ${r.summary.length} chars (max ${MAX_SUMMARY_CHARS}) — the envelope carries a bounded summary; the full result belongs on disk (artifact_paths)`);
+    }
+    if (typeof r.handoff === 'string' && r.handoff.length > MAX_RESPONSE_LINE_CHARS) {
+        errors.push(`handoff is ${r.handoff.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+    }
+    for (const [key, arr] of [
+        ['findings', r.findings],
+        ['risks', r.risks],
+        ['artifact_paths', r.artifact_paths],
+    ] as const) {
+        if (Array.isArray(arr) && arr.length > MAX_RESPONSE_ENTRIES) {
+            errors.push(`${key} carries ${arr.length} entries (max ${MAX_RESPONSE_ENTRIES}) — an envelope is a handoff, not a transcript`);
+        }
+    }
+    if (Array.isArray(r.risks)) {
+        for (const [i, risk] of (r.risks as unknown[]).entries()) {
+            if (typeof risk === 'string' && risk.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`risks[${i}] is ${risk.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (Array.isArray(r.findings)) {
+        for (const [i, f] of (r.findings as Finding[]).entries()) {
+            if (f && typeof f.title === 'string' && f.title.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`finding[${i}] title is ${f.title.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (r.artifact_paths !== undefined) {
+        if (!Array.isArray(r.artifact_paths)) {
+            errors.push('artifact_paths must be an array of path ref tokens');
+        } else {
+            for (const [i, p] of (r.artifact_paths as unknown[]).entries()) {
+                if (typeof p !== 'string' || p.includes('\n') || p.length > MAX_ARTIFACT_REF_CHARS) {
+                    errors.push(`artifact_paths[${i}] must be a single-line path ref ≤ ${MAX_ARTIFACT_REF_CHARS} chars`);
+                }
+            }
+        }
+    }
+    try {
+        const serialized = JSON.stringify(input);
+        if (serialized.length > MAX_ENVELOPE_CHARS) {
+            errors.push(`envelope serializes to ${serialized.length} chars (max ${MAX_ENVELOPE_CHARS}) — move content to disk and reference it via artifact_paths`);
+        }
+    } catch {
+        errors.push('envelope is not JSON-serializable');
+    }
     return { valid: errors.length === 0, errors };
 }
 

package/src/scripts/ai_council/clients.ts

@@ -45,6 +45,37 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { SESSION_ROLE_ENV } from '../_lib/session_role.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+
+// Session-wide subagent model ceiling (token-economy-dispatch Phase 5.2):
+// class-C setting, default absent, HUMAN-set only. When present, the CLI
+// spawn below exports CLAUDE_CODE_SUBAGENT_MODEL so the spawned vendor
+// session caps its own subagents' models. Memoised PER CWD, not per
+// process (review finding 2026-08-10): a long-lived server process may
+// serve several projects, and a single-slot memo would apply project A's
+// spend cap to project B's spawns. A human edit still needs a process
+// restart to be seen — acceptable for a per-install cap, stated here.
+const _modelCeilingMemo = new Map<string, string | null>();
+export function _subagentModelCeiling(cwd: string = process.cwd()): string | null {
+    const hit = _modelCeilingMemo.get(cwd);
+    if (hit !== undefined) return hit;
+    let ceiling: string | null;
+    try {
+        const settings = load_agent_settings({ cwd }) as Record<string, unknown>;
+        const sub = (settings['subagents'] ?? {}) as Record<string, unknown>;
+        const v = typeof sub['model_ceiling'] === 'string' ? sub['model_ceiling'].trim() : '';
+        ceiling = v.length > 0 ? v : null;
+    } catch {
+        ceiling = null; // unreadable settings → no ceiling (fail-open)
+    }
+    _modelCeilingMemo.set(cwd, ceiling);
+    return ceiling;
+}
+/** Test seam: reset the per-cwd ceiling memo. */
+export function _resetModelCeilingMemo(): void {
+    _modelCeilingMemo.clear();
+}
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import { appendEvent } from './events_log.js';
 
@@ -1179,7 +1210,25 @@ export abstract class CliClient extends ExternalAIClient {
             // (loader preload, git *_COMMAND, NODE_OPTIONS, …) so an
             // attacker-influenced parent env cannot RCE via the spawned CLI
             // or a `git` it invokes internally.
-            env: hardenedSpawnEnv(),
+            // Role marking (token-economy-dispatch Phase 2.2): a council
+            // member CLI session is worker-class — it never talks to OUR
+            // user, never dispatches sub-workers, never runs a council.
+            // The spawned vendor CLI loads this repo's hook chains; the
+            // marker lets the dispatcher run the thinner worker chain
+            // (manifest `roles.worker.drop`; pre_tool_use guards are
+            // structurally exempt). This is the ONE in-tree spawn point
+            // that launches a separate CLI session today — Agent-tool
+            // subagents share the host process env and cannot be marked
+            // (probed live 2026-08-10; see _lib/session_role.ts).
+            // The optional model ceiling (subagents.model_ceiling, class C)
+            // rides the same spawn: a spend cap the human set per install.
+            env: hardenedSpawnEnv({
+                [SESSION_ROLE_ENV]: 'worker',
+                ...((): Record<string, string> => {
+                    const ceiling = _subagentModelCeiling();
+                    return ceiling !== null ? { CLAUDE_CODE_SUBAGENT_MODEL: ceiling } : {};
+                })(),
+            }),
         };
         if (stdinPayload !== null) {
             spawnOpts.input = stdinPayload;

package/src/scripts/ask_transport.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Rung-0.5 ask transport — one prompt, one answer, no harness, no session
+ * (road-to-token-economy-dispatch Phase 4.1).
+ *
+ * The judgment ladder's gap this closes: rung 0 routes mechanical slices to
+ * deterministic scripts; rung 1 jumps straight to a full subagent spawn
+ * whose measured median cold start is ~251k tokens (dispatch_floor,
+ * 2026-08-10). A single bounded QUESTION — a classification, a small
+ * verification, a one-file semantic lookup — needs neither a session nor
+ * tools: one completion over the reconciled council transport chain
+ * (cli → api → ∅) answers it at roughly two orders of magnitude below the
+ * spawn floor.
+ *
+ * Hard caps, per the roadmap's anti-loop discipline (Risk 2 — "rung 0.5
+ * becomes a hidden agent loop"):
+ *   - ONE completion. No retry beyond the transport chain's own cli→api
+ *     fallback semantics inside the client.
+ *   - NO tool use, NO session, NO follow-up turn.
+ *   - Honest ∅: council disabled / no member / transport failure → null
+ *     (CLI exit 3), never a fabricated answer and never an escalation this
+ *     module performs itself. Escalating to a spawn is the CALLER's
+ *     decision and is recorded as such (`escalated` on the caller's line).
+ *
+ * Telemetry: every completed ask appends ONE orchestration_record line
+ * (route_taken: "ask", spawn_count: 0, dispatch_tokens measured from the
+ * provider response) — the substitution/adoption metrics registered in
+ * `src/config/dispatch-economy-metrics.json` read these lines.
+ *
+ * Reuses, never re-implements: `council_cli.load_settings` +
+ * `build_members` (member construction, auth, transport resolution,
+ * cli-first billing classification — all unchanged), `CouncilResponse`
+ * accounting, `_lib/orchestration_record` validation.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/ask_transport "is X true in file Y?" \
+ *     [--system "<system prompt>"] [--member <name>] [--format text|json] \
+ *     [--no-record] [--dir <audit-dir>]
+ *
+ * Exit codes: 0 answer produced · 2 usage error · 3 honest-∅ (no transport).
+ */
+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 type { ExternalAIClient } from './ai_council/clients.js';
+import { buildOrchestrationLine } from './_lib/orchestration_record.js';
+import { DEFAULT_DIR } from './orchestration_record.js';
+
+export interface AskResult {
+    answer: string;
+    member: string;
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    latency_ms: number;
+}
+
+export interface AskOptions {
+    /** Injected members (tests). Default: council_cli.load_settings + build_members. */
+    members?: ExternalAIClient[];
+    /** Pick a specific member by provider/name; default: first configured. */
+    member?: string;
+    systemPrompt?: string;
+    /** Telemetry append target; null disables recording (tests / --no-record). */
+    auditDir?: string | null;
+    /** Injected clock/id (tests). */
+    now?: () => Date;
+    id?: () => string;
+}
+
+const DEFAULT_SYSTEM =
+    'You are a single-completion answer service. Answer the question directly, ' +
+    'concisely, and honestly. If the question cannot be answered without tools, ' +
+    'files, or more context, reply exactly: INSUFFICIENT_CONTEXT — one line on ' +
+    'what is missing. Never invent facts.';
+
+/** Lazily import the council CLI surface so tests with injected members never load it. */
+async function defaultMembers(): Promise<ExternalAIClient[]> {
+    const mod = await import('./council_cli.js');
+    const settings = mod.load_settings();
+    return mod.build_members(settings);
+}
+
+function recordAskLine(auditDir: string, result: AskResult | null, member: string, ts: string, id: string): void {
+    const { line, errors } = buildOrchestrationLine({
+        spawn_count: 0,
+        token_delta: 0,
+        token_delta_provenance: 'estimated',
+        route_taken: 'ask',
+        verify_mode: 'none',
+        dispatch_outcome: result === null ? 'BLOCKED' : 'DONE',
+        dispatch_tokens: result === null ? null : result.input_tokens + result.output_tokens,
+        wall_clock_ms: result === null ? 0 : Math.max(0, Math.round(result.latency_ms)),
+        agent_combo: [member || 'none'],
+        origin: 'dispatch-economy-2026',
+        ts,
+        id,
+    });
+    if (errors.length || line === null) return; // telemetry must never fail the ask
+    try {
+        const file = path.join(auditDir, `${ts.slice(0, 7)}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    } catch {
+        /* fail-open — accounting never blocks the answer */
+    }
+}
+
+/**
+ * One bounded ask. Returns the answer or `null` (honest ∅ — council
+ * disabled, no member resolves, transport failure, or provider error).
+ */
+export async function askOnce(prompt: string, opts: AskOptions = {}): Promise<AskResult | null> {
+    const trimmed = prompt.trim();
+    if (!trimmed) return null;
+
+    let members: ExternalAIClient[];
+    try {
+        members = opts.members ?? (await defaultMembers());
+    } catch {
+        return _finish(null, 'none', opts); // disabled / unreadable config → ∅
+    }
+    const memberName = (m: ExternalAIClient): string => {
+        const c = m as { name?: string; provider?: string };
+        return c.name || c.provider || 'unknown';
+    };
+    const pick =
+        opts.member !== undefined ? members.find((m) => memberName(m) === opts.member) : members[0];
+    if (pick === undefined) {
+        return _finish(null, opts.member ?? 'none', opts);
+    }
+    const provider = memberName(pick);
+
+    try {
+        const response = pick.ask(opts.systemPrompt ?? DEFAULT_SYSTEM, trimmed);
+        const r = response instanceof Promise ? await response : response;
+        if (r === null || r === undefined || (r.error !== null && r.error !== undefined && r.error !== '')) {
+            return _finish(null, provider, opts);
+        }
+        const text = (r.text ?? '').trim();
+        if (!text) return _finish(null, provider, opts);
+        return _finish(
+            {
+                answer: text,
+                member: provider,
+                model: r.model ?? 'unknown',
+                input_tokens: r.input_tokens ?? 0,
+                output_tokens: r.output_tokens ?? 0,
+                latency_ms: r.latency_ms ?? 0,
+            },
+            provider,
+            opts,
+        );
+    } catch {
+        return _finish(null, provider, opts); // ONE completion — no retry here
+    }
+}
+
+function _finish(result: AskResult | null, member: string, opts: AskOptions): AskResult | null {
+    const auditDir = opts.auditDir === undefined ? path.join(process.cwd(), DEFAULT_DIR) : opts.auditDir;
+    if (auditDir !== null) {
+        const ts = (opts.now ? opts.now() : new Date()).toISOString();
+        const id = opts.id ? opts.id() : crypto.randomUUID();
+        recordAskLine(auditDir, result, member, ts, id);
+    }
+    return result;
+}
+
+export async function main(argv: readonly string[]): Promise<number> {
+    let prompt = '';
+    let system: string | undefined;
+    let member: string | undefined;
+    let format: 'text' | 'json' = 'text';
+    let record = true;
+    let dir: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a === '--system') system = argv[++i];
+        else if (a === '--member') member = argv[++i];
+        else if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
+        else if (a === '--no-record') record = false;
+        else if (a === '--dir') dir = argv[++i];
+        else if (!a.startsWith('--')) prompt = prompt ? `${prompt} ${a}` : a;
+    }
+    if (!prompt.trim()) {
+        process.stderr.write('ask_transport: a question argument is required\n');
+        return 2;
+    }
+    const opts: AskOptions = {
+        ...(system !== undefined ? { systemPrompt: system } : {}),
+        ...(member !== undefined ? { member } : {}),
+        auditDir: record ? (dir ?? path.join(process.cwd(), DEFAULT_DIR)) : null,
+    };
+    const result = await askOnce(prompt, opts);
+    if (result === null) {
+        process.stderr.write('ask_transport: ∅ — no transport resolved or the single completion failed (no retry by design)\n');
+        return 3;
+    }
+    process.stdout.write(
+        format === 'json' ? JSON.stringify(result, null, 2) + '\n' : result.answer + '\n',
+    );
+    return 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    main(process.argv.slice(2)).then((rc) => process.exit(rc));
+}

package/src/scripts/bench_hook_injection.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Hook-injection byte bench + CI gate (road-to-token-economy-cache Phase 3.2)
+ * — the latency harness's twin for the INJECTION side.
+ *
+ * Runs every concern bound on the `claude` platform against the committed
+ * fixture envelope of each slot it is bound to (tests/fixtures/hooks/
+ * <event>.json), in-process via CONCERN_REGISTRY with the hook-stdin
+ * override, under AGENT_CONFIG_REPLAY=1 (state writes skipped). Measures the
+ * bytes of the stdout payload fields a concern injects — `reason` +
+ * `additional_context` + `context` — and gates them against
+ * `src/config/hook-token-budget.json`:
+ *
+ *   - a concern whose emission exceeds its row (or the default cap) → RED
+ *   - an EMITTING concern with no explicit row above the default is fine;
+ *     the default cap IS its row — but a breach names the missing row so
+ *     the fix is a registered decision, not a silent default bump
+ *   - per-slot SUM over all bound concerns > the slot cap → RED
+ *
+ * HONEST SCOPE, stated up front: concerns are conditional-silence by design —
+ * a generic fixture triggers few of them, so most measure 0 bytes here. The
+ * gate therefore enforces the cap on whatever DOES fire under the committed
+ * fixtures (deterministic, CI-reproducible), while the census mode
+ * (`--record`) measures REAL sessions: it appends counts-only lines
+ * ({ts, slot, concern, bytes}) to agents/runtime/state/injection-census.jsonl
+ * — the repeat-injection-census blocker's instrument. Claiming the fixture
+ * numbers are the live distribution would be the coverage inflation this
+ * repo's gate discipline refuses; the two modes exist because neither
+ * substitutes for the other.
+ *
+ * Class A: in-process, no daemon, no network. Exit 0 green · 1 breach ·
+ * 2 unusable invocation. Dead-scope guarded: zero concerns run = RED.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/bench_hook_injection [--format text|json]
+ *     [--record] [--platform claude]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { CONCERN_REGISTRY } from './hooks/concern_registry.js';
+import { setHookStdinOverride, clearHookStdinOverride } from './hooks/hook_stdin.js';
+import { _load_yaml, _resolve_concerns, EVENT_VOCABULARY, type JsonObject } from './hooks/dispatch_hook.js';
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+const REPO_ROOT = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    ...(_IN_BUNDLE ? ['..'] : ['..', '..']),
+);
+const MANIFEST = path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml');
+const BUDGET = path.join(REPO_ROOT, 'src', 'config', 'hook-token-budget.json');
+const FIXTURES = path.join(REPO_ROOT, 'tests', 'fixtures', 'hooks');
+const CENSUS_FILE = path.join('agents', 'runtime', 'state', 'injection-census.jsonl');
+
+export interface Measurement {
+    slot: string;
+    concern: string;
+    bytes: number;
+    cap: number;
+    breach: boolean;
+}
+
+interface Budget {
+    default_cap_bytes: number;
+    per_concern_caps_bytes: Record<string, number | string>;
+    per_slot_sum_caps_bytes: Record<string, number | string>;
+}
+
+function capFor(budget: Budget, concern: string): number {
+    const v = budget.per_concern_caps_bytes[concern];
+    return typeof v === 'number' ? v : budget.default_cap_bytes;
+}
+
+/** Run one registered concern in-process with the fixture envelope; return payload bytes. */
+export function runConcernOnce(
+    script: string,
+    args: readonly string[],
+    envelope: JsonObject,
+): number {
+    const main = CONCERN_REGISTRY[script];
+    if (main === undefined) return -1; // not in registry — parity tests own that failure
+    let out = '';
+    const prevWrite = process.stdout.write;
+    const prevErr = process.stderr.write;
+    const prevArgv = process.argv;
+    const prevReplay = process.env['AGENT_CONFIG_REPLAY'];
+    setHookStdinOverride(JSON.stringify(envelope));
+    process.env['AGENT_CONFIG_REPLAY'] = '1';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        out += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8');
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stdout.write;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stderr.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stderr.write;
+    try {
+        process.argv = [prevArgv[0] as string, script, ...args, '--platform', 'claude'];
+        main([...args, '--platform', 'claude']);
+    } catch {
+        /* a crashing concern injects nothing — latency/parity suites own crashes */
+    } finally {
+        process.stdout.write = prevWrite;
+        process.stderr.write = prevErr;
+        process.argv = prevArgv;
+        if (prevReplay === undefined) delete process.env['AGENT_CONFIG_REPLAY'];
+        else process.env['AGENT_CONFIG_REPLAY'] = prevReplay;
+        clearHookStdinOverride();
+    }
+    const text = out.trim();
+    if (!text) return 0;
+    try {
+        const parsed = JSON.parse(text) as Record<string, unknown>;
+        let bytes = 0;
+        for (const key of ['reason', 'additional_context', 'context']) {
+            const v = parsed[key];
+            if (typeof v === 'string') bytes += Buffer.byteLength(v, 'utf-8');
+        }
+        return bytes;
+    } catch {
+        return Buffer.byteLength(text, 'utf-8'); // non-JSON stdout counts whole
+    }
+}
+
+export function bench(opts: { platform?: string; budgetPath?: string } = {}): { measurements: Measurement[]; slotSums: Record<string, { bytes: number; cap: number; breach: boolean }>; errors: string[] } {
+    const platform = opts.platform ?? 'claude';
+    const manifest = _load_yaml(MANIFEST);
+    const budget = JSON.parse(fs.readFileSync(opts.budgetPath ?? BUDGET, 'utf8')) as Budget;
+    const measurements: Measurement[] = [];
+    const slotSums: Record<string, { bytes: number; cap: number; breach: boolean }> = {};
+    const errors: string[] = [];
+
+    for (const event of EVENT_VOCABULARY) {
+        const fixtureFile = path.join(FIXTURES, `${event}.json`);
+        if (!fs.existsSync(fixtureFile)) continue;
+        const envelope = JSON.parse(fs.readFileSync(fixtureFile, 'utf8')) as JsonObject;
+        const concerns = _resolve_concerns(manifest, platform, event);
+        let sum = 0;
+        for (const concern of concerns) {
+            const bytes = runConcernOnce(String(concern['script']), Array.isArray(concern['args']) ? concern['args'].map(String) : [], envelope);
+            if (bytes < 0) {
+                errors.push(`${event}/${String(concern['name'])}: not in CONCERN_REGISTRY`);
+                continue;
+            }
+            const cap = capFor(budget, String(concern['name']));
+            const breach = bytes > cap;
+            measurements.push({ slot: event, concern: String(concern['name']), bytes, cap, breach });
+            sum += bytes;
+        }
+        const slotCapRaw = budget.per_slot_sum_caps_bytes[event];
+        const slotCap = typeof slotCapRaw === 'number' ? slotCapRaw : Number.MAX_SAFE_INTEGER;
+        slotSums[event] = { bytes: sum, cap: slotCap, breach: sum > slotCap };
+    }
+    return { measurements, slotSums, errors };
+}
+
+export function main(argv: readonly string[]): number {
+    let format: 'text' | 'json' = 'text';
+    let record = false;
+    let platform = 'claude';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
+        else if (a === '--record') record = true;
+        else if (a === '--platform') platform = argv[++i] ?? platform;
+    }
+    let result: ReturnType<typeof bench>;
+    try {
+        result = bench({ platform });
+    } catch (err) {
+        process.stderr.write(`bench_hook_injection: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+    // Dead-scope guard: a bench that ran zero concerns proves nothing (a
+    // gate that scans nothing exits green is the recorded failure class).
+    if (result.measurements.length === 0) {
+        process.stderr.write('bench_hook_injection: DEAD SCOPE — zero concerns ran; fixtures or manifest unreadable\n');
+        return 1;
+    }
+    if (record) {
+        try {
+            const file = path.join(process.cwd(), CENSUS_FILE);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const ts = new Date().toISOString();
+            for (const m of result.measurements) {
+                if (m.bytes > 0) {
+                    fs.appendFileSync(file, JSON.stringify({ ts, slot: m.slot, concern: m.concern, bytes: m.bytes }) + '\n');
+                }
+            }
+        } catch {
+            /* census is observability — never fails the bench */
+        }
+    }
+    const breaches = result.measurements.filter((m) => m.breach);
+    const slotBreaches = Object.entries(result.slotSums).filter(([, s]) => s.breach);
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    } else {
+        const emitting = result.measurements.filter((m) => m.bytes > 0);
+        process.stdout.write(`bench_hook_injection: ${result.measurements.length} concern-slot pairs · ${emitting.length} emitted under the committed fixtures\n`);
+        for (const m of emitting) {
+            process.stdout.write(`  ${m.slot.padEnd(20)} ${m.concern.padEnd(24)} ${String(m.bytes).padStart(6)} B (cap ${m.cap})${m.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const [slot, s] of Object.entries(result.slotSums)) {
+            if (s.bytes > 0) process.stdout.write(`  slot-sum ${slot.padEnd(20)} ${String(s.bytes).padStart(6)} B (cap ${s.cap === Number.MAX_SAFE_INTEGER ? '—' : s.cap})${s.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const e of result.errors) process.stdout.write(`  warn: ${e}\n`);
+    }
+    if (breaches.length > 0 || slotBreaches.length > 0) {
+        process.stderr.write(`bench_hook_injection: ${breaches.length} concern breach(es), ${slotBreaches.length} slot-sum breach(es) — the budget row is the decision surface (src/config/hook-token-budget.json)\n`);
+        return 1;
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (_IN_BUNDLE) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main(process.argv.slice(2)));