pi-condense 2.10.1 → 2.10.3

package/CHANGELOG.md

@@ -7,6 +7,14 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.10.3] - 2026-09-07
+
+- **Protected-path supersession.** Only the newest read of a protected path (`protectedPaths` / `protectedTools` calls with a string `path`) stays verbatim; earlier reads of the same path become a one-line `[Superseded: ...]` stub. Applied at render time (`pruneMessages` phase 1b, `src/supersede.ts`) and only when the pruner is already rewriting at or before that position, or on a cold-cache event (`session_start`, `session_tree`, `model_select`, `session_compact`, `thinking_level_select`) - never as the sole mid-prefix change. No new session entry, index record, or config key; supersession stops exactly when no protected call remains (`protectedPaths: []` with the default `protectedTools: []`); a read protected by tool name alone still participates. Spec: `doc/specs/2026-09-07-protected-path-supersede.md` (partially supersedes the 2026-06-11 protected-paths spec's "verbatim forever" edge case).
+
+## [2.10.2] - 2026-09-06
+
+- Protect `gauntlet-overrides.md` reads by default alongside skill files, including `.pi/` and `doc/` paths, so per-repo harness contracts survive context pruning. User-supplied `protectedPaths` still replaces the defaults; path matching remains limited to `args.path`.
+
 ## [2.10.1] - 2026-09-02
 
 - **Spill sidecar basenames capped at 255 bytes ([#14](https://github.com/jjuraszek/pi-condense/issues/14)).** Providers emitting 300+ char tool-call ids drove `blobPathFor` past the filesystem basename limit: eager spill failed silently (`ENAMETOOLONG` caught, oversized result stayed inline and bloated context) and the deterministic backfill aborted fail-closed. Fitting names stay byte-identical; over-limit names become `<234-byte sanitized prefix>.<16-hex sha1 of the unsanitized occurrence key>.txt` (exactly 255 bytes). The `.` separator is unreachable by `sanitizeId`, so capped names are namespace-disjoint from short-key names by construction - no probe, no migration, persisted `spillPath` read-back unchanged. Spec: `doc/specs/2026-09-02-gh-14-spill-filename-cap.md` (partially supersedes the 2026-06-02 spill spec's filename derivation).

package/PRUNING.md

@@ -567,6 +567,8 @@ graph LR
 captured batches (from turn_end or session scan)
   │
   ├─ 1. Protected-tools/paths filter   (capture-time, see below)
+  │     newest read per protected path stays verbatim; older reads of the same
+  │     path are stubbed at render time once the cache is cold anyway (see § Supersession)
   │     tool calls whose toolName is in protectedTools, OR whose args.path
   │     matches any protectedPaths glob, never enter the batch
   │
@@ -614,16 +616,20 @@ Implementation: `src/pruner.ts` `pruneMessages(messages, indexer)` returns `{ me
 
 ### Protected tools & paths
 
-A tool call is protected if **either** its `toolName` is in `protectedTools` **or** its `args.path` (string) matches any glob in `protectedPaths`. Protected calls are filtered out **at capture time** - they never enter the `pendingBatches` queue, so their raw `ToolResultMessage` stays verbatim in future LLM context.
+A tool call is protected if **either** its `toolName` is in `protectedTools` **or** its `args.path` (string) matches any glob in `protectedPaths`. Protected calls are filtered out **at capture time** - they never enter the `pendingBatches` queue, so their raw `ToolResultMessage` stays verbatim in future LLM context until a newer read of the same path supersedes it (below).
 
 **`protectedTools: string[]`** (default `[]`) - allowlist of tool names. Covers tools whose output is a small handle that must be reused byte-for-byte (e.g. a session-id) or planning tools like `todowrite` / `todoread`.
 
-**`protectedPaths: string[]`** (default `["**/skills/**/*.md"]`) - glob list matched against `args.path`. Designed for skill files that carry multi-step workflow gates; summarizing them is categorically lossy. Non-string or missing `path` arguments never match. Set `[]` to disable. Edit with `/pruner protected-paths`.
+**`protectedPaths: string[]`** (default `["**/skills/**/*.md", "**/gauntlet-overrides.md"]`) - glob list matched against `args.path`. Designed for skill files that carry multi-step workflow gates; summarizing them is categorically lossy. Non-string or missing `path` arguments never match. Set `[]` to disable. Edit with `/pruner protected-paths`.
 
 Glob contract: full-path match against the raw `args.path` string with `\` normalized to `/`. `*` and `?` match within a segment (no `/`); `**` crosses segments; `**/` also matches zero directories (so `**/SKILL.md` matches a bare relative `SKILL.md`). Case-sensitive. All other characters are regex-escaped literals.
 
 **Render-time re-check:** stub replacement runs in-flight on every turn (`pruneMessages`). If a tool call's persisted `args` now satisfy `isProtected` (e.g. a pattern was added mid-session), the stub is skipped and the raw result is left verbatim - this repairs already-summarized records in existing sessions with no schema change. Declared limitation: records inside already-compressed chains (`context-prune-chain` entries) are NOT repaired - their `protectedToolCallIds` set is fixed at compression time (forward-only). Dedup-alias edge: an alias resolving to an unprotected original stays stubbed.
 
+**Supersession (phase 1b, `src/supersede.ts`):** protected calls are never indexed, so content-hash dedup never sees them. Instead, at render time only the **newest** protected occurrence per normalized `args.path` (backslash -> slash; `offset`/`limit` ignored) stays verbatim; every earlier occurrence with a paired result becomes the one-line stub `[Superseded: <path> was read again later in this conversation - see the newer read. Re-read the file if this earlier content is needed.]`. The stub keeps `toolCallId`/`toolName`/`timestamp`, so pi-ai's orphan repair never fires; the assistant `toolCall` block is untouched. A call without a paired result never participates (an aborted call cannot steal the win). Recovery is "re-read the file" - no `t<N>` ref. Provider tool-call ids repeat across turns and an aborted call has no result, so a result is paired only with the same-id call in the immediately preceding assistant message (the per-turn open-set model orphan-sweep uses) - never by a global per-id cursor.
+
+**Cadence (prompt-cache economics):** a superseded read is stubbed only when the pruner is already rewriting at or before its position - `floor` is the earliest result timestamp phase 1 will stub on the next render (indexed batches, plus dedup aliases registered in the pre-flush pass - those are stubbed by phase 1 whatever their batch's outcome; a `skipped-trivial`/`skipped-oversized` batch's own calls set none) or the `startUserTimestamp` of a chain compressed this turn - or on a guaranteed-cold event: `session_start`, `session_tree`, `model_select`, `session_compact`, `thinking_level_select` (`floor = 0`, activate all). Activation is session-sticky (in-memory `occKey` set, cleared on `session_start`/`session_tree`); between those moments a freshly superseded copy stays verbatim on purpose, since a mid-prefix rewrite re-bills the whole tail once. `isProtected` is evaluated live, so a path that stops matching `protectedPaths` drops out of supersession and rejoins the normal pipeline. No config key: supersession is on whenever protection is. Spec: `doc/specs/2026-09-07-protected-path-supersede.md`.
+
 Names and patterns that don't match any captured tool call are silently ignored.
 
 ### Eager single-result spill
@@ -691,7 +697,7 @@ The last attempted prune boundary is persisted as `context-prune-frontier` so `f
 - **Tree browser (`/pruner tree`):** interactive, foldable tree of pruned tool calls grouped under their summaries. `Ctrl-O` on a summary node opens the full markdown summary in a bordered overlay.
 - **Configurable summarizer thinking (`summarizerThinking`):** trade summary cost / latency for quality (`off` / `minimal` / `low` / `medium` / `high` / `xhigh`). `default` omits the option entirely so the provider chooses.
 - **Cumulative stats:** `context-prune-stats` entries track input/output tokens and cost of every summarizer call; full detail surfaces in `/pruner stats`. Cost is also emitted on the `cost:external` pi.events channel for external aggregators (cumulative per session, live only).
-- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all four phases in a single point (stub-replace, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
+- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all five phases in a single point (stub-replace, supersede, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
 - **Live progress for `/pruner now`:** an `aboveEditor` widget shows one row per pending batch with braille spinner, streamed summary-char count, and ✓ / ⚠ status.
 
 ### Summarizer outage fallback
@@ -884,6 +890,7 @@ A **closed chain** is a span of messages from one user message - or a non-pruner
 raw messages from session
   │
   ├─ [1] tool-result stub-replace   (per-batch; existing)
+  ├─ [1b] supersede                (older protected reads of a re-read path -> stub; see § Supersession)
   ├─ [2] error-purge                (phase 2)
   ├─ [3] chain-range-prune          (runs AFTER stubs)
   │        resolve each entry to a positional index range
@@ -966,6 +973,8 @@ Chain compression does not delete data from the session JSONL. The original tool
 
 The protected output is relocated (moved), not copied — the original `ToolResultMessage` is dropped with the rest of the middle turns. The text stays in LLM context because it is embedded in the surviving synthetic block. It is NOT registered in the tool-call index and is NOT recoverable via `context_tree_query`; it does not need to be, because it is present verbatim.
 
+Relocation reads the array **after** phase 1b, so a protected read that has been superseded relocates as its one-line stub, not the verbatim body - the verbatim copy is the newer read elsewhere in context.
+
 The `context-prune-chain` session entry carries the matching `protectedToolCallIds` array so `session_start` reconstruction can re-embed the outputs on reload.
 
 **Rejected alternative:** skip compression for any chain that contains a protected tool. Rejected because `todowrite`/`todoread` recur in most chains for opted-in users, so this strategy would forfeit most chain compression for the people who most need `protectedTools`.
@@ -1089,7 +1098,7 @@ Error purge replaces those arg bodies with compact stubs after the error has coo
 **Transform position:** Error purge runs in Phase 2, after stub-replace and before chain range prune.
 
 ```
-[stub-replace] → [error-purge] → [chain-range-prune] → [orphan-sweep]
+[stub-replace] → [supersede] → [error-purge] → [chain-range-prune] → [orphan-sweep]
 ```
 
 **Config keys:**

package/README.md

@@ -169,9 +169,11 @@ Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_A
 | `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
 | `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn`; the trigger point is capped at 300k tokens |
 | `frontierGapThresholdTokens` | `null` | Opt-in absolute-token flush trigger: fires at `turn_end` once the un-pruned tail past the prune frontier reaches N tokens, regardless of window size; recommended starting value `80000` |
-| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md"]` | Tool names / path globs that are never pruned |
+| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md", "**/gauntlet-overrides.md"]` | Tool names / path globs that are never summarized; only the newest read per protected path stays verbatim (older reads of the same path are stubbed once the prompt cache is cold anyway) |
 | `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
 
+The default also protects reads of [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet)'s per-repo `gauntlet-overrides.md` so the repo's harness contract stays available for gate decisions after pruning.
+
 The full settings JSON, every key, the commands table, footer widget states, spilled-output details, and the summarizer-model-by-plan table live in **[doc/configuration.md](doc/configuration.md)**.
 
 ## Relationship to the rest of the platform

package/index.ts

@@ -45,6 +45,7 @@ import { StatsAccumulator, emitExternalCost } from "./src/stats.js";
 import { PruneFrontierTracker } from "./src/frontier.js";
 import { BlockRefIssuer } from "./src/block-refs.js";
 import { compressEligible } from "./src/chain-compressor.js";
+import { createSupersedeState, earliestChainStart, earliestResultTimestamp, lowerFloor } from "./src/supersede.js";
 import { detectChains, withClosingMessage } from "./src/chain-detector.js";
 import { inGraceRecoveryToolCallIds } from "./src/recovery-grace.js";
 import { shouldBudgetFlush, shouldDeltaFlush, shouldFrontierGapFlush, usageFraction } from "./src/budget.js";
@@ -82,6 +83,10 @@ export default function (pi: ExtensionAPI) {
   // (dedup'd across the session's lifetime, not per-render).
   const diagnostics = new DiagnosticSink((type, data) => pi.appendEntry(type, data));
 
+  // Newest-protected-read-wins state (spec 2026-09-07). In-memory only: on
+  // session_start / session_tree the cold floor re-activates everything.
+  const supersede = createSupersedeState();
+
   // Pending batches — accumulated until the prune trigger fires
   const pendingBatches: CapturedBatch[] = [];
   let isFlushing = false;
@@ -454,6 +459,12 @@ export default function (pi: ExtensionAPI) {
       const dedupedBatches: CapturedBatch[] = [];
       let firstFailureIndex = -1;
 
+      // Every tool call phase 1 will stub on the next render is a floor
+      // source for supersession: dedup aliases regardless of batch outcome,
+      // plus the batch's own calls when the batch was actually indexed.
+      const floorSources: import("./src/types.js").CapturedToolCall[] = [];
+      for (let i = 0; i < batches.length; i++) floorSources.push(...dedupedPerBatch[i].toolCalls);
+
       for (let i = 0; i < batches.length; i++) {
         const result = results[i];
         if (result === null) {
@@ -530,6 +541,7 @@ export default function (pi: ExtensionAPI) {
             // Keep the in-memory summary-body registry current so chain compression
             // can build synthetic chain messages without rescanning session entries.
             indexer.registerSummaryBody(batchOccurrenceKeys, summaryText);
+            floorSources.push(...batch.toolCalls);
           } else {
             oversizedBatches.push(batch);
           }
@@ -546,6 +558,8 @@ export default function (pi: ExtensionAPI) {
         processedBatches.push(batch);
       }
 
+      lowerFloor(supersede, earliestResultTimestamp(floorSources));
+
       // Restore unprocessed batches (those at and after the first failure)
       if (firstFailureIndex >= 0) {
         restoreBatches(batches.slice(firstFailureIndex));
@@ -664,6 +678,7 @@ export default function (pi: ExtensionAPI) {
             inGrace,
           );
           if (compressedEntries.length > 0) {
+            lowerFloor(supersede, earliestChainStart(compressedEntries));
             statsAccum.addChainsCompressed(compressedEntries.length);
             statsAccum.persist(pi);
             emitExternalCost(pi, statsAccum);
@@ -785,6 +800,8 @@ export default function (pi: ExtensionAPI) {
     statsAccum.reconstructFromSession(ctx);
     fallbackController.reset();
     diagnostics.reset();
+    supersede.activated.clear();
+    supersede.floor = 0;
 
     // Rebuild prune frontier from persisted session entries
     frontier.reconstructFromSession(ctx);
@@ -826,6 +843,8 @@ export default function (pi: ExtensionAPI) {
     blockRefs.rebuildFrom(indexer.getChainEntries().map((e) => e.blockId));
     statsAccum.reconstructFromSession(ctx);
     diagnostics.reset();
+    supersede.activated.clear();
+    supersede.floor = 0;
     frontier.reconstructFromSession(ctx);
     // Pending batches belong to the old branch — discard them
     pendingBatches.length = 0;
@@ -842,6 +861,18 @@ export default function (pi: ExtensionAPI) {
     setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
   });
 
+  // Cache is a per-model prefix; these three moments are cold regardless, so
+  // activating every pending supersession here costs no extra cache miss.
+  pi.on("model_select", async () => {
+    supersede.floor = 0;
+  });
+  pi.on("session_compact", async () => {
+    supersede.floor = 0;
+  });
+  pi.on("thinking_level_select", async () => {
+    supersede.floor = 0;
+  });
+
   // ── turn_end: capture batch, flush immediately or queue ──────────────────
   pi.on("turn_end", async (event, ctx) => {
     if (!currentConfig.value.enabled) return;
@@ -994,7 +1025,7 @@ export default function (pi: ExtensionAPI) {
 
     // pruneMessages is the single source of truth for "is there work to do".
     // It returns the original array reference (pruned: false) only when none of
-    // the four phases changed anything; index/registry emptiness alone does not
+    // the five phases changed anything; index/registry emptiness alone does not
     // imply a no-op, since error-purge (phase 2) prunes independently of them.
     // Calling it unconditionally is safe and avoids a split gate here.
     const result = pruneMessages(
@@ -1005,6 +1036,7 @@ export default function (pi: ExtensionAPI) {
       currentConfig.value,
       currentConfig.value.recoveryGraceTurns,
       diagnostics,
+      { state: supersede, isProtected: protectionPredicate },
     );
     if (result.pruned) {
       messages = result.messages;
@@ -1046,6 +1078,7 @@ export default function (pi: ExtensionAPI) {
       inGrace,
     );
     if (result.compressedEntries.length > 0) {
+      lowerFloor(supersede, earliestChainStart(result.compressedEntries));
       statsAccum.addChainsCompressed(result.compressedEntries.length);
       statsAccum.persist(pi);
       emitExternalCost(pi, statsAccum);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.10.1",
+  "version": "2.10.3",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/commands.ts

@@ -256,7 +256,7 @@ function protectedToolsDescription(config: ContextPruneConfig): string {
 }
 
 function protectedPathsDescription(config: ContextPruneConfig): string {
-  return `Glob patterns matched against a tool call's \`args.path\`; matching outputs are NEVER pruned. Currently: ${protectedToolsDisplay(config.protectedPaths)}. Edit via \`/pruner protected-paths\` (interactive) or \`/pruner protected-paths <comma-separated globs>\`. Set to 'none' to disable (kill switch). Default protects skill files: **/skills/**/*.md`;
+  return `Glob patterns matched against a tool call's \`args.path\`; matching outputs are NEVER pruned. Currently: ${protectedToolsDisplay(config.protectedPaths)}. Edit via \`/pruner protected-paths\` (interactive) or \`/pruner protected-paths <comma-separated globs>\`. Set to 'none' to disable (kill switch). Default protects skill files and per-repo gauntlet overrides: **/skills/**/*.md, **/gauntlet-overrides.md`;
 }
 
 const HELP_TEXT = `pruner — automatically summarizes tool-call outputs to keep context lean.

package/src/config.test.ts

@@ -35,6 +35,22 @@ async function writeContextPrune(overrides: Record<string, unknown>): Promise<vo
   await writeFile(settingsPath(), JSON.stringify({ contextPrune: overrides }));
 }
 
+describe("loadConfig protectedPaths", () => {
+  it("uses the defaults when unset", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.protectedPaths).toEqual(DEFAULT_CONFIG.protectedPaths);
+  });
+
+  it("replaces defaults with user-supplied paths, including an empty list", async () => {
+    for (const protectedPaths of [["**/custom.md"], []]) {
+      await writeContextPrune({ protectedPaths });
+      const config = await loadConfig();
+      expect(config.protectedPaths).toEqual(protectedPaths);
+    }
+  });
+});
+
 describe("loadConfig recoveryGraceTurns normalization", () => {
   it("preserves an explicit 0", async () => {
     await writeContextPrune({ recoveryGraceTurns: 0 });

package/src/protected.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { globToRegExp, isProtected } from "./protected.js";
+import { globToRegExp, isProtected, normalizePath } from "./protected.js";
+import { DEFAULT_CONFIG } from "./types.js";
 
 describe("globToRegExp", () => {
   test("** crosses path segments", () => {
@@ -33,6 +34,27 @@ describe("globToRegExp", () => {
   });
 });
 
+describe("isProtected defaults", () => {
+  test.each([".pi/gauntlet-overrides.md", "doc/gauntlet-overrides.md"])(
+    "protects reads of %s",
+    (path) => {
+      expect(isProtected("read", { path }, DEFAULT_CONFIG)).toBe(true);
+    },
+  );
+
+  test("protects skill reads", () => {
+    expect(isProtected("read", { path: "/h/skills/x/SKILL.md" }, DEFAULT_CONFIG)).toBe(true);
+  });
+
+  test("does not protect sibling settings reads", () => {
+    expect(isProtected("read", { path: ".pi/settings.json" }, DEFAULT_CONFIG)).toBe(false);
+  });
+
+  test("does not infer paths from bash commands", () => {
+    expect(isProtected("bash", { command: "cat .pi/gauntlet-overrides.md" }, DEFAULT_CONFIG)).toBe(false);
+  });
+});
+
 describe("isProtected", () => {
   const cfg = { protectedTools: ["todowrite"], protectedPaths: ["**/skills/**/*.md"] };
 
@@ -60,3 +82,10 @@ describe("isProtected", () => {
     expect(isProtected("read", { path: "skills/a/SKILL.md" }, { protectedTools: [], protectedPaths: [] })).toBe(false);
   });
 });
+
+describe("normalizePath", () => {
+  test("normalizePath turns backslashes into forward slashes and nothing else", () => {
+    expect(normalizePath("h\\skills\\x\\SKILL.md")).toBe("h/skills/x/SKILL.md");
+    expect(normalizePath("./a/../b.md")).toBe("./a/../b.md");
+  });
+});

package/src/protected.ts

@@ -41,11 +41,16 @@ export function globToRegExp(pattern: string): RegExp {
   return compiled;
 }
 
+/** Identity normalization shared by protection matching and supersession: slash direction only, no resolution. */
+export function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
 export function isProtected(toolName: string, args: unknown, config: ProtectionConfig): boolean {
   if (config.protectedTools.includes(toolName)) return true;
   if (config.protectedPaths.length === 0) return false;
   const path = (args as Record<string, unknown> | null | undefined)?.path;
   if (typeof path !== "string") return false;
-  const normalized = path.replace(/\\/g, "/");
+  const normalized = normalizePath(path);
   return config.protectedPaths.some((p) => globToRegExp(p).test(normalized));
 }

package/src/pruner.test.ts

@@ -4,7 +4,9 @@ import { ToolCallIndexer } from "./indexer.js";
 import { CUSTOM_TYPE_INDEX } from "./types.js";
 import type { ChainCompressionConfig, ChainCompressionEntry } from "./types.js";
 import { DiagnosticSink } from "./diagnostics.js";
-import { pruneWithZeroSweepAssertion } from "./test-support.js";
+import { pruneWithZeroSweepAssertion, expectNoOrphanToolResults } from "./test-support.js";
+import { createSupersedeState, supersededStub } from "./supersede.js";
+import { isProtected } from "./protected.js";
 
 // Minimal mock exposing only the ToolCallIndexer surface that pruneMessages calls.
 // `hasLegacyBareRecord` defaults to the bare `summarized` set: most of the fixture
@@ -1053,3 +1055,74 @@ describe("G4/C3: orphan-sweep zero-fire proof across pruner fixtures", () => {
     it(`zero orphan sweeps: ${name}`, run);
   }
 });
+
+describe("pruneMessages phase 1b (supersede)", () => {
+  const protection = { protectedTools: [], protectedPaths: ["**/skills/**/*.md"] };
+  const isProt = (n: string, a: unknown) => isProtected(n, a, protection);
+  const SKILL = "/h/skills/x/SKILL.md";
+
+  function twoReads(): any[] {
+    return [
+      { role: "user", timestamp: 1, content: [{ type: "text", text: "go" }] },
+      { role: "assistant", timestamp: 2, content: [{ type: "toolCall", id: "r1", name: "read", input: { path: SKILL } }] },
+      { role: "toolResult", toolCallId: "r1", toolName: "read", content: [{ type: "text", text: "FIRST" }], isError: false, timestamp: 3 },
+      { role: "assistant", timestamp: 4, content: [{ type: "text", text: "ok" }] },
+      { role: "user", timestamp: 5, content: [{ type: "text", text: "again" }] },
+      { role: "assistant", timestamp: 6, content: [{ type: "toolCall", id: "r2", name: "read", input: { path: SKILL } }] },
+      { role: "toolResult", toolCallId: "r2", toolName: "read", content: [{ type: "text", text: "SECOND" }], isError: false, timestamp: 7 },
+      { role: "assistant", timestamp: 8, content: [{ type: "text", text: "done" }] },
+    ];
+  }
+
+  it("supersede param absent -> output identical to today", () => {
+    const msgs = twoReads();
+    const { messages: out, pruned } = pruneMessages(msgs, makeMockIndexer(), undefined, undefined, protection);
+    expect(pruned).toBe(false);
+    expect(out).toBe(msgs);
+  });
+
+  it("nothing activated -> input reference, pruned false", () => {
+    const msgs = twoReads();
+    const state = createSupersedeState();
+    const { messages: out, pruned } = pruneMessages(msgs, makeMockIndexer(), undefined, undefined, protection, 0, undefined, { state, isProtected: isProt });
+    expect(pruned).toBe(false);
+    expect(out).toBe(msgs);
+  });
+
+  it("one activation -> fresh array, pruned true, input untouched, newest verbatim, metadata kept", () => {
+    const msgs = twoReads();
+    const before = JSON.stringify(msgs);
+    const state = createSupersedeState();
+    state.floor = 0;
+    const { messages: out, pruned } = pruneMessages(msgs, makeMockIndexer(), undefined, undefined, protection, 0, undefined, { state, isProtected: isProt });
+    expect(pruned).toBe(true);
+    expect(out).not.toBe(msgs);
+    expect(JSON.stringify(msgs)).toBe(before);
+    expect(out[2]).toEqual({ ...msgs[2], content: [{ type: "text", text: supersededStub(SKILL) }] });
+    expect(out[6]).toBe(msgs[6]);
+    expectNoOrphanToolResults(out);
+  });
+
+  it("superseded read inside a compressed chain relocates as the stub", () => {
+    const msgs = twoReads();
+    const entry = {
+      blockId: "b1",
+      startUserTimestamp: 1,
+      droppedToolCallIds: ["r1"],
+      protectedToolCallIds: ["r1"],
+      finalAssistantTimestamp: 4,
+      toolRefs: [],
+      compressedAt: 100,
+    } as any;
+    const indexer = makeMockIndexer({ chainEntries: [entry], summaryBodyMap: new Map([["r1", "SUMMARY"]]) });
+    const state = createSupersedeState();
+    state.floor = 0;
+    const { messages: out } = pruneMessages(msgs, indexer, enabledCC, undefined, protection, 0, undefined, { state, isProtected: isProt });
+    const synthetic = out.find((m: any) => typeof m.content?.[0]?.text === "string" && m.content[0].text.startsWith("<compressed-chain"));
+    expect(synthetic.content[0].text).toContain('<protected-output tool="read">');
+    expect(synthetic.content[0].text).toContain(supersededStub(SKILL));
+    expect(synthetic.content[0].text).not.toContain("FIRST");
+    expect(out.find((m: any) => m.role === "toolResult" && m.toolCallId === "r2").content[0].text).toBe("SECOND");
+    expectNoOrphanToolResults(out);
+  });
+});

package/src/pruner.ts

@@ -8,6 +8,7 @@ import { inGraceRecoveryToolCallIds } from "./recovery-grace.js";
 import { occKey } from "./occurrence-key.js";
 import { sweepOrphanToolResults } from "./orphan-sweep.js";
 import type { DiagnosticSink } from "./diagnostics.js";
+import { applySupersede, type SupersedeState } from "./supersede.js";
 
 /**
  * Estimate of a message array's context weight. Serializing the whole array
@@ -20,7 +21,7 @@ export function sizeMessages(messages: any[]): number {
 }
 
 /**
- * Transforms the `context` event message array in four phases:
+ * Transforms the `context` event message array in five phases:
  *
  * Phase 1 — stub-replace: ToolResultMessages for summarized tool calls are
  * replaced with short stubs pointing the model at `context_tree_query`.
@@ -37,6 +38,13 @@ export function sizeMessages(messages: any[]): number {
  *     to recovery is present on the toolResult itself, not only in the
  *     separate summary message.
  *
+ * Phase 1b — supersede: protected reads (never indexed) whose `args.path`
+ * is read again later in the same context are replaced with a one-line
+ * "superseded" stub, but only once `SupersedeState.floor` says the pruner
+ * is rewriting at/before their position anyway (or the cache is cold).
+ * See src/supersede.ts. Runs before phase 3 so a superseded read inside a
+ * compressed chain relocates as the stub, not the verbatim body.
+ *
  * Phase 2 — error purge: replaces failed toolCall arg bodies with stubs after a
  * cooldown, reclaiming context from large `write`/`edit` arguments that will
  * never succeed. The toolResult error message stays visible.
@@ -78,6 +86,7 @@ export function pruneMessages(
   protection?: ProtectionConfig,
   recoveryGraceTurns: number = 0,
   diagnostics?: DiagnosticSink,
+  supersede?: { state: SupersedeState; isProtected: (toolName: string, args: unknown) => boolean },
 ): { messages: any[]; pruned: boolean; beforeChars: number; afterChars: number } {
   // Phase 1: stub-replace summarized tool results
   let pruned = false;
@@ -136,6 +145,15 @@ export function pruneMessages(
 
   let current: any[] = pruned ? next : messages;
 
+  // Phase 1b: supersede older protected reads of a re-read path
+  if (supersede) {
+    const afterSupersede = applySupersede(current, supersede.state, supersede.isProtected);
+    if (afterSupersede !== current) {
+      current = afterSupersede;
+      pruned = true;
+    }
+  }
+
   // Phase 2: error purge — replace failed toolCall arg bodies after cooldown
   if (errorPurge?.enabled) {
     const afterPurge = purgeErroredArgs(current, errorPurge);