@event4u/agent-config 9.32.0 → 9.33.0

package/src/scripts/install.ts

@@ -975,13 +975,17 @@ function ensure_agent_settings(
     success(`${SETTINGS_FILE} created (rule_loading_tier=${profile}${suffix})`);
 }
 
-function ensure_vscode_bridge(project_root: string, package_type: string, force: boolean): void {
+function ensure_vscode_bridge(
+    project_root: string,
+    package_type: string,
+    force: boolean,
+): Record<string, unknown>[] {
     const plugin_paths: Record<string, string> = {
         npm: './node_modules/@event4u/agent-config/plugin/agent-config',
     };
     const plugin_path = plugin_paths[package_type] ?? './plugin/agent-config';
     const bridge = { 'chat.pluginLocations': { [plugin_path]: true } };
-    merge_json_file(
+    return merge_json_file(
         path.join(project_root, '.vscode', 'settings.json'),
         bridge,
         force,
@@ -1043,8 +1047,11 @@ function _remove_legacy_augment_trampolines(): void {
                 fs.unlinkSync(legacy);
                 skip(`removed legacy ~/.augment/hooks/${name}`);
             }
-        } catch {
-            /* OSError → ignore */
+        } catch (err) {
+            // A swallowed failure leaves a stale trampoline that no manifest entry
+            // covers, so uninstall cannot reach it. Non-fatal and semantics-neutral:
+            // the removal is still best-effort, it is simply no longer silent.
+            warn(`could not remove legacy ${legacy}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }
@@ -5075,8 +5082,15 @@ function _main_project_install(
     const merged_keys_by_tool: Record<string, Record<string, unknown>[]> = {};
 
     if (!opts.skip_bridges) {
-        ensure_vscode_bridge(project_root, package_type, opts.force);
-        merged_keys_by_tool['augment'] = ensure_augment_bridge(project_root, opts.force);
+        // `.vscode/settings.json` and `.augment/settings.json` are the two bridges
+        // written unconditionally, so neither belongs to a selected tool. The
+        // lockfile keys `merged_keys` by tool name (`_VALID_TOOLS`), so both are
+        // recorded under the substrate entry `augment` — see
+        // `docs/contracts/install-layout.md` § Untracked surfaces for the residual.
+        merged_keys_by_tool['augment'] = [
+            ...ensure_vscode_bridge(project_root, package_type, opts.force),
+            ...ensure_augment_bridge(project_root, opts.force),
+        ];
         if (_is_tool_enabled(tools, 'claude-code')) {
             merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
         }

package/src/scripts/lint_budget_ownership.ts

@@ -15,6 +15,16 @@
  * are allowed but not required — the top-level owner/review_by covers the
  * file.
  *
+ * ROW-LEVEL schema, opt-in (road-to-cost-parity-0-program § 1.2b/1.3): a
+ * budget file that declares a `row_schema` block additionally has every row
+ * of every top-level array checked for the fields it names — in practice
+ * `source` (so a baseline figure without a traceable origin cannot enter the
+ * file) plus the three honest-null fields. The honest-null contract is the
+ * part that binds: a row that records a `revised_from` without a
+ * `revision_evidence` pointer fails the file, because a target that moved
+ * without published evidence is precisely the drift the clause exists to
+ * refuse. Files that declare no `row_schema` are untouched by this half.
+ *
  * Exit codes: 0 clean · 1 findings · 2 internal error.
  */
 import * as fs from 'node:fs';
@@ -41,6 +51,76 @@ export function checkBudgetDoc(relPath: string, doc: Record<string, unknown>): s
     return errors;
 }
 
+const DEFAULT_ROW_FIELDS = [
+    'id',
+    'unit',
+    'baseline',
+    'source',
+    'revisable',
+    'revision_evidence',
+    'revised_from',
+];
+
+function isRow(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Row-level checks for budget files that opt in via a `row_schema` block.
+ * Returns [] for every file that does not declare one.
+ */
+export function checkBudgetRows(relPath: string, doc: Record<string, unknown>): string[] {
+    const schema = doc['row_schema'];
+    if (!isRow(schema)) return [];
+
+    const declared = schema['required_row_fields'];
+    const required =
+        Array.isArray(declared) && declared.every((f) => typeof f === 'string')
+            ? (declared as string[])
+            : DEFAULT_ROW_FIELDS;
+
+    const errors: string[] = [];
+    if (typeof doc['schema_version'] !== 'number') {
+        errors.push(`${relPath}: \`row_schema\` declared but no numeric top-level \`schema_version\``);
+    }
+    if (typeof doc['registered_at'] !== 'string' || !DATE_RE.test(doc['registered_at'])) {
+        errors.push(`${relPath}: \`row_schema\` declared but no valid top-level \`registered_at\` (YYYY-MM-DD)`);
+    }
+
+    for (const [key, value] of Object.entries(doc)) {
+        if (!Array.isArray(value)) continue;
+        value.forEach((row, index) => {
+            if (!isRow(row)) return;
+            const id = typeof row['id'] === 'string' ? row['id'] : `#${index}`;
+            const where = `${relPath}: ${key}[${index}] (${id})`;
+
+            for (const field of required) {
+                if (!(field in row)) errors.push(`${where}: missing \`${field}\``);
+            }
+            if ('source' in row) {
+                const source = row['source'];
+                if (typeof source !== 'string' || source.trim() === '') {
+                    errors.push(`${where}: empty \`source\` — a baseline figure needs a traceable origin`);
+                }
+            }
+            if ('revisable' in row && row['revisable'] !== true) {
+                errors.push(`${where}: \`revisable\` must be true — an unrevisable target is not honest-null`);
+            }
+            // The honest-null contract: a moved target must publish what moved it.
+            const revisedFrom = row['revised_from'];
+            if (revisedFrom !== null && revisedFrom !== undefined) {
+                const evidence = row['revision_evidence'];
+                if (typeof evidence !== 'string' || evidence.trim() === '') {
+                    errors.push(
+                        `${where}: sets \`revised_from\` without a \`revision_evidence\` pointer — a revision without published evidence`,
+                    );
+                }
+            }
+        });
+    }
+    return errors;
+}
+
 export function budgetFiles(dir: string = CONFIG_DIR): string[] {
     try {
         return fs
@@ -85,6 +165,7 @@ export function main(): number {
             continue;
         }
         errors.push(...checkBudgetDoc(rel, doc));
+        errors.push(...checkBudgetRows(rel, doc));
         const review = doc['review_by'];
         if (typeof review === 'string' && DATE_RE.test(review) && review < today) {
             process.stderr.write(

package/src/scripts/lint_skill_frontmatter_safety.ts

@@ -47,6 +47,19 @@ const _RE_PERMISSION_MODE = /^\s*permissionMode:\s*['"]?bypassPermissions/;
 //   Python: re.match(r"\s*allowed-tools:\s*(.+)$", text)
 const _RE_ALLOWED_TOOLS = /^\s*allowed-tools:\s*(.+)$/;
 
+// Subagent definitions grant tools under a TOP-LEVEL `tools:` key (subagent-v1,
+// `src/scripts/schemas/subagent.schema.json`), not under `execution.allowed_tools`
+// and not as `allowed-tools`. Both other spellings were already read here; this
+// one was not, and `src/subagents` was not a scan root either — so the two
+// over-broad-grant checks below had never inspected a subagent definition.
+// Top-level anchored (no leading whitespace) so a nested `tools:` inside some
+// other block cannot be mistaken for a grant; the key is unused by skills,
+// commands and domain artefacts, so the anchor costs no coverage.
+const _RE_TOOLS_KEY = /^tools:\s*(.*)$/;
+// A YAML block-sequence item under it (`  - Bash`). Inline flow (`tools: [Bash]`)
+// is captured by the key regex's own trailing group.
+const _RE_SEQ_ITEM = /^\s+-\s*(.+)$/;
+
 /** Mirror Python `str.strip("'\"")` — strip any leading/trailing `'` or `"`. */
 function _stripQuotes(s: string): string {
     let lo = 0;
@@ -151,6 +164,44 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
         }
     }
 
+    // Top-level `tools:` — the subagent-v1 grant key. Collect the inline value
+    // plus any block-sequence items that follow, and run the same two checks the
+    // other two spellings get. A subagent is never an execution skill (no
+    // `execution:` block), so the bare-Bash arm applies by construction.
+    for (let i = 0; i < body.length; i += 1) {
+        const [lineno, text] = body[i] as [number, string];
+        const key = _RE_TOOLS_KEY.exec(text);
+        if (!key) {
+            continue;
+        }
+        const grants: string[] = [];
+        const inline = (key[1] ?? '').trim();
+        if (inline !== '') {
+            grants.push(inline);
+        }
+        for (let j = i + 1; j < body.length; j += 1) {
+            const [, next] = body[j] as [number, string];
+            const item = _RE_SEQ_ITEM.exec(next);
+            if (!item) {
+                break;
+            }
+            grants.push(_stripQuotes((item[1] as string).trim()));
+        }
+        const joined = grants.join(', ');
+        if (joined !== '' && (_WILDCARD_TOOL.test(joined) || _BARE_BASH.test(joined))) {
+            out.push(
+                new sl.Finding(
+                    sf.rel,
+                    lineno,
+                    CHECK,
+                    'HIGH',
+                    'wildcard / bare-Bash tool grant (over-broad)',
+                    sf.weight,
+                ),
+            );
+        }
+    }
+
     if (Object.keys(ex).length === 0) {
         return out;
     }
@@ -258,7 +309,10 @@ export function main(argv: readonly string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const findings: sl.Finding[] = [];
-    const roots = ['src/skills', 'src/agent-src', 'src/domains'];
+    // `src/subagents` is the fourth root, added because its omission is what made
+    // the over-broad-grant checks blind: the only artefact in the tree granting a
+    // bare shell lives there, and the gate had never read it.
+    const roots = ['src/skills', 'src/agent-src', 'src/domains', 'src/subagents'];
     let scanned = 0;
     for (const sf of sl.iter_corpus(roots, ['.md'])) {
         scanned += 1;

package/src/scripts/lint_workflow_paths.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env tsx
+/**
+ * lint_workflow_paths — a workflow `paths:` filter that matches nothing runs
+ * nothing, silently, forever.
+ *
+ * ## The defect class
+ *
+ * A GitHub `on.<event>.paths` filter is a promise: "run this job when these
+ * files change". When the named tree is renamed, retired, or gitignored, the
+ * promise stops being kept and nothing says so — the workflow does not error,
+ * it simply never triggers. The job still appears in the Actions list, still
+ * shows green from its last real run, and a reader auditing the pipeline reads
+ * an intent the pipeline no longer has.
+ *
+ * That is strictly worse than a missing filter. A missing filter over-triggers
+ * and wastes minutes; a dead one under-triggers and hides regressions, and it
+ * is invisible to every other gate in this suite: `actionlint` validates the
+ * schema (a string is a valid string), and no reference checker resolves a
+ * glob against the tree.
+ *
+ * ## Measured, not assumed
+ *
+ * The census that motivated this gate found **20** dead entries across 6
+ * workflow files in four classes: a source tree retired by ADR-051, a
+ * **gitignored** projection tree (matched by no diff, ever), two paths that
+ * moved during the Python-to-TS migration, and two bare repo-root paths whose
+ * real files live under `src/`. All 20 were classified before this gate was
+ * written, and all 20 were repaired in the same change — so the gate ships
+ * **strict** over a corpus verified empty, rather than advisory over a corpus
+ * nobody looked at. A gate that reports zero findings on a corpus it has never
+ * been proven able to fail on is blind, not clean; `--self-test` is what
+ * separates those two.
+ *
+ * ## What counts as a match
+ *
+ * A glob matches when at least one **tracked** file matches it. Tracked, not
+ * on-disk, is the correct universe on purpose: a `paths:` filter is evaluated
+ * against a diff, and only tracked files appear in diffs. This is exactly why
+ * `.augment/**` is dead here despite the directory existing locally — it is
+ * gitignored, so no change to it can ever reach a pull request.
+ *
+ * Directory-shaped entries (`taskfiles/**`, or a bare `src/scripts`) match by
+ * prefix, mirroring GitHub's own semantics.
+ *
+ * ## The escape, and why it is inline
+ *
+ * A filter naming a path that does not exist *yet* — a tree an in-flight PR
+ * introduces — declares itself on the entry:
+ *
+ *     - "future/tree/ **"  # workflow-path-allow: lands in PR #1234, filter pre-staged
+ *
+ * The reason is required and must be more than one word. There is deliberately
+ * no allowlist JSON: a side-channel file is the shape that grows past twenty
+ * entries and quietly becomes the budget bypass `autonomous-execution` names.
+ */
+import * as fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REAL_REPO_ROOT = path.resolve(SCRIPTS_DIR, '..', '..');
+
+const ALLOW_RE = /#\s*workflow-path-allow:\s*(.+?)\s*$/;
+/** A reason must carry real content — two words minimum, eight characters. */
+const MIN_REASON_WORDS = 2;
+const MIN_REASON_CHARS = 8;
+
+export interface PathFinding {
+    readonly file: string;
+    readonly line: number;
+    readonly glob: string;
+    readonly why: 'no-match' | 'thin-reason';
+}
+
+/**
+ * Translate the subset of glob syntax GitHub path filters use into a RegExp.
+ *
+ * `**` crosses directory separators, `*` and `?` do not. Everything else is a
+ * literal — no brace expansion, no character classes, because GitHub does not
+ * document them for this field and guessing at unsupported syntax would make
+ * the gate disagree with the thing it is auditing.
+ */
+export function globToRegExp(glob: string): RegExp {
+    let out = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i] as string;
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                out += '.*';
+                i += 1;
+                if (glob[i + 1] === '/') {
+                    i += 1;
+                }
+            } else {
+                out += '[^/]*';
+            }
+        } else if (c === '?') {
+            out += '[^/]';
+        } else {
+            out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+
+/** Does `glob` match at least one path in `tracked`? */
+export function globMatchesAny(glob: string, tracked: readonly string[]): boolean {
+    const re = globToRegExp(glob);
+    const prefix = `${glob.replace(/\/?\*\*$/, '').replace(/\/$/, '')}/`;
+    return tracked.some((t) => re.test(t) || t === glob || t.startsWith(prefix));
+}
+
+/**
+ * Extract every `paths:` / `paths-ignore:` list entry from one workflow body.
+ *
+ * A hand-rolled scan rather than a YAML parse, deliberately: the gate must
+ * report the LINE an entry sits on so a maintainer can jump to it, and a parsed
+ * document has thrown that away. The block ends at the first non-comment,
+ * non-list line — which is how YAML block sequences end anyway.
+ */
+export function extractPathEntries(
+    body: string,
+): { line: number; glob: string; allow: string | null }[] {
+    const out: { line: number; glob: string; allow: string | null }[] = [];
+    let inBlock = false;
+    const lines = body.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        if (/^\s*paths(-ignore)?:\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        if (!inBlock) {
+            continue;
+        }
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            continue;
+        }
+        const m = line.match(/^\s*-\s*(?:'([^']*)'|"([^"]*)"|([^#\s]+))\s*(#.*)?$/);
+        if (m === null) {
+            inBlock = false;
+            continue;
+        }
+        const glob = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+        if (glob === '') {
+            continue;
+        }
+        const allowMatch = (m[4] ?? '').match(ALLOW_RE);
+        out.push({ line: i + 1, glob, allow: allowMatch ? (allowMatch[1] as string) : null });
+    }
+    return out;
+}
+
+function _trackedFiles(repoRoot: string): string[] {
+    try {
+        return execFileSync('git', ['ls-files'], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            maxBuffer: 256 * 1024 * 1024,
+        })
+            .split('\n')
+            .filter((l) => l !== '');
+    } catch {
+        return [];
+    }
+}
+
+function _reasonIsThin(reason: string): boolean {
+    return (
+        reason.trim().length < MIN_REASON_CHARS ||
+        reason.trim().split(/\s+/).filter(Boolean).length < MIN_REASON_WORDS
+    );
+}
+
+export interface ScanOptions {
+    readonly repoRoot: string;
+    readonly workflowDir: string;
+    readonly tracked: readonly string[];
+}
+
+export function scanWorkflowDir(
+    opts: ScanOptions,
+    ledger: GateLedger,
+): PathFinding[] {
+    const findings: PathFinding[] = [];
+    let files: string[] = [];
+    try {
+        files = fs
+            .readdirSync(opts.workflowDir)
+            .filter((f) => /\.ya?ml$/.test(f))
+            .sort();
+    } catch {
+        files = [];
+    }
+    ledger.plan(files);
+
+    for (const f of files) {
+        let body: string;
+        try {
+            body = fs.readFileSync(path.join(opts.workflowDir, f), 'utf-8');
+        } catch {
+            ledger.fail(f, 'unreadable');
+            continue;
+        }
+        const before = findings.length;
+        for (const entry of extractPathEntries(body)) {
+            if (entry.allow !== null) {
+                if (_reasonIsThin(entry.allow)) {
+                    findings.push({ file: f, line: entry.line, glob: entry.glob, why: 'thin-reason' });
+                }
+                continue;
+            }
+            if (!globMatchesAny(entry.glob, opts.tracked)) {
+                findings.push({ file: f, line: entry.line, glob: entry.glob, why: 'no-match' });
+            }
+        }
+        if (findings.length > before) {
+            ledger.fail(f, `${String(findings.length - before)} dead path filter(s)`);
+        } else {
+            ledger.complete(f);
+        }
+    }
+    return findings;
+}
+
+interface Args {
+    quiet: boolean;
+    selfTest: boolean;
+    root: string | null;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, selfTest: false, root: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--quiet') {
+            args.quiet = true;
+        } else if (a === '--self-test') {
+            args.selfTest = true;
+        } else if (a === '--root') {
+            args.root = argv[i + 1] ?? null;
+            i += 1;
+        }
+    }
+    return args;
+}
+
+function _selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lwp-selftest-'));
+    const mkRepo = (name: string, workflow: string): string => {
+        const repo = path.join(tmp, name);
+        fs.mkdirSync(path.join(repo, '.github', 'workflows'), { recursive: true });
+        fs.mkdirSync(path.join(repo, 'src'), { recursive: true });
+        fs.writeFileSync(path.join(repo, 'src', 'real.ts'), '// real\n');
+        execFileSync('git', ['init', '-q'], { cwd: repo });
+        execFileSync('git', ['add', '-A'], { cwd: repo });
+        fs.writeFileSync(path.join(repo, '.github', 'workflows', 'w.yml'), workflow, 'utf-8');
+        execFileSync('git', ['add', '-A'], { cwd: repo });
+        return repo;
+    };
+    const run = (repo: string): number =>
+        runGateCli(
+            REAL_REPO_ROOT,
+            'src/scripts/lint_workflow_paths.ts',
+            ['--root', repo, '--quiet'],
+            REAL_REPO_ROOT,
+        );
+
+    const HEAD = 'on:\n  pull_request:\n    paths:\n';
+    try {
+        const dead = mkRepo('dead', `${HEAD}      - "retired/tree/**"\n`);
+        const live = mkRepo('live', `${HEAD}      - "src/**"\n`);
+        const allowed = mkRepo(
+            'allowed',
+            `${HEAD}      - "future/tree/**"  # workflow-path-allow: lands in the follow-up PR\n`,
+        );
+        const thin = mkRepo('thin', `${HEAD}      - "future/tree/**"  # workflow-path-allow: soon\n`);
+        const bareDir = mkRepo('baredir', `${HEAD}      - "src"\n`);
+        return runSelfTest({
+            gate: 'lint_workflow_paths',
+            minCases: 4,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'a filter naming a retired tree is rejected',
+                    expect: 'reject',
+                    run: () => run(dead),
+                },
+                { name: 'a filter that matches tracked files passes', expect: 'accept', run: () => run(live) },
+                {
+                    name: 'a bare directory entry matches by prefix, as GitHub does',
+                    expect: 'accept',
+                    run: () => run(bareDir),
+                },
+                {
+                    name: 'a declared pre-staged filter with a real reason passes',
+                    expect: 'accept',
+                    run: () => run(allowed),
+                },
+                {
+                    name: 'a one-word reason is rejected — an unclassifiable exception is boilerplate',
+                    expect: 'reject',
+                    run: () => run(thin),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = _parseArgs(argv);
+    if (args.selfTest) {
+        return _selfTest();
+    }
+    const repoRoot = args.root !== null ? path.resolve(args.root) : REAL_REPO_ROOT;
+    const workflowDir = path.join(repoRoot, '.github', 'workflows');
+    const tracked = _trackedFiles(repoRoot);
+
+    const ledger = new GateLedger('lint_workflow_paths');
+    const findings = scanWorkflowDir({ repoRoot, workflowDir, tracked }, ledger);
+    const tally = ledger.finalize();
+
+    if (!args.quiet && findings.length > 0) {
+        process.stdout.write('\nlint_workflow_paths — path filters that can never fire:\n\n');
+        for (const f of findings) {
+            const why =
+                f.why === 'no-match'
+                    ? 'matches no tracked file'
+                    : 'workflow-path-allow reason is too thin to classify';
+            process.stdout.write(
+                `  ${f.file}:${String(f.line)}  ${f.glob}\n      ${why}\n`,
+            );
+        }
+        process.stdout.write(
+            '\n  Fix: delete the entry if the tree is retired, or repoint it if the path moved.\n' +
+                '  A filter that matches nothing does not over-trigger — it never triggers.\n',
+        );
+    }
+    if (!args.quiet) {
+        process.stdout.write(
+            `\nlint_workflow_paths: ${String(findings.length)} dead filter(s) across ` +
+                `${String(new Set(findings.map((f) => f.file)).size)} workflow file(s)\n`,
+        );
+        ledger.report();
+    }
+    reportScanned({
+        gate: 'lint_workflow_paths',
+        scanned: tally.completed + tally.failed,
+        units: 'workflow file(s)',
+        roots: ['.github/workflows'],
+    });
+    return findings.length > 0 ? 1 : 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+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;
+    }
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/preamble_byte_census.ts

@@ -557,7 +557,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return 0;
 }
 
-if (process.argv[1] !== undefined) {
+// `__AGENT_CONFIG_BUNDLE__` is defined true by every esbuild target. Inside a
+// bundle `import.meta.url` is the OUTPUT file's URL for every bundled module,
+// so the guard below would match whenever the bundle is invoked directly — and
+// importing this module from a bundled CLI entry (`cmd_doctor` bundles under
+// `build:cli-delegate`) would run the census and exit before that entry's own
+// main. Same shape as the guard in `dispatch_economy_report.ts`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _isBundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+if (!_isBundled && process.argv[1] !== undefined) {
     const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === invokedUrl) process.exit(main());
 }

package/src/scripts/report_carrier_divergence.ts

@@ -35,6 +35,16 @@
  * ignored, which is the failure `check-rule-invariants` already paid for once.
  * The point is that the condition becomes VISIBLE, not that it becomes illegal.
  *
+ * BEFORE QUOTING A COUNT FROM THIS REPORT
+ * ---------------------------------------
+ * Read `agents/settings/contexts/carrier-divergence-109-vs-24.md` first. The
+ * figure "109 divergent pairs, binding undefined" reached five independent
+ * release reviews as the tree's largest technical debt; all 109 carry
+ * byte-identical prose, and the real actionable set is the 24-pair `paths:`
+ * subset below, in the over-delivery direction. That correction had no stable
+ * surface, which is why every fresh reader re-derived the wrong number from
+ * this report's own output.
+ *
  * THE FOUR CLASSES, AND WHICH ONE A READER MUST ACT ON
  * ---------------------------------------------------
  *   body-diff        the two carriers deliver different PROSE. This is the class