pi-condense 2.7.0 → 2.9.0

package/src/chain-compressor.ts

@@ -1,8 +1,11 @@
 import { CUSTOM_TYPE_CHAIN } from "./types.js";
-import type { ChainRange, ChainCompressionEntry } from "./types.js";
+import type { ChainRange, ChainCompressionEntry, ToolCallRecord } from "./types.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import type { BlockRefIssuer } from "./block-refs.js";
-import { bareToolCallId, parseOccKey } from "./occurrence-key.js";
+import type { DiagnosticSink } from "./diagnostics.js";
+import { bareToolCallId, occKey, parseOccKey, resultTimestampOf } from "./occurrence-key.js";
+import { resolveRange } from "./chain-range-prune.js";
+import { extractToolResultText } from "./batch-capture.js";
 
 /**
  * Grace ids are keyed the same way `recovery-grace.ts` keys them: occurrence
@@ -65,6 +68,17 @@ export interface ChainCompressorIndexerDeps {
   getPerBatchSummariesForToolCallIds(toolCallIds: string[]): string[];
   getToolRefsForToolCallIds(toolCallIds: string[]): string[];
   registerChain(entry: import("./types.js").ChainCompressionEntry): void;
+  getIndex(): Map<string, ToolCallRecord>;
+  backfillChainRecords(
+    records: ToolCallRecord[],
+    opts: {
+      spillThreshold: number;
+      spillPreviewBytes: number;
+      sessionDir: string;
+      sessionId: string;
+      appendEntry: (customType: string, data?: unknown) => void;
+    },
+  ): Promise<import("./types.js").SummaryToolCallRef[]>;
 }
 
 export interface CompressEligibleDeps {
@@ -81,6 +95,85 @@ export interface CompressEligibleDeps {
    * the renderer falls back to the per-batch concatenation.
    */
   fuseRange?: (perBatchSummaryText: string) => Promise<string | null>;
+  /** MUST be the same withClosingMessage(...) array chain detection ran on - raw branch messages spuriously fail span resolution on the message_end path (see doc/specs/2026-08-14-uncovered-chain-deterministic-backfill.md). */
+  messages: any[];
+  diagnostics: Pick<DiagnosticSink, "report">;
+  backfill: { spillThreshold: number; spillPreviewBytes: number; sessionDir: string; sessionId: string };
+}
+
+/**
+ * Pure span walk backing the deterministic zero-LLM branch. Excludes
+ * protected middles (relocated verbatim at render, never phase-1 stubbed)
+ * and already-indexed occurrence keys (retry idempotence).
+ */
+export function extractChainRecords(
+  messages: any[],
+  chain: Pick<ChainRange, "startUserTimestamp" | "finalAssistantTimestamp" | "protectedToolCallIds">,
+  isIndexed: (occurrenceKey: string) => boolean,
+): ToolCallRecord[] {
+  const range = resolveRange(chain, messages);
+  if (!range) return [];
+  const protectedIds = new Set(chain.protectedToolCallIds ?? []);
+  const open = new Map<string, { toolName: string; args: unknown }>();
+  const records: ToolCallRecord[] = [];
+  for (let i = range.startIndex + 1; i < range.endIndex; i++) {
+    const msg = messages[i];
+    if (msg.role === "assistant" && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type === "toolCall") open.set(block.id, { toolName: block.name, args: block.input ?? block.args ?? block.arguments ?? {} });
+      }
+    } else if (msg.role === "toolResult") {
+      const call = open.get(msg.toolCallId);
+      if (!call) continue;
+      if (protectedIds.has(msg.toolCallId)) continue;
+      const resultTimestamp = resultTimestampOf(msg.timestamp);
+      if (resultTimestamp === undefined) continue;
+      const key = occKey(msg.toolCallId, resultTimestamp);
+      if (isIndexed(key)) continue;
+      records.push({
+        toolCallId: msg.toolCallId,
+        toolName: call.toolName,
+        args: call.args as Record<string, unknown>,
+        resultText: extractToolResultText(msg),
+        isError: msg.isError === true,
+        turnIndex: -1, // backfilled records have no batch turn; query tool renders "Turn: -1" (pinned)
+        timestamp: resultTimestamp,
+        resultTimestamp,
+      });
+    }
+  }
+  return records;
+}
+
+const EXCERPT_CAP = 200;
+function excerpt(args: unknown): string {
+  const s = JSON.stringify(args) ?? "";
+  return s.length <= EXCERPT_CAP ? s : s.slice(0, EXCERPT_CAP) + "...";
+}
+
+/** Deterministic zero-LLM body. Grammar pinned by tests - change both together. */
+export function buildDeterministicBody(records: ToolCallRecord[], refs: string[]): string {
+  const counts = new Map<string, number>();
+  for (const r of records) counts.set(r.toolName, (counts.get(r.toolName) ?? 0) + 1);
+  const histogram = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([name, n]) => `${name} x${n}`)
+    .join(", ");
+  const at = (r: ToolCallRecord) => r.resultTimestamp ?? r.timestamp;
+  const sorted = [...records].sort((a, b) => at(a) - at(b));
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  const seconds = Math.round((at(last) - at(first)) / 1000);
+  const refsLine = refs.length > 0 ? refs.join(", ") : records.map((r) => r.toolCallId).join(", ");
+  return [
+    "Deterministic chain compression (no per-batch summary existed for this span; raw outputs recoverable via context_tree_query).",
+    `Calls: ${records.length}`,
+    `Tools: ${histogram}`,
+    `Span: ${new Date(at(first)).toISOString()} -> ${new Date(at(last)).toISOString()} (${seconds}s)`,
+    `First: ${first.toolName} ${excerpt(first.args)}`,
+    `Last: ${last.toolName} ${excerpt(last.args)}`,
+    `Refs: ${refsLine}`,
+  ].join("\n");
 }
 
 export interface CompressEligibleResult {
@@ -121,7 +214,55 @@ export async function compressEligible(
     const lookupKeys = chain.middleOccurrenceKeys?.length ? chain.middleOccurrenceKeys : chain.middleToolCallIds;
 
     if (!deps.indexer.hasPerBatchSummaryCoveringAny(lookupKeys)) {
-      skipped.push({ startUserTimestamp: chain.startUserTimestamp, reason: "no-summary" });
+      // Deterministic zero-LLM fallback (spec 2026-08-14). Fail-closed: any
+      // failure below preserves the historical no-summary skip.
+      const index = deps.indexer.getIndex();
+      const indexed: ToolCallRecord[] = [];
+      for (const key of lookupKeys) {
+        const r = index.get(key);
+        if (r) indexed.push(r);
+      }
+      const fresh = extractChainRecords(deps.messages, chain, (k) => index.has(k));
+      if (fresh.length === 0 && indexed.length === 0) {
+        const protectedIds = new Set(chain.protectedToolCallIds ?? []);
+        const fullyProtected =
+          chain.middleToolCallIds.length > 0 && chain.middleToolCallIds.every((id) => protectedIds.has(id));
+        if (!fullyProtected) {
+          // Genuine span mismatch - nothing extractable, nothing durable.
+          deps.diagnostics.report(
+            "backfill-empty",
+            String(chain.startUserTimestamp),
+            `middles=${chain.middleToolCallIds.length}`,
+          );
+        }
+        skipped.push({ startUserTimestamp: chain.startUserTimestamp, reason: "no-summary" });
+        continue;
+      }
+      try {
+        if (fresh.length > 0) {
+          await deps.indexer.backfillChainRecords(fresh, { ...deps.backfill, appendEntry: deps.appendEntry });
+        }
+      } catch {
+        skipped.push({ startUserTimestamp: chain.startUserTimestamp, reason: "no-summary" });
+        continue;
+      }
+      const allRecords = [...indexed, ...fresh];
+      const toolRefs = deps.indexer.getToolRefsForToolCallIds(lookupKeys);
+      const entry: ChainCompressionEntry = {
+        blockId: deps.blockRefs.issue(),
+        startUserTimestamp: chain.startUserTimestamp,
+        droppedToolCallIds: chain.middleToolCallIds,
+        finalAssistantTimestamp: chain.finalAssistantTimestamp,
+        toolRefs,
+        compressedAt: deps.now(),
+        rangeSummaryText: buildDeterministicBody(allRecords, toolRefs),
+        bodySource: "deterministic",
+        ...(chain.protectedToolCallIds?.length ? { protectedToolCallIds: chain.protectedToolCallIds } : {}),
+        ...(chain.middleOccurrenceKeys?.length ? { droppedOccurrenceKeys: chain.middleOccurrenceKeys } : {}),
+      };
+      deps.appendEntry(CUSTOM_TYPE_CHAIN, entry);
+      deps.indexer.registerChain(entry);
+      compressedEntries.push(entry);
       continue;
     }
 

package/src/chain-range-prune.test.ts

@@ -627,6 +627,15 @@ describe("resolveRange", () => {
     msgs[2] = { ...msgs[2], timestamp: 1200 };
     expect(resolveRange(entry(), msgs)).toEqual({ startIndex: 0, endIndex: 3 });
   });
+
+  test("resolveRange accepts a minimal timestamp pair (backfill span walk)", () => {
+    const messages = [
+      { role: "user", timestamp: 100 },
+      { role: "assistant", timestamp: 200 },
+    ];
+    const range = resolveRange({ startUserTimestamp: 100, finalAssistantTimestamp: 200 }, messages);
+    expect(range).toEqual({ startIndex: 0, endIndex: 1 });
+  });
 });
 
 describe("applyChainCompressions - positional", () => {

package/src/chain-range-prune.ts

@@ -75,7 +75,7 @@ export function buildSyntheticChainMessage(
  * turns (doc/specs/2026-08-12-toolcall-id-collisions.md).
  */
 export function resolveRange(
-  entry: ChainCompressionEntry,
+  entry: Pick<ChainCompressionEntry, "startUserTimestamp" | "finalAssistantTimestamp">,
   messages: any[],
 ): { startIndex: number; endIndex: number } | null {
   if (entry.finalAssistantTimestamp === null) return null;

package/src/commands.test.ts

@@ -201,6 +201,16 @@ describe("diagnostic counters on the status line", () => {
       "\u2502 prune: ON \u00b7 diag u1",
     );
   });
+
+  it("appends b<N> for backfill-empty alongside u/m/o", () => {
+    const text = pruneStatusText(cfg(true), undefined, {
+      "unresolved-range": 2,
+      "range-id-mismatch": 0,
+      "orphan-sweep": 1,
+      "backfill-empty": 2,
+    });
+    expect(text).toBe("prune: ON \u00b7 diag u2/o1/b2");
+  });
 });
 
 describe("context metrics suffix on the status line", () => {

package/src/commands.ts

@@ -24,6 +24,7 @@ import {
 } from "./types.js";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { saveConfig } from "./config.js";
+import { MAX_BUDGET_WINDOW } from "./budget.js";
 import { formatTokens, formatCost, formatCharProgress, formatCompactCount } from "./stats.js";
 import { Container, Text, SettingsList, type SettingItem } from "@earendil-works/pi-tui";
 import { DynamicBorder, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
@@ -71,6 +72,7 @@ export function pruneStatusText(
         diagnostics["unresolved-range"] ? `u${diagnostics["unresolved-range"]}` : "",
         diagnostics["range-id-mismatch"] ? `m${diagnostics["range-id-mismatch"]}` : "",
         diagnostics["orphan-sweep"] ? `o${diagnostics["orphan-sweep"]}` : "",
+        diagnostics["backfill-empty"] ? `b${diagnostics["backfill-empty"]}` : "",
       ].filter(Boolean)
     : [];
   const suffix = diag.length > 0 ? ` \u00b7 diag ${diag.join("/")}` : "";
@@ -234,10 +236,12 @@ function maxTimeoutDescription(config: ContextPruneConfig): string {
 }
 
 function autoBudgetThresholdDescription(config: ContextPruneConfig): string {
+  const cap = `${MAX_BUDGET_WINDOW / 1000}k`;
   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.`;
+    return `Token-budget auto-flush: force a prune when context usage reaches this share of the window (or ${cap} tokens, whichever comes first), regardless of prune-on mode. Currently off. Pick a percentage to enable.`;
   }
-  return `Token-budget auto-flush: force a prune when context usage reaches ${Math.round(config.autoBudgetThreshold * 100)}% of the window, regardless of prune-on mode. Set to Off to disable.`;
+  const pct = Math.round(config.autoBudgetThreshold * 100);
+  return `Token-budget auto-flush: force a prune when context usage reaches ${pct}% of the window or ${cap} tokens, whichever comes first, regardless of prune-on mode. The ${cap} ceiling keeps this reachable on huge-window models. Set to Off to disable.`;
 }
 
 function protectedToolsDisplay(list: string[]): string {

package/src/diagnostics.test.ts

@@ -46,7 +46,7 @@ describe("DiagnosticSink", () => {
 
   test("counts are per kind and start at zero", () => {
     const { sink } = sinkWithLog();
-    expect(sink.counts()).toEqual({ "unresolved-range": 0, "range-id-mismatch": 0, "orphan-sweep": 0 });
+    expect(sink.counts()).toEqual({ "unresolved-range": 0, "range-id-mismatch": 0, "orphan-sweep": 0, "backfill-empty": 0 });
     sink.report("orphan-sweep", "a,b", "swept 2");
     expect(sink.counts()["orphan-sweep"]).toBe(1);
   });
@@ -96,7 +96,7 @@ describe("DiagnosticSink", () => {
     sink.report("unresolved-range", "b5", "x");
     sink.report("orphan-sweep", "a", "y");
     sink.reset();
-    expect(sink.counts()).toEqual({ "unresolved-range": 0, "range-id-mismatch": 0, "orphan-sweep": 0 });
+    expect(sink.counts()).toEqual({ "unresolved-range": 0, "range-id-mismatch": 0, "orphan-sweep": 0, "backfill-empty": 0 });
   });
 
   test("reset() allows a previously-seen (kind, dedupKey) to report again", () => {
@@ -112,3 +112,12 @@ describe("DiagnosticSink", () => {
     expect(sink.counts()["unresolved-range"]).toBe(1);
   });
 });
+
+test("counts backfill-empty like any other kind", () => {
+  const appended: Array<{ type: string; data: any }> = [];
+  const sink = new DiagnosticSink((type, data) => appended.push({ type, data }));
+  sink.report("backfill-empty", "b5", "middleCount=0");
+  sink.report("backfill-empty", "b5", "middleCount=0"); // deduped
+  expect(sink.counts()["backfill-empty"]).toBe(1);
+  expect(appended.length).toBe(1);
+});

package/src/diagnostics.ts

@@ -13,6 +13,7 @@ export class DiagnosticSink {
     "unresolved-range": 0,
     "range-id-mismatch": 0,
     "orphan-sweep": 0,
+    "backfill-empty": 0,
   };
 
   constructor(private readonly appendEntry: (customType: string, data?: unknown) => void) {}

package/src/id-collision.integration.test.ts

@@ -89,6 +89,9 @@ const primeIndexer = async (
     blockRefs: { issue: () => `b${nextBlock++}` } as any,
     appendEntry: append,
     now: () => 9000,
+    messages,
+    diagnostics: { report: () => {} },
+    backfill: { spillThreshold: 100_000, spillPreviewBytes: 500, sessionDir: "/tmp/unused", sessionId: "s" },
   });
 
   return { indexer, appended, refsByToolCallId };
@@ -151,7 +154,17 @@ describe("id collision, end to end", () => {
     expectNoOrphanToolResults(out.messages);
   });
 
-  test("live-flush bare-id keying bug: chains are skipped as no-summary, no synthetics emitted", async () => {
+  // Regression for the bare-id keying bug (ref #8): registerSummaryBody keyed
+  // with `tc.toolCallId` (no resultTimestamp) mismatches hasPerBatchSummaryCoveringAny's
+  // occurrence-key lookups, so both chains fall through to the "no per-batch
+  // summary covers this span" branch. Pre-2026-08-14 that branch was a permanent
+  // no-summary skip (the bug this test used to pin). Since the deterministic
+  // backfill fallback (doc/specs/2026-08-14-uncovered-chain-deterministic-backfill.md),
+  // that branch instead compresses deterministically from already-indexed
+  // records (both chains' tool calls were indexed via addBatch, just not
+  // summary-covered under the right key) - so the keying bug can no longer
+  // strand a chain through this path. Pin the new correct behavior instead.
+  test("live-flush bare-id keying bug: chains compress deterministically instead of stranding", async () => {
     const messages = buildSession();
     // Mirrors the production BUG exactly: `tc.toolCallId` with no resultTimestamp,
     // matching index.ts's pre-fix `batch.toolCalls.map((tc) => tc.toolCallId)`.
@@ -159,7 +172,12 @@ describe("id collision, end to end", () => {
     const out = pruneMessages(messages, indexer, chainConfig);
 
     const synthetics = syntheticsOf(out.messages);
-    expect(synthetics).toHaveLength(0);
+    expect(synthetics).toHaveLength(2);
+    for (const s of synthetics) {
+      expect(s.content[0].text).toContain("Deterministic chain compression");
+      expect(s.content[0].text).toMatch(/Refs: t\d+/);
+    }
+    expectNoOrphanToolResults(out.messages);
   });
 
   test("re-rendering the same session is deep-equal", async () => {

package/src/indexer.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { ToolCallIndexer } from "./indexer.js";
-import { CUSTOM_TYPE_INDEX, CUSTOM_TYPE_SUMMARY, CUSTOM_TYPE_DEDUP_ALIAS } from "./types.js";
-import type { CapturedBatch } from "./types.js";
+import { CUSTOM_TYPE_INDEX, CUSTOM_TYPE_SUMMARY, CUSTOM_TYPE_DEDUP_ALIAS, CUSTOM_TYPE_CHAIN } from "./types.js";
+import type { CapturedBatch, ToolCallRecord } from "./types.js";
+import { occKey } from "./occurrence-key.js";
 
 const batch = (
   turnIndex: number,
@@ -334,3 +338,208 @@ describe("session rebuild", () => {
     expect(indexer.isSummarized("bash_8")).toBe(true);
   });
 });
+
+function backfillOpts(appended: Array<{ type: string; data: any }>, tmpDir: string) {
+  return {
+    spillThreshold: 100_000,
+    spillPreviewBytes: 500,
+    sessionDir: tmpDir,
+    sessionId: "test-session",
+    appendEntry: (type: string, data?: unknown) => appended.push({ type, data }),
+  };
+}
+
+function record(id: string, ts: number, over: Partial<ToolCallRecord> = {}): ToolCallRecord {
+  return {
+    toolCallId: id,
+    toolName: "bash",
+    args: { command: "ls" },
+    resultText: "out-" + id,
+    isError: false,
+    turnIndex: -1,
+    timestamp: ts,
+    resultTimestamp: ts,
+    ...over,
+  };
+}
+
+describe("backfillChainRecords", () => {
+  test("happy path: indexes records, returns refs, persists one entry", async () => {
+    const indexer = new ToolCallIndexer();
+    const appended: Array<{ type: string; data: any }> = [];
+    const records = [record("a", 1), record("b", 2)];
+
+    const refs = await indexer.backfillChainRecords(records, backfillOpts(appended, "/tmp/unused"));
+
+    expect(refs).toHaveLength(2);
+    for (const ref of refs) expect(ref.shortId).toMatch(/^t\d+$/);
+
+    expect(indexer.getRecord("a")?.toolCallId).toBe("a");
+    expect(indexer.resolveToolCallId(refs[0].shortId)).toBe(occKey("a", 1));
+
+    expect(appended).toHaveLength(1);
+    expect(appended[0].type).toBe(CUSTOM_TYPE_INDEX);
+    expect(appended[0].data.backfilled).toBe(true);
+    expect(appended[0].data.refs).toHaveLength(2);
+    expect(appended[0].data.toolCalls).toHaveLength(2);
+  });
+
+  test("dedup exclusion: backfilled records never seed contentHashToOriginal", async () => {
+    const indexer = new ToolCallIndexer();
+    const appended: Array<{ type: string; data: any }> = [];
+    await indexer.backfillChainRecords([record("a", 1)], backfillOpts(appended, "/tmp/unused"));
+
+    expect(indexer.lookupByContent("bash", "out-a")).toBeUndefined();
+  });
+
+  test("append failure aborts atomically: no partial index state", async () => {
+    const indexer = new ToolCallIndexer();
+    const opts = {
+      ...backfillOpts([], "/tmp/unused"),
+      appendEntry: () => {
+        throw new Error("append failed");
+      },
+    };
+
+    await expect(indexer.backfillChainRecords([record("a", 1)], opts)).rejects.toThrow();
+
+    expect(indexer.getIndex().size).toBe(0);
+    expect(indexer.getShortRefForToolCallId(occKey("a", 1))).toBeUndefined();
+  });
+
+  test("spill: large result text is written to a sidecar blob", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "pi-condense-backfill-"));
+    const indexer = new ToolCallIndexer();
+    const appended: Array<{ type: string; data: any }> = [];
+    const bigText = "x".repeat(200_001);
+    const opts = { ...backfillOpts(appended, tmpDir), spillThreshold: 200_000 };
+
+    await indexer.backfillChainRecords([record("a", 1, { resultText: bigText })], opts);
+
+    const persistedRecord = appended[0].data.toolCalls[0];
+    expect(persistedRecord.spillPath).toBeTruthy();
+    expect(persistedRecord.resultText).toBe("");
+    expect(persistedRecord.resultPreview).toBeTruthy();
+    expect(persistedRecord.contentHash).toBeTruthy();
+
+    const blobContents = await readFile(persistedRecord.spillPath, "utf-8");
+    expect(blobContents).toBe(bigText);
+  });
+
+  test("reconstruction round-trip: backfilled entry replays without seeding dedup", async () => {
+    const indexer = new ToolCallIndexer();
+    const appended: Array<{ type: string; data: any }> = [];
+    const refs = await indexer.backfillChainRecords([record("a", 1)], backfillOpts(appended, "/tmp/unused"));
+
+    const indexEntry = { type: "custom", customType: CUSTOM_TYPE_INDEX, data: appended[0].data };
+    const rebuilt = new ToolCallIndexer();
+    const ctx = { sessionManager: { getBranch: () => [indexEntry] } } as any;
+    rebuilt.reconstructFromSession(ctx);
+
+    expect(rebuilt.getRecord("a")?.toolCallId).toBe("a");
+    expect(rebuilt.resolveToolCallId(refs[0].shortId)).toBe(occKey("a", 1));
+    expect(rebuilt.lookupByContent("bash", "out-a")).toBeUndefined();
+  });
+
+  test("legacy round-trip unchanged: pre-change entries (no backfilled/refs) still seed dedup", () => {
+    const indexEntry = {
+      type: "custom",
+      customType: CUSTOM_TYPE_INDEX,
+      data: { toolCalls: [record("a", 1)] },
+    };
+    const indexer = new ToolCallIndexer();
+    const ctx = { sessionManager: { getBranch: () => [indexEntry] } } as any;
+    indexer.reconstructFromSession(ctx);
+
+    expect(indexer.lookupByContent("bash", "out-a")).toBe(occKey("a", 1));
+  });
+
+  test("full legacy session round-trip: pre-change context-prune-chain + context-prune-index entries reconstruct to identical state", () => {
+    // Mirrors a real pre-change session: a summarized batch (index entry +
+    // per-batch summary entry, both pre-existing shapes) followed by a
+    // pre-change chain-compression entry (no bodySource - that field didn't
+    // exist yet) recording the range-drop decision over that batch's calls.
+    const indexEntry = {
+      type: "custom",
+      customType: CUSTOM_TYPE_INDEX,
+      data: {
+        toolCalls: [
+          {
+            toolCallId: "tc1",
+            toolName: "bash",
+            args: { cmd: "ls" },
+            resultText: "listing",
+            isError: false,
+            turnIndex: 0,
+            timestamp: 100,
+            resultTimestamp: 110,
+          },
+          {
+            toolCallId: "tc2",
+            toolName: "read",
+            args: { path: "f" },
+            resultText: "file contents",
+            isError: false,
+            turnIndex: 0,
+            timestamp: 100,
+            resultTimestamp: 210,
+          },
+        ],
+      },
+    };
+    const summaryEntry = {
+      type: "custom_message",
+      customType: CUSTOM_TYPE_SUMMARY,
+      content: "summarized tc1 and tc2",
+      details: {
+        toolCallRefs: [
+          { shortId: "t1", toolCallId: "tc1", resultTimestamp: 110 },
+          { shortId: "t2", toolCallId: "tc2", resultTimestamp: 210 },
+        ],
+        toolNames: ["bash", "read"],
+        turnIndex: 0,
+        timestamp: 100,
+      },
+    };
+    // Pre-change shape: no `bodySource` field (introduced by the uncovered-
+    // chain backfill feature; its absence must preserve existing semantics).
+    const chainEntry = {
+      type: "custom",
+      customType: CUSTOM_TYPE_CHAIN,
+      data: {
+        blockId: "b1",
+        startUserTimestamp: 50,
+        droppedToolCallIds: ["tc1", "tc2"],
+        droppedOccurrenceKeys: [occKey("tc1", 110), occKey("tc2", 210)],
+        finalAssistantTimestamp: 300,
+        toolRefs: ["t1", "t2"],
+        compressedAt: 12345,
+        rangeSummaryText: "fused range summary of tc1+tc2",
+      },
+    };
+
+    const indexer = new ToolCallIndexer();
+    const ctx = {
+      // Deep-clone so the byte-identity assertion below compares against the
+      // original fixture, not the same object reference the registry stored.
+      sessionManager: { getBranch: () => structuredClone([indexEntry, summaryEntry, chainEntry]) },
+    } as any;
+    indexer.reconstructFromSession(ctx);
+
+    // Chain registry populated, entry reconstructs byte-identical to what was persisted.
+    const entries = indexer.getChainEntries();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toEqual(chainEntry.data as any);
+    expect(entries[0].bodySource).toBeUndefined();
+
+    // Refs resolve exactly as a pre-change session would have resolved them.
+    expect(indexer.getRecord("t1")?.resultText).toBe("listing");
+    expect(indexer.getRecord("t2")?.resultText).toBe("file contents");
+    expect(indexer.resolveToolCallId("t1")).toBe(occKey("tc1", 110));
+    expect(indexer.resolveToolCallId("t2")).toBe(occKey("tc2", 210));
+
+    // Dedup canonical seeded (non-backfilled legacy index entry -> normal addBatch-equivalent seeding).
+    expect(indexer.lookupByContent("bash", "listing")).toBe(occKey("tc1", 110));
+    expect(indexer.lookupByContent("read", "file contents")).toBe(occKey("tc2", 210));
+  });
+});

package/src/indexer.ts

@@ -19,6 +19,8 @@ import {
 } from "./summary-refs.js";
 import { hashToolResult } from "./content-hash.js";
 import { bareToolCallId, occKey, parseOccKey } from "./occurrence-key.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { applySpill, blobDirFor, blobPathFor } from "./spill.js";
 
 export class ToolCallIndexer {
   /** occurrence key (`id@resultTimestamp`, or bare id for legacy) -> record */
@@ -78,17 +80,22 @@ export class ToolCallIndexer {
     for (const entry of branch) {
       if (entry.type === "custom" && (entry as any).customType === CUSTOM_TYPE_INDEX) {
         const data = (entry as any).data as IndexEntryData;
+        const backfilled = data.backfilled === true;
         if (data && Array.isArray(data.toolCalls)) {
           for (const toolCall of data.toolCalls) {
             const key = this.indexRecord(toolCall);
             // First-seen wins so the contentHashToOriginal map matches what
-            // addBatch would have produced at append time.
-            const hash = toolCall.contentHash ?? hashToolResult(toolCall.toolName, toolCall.resultText);
-            if (!this.contentHashToOriginal.has(hash)) {
-              this.contentHashToOriginal.set(hash, key);
+            // addBatch would have produced at append time. Backfilled records
+            // never seed this map (dedup poison guard - see backfillChainRecords).
+            if (!backfilled) {
+              const hash = toolCall.contentHash ?? hashToolResult(toolCall.toolName, toolCall.resultText);
+              if (!this.contentHashToOriginal.has(hash)) {
+                this.contentHashToOriginal.set(hash, key);
+              }
             }
           }
         }
+        if (backfilled && Array.isArray(data.refs)) this.registerSummaryRefs(data.refs);
         continue;
       }
 
@@ -503,4 +510,38 @@ export class ToolCallIndexer {
 
     appendEntry(CUSTOM_TYPE_INDEX, { toolCalls: records } as IndexEntryData);
   }
+
+  /**
+   * Atomic recoverability backfill for an uncovered chain (spec
+   * 2026-08-14-uncovered-chain-deterministic-backfill). Append-before-commit:
+   * in-memory maps are touched only after the index entry persisted. Records
+   * never seed contentHashToOriginal (dedup poison guard). Refs ride the
+   * entry so they survive session restart without a summary message.
+   */
+  async backfillChainRecords(
+    records: ToolCallRecord[],
+    opts: {
+      spillThreshold: number;
+      spillPreviewBytes: number;
+      sessionDir: string;
+      sessionId: string;
+      appendEntry: (customType: string, data?: unknown) => void;
+    },
+  ): Promise<SummaryToolCallRef[]> {
+    for (const r of records) {
+      if (r.resultText.length < opts.spillThreshold) continue;
+      const key = occKey(r.toolCallId, r.resultTimestamp);
+      const path = blobPathFor(opts.sessionDir, opts.sessionId, key);
+      await mkdir(blobDirFor(opts.sessionDir, opts.sessionId), { recursive: true });
+      await writeFile(path, r.resultText, "utf-8"); // throw = abort backfill (fail-closed)
+      applySpill(r, path, opts.spillPreviewBytes);
+    }
+    const calls = records.map((r) => ({ toolCallId: r.toolCallId, resultTimestamp: r.resultTimestamp }));
+    const { refs, nextIndex } = buildShortToolCallRefs(calls, this.nextShortAliasNumber);
+    this.nextShortAliasNumber = nextIndex; // burned numbers on failure are acceptable (monotonic, opaque)
+    opts.appendEntry(CUSTOM_TYPE_INDEX, { toolCalls: records, backfilled: true, refs } satisfies IndexEntryData);
+    for (const r of records) this.indexRecord(r);
+    this.registerSummaryRefs(refs);
+    return refs;
+  }
 }

package/src/query-tool.test.ts

@@ -114,4 +114,33 @@ describe("context_tree_query occurrence handling", () => {
     expect(text).not.toContain("undefined");
     expect(text).not.toContain("@legacy");
   });
+
+  test("backfilled record (turnIndex -1) renders 'Turn: -1' (cosmetic pin, ref #10)", async () => {
+    const idx = new ToolCallIndexer();
+    const appended: Array<{ type: string; data: any }> = [];
+    await idx.backfillChainRecords(
+      [
+        {
+          toolCallId: "bash_bf",
+          toolName: "bash",
+          args: { command: "ls" },
+          resultText: "backfilled-output",
+          isError: false,
+          turnIndex: -1,
+          timestamp: 1,
+          resultTimestamp: 1,
+        },
+      ],
+      {
+        spillThreshold: 100_000,
+        spillPreviewBytes: 500,
+        sessionDir: "/tmp/unused",
+        sessionId: "test-session",
+        appendEntry: (type: string, data?: unknown) => appended.push({ type, data }),
+      },
+    );
+
+    const text = await runTool(idx, ["bash_bf@1"]);
+    expect(text).toContain("Turn: -1");
+  });
 });