@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_cli/doctor_execution.ts

@@ -0,0 +1,173 @@
+/**
+ * The `execution` block of `agent-config doctor --json`.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 0.3. Its own module
+ * rather than a function inside `cmd_doctor.ts` for the reason
+ * `_lib/continuation_ladder.ts` states for itself: `check_source_size_budget` is
+ * a shrink-only ratchet and `cmd_doctor.ts` sits far past the 1,500-line cap, so
+ * every line added there is an added violation. A phase pays for its additions by
+ * putting new code in a file under the cap rather than by raising a baseline.
+ *
+ * `owner_owned_check` appears here as the ladder's last RUNG rather than as a
+ * separate field, because it is not a separate switch: it is the rung that
+ * decides whether the residue is owner-owned at all, and lifting it out would
+ * suggest it can be toggled independently of the order it sits in.
+ */
+
+import {
+    executionPostureFromOverrides,
+    resolveExecutionPosture,
+} from '../../shared/missionExecution.js';
+import {
+    forgeProtectionRows,
+    protectionActions,
+    type ForgeReading,
+} from '../_lib/forge_protection.js';
+import {
+    FORGE_TOTAL_BUDGET_MS,
+    budgetOf,
+    forgeReadingFor,
+    liveForgeApi,
+    originUrl,
+    resolveForgeRepo,
+    type Runner,
+} from '../_lib/forge_reader.js';
+
+type Dict = Record<string, unknown>;
+
+/** A settings-override stream, in the shape `iter_setting_overrides` yields. */
+export type OverrideStream = Iterable<readonly [string, unknown, string]>;
+
+/**
+ * Build the payload block from a settings-override stream.
+ *
+ * A stream that throws yields the defaults rather than propagating — a
+ * diagnostic that cannot report because its own input is malformed is the one
+ * shape `doctor` must never take.
+ */
+export function executionJson(overrides: () => OverrideStream): Dict {
+    let posture;
+    try {
+        posture = executionPostureFromOverrides(overrides());
+    } catch {
+        posture = resolveExecutionPosture({});
+    }
+    return {
+        fix_loop_max: posture.fix_loop_max,
+        escalation: [...posture.escalation],
+    };
+}
+
+/**
+ * The `forge_protection` block of `doctor --json` — Phase 3.2.
+ *
+ * **THIS function does not reach the network; `doctor` now does.** The mapper
+ * stays pure and takes an INJECTED reading — a caller that queried the forge
+ * passes it, one that did not passes the all-null reading, which produces five
+ * `unread` rows that still name the call each value would come from. What
+ * changed is the caller: `forgeProtectionJsonFor` below acquires that reading,
+ * so `doctor --json` does make `gh` calls. Phase 3.2's "`doctor` does not reach
+ * the network" is SUPERSEDED, and this header said otherwise for three review
+ * rounds while the function forty lines down called it a reversal — the third
+ * copy of a refuted argument in this diff, each found by a different round.
+ * Corrected here for the reason the others were: a header is where a dead
+ * argument gets reused.
+ *
+ * That is the honest shape for *read, never guessed*: the block is always
+ * present, a value appears only when a named call produced it, and `unread` is a
+ * third state rather than a quiet `false`. A row that was never looked at and a
+ * row that was looked at and failed are different repairs.
+ *
+ * `actions` carries the human ACTION lines — the step's own words are that a
+ * missing row is a blocker entry and NOT a halt, so this reports and returns.
+ */
+export function forgeProtectionJson(reading: ForgeReading, repo: string | null = null): Dict {
+    const rows = forgeProtectionRows(reading);
+    const readFromForge = rows.some((r) => r.state !== 'unread');
+    // **The slug is reported only when something was actually read, and that
+    // invariant is structural rather than a caller's promise.** The first
+    // version reported whatever the git remote resolved to, which is a LOCAL
+    // read that succeeds with no network — so an ordinary offline run (GitHub
+    // remote present, no connectivity, no opt-out) emitted a named repository
+    // and substituted sources while every row was `unread`. That made the
+    // claim this change rests on — offline output is what Phase 3.2 shipped —
+    // false on exactly the failed-live path the council condition names. The
+    // earlier verification only ever exercised the opt-out switch and read it
+    // as offline; the two are not the same path.
+    const anonymous = repo === null || !readFromForge;
+    const name = (s: string): string =>
+        anonymous ? s : s.replace(/\{owner\}\/\{repo\}/g, () => repo);
+    return {
+        repository: readFromForge ? repo : null,
+        rows: rows.map((r) => ({
+            id: r.id,
+            state: r.state,
+            source: name(r.source),
+            detail: r.detail,
+        })),
+        actions: protectionActions(rows).map(name),
+        read_from_forge: readFromForge,
+    };
+}
+
+/**
+ * The block as `doctor` itself builds it — AC-5.
+ *
+ * Phase 3.2 left `forgeProtectionJson` with no production caller, so the
+ * command the criterion names reported five `unread` rows while the forge
+ * satisfied all five, and the rows were only ever established by a human
+ * running `gh api` and reading the mapper in a test. This is the wiring that
+ * makes the named command answer for itself.
+ *
+ * **This IS a reversal of Phase 3.2's module boundary, and the roadmap records
+ * the supersession.** An earlier draft of this comment argued the opposite —
+ * "an addition rather than a reversal" — which a 2/2 convergent council pass
+ * refuted: that note recorded two boundaries, `doctor` does not reach the
+ * network AND the reading is injected, and this reverses both. The refuted
+ * argument is corrected here rather than left standing, because a comment is
+ * what the next reader of this module finds first and is where a refuted
+ * reasoning would get reused.
+ *
+ * What survives is the AVAILABILITY property, which is narrower than the
+ * earlier claim and is the one the supersession rests on: every failure path in
+ * `forgeReadingFor` — opt-out switch, no GitHub remote, no `gh`, no
+ * credentials, timeout, unparseable payload, a throw — returns the same
+ * `UNREAD_FORGE` reading, so offline the ROWS, their `source` templates and the
+ * action lines are what Phase 3.2 printed. Not the whole document: the block
+ * gained a top-level `repository` key, which is `null` on every such path. A
+ * consumer validating `forge_protection` against a closed schema sees that one
+ * added key; "prints exactly what it printed before" was too strong and is not
+ * claimed.
+ *
+ * `process.env` and the git remote are read HERE rather than inside the reader,
+ * so the reader stays injectable and every branch above is reachable from a
+ * test without spawning anything.
+ */
+export interface ForgeDeps {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The subprocess runner for both `git` and `gh`. */
+    readonly run?: Runner;
+}
+
+export function forgeProtectionJsonFor(root: string, deps: ForgeDeps = {}): Dict {
+    // The composition root — budget, thunk, host and cwd wired together — had
+    // no seam and therefore no test, so the opt-out-before-spawn and host
+    // binding were asserted one layer down against fakes while a regression in
+    // the real wiring stayed invisible. `deps` is that seam; production passes
+    // nothing and gets `process.env` plus the real spawn.
+    const env = deps.env ?? process.env;
+    const run = deps.run;
+    const remaining = budgetOf(FORGE_TOTAL_BUDGET_MS);
+    const read = forgeReadingFor({
+        env,
+        // A thunk, so the opt-out short-circuits before `git` spawns.
+        resolveRepo: () => resolveForgeRepo(originUrl(root, run)),
+        // Built from the RESOLVED target, so `gh` is addressed at the host and
+        // directory the slug came from. The per-call ceiling is whatever is
+        // left of the whole-read budget, so a call admitted near the deadline
+        // cannot run past it.
+        apiFor: (t) => liveForgeApi(remaining, run, { host: t.host, cwd: root }),
+        remaining,
+    });
+    return forgeProtectionJson(read.reading, read.repo);
+}

package/src/scripts/_cli/doctor_network_posture.ts

@@ -0,0 +1,226 @@
+/**
+ * What this install does on the network — the two `doctor` surfaces that
+ * answer that question, in one module under the source-size cap.
+ *
+ * `road-to-host-traffic-knobs-that-ship` Phases 2.1 and 2.2. Its own module
+ * rather than a function inside `cmd_doctor.ts` for the reason
+ * `_lib/doctor_runtime_checks.ts` states for itself: that file is ~3,600 lines
+ * and `check_source_size_budget` counts every line above 1,500, so a change
+ * that adds lines there pays for them by taking lines away. Wiring the traffic
+ * section in costs two lines; `checkOfflineReadiness` moving here returns more
+ * than that, and lands beside a cohesive sibling rather than in an arbitrary
+ * bin — "can this install work with no registry" and "which host traffic is
+ * switched off" are the same question asked from two ends.
+ *
+ * `checkOfflineReadiness` is a PURE MOVE: same id, same statuses, same message
+ * and remedy strings. Its `pathExists` is `fs.statSync` in a try, matching the
+ * helper it used in `cmd_doctor.ts` — `existsSync` would differ on a path whose
+ * parent denies traversal, and this is a move, not a repair.
+ *
+ * Why the traffic section reports rather than decides: the variables below belong to the HOST, not to this package. Writing one into
+ * a consumer environment changes behaviour the consumer never asked to change,
+ * and — per the mapping measured in `docs/setup/host-traffic-environment.md` —
+ * could stop their background security updates as a side effect of a telemetry
+ * preference. So this module reads `env` and returns; it writes nothing, opens
+ * no socket, and touches no settings file. Two consecutive calls return equal
+ * payloads and leave the tree byte-identical.
+ *
+ * Why an inapplicable row is PRESENT and says so: the obvious implementation lists only the variables that resolve on the
+ * current host, which produces a short, clean section on a host that documents
+ * none of them. An operator reading that concludes their traffic is governed,
+ * when in fact the package simply had nothing to say. An omission that reads as
+ * a clean bill of health is the precise failure this surface exists to prevent,
+ * so a row that does not apply is emitted with the literal state
+ * {@link NOT_APPLICABLE} instead of being dropped.
+ *
+ * A variable that is SET on a host that does not document it still reports its
+ * value beside that state. The state says "this host is not known to read it";
+ * dropping the value as well would hide a fact the reader has.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The doctor's structured check row. Mirrors `cmd_doctor`'s internal `Dict`. */
+export interface NetworkCheck {
+    id: string;
+    status: 'ok' | 'warn' | 'fail' | 'skipped';
+    message: string;
+    remedy: string;
+    /** Structural compatibility with `cmd_doctor`'s `Dict` row type. */
+    [k: string]: string;
+}
+
+/** The literal a row carries where the host has no documented meaning for it. */
+export const NOT_APPLICABLE = 'not applicable on this host';
+
+/** The documentation surface every row points at. One copy of the mapping. */
+export const TRAFFIC_DOC = 'docs/setup/host-traffic-environment.md';
+
+/** Host id used when nothing in the environment identifies the host. */
+export const UNKNOWN_HOST = 'unknown';
+
+/**
+ * One documented host traffic variable.
+ *
+ * `hosts` lists the host ids whose shipped build was actually READ for this
+ * variable — never a host somebody expects to behave the same way. A host
+ * absent from the list gets {@link NOT_APPLICABLE}, which is the honest answer
+ * and also the safe one.
+ */
+export interface TrafficVariable {
+    readonly variable: string;
+    readonly hosts: readonly string[];
+    /** Host build and date the row was read from, e.g. `claude-code 2.1.284 · 2026-09-29`. */
+    readonly checked_against: string;
+    /**
+     * May THIS PACKAGE write the variable into the host env block?
+     *
+     * `false` on both traffic variables and it is not a policy setting — it is a
+     * structural fact: `install.ts`'s `WRITABLE_HOST_ENV` is a two-row allow
+     * table and the settings schema admits only those two keys, so neither
+     * traffic variable is expressible anywhere in the write path. Reported
+     * because a consumer reading `set` on a row deserves to know whether this
+     * package could have been the one that set it.
+     */
+    readonly writable_by_this_package: boolean;
+}
+
+/** The host build every row below was read from. One place to bump on a re-check. */
+const CHECKED = 'claude-code 2.1.284 · 2026-09-29';
+
+/**
+ * The documented set, in the order `docs/setup/host-traffic-environment.md`
+ * lists it. What each one governs — and does not — lives in that page and is
+ * deliberately not duplicated here: a second copy is a second thing to keep
+ * true, and this one would be the copy nobody re-reads.
+ */
+export const TRAFFIC_VARIABLES: readonly TrafficVariable[] = [
+    // Both traffic variables reach the host's update-disabled resolver, the
+    // blanket one as its third rung, so neither is writable by this package —
+    // owner-decided 2026-09-30.
+    { variable: 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: false },
+    { variable: 'DISABLE_AUTOUPDATER', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: false },
+    // Size caps. Neither reaches the updater resolver, and neither suppresses a
+    // call, an update check or a download.
+    { variable: 'BASH_MAX_OUTPUT_LENGTH', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: true },
+    { variable: 'MAX_MCP_OUTPUT_TOKENS', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: true },
+];
+
+/** An environment map, in the shape `process.env` has. */
+export type EnvMap = Readonly<Record<string, string | undefined>>;
+
+/** Which host this process is running under, and whether that was observed. */
+export interface TrafficHost {
+    host: string;
+    observed: boolean;
+}
+
+/**
+ * Resolve the host from the environment it exported.
+ *
+ * `observed` carries the same distinction `routing:doctor` draws for its own
+ * platform field: a host that identified itself is a fact, and the absence of
+ * any marker is NOT evidence of a different host — only evidence that nobody
+ * said. An unidentified host resolves to {@link UNKNOWN_HOST}, which documents
+ * no variable, so every row reads {@link NOT_APPLICABLE} rather than reporting
+ * against a host this code guessed at.
+ */
+export function resolveTrafficHost(env: EnvMap): TrafficHost {
+    const claude =
+        (env['CLAUDECODE'] ?? '').trim() !== '' || (env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() !== '';
+    if (claude) return { host: 'claude-code', observed: true };
+    return { host: UNKNOWN_HOST, observed: false };
+}
+
+/** One emitted row: the variable, its state on this host, and its value if set. */
+export interface TrafficRow {
+    variable: string;
+    state: string;
+    value: string | null;
+    checked_against: string;
+    writable_by_this_package: boolean;
+}
+
+/**
+ * Build one row. A variable the host does not document reports
+ * {@link NOT_APPLICABLE} whether or not it happens to be exported.
+ */
+function trafficRow(spec: TrafficVariable, env: EnvMap, host: string): TrafficRow {
+    const raw = env[spec.variable];
+    const present = raw !== undefined && raw !== '';
+    const applicable = spec.hosts.includes(host);
+    return {
+        variable: spec.variable,
+        state: applicable ? (present ? 'set' : 'unset') : NOT_APPLICABLE,
+        value: present ? String(raw) : null,
+        checked_against: spec.checked_against,
+        writable_by_this_package: spec.writable_by_this_package,
+    };
+}
+
+/**
+ * The `traffic_environment` block of `agent-config doctor --json`.
+ *
+ * Read-only by construction: the only input is the injected `env` map, and the
+ * only output is a fresh object. `hostOverride` is the test seam Phase 2.2's
+ * non-Claude fixture needs, and is never passed by the production call site.
+ *
+ * `reporting_read_only` replaced a flat `read_only: true` on 2026-09-30, and the
+ * rename is the point rather than cosmetics: this REPORT is still read-only, but
+ * the PACKAGE is no longer, so the old key had become a true statement about the
+ * wrong subject. Two of the four rows are now writable by the installer when the
+ * consumer sets a cap, and `writable_by_this_package` says which — a consumer
+ * reading `set` deserves to know whether we could have been the one who set it.
+ */
+export function trafficEnvironmentJson(
+    env: EnvMap,
+    hostOverride?: TrafficHost,
+): Record<string, unknown> {
+    const resolved = hostOverride ?? resolveTrafficHost(env);
+    return {
+        host: resolved.host,
+        host_observed: resolved.observed,
+        doc: TRAFFIC_DOC,
+        reporting_read_only: true,
+        writable_by_this_package: TRAFFIC_VARIABLES.filter((v) => v.writable_by_this_package).map(
+            (v) => v.variable,
+        ),
+        rows: TRAFFIC_VARIABLES.map((spec) => trafficRow(spec, env, resolved.host)),
+    };
+}
+
+/** `fs.statSync` in a try — the `cmd_doctor.ts` helper this move preserves. */
+function pathExists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The `offline-readiness` check — a pure move out of `cmd_doctor.ts`.
+ *
+ * `packageRoot` is passed IN rather than resolved here for the reason
+ * `doctor_runtime_checks.ts` gives for its `which` parameter: `_package_root`
+ * lives in `cmd_doctor.ts` and importing it back would make the two modules
+ * circular.
+ */
+export function checkOfflineReadiness(packageRoot: string): NetworkCheck {
+    const script = path.join(packageRoot, 'src', 'scripts', 'hermetic-install.sh');
+    if (!pathExists(script)) {
+        return {
+            id: 'offline-readiness',
+            status: 'warn',
+            message: 'src/scripts/hermetic-install.sh not found in package',
+            remedy: 'reinstall @event4u/agent-config or pull missing files',
+        };
+    }
+    return {
+        id: 'offline-readiness',
+        status: 'ok',
+        message: 'verified-offline install entrypoint present',
+        remedy: '',
+    };
+}

package/src/scripts/_lib/activation_payload.ts

@@ -0,0 +1,247 @@
+/**
+ * The runtime activation payload — what a trigger match charges per fire.
+ *
+ * The third of the three numbers `road-to-the-delivery-flip-that-tells-the-truth`
+ * Phase 3 separates. The other two already have names and a record: ADR-270
+ * calls them `source_corpus` (what the source tree could deliver) and
+ * `host_payload` (what one host actually receives at rest), and requires them to
+ * be structurally separate fields because "until the two are named apart, every
+ * ceiling discussion risks comparing unlike quantities". After a per-host
+ * projection flip a third quantity diverges from both: the bytes a delivery
+ * concern injects when a rule's trigger fires. A standing reduction published
+ * without it is a saving published without its cost.
+ *
+ * MEASURED THROUGH THE CONCERN'S OWN SELECTION, never a second model of it.
+ * `matchTierRules` + `selectForInjection` are the functions the runtime concern
+ * calls; an offline figure computed by a different matcher would price a set the
+ * concern does not deliver. That is the same single-definition rule
+ * `_lib/rule_injection.ts` was written for, applied one layer out.
+ *
+ * THE CAP IS A PARAMETER, not an import. The value lives on the concern
+ * (`hooks/rule_inject_hook.ts::CAP_BYTES`) and every caller passes it, so this
+ * module stays free of the hook's import closure and can be read from a gate, a
+ * report, or a bundled path without dragging a hook into it.
+ *
+ * Moved here from `report_standing_payload_by_host.ts`, which had the only
+ * implementation and is still its largest caller — same move, and for the same
+ * reason, as `censusRuleDir` into `_lib/carrier_divergence.ts`: a second reader
+ * needed it and a second copy is how two numbers start disagreeing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { loadRouter, matchTierRules, selectForInjection } from './rule_injection.js';
+
+/** The frozen corpus every fire figure in this module is sampled from. */
+export const ROUTING_MATRIX_REL = path.join('tests', 'eval', 'routing-matrix');
+
+/** One positive prompt of the frozen corpus, with the open files it declares. */
+export interface CorpusPrompt {
+    prompt: string;
+    openFiles: string[] | null;
+}
+
+/**
+ * Every YAML shape inside `positives:` this hand parser cannot read.
+ *
+ * `readCorpusPositives` accepts only `- prompt: "…"` with a double-quoted
+ * same-line scalar and an inline `open_files: [...]`. Any other legal shape —
+ * single quotes, an unquoted scalar, a folded block, a block sequence for
+ * `open_files` — is SILENTLY SKIPPED, which drops fires out of the distribution
+ * a budget row is derived from. A measurement that governs a budget must fail
+ * loudly on a shape it cannot read rather than under-count, so callers refuse on
+ * a non-empty result here.
+ *
+ * Reported as a shape problem rather than fixed by widening the parser: this
+ * module must not grow a second YAML implementation, and the corpus is frozen,
+ * so the honest answer to an unreadable shape is to say which file carries it.
+ */
+export function corpusShapeProblems(root: string): string[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const problems: string[] = [];
+    if (!fs.existsSync(dir)) return problems;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let lineNo = 0;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            lineNo += 1;
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            if (/^\s*-\s*prompt:/u.test(raw) && !/^\s*-\s*prompt:\s*"(.*)"\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a \`- prompt:\` this parser cannot read — only a ` +
+                        `double-quoted same-line scalar is accepted: ${JSON.stringify(raw.trim())}`,
+                );
+                continue;
+            }
+            if (/^\s*-\s*/u.test(raw) && !/^\s*-\s*(prompt|command|open_files):/u.test(raw)
+                && raw.trim() !== '-' && raw.trim() !== '') {
+                // A bare sequence item under `positives:` is a shape with no
+                // `prompt:` key on its first line — folded or nested.
+                if (!/^\s{4,}/u.test(raw)) {
+                    problems.push(
+                        `${f}:${String(lineNo)}: a positives entry whose first line carries no ` +
+                            `\`prompt:\` key: ${JSON.stringify(raw.trim())}`,
+                    );
+                }
+            }
+            if (/^\s*open_files:\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a BLOCK-sequence \`open_files:\` — only the inline ` +
+                        '`[...]` form is read, so this entry\'s files would be dropped',
+                );
+            }
+        }
+    }
+    return problems;
+}
+
+/** Every positive prompt in the frozen routing-matrix corpus. Near-misses are not fires. */
+export function readCorpusPositives(root: string): CorpusPrompt[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const out: CorpusPrompt[] = [];
+    if (!fs.existsSync(dir)) return out;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let cur: CorpusPrompt | null = null;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            const p = /^\s*-\s*prompt:\s*"(.*)"\s*$/u.exec(raw);
+            if (p !== null) {
+                cur = { prompt: p[1] as string, openFiles: null };
+                out.push(cur);
+                continue;
+            }
+            const of = /^\s*open_files:\s*\[(.*)\]\s*$/u.exec(raw);
+            if (of !== null && cur !== null) {
+                cur.openFiles = (of[1] as string)
+                    .split(',')
+                    .map((x) => x.trim().replace(/^["']|["']$/gu, ''))
+                    .filter((x) => x !== '');
+            }
+        }
+    }
+    return out;
+}
+
+/** Nearest-rank percentile over an unsorted sample. Empty sample → 0. */
+export function percentile(xs: readonly number[], q: number): number {
+    if (xs.length === 0) return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor(q * (s.length - 1)))] as number;
+}
+
+export interface SlotFireSizes {
+    readonly slot: string;
+    readonly fires: number;
+    readonly p50: number;
+    readonly p90: number;
+    readonly max: number;
+}
+
+/**
+ * Gate-open per-fire emission sizes for the delivery concern, per slot.
+ *
+ * `pre_compact` is 0 by construction rather than by measurement: that branch of
+ * `rule_inject_hook` clears the seen-set and returns allow without writing to
+ * stdout, so there is no emission to sample.
+ */
+export function slotFireSizes(root: string, capBytes: number): SlotFireSizes[] {
+    const router = loadRouter(root);
+    const prompts = readCorpusPositives(root);
+    const sample = (mode: 'prompt' | 'file'): number[] => {
+        const out: number[] = [];
+        for (const r of prompts) {
+            if (mode === 'file' && (r.openFiles === null || r.openFiles.length === 0)) continue;
+            const matches =
+                mode === 'prompt'
+                    ? matchTierRules(router, r.prompt, null, null)
+                    : matchTierRules(router, '', r.openFiles, null);
+            if (matches.length === 0) continue;
+            const sel = selectForInjection(root, matches, capBytes);
+            if (sel.selected.length > 0) out.push(sel.bytes);
+        }
+        return out;
+    };
+    const row = (slot: string, xs: number[]): SlotFireSizes => ({
+        slot,
+        fires: xs.length,
+        p50: percentile(xs, 0.5),
+        p90: percentile(xs, 0.9),
+        max: xs.length === 0 ? 0 : Math.max(...xs),
+    });
+    return [
+        row('user_prompt_submit', sample('prompt')),
+        row('pre_tool_use', sample('file')),
+        row('pre_compact', []),
+    ];
+}
+
+/** The third labelled number, or the reason it could not be taken on this tree. */
+export interface ActivationPayload {
+    /** Always the literal `activation-payload` — the label a reader and a caller key on. */
+    readonly scope: 'activation-payload';
+    /** `false` when the corpus or the router is absent; every figure is then 0. */
+    readonly measured: boolean;
+    /** Why it is unmeasured, or `null`. Never an estimate in place of a number. */
+    readonly unmeasured_reason: string | null;
+    /** The cap the sampled selection was taken at — the concern's `CAP_BYTES`. */
+    readonly cap_bytes: number;
+    readonly corpus: string;
+    readonly slots: readonly SlotFireSizes[];
+    readonly basis: string;
+}
+
+/**
+ * The runtime activation payload, or an honestly unmeasured reading.
+ *
+ * Never throws and never estimates: a missing corpus or router yields
+ * `measured: false` with the reason named, because a fabricated distribution
+ * published beside a standing saving is the exact defect this number exists to
+ * prevent.
+ */
+export function measureActivationPayload(root: string, capBytes: number): ActivationPayload {
+    const basis =
+        'Gate-open per-fire emission of the `rule-inject` concern over the frozen ' +
+        '`tests/eval/routing-matrix` positives, measured through the same ' +
+        '`matchTierRules` + `selectForInjection` the runtime concern calls, at the ' +
+        'concern\'s own CAP_BYTES. Bytes per fire, never tokens — the unit ' +
+        '`hook-token-budget.json` enforces.';
+    const empty = (reason: string): ActivationPayload => ({
+        scope: 'activation-payload',
+        measured: false,
+        unmeasured_reason: reason,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots: [],
+        basis,
+    });
+    if (!fs.existsSync(path.join(root, ROUTING_MATRIX_REL))) {
+        return empty(`the frozen corpus ${ROUTING_MATRIX_REL} is absent under ${root}`);
+    }
+    const shape = corpusShapeProblems(root);
+    if (shape.length > 0) {
+        return empty(
+            `${String(shape.length)} corpus entry/entries are in a shape the reader cannot parse, ` +
+                `so the distribution would be under-counted — first: ${shape[0] as string}`,
+        );
+    }
+    let slots: SlotFireSizes[];
+    try {
+        slots = slotFireSizes(root, capBytes);
+    } catch (err) {
+        return empty(`the fire sample could not be taken: ${(err as Error).message}`);
+    }
+    return {
+        scope: 'activation-payload',
+        measured: true,
+        unmeasured_reason: null,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots,
+        basis,
+    };
+}

package/src/scripts/_lib/agent_settings.ts

@@ -53,6 +53,7 @@ import { fileURLToPath } from 'node:url';
 
 import * as user_global_paths from './user_global_paths.js';
 import { carveOutKeys } from '../../shared/settingsCarveOut.js';
+import { applyRenamedKeys } from './settings_renamed_keys.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -956,9 +957,9 @@ export function load_agent_settings(
     // precedence here is the inverse of the server family's, so the order of
     // these three statements is the whole contract.
     const merged: SettingsDict = template_defaults(template_path ?? undefined);
-    _deep_merge(merged, user_global_filtered);
+    _deep_merge(merged, applyRenamedKeys(user_global_filtered));
     for (const p of cascade) {
-        const layer = _read_yaml(p) ?? {};
+        const layer = applyRenamedKeys(_read_yaml(p) ?? {});
         if (Object.keys(layer).length > 0) {
             _deep_merge(merged, layer);
         }
@@ -967,6 +968,7 @@ export function load_agent_settings(
     return merged;
 }
 
+
 /**
  * Settings keys this package has DELETED. A leftover value from an older
  * install is ignored — never applied by any reader — and surfaced with ONE