@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/hooks/state_io.ts

@@ -6,10 +6,14 @@
  * Python module exactly (snake_case kept deliberately — fidelity over
  * TS idiom).
  *
- * Per `docs/contracts/hook-architecture-v1.md` § Concurrency, every concern
- * that writes under `agents/runtime/state/` MUST:
- *
- * 1. Acquire an exclusive lock on `agents/runtime/state/.dispatcher.lock`.
+ * Per `docs/contracts/hook-architecture-v1.md`, Concurrency, every concern
+ * that writes a state file under `agents/` MUST:
+ *
+ * 1. Acquire an exclusive lock on `<state_dir>/.dispatcher.lock` — the SAME
+ *    directory the target file lives in, derived from the target's own
+ *    path (`path.dirname`), never a single fixed location: one concern's
+ *    target under `agents/runtime/state/` locks there, another's target
+ *    under `agents/state/` locks there instead.
  * 2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
  * 3. Rename(2) (atomic on the same filesystem) tmp → dest.
  * 4. Release the lock.

package/src/scripts/hooks/svg_obligation.ts

@@ -0,0 +1,497 @@
+/**
+ * The open-SVG-obligation reading — step 2.1(b) of `road-to-svg-review-followups`.
+ *
+ * THE HOLE THIS CLOSES, which a review found and a reading confirmed. A turn
+ * that edits an `.svg` and then runs `ui:render --profile asset` looks, to the
+ * turn-end gate, like a turn that verified its work. It is not: on a machine
+ * with no Playwright that command rendered nothing, and until 2026-10-11 it
+ * also exited 0. Teaching `isVerificationCommand` the command would have made
+ * the hole worse rather than better — the transcript path never sees an exit
+ * code (`turn_end_gate_hook.ts:764` matches a command and stops), so a bare
+ * call would have discharged the obligation on both paths.
+ *
+ * So the detector reads the RENDER, never the call. An `.svg` the turn edited
+ * is discharged by exactly one of two records:
+ *
+ *   1. an asset manifest with `verification: "verified"` whose `asset.digest`
+ *      equals the file's CURRENT digest; or
+ *   2. an asset manifest with `reason: "renderer-absent"` whose `static` block
+ *      carries `errors: 0` on that same digest — reported as `static-only`.
+ *
+ * Path 2 is why a consumer without Playwright is not refused forever on a gate
+ * declared `blocking`. A `render-failed` manifest discharges NOTHING: a
+ * renderer that ran and failed is a real failure, not a capability fact.
+ *
+ * FOUR PRECISIONS, each from a third review and each closing a way the gate
+ * would otherwise refuse honest work or accept dishonest work:
+ *
+ *   (ii)  A planted fixture opens no obligation. `tests/design-artifacts/
+ *         fixtures/**` and `tests/design-artifacts/scenarios/**` carry errors
+ *         ON PURPOSE and can never reach `verified`, so without this every turn
+ *         that touches one would be refused on a blocking gate. By PATH, not by
+ *         an inline ignore marker — a marker would hide the planted error from
+ *         the very test that has to find it.
+ *   (iii) A manifest counts only where THIS turn ran a render NAMING THAT
+ *         FILE after the edit. Otherwise an agent could write a manifest by
+ *         hand, digest included, and discharge its own obligation.
+ *
+ *         A turn that writes into the render directory by any other route —
+ *         an edit tool, or a shell command naming the directory — voids every
+ *         manifest for that turn, so a hand-written manifest plus a render that
+ *         names the file (and failed) no longer discharges (16.5.0 release
+ *         review).
+ *
+ *         THE RESIDUAL, stated rather than implied. This is a check against an
+ *         omission, not a tamper-proof attestation: a process that can run a
+ *         shell can write a file by a route no transcript reading recognises.
+ *         What is enforced is that a render naming the file ran and that the
+ *         turn did not visibly write the render directory; what is not
+ *         enforced is that the manifest on disk is the one that render produced. A manifest left by an
+ *         EARLIER turn whose digest still matches therefore discharges — and
+ *         that is defensible, because a matching digest means the bytes have
+ *         not moved since it was taken, which is the whole claim a digest
+ *         makes. It is recorded here because the first version of this
+ *         paragraph promised more than the code did (finding 2 of this
+ *         change's own completion review), and a gate whose documented
+ *         assurance outruns its implementation is quoted as written.
+ *   (iv)  A deleted `.svg` opens no obligation — it has no current digest, so
+ *         there is nothing a render could be bound to.
+ *
+ * Its own module rather than another 200 lines inside the gate: the gate ships
+ * in a byte-capped bundle AND sits two lines under the source-size ratchet, so
+ * a separate module is both the unit whose cost can be measured and the only
+ * place this could have gone.
+ *
+ * It is also why `openSvgObligation` returns a finding-shaped object rather
+ * than a reason the gate wraps: the gate's entry for it is ONE line, and the
+ * reasoning that would have been a comment there is the paragraph above.
+ *
+ * THE DETECTOR RUNS UNCONDITIONALLY, including while a subagent dispatch is
+ * open — nothing about a dispatch makes an unrendered graphic rendered.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { isAssetRenderCommand } from '../_lib/verification_command.js';
+import type { ToolCall } from '../_lib/turn_end_transcript.js';
+
+/**
+ * Re-exported, not re-derived. Finding 3 of this change's SECOND completion
+ * review moved the predicate into `_lib/verification_command.ts`, because
+ * detector C needs it too and a `_lib` module may not import from `hooks/`.
+ * Two copies of a command-shape regex is how the two detectors come to
+ * disagree about what a render is.
+ */
+export { isAssetRenderCommand };
+
+/**
+ * Tools that WRITE. One copy, here rather than imported from the gate: the
+ * gate imports this module, so the dependency runs one way.
+ */
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/** Where `ui:render` writes. One copy of the path, shared with the CLI by value. */
+export const RENDER_REL = path.join('agents', 'runtime', 'state', 'render');
+
+/**
+ * Paths whose `.svg` files are planted on purpose. Precision (ii).
+ *
+ * Compared against a forward-slash form of the path so the list reads the same
+ * on every platform and a Windows-shaped tool call is not silently exempt.
+ */
+export const PLANTED_PREFIXES: readonly string[] = [
+    'tests/design-artifacts/fixtures/',
+    'tests/design-artifacts/scenarios/',
+];
+
+export type DischargeKind = 'verified' | 'static-only';
+
+export interface SvgObligation {
+    /** Repo-relative, forward slashes — the evidence span a refusal quotes. */
+    file: string;
+    /** Why it is still open, in the words the refusal uses. */
+    reason: string;
+}
+
+export interface SvgDischarge {
+    file: string;
+    kind: DischargeKind;
+}
+
+export interface SvgObligationReading {
+    open: SvgObligation[];
+    discharged: SvgDischarge[];
+}
+
+/** The shape this reads out of a manifest. Deliberately partial. */
+interface AssetManifestish {
+    profile?: unknown;
+    verification?: unknown;
+    reason?: unknown;
+    asset?: { digest?: unknown; findings?: unknown } | undefined;
+    static?: { errors?: unknown; digest?: unknown } | undefined;
+}
+
+/** Does a manifest's asset reading carry an error-severity finding? */
+function hasErrorFinding(m: AssetManifestish): boolean {
+    const f = m.asset?.findings;
+    return Array.isArray(f) && f.some((x) => (x as { severity?: unknown })?.severity === 'error');
+}
+
+/**
+ * Repo-relative, forward slashes — whatever the host handed us.
+ *
+ * Finding 1 of this change's completion review, and it was a live gate risk
+ * rather than a tidiness point: this used to normalise separators only, so an
+ * ABSOLUTE tool-call path never started with `tests/design-artifacts/…` and the
+ * planted-fixture exemption silently missed. A blocking gate would then have
+ * refused every turn that edits one of the ~25 deliberately-broken fixtures
+ * this very change adds — and no test caught it, because every case passed a
+ * relative path. The function four lines down already treated an absolute path
+ * as expected input, which is the contradiction inside one file that made the
+ * finding decidable.
+ */
+const rel = (root: string, p: string): string => {
+    const slashed = p.split(path.sep).join('/');
+    // Normalised, so `fixtures/../../../public/a.svg` is `public/a.svg` and not
+    // a planted fixture by prefix (16.5.0 re-cut review).
+    if (!path.isAbsolute(p)) return path.posix.normalize(slashed).replace(/^\.\//, '');
+    const inside = path.relative(root, p).split(path.sep).join('/');
+    // `path.relative` escaping the root with `..` means the path is NOT in this
+    // workspace; keep it as given rather than inventing a relation to it.
+    return inside === '' || inside.startsWith('../') ? slashed : inside;
+};
+
+export function isPlantedFixture(relPath: string, root = ''): boolean {
+    const norm = rel(root, relPath);
+    return PLANTED_PREFIXES.some((prefix) => norm.startsWith(prefix));
+}
+
+/** Every asset manifest currently under the render directory. */
+export function readAssetManifests(root: string): AssetManifestish[] {
+    const dir = path.join(root, RENDER_REL);
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    const out: AssetManifestish[] = [];
+    for (const name of entries) {
+        let raw: string;
+        try {
+            raw = fs.readFileSync(path.join(dir, name, 'manifest.json'), 'utf8');
+        } catch {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(raw) as AssetManifestish;
+            if (parsed.profile === 'asset') out.push(parsed);
+        } catch {
+            // An unreadable manifest discharges nothing, which is the same
+            // verdict as an absent one and the safe direction for a gate.
+        }
+    }
+    return out;
+}
+
+/**
+ * How a digest is discharged by the manifests on disk, or `null`.
+ *
+ * `verified` wins over `static-only` when both exist: the stronger record is
+ * the one the report should name.
+ */
+export function dischargeFor(manifests: readonly AssetManifestish[], digest: string): DischargeKind | null {
+    let staticOnly = false;
+    for (const m of manifests) {
+        // AN ERROR FLOOR ON BOTH PATHS. Finding 2 of the fifth completion
+        // review: `verification: 'verified'` is written unconditionally by the
+        // render — it means a digest-bound render HAPPENED, which is what the
+        // skill's status table says and what it should keep meaning — and this
+        // branch discharged on it with no look at what the render FOUND. So a
+        // file whose own reading carries an error findings discharged a
+        // blocking gate through the strong path, while the weaker
+        // `renderer-absent` path below refused at a single error. The rigour
+        // was inverted: the path that saw more of the file demanded less of it.
+        if (m.verification === 'verified' && m.asset?.digest === digest && !hasErrorFinding(m)) {
+            return 'verified';
+        }
+        if (m.reason === 'renderer-absent' && m.static?.digest === digest && m.static.errors === 0) {
+            staticOnly = true;
+        }
+    }
+    return staticOnly ? 'static-only' : null;
+}
+
+export interface SvgObligationInputs {
+    /**
+     * One entry per file the turn EDITED, in order, `.svg` and otherwise, each
+     * carrying the `ui:render --profile asset` command lines that ran after
+     * THAT file's last edit, verbatim.
+     *
+     * Precision (iii), and both halves of it were wrong once.
+     *
+     * The first round made it per file by NAME: a single boolean used to mean
+     * that any asset render anywhere unlocked every manifest on disk, so a
+     * hand-written manifest plus a decoy render on an unrelated file
+     * discharged the obligation. A command must NAME the file it discharges.
+     *
+     * The second round made it per file by TIME, which is finding 2 of that
+     * round. The render window was taken from the turn's LAST `.svg` edit
+     * globally while the obligation is per file, so the ordinary interleaved
+     * turn — edit a, render a, edit b, render b — hid render-a behind edit-b
+     * and refused a turn in which both files were rendered correctly after
+     * their own edits. Confirmed by running it before it was changed.
+     *
+     * Both windows are the same shape: a render counts for a file only if it
+     * names that file AND follows that file's own last edit.
+     */
+    edits: ReadonlyArray<{ path: string; rendered: readonly string[] }>;
+    /**
+     * True when this turn wrote into the render directory by some route other
+     * than an asset render — an edit tool, or a shell command naming the
+     * directory. The manifests on disk are then not evidence of a render, so
+     * none of them discharges anything (16.5.0 release review).
+     */
+    renderDirTampered?: boolean;
+}
+
+/**
+ * The reading. Pure apart from reading the files it is asked about, so the
+ * eight cases the roadmap names can be exercised without a hook run.
+ */
+export function readSvgObligations(root: string, inputs: SvgObligationInputs): SvgObligationReading {
+    const open: SvgObligation[] = [];
+    const discharged: SvgDischarge[] = [];
+    const seen = new Set<string>();
+    let manifests: AssetManifestish[] | null = null;
+
+    for (const { path: raw, rendered } of inputs.edits) {
+        if (!/\.svg$/i.test(raw)) continue;
+        // Repo-relative FIRST, so `seen`, the planted exemption and the
+        // reported `file` all speak the same dialect — the doc on
+        // `SvgObligation.file` promises repo-relative and used to be false for
+        // an absolute tool call.
+        const relPath = rel(root, raw);
+        if (seen.has(relPath)) continue;
+        seen.add(relPath);
+        // (ii) planted fixtures carry errors on purpose.
+        if (isPlantedFixture(relPath, root)) continue;
+
+        // (iv) a deleted file has no current digest, so nothing could be bound
+        // to it and no render could ever discharge it.
+        const abs = path.isAbsolute(raw) ? raw : path.join(root, relPath);
+        // The BYTES, matching the render and the static witness. Finding 2 of
+        // the sixth completion review: this hashed the UTF-8 decoded string
+        // while the render hashed the raw buffer, so a file the decode is not
+        // byte-exact over could never have its obligation discharged.
+        let bytes: Buffer;
+        try {
+            bytes = fs.readFileSync(abs);
+        } catch {
+            continue;
+        }
+        const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+
+        // (iii) The manifests are only consulted once a render was observed.
+        // Reading them first and then discarding the verdict would make the
+        // ordering look like a performance detail rather than the rule.
+        if (!renderNames(rendered, relPath)) {
+            open.push({
+                file: relPath,
+                reason:
+                    'no `ui:render --profile asset` naming this file ran after THIS file\'s last edit, so no ' +
+                    'manifest on ' +
+                    'disk can be attributed to it — a manifest written by any other route, and a render of ' +
+                    'some other file, both discharge nothing',
+            });
+            continue;
+        }
+        if (inputs.renderDirTampered) {
+            open.push({
+                file: relPath,
+                reason:
+                    'this turn wrote into the render directory by a route other than `ui:render`, so no manifest ' +
+                    'there is evidence of a render — re-run the render in a turn that does not touch it',
+            });
+            continue;
+        }
+        manifests ??= readAssetManifests(root);
+        const kind = dischargeFor(manifests, digest);
+        if (kind === null) {
+            open.push({
+                file: relPath,
+                reason:
+                    'no asset manifest matches this file\'s current digest — a render that is `verified`, or a ' +
+                    '`renderer-absent` one whose static witness reports 0 errors on the same digest, discharges it',
+            });
+            continue;
+        }
+        discharged.push({ file: relPath, kind });
+    }
+    return { open, discharged };
+}
+
+/**
+ * Does one of the observed renders NAME this file?
+ *
+ * The render is a precondition for reading a manifest, never a discharge on
+ * its own — `isVerificationCommand` still does not match it, so the command's
+ * text cannot satisfy the obligation on the transcript path. Detector C reads
+ * `isVerificationAttempt` instead, which is a different question with a
+ * different right answer; both live in `_lib/verification_command.ts`, where
+ * the split is argued.
+ */
+export function renderNames(commands: readonly string[], relPath: string): boolean {
+    const base = relPath.split('/').pop() ?? relPath;
+    return commands.some((c) => {
+        const slashed = c.split(path.sep).join('/');
+        // The path as written, or its basename — a caller may `cd` first, and a
+        // basename collision inside one turn is a narrower hole than the
+        // any-render-unlocks-everything it replaces.
+        //
+        // BOTH tests are anchored. Finding 3 of the fourth completion review:
+        // the path branch was a bare `includes`, so a render of
+        // `public/icon.svg` counted as naming `n.svg` and `on.svg` — any file
+        // whose path is a substring of another file's path was discharged by a
+        // render it had nothing to do with, which is the
+        // any-render-unlocks-everything hole this function replaced, reopened
+        // one character at a time. The boundary admits `/` before, so a path
+        // written `./public/icon.svg` still names `public/icon.svg`.
+        const bounded = (needle: string): boolean =>
+            new RegExp(`(^|[\\s/'"])${escapeRe(needle)}(\\s|$|['"])`).test(slashed);
+        return bounded(relPath) || bounded(base);
+    });
+}
+
+/**
+ * A render call standing alone — no second command chained to it and no
+ * redirect — so its text cannot also carry a write. A leading `cd <dir> &&`,
+ * piping its output to a read-only filter, and folding stderr into stdout are
+ * allowed.
+ */
+export function isPureRender(command: string): boolean {
+    if (!isAssetRenderCommand(command)) return false;
+    const [head, ...pipes] = command.replace(/^\s*cd\s+[^;&|<>`$\n]+&&\s*/, '').replace(/\s\d?>&\d\b/g, ' ').replace(/\s2>\s*\/dev\/null\b/g, ' ').split('|');
+    if (/[;&<>`\n]|\$\(/.test(head ?? '')) return false;
+    return pipes.every((p) => /^\s*(tail|head|grep|jq|cat|less|wc)\b[^;&<>`|]*$/.test(p) && !/\$\(/.test(p));
+}
+
+/**
+ * Does a shell command (other than a pure render) write somewhere a render
+ * manifest could live? Read by shape: a write operator, together with the
+ * render directory, a `render/` path or a `manifest.json` — so `cd` into the
+ * state directory and a relative write is caught, and reading a manifest
+ * back is not.
+ */
+export function writesRenderDir(command: string): boolean {
+    if (isPureRender(command)) return false;
+    const slashed = command.split(path.sep).join('/');
+    const names = /(^|[\s/'"])(render\/|manifest\.json\b)/.test(slashed) || slashed.includes('state/render');
+    // A LISTED interpreter in a command that names the directory counts as a
+    // write — inline flag, long option, `eval` or a program on stdin — because
+    // what it does with the path is not readable from the command line. A
+    // read-only script is caught too, on purpose: the cost is one re-render.
+    // An unlisted or indirected interpreter is not seen; see the header residual.
+    const writes = />(?!&)|\b(tee|sponge)\b|\b(cp|mv|ln|install|rsync|dd)\s|\bsed\s+-i|\bwriteFile|\b(python[\d.]*|perl|ruby|node|deno|bun|php|osascript)\b/.test(
+        slashed.replace(/\s\d?>&\d\b/g, ' ').replace(/\s2>\s*\/dev\/null\b/g, ' '),
+    );
+    return names && writes;
+}
+
+/** Escape a path component for use inside a RegExp. */
+function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+
+
+/**
+ * An `.svg` this turn edited that no render describes — step 2.1(b) of
+ * `road-to-svg-review-followups`.
+ *
+ * REPORTED UNDER `verification`, not under a new detector id, and that is a
+ * choice rather than a shortcut: this IS a verification finding — a file
+ * changed and nothing that can fail was run over it — and a seventh id would
+ * ripple through `DETECTOR_IDS`, the per-detector counters and the demotion
+ * contract for a distinction the operator never makes.
+ *
+ * IT RUNS EVEN WHEN `detectUnverifiedEdit` IS SATISFIED. That is the point:
+ * review claim C2 is about a turn that edits an `.svg` and then runs something
+ * — a test suite, a linter, a bare `ui:render` — which looks like verification
+ * and did not look at the graphic. An unrelated check discharges nothing here.
+ *
+ * The companion half is that `isVerificationCommand` learns NEITHER `ui:render`
+ * NOR `xmllint`. Teaching it either would discharge the obligation on the
+ * transcript path from the command text alone, which is the hole rather than
+ * the fix. `svg_obligation.ts` carries the two records that do discharge it.
+ */
+export function openSvgObligation(
+    workspaceRoot: string,
+    toolCalls: readonly ToolCall[],
+): { detector: 'verification'; evidence: string; reason: string; mode: 'transcript' } | null {
+    // Precision (iii). The render has to come AFTER the edit it describes, on
+    // both evidence paths — `toolCalls` is assembled for both, so one rule
+    // covers them rather than two that can disagree.
+    //
+    // The window is per FILE, which finding 2 of the second review round is
+    // about: taking it from the turn's last `.svg` edit globally hid an
+    // earlier file's render behind a later file's edit, so the ordinary
+    // interleaved turn was refused although every file had been rendered after
+    // its own edit. The last edit of each path is the one that counts, because
+    // an earlier render describes bytes a later edit replaced.
+    const lastEditOf = new Map<string, number>();
+    for (let i = 0; i < toolCalls.length; i += 1) {
+        const c = toolCalls[i]!;
+        if (!EDIT_TOOLS.has(c.name) || c.path === undefined) continue;
+        lastEditOf.set(c.path, i);
+    }
+    if (lastEditOf.size === 0) return null;
+
+    const edits = [...lastEditOf].map(([p, at]) => {
+        const rendered: string[] = [];
+        for (let i = at + 1; i < toolCalls.length; i += 1) {
+            const c = toolCalls[i]!;
+            if (c.name === 'Bash' && c.command !== undefined && isPureRender(c.command)) {
+                rendered.push(c.command);
+            }
+        }
+        return { path: p, rendered };
+    });
+
+    const renderDir = RENDER_REL.split(path.sep).join('/');
+    const renderDirTampered = toolCalls.some((c) => {
+        if (EDIT_TOOLS.has(c.name) && c.path !== undefined) {
+            return rel(workspaceRoot, c.path).startsWith(`${renderDir}/`);
+        }
+        return c.name === 'Bash' && c.command !== undefined && writesRenderDir(c.command);
+    });
+
+    let reading: SvgObligationReading;
+    try {
+        reading = readSvgObligations(workspaceRoot, { edits, renderDirTampered });
+    } catch {
+        // A gate that crashed on its own instrument is a new failure mode on a
+        // path meant to be inert. An unreadable render directory is no finding.
+        return null;
+    }
+    const first = reading.open[0];
+    if (first === undefined) return null;
+
+    const more = reading.open.length > 1 ? ` (and ${String(reading.open.length - 1)} more)` : '';
+    return {
+        // Reported under `verification` rather than a seventh detector id: it
+        // IS a verification finding — a file changed and nothing that can fail
+        // ran over it — and a new id would ripple through DETECTOR_IDS, the
+        // per-detector counters and the demotion contract for a distinction the
+        // operator never makes.
+        detector: 'verification',
+        mode: 'transcript',
+        evidence: first.file,
+        reason:
+            `this turn edited an .svg and no render describes it${more} — ${first.reason}. ` +
+            'A bare `ui:render --profile asset` that rendered nothing, and a test or lint run over other ' +
+            'files, both discharge nothing: the gate reads the render, never the call.',
+    };
+}

package/src/scripts/hooks/svg_rules_loader.ts

@@ -0,0 +1,133 @@
+/**
+ * The conditional chunk — step 0.1 of `road-to-svg-rules-in-the-dispatch-path`.
+ *
+ * WHY A CHUNK AND NOT AN IMPORT. `src/scripts/_lib/svg_rules.ts` costs 30,924
+ * bytes when it is statically imported into `dist/hooks/dispatch.js`, the one
+ * bundle every hook event loads on every dispatch. An AI council of two
+ * providers refused a ceiling raise for it 2/2 on 2026-10-11 and both seats
+ * asked for this to be tried first: emit the rule set beside the bundle and
+ * load it only when the written path ends in `.svg`.
+ *
+ * WHY `require` AND NOT `await import`. `ConcernMain` is
+ * `(argv?) => number | undefined | void` — synchronous. A concern that returned
+ * a Promise would have its exit code read as an object, so the chunk has to be
+ * loadable without an `await`. It is therefore emitted as CJS and pulled with
+ * `createRequire`, which is synchronous. This is a constraint of the dispatch
+ * contract, not a style choice; making it `async` means making every concern
+ * async, which is a different change than this one.
+ *
+ * WHY THE SPECIFIER IS COMPUTED AT RUNTIME. A literal `import()` or `require()`
+ * argument is analyzable, and esbuild would inline the module — which is
+ * exactly the 30,924 bytes this avoids. Both branches build their specifier
+ * from `import.meta.url`, so neither is a static edge in the bundle's graph.
+ *
+ * THE TWO BRANCHES.
+ *
+ *   bundled   — `import.meta.url` is `dist/hooks/dispatch.js` (esbuild keeps
+ *               `import.meta.url` in ESM output and the banner resolves the
+ *               real path through a symlink), so the chunk is its sibling
+ *               `dist/hooks/svg_rules.chunk.cjs`.
+ *   unbundled — running from source under `tsx`, where `require` of a `.ts`
+ *               file resolves through tsx's CJS hook. Measured working
+ *               2026-10-11; there is no chunk on this path and none is built.
+ *
+ * FAILURE IS NULL, NEVER A THROW. A missing chunk in a consumer install, a
+ * chunk packed to another path, or a module that throws on load all return
+ * `null` and the caller reports the rules as unavailable. The dispatch bundle
+ * handles every hook event in one process: a throw that escaped here would
+ * break events that never touched an `.svg`, which is the containment
+ * `design_pass_svg.test.ts` pins.
+ */
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { Finding as SvgFinding, ScanOptions } from '../_lib/svg_rules.js';
+import { verifyBundle } from './bundle_integrity.js';
+
+/** The signature `scanSvg` exports. Type-only, so no bytes reach the bundle. */
+export type SvgScan = (text: string, file: string, opts?: ScanOptions) => SvgFinding[];
+
+/** The emitted sibling's name. `build:hook-chunks` writes exactly this. */
+export const CHUNK_BASENAME = 'svg_rules.chunk.cjs';
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+
+/** True when this code is running from `dist/hooks/dispatch.js`. */
+export function isBundled(): boolean {
+    return typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+}
+
+/**
+ * Where to load the rules from, given this module's own URL.
+ *
+ * Exported so a test can pin both branches without a bundle: the path algebra
+ * is the half that breaks silently in a consumer install, and a probe that can
+ * only run against a built bundle would not be run.
+ */
+export function rulesSpecifier(selfUrl: string, bundled: boolean): string {
+    const selfPath = fileURLToPath(selfUrl);
+    const dir = path.dirname(selfPath);
+    if (bundled) return path.join(dir, CHUNK_BASENAME);
+    // From source: `.../src/scripts/hooks/` → `.../src/scripts/_lib/`. The
+    // extension follows this file's own, so a compiled-to-JS tree resolves too.
+    const ext = selfPath.endsWith('.ts') ? '.ts' : '.js';
+    return path.join(dir, '..', '_lib', `svg_rules${ext}`);
+}
+
+const cache = new Map<string, SvgScan | null>();
+
+/**
+ * The rule set, or `null` when it could not be loaded.
+ *
+ * Cached including the failure: a consumer whose install is missing the chunk
+ * would otherwise pay a failed module resolution on every `.svg` write.
+ *
+ * Keyed BY `selfUrl`. Finding 13 of the third completion review: a single
+ * slot meant the first call's verdict answered every later call whatever url
+ * it passed, so the parameter was accepted and ignored — the shape this
+ * change's own review found three times under other names. It is one caller
+ * and one url on the hook path, so nothing observable changed; a cache whose
+ * key is not its input is wrong regardless of who currently calls it, and
+ * that is cheaper to fix than to remember.
+ */
+export function loadSvgScan(selfUrl: string = import.meta.url): SvgScan | null {
+    const hit = cache.get(selfUrl);
+    if (hit !== undefined || cache.has(selfUrl)) return hit ?? null;
+    const scan = loadSvgScanUncached(selfUrl);
+    cache.set(selfUrl, scan);
+    return scan;
+}
+
+/**
+ * The uncached load. Separate so a test can exercise a failure and a success.
+ *
+ * `bundled` is an explicit override rather than always `isBundled()`: under a
+ * test runner the define is absent, so the bundled branch — the one that
+ * breaks silently in a consumer install — would otherwise be unreachable from
+ * any test that does not first build a bundle, and a probe that expensive does
+ * not get run. The hook path never passes it.
+ */
+export function loadSvgScanUncached(
+    selfUrl: string = import.meta.url,
+    bundled: boolean = isBundled(),
+): SvgScan | null {
+    try {
+        const specifier = rulesSpecifier(selfUrl, bundled);
+        // The chunk runs inside the dispatch process, so it gets the bundle's
+        // own integrity check: a mismatch with its sidecar is not executed.
+        // No sidecar is `unverifiable` and allowed, as for `dispatch.js`.
+        if (bundled && verifyBundle(specifier).state === 'mismatch') return null;
+        const req = createRequire(selfUrl);
+        const mod = req(specifier) as Record<string, unknown>;
+        const scan = mod['scanSvg'];
+        return typeof scan === 'function' ? (scan as SvgScan) : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Test seam: forget every cached verdict. Never called by the hook path. */
+export function _resetSvgScanCache(): void {
+    cache.clear();
+}