@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/measure_turn_end_gate.ts

@@ -63,8 +63,26 @@
  *     means reusing `nextState`, which is a larger change than a measurement
  *     correction and would itself need re-measuring.
  *
+ *   · THE RETRY-CONDITIONED RE-REFUSAL SHARE, which every bullet above is
+ *     silent about because until 2026-09-30 nothing produced it. It does NOT
+ *     come from the corpus: it is read from the gate's own shadow records under
+ *     `agents/runtime/state/turn-end-gate/*.shadow.json`, written live on an
+ *     allow path by the instrument `turn-end-detector-demotion.md` registers as
+ *     instrument 1. Reported per LAYER and then per detector, never pooled, and
+ *     never as `0.0%` where it has no denominator — see `renderQ1`.
+ *   · It does NOT print that contract's **Q1**, and the distinction is in the
+ *     report's own header rather than only here. Q1 conditions BOTH its halves
+ *     on the detector; the shadow record cannot, because it never stores which
+ *     refusal produced a retry. The two disagree in direction and neither
+ *     bounds the other, so no number this prints may be read against a bar.
+ *   · It does not report promissory, completion or untested at all. Those three
+ *     are skipped by the gate when a dispatch is open and the shadow record
+ *     carries no dispatch flag, so their denominators would absorb silences
+ *     nobody observed. The contract's attribution clause already forbids it.
+ *
  * Usage:
  *   ./scripts-run src/scripts/measure_turn_end_gate --store <dir> [--limit N] [--show-fires]
+ *   ./scripts-run src/scripts/measure_turn_end_gate --q1 [--workspace <dir>]
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -82,6 +100,14 @@ import {
     extractToolCalls,
     type ToolCall,
 } from './hooks/turn_end_gate_hook.js';
+import {
+    DETECTOR_IDS,
+    DISPATCH_CENSORED_DETECTORS,
+    SHADOW_LAYERS,
+    collectShadowStats,
+    retryConditionedShare,
+    type ShadowStats,
+} from './_lib/turn_end_refusals.js';
 
 interface Counts {
     /**
@@ -495,16 +521,169 @@ export function render(c: Counts): string {
     ].join('\n');
 }
 
+/** `n` with a unit that agrees with it. One place, so no line has to remember. */
+function plural(n: number, one: string, many = `${one}s`): string {
+    return `${String(n)} ${n === 1 ? one : many}`;
+}
+
+/**
+ * The retry-conditioned re-refusal share, read from the shadow records rather
+ * than from a transcript. `road-to-a-stop-that-holds` step 2.2; the producer is
+ * step 2.1.
+ *
+ * ```
+ * THIS IS NOT THE Q1 `turn-end-detector-demotion.md` REGISTERS BARS AGAINST,
+ * AND THE REPORT SAYS SO IN ITS OWN HEADER.
+ * ```
+ *
+ * The first version of this renderer called the number Q1 outright. An
+ * independent review (2026-10-01) showed the two are different quantities that
+ * disagree in direction, not one quantity with a looser denominator — see
+ * `retryConditionedShare` for the worked ten-retry example. The rename and this
+ * header are that finding, acted on rather than noted.
+ *
+ * A DIFFERENT SOURCE FROM EVERY OTHER NUMBER THIS SCRIPT PRINTS, which is why
+ * it is a separate renderer rather than another line in `render`. The fire
+ * rates above are replayed out of a transcript corpus; this comes out of
+ * `agents/runtime/state/turn-end-gate/*.shadow.json`, written live by the gate
+ * on an allow path. The two cannot be joined — a shadow record carries no
+ * transcript and a transcript carries no shadow record — so printing them from
+ * one `Counts` object would invite exactly the cross-instrument arithmetic R2
+ * finding 7 removed from the language totals.
+ *
+ * NULL IS PRINTED AS `—`, NEVER AS `0.0%`. The two mean opposite things and
+ * `retryConditionedShare` keeps them apart for that reason; collapsing them at
+ * the render layer would undo the distinction one line before a human reads it.
+ *
+ * THE RESOLVED WORKSPACE IS PRINTED, because the one failure mode here is quiet:
+ * `--workspace` takes any path, a worktree carries no `agents/runtime/`, and the
+ * report for a wrong directory is a confident "no shadow record". A reading
+ * pasted into an evidence file must carry the directory that produced it.
+ */
+export function renderQ1(stats: ShadowStats, today: string, workspace?: string): string {
+    const lines: string[] = [
+        `measure-turn-end-gate · retry-conditioned re-refusal share · ${plural(stats.files, 'shadow record')} · read ${today}`,
+        '  NOT the Q1 `turn-end-detector-demotion.md` registers bars against — see',
+        '  the note below the table before comparing any number here to a bar.',
+    ];
+    if (workspace !== undefined) {
+        lines.push(`  workspace: ${path.resolve(workspace)}`);
+    }
+    lines.push('');
+    if (stats.files === 0) {
+        lines.push(
+            '  No readable shadow record under this workspace. The share has no',
+            '  denominator and is not reported as zero — a gate that has never been',
+            '  retried is not a gate whose retries all came back clean.',
+        );
+        if (stats.unreadable > 0) {
+            lines.push(
+                '',
+                `  ${plural(stats.unreadable, 'shadow file')} present but UNREADABLE, so "none" above`,
+                '  means none could be parsed rather than none exists. That is a defect to',
+                '  investigate, not an empty sample.',
+            );
+        }
+        return lines.join('\n');
+    }
+    for (const layer of SHADOW_LAYERS) {
+        const bucket = stats.byLayer.find((b) => b.layer === layer);
+        if (bucket === undefined) continue;
+        lines.push(
+            `  layer ${layer} — ${plural(bucket.retries, 'retry', 'retries')} observed, ${plural(bucket.rows, 'shadow row')}`,
+        );
+        if (bucket.retries === 0) {
+            lines.push('    (no retry on this layer; every share below would have no denominator)');
+        }
+        for (const id of DETECTOR_IDS) {
+            if (DISPATCH_CENSORED_DETECTORS.has(id)) {
+                lines.push(`    ${id.padEnd(17)} censored   (dispatch-suppressed retries are indistinguishable)`);
+                continue;
+            }
+            const share = retryConditionedShare(stats, layer, id);
+            // A dash denies a measurement; a count beside it reads like one. The
+            // `(0 / 0)` the first version printed there was the denial and the
+            // measurement on the same line.
+            if (share === null) {
+                lines.push(`    ${id.padEnd(17)}      —`);
+                continue;
+            }
+            const shown = `${(100 * share).toFixed(1)}%`.padStart(6);
+            lines.push(`    ${id.padEnd(17)} ${shown}   (${String(bucket.byDetector[id])} / ${String(bucket.retries)})`);
+        }
+        lines.push('');
+    }
+    lines.push(
+        '  WHAT THIS IS, precisely, because the contract defines a DIFFERENT number',
+        '  under a similar name. Printed here: of the retries observed on a layer,',
+        "  the share a detector would have refused. The contract's Q1: of a",
+        "  DETECTOR'S OWN initial refusals, the share whose retry that same detector",
+        '  refuses again. Both halves of the contract definition are conditioned on',
+        '  the detector; neither half here is, because `ShadowRecord` does not record',
+        '  which refusal produced a retry. The two disagree in direction and neither',
+        '  bounds the other, so no number above may be read against a bar in',
+        "  `turn-end-detector-demotion.md` § The bars. Closing that needs the",
+        '  PRODUCER to record the originating detector.',
+        '',
+        '  THREE DETECTORS ARE CENSORED, and the contract requires it rather than',
+        '  this renderer choosing it. `runDetectors` skips promissory, completion and',
+        "  untested when a dispatch is open, and the shadow record carries no dispatch",
+        '  flag — so those retries would enter their denominators as observations of',
+        '  silence that nobody made. The attribution clause already forbids reporting',
+        '  a detector a rollup cannot separate that way.',
+        '',
+        '  GROUPED BY LAYER FIRST, and the grouping is load-bearing rather than',
+        '  cosmetic. A `stop_hook_active` retry follows ANY stop concern\'s block, not',
+        '  only this gate\'s, so a pooled share divides another concern\'s retries into',
+        '  this gate\'s refusals. `retries_observed` is keyed by layer so the',
+        '  denominator splits with the numerator.',
+        '',
+        '  TWO FURTHER BOUNDS ON EVERY NUMBER ABOVE, both properties of the instrument:',
+        '    1. A retry whose transcript is absent, oversized or textless records',
+        '       NOTHING — no row and no retry. Numerator and denominator shrink',
+        '       together, so each share is an UPPER bound, never a point estimate.',
+        '    2. On a host that sends no `session_id` every session shares one record.',
+        '       The record count above is FILES; it equals sessions only where the',
+        '       host sends an id.',
+        '',
+        '  A share above may be well-formed and still unreadable as a rate if the',
+        '  record count is small. The count is printed first for that reason.',
+    );
+    if (stats.dropped > 0) {
+        lines.push(
+            '',
+            `  ${plural(stats.dropped, 'row')} dropped to the per-session cap: every numerator above is a FLOOR.`,
+        );
+    }
+    if (stats.unreadable > 0) {
+        lines.push(
+            '',
+            `  ${plural(stats.unreadable, 'shadow file')} present but unreadable — same reading, same direction.`,
+        );
+    }
+    if (stats.earliest !== null && stats.latest !== null) {
+        lines.push('', `  Window observed: ${stats.earliest} … ${stats.latest}`);
+    }
+    return lines.join('\n');
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     let store = '';
     let limit = 30;
     let showFires = false;
+    let q1Only = false;
+    let workspace = process.cwd();
     for (let i = 0; i < argv.length; i += 1) {
         if (argv[i] === '--store' && argv[i + 1] !== undefined) {
             store = argv[i + 1]!;
             i += 1;
         } else if (argv[i] === '--show-fires') {
             showFires = true;
+        } else if (argv[i] === '--q1') {
+            q1Only = true;
+        } else if (argv[i] === '--workspace' && argv[i + 1] !== undefined) {
+            workspace = argv[i + 1]!;
+            i += 1;
         } else if (argv[i] === '--limit' && argv[i + 1] !== undefined) {
             // R2 finding 15: an unvalidated parseInt made `--limit abc` yield
             // NaN, `slice(0, NaN)` return nothing, and the script exit 2 with
@@ -521,6 +700,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             i += 1;
         }
     }
+    const today = new Date().toISOString().slice(0, 10);
+    // `--q1` needs no transcript corpus: the shadow records are the source, and
+    // requiring a `--store` for them would make the one reading this roadmap
+    // asks for contingent on an unrelated input. Deliberately NOT a silent
+    // default of the store path — a reading over the wrong workspace is the
+    // failure mode here, and it is quiet.
+    if (q1Only) {
+        process.stdout.write(`${renderQ1(collectShadowStats(workspace), today, workspace)}\n`);
+        return 0;
+    }
     if (!store) {
         process.stderr.write('measure-turn-end-gate: --store <transcript dir> is required\n');
         return 2;
@@ -533,6 +722,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
     process.stdout.write(`${render(counts)}\n`);
+    // Q1 rides on the default report because step 2.2 asks that
+    // `measure_turn_end_gate` PRINT it, not that it offer to. A reader who
+    // never learns the flag exists still sees the number.
+    process.stdout.write(`\n${renderQ1(collectShadowStats(workspace), today, workspace)}\n`);
     if (showFires) {
         process.stdout.write(`\n  detector F fired here — read these turns before\n  calling any of them a false positive:\n${renderFires(counts)}\n`);
         process.stdout.write(`\n  detector E fired here — same reading, same reason:\n${renderDroppedFires(counts)}\n`);

package/src/scripts/memory_learn_hook.ts

@@ -22,6 +22,11 @@
  *   PROMOTED lesson is surfaced as a one-line visibility marker pointing
  *   at the existing /memory:propose flow. Nothing auto-writes curated
  *   `agents/memory/*.yml`.
+ * - Measured: every run appends one line to the gitignored dogfood ledger
+ *   (`agents/runtime/state/learning-dogfood.jsonl`) BEFORE the early
+ *   returns, so the 30-day window the default flip is gated on can read a
+ *   zero rather than a silence. See `runLearn` for why that distinction is
+ *   the whole point.
  *
  * Exit codes (dispatcher contract): 0 always (allow).
  */
@@ -44,8 +49,9 @@ import type { SettingsClass } from '../shared/settingsClasses.js';
 import { consentVerdict, type ConsentVerdict } from '../shared/settingsConsent.js';
 
 import {
-    buildSidecar,
+    buildSidecarFromSignals,
     LESSONS_NAME,
+    readSignals,
     renderLessonsMd,
     SIDECAR_NAME,
 } from './learning_sidecar.js';
@@ -175,23 +181,102 @@ export function enabled(root: string): boolean {
     return learnConsent(root) === 'granted';
 }
 
-/** Run the aggregation. Returns the one-line marker to emit, or null. */
+/**
+ * The dogfood ledger: repo-relative POSIX path, one JSON object per line.
+ *
+ * Under `agents/runtime/` — gitignored wholesale — because it is one machine's
+ * timings and counts, not a shared artefact. Its continuity-surface row records
+ * it as `excluded`: nothing restores a session from it.
+ */
+export const DOGFOOD_LEDGER_POSIX = 'agents/runtime/state/learning-dogfood.jsonl';
+
+/** One session end, as the ledger records it. */
+export interface DogfoodLine {
+    /** The `now` the aggregation ran against. */
+    at: string;
+    /** Wall-clock ms for read + aggregate — the portion the 2 s budget governs. */
+    wall_ms: number;
+    /** Well-formed signal records read from the intake. */
+    signals_in: number;
+    /** Lessons the aggregation produced. */
+    lessons_out: number;
+    /** Of those, how many carry the `preferred` verdict. */
+    preferred: number;
+}
+
+/**
+ * Append one measurement line. Never throws: the ledger is a measurement, and
+ * a measurement that can break the thing it measures is worse than no ledger.
+ */
+export function appendDogfoodLine(root: string, line: DogfoodLine): void {
+    try {
+        const file = path.join(root, ...DOGFOOD_LEDGER_POSIX.split('/'));
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    } catch {
+        // fail-open, same contract as the aggregation itself.
+    }
+}
+
+/** Read the ledger back. Malformed lines are skipped, an absent file is empty. */
+export function readDogfoodLines(root: string): DogfoodLine[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(root, ...DOGFOOD_LEDGER_POSIX.split('/')), 'utf8');
+    } catch {
+        return [];
+    }
+    const out: DogfoodLine[] = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line) continue;
+        try {
+            out.push(JSON.parse(line) as DogfoodLine);
+        } catch {
+            continue;
+        }
+    }
+    return out;
+}
+
+/**
+ * Run the aggregation. Returns the one-line marker to emit, or null.
+ *
+ * MEASURE FIRST, THEN DECIDE. The flip condition this hook's default is gated
+ * on (`src/config/agent-settings.template.yml:1376-1378`) names two numbers —
+ * non-trivial signal AND session-end p95 < 2 s — and until the ledger below
+ * existed, neither was recorded: every early return here fired before any
+ * measurement point, so a checkout with an empty intake produced an unbroken
+ * silence. A silence and a measured zero read identically to whoever opens the
+ * window, which is the one failure a 30-day window cannot recover from. So the
+ * read, the aggregation and the ledger line all happen before the first return.
+ */
 export function runLearn(root: string, nowIso: string, budgetMs: number = BUDGET_MS): string | null {
     const started = Date.now();
     const intakeDir = path.join(root, 'agents', 'memory', 'intake');
     const outDir = path.join(root, 'agents', 'memory');
-    if (!fs.existsSync(intakeDir)) return null;
-    const sidecar = buildSidecar(intakeDir, nowIso);
+    // An absent intake directory is a zero-signal session, not an absent one.
+    const haveIntake = fs.existsSync(intakeDir);
+    const signals = haveIntake ? readSignals(intakeDir) : [];
+    const sidecar = buildSidecarFromSignals(signals, nowIso);
+    const preferred = sidecar.lessons.filter((l) => l.verdict === 'preferred').length;
+    appendDogfoodLine(root, {
+        at: nowIso,
+        wall_ms: Date.now() - started,
+        signals_in: signals.length,
+        lessons_out: sidecar.lessons.length,
+        preferred,
+    });
+    if (!haveIntake) return null;
     if (Date.now() - started > budgetMs) return null; // over budget — skip the write
     if (sidecar.lessons.length === 0) return null;
     fs.writeFileSync(path.join(outDir, SIDECAR_NAME), `${JSON.stringify(sidecar, null, 2)}\n`, 'utf8');
     fs.writeFileSync(path.join(outDir, LESSONS_NAME), renderLessonsMd(sidecar), 'utf8');
-    const promoted = sidecar.lessons.filter((l) => l.verdict === 'preferred').length;
     const deadEnds = sidecar.lessons.filter((l) => l.verdict === 'dead_end').length;
     // Memory-visibility contract shape: one line, ids/counters only, no bodies.
     return (
         `🧠 Memory: sidecar refreshed — ${sidecar.lessons.length} lesson(s) ` +
-        `(${promoted} preferred · ${deadEnds} dead-end); promote via /memory:propose`
+        `(${preferred} preferred · ${deadEnds} dead-end); promote via /memory:propose`
     );
 }
 

package/src/scripts/memory_lookup.ts

@@ -35,7 +35,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 import YAML, { parseDocument } from 'yaml';
 
-import { sanitize_entry } from './_lib/retrieval_sanitize.js';
+import { sanitize_entry } from './_lib/retrieval_sanitize.js'; // read-surface: ingested-corpus
 import { LexicalIndex, tokenize as _lexTokenize } from './_lib/lexical_index.js';
 import {
     ensureIndex as _ftsEnsureIndex,

package/src/scripts/model_rule_injection.ts

@@ -65,6 +65,7 @@ import {
     triggerlessRuleIds,
     type Router,
 } from './_lib/rule_injection.js';
+import { ruleBody } from './_lib/rule_law_section.js';
 import {
     renderArmExperiment,
     runArmExperiment,
@@ -682,6 +683,34 @@ export function runEndpoints(corpusDir: string): EndpointResult[] {
     ]);
     const thinnedAndPathOnly = pathOnlyReach.filter((id) => !alwaysEager.has(id));
 
+    // PROMPT-LEVEL beside RULE-LEVEL — step 0.4 of
+    // `road-to-a-rule-carrier-that-works-outside-the-repo`.
+    //
+    // The two numbers above are per RULE: a rule counts as reachable when ANY
+    // of its labelled positives matches. That is the right unit for the bar —
+    // "no labelled rule left unreachable" — and it is the wrong unit for the
+    // question a reader actually asks next, which is how much of the corpus the
+    // shipped binding delivers. A rule reachable on one of twelve prompts and a
+    // rule reachable on all twelve are the same row in `byRule`.
+    //
+    // So the pair is reported in both units. The SUMMARY view has computed the
+    // prompt-level figures since the two-readings split landed; what was missing
+    // is that `--endpoints`, which is the view a claim cites, printed only the
+    // rule-level half. A reader comparing the two views saw 99/102 and 305/335
+    // and had no way to tell they measure different things.
+    const promptHonoured = positives.filter((c) => reach(c, true)).length;
+    const promptIgnored = positives.filter((c) => reach(c, false)).length;
+
+    // The SUMMARY view prints a LOWER pair over the same corpus, and the gap is
+    // not noise. `scoreExact` calls `matchTierRules(router, c.prompt, of)` with
+    // three arguments and drops the case's `command`, so a positive whose rule
+    // is reached by a `command:` trigger scores as a miss there and as a hit
+    // here. Recorded rather than repaired: this phase changes no behaviour, and
+    // the SUMMARY figures are cited in a roadmap and in the prereg. Both
+    // readings are printed so neither view has to be trusted over the other.
+    const summaryHonoured = scoreExact(router, cases, true);
+    const summaryIgnored = scoreExact(router, cases, false);
+
     // (c) A near-miss must never deliver its labelled rule.
     const exact = scoreExact(router, cases, true);
 
@@ -716,7 +745,15 @@ export function runEndpoints(corpusDir: string): EndpointResult[] {
                 `${byRule.size - pathOnlyReach.length}/${byRule.size}; reachable only via a ` +
                 `path trigger: ${pathOnlyReach.length === 0 ? 'none' : pathOnlyReach.join(', ')}` +
                 ` (of which thinned, i.e. at no scope on that route: ` +
-                `${thinnedAndPathOnly.length === 0 ? 'none' : thinnedAndPathOnly.join(', ')})`,
+                `${thinnedAndPathOnly.length === 0 ? 'none' : thinnedAndPathOnly.join(', ')})` +
+                ` | per-prompt reach: ${promptIgnored}/${positives.length} with open_files ` +
+                `IGNORED against ${promptHonoured}/${positives.length} honoured — the same ` +
+                `corpus in prompts rather than in rules, because a rule reachable on one of ` +
+                `twelve positives and one reachable on all twelve are one row above` +
+                ` | SUMMARY prints ${summaryIgnored.hits}/${summaryIgnored.positives} and ` +
+                `${summaryHonoured.hits}/${summaryHonoured.positives} for the same corpus: ` +
+                `scoreExact drops the case's command trigger, so a command-reached positive ` +
+                `misses there and hits here`,
             bar: 'unreachable == 0 (a rule with zero matched positives is a rule the mode removed)',
             passed: unreachable.length === 0,
         },
@@ -781,13 +818,23 @@ export function runSelftest(corpusDir: string): SelftestCase[] {
         });
     } else {
         const id = injection.rules[0] as string;
-        const projected = loadRuleBody(REPO_ROOT, id) ?? '';
-        const mutated = `${projected.trim().slice(0, -1)}~MUTATED~`;
+        // THE DELIVERED FORM, not the raw file. Since step 1.4 the concern emits
+        // `ruleBody` of the projection — frontmatter and HTML comments stripped
+        // by the same parser `project_thin_rules` uses — so comparing against
+        // the raw file asserts a substring the payload no longer contains. The
+        // endpoint's claim is unchanged: the payload carries the body verbatim
+        // and rejects a mutation of it. What "the body" means moved, and this
+        // moved with it.
+        const projected = ruleBody(loadRuleBody(REPO_ROOT, id) ?? '');
+        const mutated = `${projected.slice(0, -1)}~MUTATED~`;
         out.push({
             endpoint: 'a-delivery',
             name: 'one-byte mutation rejected',
-            passed: injection.body.includes(projected.trim()) && !injection.body.includes(mutated),
-            detail: `${id}: the concern's payload carries the projected body verbatim and rejects a mutation of it`,
+            passed:
+                projected !== ''
+                && injection.body.includes(projected)
+                && !injection.body.includes(mutated),
+            detail: `${id}: the concern's payload carries the delivered body verbatim and rejects a mutation of it`,
         });
     }
 

package/src/scripts/prepack-check.mjs

@@ -23,6 +23,7 @@
  * Skip with PREPACK_SKIP_BUILD_CHECK=1 only for local `npm pack` dry-runs
  * that intentionally test the failure mode.
  */
+import { createHash } from 'node:crypto';
 import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { argv, env, exit } from 'node:process';
@@ -66,6 +67,58 @@ if (head !== SHEBANG) {
 
 process.stderr.write(`prepack-check: ${BIN} OK\n`);
 
+// ---------------------------------------------------------------------------
+// Bundle-digest sidecar: `dist/hooks/dispatch.js` must ship with the
+// `dist/hooks/dispatch.sha256` its build wrote, and the digest must still
+// describe the bundle beside it.
+//
+// Risk 3 of road-to-a-kernel-that-guards-its-plumbing: the runtime integrity
+// check treats a MISSING sidecar as `unverifiable` and allows, deliberately,
+// so that a consumer install predating the sidecar is not wedged. That safety
+// property has a cost — a bundle shipped without its sidecar silently disables
+// the check for every consumer who installs it, and nothing at runtime can
+// tell that apart from the legitimate old-package case. The place to catch it
+// is here, in the one step that knows a bundle is being packaged NOW and
+// therefore had no excuse for the sidecar's absence.
+//
+// A stale digest is treated exactly like a missing one: both mean the two
+// files were not produced by the same `npm run build:hooks`.
+const HOOK_BUNDLE = resolve('dist/hooks/dispatch.js');
+const HOOK_SIDECAR = resolve('dist/hooks/dispatch.sha256');
+let hookBundleBytes = null;
+try {
+    hookBundleBytes = readFileSync(HOOK_BUNDLE);
+} catch {
+    // No hook bundle in this tree at all — `npm run build` builds it, and gate
+    // 1 above has already failed if the build did not run. Nothing to check.
+}
+if (hookBundleBytes !== null) {
+    let sidecarText;
+    try {
+        sidecarText = readFileSync(HOOK_SIDECAR, 'utf8');
+    } catch {
+        die(
+            `dist/hooks/dispatch.js ships without dist/hooks/dispatch.sha256. The runtime ` +
+                `integrity check reads a missing sidecar as "unverifiable" and ALLOWS, so ` +
+                `publishing this tarball would silently disable it for every consumer. Run ` +
+                `\`npm run build:hooks\`, which writes both.`,
+        );
+    }
+    const claimed = /^([0-9a-f]{64})\s/u.exec(sidecarText.trim())?.[1] ?? null;
+    if (claimed === null) {
+        die(`dist/hooks/dispatch.sha256 is malformed — expected "<64 hex>  dispatch.js".`);
+    }
+    const actual = createHash('sha256').update(hookBundleBytes).digest('hex');
+    if (actual !== claimed) {
+        die(
+            `dist/hooks/dispatch.sha256 does not describe dist/hooks/dispatch.js ` +
+                `(sidecar ${claimed.slice(0, 12)}…, bundle ${actual.slice(0, 12)}…). The two were ` +
+                `not produced by the same build. Run \`npm run build:hooks\`.`,
+        );
+    }
+    process.stderr.write(`prepack-check: dist/hooks/dispatch.sha256 OK (${actual.slice(0, 12)}…)\n`);
+}
+
 // ---------------------------------------------------------------------------
 // Import-completeness guard: every relative import reachable from the
 // SHIPPED src/ trees must itself resolve to a shipped file. Catches the