@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/generate_reference_toc.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env tsx
+/**
+ * Heading index for long skill reference files
+ * (road-to-steps-the-skill-cannot-skip 1.5).
+ *
+ * Every `src/skills/<skill>/references/**\/*.md` longer than MIN_LINES gets a
+ * generated list of its `##` headings right under its title, so a reader who
+ * opens the file sees where to go before line 30. The block is regenerated, never
+ * written by hand: `task sync` runs this in write mode, and `--check` reports
+ * drift without failing — the index is a reading aid, not a contract.
+ *
+ * Exit codes: 0 always, except 2 for an unknown flag.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const MIN_LINES = 100;
+
+const START = '<!-- reference-toc:start (generated by generate_reference_toc — do not edit) -->';
+const END = '<!-- reference-toc:end -->';
+const BLOCK = /\n?<!-- reference-toc:start[^\n]*-->\n[\s\S]*?<!-- reference-toc:end -->\n/;
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** GitHub's heading anchor: inline markup dropped, lower-cased, punctuation removed. */
+function anchor(text: string): string {
+    return text
+        .replace(/`/g, '')
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+
+/** `##` headings outside fenced blocks, in order. */
+function headings(source: string): string[] {
+    const out: string[] = [];
+    let fence: string | null = null;
+    for (const line of source.split('\n')) {
+        const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+        if (fence !== null) {
+            if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+            continue;
+        }
+        if (marker !== undefined) {
+            fence = marker;
+            continue;
+        }
+        const h = /^## +(.+?)\s*#*\s*$/.exec(line);
+        if (h !== null) out.push(h[1] as string);
+    }
+    return out;
+}
+
+/** The file with its index block regenerated, removed, or untouched. */
+export function withToc(source: string): string {
+    const bare = source.replace(BLOCK, '');
+    const titles = headings(bare);
+    if (bare.split('\n').length <= MIN_LINES || titles.length < 2) return bare;
+    const seen = new Map<string, number>();
+    const entries = titles.map((t) => {
+        const base = anchor(t);
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        const label = t.replace(/`/g, '').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+        return `- [${label}](#${n === 0 ? base : `${base}-${n}`})`;
+    });
+    const block = `${START}\n**Contents**\n\n${entries.join('\n')}\n${END}\n`;
+    const lines = bare.split('\n');
+    const title = lines.findIndex((l) => /^# /.test(l));
+    if (title === -1 || title > 10) return `${block}\n${bare}`;
+    const before = lines.slice(0, title + 1).join('\n');
+    const after = lines.slice(title + 1).join('\n');
+    return `${before}\n\n${block}${after.startsWith('\n') ? after : `\n${after}`}`;
+}
+
+function referenceFiles(root: string): string[] {
+    const skills = path.join(root, 'src', 'skills');
+    if (!fs.existsSync(skills)) return [];
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) walk(full);
+            else if (e.name.endsWith('.md')) out.push(full);
+        }
+    };
+    for (const skill of fs.readdirSync(skills).sort()) {
+        const refs = path.join(skills, skill, 'references');
+        if (fs.existsSync(refs)) walk(refs);
+    }
+    return out.sort();
+}
+
+export function main(argv: string[] = process.argv.slice(2), root: string = REPO_ROOT): number {
+    const unknown = argv.filter((a) => a !== '--check');
+    if (unknown.length > 0) {
+        process.stderr.write(`generate_reference_toc: unknown argument ${unknown[0]}\n`);
+        return 2;
+    }
+    const check = argv.includes('--check');
+    const files = referenceFiles(root);
+    const drift: string[] = [];
+    for (const file of files) {
+        const source = fs.readFileSync(file, 'utf-8');
+        const next = withToc(source);
+        if (next === source) continue;
+        drift.push(path.relative(root, file).split(path.sep).join('/'));
+        if (!check) fs.writeFileSync(file, next, 'utf-8');
+    }
+    process.stdout.write(`scanned: ${files.length}\n`);
+    if (check && drift.length > 0) {
+        process.stdout.write(
+            `⚠️  generate_reference_toc: ${drift.length} reference file(s) carry a stale heading index ` +
+                '(warn-only — `task sync` regenerates it):\n',
+        );
+        for (const d of drift) process.stdout.write(`  ${d}\n`);
+        return 0;
+    }
+    process.stdout.write(
+        check
+            ? `✅  generate_reference_toc: ${files.length} reference file(s), every heading index current.\n`
+            : `✅  generate_reference_toc: ${drift.length} of ${files.length} reference file(s) rewritten.\n`,
+    );
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/generate_subagent_floor.ts

@@ -107,6 +107,16 @@ export function prompt_files(dir: string): string[] {
         .map((f) => path.join(dir, f));
 }
 
+/**
+ * Package worker definitions that carry the floor in their own body
+ * (`ac-worker`, `ac-researcher`). Only a definition that already holds a span
+ * is in scope: `apply_span`'s append path targets a prompt template, and on a
+ * definition it would land inside the frontmatter.
+ */
+export function definitions_with_span(dir: string = path.join(REPO_ROOT, 'src', 'subagents')): string[] {
+    return prompt_files(dir).filter((f) => fs.readFileSync(f, 'utf-8').includes(BEGIN));
+}
+
 /**
  * Replace an existing span, or append one after the mode-reference line.
  *
@@ -130,7 +140,7 @@ export function apply_span(text: string, span: string): string {
 
 function main(argv: string[]): number {
     const check = argv.includes('--check');
-    const files = PROMPT_DIRS.flatMap((d) => prompt_files(d));
+    const files = [...PROMPT_DIRS.flatMap((d) => prompt_files(d)), ...definitions_with_span()];
     if (files.length === 0) {
         process.stderr.write(
             `❌  generate_subagent_floor: no prompt templates under ${PROMPT_DIRS.join(' or ')}\n`,

package/src/scripts/handoff_context_hook.ts

@@ -427,6 +427,35 @@ export function recycleEnvelopeGate(source: string): SourceGate {
     return _gate(source, RECYCLE_INJECTING_SOURCES);
 }
 
+/**
+ * The procedure cursor's position after a compaction, read from the state file
+ * on disk and phrased as a record, never as an instruction: a resumed step that
+ * was already done must not be read as one to do again. No procedure state file,
+ * no line.
+ */
+export function procedurePositionLine(root: string): string | null {
+    try {
+        const file = path.join(root, '.work-state.json');
+        if (fs.statSync(file).size > 1024 * 1024) return null;
+        const input = (JSON.parse(fs.readFileSync(file, 'utf-8')) as { input?: { kind?: unknown; data?: unknown } }).input;
+        if (input?.kind !== 'procedure' || typeof input.data !== 'object' || input.data === null) return null;
+        const d = input.data as { skill?: unknown; started_head?: unknown; current?: unknown; order?: unknown; steps?: unknown };
+        // A committed state file is repo content, re-injected at every compaction:
+        // only id-shaped strings reach the context, never free text.
+        const id = /^[a-z0-9._-]{1,64}$/;
+        if (typeof d.skill !== 'string' || !Array.isArray(d.order) || typeof d.current !== 'string') return null;
+        if (!id.test(d.skill) || !id.test(d.current)) return null;
+        const k = d.order.indexOf(d.current) + 1;
+        if (k === 0) return null;
+        const rec = (d.steps as Record<string, { status?: unknown }> | undefined)?.[d.current];
+        const exit = rec?.status === 'ok' || rec?.status === 'stale' ? rec.status : 'partial';
+        const head = typeof d.started_head === 'string' && /^[0-9a-f]{4,64}$/.test(d.started_head) ? d.started_head.slice(0, 12) : 'none';
+        return `procedure ${d.skill}@${head} · step ${String(k)} of ${String(d.order.length)} (${d.current}) · last exit ${exit}`;
+    } catch {
+        return null;
+    }
+}
+
 // ---------------------------------------------------------------------
 // CLI — dispatcher concern entry point
 // ---------------------------------------------------------------------
@@ -492,6 +521,11 @@ export function main(): number {
                 blocks.push(handoff.context);
                 reasons.push(handoff.reason);
             }
+            const position = source === 'compact' ? procedurePositionLine(root) : null;
+            if (position !== null) {
+                blocks.push(position);
+                reasons.push('procedure position');
+            }
             if (blocks.length > 0) {
                 process.stdout.write(
                     JSON.stringify({

package/src/scripts/hook_carrier_census.ts

@@ -0,0 +1,263 @@
+/**
+ * hook_carrier_census — where the claude hook carrier actually reaches a
+ * dispatcher, per install path (road-to-a-hook-carrier-that-is-never-silent 0.1).
+ *
+ * For each install path — a source checkout, `npm i -g`, `npx` — a scratch
+ * `HOME` is laid out in that path's shape, and the manifest-derived
+ * `SessionStart` command is run under `/bin/sh` twice: under the launcher's
+ * `PATH` (node plus whatever bin directory the install path puts on it) and
+ * under `PATH=/usr/bin:/bin`, from a project directory with no local install.
+ * Each run is made once without a staged runtime, the shape every machine had
+ * before Phase 1, and once with one.
+ *
+ * The package in each fixture carries a stand-in dispatcher that only says it
+ * was reached: what is under test is the command's resolution, not the bundle.
+ * The `npx` package root is the layout npm 11 was observed to use; the report
+ * states how that observation was made.
+ *
+ * Deterministic: no scratch path, date or host value reaches the report, so two
+ * runs at one commit are byte-equal (`--check` compares).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/hook_carrier_census            # print
+ *   ./scripts-run src/scripts/hook_carrier_census --write    # write the report
+ *   ./scripts-run src/scripts/hook_carrier_census --check    # exit 1 on drift
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { stageRuntime } from '../install/stagedRuntime.js';
+import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
+import { generatedByQuote } from './_lib/generated_by.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const REPORT_REL = 'agents/evidence/analysis/hook-carrier-census-2026-10.md';
+
+/** Observed 2026-10-18 with npm 11.19.0: `npx -y --cache <c> @event4u/agent-config`. */
+export const NPX_PACKAGE_REL = '_npx/4297e1a784ff86d4/node_modules/@event4u/agent-config';
+
+const STAND_IN =
+    "if (process.argv.includes('--read-exit')) process.stderr.write('dispatch_hook: --read-exit ok\\n');\n";
+
+interface InstallPath {
+    readonly id: 'checkout' | 'npm-global' | 'npx';
+    /** Package root relative to the scratch HOME, as a reader would name it. */
+    readonly rootLabel: string;
+    readonly rootRel: string;
+    readonly inCache: boolean;
+    /** A bin directory this path puts on the launcher PATH, relative to HOME. */
+    readonly binRel: string | null;
+}
+
+export const INSTALL_PATHS: readonly InstallPath[] = [
+    { id: 'checkout', rootLabel: '<checkout>', rootRel: 'checkout', inCache: false, binRel: null },
+    {
+        id: 'npm-global',
+        rootLabel: '<prefix>/lib/node_modules/@event4u/agent-config',
+        rootRel: 'prefix/lib/node_modules/@event4u/agent-config',
+        inCache: false,
+        binRel: 'prefix/bin',
+    },
+    {
+        id: 'npx',
+        rootLabel: `<npm cache>/${NPX_PACKAGE_REL}`,
+        rootRel: `npm-cache/${NPX_PACKAGE_REL}`,
+        inCache: true,
+        binRel: null,
+    },
+];
+
+function write(p: string, body: string, mode?: number): void {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, body);
+    if (mode !== undefined) fs.chmodSync(p, mode);
+}
+
+function layOut(home: string, ip: InstallPath): string {
+    const root = path.join(home, ip.rootRel);
+    write(path.join(root, 'package.json'), JSON.stringify({ name: '@event4u/agent-config', version: '0.0.0' }));
+    write(path.join(root, 'src', 'scripts', 'hook_manifest.yaml'), 'schema_version: 1\n');
+    write(path.join(root, 'dist', 'agent-src', 'rules', 'example.md'), '# example\n');
+    write(path.join(root, 'dist', 'hooks', 'dispatch.js'), STAND_IN);
+    if (ip.binRel !== null) {
+        write(
+            path.join(home, ip.binRel, 'agent-config'),
+            `#!/bin/sh\nshift\nexec "${process.execPath}" "${path.join(root, 'dist', 'hooks', 'dispatch.js')}" "$@"\n`,
+            0o755,
+        );
+    }
+    return root;
+}
+
+function reaches(command: string, home: string, pathValue: string): boolean {
+    const project = path.join(home, 'empty-project');
+    fs.mkdirSync(project, { recursive: true });
+    const probe = command.replace(/--min-version (\d+)/g, '--min-version $1 --read-exit');
+    const res = spawnSync('/bin/sh', ['-c', probe], {
+        cwd: project,
+        input: '{}',
+        encoding: 'utf-8',
+        env: {
+            PATH: pathValue,
+            HOME: home,
+            EVENT4U_CONFIG_HOME: path.join(home, '.event4u', 'agent-config'),
+            CLAUDE_PROJECT_DIR: project,
+            AC_HOOK_PROBE: '1',
+        },
+        timeout: 30000,
+    });
+    return typeof res.stderr === 'string' && res.stderr.includes('--read-exit ok');
+}
+
+interface Row {
+    readonly ip: InstallPath;
+    readonly staged: boolean;
+    readonly launcher: boolean;
+    readonly stripped: boolean;
+    readonly pointerRoot: string;
+}
+
+export function runCensus(): Row[] {
+    const command = build_claude_hook_matrix(path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml'))['SessionStart'];
+    if (command === undefined) throw new Error('no SessionStart command in the matrix');
+    const rows: Row[] = [];
+    for (const ip of INSTALL_PATHS) {
+        for (const staged of [false, true]) {
+            const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-carrier-census-'));
+            try {
+                const root = layOut(home, ip);
+                const runtime = path.join(home, '.event4u', 'agent-config', 'runtime');
+                if (staged) stageRuntime({ packageRoot: root, runtimeRoot: runtime, nodePath: process.execPath });
+                const launcherPath = [path.dirname(process.execPath), ...(ip.binRel ? [path.join(home, ip.binRel)] : []), '/usr/bin', '/bin'].join(':');
+                rows.push({
+                    ip,
+                    staged,
+                    launcher: reaches(command, home, launcherPath),
+                    stripped: reaches(command, home, '/usr/bin:/bin'),
+                    pointerRoot: staged
+                        ? `~/.event4u/agent-config/runtime/current/dist/agent-src/rules/`
+                        : `${ip.rootLabel}/dist/agent-src/rules/`,
+                });
+            } finally {
+                fs.rmSync(home, { recursive: true, force: true });
+            }
+        }
+    }
+    return rows;
+}
+
+function tail(command: string): string {
+    return (command.split(';').pop() ?? '').trim().split(/\s+/).slice(0, 2).join(' ');
+}
+
+function yn(b: boolean): string {
+    return b ? 'reached' : '**not reached**';
+}
+
+/**
+ * The Reading's first two bullets, checked against the cells. They are prose,
+ * and `--check` compares the file only against a regenerated copy carrying the
+ * same prose, so a flipped cell would otherwise leave a report that contradicts
+ * its own table.
+ */
+export function readingContradictions(rows: readonly Row[]): string[] {
+    const out: string[] = [];
+    for (const r of rows) {
+        const where = `${r.ip.id} (${r.staged ? 'staged' : 'unstaged'})`;
+        if (r.staged && !(r.launcher && r.stripped)) out.push(`${where}: staged, yet a PATH did not reach the dispatcher`);
+        if (!r.staged && r.stripped) out.push(`${where}: unstaged, yet the stripped PATH reached the dispatcher`);
+        if (!r.staged && r.launcher !== (r.ip.id === 'npm-global')) out.push(`${where}: launcher PATH ${yn(r.launcher)}`);
+    }
+    return out;
+}
+
+export function renderReport(rows: readonly Row[]): string {
+    const contradictions = readingContradictions(rows);
+    if (contradictions.length > 0) {
+        throw new Error(`hook_carrier_census: the Reading no longer matches the cells — ${contradictions.join('; ')}`);
+    }
+    const command = build_claude_hook_matrix(path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml'))['SessionStart'] ?? '';
+    const lines = [
+        '<!-- evidence-type: analysis -->',
+        '',
+        '# The claude hook carrier, per install path',
+        '',
+        generatedByQuote('hook_carrier_census', 'Evidence for'),
+        '> `road-to-a-hook-carrier-that-is-never-silent` step 0.1. Regenerate with',
+        '> `--write`; `--check` fails when this file and a fresh run disagree.',
+        '',
+        '## Method',
+        '',
+        'Each install path is laid out under a scratch `HOME` and the manifest-derived',
+        '`SessionStart` command is run under `/bin/sh` from a project directory with no',
+        'local install. "Launcher PATH" is node plus the bin directory the path puts on',
+        '`PATH`; "stripped" is `PATH=/usr/bin:/bin`. The package carries a stand-in',
+        'dispatcher that only reports being reached, so the cells measure the command\'s',
+        'resolution and nothing the bundle does. "Unstaged" is a machine without',
+        '`~/.event4u/agent-config/runtime/`, which is every machine installed before',
+        'Phase 1; "staged" is one an install of this tree has staged.',
+        '',
+        `Command tail (the statement after the last \`;\`, first two words): \`${tail(command)}\`.`,
+        '',
+        '## Cells',
+        '',
+        '| Install path | Package root | Under a package-manager cache | Runtime | Launcher PATH | Stripped PATH | Stub pointer root |',
+        '|---|---|---|---|---|---|---|',
+    ];
+    for (const r of rows) {
+        lines.push(
+            `| ${r.ip.id} | \`${r.ip.rootLabel}\` | ${r.ip.inCache ? 'yes' : 'no'} | ${r.staged ? 'staged' : 'unstaged'} | ` +
+                `${yn(r.launcher)} | ${yn(r.stripped)} | \`${r.pointerRoot}\` |`,
+        );
+    }
+    lines.push(
+        '',
+        '## Reading',
+        '',
+        '- Unstaged, only `npm i -g` reaches a dispatcher, and only while its bin',
+        '  directory is on the launcher `PATH`; every unstaged stripped-PATH cell is',
+        '  silent. That is the defect the roadmap names: on a checkout or `npx` install',
+        '  no hook concern runs, the three `fail_closed` guards included.',
+        '- Staged, every cell reaches the dispatcher, because the command runs the',
+        '  staged bundle with the node recorded at install before it consults `PATH`.',
+        '- The `npx` root sits under the npm cache. Its layout was observed on',
+        '  2026-10-18 with npm 11.19.0 by `npx -y --cache <scratch> @event4u/agent-config',
+        '  --version` with the global prefix pointed at an empty directory: the package',
+        `  landed at \`<cache>/${NPX_PACKAGE_REL}\`. With a global install on`,
+        '  `PATH` the same command ran the global binary and placed nothing in the cache',
+        '  at all, so an `npx` row on such a machine is really the `npm-global` row.',
+        '- Unstaged stub pointers are rooted at the package root, which for `npx` is',
+        '  that cache; staged pointers resolve under the machine root.',
+        '',
+    );
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[]): number {
+    const report = renderReport(runCensus());
+    const target = path.join(REPO_ROOT, REPORT_REL);
+    if (argv.includes('--check')) {
+        const onDisk = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+        if (onDisk !== report) {
+            process.stderr.write(`hook_carrier_census: ${REPORT_REL} is stale — re-run with --write\n`);
+            return 1;
+        }
+        process.stdout.write(`hook_carrier_census: ${REPORT_REL} is current\n`);
+        return 0;
+    }
+    if (argv.includes('--write')) {
+        fs.writeFileSync(target, report);
+        process.stdout.write(`hook_carrier_census: wrote ${REPORT_REL}\n`);
+        return 0;
+    }
+    process.stdout.write(report);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/src/scripts/hook_chunks.d.mts

@@ -0,0 +1,12 @@
+/** Type declarations for hook_chunks.mjs (the one definition of the conditional hook chunks). */
+export declare const HOOK_CHUNKS: ReadonlyArray<{ readonly entry: string; readonly outfile: string; readonly external?: readonly string[] }>;
+export declare const CHUNK_OPTIONS: Readonly<{
+    bundle: true;
+    platform: 'node';
+    format: 'cjs';
+    target: string;
+    define: Readonly<Record<string, string>>;
+    banner: Readonly<{ js: string }>;
+}>;
+export declare function buildChunk(root: string, entry: string, outfile: string): void;
+export declare function main(args?: readonly string[]): number;

package/src/scripts/hook_chunks.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * hook_chunks.mjs — the one definition of the conditional hook chunks, and
+ * their build.
+ *
+ * A chunk is code the dispatch bundle loads only when a caller needs it
+ * (`hooks/svg_rules_loader.ts`, `hooks/egress_engine_loader.ts`). Its entry,
+ * its output and its esbuild options live here and nowhere else:
+ * `npm run build:hook-chunks` runs this file, and the bundle-composition gate
+ * imports it to build the same chunk to a throwaway path and measure it. A
+ * second description of the build — a parsed shell script — is how a measured
+ * build and a shipped build come apart, which is the reason this is a module.
+ *
+ * Plain `.mjs` like `write_bundle_digest.mjs`: it runs in `build:hooks` before
+ * anything is compiled.
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { argv, exit } from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { buildSync } from 'esbuild';
+
+/** Every chunk: its entry and where `build:hook-chunks` writes it, repo-relative. */
+export const HOOK_CHUNKS = Object.freeze([
+    Object.freeze({ entry: 'src/scripts/_lib/svg_rules.ts', outfile: 'dist/hooks/svg_rules.chunk.cjs' }),
+    Object.freeze({ entry: 'src/scripts/_lib/egress_engine.ts', outfile: 'dist/hooks/egress_engine.chunk.cjs' }),
+    // `yaml` stays external here, alone among the chunks. Inlined it is
+    // 258 KB of the 472 KB chunk — a second copy of a parser the dispatch
+    // bundle already carries, shipped so one `session_start` concern can
+    // read a settings file. It is a declared runtime dependency of this
+    // package, so a CJS `require('yaml')` from `dist/hooks/` resolves it in
+    // any install; if it ever does not, `loadLazyConcern` returns null and
+    // the dispatcher falls back to the spawn path, which is slower and
+    // still correct.
+    Object.freeze({
+        entry: 'src/scripts/chat_history.ts',
+        outfile: 'dist/hooks/chat_history.chunk.cjs',
+        external: Object.freeze(['yaml']),
+    }),
+]);
+
+/**
+ * The esbuild options every chunk is built with.
+ *
+ * `__AGENT_CONFIG_BUNDLE__` is defined here for the same reason `build:hooks`
+ * defines it: a chunk carrying a concern carries that concern's CLI entry
+ * guard, and without the define the guard falls through to comparing
+ * `import.meta.url` against `argv[1]` inside a bundle where every module
+ * shares one url. Defined, the guard is statically false and the concern never
+ * auto-runs on require.
+ *
+ * `import.meta` is empty under the `cjs` format, so esbuild would leave
+ * `createRequire(import.meta.url)` — which `_lib/agent_settings.ts` runs at
+ * module scope — calling `createRequire(undefined)` and throwing on the first
+ * require of the chunk. The banner rebuilds the one shape that is actually
+ * used, from `__filename`, and the define points `import.meta` at it. The
+ * resolved url is the chunk's own path, so `resolvePackageRoot` walks up to the
+ * same package root it reaches from `dist/hooks/dispatch.js`.
+ */
+export const CHUNK_OPTIONS = Object.freeze({
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    target: 'node20',
+    define: {
+        __AGENT_CONFIG_BUNDLE__: 'true',
+        'import.meta.url': '__acChunkMetaUrl',
+        'import.meta': '__acChunkMeta',
+    },
+    banner: {
+        js:
+            "const __acChunkMetaUrl = require('node:url').pathToFileURL(__filename).href; " +
+            'const __acChunkMeta = { url: __acChunkMetaUrl, dirname: __dirname, filename: __filename };',
+    },
+});
+
+/**
+ * Build one chunk from `root` to `outfile` (absolute). Throws when esbuild
+ * reports an error.
+ *
+ * Externals are looked up from {@link HOOK_CHUNKS} by entry rather than passed
+ * in, so the gate that measures a chunk and the script that ships it cannot
+ * build it with different options — the reason this module exists at all.
+ */
+export function buildChunk(root, entry, outfile) {
+    const declared = HOOK_CHUNKS.find((c) => c.entry === entry);
+    const external = declared?.external ?? [];
+    const result = buildSync({ ...CHUNK_OPTIONS, external: [...external], absWorkingDir: root, entryPoints: [entry], outfile, logLevel: 'error' });
+    if (result.errors.length > 0) throw new Error(`esbuild reported ${String(result.errors.length)} error(s) building ${entry}`);
+}
+
+/**
+ * Build every chunk and write its digest sidecar. `--out-dir DIR` writes the
+ * outputs under DIR instead of the repository, for a test that must not touch
+ * the live `dist/`.
+ */
+export function main(args = argv.slice(2)) {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const at = args.indexOf('--out-dir');
+    const outRoot = at >= 0 && args[at + 1] !== undefined ? path.resolve(args[at + 1]) : root;
+    const digest = path.join(root, 'src', 'scripts', 'write_bundle_digest.mjs');
+    for (const chunk of HOOK_CHUNKS) {
+        const out = path.join(outRoot, chunk.outfile);
+        buildChunk(root, chunk.entry, out);
+        const r = spawnSync(process.execPath, [digest, out], { stdio: 'inherit' });
+        if (r.status !== 0) return r.status ?? 1;
+    }
+    return 0;
+}
+
+if (argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(argv[1])).href) {
+    exit(main());
+}