@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/rule_inject_hook.ts

@@ -36,41 +36,90 @@
  * does. On any other host, and on a `lean_projection.mode: eager-all` rollback,
  * it emits nothing.
  *
+ * THE INSTALL DECLARES THE SCOPE, THE PACKAGE SUPPLIES THE TEXT (step 1.3).
+ * A rule is delivered only when the host's own rule directories carry a file
+ * for it — `~/.claude/rules/` and `<project>/.claude/rules/`, as a union,
+ * because the host loads both. The router is the PACKAGE's list of what could
+ * route and is a larger set: 13 router tier rules are maintainer-only by
+ * `workspaces`, and before this filter a consumer could receive a body for a
+ * rule their install never carried. The two halves cannot be one read — under
+ * `delivery` the installed files are thin stubs by construction, so they can say
+ * WHICH rules are in scope and never WHAT they say. Where no host rule directory
+ * exists at all, nothing declares a scope and no filter applies; see
+ * `rule_layer_overlap.hostRuleLayerIds` for why that is not the empty set.
+ *
+ * THE HOST FORM, BY THE PROJECTOR'S OWN PARSER (step 1.4). Delivered text is
+ * `rule_law_section.ruleBody` of the file: frontmatter and HTML comments
+ * removed. Both are bytes the model cannot act on — the frontmatter is the
+ * routing surface the router has already read, and the comments are authoring
+ * scaffolding no host renders. `project_thin_rules.ts` calls the same function
+ * for the same reason, so "what a stub carries" and "what a delivery carries"
+ * cannot drift into two spellings. A file with nothing left after the strip is
+ * not delivered: an empty `<rule>` element is framing with no content in it.
+ *
+ * ONE STRING THE HOST DOES NOT REPLACE, AND A MANIFEST (step 1.5). Claude Code
+ * substitutes an `additionalContext` over 10,000 CHARACTERS with a path and a
+ * 2,000-character preview, so an oversized delivery does not arrive truncated —
+ * it does not arrive. {@link COMPOSED_CHARS} bounds the whole rule-produced
+ * string at 8,000, and `compose` fills it in the order D1 fixes: the law of
+ * every matched high-consequence rule, then the highest-priority full body that
+ * fits, then further bodies, then the law of everything still unsent, then the
+ * manifest. Nothing is ever cut mid-obligation — a rule whose law alone does not
+ * fit is REPORTED, because half a law reads like a whole one.
+ *
+ * AND EVERY MATCH IS IN THE MANIFEST, labelled `full`, `law`, `omitted_budget`
+ * or `source_unavailable`. A pointer is never labelled delivered. This is where
+ * `selectForInjection`'s `dropped` list is finally read: before it, a body the
+ * byte cap discarded left no trace, so a consumer could not tell a rule that did
+ * not match from one that matched and was thrown away.
+ *
  * ONE MATCHER, SHARED WITH THE OFFLINE MODEL. Everything about selection,
  * ordering, capping and body loading comes from `_lib/rule_injection.ts`, which
  * `model_rule_injection.ts` also imports. Step 0.5 states the reason in as many
  * words: an experiment whose offline pricing and runtime delivery use different
  * matchers measures nothing.
  *
- * ONCE PER SESSION PER RULE, RE-ARMED ON COMPACTION. A rule's body is injected
- * the first time one of its triggers fires and not again, because the model
- * already has it. Compaction is exactly the event that makes that false, so
- * `pre_compact` clears the seen-set — the same pin-lost shape `language-mirror`
- * uses. State lives under `agents/runtime/state/`, the class
- * `context-hygiene.json` already occupies; no new state convention is created.
+ * ONCE PER SESSION PER RULE, RE-ARMED AND RESTORED ON COMPACTION. A rule's body
+ * is injected the first time one of its triggers fires and not again, because
+ * the model already has it. Compaction is exactly the event that makes that
+ * false, so `pre_compact` empties the seen-set — the same pin-lost shape
+ * `language-mirror` uses.
+ *
+ * STATE LIVES UNDER THE USER-GLOBAL ROOT, KEYED BY PROJECT (step 1.7). It used
+ * to be `<workspace>/agents/runtime/state/rule-inject/`, so every consumer
+ * session left dispatcher bookkeeping as untracked files inside someone else's
+ * repository. The seen-set is state about a SESSION, not about the project.
+ * The delivered-row ledger beside it is deliberately NOT moved — see
+ * {@link statePath} for the join that depends on where it is.
  *
  * WHAT IS RE-DELIVERED AFTER A COMPACTION, EXACTLY
- * (road-to-delivery-for-every-host 2.4 — stated because a rule lost at a
- * compaction boundary is lost for the rest of the session, and "re-armed" alone
- * does not say what a reader may rely on):
+ * (road-to-delivery-for-every-host 2.4, amended by step 1.6 — stated because a
+ * rule lost at a compaction boundary used to be lost for the rest of the
+ * session, and "re-armed" alone does not say what a reader may rely on):
  *
- *   · `pre_compact` clears the WHOLE seen-set for that session, not the rules
+ *   · `pre_compact` empties the WHOLE seen-set for that session, not the rules
  *     matched on the compacted turn. There is no per-rule bookkeeping to be
- *     partially wrong about.
+ *     partially wrong about. Since 1.6 it also hands those ids to `pending`
+ *     rather than deleting them — see {@link armRestore}.
  *   · Nothing is delivered BY the compaction itself. The slot emits zero bytes
- *     and exits allow; re-arming is silent.
- *   · A rule's body returns on the NEXT turn whose trigger matches it — which
- *     means a rule whose trigger does not fire again is NOT restored. Delivery
- *     is trigger-driven on both sides of the boundary; compaction resets the
- *     de-duplication, it does not replay a transcript.
- *   · The seen-set is per session, so a compaction in one session re-arms only
- *     that session.
- *
- * Held by three fixtures in `tests/scripts/rule_inject_hook.test.ts` under
- * "once per session per rule, re-armed on compaction": the dedup case, the
- * matched-rule → compaction → matching-turn → body-present case, and the
- * per-session case. All three predate this roadmap; 2.4 adds the contract
- * above, not the coverage, and says so rather than claiming new tests.
+ *     and exits allow; re-arming is silent. It cannot deliver: the host is about
+ *     to discard the context it would emit into.
+ *   · `session_start` with `source: compact` sends the LAW section of every
+ *     rule in that pending set, under the same 8,000-character budget, once.
+ *     That is the half this paragraph used to end at: a rule whose trigger does
+ *     not recur is no longer unrestored. A rule with no law section is reported
+ *     in the manifest rather than having its whole body sent in its place.
+ *   · A rule's BODY still returns on the next turn whose trigger matches it.
+ *     The restore does not re-arm the de-duplication and does not replace
+ *     trigger-driven delivery; it covers the gap between the two.
+ *   · The seen-set is per session, so a compaction in one session re-arms and
+ *     restores only that session.
+ *
+ * Held by fixtures in `tests/scripts/rule_inject_hook.test.ts` under "once per
+ * session per rule" and "re-deliver after a compact", and — for the BINDING
+ * rather than the function — by the dispatcher column in
+ * `rule_inject_foreign_matrix.test.ts`, because a suite that only calls `main()`
+ * stays green over a slot the dispatcher never routes to this concern.
  *
  * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
  * missing router, unreadable body, unwritable state. The one non-zero exit is
@@ -90,29 +139,38 @@
  * claude 2.1.241, three verdicts). Delivery is therefore orchestrator-only, and
  * no third binding is added.
  */
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { hookSectionEnabled, leanProjectionHostsRaw, leanProjectionModeRaw } from '../_lib/hook_settings.js';
-import {
-    deliversBodies,
-    normalizeLeanProjectionMode,
-    resolveLeanProjectionHosts,
-} from '../_lib/lean_projection_mode.js';
+import { hookSectionEnabled } from '../_lib/hook_settings.js';
+import * as user_global_paths from '../_lib/user_global_paths.js';
+import { deliversBodies, resolveLeanProjection } from '../_lib/lean_projection_mode.js';
 import { enforcement_class_from_frontmatter } from '../_lib/obligation_frequency.js';
-import { appendDelivered, stamp, type DeliveredRow } from '../_lib/obligations.js';
 import {
+    appendDelivered,
+    stamp,
+    type DeliveredRow,
+    type WriterInput,
+} from '../_lib/obligations.js';
+import {
+    allTierRules,
+    bytesOf,
     loadRuleBody,
     loadRouter,
     matchTierRules,
+    ruleSources,
     selectForInjection,
+    type SelectionResult,
+    type TierRuleMatch,
 } from '../_lib/rule_injection.js';
+import { readConsequenceClass, stubLawIds } from '../_lib/rule_consequence_class.js';
+import { lawText, ruleBody } from '../_lib/rule_law_section.js';
+import { hostRuleLayerIds } from '../_lib/rule_layer_overlap.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 /**
  * Per-prompt injection ceiling, in UTF-8 BYTES.
@@ -186,45 +244,142 @@ export function workspaceRoot(env: JsonObject): string {
 // ── seen-set state ───────────────────────────────────────────────────────
 
 export interface SeenState {
+    /** Ids already delivered in this session. */
     rules: string[];
+    /**
+     * Ids the compaction boundary took away, waiting for the restore slot.
+     *
+     * IDS, NEVER TEXT. The restore re-reads each rule's law from the corpus; a
+     * seen-set that cached bodies would be a second copy of the rule layer
+     * living in a consumer's state directory, going stale on every upgrade.
+     */
+    pending?: string[];
+}
+
+/**
+ * A stable, readable, collision-free directory name for one project root.
+ *
+ * The basename alone collides — a developer with `~/work/api` and
+ * `~/clients/api` would share a seen-set and silently lose deliveries in both.
+ * The digest alone is unreadable, and this directory is one a human opens when
+ * a delivery looks wrong. Both, so neither problem is the one you get.
+ */
+function projectKey(root: string): string {
+    const abs = path.resolve(root);
+    const name = (path.basename(abs) || 'root').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 40);
+    return `${name}-${createHash('sha256').update(abs, 'utf-8').digest('hex').slice(0, 12)}`;
 }
 
+/**
+ * Where this session's seen-set lives (step 1.7).
+ *
+ * UNDER THE USER-GLOBAL ROOT, KEYED BY PROJECT. It used to be written to
+ * `<workspace>/agents/runtime/state/rule-inject/`, so every consumer session
+ * left dispatcher bookkeeping inside someone else's repository — untracked
+ * files in their `git status`, in a directory their `.gitignore` says nothing
+ * about unless this package's managed block was installed. The seen-set is
+ * state ABOUT a session, not about the project, and the project is the one
+ * place it has no business being.
+ *
+ * THE DELIVERED-ROW LEDGER IS DELIBERATELY NOT MOVED WITH IT.
+ * `recordDelivered` writes through `_lib/obligations.ts`, which resolves under
+ * the project root, and `road-to-a-stop-that-holds` Phase 3 reads those rows
+ * and joins them on the session id. Moving the ledger would be a second,
+ * larger change with a live consumer; moving only the seen-set leaves that join
+ * untouched by construction, because the two were never keyed on each other.
+ *
+ * `EVENT4U_CONFIG_HOME` and `$HOME` resolve the root, so a test points it
+ * somewhere disposable instead of writing into the developer's own state.
+ *
+ * ONE COST, STATED: an upgrade mid-session orphans the old file and the seen-set
+ * reads empty, which re-injects each matched rule once more. Session state is
+ * per session and cheap to rebuild; a migration step for it would be more code
+ * than the duplicate it prevents.
+ */
 export function statePath(root: string, session: string): string {
     const safe = session.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || 'unknown';
-    return path.join(root, 'agents', 'runtime', 'state', 'rule-inject', `${safe}.json`);
+    return path.join(
+        user_global_paths.write_target(path.join('state', 'rule-inject', projectKey(root))),
+        `${safe}.json`,
+    );
 }
 
-export function readSeen(root: string, session: string): Set<string> {
+function readState(root: string, session: string): SeenState {
     try {
         const raw = fs.readFileSync(statePath(root, session), 'utf-8');
         const parsed = JSON.parse(raw) as SeenState;
-        return new Set(Array.isArray(parsed.rules) ? parsed.rules.map(String) : []);
+        return {
+            rules: Array.isArray(parsed.rules) ? parsed.rules.map(String) : [],
+            pending: Array.isArray(parsed.pending) ? parsed.pending.map(String) : [],
+        };
     } catch {
-        return new Set(); // fresh session, or a file nothing can parse
+        return { rules: [], pending: [] }; // fresh session, or a file nothing can parse
     }
 }
 
-export function writeSeen(root: string, session: string, seen: Set<string>): void {
+export function readSeen(root: string, session: string): Set<string> {
+    return new Set(readState(root, session).rules);
+}
+
+function writeState(root: string, session: string, state: SeenState): void {
     const p = statePath(root, session);
     try {
         fs.mkdirSync(path.dirname(p), { recursive: true });
-        const payload: SeenState = { rules: [...seen].sort() };
-        fs.writeFileSync(`${p}.tmp`, `${JSON.stringify(payload)}\n`, 'utf-8');
+        fs.writeFileSync(`${p}.tmp`, `${JSON.stringify(state)}\n`, 'utf-8');
         fs.renameSync(`${p}.tmp`, p);
     } catch {
         /* unwritable state must never fail a turn — worst case a re-injection */
     }
 }
 
-export function clearSeen(root: string, session: string): void {
-    try {
-        fs.rmSync(statePath(root, session), { force: true });
-    } catch {
-        /* ignore */
+export function writeSeen(root: string, session: string, seen: Set<string>): void {
+    const prev = readState(root, session);
+    writeState(root, session, { rules: [...seen].sort(), pending: prev.pending ?? [] });
+}
+
+/**
+ * Hand the seen-set to the restore slot instead of deleting it (step 1.6).
+ *
+ * `pre_compact` used to `rm` this file, which re-armed delivery correctly and
+ * threw away the one thing the restore needs. The de-duplication is still
+ * cleared — `rules` goes empty, so a rule whose trigger fires again gets its
+ * BODY back exactly as before — and the ids move to `pending`, where
+ * `session_start` with `source: compact` reads them and sends each rule's LAW.
+ *
+ * That is the half the header used to end at: a rule whose trigger does not
+ * recur was not restored at all, and a rule lost at a compaction boundary is
+ * lost for the rest of the session.
+ */
+export function armRestore(root: string, session: string): void {
+    const prev = readState(root, session);
+    const pending = [...new Set([...prev.rules, ...(prev.pending ?? [])])].sort();
+    if (pending.length === 0) {
+        try {
+            fs.rmSync(statePath(root, session), { force: true });
+        } catch {
+            /* ignore */
+        }
+        return;
     }
+    writeState(root, session, { rules: [], pending });
+}
+
+/** The ids waiting for the restore slot. */
+export function readPending(root: string, session: string): Set<string> {
+    return new Set(readState(root, session).pending ?? []);
 }
 
-// ── payload extraction ───────────────────────────────────────────────────
+/**
+ * Drop the pending set, once the restore it fed has actually been built.
+ *
+ * SEPARATE FROM THE READ on purpose. A single take-and-clear loses the set when
+ * the build fails, on a slot that does not fire again for that boundary — so
+ * the clear is the caller's last step rather than its first.
+ */
+export function clearPending(root: string, session: string): void {
+    const prev = readState(root, session);
+    if ((prev.pending ?? []).length > 0) writeState(root, session, { rules: prev.rules, pending: [] });
+}
 
 /** The user's prompt, across the shapes the hosts use. */
 export function extractPrompt(payload: JsonObject): string {
@@ -238,12 +393,162 @@ export function extractFilePath(payload: JsonObject): string | null {
     return str(ti, 'file_path', 'path', 'filePath', 'notebook_path');
 }
 
-// ── decision ─────────────────────────────────────────────────────────────
+/**
+ * Per-fire ceiling on the whole rule-produced string, in CHARACTERS (D2).
+ *
+ * CHARACTERS, because that is the unit the host's own threshold is in. Claude
+ * Code replaces an `additionalContext` longer than 10,000 CHARACTERS with a
+ * path and a 2,000-character preview, so a delivery over that line is not
+ * truncated — it is substituted, and the obligation text never arrives at all.
+ *
+ * WHICH STRING IT BOUNDS, stated because the two readings give different
+ * margins and D2's own wording did not separate them. This number bounds the
+ * RULE-PRODUCED string: the `<rule>` elements and the manifest, which is what
+ * this concern emits. The host's 10,000 applies to the `additionalContext` it
+ * assembles, and the other concerns on this slot measured 1,272 characters of
+ * non-rule text. So the margin is 2,000 if the host measures this concern's
+ * payload alone, and **728** if it measures the assembled string — the
+ * conservative reading, and still a margin. 8,000 is safe under both; which
+ * reading is right has not been established here and the smaller number is the
+ * one to plan against.
+ *
+ * IT BOUNDS THE WHOLE STRING, framing and manifest included, because that is
+ * what the host measures. {@link CAP_BYTES} above bounds something else — the
+ * SELECTION, shared byte-for-byte with the offline model — and both still
+ * apply: selection drops whole bodies to stay under the byte cap, then
+ * composition drops or demotes to stay under this one.
+ *
+ * THE TWO CANNOT BREACH EACH OTHER AT ANY RATIO THIS CORPUS PRODUCES, and the
+ * ratio is measured rather than assumed: over the 121 projected rule files the
+ * mean is 1.0088 bytes per character and the per-file maximum is 1.0346
+ * (`no-decorative-emojis-in-git-surfaces.md`), so 8,000 characters is at most
+ * 8,277 bytes against a registered 16,384. A composed string would have to
+ * average 2.05 bytes per character to reach the byte row, which no Markdown
+ * rule corpus produces. `per_concern_caps_chars` in
+ * `src/config/hook-token-budget.json` registers this number in its own unit
+ * rather than converting it into the bytes map, and a fixture pins both.
+ */
+export const COMPOSED_CHARS = 8000;
+
+/**
+ * What a matched rule actually got, as the manifest labels it.
+ *
+ * `full` and `law` mean text arrived. `omitted_budget` and `source_unavailable`
+ * mean it did not, and both are a POINTER — an id the model can ask for. A
+ * pointer is never labelled delivered; that distinction is the whole reason the
+ * manifest has four values instead of a present/absent flag.
+ */
+export type DeliveryForm = 'full' | 'law' | 'omitted_budget' | 'source_unavailable';
+
+/**
+ * The host's own threshold, in the host's own unit (step 0.3).
+ *
+ * Claude Code REPLACES an `additionalContext` longer than this with a path and
+ * a 2,000-character preview. A composed string over this line is therefore not
+ * truncated — it is substituted, and the obligation text never arrives. That is
+ * why this number is the one the arrival record checks against rather than
+ * {@link COMPOSED_CHARS}: 8,000 is the budget this concern holds itself to, and
+ * 10,000 is the line past which the host stops delivering what it was handed.
+ *
+ * WHICH STRING IS MEASURED, stated because risk 5 of this roadmap's register
+ * says the answer is not established. This records the RULE-PRODUCED string,
+ * which is the only one this concern can see. If the host measures the
+ * ASSEMBLED `additionalContext` instead, the real margin is 728 rather than
+ * 2,000 and a reading of 0 here is necessary but not sufficient. The record is
+ * honest about which of the two it is; it does not settle the question.
+ */
+export const HOST_REPLACE_CHARS = 10000;
+
+/**
+ * The three forms step 0.3 names, which is not {@link DeliveryForm}'s four.
+ *
+ * `omitted_budget` and `source_unavailable` are different REASONS for the same
+ * outcome — an id the model can ask for and no text. The arrival record asks
+ * what the model got, so the two collapse to `pointer`; the manifest keeps the
+ * distinction, because a consumer diagnosing a broken install needs the reason
+ * and a reader counting arrivals does not.
+ */
+export type ArrivalForm = 'body' | 'law' | 'pointer';
+
+/**
+ * How far a matched rule got, in the levels D4 fixed (step 0.3).
+ *
+ * - `A0` discoverable — a file or pointer exists.
+ * - `A1` routed — a trigger matched.
+ * - `A2` arrived — the obligation text is in context.
+ * - `A3` enforced — a gate blocks the forbidden outcome.
+ *
+ * THIS CONCERN NEVER WRITES A0 OR A3, and both omissions are deliberate rather
+ * than unimplemented. A0 is the level of a rule that never routed, and this
+ * concern only ever sees rules that did — writing an A0 row per fire for every
+ * rule in the corpus would be a per-turn sweep of the router to record the
+ * absence of an event. A3 belongs to whatever gate refuses the outcome; a
+ * carrier that recorded its own delivery as `enforced` would be the
+ * emitter-record-read-as-compliance mistake the delivered ledger's own header
+ * carries a council lock against.
+ */
+export type ArrivalLevel = 'A0' | 'A1' | 'A2' | 'A3';
+
+/** One matched rule, with what it got and how far that got it. */
+export interface ArrivalRow {
+    readonly rule: string;
+    readonly form: ArrivalForm;
+    readonly arrival: ArrivalLevel;
+}
+
+/** One fire, measured on the composed string in the host's unit. */
+export interface ArrivalRecord {
+    /** The composed string's length in CHARACTERS — what the host counts. */
+    readonly chars: number;
+    /** 1 when this fire was over {@link HOST_REPLACE_CHARS}, else 0. Summing the column gives the over-budget count. */
+    readonly over_budget: number;
+    /** Which slot the fire reached the host on. */
+    readonly slot: string;
+    readonly at: string;
+    readonly rows: readonly ArrivalRow[];
+}
+
+/** The manifest's four reasons, as the three forms a reader of arrivals wants. */
+export function arrivalForm(f: DeliveryForm): ArrivalForm {
+    if (f === 'full') return 'body';
+    if (f === 'law') return 'law';
+    return 'pointer';
+}
+
+/**
+ * What this fire actually delivered, in the host's unit.
+ *
+ * TWO WAYS TO STAY AT A1, and they are different failures with the same
+ * reading. A pointer never carried text in the first place — step 0.3's "a
+ * pointer is never recorded above A1", taken literally. And a composed string
+ * the host REPLACES carried text that the host then did not deliver, so every
+ * row in that fire is A1 however good its form looked: the manifest says `body`
+ * and the model received a path. Recording those as A2 would be the instrument
+ * reporting its own intent instead of the outcome, which is the one thing a
+ * measurement of arrival must not do.
+ */
+export function arrivalRecord(injection: Injection, slot: string, now = stamp()): ArrivalRecord {
+    const chars = injection.body.length;
+    const replaced = chars > HOST_REPLACE_CHARS;
+    return {
+        chars,
+        over_budget: replaced ? 1 : 0,
+        slot,
+        at: now,
+        rows: injection.manifest.map(([rule, f]) => {
+            const form = arrivalForm(f);
+            return { rule, form, arrival: form === 'pointer' || replaced ? 'A1' : 'A2' };
+        }),
+    };
+}
 
 export interface Injection {
+    /** Ids whose TEXT was emitted — what the ledger records. */
     rules: string[];
     bytes: number;
     body: string;
+    /** Every matched rule with the form it got, in router order. */
+    manifest: Array<[string, DeliveryForm]>;
 }
 
 /**
@@ -268,7 +573,7 @@ export interface Injection {
 export function recordDelivered(root: string, session: string, ruleIds: string[]): number {
     try {
         const now = stamp();
-        const rows: DeliveredRow[] = ruleIds.map((id) => {
+        const rows: WriterInput<DeliveredRow>[] = ruleIds.map((id) => {
             const body = loadRuleBody(root, id);
             return {
                 rule: id,
@@ -284,6 +589,256 @@ export function recordDelivered(root: string, session: string, ruleIds: string[]
     }
 }
 
+/**
+ * Ids whose LAW may stand on its own, empty when the config is unreachable.
+ *
+ * `stubLawIds` and not `Object.keys(members)`: the `no_stub` subset is exactly
+ * the members whose law is missing or too long to carry the obligation alone,
+ * which is why the projector ships those full-bodied. Serving one of them its
+ * law here would be the thin-stub defect `rule_consequence_class.ts` exists to
+ * prevent, reproduced at the delivery end — and `stubLawIds` is that module's
+ * own answer, so re-deriving the distinction here would be a second reader of a
+ * class that is supposed to have one.
+ *
+ * MEMOISED PER ROOT. The config is 12 kB of JSON and this runs on the
+ * `user_prompt_submit` hot path; a dispatch is one process and an install does
+ * not change under it.
+ */
+const HI_CACHE = new Map<string, Set<string>>();
+
+function highConsequenceIds(root: string): Set<string> {
+    const hit = HI_CACHE.get(root);
+    if (hit !== undefined) return hit;
+    let out = new Set<string>();
+    for (const r of [root, ruleSources(root).pkg]) {
+        if (r === null) continue;
+        try {
+            out = stubLawIds(readConsequenceClass(r));
+            break;
+        } catch {
+            continue;
+        }
+    }
+    HI_CACHE.set(root, out);
+    return out;
+}
+
+/** The manifest block, which is part of the budgeted string rather than beside it. */
+function manifestText(rows: Array<[string, DeliveryForm]>): string {
+    return `<rule-manifest>\n${rows.map(([id, f]) => `${id}=${f}`).join('\n')}\n</rule-manifest>`;
+}
+
+/**
+ * Compose one fire under {@link COMPOSED_CHARS}, in the order D1 fixes.
+ *
+ * THE ORDER IS A DECISION, not an implementation detail. D1:
+ *
+ *   1. the law of every matched HIGH-CONSEQUENCE rule,
+ *   2. then the highest-priority full body that fits,
+ *   3. then further full bodies,
+ *   4. then the law of everything still unsent,
+ *   5. then the manifest.
+ *
+ * Phase 1 first because a high-consequence rule's law arriving is worth more
+ * than a lower-consequence rule's whole body, and a budget that filled in
+ * priority order alone would spend itself before reaching it.
+ *
+ * PHASE 1 IS A FLOOR AND NEVER A CEILING, which is the half the first
+ * implementation got backwards. A rule served its law in phase 1 can be
+ * UPGRADED to its whole body in phase 2 when the budget still has room for the
+ * difference — `put` replaces the part in place and charges only the delta.
+ * Without that, the 23 class members with a law section could never receive
+ * their body however empty the budget was: `security-sensitive-stop` would have
+ * dropped 5,687 characters to 429 on every fire, and its id still enters the
+ * seen-set, so the body would not have come back later either. D1's "then the
+ * highest-priority full body that fits" reads as a floor and has to behave like
+ * one.
+ *
+ * EVERY MATCHED CLASS MEMBER REACHES PHASE 1, including one the byte cap
+ * dropped. `selectForInjection` ranks on score alone and knows nothing about
+ * the class, so a high-consequence rule can lose that race; D1 says "every
+ * matched", so the text for a dropped class member is loaded here rather than
+ * left unreachable.
+ *
+ * NOTHING IS EVER TRUNCATED. A rule whose law alone does not fit is REPORTED —
+ * `omitted_budget` in the manifest — because half an obligation reads like a
+ * whole one and is the more dangerous output. The manifest's space is reserved
+ * BEFORE any text is admitted, using the longest label for every matched id, so
+ * the report can never be the thing that pushes the string over.
+ *
+ * `sel.dropped` is read here, and that is the point of the step as much as the
+ * budget is: before this, a body dropped by the byte cap left no trace at all,
+ * so a consumer could not tell a rule that did not match from one that matched
+ * and was silently discarded.
+ */
+function compose(
+    root: string,
+    sel: SelectionResult,
+    hi: Set<string>,
+    lawOnly = false,
+): Injection | null {
+    const form = new Map<string, DeliveryForm>();
+    const full = new Map<string, string>();
+    const read = (id: string): void => {
+        const raw = loadRuleBody(root, id);
+        // STEP 1.4 — the host form, by the parser the thin projector uses.
+        // `ruleBody` strips frontmatter and HTML comments: the first is the
+        // routing surface the router already read, the second is authoring
+        // scaffolding no host renders to a model. A file with nothing left after
+        // the strip carries no obligation — an empty `<rule>` element is framing
+        // with no content inside it.
+        const body = raw === null ? '' : ruleBody(raw);
+        if (body === '') {
+            form.set(id, 'source_unavailable');
+            return;
+        }
+        form.set(id, 'omitted_budget');
+        full.set(id, body);
+    };
+    for (const m of sel.dropped) {
+        if (hi.has(m.id)) {
+            read(m.id);
+            continue;
+        }
+        form.set(m.id, (sel.bodyBytes.get(m.id) ?? 0) === 0 ? 'source_unavailable' : 'omitted_budget');
+    }
+    for (const m of sel.selected) read(m.id);
+
+    const all = [...sel.selected, ...sel.dropped].sort((a, b) => a.order - b.order);
+    const tiers = new Map(all.map((m) => [m.id, m.tier]));
+    const reserve = manifestText(all.map((m) => [m.id, 'source_unavailable']));
+    let left = COMPOSED_CHARS - reserve.length - 2;
+    // BOTH UNITS RESERVE THE MANIFEST. The byte row is the registered one, so a
+    // manifest charged against the character budget and not against this one
+    // would let the emission exceed the row it is registered at.
+    let bytesLeft = CAP_BYTES - bytesOf(reserve) - 2;
+    const parts: string[] = [];
+    const partOf = new Map<string, number>();
+    const put = (id: string, kind: 'full' | 'law', text: string): boolean => {
+        const part = `<rule id="${id}" tier="${tiers.get(id) ?? ''}" form="${kind}">\n${text}\n</rule>`;
+        const at = partOf.get(id);
+        const prev = at === undefined ? '' : (parts[at] as string);
+        const sep = at === undefined && parts.length > 0 ? 2 : 0;
+        // BOTH UNITS, INDEPENDENTLY. The measured 1.0346 bytes-per-character
+        // maximum over today's corpus says the character budget binds first, and
+        // a measurement over one corpus is evidence rather than an invariant: a
+        // 6,000-character payload of three-byte code points is 18,000 bytes.
+        // Safety that rests on a ratio stops being safety the day the corpus
+        // changes, so the registered byte row is enforced here too and the ratio
+        // is what makes the second check almost never bind rather than what
+        // makes it unnecessary.
+        const cost = part.length - prev.length + sep;
+        const costBytes = bytesOf(part) - bytesOf(prev) + sep;
+        if (cost > left || costBytes > bytesLeft) return false;
+        left -= cost;
+        bytesLeft -= costBytes;
+        if (at === undefined) {
+            partOf.set(id, parts.length);
+            parts.push(part);
+        } else {
+            parts[at] = part;
+        }
+        form.set(id, kind);
+        return true;
+    };
+
+    const ranked = [...all].sort((a, b) => b.score - a.score || a.order - b.order);
+    for (const m of ranked) {
+        const body = full.get(m.id);
+        if (body === undefined || !hi.has(m.id)) continue;
+        const law = lawText(body);
+        // A class member with no law section cannot be served by phase 1. It is
+        // left to compete for a full body below rather than reported, which is
+        // `no_stub`'s own answer to the same state.
+        if (law !== null) put(m.id, 'law', law);
+    }
+    for (const m of ranked) {
+        const body = full.get(m.id);
+        if (body === undefined || form.get(m.id) === 'full') continue;
+        // A RESTORE SENDS LAWS, with one exception: a rule with NO law section
+        // has no law to send, and reporting it `omitted_budget` would blame a
+        // budget decision nobody made. Those compete for their body instead, so
+        // every label on the restore is true.
+        if (lawOnly && lawText(body) !== null) continue;
+        put(m.id, 'full', body);
+    }
+    for (const m of ranked) {
+        const body = full.get(m.id);
+        if (body === undefined || form.get(m.id) !== 'omitted_budget') continue;
+        const law = lawText(body);
+        if (law !== null) put(m.id, 'law', law);
+    }
+
+    const rows: Array<[string, DeliveryForm]> = all.map((m) => [
+        m.id,
+        form.get(m.id) ?? 'source_unavailable',
+    ]);
+    const ids = rows.filter(([, f]) => f === 'full' || f === 'law').map(([id]) => id);
+    // THE MANIFEST IS BOUNDED TOO, and by construction rather than by how many
+    // rules this router happens to carry. Its space is reserved above at the
+    // longest label, so it always fits what was reserved — but if the RESERVE
+    // itself exceeded the budget (enough matches that the report alone is over
+    // 8,000 characters) the fill loop would admit nothing and the manifest
+    // would be the whole emission, over the cap. No router today comes close;
+    // "no corpus today comes close" is the shape of claim the byte check above
+    // exists because of, so this is a property instead.
+    //
+    // UNDELIVERED ROWS GO FIRST. A row for a rule whose text IS in this string
+    // must never be the one dropped — that would report a delivered rule as
+    // omitted, which is the one thing AC-2 forbids outright.
+    const order = [...rows.keys()].sort(
+        (a, b) =>
+            Number(['full', 'law'].includes((rows[a] as [string, DeliveryForm])[1])) -
+            Number(['full', 'law'].includes((rows[b] as [string, DeliveryForm])[1])),
+    );
+    const head = parts.join('\n\n') + (parts.length > 0 ? '\n\n' : '');
+    let drop = 0;
+    let body = head + manifestText(rows);
+    while (body.length > COMPOSED_CHARS && drop < rows.length) {
+        drop += 1;
+        const cut = new Set(order.slice(0, drop));
+        const kept = rows.filter((_, i) => !cut.has(i));
+        body = head + manifestText([...kept, [`+${drop}`, 'omitted_budget']]);
+    }
+    return { rules: ids, bytes: bytesOf(body), body, manifest: rows };
+}
+
+/**
+ * Build the post-compaction restore, or `null` for silence (step 1.6).
+ *
+ * LAWS, NOT BODIES, and the asymmetry with a normal fire is the point. A
+ * compaction removed text the model was already under; re-sending every body
+ * would re-spend the whole budget on rules whose obligations the session may
+ * never touch again. The law is the part that cannot be inferred from the rest,
+ * so it is what the budget buys back. Everything that does not fit is reported
+ * in the same manifest as any other fire.
+ *
+ * The router supplies each id's tier and declaration order, because the
+ * seen-set deliberately carries neither — see {@link SeenState.pending}.
+ */
+function restore(root: string, ids: Set<string>): Injection | null {
+    if (ids.size === 0) return null;
+    let router;
+    try {
+        router = loadRouter(root);
+    } catch {
+        return null;
+    }
+    const selected: TierRuleMatch[] = [];
+    let order = 0;
+    for (const r of allTierRules(router)) {
+        if (ids.has(r.id)) selected.push({ id: r.id, tier: r.tier, score: 0, order });
+        order += 1;
+    }
+    if (selected.length === 0) return null;
+    return compose(
+        root,
+        { selected, dropped: [], bytes: 0, bodyBytes: new Map() },
+        new Set(selected.map((m) => m.id)),
+        true,
+    );
+}
+
 /**
  * Build the injection for one event, or `null` for silence.
  *
@@ -305,21 +860,30 @@ export function buildInjection(
     } catch {
         return null; // no router — nothing to deliver, and never a failure
     }
+    // STEP 1.3 — the install declares the scope, the package supplies the text.
+    //
+    // The router is the PACKAGE's list of every rule that could route. What a
+    // given consumer is actually under is what their install wrote into the
+    // host's rule directories, and the two are not the same set: 13 router tier
+    // rules are maintainer-only by `workspaces`, and before this filter a
+    // consumer could receive a body for a rule their install never carried.
+    //
+    // The two halves cannot be one read, and that is the reason this is a
+    // filter rather than a different body source. In `delivery` mode the
+    // installed files are thin stubs by construction, so the installed layer can
+    // say WHICH rules are in scope and never WHAT they say; the body still comes
+    // from the package corpus `ruleSources` resolves.
+    //
+    // `null` means no host rule layer exists to declare a scope — see
+    // `hostRuleLayerIds`. No filter then, because scoping to an empty set would
+    // re-create the silence step 1.1 repaired.
+    const scope = hostRuleLayerIds(root);
     const matches = matchTierRules(router, prompt, openFiles, command).filter(
-        (m) => !seen.has(m.id),
+        (m) => !seen.has(m.id) && (scope === null || scope.has(m.id)),
     );
     if (matches.length === 0) return null;
     const sel = selectForInjection(root, matches, CAP_BYTES);
-    const parts: string[] = [];
-    const ids: string[] = [];
-    for (const m of sel.selected) {
-        const body = loadRuleBody(root, m.id);
-        if (body === null) continue;
-        ids.push(m.id);
-        parts.push(`<rule id="${m.id}" tier="${m.tier}">\n${body.trim()}\n</rule>`);
-    }
-    if (ids.length === 0) return null;
-    return { rules: ids, bytes: sel.bytes, body: parts.join('\n\n') };
+    return compose(root, sel, highConsequenceIds(root));
 }
 
 // ── main ─────────────────────────────────────────────────────────────────
@@ -358,10 +922,16 @@ export const DELIVERY_HOST = 'claude-code';
  * to open. `AGENT_CONFIG_REPLAY` re-imposes it, which is what keeps
  * `bench_hook_injection` measuring the configured tree rather than the probe.
  */
-export function gateOpen(root: string, cliEntry: boolean): boolean {
-    const mode = normalizeLeanProjectionMode(leanProjectionModeRaw(root));
-    const hosts = resolveLeanProjectionHosts(leanProjectionHostsRaw(root)).hosts;
-    if (deliversBodies(mode) && hosts.includes(DELIVERY_HOST)) return true;
+export function gateOpen(root: string, cliEntry: boolean, packageRoot?: string | null): boolean {
+    // ONE resolver since step 1.2 — the full cascade (template base, canonical
+    // `agents/settings/`, project root, user-global), not the legacy root file
+    // this concern used to read alone. `packageRoot` is where the template is
+    // found; inside the bundle nothing else can locate it.
+    const { mode, hosts } = resolveLeanProjection({
+        projectRoot: root,
+        packageRoot: packageRoot ?? null,
+    });
+    if (deliversBodies(mode) && hosts.hosts.includes(DELIVERY_HOST)) return true;
     if (hookSectionEnabled(root, 'rule_inject')) return true;
     return cliEntry && process.env['AGENT_CONFIG_REPLAY'] !== '1';
 }
@@ -390,11 +960,38 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const session = str(env, 'session_id', 'sessionId') ?? str(payload, 'session_id', 'sessionId') ?? 'unknown';
 
     if (slot === 'pre_compact') {
-        clearSeen(root, session);
-        return EXIT_ALLOW; // re-arm is silent; the next turn re-injects
+        armRestore(root, session);
+        return EXIT_ALLOW; // re-arm is silent; the restore happens on the next slot
+    }
+    if (slot === 'session_start') {
+        // ONLY on `source: compact`. `startup`, `resume`, `clear` and `fork`
+        // either begin a session that never had a seen-set or hand back a
+        // transcript the host already restored; emitting there would be a
+        // duplicate, and on `fork` a duplicate belonging to a session that is
+        // still alive. An unknown source emits nothing rather than guessing —
+        // the same stance `handoff-context`'s `sourceGate` takes.
+        if ((str(payload, 'source') ?? str(env, 'source')) !== 'compact') return EXIT_ALLOW;
+        if (!gateOpen(root, _isCliEntry(), ruleSources(root).pkg)) return EXIT_ALLOW;
+        // READ, then BUILD, then clear — never clear first. A restore that
+        // fires twice on one boundary is a duplicate delivery, so the set has to
+        // be cleared; clearing it BEFORE the build means a build that fails
+        // (the package moved mid-session, or an upgrade renamed every pending
+        // rule out of the router) loses the set permanently and silently, on the
+        // one slot that does not come round again.
+        const restored = restore(root, readPending(root, session));
+        if (restored === null) return EXIT_ALLOW;
+        clearPending(root, session);
+        recordDelivered(root, session, restored.rules);
+        return emit(restored, slot, root, session);
     }
     if (slot !== 'user_prompt_submit' && slot !== 'pre_tool_use') return EXIT_ALLOW;
-    if (!gateOpen(root, _isCliEntry())) return EXIT_ALLOW;
+
+    // Resolved ONCE, before the gate. The gate needs the package root to find
+    // the settings template and the delivery needs it to find the corpus;
+    // reading the environment and probing the filesystem twice for the same
+    // answer is a cost every hook dispatch on every slot would pay.
+    const src = ruleSources(root);
+    if (!gateOpen(root, _isCliEntry(), src.pkg)) return EXIT_ALLOW;
 
     let prompt = '';
     let openFiles: string[] | null = null;
@@ -412,6 +1009,39 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         openFiles = [fp];
     }
 
+    // Fail CLOSED and SAY SO. An empty delivery is indistinguishable from "no
+    // rule matched", which is the exact silence this concern shipped with; one
+    // line on stderr — which the dispatcher captures — is what makes a broken
+    // install diagnosable from outside this file. Still allow: a carrier that
+    // cannot find its corpus must not fail a turn.
+    if (src.gap !== null) {
+        // Fail CLOSED and SAY SO, through the channel the dispatcher actually
+        // surfaces. Writing to stderr looks right and is not: `_run_concern_inproc`
+        // captures a concern's stderr and `dispatch_hook` re-emits it only at
+        // rc >= 3 (a crash), so a concern exiting allow is silent by
+        // construction — which is the exact failure this diagnostic exists to
+        // end, reproduced one layer up. Found by the 1.8 matrix against the
+        // built bundle; no in-process fixture could have seen it.
+        //
+        // WHERE IT ACTUALLY LANDS, measured against the built bundle rather
+        // than assumed: on Claude Code `emitFor` translates an advisory warn on
+        // this slot into `hookSpecificOutput.additionalContext` at exit 0, so
+        // this line reaches the MODEL, not the operator's terminal. That is the
+        // host's translation and not a choice available here — `reason` alone
+        // has no terminal-facing path on this slot.
+        //
+        // It is the right place anyway: the agent is what the user is talking
+        // to, so an agent told its rule corpus is missing can say so. The cost
+        // is one short line per turn for as long as the install stays broken,
+        // which is bounded and deliberate. Bounding it further — once per
+        // session, via the seen-set — needs a state write this concern cannot
+        // currently afford (`src/config/hook-bundle-budget.json` left 30 bytes
+        // of headroom at this commit), and is recorded in the roadmap rather
+        // than silently skipped.
+        process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: src.gap })}\n`);
+        return EXIT_WARN;
+    }
+
     const seen = readSeen(root, session);
     const injection = buildInjection(root, prompt, openFiles, command, seen);
     if (injection === null) return EXIT_ALLOW; // silence is the default
@@ -420,10 +1050,77 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     writeSeen(root, session, seen);
     recordDelivered(root, session, injection.rules);
 
+    return emit(injection, slot, root, session);
+}
+
+/**
+ * Where this session's arrival record lives (step 0.3).
+ *
+ * BESIDE THE SEEN-SET, under the user-global root and keyed by project, for the
+ * reason step 1.7 moved that one: a measurement about a session is not state
+ * about the project, and a consumer's `git status` is the wrong place to learn
+ * what this dispatcher counted. The delivered-row ledger stays where it is —
+ * `road-to-a-stop-that-holds` Phase 3 joins on it — and this is a different
+ * record with a different reader, so the two do not have to live together.
+ *
+ * JSONL rather than one rewritten object: a fire appends, and an append cannot
+ * lose the rows already written by partially serialising the whole file. The
+ * over-budget COUNT the step asks for is the sum of the `over_budget` column,
+ * which a reader computes; storing a running total here would be a second
+ * number that can disagree with the rows it summarises.
+ */
+export function arrivalPath(root: string, session: string): string {
+    const safe = session.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || 'unknown';
+    return path.join(
+        user_global_paths.write_target(path.join('state', 'rule-inject', projectKey(root))),
+        `${safe}.arrival.jsonl`,
+    );
+}
+
+/**
+ * Append one fire's arrival record, best-effort.
+ *
+ * NEVER THROWS. This is an instrument, and a turn refused because an instrument
+ * missed a reading is worse than the missing reading — the same stance
+ * `appendDelivered` takes, for the same reason.
+ */
+export function recordArrival(root: string, session: string, record: ArrivalRecord): void {
+    try {
+        const p = arrivalPath(root, session);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, `${JSON.stringify(record)}\n`, 'utf-8');
+    } catch {
+        /* an unwritable instrument costs a reading, never a turn */
+    }
+}
+
+/** Read back what this session recorded, dropping any line nothing can parse. */
+export function readArrival(root: string, session: string): ArrivalRecord[] {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(arrivalPath(root, session), 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: ArrivalRecord[] = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '') continue;
+        try {
+            out.push(JSON.parse(line) as ArrivalRecord);
+        } catch {
+            continue; // a torn last line must not cost the rows before it
+        }
+    }
+    return out;
+}
+
+/** The one place a delivery reaches the host, shared by the fire and the restore. */
+function emit(injection: Injection, slot: string, root: string, session: string): number {
+    recordArrival(root, session, arrivalRecord(injection, slot));
     process.stdout.write(
         `${JSON.stringify({
             decision: 'warn',
-            reason: `rule-inject: ${injection.rules.length} rule body/bodies on ${slot} (${injection.bytes} B)`,
+            reason: `rule-inject: ${injection.rules.length}/${injection.manifest.length} matched rule(s) sent on ${slot} (${injection.body.length} chars)`,
             additional_context: injection.body,
         })}\n`,
     );