@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/_lib/scan_scope.ts

@@ -23,6 +23,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import process from 'node:process';
 
 /** Raised when a gate's scope is empty — it cannot have checked anything. */
 export class DeadScopeError extends Error {
@@ -49,6 +50,24 @@ export interface ScannedOptions {
      * corpus is a real, expected state (an optional consumer surface that may
      * genuinely be absent) — never to silence a moved root. The string is the
      * reason and is printed, so it is reviewable in a diff.
+     *
+     * **Carry one of the three prefixes below.** A reason a reviewer cannot
+     * classify from the comment alone is how a justified exception becomes an
+     * allowlist of boilerplate (`road-to-gate-hardening-adoption`, AI council
+     * 2026-08-04). The prefix states which kind of emptiness is claimed:
+     *
+     * - `OPTIONAL_INPUT:` — the root belongs to a surface that may legitimately
+     *   be absent in this project (a consumer tree, an opt-in pack).
+     * - `EMPTY_VALID:` — zero units IS the success state (`check_no_todos`: an
+     *   empty tree genuinely has zero TODOs).
+     * - `WATCHLIST_DRIVEN:` — the gate has no corpus at all; it guards named
+     *   files and its scope is asserted by {@link assertWatchlistResolves}.
+     *
+     * The operational test every reason must pass, applied from the comment
+     * alone: **if this gate's scan root were deleted, would the reason still
+     * make sense?** `check_no_todos` → yes. `check_frontmatter_valid` → no; no
+     * docs to validate is blindness, not cleanliness, and that gate must
+     * reclassify rather than claim `allowEmpty`.
      */
     allowEmpty?: string;
 }
@@ -75,6 +94,31 @@ export function assertScanned(opts: ScannedOptions): void {
     );
 }
 
+/**
+ * Assert a corpus gate's scope AND publish the count it just validated.
+ *
+ * The two halves of scope hardening drifted apart in practice: 14 gates emit
+ * the machine-readable `scanned:` line the coverage guard reads, 12 assert
+ * their scope, and only 8 do both. A gate that publishes a number it never
+ * asserted can print `scanned: 0` and exit green; a gate that asserts without
+ * publishing is invisible to `check_gate_coverage`. Splitting the two also
+ * lets the published number drift from the number that was validated — the
+ * invented-count failure that is mechanically undetectable downstream.
+ *
+ * One call closes both: the emitted number is, by construction, the number the
+ * assertion just accepted. Use this for any gate that should also carry a floor
+ * in `src/config/gate-coverage.yml`; plain {@link assertScanned} stays correct
+ * for a gate that only needs its scope guarded.
+ *
+ * The line goes to stdout unconditionally — a count only visible without
+ * `--quiet` is not a count, since CI passes `--quiet` (the `lint_handoffs`
+ * lesson, preserved here so no caller has to rediscover it).
+ */
+export function reportScanned(opts: ScannedOptions, write = process.stdout.write.bind(process.stdout)): void {
+    assertScanned(opts);
+    write(`scanned: ${String(opts.scanned)}\n`);
+}
+
 export interface WatchlistOptions {
     /** Gate name, for the error message. */
     gate: string;

package/src/scripts/_lib/stdin.ts

@@ -0,0 +1,82 @@
+/**
+ * Read piped stdin completely — including payloads larger than the pipe buffer.
+ *
+ * WHY THIS EXISTS (measured 2026-08-04, PR "take the unhardened-gate count from
+ * 189 to 4"): the CI step
+ *
+ *     gh pr diff "$PR" | ./scripts-run src/scripts/check_no_new_legacy_path --stdin
+ *
+ * crashed with `EAGAIN: resource temporarily unavailable, read` at
+ * `fs.readFileSync(0)`. Not flaky — **reproducible on that PR and green on every
+ * PR before it.** A pipe holds ~64 KB; while the diff fit, the single read
+ * returned everything. That PR's diff is ~6,400 lines, so the writer is still
+ * filling the pipe when the reader arrives, and Node leaves the inherited fd 0
+ * in non-blocking mode: the read fails instead of waiting.
+ *
+ * A size-dependent gate failure is the same family of defect this suite's
+ * scan-scope work exists to kill — the gate works on the changes small enough
+ * not to matter and breaks on the ones big enough to. And the sibling
+ * workaround is worse than the crash: `check_release_pr_shape` wraps the same
+ * call in `catch { data = '' }`, so an oversized diff there reads as an empty
+ * one and the gate passes over nothing.
+ *
+ * So: retry on EAGAIN rather than swallow it, and never substitute an empty
+ * string for a failed read. A caller that gets `''` here got a genuinely empty
+ * stdin.
+ */
+import * as fs from 'node:fs';
+
+const CHUNK = 64 * 1024;
+/** Sleep between EAGAIN retries. Synchronous — these are sync CLI entry points. */
+const RETRY_SLEEP_MS = 5;
+/**
+ * Total patience before giving up, in retries. At 5 ms this is ~10 s, which is
+ * far beyond any `gh pr diff` and still terminates rather than spinning forever
+ * if fd 0 is a pipe nobody ever writes to.
+ */
+const MAX_RETRIES = 2000;
+
+/** Sleep without a busy loop, in synchronous code. */
+function _sleepSync(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Read all of fd 0 as UTF-8.
+ *
+ * @throws the underlying error for anything that is not EAGAIN, and after
+ *         {@link MAX_RETRIES} consecutive EAGAINs — a caller must not be able to
+ *         mistake a failed read for empty input.
+ */
+export function readStdinText(fd = 0): string {
+    const chunks: Buffer[] = [];
+    const buf = Buffer.alloc(CHUNK);
+    let retries = 0;
+    for (;;) {
+        let read: number;
+        try {
+            read = fs.readSync(fd, buf, 0, CHUNK, null);
+            retries = 0;
+        } catch (exc) {
+            const code = (exc as NodeJS.ErrnoException).code;
+            if (code === 'EAGAIN') {
+                retries += 1;
+                if (retries > MAX_RETRIES) {
+                    throw new Error(
+                        `readStdinText: stdin stayed unreadable across ${String(MAX_RETRIES)} retries ` +
+                            `(~${String((MAX_RETRIES * RETRY_SLEEP_MS) / 1000)}s). Refusing to report an ` +
+                            'empty read as empty input.',
+                    );
+                }
+                _sleepSync(RETRY_SLEEP_MS);
+                continue;
+            }
+            // EOF is how some platforms end a pipe read rather than returning 0.
+            if (code === 'EOF') break;
+            throw exc;
+        }
+        if (read === 0) break;
+        chunks.push(Buffer.from(buf.subarray(0, read)));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}

package/src/scripts/audit_adr_coverage.ts

@@ -22,6 +22,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/audit_adr_coverage.ts → parents[2] of the .py file is repo root.
@@ -251,14 +253,40 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
     return lines.join('\n') + '\n';
 }
 
+/**
+ * A vanished `docs/adrs/` makes every area report zero ADRs — "missing
+ * bootstrap" across the board, which both modes treat as a warning and exit 0.
+ * Exit 1 is the hard-failure code (`cmd_check`); 2 is reserved for argparse
+ * usage errors.
+ */
+function _dead_adr_scope(scanned: number): number | null {
+    try {
+        assertScanned({
+            gate: 'audit_adr_coverage',
+            scanned,
+            units: 'ADR file(s)',
+            roots: ['docs/adrs'],
+        });
+        return null;
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+}
+
 export function cmd_report(): number {
     process.stdout.write('## ADR coverage report\n');
     process.stdout.write('\n');
     process.stdout.write('| Area | Contract | ADRs | README | Status |\n');
     process.stdout.write('|---|---|---:|:---:|---|\n');
     let missingBootstrap = 0;
+    let totalAdrs = 0;
     for (const [area, meta] of Object.entries(AREAS)) {
         const [adrs] = scan_area(area);
+        totalAdrs += adrs.length;
         const readme = _exists(path.join(ADR_ROOT, area, 'README.md')) ? '✅' : '—';
         const contractPresent = _exists(_contract_path(meta));
         const status = adrs.length > 0 ? 'ok' : 'missing bootstrap';
@@ -268,6 +296,10 @@ export function cmd_report(): number {
         const contractCell = contractPresent ? meta.contract : `_${meta.contract}_ (no contract)`;
         process.stdout.write(`| \`${area}\` | ${contractCell} | ${adrs.length} | ${readme} | ${status} |\n`);
     }
+    const dead = _dead_adr_scope(totalAdrs);
+    if (dead !== null) {
+        return dead;
+    }
     process.stdout.write('\n');
     process.stdout.write(
         `BASELINE: ${Object.keys(AREAS).length} canonical areas · ${missingBootstrap} missing bootstrap ADR(s)\n`,
@@ -278,6 +310,7 @@ export function cmd_report(): number {
 export function cmd_check(): number {
     let hard = 0;
     let warn = 0;
+    let totalAdrs = 0;
     for (const dir of unlistedAreaDirs(ADR_ROOT)) {
         process.stderr.write(
             `❌ ${dir}/: area directory exists on disk but is absent from AREAS — it is not audited at all. ` +
@@ -287,6 +320,7 @@ export function cmd_check(): number {
     }
     for (const [area, meta] of Object.entries(AREAS)) {
         const [adrs, errs] = scan_area(area);
+        totalAdrs += adrs.length;
         for (const e of errs) {
             process.stderr.write(`❌ ${e}\n`);
             hard += 1;
@@ -300,6 +334,10 @@ export function cmd_check(): number {
             warn += 1;
         }
     }
+    const dead = _dead_adr_scope(totalAdrs);
+    if (dead !== null) {
+        return dead;
+    }
     process.stdout.write(`BASELINE: ${hard} hard fail(s) · ${warn} warn(s)\n`);
     return hard ? 1 : 0;
 }

package/src/scripts/audit_auto_rules.ts

@@ -28,6 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_auto_rules.py → parent.parent.parent == repo root.
@@ -404,9 +405,22 @@ function _ruleToJson(r: RuleEntry): Record<string, Json> {
 }
 
 export function main(): number {
-    if (_src_rule_paths().length === 0) {
-        process.stderr.write("❌  No source rules found under any artefact root's rules/\n");
-        return 1;
+    // The scanned unit is every source rule, not the `type: auto` subset
+    // `collect()` keeps: over a vanished rules/ tree "no auto-rules" still reads
+    // true, and the budget report would be regenerated with rule_count 0.
+    try {
+        assertScanned({
+            gate: 'audit_auto_rules',
+            scanned: _src_rule_paths().length,
+            units: 'source rule file(s)',
+            roots: artefact_roots().map((r) => `${_relPosix(r, REPO_ROOT) || '.'}/rules`),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const rules = collect();
     fs.mkdirSync(REPORT_DIR, { recursive: true });

package/src/scripts/audit_command_surface.ts

@@ -27,6 +27,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { SRC_DOMAINS } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -974,8 +975,50 @@ export function grown_packs(baseline: string, commands: Command[]): Map<string,
     return grew;
 }
 
+/**
+ * Scope guard shared by all three modes.
+ *
+ * `_rglobMdSorted` yields nothing for a root that does not exist, and every
+ * mode's verdict is a comparison over the collected commands — so a moved
+ * `src/domains` leaves the per-pack budget trivially satisfied, the overlap
+ * scan pair-less, and the surface report regenerated with `total: 0`. Only
+ * `main`'s `_exists(args.root)` guard covered that, and it does not see a
+ * present-but-command-less tree.
+ *
+ * @returns the exit code to return, or null when the scope is live.
+ */
+function _dead_scope(commands: readonly Command[], roots: readonly string[]): number | null {
+    try {
+        assertScanned({
+            gate: 'audit_command_surface',
+            scanned: commands.length,
+            units: 'command file(s)',
+            roots,
+        });
+        return null;
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 2 — this file's existing "the root is not usable" code
+            // (`error: <root> does not exist`), not 1, which means a pack
+            // exceeded its budget.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+}
+
+/** Repo-relative form of the roots `collect_all` walks, for the scope message. */
+function _command_roots_rel(): string[] {
+    return _command_roots().map((r) => _relPosix(r, REPO_ROOT));
+}
+
 export function check_new_budget(baseline: string, quiet: boolean): number {
     const commands = collect_all();
+    const dead = _dead_scope(commands, _command_roots_rel());
+    if (dead !== null) {
+        return dead;
+    }
     const audit = build_budget_audit(commands, load_size_classes());
     const byPack = new Map<string, PackEntry>();
     for (const p of audit.packs) {
@@ -1155,6 +1198,10 @@ export function main(argv: string[] | null = null): number {
 
     if (args.budget) {
         const commands = collect_all();
+        const dead = _dead_scope(commands, _command_roots_rel());
+        if (dead !== null) {
+            return dead;
+        }
         const audit = build_budget_audit(commands, load_size_classes());
         fs.writeFileSync(OUT_BUDGET_JSON, _jsonDumpsIndent2(audit), 'utf-8');
         fs.writeFileSync(OUT_BUDGET_MD, render_budget_md(audit), 'utf-8');
@@ -1177,6 +1224,10 @@ export function main(argv: string[] | null = null): number {
     }
 
     const commands = collect(args.root);
+    const dead = _dead_scope(commands, [_relPosix(args.root, REPO_ROOT)]);
+    if (dead !== null) {
+        return dead;
+    }
     const pairs = find_overlap_pairs(commands);
 
     fs.writeFileSync(

package/src/scripts/audit_initial_context.ts

@@ -32,6 +32,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import * as token_count from './_lib/token_count.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { SRC_AGENT, SRC_DOMAINS } from './_lib/agent_src.js';
 import * as projectThinRules from './project_thin_rules.js';
 
@@ -304,14 +305,30 @@ function _catalog(globPat: string): Measure {
     return m;
 }
 
+const CATALOG_GLOBS = {
+    skills_projected: '.claude/skills/*/SKILL.md',
+    skills_core_source: 'src/skills/*/SKILL.md',
+    commands_core_source: 'src/domains/*/**/command.md',
+} as const;
+
 export function description_catalog(): Record<string, Measure> {
     return {
-        skills_projected: _catalog('.claude/skills/*/SKILL.md'),
-        skills_core_source: _catalog('src/skills/*/SKILL.md'),
-        commands_core_source: _catalog('src/domains/*/**/command.md'),
+        skills_projected: _catalog(CATALOG_GLOBS.skills_projected),
+        skills_core_source: _catalog(CATALOG_GLOBS.skills_core_source),
+        commands_core_source: _catalog(CATALOG_GLOBS.commands_core_source),
     };
 }
 
+/**
+ * Files the catalogs glob — counted UNFILTERED, unlike the `entries` the
+ * measurement keeps (only those carrying a description). A vanished skills or
+ * commands tree must read as zero files, not as "nothing declares a
+ * description", which is indistinguishable from a clean tree at zero tokens.
+ */
+function catalog_file_count(): number {
+    return Object.values(CATALOG_GLOBS).reduce((n, pat) => n + _glob(pat).length, 0);
+}
+
 interface LongestRule {
     id: string;
     tokens_gpt: number;
@@ -700,6 +717,25 @@ function parse_args(argv: string[]): ParsedArgs {
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // Every budget in BUDGETS is a token count over these catalogs: an empty
+    // catalog measures zero tokens and passes every cap, so the surface has to
+    // be proved non-empty before the caps mean anything. Exit 1 is the gate's
+    // failure code (`--fail-if-over-budget`); 2 is reserved for usage errors.
+    try {
+        assertScanned({
+            gate: 'audit_initial_context',
+            scanned: catalog_file_count(),
+            units: 'catalog file(s)',
+            roots: Object.values(CATALOG_GLOBS),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const data = build();
 
     if (args.fail_if_over_budget) {

package/src/scripts/audit_mcp_tools.ts

@@ -21,6 +21,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/audit_mcp_tools.ts → parent.parent.parent of the .py file = repo root.
@@ -228,6 +230,29 @@ function parse_args(argv: string[]): ParsedArgs {
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // This generator walks no tree — it reads two named sources, and
+    // `_index_handlers` / `_index_catalog_lines` swallow a read failure as an
+    // empty index, so a moved `tools.ts` renders every tool `_stub-only_`
+    // rather than reporting that half the input vanished.
+    try {
+        assertWatchlistResolves({
+            gate: 'audit_mcp_tools',
+            candidates: [
+                path.posix.join('src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json'),
+                path.posix.join('src', 'scripts', 'mcp_server', 'tools.ts'),
+            ],
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            // 2 (the usage / could-not-run code) over 1, which this CLI
+            // documents as "the inventory drifted from the generator".
+            process.stderr.write(`❌ ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     const catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf-8')) as Catalog;
     const handlers = _index_handlers();
     const cat_lines = _index_catalog_lines();

package/src/scripts/audit_overlap.ts

@@ -28,6 +28,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_overlap.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
@@ -381,7 +383,28 @@ export function main(): number {
         return 1;
     }
     const data = JSON.parse(fs.readFileSync(AUDIT_JSON, 'utf-8')) as { rules: RuleEntry[] };
-    const pairs = analyse(data.rules);
+    // The existence check above does not cover a present-but-ruleless input:
+    // an upstream `audit_auto_rules` that itself scanned nothing yields a
+    // "0 pairs flagged" report, which is the answer a real clean run gives.
+    // The unit is the rules read, never the pairs flagged.
+    const rules = Array.isArray(data.rules) ? data.rules : [];
+    try {
+        assertScanned({
+            gate: 'audit_overlap',
+            scanned: rules.length,
+            units: 'rule(s)',
+            roots: ['agents/reports/auto-rules-audit.json'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only non-zero code — same one the missing-input
+            // path uses, and for the same reason: it could not run.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const pairs = analyse(rules);
     // Build the JSON payload with the two `round(x, 3)` fields wrapped as
     // PyFloat so 0.0 / 0.5 / 1.0 render with a trailing `.0` like json.dumps.
     const pairsJson: Json = pairs.map(

package/src/scripts/audit_skill_descriptions.ts

@@ -25,6 +25,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const MIN_LENGTH = 150;
 // Mirrors scripts/skill_linter.py `description_too_long` threshold.
@@ -386,6 +387,24 @@ export function main(argv: string[] | null = null): number {
     for (const r of roots) {
         findings.push(...collect_findings(r));
     }
+    // The roots check above only proves a `skills/` DIRECTORY exists; roots that
+    // hold no SKILL.md still render "Audited 0 skills … ✅ All descriptions look
+    // reasonable." Exit 2 is this gate's only failure code, and it already
+    // covers the sibling "no skills/ directories found" case.
+    try {
+        assertScanned({
+            gate: 'audit_skill_descriptions',
+            scanned: findings.length,
+            units: 'SKILL.md file(s)',
+            roots,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`error: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     if (args.json) {
         process.stdout.write(pyJsonDumpsIndent2(findings.map(_asdict)) + '\n');
     } else {

package/src/scripts/{verify_before_complete_hook.ts → before_complete_hook.ts}

@@ -2,9 +2,22 @@
 /**
  * Platform-agnostic hook for the `verify-before-complete` rule.
  *
- * Ported from the retired Python `src/scripts/verify_before_complete_hook.py` (ADR-200 —
- * Python→TS migration, Phase 6 / hooks). Public API mirrors the Python
- * module exactly (snake_case kept deliberately — fidelity over TS idiom).
+ * Named `before_complete_hook`, not `verify_before_complete_hook`: `verify_` is
+ * one of the gate-shaped prefixes in `_lib/gate_population.ts`, so the old name
+ * put an observability hook into the gate population, where the scan-scope
+ * ratchet counted it as a gate that cannot assert a scan scope (it scans no
+ * corpus — its only inputs are its stdin envelope and the state file it writes).
+ * AI council 2026-08-05 rejected the alternative of excluding `_hook.ts` in the
+ * population filter as population-shrinking: `.d.ts` / `.test.ts` are excluded
+ * because the language and the test runner make them structurally
+ * non-executable, whereas "a hook never blocks" is an operational property you
+ * can only learn by reading `hook_manifest.yaml` — and manifest-driven
+ * classification was already rejected once. Renaming keeps classification
+ * structural and needs no exclusion rule.
+ *
+ * Ported from the retired Python `src/scripts/verify_before_complete_hook.py`
+ * (ADR-200 — Python→TS migration, Phase 6 / hooks). Public API mirrors the
+ * Python module exactly (snake_case kept deliberately — fidelity over TS idiom).
  *
  * Records observable evidence that a verification command (tests, quality
  * tools, build) ran. The rule body cites the resulting state file as the

package/src/scripts/bench_ab_task_runner.ts

@@ -194,6 +194,12 @@ interface RunResult {
     tokens?: number;
     /** Empty object `{}` on dry-run (key absent in Python); breakdown otherwise. */
     tokens_breakdown?: TokensBreakdown | Record<string, never>;
+    /**
+     * Model ids the envelope actually billed (`modelUsage` keys) — the only
+     * place a run states which model answered it. Empty when the envelope
+     * omits the block. Feeds the delta-#3 model-id check.
+     */
+    models_seen?: string[];
     errored?: boolean;
     num_turns?: number;
     subtype?: string;
@@ -295,6 +301,7 @@ export function run_live(
     const returncode = result.status ?? -1;
     let transcript: string = stdout;
     let tokens = 0;
+    let modelsSeen: string[] = [];
     let isError = false;
     let errReason = 'ok';
     let numTurns = 0;
@@ -337,6 +344,16 @@ export function run_live(
             breakdown.output_tokens +
             breakdown.cache_read_input_tokens +
             breakdown.cache_creation_input_tokens;
+        // `modelUsage` is keyed by the model ids the run actually billed. Record
+        // them unconditionally: the delta-#3 check needs the id even on a run
+        // whose top-level `usage` was fine, and a mid-sweep model swap is exactly
+        // the case where the totals look ordinary.
+        modelsSeen = Object.keys(
+            (_isPlainObj(obj['modelUsage']) ? (obj['modelUsage'] as Record<string, unknown>) : {}) as Record<
+                string,
+                unknown
+            >,
+        );
         // The top-level `usage` block is zeroed on a budget-capped / errored run
         // (and unreliable even on some completions). `modelUsage` carries the
         // authoritative per-model counts — sum it as the fallback so token deltas
@@ -387,6 +404,7 @@ export function run_live(
         wall_time_seconds: _pyRound(duration, 3),
         tokens,
         tokens_breakdown: breakdown,
+        models_seen: modelsSeen,
         errored: isError || returncode !== 0,
         num_turns: numTurns,
         subtype,