@event4u/agent-config 17.0.0 → 17.2.0

package/src/config/hook-bundle-budget.json

@@ -4,8 +4,8 @@
     "registered_at": "2026-10-01",
     "owner": "maintainer",
     "review_by": "2027-10-01",
-    "max_bytes": 1550000,
-    "max_bytes_derivation": "Measured 1,514,715 bytes on origin/main at 213d87055 (the gate's own reading, APFS-cloned node_modules so no worktree path artefacts). The ceiling is that reading plus ~2.3 % of headroom, rounded to 1,550,000, on the same doctrine as the 2026-10-01 registration: a bundle is rebuilt from source on every run, so an esbuild minor that renames symbols moves the figure by hundreds of bytes with no change to this tree, and a ceiling one byte above the reading would red on that. Composition is healthy at this reading and was checked rather than assumed: one YAML package (258,833 bytes) and 1,238,525 bytes of own source, so the growth is own code, not a re-entered dependency. The 1,564,211-byte pre-swap regression this roadmap closed still cannot reappear under it.",
+    "max_bytes": 1550500,
+    "max_bytes_derivation": "Measured 1,514,715 bytes on origin/main at 213d87055 (the gate's own reading, APFS-cloned node_modules so no worktree path artefacts). The ceiling is that reading plus ~2.3 % of headroom, rounded to 1,550,000, on the same doctrine as the 2026-10-01 registration: a bundle is rebuilt from source on every run, so an esbuild minor that renames symbols moves the figure by hundreds of bytes with no change to this tree, and a ceiling one byte above the reading would red on that. Composition is healthy at this reading and was checked rather than assumed: one YAML package (258,833 bytes) and 1,238,525 bytes of own source, so the growth is own code, not a re-entered dependency. The 1,564,211-byte pre-swap regression this roadmap closed still cannot reappear under it. RAISED to 1,550,500 on 2026-10-23 for the InstructionsLoaded binding (237 bytes against 51 of headroom); the reasoning and the measured alternative are the last `raise_log` entry, so this paragraph describes the 1,550,000 registration and the raise is recorded there rather than restated.",
     "shrink_only": true,
     "shrink_only_note": "A RAISE needs a recorded reason in `raise_log` below naming what was added and why it could not be avoided. Enforced since road-to-a-ratification-fence-that-follows-its-imports 3.2: the gate reads `max_bytes` at the base revision, and a working value above it fails unless `raise_log` gained an entry whose `to` equals the new value. A lowering needs no entry. This file is also on the ratification gate's watched set, so a raise carries a record as well as a log entry.",
     "raise_log": [
@@ -24,9 +24,18 @@
             "from": 28000,
             "to": 32000,
             "by": "agent, during the feat/subagent-system-2583 run",
-            "what_was_added": "The queued engine work the 28,000 ceiling was sized for, landed together: the validated identifier rows of one-detector 2.3 (IBAN, card, e-mail with a keyed-digest allowlist, three phone shapes, German tax id, US SSN), the invisible-character and lookalike-letter normalisation of 2.5, and three free-tier credential rows (Hugging Face, NVIDIA, Replicate) of free-hands 1.2. Measured 30,445 bytes when the raise landed; 30,493 bytes at the ratified revision, after the round-6 IBAN rows.",
-            "why_it_could_not_be_avoided": "Each addition is a detection row or the normalisation that keeps one from being hidden; the 2026-10-18 derivation already counted them as the chunk's planned growth and underestimated their sum by about 2.4 KB. The chunk is loaded only when a caller needs detection, so no dispatch pays these bytes; the dispatch bundle itself is unchanged.",
+            "what_was_added": "The queued engine work the 28,000 ceiling was sized for, landed together: the validated identifier rows of one-detector 2.3 (IBAN, card, e-mail with a keyed-digest allowlist, three phone shapes, German tax id, US SSN), and three free-tier credential rows (Hugging Face, NVIDIA, Replicate) of free-hands 1.2. The invisible-character normalisation of one-detector 2.5 (`egress_normalize.ts`) is not in this chunk: the engine does not import it (corrected 2026-10-23, road-to-a-tick-the-shipped-path-earns 1.4). Measured 30,445 bytes when the raise landed; 30,493 bytes at the ratified revision, after the round-6 IBAN rows.",
+            "why_it_could_not_be_avoided": "Each addition is an identifier or credential detection row; the 2026-10-18 derivation already counted them as the chunk's planned growth and underestimated their sum by about 2.4 KB. The chunk is loaded only when a caller needs detection, so no dispatch pays these bytes; the dispatch bundle itself is unchanged.",
             "what_would_have_caught_it": "Re-measuring the queued items' sum when the ceiling was set, rather than estimating each."
+        },
+        {
+            "date": "2026-10-23",
+            "from": 1550000,
+            "to": 1550500,
+            "by": "agent, feat/instructions-loaded-binding (road-to-a-setup-that-decides-itself 1.1)",
+            "what_was_added": "The `InstructionsLoaded` binding: one `LAZY_CONCERNS` row for the observer (its 11,097-byte body ships in its own chunk, never in this bundle) and the event name in the three vocabularies the bundle carries (dispatcher, collector, journal). Measured 1,550,186 bytes with the binding by the gate; the same esbuild invocation on the base and on this branch differs by 237 bytes, so the base sat at 1,549,949 — 51 bytes of headroom.",
+            "why_it_could_not_be_avoided": "D8 (council, 2026-10-18) asked for room before a raise. Room was tried and measured: moving `session-eol` (27,708 B in-bundle, `stop` alone) into a chunk freed 29,948 B (same esbuild invocation, with and without the move) but produced a 259,330-byte chunk (`yaml` external) required on every `stop` — about 8.5 times the bytes that event parses today, to buy 186. The observer itself was already moved out. What remains in the bundle is the row and three event-name strings, which no chunk can carry.",
+            "what_would_have_caught_it": "Nothing earlier: the base sat 51 bytes under the ceiling, so any new event in the vocabulary would have tripped it. Sized to this binding plus about 300 bytes; step 3.3's promotion is sized when it is built."
         }
     ],
     "chunks": [
@@ -47,6 +56,12 @@
             "max_bytes": 232000,
             "registered_at": "2026-10-20",
             "derivation": "Measured 209,890 bytes on 2026-10-20, with `yaml` external (inlined it is 472,201 \u2014 a second copy of the parser the dispatch bundle already carries). The ceiling is that reading plus about 10 %, rounded, because this chunk carries a 2,300-line concern plus the memory lookup and FTS index it reads, all of which still grow.\n\nWHY IT WAS MOVED \u2014 AND THE REASON FIRST GIVEN WAS FALSE, which is recorded here rather than corrected silently. This entry said `chat-history` is bound on `session_start` and on no other event, and called it the largest narrow-event module the metafile ranks. An independent provider review of 2026-10-20 checked the manifest and refused the change on it: `chat-history` is bound on FIVE events \u2014 `session_start`, `session_end`, `stop`, `post_tool_use` and `user_prompt_submit` \u2014 across seven hosts. It is close to the widest-bound concern in the tree, not the narrowest. The claim came from reading the `session_start:` rows of the manifest and never the others.\n\nWHAT SURVIVES THE CORRECTION, stated as narrowly as the evidence allows: the move takes 120,586 bytes out of a bundle every hook event parses (1,549,961 -> 1,429,414 B) and pays for them with one `require` of a 209,890-byte CJS file on the events that actually need the concern. Whether that is a latency WIN is UNMEASURED, and the 2026-10-18 council that chose this mechanism asked for exactly that proof inside `src/config/hook-latency-budget.json`. Until it exists this chunk is a byte-budget move with an unproven wall-clock effect, and the honest narrow-event candidates the same metafile ranks are recorded for whoever re-does it: `turn-end-gate` 71,928 B on `stop` alone, `injection-scan` 46,660 B on `post_tool_use` alone, `skill-route` 31,183 B and `git-authorization` 30,761 B on `user_prompt_submit` alone, `session-eol` 27,708 B on `stop` alone, `handoff-context` 25,220 B on `session_start` alone.\n\nUNLIKE THE OTHER TWO CHUNKS this one carries a CONCERN, so there is a correct path behind the fast one: `_run_concern` tries the static registry, then `loadLazyConcern`, then the historical spawn-per-concern path. A missing or mis-digested chunk costs latency, never the concern's effect \u2014 which the same review confirmed, noting it holds because `src/scripts/` ships in the package."
+        },
+        {
+            "entry": "src/scripts/hooks/instructions_observer_hook.ts",
+            "max_bytes": 12000,
+            "registered_at": "2026-10-23",
+            "derivation": "Measured 11,097 bytes on 2026-10-23 (the observe-only `InstructionsLoaded` capture, its classifier, and the CLI entry the spawn fallback needs). The ceiling is that reading plus about 10 %, rounded, with no growth queued. Bound on `instructions_loaded` alone, so a chunk keeps it off every other dispatch's parse; the observer body ships here, never in the dispatch bundle. The binding that reaches it (one registry row and the event name in three vocabularies, 237 bytes) does sit in the bundle and is the 2026-10-23 raise of `max_bytes` recorded in `raise_log`. Like `chat_history` it carries a concern, so a missing chunk falls back to the spawn path and costs latency, never the capture."
         }
     ],
     "chunks_note": "A chunk is loaded only when a caller needs it, so its bytes are not paid by every dispatch; its ceiling exists so that the move out of dispatch.js stays a measured place rather than an unmeasured one. The gate builds each chunk with the exact esbuild segment `build:hook-chunks` uses for its entry.",

package/src/config/hook-token-budget.json

@@ -44,7 +44,7 @@
   "_comment": "Cross-concern per-fire sum per slot (roadmap 3.1). session_start is one-time and may carry the restore payloads; per-turn slots stay tight.",
   "session_start": 16384,
   "user_prompt_submit": 16384,
-  "user_prompt_submit_reason": "RAISED 4096 -> 16384 on 2026-09-07 by road-to-delivery-for-every-host 3.2, under owner ruling E2, which assigns this move to the run that flips `lean_projection.mode: delivery` and is the activation charge the `rule-inject` row below defers to it. THE NUMBER IS MEASURED, NOT CHOSEN: 16,384 is the p90 gate-open fire size of the delivery concern over the frozen `tests/eval/routing-matrix` corpus rounded UP to 512 bytes, exactly as E2 specifies. Distribution over 318 gate-open fires: p50 6,674 B, p90 16,188 B, max 20,406 B. Reproduce it from `_lib/rule_injection.ts::matchTierRules` + `selectForInjection` at `hooks/rule_inject_hook.ts::CAP_BYTES` over that corpus. NOT config weakening, and the guard agrees by its own classification: `hooks/block_config_weakening.ts:96-98` classifies `*-budget.json` as `advisory`, so its decide() path returns `warn` and never a block — treat that warning as expected and documented. `pre_tool_use` is deliberately NOT raised alongside it: the concern's binding on that slot was REMOVED in the same change, so nothing new emits there and its 2,048 stands.",
+  "user_prompt_submit_reason": "RAISED 4096 -> 16384 on 2026-09-07 by road-to-delivery-for-every-host 3.2, under owner ruling E2, which assigns this move to the run that flipped the rule layer to its delivery form (then a settings key, removed by road-to-a-setup-that-decides-itself 4.4) and is the activation charge the `rule-inject` row below defers to it. THE NUMBER IS MEASURED, NOT CHOSEN: 16,384 is the p90 gate-open fire size of the delivery concern over the frozen `tests/eval/routing-matrix` corpus rounded UP to 512 bytes, exactly as E2 specifies. Distribution over 318 gate-open fires: p50 6,674 B, p90 16,188 B, max 20,406 B. Reproduce it from `_lib/rule_injection.ts::matchTierRules` + `selectForInjection` at `hooks/rule_inject_hook.ts::CAP_BYTES` over that corpus. NOT config weakening, and the guard agrees by its own classification: `hooks/block_config_weakening.ts:96-98` classifies `*-budget.json` as `advisory`, so its decide() path returns `warn` and never a block — treat that warning as expected and documented. `pre_tool_use` is deliberately NOT raised alongside it: the concern's binding on that slot was REMOVED in the same change, so nothing new emits there and its 2,048 stands.",
   "pre_tool_use": 2048,
   "post_tool_use": 2048,
   "stop": 2048,

package/src/config/packed-binary-manifest.json

@@ -28,6 +28,33 @@
       "grammar_id": "javascript",
       "abi": 14,
       "why": "The JavaScript grammar. Same reason as the php entry."
+    },
+    {
+      "path": "src/vendor/grammars/tree-sitter-python.wasm",
+      "sha256": "9056d0fb0c337810d019fae350e8167786119da98f0f282aceae7ab89ee8253b",
+      "size": 476105,
+      "kind": "tree-sitter-wasm-grammar",
+      "grammar_id": "python",
+      "abi": 14,
+      "why": "The Python grammar (road-to-a-map-that-draws-itself 6.1). Same reason as the php entry: the engine indexes .py files in a consumer install with no manual parser step."
+    },
+    {
+      "path": "src/vendor/grammars/tree-sitter-go.wasm",
+      "sha256": "9963ca89b616eaf04b08a43bc1fb0f07b85395bec313330851f1f1ead2f755b6",
+      "size": 235957,
+      "kind": "tree-sitter-wasm-grammar",
+      "grammar_id": "go",
+      "abi": 14,
+      "why": "The Go grammar (road-to-a-map-that-draws-itself 6.1). Same reason as the php entry: the engine indexes .go files in a consumer install with no manual parser step."
+    },
+    {
+      "path": "src/vendor/grammars/tree-sitter-java.wasm",
+      "sha256": "637aac4415fb39a211a4f4292d63c66b5ce9c32fa2cd35464af4f681d91b9a1f",
+      "size": 430239,
+      "kind": "tree-sitter-wasm-grammar",
+      "grammar_id": "java",
+      "abi": 14,
+      "why": "The Java grammar (road-to-a-map-that-draws-itself 6.1). Same reason as the php entry: the engine indexes .java files in a consumer install with no manual parser step."
     }
   ]
 }

package/src/config/production-entries.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Production entries for check_step_production_reach (road-to-a-tick-the-shipped-path-earns 3.1). `entries` are modules a host or a consumer runs directly. `entry_sources` are files that name runnable scripts by path (`src/scripts/<name>`, with or without `.ts`); every script they name is an entry too. Projected subagent definitions are markdown read by the host, not imported, so they are not entries here: a step about one names its generator with `production entry: <path>`.",
+  "entries": [
+    "src/scripts/hooks/dispatch_hook.ts",
+    "src/cli/agent-config.ts",
+    "src/server/app.ts"
+  ],
+  "entry_sources": [
+    "src/scripts/_dispatch.bash",
+    "Taskfile.yml",
+    "taskfiles/*.yml",
+    "hooks/hooks.json",
+    ".github/workflows/*.yml",
+    "src/agent-src/commands/**/*.md",
+    "src/domains/**/*.md",
+    "src/skills/**/SKILL.md"
+  ]
+}

package/src/config/release-gate-locality.yml

@@ -106,13 +106,6 @@ jobs:
     script: src/scripts/check_template_pin_drift.ts
     guard: ~
 
-  finding-dispositions:
-    local: './scripts-run src/scripts/check_finding_dispositions --release ${VERSION}'
-    verify: false
-    reason: 'NEEDS_PR: the unrecorded-findings half reads live PR review comments. The missing-dispositions half does run locally and is what the `local` command covers.'
-    script: src/scripts/check_finding_dispositions.ts
-    guard: ~
-
   audit-gate:
     local: 'npm audit --omit=dev --audit-level=high'
     verify: true

package/src/config/skill-body-budget.json

@@ -38,7 +38,7 @@
     "character-consistency": 8555,
     "check-refs": 4188,
     "churn-prevention": 8014,
-    "code-intelligence": 16492,
+    "code-intelligence": 16998,
     "code-refactoring": 13717,
     "code-review": 16261,
     "command-routing": 6040,
@@ -681,6 +681,12 @@
       "old": 7434,
       "new": 8465,
       "reason": "A § Free tiers table (where a free tier's quota, data-use and region terms are read live, plus the never-send-project-data-to-a-training-tier line) so the skill answers 'set up a free LLM API' without copying any model id or limit. road-to-free-hands-a-paid-head-checks 7.1."
+    },
+    {
+      "skill": "code-intelligence",
+      "old": 16492,
+      "new": 16998,
+      "reason": "road-to-a-map-that-draws-itself (ADR-297): step 0 sends an orientation question to agents/map/MAP.md before any graph query, and the MCP table gains rows for graph_map_status and graph_area. Both are the skill's routing surface for the new map; trimming them would hide the tools the roadmap added."
     }
   ]
 }

package/src/install/claudeRuleRewrite.ts

@@ -48,6 +48,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { _claude_paths_plan } from './claudePathsPlan.js';
+// Re-exported for `install.ts`, which sits past the source-size ceiling and so
+// reaches it through the namespace it already imports instead of a new line.
+export { onlyDeployed } from './loggedWrites.js';
 import { parseFrontmatter } from './ruleInScope.js';
 
 /**
@@ -134,8 +137,9 @@ export function rewriteAndReport(
     warn: (m: string) => void,
     wrappers?: { wrapped: readonly string[]; reserved: readonly string[]; foreign?: readonly string[] },
     preserved: ReadonlySet<string> = new Set(),
+    onWrite?: (target: string) => void,
 ): ClaudeRuleRewriteResult {
-    const result = rewriteClaudeRules(rulesDir, preserved);
+    const result = rewriteClaudeRules(rulesDir, preserved, onWrite);
     // The flat-command wrapper report rides along rather than sitting at the
     // call site: `install.ts` is thousands of lines past
     // `check_source_size_budget`'s ceiling, and this module is the one place
@@ -248,10 +252,14 @@ export function renderClaudeRule(sourceText: string): {
  * disappearing from the frontmatter.
  *
  * Returns counts rather than printing. The caller owns the reporting surface.
+ * `onWrite` receives each rewritten path, so the installer can log it: the
+ * transaction log is read back as proof the bytes on disk are ours, and a
+ * write it never saw would leave every rewritten rule unprovable.
  */
 export function rewriteClaudeRules(
     rulesDir: string,
     preserved: ReadonlySet<string> = new Set(),
+    onWrite?: (target: string) => void,
 ): ClaudeRuleRewriteResult {
     const result: ClaudeRuleRewriteResult = { rewritten: 0, scoped: [], dropped: [], failed: [] };
     let entries: string[];
@@ -299,6 +307,7 @@ export function rewriteClaudeRules(
                 });
                 continue;
             }
+            onWrite?.(full);
             result.rewritten += 1;
         }
         const stem = name.slice(0, -3);

package/src/install/conflict.ts

@@ -18,7 +18,8 @@
 import { existsSync } from 'node:fs';
 
 import { sha256File } from './plan.js';
-import { isLedgerMigration } from './preserve.js';
+import { loggedWriteDigests, wroteTheseBytes, type LoggedWrites } from './loggedWrites.js';
+import { isLedgerMigration, logProofApplies, sidecarPathFor } from './preserve.js';
 import {
     classifyOwnership,
     ledgerListedPaths,
@@ -200,10 +201,13 @@ export const CONFLICT_BATCH_THRESHOLD = 5;
  *
  * `recorded` is injectable for tests; by default it is read from the
  * manifest at `plan.root`, with the user-scoped ownership ledger laid over it.
+ * `logged` likewise; by default it is the install transaction log, opened only
+ * for an entry `logProofApplies` to.
  */
 export function computeConflicts(
     plan: InstallPlan,
     recordedOverride?: RecordedHashes,
+    loggedOverride?: LoggedWrites,
 ): readonly ConflictEntry[] {
     // Force returns before the manifest is read. As a default parameter the
     // map was built at call entry and discarded on the next line, so every
@@ -214,6 +218,7 @@ export function computeConflicts(
     // digests never reaches the branch that needs this, and an unconditional
     // read would charge every plan for an answer most of them discard.
     let ledgerFiles: ReadonlySet<string> | null = null;
+    let logged: LoggedWrites | undefined;
     const ledgerLists = (p: string): boolean => {
         ledgerFiles ??= ledgerListedPaths();
         return ledgerFiles.has(p);
@@ -234,6 +239,24 @@ export function computeConflicts(
             const onDisk = sha256File(entry.path);
             const ownership = classifyOwnership(recorded.get(entry.path), onDisk);
             if (ownership === 'recorded-unchanged') continue;
+            // The writer's transaction-log proof, under the writer's own
+            // condition (`logProofApplies`): where it holds and the log records
+            // these bytes, the writer replaces the file, so the preview must
+            // not name it.
+            const recordedSha = recorded.get(entry.path);
+            const unproven = {
+                exists: true,
+                recordedSha256: recordedSha,
+                onDiskSha256: onDisk,
+                force: false,
+                ledgerListed: ledgerLists(entry.path),
+                recordedIsStaged:
+                    typeof recordedSha === 'string' && recordedSha === recorded.get(sidecarPathFor(entry.path)),
+            };
+            if (logProofApplies(unproven)) {
+                logged ??= loggedOverride ?? loggedWriteDigests();
+                if (wroteTheseBytes(entry.path, onDisk as string, logged)) continue;
+            }
             if (ownership === 'unknown' && plan.policy.knownPaths.has(entry.path)) continue;
             // CANDIDACY, not the verdict, and it is computed BEFORE the
             // equality short-circuit below rather than after. The migration

package/src/install/conflictTracker.ts

@@ -28,11 +28,13 @@ import {
     decideDeployWrite,
     foreignSidecarMessage,
     isLedgerMigration,
+    logProofApplies,
     migrationPreservedMessage,
     preservedFileMessage,
     sidecarPathFor,
     type DeployWriteDecision,
 } from './preserve.js';
+import { loggedWriteDigests, wroteTheseBytes, type LoggedWrites } from './loggedWrites.js';
 import { ledgerListedPaths, recordedHashesWithLedger, type RecordedHashes } from './recordedOwnership.js';
 
 /**
@@ -89,6 +91,8 @@ export interface ConflictState {
      * compare a file against a listing this very run had just produced.
      */
     ledgerFiles: ReadonlySet<string> | null;
+    /** The transaction log's writes, read lazily once per run for the same reason. */
+    logged: LoggedWrites | null;
     preserved: string[];
     /**
      * Targets this run preserved on the migration branch.
@@ -148,6 +152,7 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
         root: null,
         recorded: null,
         ledgerFiles: null,
+        logged: null,
         preserved: [],
         migrated: new Set(),
         staged: new Map(),
@@ -331,6 +336,7 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
             conflictState.root = root;
             conflictState.recorded = null;
             conflictState.ledgerFiles = null;
+            conflictState.logged = null;
             conflictState.preserved = [];
             conflictState.migrated = new Set();
             conflictState.staged = new Map();
@@ -344,13 +350,23 @@ export function createConflictTracker(host: ConflictTrackerHost): ConflictTracke
          */
         resolve(target: string, force: boolean, would: WouldWrite): DeployWriteDecision {
             const exists = pathExists(target);
-            const base = {
+            const recordedSha256 = exists ? recordedHashFor(target) : undefined;
+            const unproven = {
                 exists,
-                recordedSha256: exists ? recordedHashFor(target) : undefined,
+                recordedSha256,
                 onDiskSha256: exists ? sha256OfFile(target) : null,
                 force,
                 ledgerListed: exists && ledgerLists(target),
+                recordedIsStaged:
+                    typeof recordedSha256 === 'string' && recordedSha256 === recordedHashFor(sidecarPathFor(target)),
             };
+            // The log is opened only where the record alone would preserve
+            // without cause, and read once per run: this run's own appends
+            // cannot prove a file it has not reached yet.
+            const loggedWrite =
+                logProofApplies(unproven) &&
+                wroteTheseBytes(target, unproven.onDiskSha256 as string, (conflictState.logged ??= loggedWriteDigests()));
+            const base = { ...unproven, loggedWrite };
             // The packaged digest costs a temp write and a tag, so it is
             // computed only for the targets that can consume it. On a tree
             // where every ledger-listed path carries a digest — which is every

package/src/install/installThinLayer.ts

@@ -109,6 +109,11 @@ export interface ThinInstalledLayerOptions {
      * the staged runtime, which outlives a cleared package-manager cache.
      */
     readonly bodyLinkRoot?: string | null;
+    /**
+     * Called with each path this pass rewrote — the installer logs it, because
+     * the transaction log is read back as proof the bytes on disk are ours.
+     */
+    readonly onWrite?: (target: string) => void;
 }
 
 /**
@@ -212,6 +217,7 @@ export function thinInstalledRuleLayer(opts: ThinInstalledLayerOptions): ThinIns
         try {
             if (next !== installed) {
                 fs.writeFileSync(target, next, 'utf-8');
+                opts.onWrite?.(target);
                 rewritten += 1;
             }
             thinned += 1;

package/src/install/loggedWrites.ts

@@ -0,0 +1,148 @@
+/**
+ * The install transaction log read as an ownership record.
+ *
+ * WHY. The writer preserves any managed file it cannot prove is still the bytes
+ * it wrote. For a file deployed before the ownership ledger recorded digests,
+ * the ledger has nothing to compare against, so EVERY such file was preserved
+ * and a sidecar staged beside it — thousands of them on one upgrade, all
+ * untouched. Worse, the ledger then records the staged digest for each target,
+ * so the next run calls the same untouched file "user-modified".
+ *
+ * The proof was on disk the whole time. `src/scripts/install.ts` appends a
+ * `write` entry carrying the SHA-256 of the target's bytes immediately after
+ * every copy. A file whose bytes equal a digest the log records this installer
+ * writing to that exact path is the installer's own output, unedited. A path
+ * with no matching record keeps the existing answer. WHEN that proof may decide
+ * is narrower than "whenever it matches" — see `decideDeployWrite`.
+ *
+ * WHAT IS READ. The active log and every rotated sibling, plain or gzipped
+ * (`txlog.ts` rotates at 10 MB or 30 days, and the gzip step can leave both
+ * forms behind). An unreadable or truncated file contributes nothing — the
+ * failure direction is "no proof", which preserves.
+ *
+ * COST. Parsed per FILE and cached on that file's size and mtime. A rotated
+ * archive never changes, so only the active log is re-read when it grows — and
+ * an install appends to it after every file it touches, so a cache keyed on the
+ * whole set would re-parse the entire history once per candidate.
+ */
+
+import { gunzipSync } from 'node:zlib';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+
+import { getLogPath } from './paths.js';
+
+/** Absolute target path → every digest the log records this installer writing there. */
+export type LoggedWrites = ReadonlyMap<string, ReadonlySet<string>>;
+
+const WRITE_MARKER = '"kind":"write"';
+
+const fileCache = new Map<string, { readonly stamp: string; readonly entries: ReadonlyArray<readonly [string, string]> }>();
+const dirRealpaths = new Map<string, string>();
+
+/**
+ * One canonical spelling for a path: its directory realpath'd, its basename
+ * kept. Both the log keys and the queries go through it, so `/var/…` and its
+ * macOS realpath twin meet. The directory is realpath'd rather than the file
+ * because the file may not exist, and is memoised because a log names a few
+ * hundred directories across tens of thousands of entries.
+ */
+export function canonicalPath(p: string): string {
+    const abs = resolve(p);
+    const dir = dirname(abs);
+    let real = dirRealpaths.get(dir);
+    if (real === undefined) {
+        try {
+            real = realpathSync(dir);
+        } catch {
+            real = dir;
+        }
+        dirRealpaths.set(dir, real);
+    }
+    return join(real, basename(abs));
+}
+
+/** The active log plus its rotated siblings, sorted by name. */
+function logFiles(logPath: string): string[] {
+    const dir = dirname(logPath);
+    if (!existsSync(dir)) return [];
+    const stem = basename(logPath).replace(/\.jsonl$/, '');
+    try {
+        return readdirSync(dir)
+            .filter((n) => n.startsWith(stem) && (n.endsWith('.jsonl') || n.endsWith('.jsonl.gz')))
+            .map((n) => join(dir, n))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+function writesIn(file: string): ReadonlyArray<readonly [string, string]> {
+    let stamp: string;
+    try {
+        const st = statSync(file);
+        stamp = `${st.size}:${Math.trunc(st.mtimeMs)}`;
+    } catch {
+        return [];
+    }
+    const cached = fileCache.get(file);
+    if (cached !== undefined && cached.stamp === stamp) return cached.entries;
+
+    let text = '';
+    try {
+        const raw = readFileSync(file);
+        text = (file.endsWith('.gz') ? gunzipSync(raw) : raw).toString('utf8');
+    } catch {
+        text = '';
+    }
+    const entries: Array<readonly [string, string]> = [];
+    for (const line of text.split('\n')) {
+        if (!line.includes(WRITE_MARKER)) continue;
+        let entry: { path?: unknown; sha256?: unknown };
+        try {
+            entry = JSON.parse(line) as { path?: unknown; sha256?: unknown };
+        } catch {
+            continue;
+        }
+        if (typeof entry.path !== 'string' || typeof entry.sha256 !== 'string' || entry.sha256 === '') continue;
+        entries.push([canonicalPath(entry.path), entry.sha256]);
+    }
+    fileCache.set(file, { stamp, entries });
+    return entries;
+}
+
+/** Every `write` the transaction log records, keyed by canonical path. */
+export function loggedWriteDigests(logPath: string = getLogPath()): LoggedWrites {
+    const writes = new Map<string, Set<string>>();
+    for (const file of logFiles(logPath)) {
+        for (const [target, sha] of writesIn(file)) {
+            let set = writes.get(target);
+            if (set === undefined) writes.set(target, (set = new Set()));
+            set.add(sha);
+        }
+    }
+    return writes;
+}
+
+/**
+ * Wrap a log writer so it records only paths this run's copy deploys.
+ *
+ * The claude-code rewrite and thinning passes walk the whole rule directory,
+ * including rules the user authored there; logging those rewrites would make
+ * the log vouch for content that was never the package's.
+ */
+export function onlyDeployed(
+    anchor: string,
+    currentFiles: ReadonlySet<string>,
+    log: (target: string) => void,
+): (target: string) => void {
+    return (target) => {
+        const rel = relative(resolve(anchor), resolve(target)).split(sep).join('/');
+        if (currentFiles.has(rel)) log(target);
+    };
+}
+
+/** Did this installer write exactly `onDiskSha256` to `target`? */
+export function wroteTheseBytes(target: string, onDiskSha256: string, writes: LoggedWrites): boolean {
+    return writes.get(canonicalPath(target))?.has(onDiskSha256) === true;
+}

package/src/install/paths.ts

@@ -69,12 +69,21 @@ export function getInstallRoot(home?: string): string {
 }
 
 /**
- * Absolute path to the active transaction log:
- * `~/.event4u/agent-config/install-log.jsonl`.
+ * Absolute path to the active transaction log: `install-log.jsonl` in
+ * `$EVENT4U_CONFIG_HOME` when that is set and no explicit `home` is given,
+ * otherwise in `~/.event4u/agent-config/`.
  *
  * Phase A4 writers append here on every successful atomic rename.
+ *
+ * Without the variable, the hermetic test environment — which sets only that
+ * variable — appended every test install to the real user's log, and the log
+ * is now read back as ownership proof. A history written under the other root
+ * before a user switched roots is not read; the failure direction is "no
+ * proof", which preserves.
  */
 export function getLogPath(home?: string): string {
+    const configHome = home ? undefined : process.env['EVENT4U_CONFIG_HOME'];
+    if (configHome) return join(configHome, INSTALL_LOG_FILENAME);
     return join(getInstallRoot(home), INSTALL_LOG_FILENAME);
 }
 

package/src/install/preserve.ts

@@ -109,6 +109,23 @@ export interface DeployWriteInputs {
      * `null` when the file could not be read.
      */
     readonly onDiskSha256: string | null;
+    /**
+     * True when the install transaction log records this installer writing
+     * exactly the bytes now on disk to this path (`./loggedWrites.ts`).
+     * Absent means false. Decides only where {@link logProofApplies} says so.
+     */
+    readonly loggedWrite?: boolean;
+    /**
+     * True when the recorded digest is the one this installer STAGED beside the
+     * target as a sidecar, rather than bytes it wrote to the target itself.
+     *
+     * The ledger records a preserved target under the staged digest, so such a
+     * target reads `recorded-modified` without anyone having edited it. Only
+     * then may the log override the record: a recorded digest of bytes we DID
+     * write diverging from disk is a real edit — including a user restoring an
+     * older shipped version on purpose, which the log would also match.
+     */
+    readonly recordedIsStaged?: boolean;
     /** True when the run carries `--force`. */
     readonly force: boolean;
 }
@@ -135,18 +152,36 @@ export interface DeployWriteInputs {
  * behaviour stands rather than being changed on a case nobody reasoned about.
  */
 export function isLedgerMigration(inputs: Omit<DeployWriteInputs, 'packagedSha256'>): boolean {
-    if (!inputs.exists || inputs.force) return false;
+    if (!inputs.exists || inputs.force || inputs.loggedWrite === true) return false;
     if (inputs.ledgerListed !== true) return false;
     if (inputs.onDiskSha256 === null) return false;
     return classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256) === 'unknown';
 }
 
+/**
+ * May the transaction-log proof decide this target? Only where the verdict
+ * would otherwise be a preservation the record cannot justify: a ledger-listed
+ * file with no digest (the migration branch), or a `recorded-modified` file
+ * whose recorded digest is a staged one. Everywhere else the log is not read —
+ * the ledger alone already decides, and a genuine edit must stay preserved.
+ */
+export function logProofApplies(inputs: Omit<DeployWriteInputs, 'packagedSha256' | 'loggedWrite'>): boolean {
+    if (!inputs.exists || inputs.force || inputs.onDiskSha256 === null) return false;
+    const ownership = classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256);
+    if (ownership === 'recorded-modified') return inputs.recordedIsStaged === true;
+    // `loggedWrite` is cleared because `isLedgerMigration` excludes a proven
+    // target, and this asks whether the target is a candidate BEFORE the proof.
+    return ownership === 'unknown' && isLedgerMigration({ ...inputs, loggedWrite: false });
+}
+
 /**
  * Decide whether the writer may replace one managed file.
  *
- * A target that does not exist is written. A forced run writes. Otherwise the
- * recorded-ownership verdict decides: `recorded-modified` preserves, and
- * `recorded-unchanged` writes.
+ * A target that does not exist is written. A forced run writes. A target whose
+ * bytes the transaction log records this installer writing there is written
+ * where {@link logProofApplies} — there is no edit to lose. Otherwise the
+ * recorded-ownership verdict decides:
+ * `recorded-modified` preserves, and `recorded-unchanged` writes.
  *
  * The `unknown` arm is the one worth stating out loud. No recorded digest
  * means no divergence to measure — a tree with no manifest, a global anchor
@@ -169,6 +204,7 @@ export function isLedgerMigration(inputs: Omit<DeployWriteInputs, 'packagedSha25
 export function decideDeployWrite(inputs: DeployWriteInputs): DeployWriteDecision {
     if (!inputs.exists) return 'write';
     if (inputs.force) return 'write';
+    if (inputs.loggedWrite === true && logProofApplies(inputs)) return 'write';
     const ownership = classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256);
     if (ownership === 'recorded-modified') return 'preserve';
     if (ownership === 'unknown' && isLedgerMigration(inputs)) {

package/src/install/txlog.ts

@@ -6,14 +6,18 @@
  * nothing is un-written automatically. No PID lockfile (per Phase-A4
  * decision 8).
  *
- * WHAT ACTUALLY WRITES THIS FILE, as of 2026-09-15: two call sites.
- * `src/server/routes/install.ts`'s recovery-dismiss handler appends a
- * `rollback` marker with an empty path and a null hash; `src/scripts/install.ts`
- * — the surviving headless writer, per-file, through `_log_tx_entry` — appends
- * a `write` or `skip` entry per copied/skipped path during
- * `_copy_dir_dereferencing_symlinks`. Both call `appendTxLog` directly, so the
+ * WHAT ACTUALLY WRITES THIS FILE: `src/server/routes/install.ts`'s
+ * recovery-dismiss handler appends a `rollback` marker with an empty path and a
+ * null hash; `src/scripts/install.ts`, through `_log_tx_entry`, appends a
+ * `write` or `skip` entry per path it copies, preserves or stages a sidecar
+ * for, and a `write` entry per deployed Claude rule the host-form rewrite and
+ * the thinning pass rewrite after the copy. All call `appendTxLog`, so the
  * entry shape is identical by construction rather than by convention.
  *
+ * WHAT READS IT: recovery (the active log only) and `./loggedWrites.ts`, which
+ * reads every `write` digest in the active log AND its rotated siblings as
+ * proof that bytes on disk are the installer's own output.
+ *
  * Rotation: 10 MB OR 30 days, whichever first. Rotated copies move to
  * `install-log.<ISO>.jsonl.gz` siblings; recovery never scans them.
  *

package/src/scripts/_cli/cmd_conformance.ts

@@ -39,6 +39,7 @@ import * as YAML from 'yaml';
 
 import * as installed_tools from '../_lib/installed_tools.js';
 import { atomicAppendLine } from '../../install/atomic.js';
+import { getLogPath } from '../../install/paths.js';
 import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
@@ -120,13 +121,13 @@ export function conformanceLogPath(): string {
     return path.join(os.homedir(), '.event4u', 'agent-config', 'conformance-log.jsonl');
 }
 
-/** Default install txlog path (kept in sync with `src/install/txlog.ts` docs). */
+/** Install txlog path — the one the installer writes, via `getLogPath()`. */
 export function installLogPath(): string {
     const override = process.env['AGENT_CONFIG_INSTALL_LOG'];
     if (override && override.trim().length > 0) {
         return override;
     }
-    return path.join(os.homedir(), '.event4u', 'agent-config', 'install-log.jsonl');
+    return getLogPath();
 }
 
 // ---------------------------------------------------------------------------