@event4u/agent-config 11.0.0 → 12.1.0

package/src/scripts/gen_discovery_baseline.ts

@@ -247,19 +247,19 @@ export function main(): number {
     out.push('');
 
     out.push('## Sample commands (first 10)\n');
-    out.push('| File | name | tier | cluster |');
+    out.push('| File | name | visibility | cluster |');
     out.push('|---|---|---|---|');
     for (const c of commands.slice(0, 10)) {
         const fm = _frontmatter(c);
         const rel = _relativeTo(c, SRC);
-        out.push(`| \`${rel}\` | ${fm.name ?? ''} | ${fm.tier ?? ''} | ${fm.cluster ?? ''} |`);
+        out.push(`| \`${rel}\` | ${fm.name ?? ''} | ${fm.visibility ?? ''} | ${fm.cluster ?? ''} |`);
     }
     out.push('');
 
     out.push('## Notes\n');
     out.push('- Every skill carries `domain:` today — Phase 4 mapping uses it as primary signal.');
     out.push('- Rules use `type` (always | auto) + `tier` (safety-floor | kernel | …); no `domain:` today.');
-    out.push('- Commands use `tier` + `cluster`; no `domain:` today.');
+    out.push('- Commands use `visibility` + `cluster`; no `domain:` today.');
     out.push('- Templates have no consistent frontmatter; Phase 4 quarantines them in `unassigned-artefacts.yml`.');
     out.push('');
 

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
@@ -590,6 +614,26 @@ concerns:
 # blocker: in-process Agent-tool subagents inherit the host process env and
 # cannot be marked per-spawn; the axis binds where the suite launches a CLI
 # session itself.
+#
+# Superseded in part, 2026-08-14 (road-to-subagent-lifecycle-integrity Phase 4
+# Step 2). The env half above still stands — nothing marks an in-process spawn
+# per-process. What has changed is that env is no longer the only candidate
+# channel: `subagent_start` / `subagent_stop` are bound on this host
+# (2.1.229, Phase 0 Step 1) and their payload carries `agent_id`, which
+# `subagent-ledger` correlates on today. So a payload-bound role axis —
+# `agent_id` present ⇒ role `worker` — is a live proposal (Phase 4 Step 1),
+# not a closed question.
+# It is NOT implemented, and the reason is a missing measurement rather than a
+# missing decision: whether `agent_id` reaches a `PreToolUse` / `PostToolUse`
+# payload inside a subagent is unverified on this host. That is Phase 0 Step 4,
+# blocked on `raw-capture-needs-host-env` (the capture itself is already
+# shipped — `dispatch_hook._maybe_capture_payload`). A neighbouring assertion
+# from the same spike already came back negative: `agent_type` does NOT arrive
+# on `SubagentStop` (18 of 25 stop records null), so the documented-field
+# presence is not assumed for `agent_id` either.
+# Until that spike lands the env path is the only one wired, and the
+# pre_tool_use exemption above is unaffected either way — a payload-resolved
+# `worker` still cannot drop a pre_tool_use concern.
 roles:
   worker:
     # Orchestrator-only concerns (Phase 2.3): a worker never talks to the
@@ -603,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]
@@ -611,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).
@@ -655,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
@@ -678,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
@@ -693,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
@@ -729,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/subagent_ledger_hook.ts

@@ -73,8 +73,9 @@
  * a `subagent_reaped` line is written for it. That line is not bookkeeping —
  * it is the closest thing this instrument has to a direct observation of a
  * never-returning dispatch, which is why the leak is reported rather than
- * quietly swept. `session_id` rides on the record so a future sweep can scope
- * by session; nothing reads it yet and it is not claimed to.
+ * quietly swept. `session_id` rides on the open record AND on both dispatch
+ * lines so a rate can be scoped by session; nothing reads it yet and it is not
+ * claimed to.
  *
  * ── Depth and concurrency (Step 3) ────────────────────────────────────────
  *
@@ -598,6 +599,13 @@ function handleStart(root: string, payload: JsonObject, nowIso: string, sessionI
         event: 'subagent_start',
         ts: nowIso,
         ref,
+        // Phase 1 Step 4 correction (b): without this the dispatch denominator
+        // is not per-session. Three sessions share one ledger file, so a rate
+        // computed over the file aggregates strangers — the measured window
+        // held 7 starts against 25 stops, one of them an agent type this
+        // session never dispatched. The open record already carried it; the
+        // appended line did not, and the line is what a rate is computed from.
+        session_id: sessionId,
         agent_type: rec.agent_type,
         parent_ref: parentRef,
         depth,
@@ -606,7 +614,7 @@ function handleStart(root: string, payload: JsonObject, nowIso: string, sessionI
     });
 }
 
-function handleStop(root: string, payload: JsonObject, nowIso: string): void {
+function handleStop(root: string, payload: JsonObject, nowIso: string, sessionId: string | null): void {
     const agentId = str(payload, 'agent_id', 'agentId');
     if (agentId === null) {
         appendUnidentified(root, 'subagent_stop', nowIso, payload);
@@ -631,6 +639,11 @@ function handleStop(root: string, payload: JsonObject, nowIso: string): void {
         event: 'subagent_stop',
         ts: nowIso,
         ref,
+        // The session this stop was OBSERVED in, read from the same envelope
+        // position as the start's — never back-filled from `rec`, which would
+        // relabel a cross-session stop as belonging to the dispatching session
+        // and hide exactly the mismatch this field exists to expose.
+        session_id: sessionId,
         agent_type: rec?.agent_type ?? str(payload, 'agent_type', 'agentType', 'subagent_type', 'subagentType'),
         depth: rec?.depth ?? null,
         depth_basis: rec?.depth_basis ?? null,
@@ -661,7 +674,7 @@ export function processEnvelope(envelope: JsonValue, consumerRoot: string): numb
         reapStaleOpenRecords(consumerRoot, nowIso);
 
         if (event === 'subagent_start') handleStart(consumerRoot, payload, nowIso, sessionId);
-        else handleStop(consumerRoot, payload, nowIso);
+        else handleStop(consumerRoot, payload, nowIso, sessionId);
     } catch {
         // Malformed payload, unreadable disk, anything — never disturb the run.
         return EXIT_ALLOW;

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 ?? '');

package/src/scripts/install.ts

@@ -81,6 +81,12 @@ import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import { collect_drift, format_drift_report } from './_lib/install_drift.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
+// The LIBRARY half, deliberately not `capture_skill_catalogue.js`: that module
+// is a CLI entry with a top-level `process.exit()`, and esbuild would bundle
+// that exit into the installer a consumer loads (`check_installer_import_purity`
+// catches exactly this). The lib has no entry and no exit.
+import * as catalogue from './_lib/skill_catalogue.js';
+import { isInteractiveSession, type SessionProbe } from '../shared/interactiveContext.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
@@ -3899,6 +3905,32 @@ function install_global(
         if (!state.QUIET) warn(`settings-surface snapshot failed — ${String(e)}`);
     }
 
+    // Catalogue-budget warning (road-to-skill-catalogue-budget Phase 1).
+    // Some hosts silently truncate the skill catalogue they were handed: the
+    // deploy reports success, and the model never sees most of what was
+    // deployed. A host that publishes its own dropped count has a MEASURED
+    // ceiling; one that does not gets no warning and no invented number.
+    // Warn only — over-shipping is the safe direction, and a consumer who
+    // accepts truncation is making a legitimate choice.
+    if (!state.QUIET) {
+        try {
+            for (const line of _catalogue_truncation_warnings(deploy_results, project_root)) {
+                warn(line);
+            }
+            const notice = _scoped_migration_notice(deploy_results, project_root, package_root, {
+                env: process.env,
+                stdinTty: process.stdin.isTTY === true,
+                stdoutTty: process.stdout.isTTY === true,
+            });
+            if (notice.length > 0) {
+                process.stdout.write('\n');
+                for (const line of notice) info(line);
+            }
+        } catch {
+            // A measurement must never sink an install that otherwise worked.
+        }
+    }
+
     if (!state.QUIET) {
         process.stdout.write('\n');
         success(`Global install completed (v${installed_version}).`);
@@ -3907,6 +3939,103 @@ function install_global(
     return 0;
 }
 
+/**
+ * One line per deployed host whose catalogue exceeds a ceiling this machine has
+ * actually measured. Empty when nothing has been measured — the observation log
+ * lives where captures accumulate, and an install on a machine that never ran
+ * one has no basis to claim a limit.
+ *
+ * Returns lines rather than printing them so the decision is testable without
+ * capturing stdout.
+ */
+export function _catalogue_truncation_warnings(
+    deploy_results: Record<string, DeployResult>,
+    project_root: string | null,
+): string[] {
+    const log_candidates = [
+        path.join(user_global_paths.event4u_root(), 'state', 'skill-catalogue.jsonl'),
+        ...(project_root ? [path.join(project_root, catalogue.OBSERVATION_LOG)] : []),
+    ];
+    const records = log_candidates.flatMap((p) => catalogue.readObservationLog(p));
+    if (records.length === 0) return [];
+
+    const limits = catalogue.knownHostLimits(records);
+    if (limits.size === 0) return [];
+
+    const lines: string[] = [];
+    for (const tool_id of Object.keys(deploy_results).sort()) {
+        const [, , status] = deploy_results[tool_id] as DeployResult;
+        if (status !== 'deployed') continue;
+        const limit = limits.get(tool_id);
+        if (limit === undefined) continue;
+        const anchor_raw = USER_SCOPE_PATHS[tool_id];
+        if (!anchor_raw) continue;
+
+        const volume = catalogue.measureCatalogueVolume(tool_id, expanduser(anchor_raw));
+        const warning = catalogue.catalogueLimitWarning(volume, limit);
+        if (warning !== null) lines.push(warning);
+    }
+    return lines;
+}
+
+/**
+ * The scoped-projection migration notice for an EXISTING install.
+ *
+ * Shape decided by AI council 2026-08-15 (2/2 converged, both members present):
+ * option B — the existing warning PLUS an interactive notice that persists
+ * NOTHING and names the manual edit and the GUI route. `projection.mode` is
+ * settings class C, so no agent may write it; a notice that offered a CLI
+ * write would send the reader to a command guaranteed to refuse them.
+ *
+ * Eligibility and delivery are separate on purpose. A non-interactive run can
+ * be fully eligible; it simply gets the warning and no notice, and the two
+ * outcomes stay distinguishable instead of collapsing into "nothing printed".
+ *
+ * Known and accepted: with nothing persisted, a qualifying install sees this
+ * on every deploy. The council named that as the strongest argument for doing
+ * nothing at all, and it does not outweigh making a measured, silent
+ * capability loss an explicit human decision.
+ */
+export function _scoped_migration_notice(
+    deploy_results: Record<string, DeployResult>,
+    project_root: string | null,
+    package_root: string,
+    probe: SessionProbe,
+): string[] {
+    if (!isInteractiveSession(probe)) return [];
+
+    const log_candidates = [
+        path.join(user_global_paths.event4u_root(), 'state', 'skill-catalogue.jsonl'),
+        ...(project_root ? [path.join(project_root, catalogue.OBSERVATION_LOG)] : []),
+    ];
+    const limits = catalogue.knownHostLimits(log_candidates.flatMap((p) => catalogue.readObservationLog(p)));
+    if (limits.size === 0) return [];
+
+    const resolved = _resolve_scoped_projection(package_root);
+    const settings_path =
+        _resolve_global_settings_path() ??
+        path.join(user_global_paths.event4u_root(), 'settings', SETTINGS_FILE);
+
+    for (const tool_id of Object.keys(deploy_results).sort()) {
+        const [, , status] = deploy_results[tool_id] as DeployResult;
+        if (status !== 'deployed') continue;
+        const anchor_raw = USER_SCOPE_PATHS[tool_id];
+        if (!anchor_raw) continue;
+
+        const volume = catalogue.measureCatalogueVolume(tool_id, expanduser(anchor_raw));
+        const eligibility = catalogue.migrationEligibility(
+            tool_id,
+            resolved.mode,
+            volume.skillEntries,
+            limits,
+        );
+        if (eligibility.eligible) {
+            return catalogue.migrationPromptLines(tool_id, eligibility, settings_path);
+        }
+    }
+    return [];
+}
+
 const SETTINGS_SURFACE_REL = path.join('state', 'settings-surface.json');
 const SETTINGS_DELTA_REL = path.join('state', 'settings-delta.json');