@event4u/agent-config 12.0.0 → 12.1.0

package/src/scripts/condense.ts

@@ -1450,7 +1450,31 @@ export interface ClaudePathsPlan {
     /** Patterns to emit under `paths:`, in declaration order. */
     globs: string[];
     /** Patterns deliberately not emitted, with the reason a reader can act on. */
-    dropped: { pattern: string; reason: 'unresolved-placeholder' | 'over-budget' }[];
+    dropped: { pattern: string; reason: 'unresolved-placeholder' | 'over-budget' | 'mixed-triggers' }[];
+}
+
+/**
+ * Does this rule declare any trigger that is NOT path-shaped?
+ *
+ * Load-bearing for `_claude_paths_plan` below, because one `triggers:` list
+ * means two different things on two hosts. Cursor and Windsurf treat globs as
+ * ADDITIVE — a rule with empty globs still reaches the agent through its
+ * description (see `_emit_cursor_mdc`'s own comment). Claude Code treats
+ * `paths:` as EXCLUSIVE: with it the rule loads on a path match; without it the
+ * rule loads unconditionally. The emitter fed both semantics from one list, so
+ * a rule that declared keywords *and* one path glob silently became
+ * path-gated-only on Claude.
+ */
+export function _has_non_path_trigger(meta: Record<string, unknown>): boolean {
+    const triggers = meta['triggers'];
+    if (!Array.isArray(triggers)) return false;
+    for (const t of triggers) {
+        if (t === null || typeof t !== 'object' || Array.isArray(t)) continue;
+        const obj = t as Record<string, unknown>;
+        if (typeof obj['keyword'] === 'string' && obj['keyword']) return true;
+        if (typeof obj['phrase'] === 'string' && obj['phrase']) return true;
+    }
+    return false;
 }
 
 /**
@@ -1470,6 +1494,31 @@ export function _claude_paths_plan(meta: Record<string, unknown>): ClaudePathsPl
     }
     const globs: string[] = [];
     const dropped: ClaudePathsPlan['dropped'] = [];
+
+    // A rule that ALSO declares keyword / phrase triggers gets no `paths:` at
+    // all, and therefore keeps loading unconditionally on Claude Code.
+    //
+    // Emitting `paths:` here would narrow the rule to a path match and discard
+    // every keyword the author wrote, because this host reads the list as the
+    // whole gate rather than as one way in. Measured before this guard: 25 of
+    // 110 projected rules carried `paths:` and 19 of them also carried keyword
+    // triggers — `design-fidelity` lost 21 of them, in exactly the pasted-
+    // screenshot and capability-URL handovers its own routing section names as
+    // the classes it exists to catch. Nothing in the tree recorded a decision
+    // to make that trade, which is why it is treated as a defect.
+    //
+    // The drop is REPORTED rather than silent, so a rule whose obligation
+    // really is path-bound is visible as a candidate for removing its keyword
+    // triggers — the narrowing then becomes an authoring decision instead of an
+    // emitter side effect. Cursor and Windsurf are untouched: globs are
+    // additive there, so the same rule keeps both routes.
+    if (_has_non_path_trigger(meta)) {
+        for (const raw of derive_trigger_globs(meta)) {
+            dropped.push({ pattern: raw, reason: 'mixed-triggers' });
+        }
+        return { globs, dropped };
+    }
+
     let spent = 0;
     for (const raw of derive_trigger_globs(meta)) {
         if (_is_unresolved_placeholder(raw)) {

package/src/scripts/dispatch_r2_reviewer.ts

@@ -222,13 +222,23 @@ export const REVIEW_SCOPE_NAME_ONLY_FLAGS: readonly string[] = [
     '-O/dev/null',
 ];
 
-/** `git diff` argv for the review scope (patch body), config-pinned. */
-export function reviewScopeDiffArgs(base: string): string[] {
+/**
+ * `git diff` argv for the review scope (patch body), config-pinned.
+ *
+ * `head` defaults to `HEAD` — the only value the dispatcher and the validator
+ * ever pass, since both bind the scope being dispatched *now*. It is a
+ * parameter so that an out-of-band measurement can re-derive the scope at a
+ * HISTORICAL revision through this same definition instead of assembling a
+ * second `git diff` argv beside it: a private copy would drift from the
+ * normative flag list above the first time a flag changes, and then report a
+ * hash no gate would ever produce.
+ */
+export function reviewScopeDiffArgs(base: string, head = 'HEAD'): string[] {
     return [
         ...REVIEW_SCOPE_GIT_CONFIG,
         'diff',
         ...REVIEW_SCOPE_DIFF_FLAGS,
-        `${base}...HEAD`,
+        `${base}...${head}`,
         '--',
         ':/',
         ...REVIEW_SCOPE_EXCLUDES,
@@ -236,12 +246,12 @@ export function reviewScopeDiffArgs(base: string): string[] {
 }
 
 /** `git diff --name-only` argv for the review scope (changed-file list), config-pinned. */
-export function reviewScopeNameOnlyArgs(base: string): string[] {
+export function reviewScopeNameOnlyArgs(base: string, head = 'HEAD'): string[] {
     return [
         ...REVIEW_SCOPE_GIT_CONFIG,
         'diff',
         ...REVIEW_SCOPE_NAME_ONLY_FLAGS,
-        `${base}...HEAD`,
+        `${base}...${head}`,
         '--',
         ':/',
         ...REVIEW_SCOPE_EXCLUDES,

package/src/scripts/evidence_report.ts

@@ -29,6 +29,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { workspaceIdentity } from './_lib/git_common_dir.js';
+
 // argparse `prog` is hardcoded to "evidence_report.py" in the retired Python implementation,
 // so usage strings stay byte-identical regardless of the `.py`/`.ts` filename.
 const PROG = 'evidence_report.py';
@@ -39,15 +41,24 @@ const DESCRIPTION = 'Evidence Report template automation.';
 // Repo-root resolution
 // ---------------------------------------------------------------------------
 
-/** Return repo root via git, falling back to relative-path heuristic. */
+/**
+ * Return repo root, falling back to the relative-path heuristic.
+ *
+ * Census row R4. The previous implementation spawned
+ * `git rev-parse --show-toplevel` with **no `cwd` and no env scrub**, so an
+ * inherited `GIT_DIR` (every git hook exports one) silently answered about the
+ * hook's repository instead of this one. `workspaceIdentity()` reads files, so
+ * there is no child process to redirect. The fallback is unchanged, and in a
+ * plain invocation both forms return the same path.
+ */
 function _repo_root(): string {
-    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
-    if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+    const root = workspaceIdentity().repoRoot;
+    if (!root.resolved) {
         // Script lives at src/scripts/; repo root is two levels up.
         const here = fileURLToPath(import.meta.url);
         return path.resolve(path.dirname(here), '..', '..');
     }
-    return result.stdout.trim();
+    return root.value;
 }
 
 function _git_head_short(): string {

package/src/scripts/hook_manifest.yaml

@@ -556,6 +556,30 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-inbox-harvest-2026-08-d-context-ledger Phase 1 Step 1.1 — the
+  # tool-result byte counter. `hook-token-budget.json` registers the gap it
+  # closes in its own words: bytes-into-context from tool RESULTS are
+  # instrumented nowhere, so every context-cost claim in this tree is made
+  # against a denominator missing its dominant term.
+  #
+  # CAPTURE ONLY. It appends `{ts, tool, bytes, measurable}` to a gitignored
+  # census file and emits NOTHING to the model — zero injection bytes, which
+  # is why it carries a metric registration rather than a per-concern byte
+  # cap. The threshold question (when is a result too large) is deliberately
+  # unanswered: the distribution has never been observed, and the house rule
+  # is baseline before mechanism.
+  #
+  # The record type has four fields and none can hold free text — a tool
+  # NAME, a byte COUNT, a timestamp and a measurable flag. Tool results
+  # routinely carry file contents and command output; none of it can reach
+  # this output because the output has no field able to carry it.
+  #
+  # Never blocks, never warns: exit 0 on every path. fail_closed: false.
+  tool-result-bytes:
+    script: src/scripts/hooks/tool_result_bytes_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # road-to-subagent-lifecycle-integrity Phase 3 Step 1 — spawn guard, SHADOW
   # ONLY, per docs/contracts/concern-activation-policy.md. On every Agent/Task
   # call it appends one `spawn_guard_shadow` line recording what a guard WOULD
@@ -623,7 +647,7 @@ platforms:
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
@@ -631,14 +655,24 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape, language-mirror]
-    # round-5 § 6.1 — the ONLY binding on this slot in the tree. `pre_compact`
-    # sets a pin-lost marker; the `post_tool_use` entry above re-emits the pin
-    # exactly once while that marker is set, then clears it. One extra
-    # injection per compaction EVENT — never one per tool call, which is the
-    # shape § 6.2 refuses. claude only: it is the sole verified platform, and
-    # the measured compaction defect is a Claude Code transcript fact.
-    pre_compact:      [language-mirror]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape, language-mirror]
+    # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
+    # the `post_tool_use` entry above re-emits the pin exactly once while that
+    # marker is set, then clears it. One extra injection per compaction EVENT —
+    # never one per tool call, which is the shape § 6.2 refuses. claude only: it
+    # is the sole verified platform, and the measured compaction defect is a
+    # Claude Code transcript fact. (It was the ONLY binding on this slot until
+    # the entry below; that sentence is retired rather than left to rot.)
+    #
+    # `hot-context` — road-to-inbox-harvest-2026-08-d-context-ledger Step 2.1.
+    # This is the one slot that fires WHILE state is being destroyed, and it
+    # carried no WRITER at all: the cache a post-compaction `session_start`
+    # restores was written at the last `stop`, so everything the session did
+    # between that stop and the compaction was lost with it. The concern is
+    # already bound on `stop` and `session_start`; this adds the write at the
+    # moment the loss actually happens. Deterministic rebuild, emits nothing
+    # here — the 4,096-byte row it carries is for its session_start restore.
+    pre_compact:      [language-mirror, hot-context]
     # road-to-subagent-lifecycle-integrity Phase 1 Step 1. `claude` is the only
     # platform where both native events were measured present on the installed
     # binary (2.1.229 — see the evidence page cited on the alias rows below).
@@ -675,7 +709,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges
     # depend on stdout reaching the model, which this trampoline discards by
@@ -698,7 +732,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
   # (project, no file extension, must be executable per Cline docs) or
@@ -713,7 +747,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
   # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
@@ -749,7 +783,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through
   # rule-only fallback; the dispatcher silently no-ops on --platform copilot.

package/src/scripts/hooks/concern_registry.ts

@@ -63,6 +63,7 @@ import { main as editShapeMain } from './edit_shape_hook.js';
 import { main as rereadGuardMain } from './reread_guard_hook.js';
 import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
+import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
@@ -109,5 +110,6 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/reread_guard_hook.ts': rereadGuardMain as ConcernMain,
     'src/scripts/hooks/session_eol_hook.ts': sessionEolMain as ConcernMain,
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
+    'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
 };

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -243,6 +243,27 @@ export function buildRecordInput(facts: DispatchFacts, ts: string, id: string):
 
     if (!facts.isAsync) {
         if (facts.resolvedModel) {
+            // road-to-inbox-harvest-2026-08-d-top-band-model-economy Step 1.1.
+            //
+            // The raw id goes into the field the schema already reserves for it
+            // ("the model id the provider reported SERVING"). Without it, a
+            // dispatch that ran on a band the three-tier vocabulary cannot
+            // express is byte-identical in the record to one where the host
+            // reported no model at all: `extractModelFamily` returns null for
+            // both, so `tiers` is omitted for both.
+            //
+            // That collapse is precisely what blocks ADR-035's reopen
+            // condition. "Did a vendor ship a band the three tiers cannot
+            // express" is answerable only if an unmapped id is distinguishable
+            // from an absent one, and recording the served id separates them:
+            // unmapped ⇒ `model_served` set with `tiers` absent; unreported ⇒
+            // both absent.
+            //
+            // Vendor-neutral by construction: the id is stored verbatim as an
+            // opaque host string. No band above `high` is named and no mapping
+            // is invented — naming a fourth band is the decision this
+            // measurement exists to inform, never one it may pre-empt.
+            input.model_served = facts.resolvedModel;
             const family = extractModelFamily(facts.resolvedModel);
             if (family) input.tiers = [family];
         }

package/src/scripts/hooks/tool_result_bytes_hook.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Tool-result byte counter — capture only, no behaviour change
+ * (road-to-inbox-harvest-2026-08-d-context-ledger Phase 1, Step 1.1).
+ *
+ * Why this exists. `hook-token-budget.json` registers the gap in its own
+ * words: *"bytes-into-context from tool RESULTS is not instrumented
+ * anywhere (the census covers hook payloads only)"*. The injection census
+ * measures what HOOKS put into context — a few kilobytes per turn under a
+ * per-slot cap. It does not measure what TOOLS put into context, which is
+ * the larger number by any plausible margin and the one nobody can cite.
+ * Every claim about context cost in this tree is therefore made against a
+ * denominator that excludes its own dominant term.
+ *
+ * This concern is the instrument and ONLY the instrument. It appends; it
+ * never decides, never advises, and emits nothing to the model. The
+ * threshold question — when is a tool result too large — is deliberately
+ * NOT answered here: the distribution has never been observed, and a
+ * threshold set before the distribution is a number invented rather than
+ * measured. That ordering is the house rule this repository has paid to
+ * learn more than once.
+ *
+ * ── What is recorded, and what is refused ──────────────────────────────
+ *
+ * PRIVACY BY CONSTRUCTION — never widen this file to record content.
+ *
+ * The record type has exactly three fields and NONE of them can hold free
+ * text: a timestamp, a tool NAME (an id-shaped enum — `Read`, `Bash`,
+ * `Grep` — the same single host string `orchestration_record_hook` already
+ * records), and a BYTE COUNT. A tool result routinely carries file
+ * contents, command output, secrets in an env dump, and customer data from
+ * an API response. None of it reaches this file's output, because the
+ * output has no field able to carry it. A record shape that cannot hold a
+ * secret has no scrubber that can fail — the same construction
+ * `domain-safety-pii` § Surface 2 prescribes for logs and the reason the
+ * sibling `subagent-ledger` refuses `last_assistant_message` in any form.
+ *
+ * The result is measured, never read: `_resultBytes` computes a length and
+ * discards the value in the same expression.
+ *
+ * ── Always exit 0 ─────────────────────────────────────────────────────
+ *
+ * A `warn` (exit 2) is read as a hard BLOCK on this host, and this concern
+ * has nothing to say to the model. Every path returns EXIT_ALLOW —
+ * malformed envelope, unparseable payload, unwritable disk. An instrument
+ * that can fail a turn is a mechanism, and this is not one yet.
+ *
+ * ── Absence is recorded, not inferred ─────────────────────────────────
+ *
+ * A payload carrying no readable result writes a line with `bytes: null`
+ * and `measurable: false` rather than writing nothing. The two cases are
+ * otherwise byte-identical in the output — "this host does not carry tool
+ * results in its PostToolUse payload" and "no tools ran" would produce the
+ * same empty file, and the first is a finding about the instrument's own
+ * coverage that the baseline has to be able to see. This is the
+ * instrument-goes-quiet failure the sibling ledger's round-1 review fixed
+ * one layer down, applied here before it can be shipped.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { is_replay_mode } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Census file, relative to the consumer repo root. Sibling of
+ * `injection-census.jsonl` in the same directory and the same
+ * `{ts, …, bytes}` line shape — one family, two units: that file counts
+ * bytes this suite injects, this one counts bytes the host's tools do.
+ * Gitignored via `/agents/runtime/`.
+ */
+export const CENSUS_FILE = path.join('agents', 'runtime', 'state', 'tool-result-census.jsonl');
+
+/** The payload keys a host may use for a tool's result, widest first. */
+const RESULT_KEYS = ['tool_response', 'toolResponse', 'tool_result', 'toolUseResult'] as const;
+
+/**
+ * UTF-8 byte length of a tool result, or `null` when the payload carries
+ * none under any known key.
+ *
+ * A result is an object on most tools and a bare string on some (`Bash`
+ * returns its stdout directly — see the sibling hook's own test corpus), so
+ * both shapes are measured. The sibling's `extractToolResult` returns
+ * `JsonObject | null` and would report a bare-string result as absent,
+ * which is correct for its purpose (it reads named usage fields) and wrong
+ * for this one: a 400 KB command output is exactly the case this counter
+ * exists to see, and it is precisely the shape that extractor drops.
+ *
+ * Bytes, not characters: a multibyte result costs what it costs on the
+ * wire, and `String.length` would under-report it.
+ */
+export function _resultBytes(payload: JsonObject): number | null {
+    for (const key of RESULT_KEYS) {
+        const v = payload[key];
+        if (v === undefined || v === null) continue;
+        if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
+        try {
+            return Buffer.byteLength(JSON.stringify(v), 'utf8');
+        } catch {
+            // Circular or otherwise unserialisable — unmeasurable, not zero.
+            return null;
+        }
+    }
+    return null;
+}
+
+/** The tool's name, read from the same positions the sibling hook reads. */
+export function _toolName(payload: JsonObject, envelope: JsonObject): string | null {
+    const candidates = [
+        payload['tool_name'],
+        payload['toolName'],
+        payload['tool'],
+        envelope['tool_name'],
+        envelope['tool'],
+    ];
+    for (const v of candidates) {
+        if (typeof v === 'string' && v) return v;
+    }
+    return null;
+}
+
+function unwrapPayload(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+/** `${ts.slice(0,7)}` is NOT used here — the census is one flat file, as its sibling is. */
+function censusFile(consumerRoot: string): string {
+    return path.join(consumerRoot, CENSUS_FILE);
+}
+
+export interface CensusLine {
+    ts: string;
+    tool: string | null;
+    bytes: number | null;
+    /** `false` ⇒ the payload carried no readable result. See the header. */
+    measurable: boolean;
+}
+
+export function _appendCensusLine(consumerRoot: string, line: CensusLine): void {
+    if (is_replay_mode()) return;
+    const file = censusFile(consumerRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+}
+
+/** Process an ALREADY-PARSED dispatcher envelope. Always returns EXIT_ALLOW. */
+export function processEnvelope(envelope: JsonValue, consumerRoot: string): number {
+    try {
+        if (!isObject(envelope)) return EXIT_ALLOW;
+        if (envelope['event'] !== 'post_tool_use') return EXIT_ALLOW;
+
+        const payload = unwrapPayload(envelope);
+        const bytes = _resultBytes(payload);
+
+        _appendCensusLine(consumerRoot, {
+            ts: new Date().toISOString(),
+            tool: _toolName(payload, envelope),
+            bytes,
+            measurable: bytes !== null,
+        });
+    } catch {
+        // Malformed payload, unwritable disk, anything — never disturb the run.
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+/** Resolve the consumer repo root, same precedence as the sibling ledger. */
+export function resolveConsumerRoot(envelope: JsonValue): string {
+    if (isObject(envelope)) {
+        for (const key of ['workspace_root', 'project_root']) {
+            const v = envelope[key];
+            if (typeof v === 'string' && v) return v;
+        }
+        const cwd = unwrapPayload(envelope)['cwd'];
+        if (typeof cwd === 'string' && cwd) return cwd;
+    }
+    return process.cwd();
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: JsonValue = {};
+    try {
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, resolveConsumerRoot(envelope));
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());

package/src/scripts/hot_context_hook.ts

@@ -379,7 +379,19 @@ export function main(): number {
         if (_is_replay_mode()) {
             return 0; // replay fixtures: read-only, no state mutation
         }
-        if (event === 'stop' || event === 'session_end') {
+        // `pre_compact` joins the write set (road-to-inbox-harvest-2026-08-d-
+        // context-ledger Step 2.1). It is the only slot that fires WHILE state
+        // is being destroyed, and until now it carried no writer at all: the
+        // cache a post-compaction `session_start` restores was written at the
+        // last `stop`, so everything the session did since then was lost with
+        // the compaction. Writing here makes the restore reflect the moment
+        // before the loss instead of the moment before the last turn.
+        //
+        // Cheap and idempotent by construction: `_write_hot_context` is a
+        // deterministic rebuild from the history file, so an extra fire costs
+        // one rebuild and can never produce a worse cache than the older one it
+        // replaces. It emits nothing — the restore side is unchanged.
+        if (event === 'stop' || event === 'session_end' || event === 'pre_compact') {
             _write_hot_context(root);
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');