pi-condense 2.2.1 → 2.4.0

package/src/commands.ts

@@ -11,6 +11,9 @@ import {
   PROGRESS_WIDGET_ID,
   SUMMARIZER_THINKING_LEVELS,
   MIN_BATCH_CHARS_PRESETS,
+  RECOVERY_GRACE_PRESETS,
+  SUMMARIZER_IDLE_TIMEOUT_PRESETS,
+  SUMMARIZER_MAX_TIMEOUT_PRESETS,
   AUTO_BUDGET_PRESETS,
   ROLLING_WINDOW_PRESETS,
   KEEP_LAST_TURNS_PRESETS,
@@ -99,6 +102,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 +194,26 @@ 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 idleTimeoutDescription(config: ContextPruneConfig): string {
+  if (config.summarizerIdleTimeoutMs === 0) {
+    return "Summarizer idle timeout DISABLED - a stalled stream is only bounded by the ceiling (or not at all if that is 0 too).";
+  }
+  return `Abort a summarizer call after ${Math.round(config.summarizerIdleTimeoutMs / 1000)}s of silence (no stream event). Resets on every event, so it never aborts a flowing generation; a timeout feeds the same outage-fallback retry as a provider error. Set 0 to disable.`;
+}
+function maxTimeoutDescription(config: ContextPruneConfig): string {
+  if (config.summarizerMaxTimeoutMs === 0) {
+    return "Summarizer total-duration ceiling DISABLED - only the idle timeout bounds a call.";
+  }
+  return `Hard ceiling on total duration of a single summarizer call: ${Math.round(config.summarizerMaxTimeoutMs / 1000)}s. Backstop for a stream that dribbles forever without going idle. Set 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 +268,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 +572,33 @@ 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: "summarizerIdleTimeoutMs",
+              label: "Summarizer idle timeout",
+              values: SUMMARIZER_IDLE_TIMEOUT_PRESETS.map((p) => p.value),
+              currentValue: SUMMARIZER_IDLE_TIMEOUT_PRESETS.some((p) => p.value === String(config.summarizerIdleTimeoutMs))
+                ? String(config.summarizerIdleTimeoutMs)
+                : (SUMMARIZER_IDLE_TIMEOUT_PRESETS.find((p) => p.value === String(DEFAULT_CONFIG.summarizerIdleTimeoutMs))?.value ?? SUMMARIZER_IDLE_TIMEOUT_PRESETS[0].value), // fall back to the default preset if a custom value isn't in the cycle
+              description: idleTimeoutDescription(config),
+            },
+            {
+              id: "summarizerMaxTimeoutMs",
+              label: "Summarizer max timeout",
+              values: SUMMARIZER_MAX_TIMEOUT_PRESETS.map((p) => p.value),
+              currentValue: SUMMARIZER_MAX_TIMEOUT_PRESETS.some((p) => p.value === String(config.summarizerMaxTimeoutMs))
+                ? String(config.summarizerMaxTimeoutMs)
+                : (SUMMARIZER_MAX_TIMEOUT_PRESETS.find((p) => p.value === String(DEFAULT_CONFIG.summarizerMaxTimeoutMs))?.value ?? SUMMARIZER_MAX_TIMEOUT_PRESETS[0].value), // fall back to the default preset if a custom value isn't in the cycle
+              description: maxTimeoutDescription(config),
+            },
             {
               id: "autoBudgetThreshold",
               label: "Auto-flush at context %",
@@ -705,6 +758,23 @@ 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 === "summarizerIdleTimeoutMs") {
+              const parsed = Number.parseInt(newValue, 10);
+              newConfig.summarizerIdleTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CONFIG.summarizerIdleTimeoutMs;
+              const it = items.find((item) => item.id === "summarizerIdleTimeoutMs");
+              if (it) it.description = idleTimeoutDescription(newConfig);
+            } else if (id === "summarizerMaxTimeoutMs") {
+              const parsed = Number.parseInt(newValue, 10);
+              newConfig.summarizerMaxTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CONFIG.summarizerMaxTimeoutMs;
+              const it = items.find((item) => item.id === "summarizerMaxTimeoutMs");
+              if (it) it.description = maxTimeoutDescription(newConfig);
             } else if (id === "autoBudgetThreshold") {
               const parsed = Number.parseFloat(newValue);
               newConfig.autoBudgetThreshold =
@@ -812,8 +882,9 @@ export function registerCommands(
           const statsLine = s.callCount > 0
             ? `\n  --- summarizer ---\n  calls:       ${s.callCount}\n  input:       ${formatTokens(s.totalInputTokens)} tokens\n  output:      ${formatTokens(s.totalOutputTokens)} tokens\n  cost:        ${formatCost(s.totalCost)}`
             : "\n  (no summarizer calls yet)";
+          const fmtTimeout = (ms: number) => (ms === 0 ? "disabled" : `${Math.round(ms / 1000)}s`);
           ctx.ui.notify(
-            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}`,
+            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  idle to:  ${fmtTimeout(cfg.summarizerIdleTimeoutMs)}\n  max to:   ${fmtTimeout(cfg.summarizerMaxTimeoutMs)}\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}`,
           );
           break;
         }
@@ -1153,6 +1224,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,101 @@
+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 resolves the settings path from getAgentDir() lazily on each
+ * read/write, so PI_CODING_AGENT_DIR set here is honored regardless of import
+ * order (bun shares the module registry across test files). 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 settingsPath: typeof import("./config.js").settingsPath;
+
+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;
+  settingsPath = mod.settingsPath;
+});
+
+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(settingsPath(), 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);
+  });
+});
+
+describe("loadConfig summarizer timeout normalization", () => {
+  it("defaults both timeouts when absent", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(DEFAULT_CONFIG.summarizerIdleTimeoutMs);
+    expect(config.summarizerMaxTimeoutMs).toBe(DEFAULT_CONFIG.summarizerMaxTimeoutMs);
+  });
+
+  it("preserves explicit 0 (disabled) for both", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: 0, summarizerMaxTimeoutMs: 0 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(0);
+    expect(config.summarizerMaxTimeoutMs).toBe(0);
+  });
+
+  it("falls back to default for a negative idle timeout", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: -5 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(DEFAULT_CONFIG.summarizerIdleTimeoutMs);
+  });
+
+  it("falls back to default for NaN max timeout", async () => {
+    // JSON.stringify serializes NaN to null; normalize's typeof-number guard rejects it.
+    await writeContextPrune({ summarizerMaxTimeoutMs: Number.NaN });
+    const config = await loadConfig();
+    expect(config.summarizerMaxTimeoutMs).toBe(DEFAULT_CONFIG.summarizerMaxTimeoutMs);
+  });
+
+  it("floors a fractional idle timeout", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: 1234.9 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(1234);
+  });
+});

package/src/config.ts

@@ -15,8 +15,14 @@ import { DEFAULT_CONFIG, PRUNE_ON_MODES, SUMMARIZER_THINKING_LEVELS } from "./ty
  * Resolved against `getAgentDir()` so it honors `PI_CODING_AGENT_DIR`
  * (defaults to `~/.pi/agent`). Each pi preset directory therefore gets its
  * own context-prune config — including its own summarizer model.
+ *
+ * Computed lazily on each read/write rather than frozen at module load, so the
+ * resolved path always reflects the current `PI_CODING_AGENT_DIR` regardless of
+ * when the module was first imported.
  */
-export const SETTINGS_PATH = join(getAgentDir(), "settings.json");
+export function settingsPath(): string {
+  return join(getAgentDir(), "settings.json");
+}
 
 /** Top-level key under which context-prune state lives in `settings.json`. */
 export const SETTINGS_KEY = "contextPrune" as const;
@@ -52,6 +58,24 @@ function normalize(existing: Partial<ContextPruneConfig>): ContextPruneConfig {
       merged.minBatchChars >= 0
         ? Math.floor(merged.minBatchChars)
         : DEFAULT_CONFIG.minBatchChars,
+    summarizerIdleTimeoutMs:
+      typeof merged.summarizerIdleTimeoutMs === "number" &&
+      Number.isFinite(merged.summarizerIdleTimeoutMs) &&
+      merged.summarizerIdleTimeoutMs >= 0
+        ? Math.floor(merged.summarizerIdleTimeoutMs)
+        : DEFAULT_CONFIG.summarizerIdleTimeoutMs,
+    summarizerMaxTimeoutMs:
+      typeof merged.summarizerMaxTimeoutMs === "number" &&
+      Number.isFinite(merged.summarizerMaxTimeoutMs) &&
+      merged.summarizerMaxTimeoutMs >= 0
+        ? Math.floor(merged.summarizerMaxTimeoutMs)
+        : DEFAULT_CONFIG.summarizerMaxTimeoutMs,
+    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
@@ -100,7 +124,7 @@ async function readJsonObject(path: string): Promise<Record<string, unknown> | u
 
 /** Reads `<agent-dir>/settings.json` and returns the `contextPrune` block, or defaults. */
 export async function loadConfig(): Promise<ContextPruneConfig> {
-  const main = await readJsonObject(SETTINGS_PATH);
+  const main = await readJsonObject(settingsPath());
   const namespaced = main?.[SETTINGS_KEY];
   if (namespaced && typeof namespaced === "object" && !Array.isArray(namespaced)) {
     return normalize(namespaced as Partial<ContextPruneConfig>);
@@ -117,10 +141,11 @@ export async function loadConfig(): Promise<ContextPruneConfig> {
  * last-write-wins race only loses a single change, never corrupts the file.
  */
 export async function saveConfig(config: ContextPruneConfig): Promise<void> {
-  const current = (await readJsonObject(SETTINGS_PATH)) ?? {};
+  const path = settingsPath();
+  const current = (await readJsonObject(path)) ?? {};
   const next = { ...current, [SETTINGS_KEY]: config };
-  await mkdir(dirname(SETTINGS_PATH), { recursive: true });
-  const tmpPath = `${SETTINGS_PATH}.${randomBytes(8).toString("hex")}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  const tmpPath = `${path}.${randomBytes(8).toString("hex")}.tmp`;
   await writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`);
-  await rename(tmpPath, SETTINGS_PATH);
+  await rename(tmpPath, path);
 }

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;
+}