pi-condense 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -9,6 +9,10 @@ publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-07-06
+
+- **Recovery grace window for `context_tree_query` output.** The pruner used to re-stub its own recovery output at the next turn boundary, forcing a retrieve -> re-stub -> re-query loop the agent experiences as "fighting the pruner" (observed in a real session: a recovered tool dump was re-summarized on the very next flush, so the agent had to keep re-querying the same ref). A new `recoveryGraceTurns` setting (default `3`, `0` disables) keeps a recovered output verbatim for that many user-turn-groups before reverting to the stub. Enforced at **render time** in two places - Phase 1 stub-replace (`src/pruner.ts`) and chain-compression eligibility (`src/chain-compressor.ts`, which defers compressing any chain whose span still holds an in-grace recovery id) - never at capture, so the frontier, dedup, spill, and live `turn_end` paths are unchanged. The window is computed positionally from the message stream (no new `ToolCallRecord` field). Default `3` covers ~81% of same-ref re-queries observed in the local session corpus; the accepted trade-off is that a reference past the window is re-stubbed and may be re-queried, keeping context regrowth bounded rather than permanent. Tunable via `/pruner recovery-grace [n]` and the `/pruner settings` overlay. See [PRUNING.md § What Pruning Does](PRUNING.md#what-pruning-does).
+
 ## [2.2.1] - 2026-07-06
 
 - **Fix probe starvation in the summarizer outage fallback.** `FallbackController.onFallbackOnlyFail` reset the re-probe cooldown on every steady-state fallback failure, so a fallback (session) model that failed at least once per 10-minute cooldown perpetually pushed out the primary re-probe - a recovered `summarizerModel` was never re-tested and summarization stayed on the pricier session model indefinitely (the exact stall the feature exists to kill, in the fallback direction). The method is now a no-op on `lastProbeAt`: the primary re-probe fires on schedule regardless of fallback failures. In-memory only; no wire/config change.

package/PRUNING.md

@@ -185,6 +185,9 @@ graph TB
 - Every pruned tool call is also copied into the pruner's runtime/session index with its `toolCallId`, tool name, args, status, turn index, timestamp, and full `resultText`.
 - A summary message is injected as a `"steer"` (`pi.sendMessage` runtime path) or appended directly via `sessionManager.appendCustomMessageEntry` (session path, used when Pi may already be shutting down). Both deliver before the next LLM call.
 - The session JSONL file retains the original tool-result entries unchanged — pruning only affects what the *next* request sees in active context.
+- **Recovery grace window (`recoveryGraceTurns`, default 3):** after the model recovers a tool call via `context_tree_query`, that tool call's output is rendered **verbatim** (not re-stubbed) for the next N user-turn-groups, then reverts to the normal stub. Without this, the pruner re-prunes its own recovery output on the very next flush, forcing the model into a retrieve -> re-stub -> re-query loop ("fighting the pruner") whenever it keeps referencing the same recovered data across a few turns.
+  - Enforced at **render time**, in Phase 1 stub-replace and in chain-compression eligibility — NOT at capture time. Capture-time exclusion would collide with frontier trim: a tool call already past the frontier is dropped forever, so excluding a recovered call from capture would either need to resurrect frontier state or degrade the lifetime bound into permanent verbatim retention for anything ever recovered.
+  - Trade-off: this bounds but does not eliminate regrowth. A tool call still referenced after its grace window expires is re-stubbed and may be re-queried again — the accepted cost of keeping the window's context-growth impact bounded instead of unbounded.
 
 ---
 

package/README.md

@@ -87,6 +87,7 @@ Settings live under the `contextPrune` key in `<agent-dir>/settings.json` (i.e.
     "batchingMode": "turn",
     "quietOversizedSkips": false,
     "minBatchChars": 1000,
+    "recoveryGraceTurns": 3,
     "protectedTools": [],
     "protectedPaths": ["**/skills/**/*.md"],
     "dedupByContentHash": true,
@@ -118,6 +119,7 @@ Settings live under the `contextPrune` key in `<agent-dir>/settings.json` (i.e.
 | `batchingMode` | `turn` / `agent-message` | `turn` | How coarse each summary is (independent of `pruneOn`) |
 | `quietOversizedSkips` | `true` / `false` | `false` | Silences `skipped-oversized` / `skipped-trivial` info notifications |
 | `minBatchChars` | non-negative integer, `0` disables | `1000` | Pre-flush guard — batches smaller than this skip the LLM entirely |
+| `recoveryGraceTurns` | non-negative integer (user-turn-groups), `0` disables | `3` | After a `context_tree_query` recovery, render that tool's output verbatim for this many user-turn-groups before re-stubbing it. Enforced at render time (Phase 1 + chain-compression eligibility), not at capture time. See [PRUNING.md § What Pruning Does](PRUNING.md#what-pruning-does) |
 | `protectedTools` | `string[]` | `[]` | Never-pruned tool names (e.g. `["todowrite","todoread"]`). When a protected tool's chain is range-compressed, its output is preserved verbatim inside the `<compressed-chain>` block as `<protected-output>` — protected outputs are never lost. |
 | `protectedPaths` | `string[]` | `["**/skills/**/*.md"]` | Globs matched against a tool call's `args.path`; matching outputs are never pruned (same semantics as `protectedTools`, including `<protected-output>` relocation in compressed chains). Already-summarized matching reads are repaired on the next turn; chain-compressed ones are not. Set `[]` to disable. |
 | `dedupByContentHash` | `true` / `false` | `true` | Re-reads of identical (toolName, content) skip the LLM and alias the original |
@@ -192,6 +194,7 @@ Set it from the slash command (saves immediately):
 | `/pruner protected-tools [names]` | Show or edit the never-pruned tool allowlist (comma- or space-separated; `none` clears) |
 | `/pruner protected-paths [globs]` | Show or edit the never-pruned path globs (`none` clears) |
 | `/pruner min-batch-chars [n]` | Show or set the pre-flush trivial-batch threshold (`0` disables) |
+| `/pruner recovery-grace [n]` | Show or set the post-recovery verbatim grace window, in user-turn-groups (`0` disables) |
 | `/pruner dedup [on\|off\|status]` | Toggle pre-flush content-hash dedup |
 | `/pruner tree` | Foldable browser of pruned tool calls; `Ctrl-O` opens the full summary in an overlay |
 | `/pruner compact` | Retroactively compress every eligible closed chain (bypasses `rollingWindow`) |

package/index.ts

@@ -36,6 +36,7 @@ import { PruneFrontierTracker } from "./src/frontier.js";
 import { BlockRefIssuer } from "./src/block-refs.js";
 import { compressEligible } from "./src/chain-compressor.js";
 import { detectChains, withClosingMessage } from "./src/chain-detector.js";
+import { inGraceRecoveryToolCallIds } from "./src/recovery-grace.js";
 import { shouldBudgetFlush, shouldDeltaFlush, usageFraction } from "./src/budget.js";
 import { spillOversizedBatch } from "./src/spill.js";
 
@@ -530,6 +531,7 @@ export default function (pi: ExtensionAPI) {
           // message_end fires before pi persists the closing assistant, so thread it
           // in here; otherwise the newest chain reads as open and K over-retains by 1.
           const chains = detectChains(withClosingMessage(branchMessages, options.closingMessage), protectionPredicate);
+          const inGrace = inGraceRecoveryToolCallIds(branchMessages, currentConfig.value.recoveryGraceTurns);
           const { compressedEntries } = await compressEligible(
             chains,
             currentConfig.value.chainCompression.rollingWindow,
@@ -540,6 +542,7 @@ export default function (pi: ExtensionAPI) {
               now: () => Date.now(),
               fuseRange: makeFuseRange(ctx),
             },
+            inGrace,
           );
           if (compressedEntries.length > 0) {
             statsAccum.addChainsCompressed(compressedEntries.length);
@@ -825,6 +828,7 @@ export default function (pi: ExtensionAPI) {
       currentConfig.value.purgeErrors,
       currentConfig.value.thinkingStrip,
       currentConfig.value,
+      currentConfig.value.recoveryGraceTurns,
     );
     if (result.pruned) {
       messages = result.messages;
@@ -847,6 +851,7 @@ export default function (pi: ExtensionAPI) {
       .filter((e: any) => e.type === "message" && e.message)
       .map((e: any) => e.message);
     const chains = detectChains(branchMessages, protectionPredicate);
+    const inGrace = inGraceRecoveryToolCallIds(branchMessages, currentConfig.value.recoveryGraceTurns);
     const result = await compressEligible(
       chains,
       0, // effectiveK=0: compress every closed chain not already compressed
@@ -857,6 +862,7 @@ export default function (pi: ExtensionAPI) {
         now: () => Date.now(),
         fuseRange: makeFuseRange(ctx),
       },
+      inGrace,
     );
     if (result.compressedEntries.length > 0) {
       statsAccum.addChainsCompressed(result.compressedEntries.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "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/chain-compressor.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it, test } from "bun:test";
 import { selectEligible, compressEligible } from "./chain-compressor.js";
 import type { ChainCompressorIndexerDeps } from "./chain-compressor.js";
 import type { ChainRange, ChainCompressionEntry } from "./types.js";
@@ -281,3 +281,35 @@ describe("compressEligible", () => {
     expect(result.compressedEntries[0].rangeSummaryText).toBeUndefined();
   });
 });
+
+describe("selectEligible - recovery grace deferral", () => {
+  const chain = (startTs: number, ids: string[]) =>
+    ({
+      startUserTimestamp: startTs,
+      finalAssistantTimestamp: startTs + 10,
+      middleToolCallIds: ids,
+      protectedToolCallIds: [],
+    }) as any;
+  it("defers a chain whose span holds an in-grace recovery id", () => {
+    const chains = [chain(1, ["a", "t1"]), chain(2, ["b"])];
+    const eligible = selectEligible(chains, 0, new Set(), new Set(["t1"]));
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([2]);
+  });
+  it("compresses normally when no in-grace recovery id is present", () => {
+    const chains = [chain(1, ["a", "t1"]), chain(2, ["b"])];
+    const eligible = selectEligible(chains, 0, new Set(), new Set());
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([1, 2]);
+  });
+  it("defers only the grace chain without shrinking the rolling-window buffer", () => {
+    // 5 eligible chains, rollingWindow=2 -> the window boundary is at n-W=3, so chains
+    // 1,2,3 are candidates for compression and 4,5 sit in the protected buffer.
+    // The in-grace id lives on chain 4, which is already outside the compress slice and
+    // must not affect it. A pre-slice filter (the bug) removes chain 4 from `candidates`
+    // before the boundary is computed, shrinking it to 4 items and shifting the cut to
+    // n-W=2 -> wrongly dropping chain 3 too. The fix computes the boundary first, so the
+    // in-buffer grace id changes nothing and the compress set stays [1, 2, 3].
+    const chains = [chain(1, ["a"]), chain(2, ["b"]), chain(3, ["c"]), chain(4, ["d", "t1"]), chain(5, ["e"])];
+    const eligible = selectEligible(chains, 2, new Set(), new Set(["t1"]));
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([1, 2, 3]);
+  });
+});

package/src/chain-compressor.ts

@@ -13,11 +13,16 @@ import type { BlockRefIssuer } from "./block-refs.js";
  * @param chains Must be in chronological order (oldest first), as emitted by
  *   chain-detector. Ordering is not validated here; out-of-order input silently
  *   picks wrong chains because the rolling-window slice is positional.
+ * @param inGraceToolCallIds Recovery ids still within their grace window. Chains
+ *   spanning one of these ids are deferred from compression, but the rolling-window
+ *   boundary itself is computed BEFORE grace exclusion, so a grace-protected chain
+ *   never shrinks the window buffer or shifts which other chains become eligible.
  */
 export function selectEligible(
   chains: ChainRange[],
   rollingWindow: number,
   alreadyCompressed: Set<number>,
+  inGraceToolCallIds: Set<string> = new Set(),
 ): ChainRange[] {
   const candidates = chains.filter(
     (c) =>
@@ -25,7 +30,8 @@ export function selectEligible(
       !alreadyCompressed.has(c.startUserTimestamp) &&
       c.middleToolCallIds.length > 0,
   );
-  return candidates.slice(0, Math.max(0, candidates.length - rollingWindow));
+  const toCompress = candidates.slice(0, Math.max(0, candidates.length - rollingWindow));
+  return toCompress.filter((c) => !c.middleToolCallIds.some((id) => inGraceToolCallIds.has(id)));
 }
 
 /**
@@ -71,6 +77,7 @@ export async function compressEligible(
   chains: ChainRange[],
   rollingWindow: number,
   deps: CompressEligibleDeps,
+  inGraceToolCallIds: Set<string> = new Set(),
 ): Promise<CompressEligibleResult> {
   const alreadyCompressedTimestamps = new Set(
     deps.indexer.getChainEntries().map((e) => e.startUserTimestamp),
@@ -85,7 +92,7 @@ export async function compressEligible(
     }
   }
 
-  const eligible = selectEligible(chains, rollingWindow, alreadyCompressedTimestamps);
+  const eligible = selectEligible(chains, rollingWindow, alreadyCompressedTimestamps, inGraceToolCallIds);
 
   const compressedEntries: ChainCompressionEntry[] = [];
   for (const chain of eligible) {

package/src/commands.ts

@@ -11,6 +11,7 @@ import {
   PROGRESS_WIDGET_ID,
   SUMMARIZER_THINKING_LEVELS,
   MIN_BATCH_CHARS_PRESETS,
+  RECOVERY_GRACE_PRESETS,
   AUTO_BUDGET_PRESETS,
   ROLLING_WINDOW_PRESETS,
   KEEP_LAST_TURNS_PRESETS,
@@ -99,6 +100,7 @@ const SUBCOMMANDS = [
   { value: "protected-tools", label: "protected-tools — show or edit the never-pruned tool allowlist" },
   { value: "protected-paths", label: "protected-paths — show or edit the never-pruned path globs" },
   { value: "min-batch-chars", label: "min-batch-chars — show or set the pre-flush trivial-batch threshold" },
+  { value: "recovery-grace", label: "recovery-grace - show or set how long context_tree_query output stays verbatim (user-turn-groups)" },
   { value: "dedup",   label: "dedup     — toggle pre-flush content-hash dedup (on/off/status)" },
   { value: "help",    label: "help      — show this help" },
 ] as const;
@@ -190,6 +192,13 @@ function minBatchCharsDescription(config: ContextPruneConfig): string {
   return `Pre-flush guard: skip batches whose total raw resultText is below this many chars (no LLM call, frontier advances anyway). Currently ${config.minBatchChars}. Useful for sessions with many tiny tool calls. Set to 0 to disable.`;
 }
 
+function recoveryGraceDescription(config: ContextPruneConfig): string {
+  if (config.recoveryGraceTurns === 0) {
+    return "context_tree_query output is stubbed immediately (grace disabled). Set to a positive integer to keep recovered output verbatim for that many user-turn-groups.";
+  }
+  return `context_tree_query (recovery) output stays verbatim for ${config.recoveryGraceTurns} user-turn-group(s) after recovery, then reverts to the stub. Bounds the recover->re-stub->re-query loop. Currently ${config.recoveryGraceTurns}. Set to 0 to disable.`;
+}
+
 function autoBudgetThresholdDescription(config: ContextPruneConfig): string {
   if (config.autoBudgetThreshold == null) {
     return `Token-budget auto-flush: force a prune when context usage reaches this share of the window, regardless of prune-on mode. Currently off. Pick a percentage to enable.`;
@@ -244,6 +253,8 @@ Usage:
   /pruner protected-paths <globs>          Set the globs (comma- or space-separated; 'none' clears)
   /pruner min-batch-chars                  Show the current pre-flush trivial-batch threshold
   /pruner min-batch-chars <n>              Set the threshold (non-negative integer; 0 disables)
+  /pruner recovery-grace                   Show the current recovery grace window (user-turn-groups)
+  /pruner recovery-grace <n>               Set the window (non-negative integer; 0 disables)
   /pruner compact                          Retroactively compress all closed chains (ignores rollingWindow; force-compresses every eligible chain)
   /pruner dedup                            Show the current pre-flush content-hash dedup state
   /pruner dedup on|off                     Enable or disable content-hash dedup
@@ -546,6 +557,15 @@ export function registerCommands(
                 : MIN_BATCH_CHARS_PRESETS[2].value, // fall back to "1000" if a custom value isn't in the preset cycle
               description: minBatchCharsDescription(config),
             },
+            {
+              id: "recoveryGraceTurns",
+              label: "Recovery grace (user-turn-groups)",
+              values: RECOVERY_GRACE_PRESETS.map((p) => p.value),
+              currentValue: RECOVERY_GRACE_PRESETS.some((p) => p.value === String(config.recoveryGraceTurns))
+                ? String(config.recoveryGraceTurns)
+                : RECOVERY_GRACE_PRESETS[2].value,
+              description: recoveryGraceDescription(config),
+            },
             {
               id: "autoBudgetThreshold",
               label: "Auto-flush at context %",
@@ -705,6 +725,13 @@ export function registerCommands(
               if (mbItem) {
                 mbItem.description = minBatchCharsDescription(newConfig);
               }
+            } else if (id === "recoveryGraceTurns") {
+              const parsed = Number.parseInt(newValue, 10);
+              newConfig.recoveryGraceTurns = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CONFIG.recoveryGraceTurns;
+              const rgItem = items.find((item) => item.id === "recoveryGraceTurns");
+              if (rgItem) {
+                rgItem.description = recoveryGraceDescription(newConfig);
+              }
             } else if (id === "autoBudgetThreshold") {
               const parsed = Number.parseFloat(newValue);
               newConfig.autoBudgetThreshold =
@@ -1153,6 +1180,29 @@ export function registerCommands(
           break;
         }
 
+        case "recovery-grace": {
+          const arg = subArgs[0];
+          if (!arg) {
+            const cur = currentConfig.value.recoveryGraceTurns;
+            const state = cur === 0 ? "disabled" : `${cur} user-turn-group(s)`;
+            ctx.ui.notify(`Current recovery grace: ${state}.`);
+            break;
+          }
+          const parsed = Number.parseInt(arg, 10);
+          if (!Number.isFinite(parsed) || parsed < 0) {
+            ctx.ui.notify(`Invalid recovery-grace: "${arg}". Expected a non-negative integer (0 disables).`, "warning");
+            break;
+          }
+          currentConfig.value = { ...currentConfig.value, recoveryGraceTurns: parsed };
+          saveConfig(currentConfig.value);
+          ctx.ui.notify(
+            parsed === 0
+              ? "recovery-grace set to 0 - context_tree_query output stubs immediately."
+              : `recovery-grace set to ${parsed} user-turn-group(s).`,
+          );
+          break;
+        }
+
         // ── /pruner dedup [on|off|status] ──
         // Bare form shows current state; `on`/`off` flip and persist;
         // `status` is an explicit synonym for bare.

package/src/config.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, beforeAll, afterAll } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "./types.js";
+
+/**
+ * config.ts computes SETTINGS_PATH from getAgentDir() at module-load time, so
+ * PI_CODING_AGENT_DIR must be set before the module is imported. normalize()
+ * itself isn't exported; loadConfig() is the only public entry point that
+ * exercises it, so these tests drive normalization indirectly by writing
+ * settings.json into an isolated agent dir and reading it back.
+ */
+let tmpDir: string;
+let loadConfig: typeof import("./config.js").loadConfig;
+let SETTINGS_PATH: string;
+
+beforeAll(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "pi-condense-config-test-"));
+  process.env.PI_CODING_AGENT_DIR = tmpDir;
+  const mod = await import("./config.js");
+  loadConfig = mod.loadConfig;
+  SETTINGS_PATH = mod.SETTINGS_PATH;
+});
+
+afterAll(async () => {
+  delete process.env.PI_CODING_AGENT_DIR;
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+async function writeContextPrune(overrides: Record<string, unknown>): Promise<void> {
+  await writeFile(SETTINGS_PATH, JSON.stringify({ contextPrune: overrides }));
+}
+
+describe("loadConfig recoveryGraceTurns normalization", () => {
+  it("preserves an explicit 0", async () => {
+    await writeContextPrune({ recoveryGraceTurns: 0 });
+    const config = await loadConfig();
+    expect(config.recoveryGraceTurns).toBe(0);
+  });
+
+  it("falls back to the default for a negative value", async () => {
+    await writeContextPrune({ recoveryGraceTurns: -1 });
+    const config = await loadConfig();
+    expect(config.recoveryGraceTurns).toBe(DEFAULT_CONFIG.recoveryGraceTurns);
+  });
+
+  it("falls back to the default for NaN", async () => {
+    await writeContextPrune({ recoveryGraceTurns: Number.NaN });
+    const config = await loadConfig();
+    expect(config.recoveryGraceTurns).toBe(DEFAULT_CONFIG.recoveryGraceTurns);
+  });
+
+  it("floors a fractional value", async () => {
+    await writeContextPrune({ recoveryGraceTurns: 2.7 });
+    const config = await loadConfig();
+    expect(config.recoveryGraceTurns).toBe(2);
+  });
+
+  it("falls back to the default when unset", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.recoveryGraceTurns).toBe(DEFAULT_CONFIG.recoveryGraceTurns);
+  });
+});

package/src/config.ts

@@ -52,6 +52,12 @@ function normalize(existing: Partial<ContextPruneConfig>): ContextPruneConfig {
       merged.minBatchChars >= 0
         ? Math.floor(merged.minBatchChars)
         : DEFAULT_CONFIG.minBatchChars,
+    recoveryGraceTurns:
+      typeof merged.recoveryGraceTurns === "number" &&
+      Number.isFinite(merged.recoveryGraceTurns) &&
+      merged.recoveryGraceTurns >= 0
+        ? Math.floor(merged.recoveryGraceTurns)
+        : DEFAULT_CONFIG.recoveryGraceTurns,
     dedupByContentHash:
       typeof merged.dedupByContentHash === "boolean"
         ? merged.dedupByContentHash

package/src/pruner.test.ts

@@ -451,6 +451,123 @@ describe("render-time protection re-check", () => {
   });
 });
 
+describe("pruneMessages recovery grace", () => {
+  const mkQueryResult = (toolCallId: string, timestamp: number) => ({
+    role: "toolResult",
+    toolCallId,
+    toolName: "context_tree_query",
+    content: [{ type: "text", text: "VERBATIM RECOVERY OUTPUT" }],
+    isError: false,
+    timestamp,
+  });
+  const mkUser = (timestamp: number) => ({ role: "user", content: [{ type: "text", text: "go" }], timestamp });
+
+  it("renders a context_tree_query recovery output verbatim at age 0 within grace", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+    });
+    const messages = [mkQueryResult("tc-recover", 1)];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 3);
+    expect(out[0].content[0].text).toBe("VERBATIM RECOVERY OUTPUT");
+  });
+
+  it("stubs a context_tree_query recovery output aged past the grace window", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+    });
+    const messages: any[] = [mkQueryResult("tc-recover", 1), mkUser(2), mkUser(3), mkUser(4), mkUser(5)];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 3);
+    const tr = out.find((m: any) => m.toolCallId === "tc-recover") as any;
+    expect(tr.content[0].text).toContain("context_tree_query");
+    expect(tr.content[0].text).not.toBe("VERBATIM RECOVERY OUTPUT");
+  });
+
+  it("stubs at age 0 when recoveryGraceTurns is 0 (feature off)", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+    });
+    const messages = [mkQueryResult("tc-recover", 1)];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 0);
+    expect(out[0].content[0].text).not.toBe("VERBATIM RECOVERY OUTPUT");
+    expect(out[0].content[0].text).toContain("context_tree_query");
+  });
+
+  it("does not apply the grace window to non-context_tree_query outputs", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-bash"]),
+      shortRefs: new Map([["tc-bash", "t1"]]),
+    });
+    const messages = [
+      {
+        role: "toolResult",
+        toolCallId: "tc-bash",
+        toolName: "bash",
+        content: [{ type: "text", text: "VERBATIM RECOVERY OUTPUT" }],
+        isError: false,
+        timestamp: 1,
+      },
+    ];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 3);
+    expect(out[0].content[0].text).not.toBe("VERBATIM RECOVERY OUTPUT");
+    expect(out[0].content[0].text).toContain("context_tree_query");
+  });
+
+  it("isProtected precedence: a protected context_tree_query output stays verbatim even with grace off", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+      records: new Map([["tc-recover", {
+        toolCallId: "tc-recover", toolName: "context_tree_query", args: { path: "/h/skills/x/SKILL.md" },
+        resultText: "", isError: false, turnIndex: 0, timestamp: 1,
+      }]]),
+    });
+    const messages: any[] = [mkQueryResult("tc-recover", 1), mkUser(2), mkUser(3), mkUser(4), mkUser(5)];
+    const { messages: out } = pruneMessages(
+      messages, indexer, undefined, undefined, undefined,
+      { protectedTools: [], protectedPaths: ["**/skills/**/*.md"] },
+      0,
+    );
+    const tr = out.find((m: any) => m.toolCallId === "tc-recover") as any;
+    expect(tr.content[0].text).toBe("VERBATIM RECOVERY OUTPUT");
+  });
+
+  it("renders a spilled context_tree_query recovery output verbatim at age 0 within grace", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+      records: new Map([["tc-recover", {
+        toolCallId: "tc-recover", toolName: "context_tree_query", args: {},
+        resultText: "", resultPreview: "PREVIEW-HEAD", spillPath: "/blobs/tc-recover.txt",
+        spillBytes: 1048576, isError: false, turnIndex: 0, timestamp: 1,
+      }]]),
+    });
+    const messages = [mkQueryResult("tc-recover", 1)];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 3);
+    expect(out[0].content[0].text).toBe("VERBATIM RECOVERY OUTPUT");
+  });
+
+  it("stubs a spilled context_tree_query recovery output aged past the grace window to the spill-pointer stub", () => {
+    const indexer = makeMockIndexer({
+      summarized: new Set(["tc-recover"]),
+      shortRefs: new Map([["tc-recover", "t1"]]),
+      records: new Map([["tc-recover", {
+        toolCallId: "tc-recover", toolName: "context_tree_query", args: {},
+        resultText: "", resultPreview: "PREVIEW-HEAD", spillPath: "/blobs/tc-recover.txt",
+        spillBytes: 1048576, isError: false, turnIndex: 0, timestamp: 1,
+      }]]),
+    });
+    const messages: any[] = [mkQueryResult("tc-recover", 1), mkUser(2), mkUser(3), mkUser(4), mkUser(5)];
+    const { messages: out } = pruneMessages(messages, indexer, undefined, undefined, undefined, undefined, 3);
+    const tr = out.find((m: any) => m.toolCallId === "tc-recover") as any;
+    expect(tr.content[0].text).not.toBe("VERBATIM RECOVERY OUTPUT");
+    expect(tr.content[0].text).toContain("/blobs/tc-recover.txt");
+    expect(tr.content[0].text).toContain("spilled");
+  });
+});
+
 describe("sizeMessages", () => {
   it("counts hidden fields (thinking blocks), not just visible text", () => {
     // Two messages with identical visible .text but different hidden content.

package/src/pruner.ts

@@ -4,6 +4,7 @@ import { isProtected, type ProtectionConfig } from "./protected.js";
 import { applyChainCompressions } from "./chain-range-prune.js";
 import { purgeErroredArgs } from "./error-purge.js";
 import { stripOldThinking } from "./thinking-strip.js";
+import { inGraceRecoveryToolCallIds } from "./recovery-grace.js";
 
 /**
  * Estimate of a message array's context weight. Serializing the whole array
@@ -66,10 +67,12 @@ export function pruneMessages(
   errorPurge?: ErrorPurgeConfig,
   thinkingStrip?: ThinkingStripConfig,
   protection?: ProtectionConfig,
+  recoveryGraceTurns: number = 0,
 ): { messages: any[]; pruned: boolean; beforeChars: number; afterChars: number } {
   const beforeChars = sizeMessages(messages);
   // Phase 1: stub-replace summarized tool results
   let pruned = false;
+  const inGrace = inGraceRecoveryToolCallIds(messages, recoveryGraceTurns);
   const next = messages.map((msg) => {
     if (msg.role === "toolResult" && indexer.isSummarized(msg.toolCallId)) {
       const record = indexer.getRecord(msg.toolCallId);
@@ -81,6 +84,9 @@ export function pruneMessages(
       if (protection && record && isProtected(record.toolName, record.args, protection)) {
         return msg;
       }
+      if (inGrace.has(msg.toolCallId)) {
+        return msg;
+      }
       pruned = true;
       const ref = indexer.getShortRefForToolCallId(msg.toolCallId) ?? msg.toolCallId;
       const text = record?.spillPath

package/src/query-tool.ts

@@ -3,10 +3,11 @@ import { Type } from "@sinclair/typebox";
 import { truncateHead, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ToolCallIndexer } from "./indexer.js";
+import { QUERY_TOOL_NAME } from "./types.js";
 
 export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): void {
   pi.registerTool({
-    name: "context_tree_query",
+    name: QUERY_TOOL_NAME,
     label: "Query Original Tool History",
     description:
       "Retrieve original tool call results that have been pruned from active context. Pass the short refs listed in a pruner-summary message, e.g. context_tree_query({ toolCallIds: [\"t12\", \"t3\"] }), to get back the full original outputs.",

package/src/recovery-grace.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "bun:test";
+import { inGraceRecoveryToolCallIds } from "./recovery-grace.js";
+
+const user = () => ({ role: "user", content: [{ type: "text", text: "u" }] });
+const ctq = (id: string) => ({ role: "toolResult", toolCallId: id, toolName: "context_tree_query", content: [{ type: "text", text: "x" }] });
+const bash = (id: string) => ({ role: "toolResult", toolCallId: id, toolName: "bash", content: [{ type: "text", text: "x" }] });
+
+describe("inGraceRecoveryToolCallIds", () => {
+  it("includes a recovery output in the current user-turn-group (age 0)", () => {
+    const msgs = [user(), ctq("t1")];
+    expect([...inGraceRecoveryToolCallIds(msgs, 3)]).toEqual(["t1"]);
+  });
+  it("includes a recovery output exactly K user-turns old", () => {
+    const msgs = [user(), ctq("t1"), user(), user(), user()];
+    expect(inGraceRecoveryToolCallIds(msgs, 3).has("t1")).toBe(true);
+  });
+  it("excludes a recovery output older than K user-turns", () => {
+    const msgs = [user(), ctq("t1"), user(), user(), user(), user()];
+    expect(inGraceRecoveryToolCallIds(msgs, 3).has("t1")).toBe(false);
+  });
+  it("returns empty set when grace disabled (K=0)", () => {
+    const msgs = [user(), ctq("t1")];
+    expect(inGraceRecoveryToolCallIds(msgs, 0).size).toBe(0);
+  });
+  it("ignores non-recovery tool outputs", () => {
+    const msgs = [user(), bash("t1"), ctq("t2")];
+    expect([...inGraceRecoveryToolCallIds(msgs, 3)]).toEqual(["t2"]);
+  });
+  it("judges multiple recovery outputs by their own positions", () => {
+    const msgs = [user(), ctq("t1"), user(), user(), user(), user(), ctq("t2")];
+    const set = inGraceRecoveryToolCallIds(msgs, 3);
+    expect(set.has("t1")).toBe(false);
+    expect(set.has("t2")).toBe(true);
+  });
+});

package/src/recovery-grace.ts

@@ -0,0 +1,33 @@
+import { QUERY_TOOL_NAME } from "./types.js";
+
+/**
+ * Set of `context_tree_query` toolCallIds still inside the recovery grace
+ * window, computed positionally from the message array (no stored metadata).
+ *
+ * A recovery output's "user-turn-group" is the count of `role === "user"`
+ * messages at or before its position; its age is `nowUTG - that count`, where
+ * `nowUTG` is the total user messages in the array. It is in grace while
+ * `age <= graceTurns`. Works uniformly for render-context and session-branch
+ * arrays, so pruner Phase 1 and chain-compressor eligibility share one rule.
+ *
+ * `graceTurns <= 0` returns an empty set (feature disabled).
+ */
+export function inGraceRecoveryToolCallIds(messages: any[], graceTurns: number): Set<string> {
+  const result = new Set<string>();
+  if (!(graceTurns > 0)) return result;
+
+  let nowUTG = 0;
+  for (const m of messages) if (m?.role === "user") nowUTG++;
+
+  let seen = 0;
+  for (const m of messages) {
+    if (m?.role === "user") {
+      seen++;
+      continue;
+    }
+    if (m?.role === "toolResult" && m.toolName === QUERY_TOOL_NAME && typeof m.toolCallId === "string") {
+      if (nowUTG - seen <= graceTurns) result.add(m.toolCallId);
+    }
+  }
+  return result;
+}

package/src/types.ts

@@ -78,6 +78,10 @@ export const CUSTOM_TYPE_DEDUP_ALIAS = "context-prune-dedup-alias";
  */
 export const CUSTOM_TYPE_CHAIN = "context-prune-chain";
 
+/** The registered name of the recovery tool (src/query-tool.ts). Shared so the
+ * grace checks in pruner.ts / chain-compressor.ts cannot drift from registration. */
+export const QUERY_TOOL_NAME = "context_tree_query";
+
 /** pi.events channel for cross-extension cost contributions (an aggregator like pi-subagents folds these into one total). */
 export const EXTERNAL_COST_CHANNEL = "cost:external";
 
@@ -185,6 +189,19 @@ export const MIN_BATCH_CHARS_PRESETS: { value: string; label: string }[] = [
   { value: "5000", label: "5000" },
 ];
 
+/**
+ * Cycling presets for the `recoveryGraceTurns` setting in the SettingsList.
+ * Stored as strings; converted to number when applied. "0" disables the grace
+ * (recovery output stubs immediately, pre-feature behavior).
+ */
+export const RECOVERY_GRACE_PRESETS: { value: string; label: string }[] = [
+  { value: "0", label: "0 (disabled)" },
+  { value: "1", label: "1" },
+  { value: "3", label: "3 (default)" },
+  { value: "5", label: "5" },
+  { value: "8", label: "8" },
+];
+
 /**
  * Cycling presets for the `autoBudgetThreshold` setting (stored as strings;
  * the settings UI cycles string values). "0" is the disabled sentinel → null.
@@ -256,6 +273,14 @@ export interface ContextPruneConfig {
    * Default: 1000.
    */
   minBatchChars: number;
+  /**
+   * User-turn-groups a `context_tree_query` (recovery) output stays verbatim in
+   * context after recovery, before it reverts to the normal stub. Bounds the
+   * retrieve->re-stub->re-query loop without permanent retention. 0 disables
+   * (recovery output stubs immediately). Enforced at render time in pruner.ts
+   * (Phase 1) and chain-compressor.ts (eligibility), not at capture.
+   */
+  recoveryGraceTurns: number;
   /**
    * Tool names whose outputs must NEVER be pruned or summarized. Tool calls
    * with matching `toolName` are filtered out of the pruning capture path so
@@ -454,6 +479,7 @@ export const DEFAULT_CONFIG: ContextPruneConfig = {
   batchingMode: "turn",
   quietOversizedSkips: false,
   minBatchChars: 1000,
+  recoveryGraceTurns: 3,
   protectedTools: [],
   protectedPaths: ["**/skills/**/*.md"],
   chainCompression: {