pi-condense 2.5.0 → 2.6.0

package/src/pruner.ts

@@ -1,9 +1,13 @@
+import { createHash } from "node:crypto";
 import type { ToolCallIndexer } from "./indexer.js";
 import type { ChainCompressionConfig, ErrorPurgeConfig } from "./types.js";
 import { isProtected, type ProtectionConfig } from "./protected.js";
 import { applyChainCompressions } from "./chain-range-prune.js";
 import { purgeErroredArgs } from "./error-purge.js";
 import { inGraceRecoveryToolCallIds } from "./recovery-grace.js";
+import { occKey } from "./occurrence-key.js";
+import { sweepOrphanToolResults } from "./orphan-sweep.js";
+import type { DiagnosticSink } from "./diagnostics.js";
 
 /**
  * Estimate of a message array's context weight. Serializing the whole array
@@ -16,7 +20,7 @@ export function sizeMessages(messages: any[]): number {
 }
 
 /**
- * Transforms the `context` event message array in three phases:
+ * Transforms the `context` event message array in four phases:
  *
  * Phase 1 — stub-replace: ToolResultMessages for summarized tool calls are
  * replaced with short stubs pointing the model at `context_tree_query`.
@@ -42,6 +46,12 @@ export function sizeMessages(messages: any[]): number {
  * synthetic user message wrapping the existing per-batch summary text.
  * Only runs when `chainCompression.enabled` and chain entries exist.
  *
+ * Phase 4 — orphan sweep: structural post-condition run unconditionally over
+ * the final array. Removes any toolResult whose matching toolCall id was not
+ * opened by the immediately preceding assistant turn (per-turn open set, not
+ * cumulative — see src/orphan-sweep.ts). Reference-preserving when nothing is
+ * swept, so a clean render still returns the identical input array.
+ *
  * Return shape:
  *   - `pruned: true`  — at least one change happened; the returned
  *     `messages` is a freshly allocated array.
@@ -66,46 +76,61 @@ export function pruneMessages(
   errorPurge?: ErrorPurgeConfig,
   protection?: ProtectionConfig,
   recoveryGraceTurns: number = 0,
+  diagnostics?: DiagnosticSink,
 ): { messages: any[]; pruned: boolean; beforeChars: number; afterChars: number } {
   // 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);
-      // Render-time re-check: a record summarized before protectedPaths
-      // covered it is repaired here — the raw toolResult still lives in the
-      // session JSONL, so skipping the stub restores it verbatim.
-      // Dedup aliases resolve to the original record, so an alias whose own
-      // path is protected but whose original isn't stays stubbed (edge case).
-      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
-        ? [
-            `[Oversized output spilled to file — ${record.spillBytes ?? "?"} bytes.]`,
-            `Tool: ${record.toolName}`,
-            `Preview (head):`,
-            record.resultPreview ?? "",
-            `Full output — read this file (offset/limit supported): ${record.spillPath}`,
-            `Or use context_tree_query with ref \`${ref}\`.`,
-          ].join("\n")
-        : `[Summarized in pruner summary, ref \`${ref}\`. Use context_tree_query to retrieve full output.]`;
-      return {
-        role: "toolResult",
-        toolCallId: msg.toolCallId,
-        toolName: msg.toolName,
-        content: [{ type: "text", text }],
-        isError: false,
-        timestamp: msg.timestamp,
-      };
+    if (msg.role !== "toolResult") return msg;
+
+    // Fail-closed: when the message carries a timestamp, the occurrence key
+    // is tried first. The bare id is consulted only as a fallback, and only
+    // when `hasLegacyBareRecord` confirms it is LEGACY-ONLY (no occurrence
+    // siblings) - a mixed bare+occurrence id fails closed there too, since a
+    // live result under a reused id is not the legacy one. A permissive
+    // bare-id fallback would stub a live result because an older occurrence
+    // (or the legacy record) of the same provider id was summarized.
+    const key = typeof msg.timestamp === "number" ? occKey(msg.toolCallId, msg.timestamp) : msg.toolCallId;
+    const lookupKey = indexer.isSummarized(key)
+      ? key
+      : indexer.hasLegacyBareRecord(msg.toolCallId)
+        ? msg.toolCallId
+        : undefined;
+    if (lookupKey === undefined) return msg;
+
+    const record = indexer.getRecord(lookupKey);
+    // Render-time re-check: a record summarized before protectedPaths
+    // covered it is repaired here — the raw toolResult still lives in the
+    // session JSONL, so skipping the stub restores it verbatim.
+    // Dedup aliases resolve to the original record, so an alias whose own
+    // path is protected but whose original isn't stays stubbed (edge case).
+    if (protection && record && isProtected(record.toolName, record.args, protection)) {
+      return msg;
+    }
+    if (inGrace.has(key)) {
+      return msg;
     }
-    return msg;
+    pruned = true;
+    const ref = indexer.getShortRefForToolCallId(lookupKey) ?? msg.toolCallId;
+    const text = record?.spillPath
+      ? [
+          `[Oversized output spilled to file — ${record.spillBytes ?? "?"} bytes.]`,
+          `Tool: ${record.toolName}`,
+          `Preview (head):`,
+          record.resultPreview ?? "",
+          `Full output — read this file (offset/limit supported): ${record.spillPath}`,
+          `Or use context_tree_query with ref \`${ref}\`.`,
+        ].join("\n")
+      : `[Summarized in pruner summary, ref \`${ref}\`. Use context_tree_query to retrieve full output.]`;
+    return {
+      role: "toolResult",
+      toolCallId: msg.toolCallId,
+      toolName: msg.toolName,
+      content: [{ type: "text", text }],
+      isError: false,
+      timestamp: msg.timestamp,
+    };
   });
 
   let current: any[] = pruned ? next : messages;
@@ -126,7 +151,8 @@ export function pruneMessages(
       // Prefer the cohesive LLM range summary (B) when present; fall back to the
       // per-batch concatenation for spans compressed before fusion / on failure.
       const chainSummaryText = (entry: typeof chainEntries[number]): string =>
-        entry.rangeSummaryText ?? indexer.getPerBatchSummaryTextForToolCallIds(entry.droppedToolCallIds);
+        entry.rangeSummaryText ??
+        indexer.getPerBatchSummaryTextForToolCallIds(entry.droppedOccurrenceKeys ?? entry.droppedToolCallIds);
       const blockSummaryLookup = (blockId: string): string | undefined => {
         const entry = indexer.findChainEntryByBlockId(blockId);
         if (!entry) return undefined;
@@ -138,6 +164,7 @@ export function pruneMessages(
         chainSummaryText,
         chainCompression.stripFinalAssistantThinking,
         blockSummaryLookup,
+        diagnostics,
       );
       if (compressed !== current) {
         current = compressed;
@@ -146,6 +173,27 @@ export function pruneMessages(
     }
   }
 
+  // Phase 4: orphan sweep — structural post-condition. Reference-preserving
+  // when clean, so a no-op render leaves the prompt-cache prefix untouched.
+  const swept = sweepOrphanToolResults(current);
+  if (swept.messages !== current) {
+    current = swept.messages;
+    pruned = true;
+    const sortedIds = [...swept.sweptIds].sort();
+    // Hash the id list into a short, stable dedup key instead of the raw
+    // sorted join: a growing orphan set would otherwise write ever-longer
+    // keys ("a", "a,b", "a,b,c", ...), and DiagnosticSink.seen retains every
+    // prefix forever - O(n^2) characters over a session's lifetime.
+    const dedupKey = createHash("sha1").update(sortedIds.join(",")).digest("hex").slice(0, 16);
+    const shown = sortedIds.slice(0, 5);
+    const more = sortedIds.length > shown.length ? ` ... +${sortedIds.length - shown.length} more` : "";
+    diagnostics?.report(
+      "orphan-sweep",
+      dedupKey,
+      `swept ${swept.sweptIds.length} orphan toolResult(s): ${shown.join(", ")}${more}`,
+    );
+  }
+
   return pruned
     ? { messages: current, pruned, beforeChars: sizeMessages(messages), afterChars: sizeMessages(current) }
     : { messages, pruned, beforeChars: 0, afterChars: 0 };

package/src/query-tool.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { registerQueryTool } from "./query-tool.js";
+import { ToolCallIndexer } from "./indexer.js";
+import type { CapturedBatch } from "./types.js";
+
+const capture = (idx: ToolCallIndexer, id: string, ts: number, text: string, turnIndex: number) => {
+  const batch: CapturedBatch = {
+    turnIndex,
+    timestamp: ts - 50,
+    assistantText: "",
+    toolCalls: [{ toolCallId: id, toolName: "bash", args: { cmd: "ls" }, resultText: text, isError: false, resultTimestamp: ts }],
+  };
+  idx.addBatch(batch, () => {});
+};
+
+const captureLegacy = (idx: ToolCallIndexer, id: string, timestamp: number, text: string, turnIndex: number) => {
+  const batch: CapturedBatch = {
+    turnIndex,
+    timestamp,
+    assistantText: "",
+    toolCalls: [{ toolCallId: id, toolName: "bash", args: { cmd: "ls" }, resultText: text, isError: false }],
+  };
+  idx.addBatch(batch, () => {});
+};
+
+// execute returns { content: [{ type: "text", text }], details } (src/query-tool.ts:73-76)
+const runTool = async (indexer: ToolCallIndexer, toolCallIds: string[]): Promise<string> => {
+  let registered: any;
+  registerQueryTool({ registerTool: (def: any) => (registered = def) } as any, indexer);
+  const result = await registered.execute("call-1", { toolCallIds }, undefined, undefined, undefined);
+  return result.content[0].text as string;
+};
+
+describe("context_tree_query occurrence handling", () => {
+  test("a bare id with two occurrences returns both blocks, chronologically", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "bash_23", 2150, "SECOND", 1);
+    capture(idx, "bash_23", 1150, "FIRST", 0);
+    const text = await runTool(idx, ["bash_23"]);
+    expect(text.indexOf("FIRST")).toBeGreaterThan(-1);
+    expect(text.indexOf("SECOND")).toBeGreaterThan(-1);
+    expect(text.indexOf("FIRST")).toBeLessThan(text.indexOf("SECOND"));
+    expect(text.match(/## toolRef:/g)).toHaveLength(2);
+  });
+
+  test("an occurrence key returns exactly one block", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "bash_23", 1150, "FIRST", 0);
+    capture(idx, "bash_23", 2150, "SECOND", 1);
+    const text = await runTool(idx, ["bash_23@2150"]);
+    expect(text.match(/## toolRef:/g)).toHaveLength(1);
+    expect(text).toContain("SECOND");
+  });
+
+  test("an unknown id still reports not-found once", async () => {
+    const idx = new ToolCallIndexer();
+    const text = await runTool(idx, ["nope"]);
+    expect(text).toContain("not found in index");
+  });
+
+  test("a single match still labels with the caller's input and has no @ suffix", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "bash_23", 1150, "FIRST", 0);
+    const text = await runTool(idx, ["bash_23"]);
+    expect(text.match(/## toolRef:/g)).toHaveLength(1);
+    expect(text).toContain("## toolRef: bash_23\n");
+    expect(text).not.toContain("bash_23@");
+  });
+
+  test("G5 conformance: a bare id whose collision was content-deduplicated still returns both occurrences via context_tree_query", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "bash_23", 1150, "SAME", 0);
+    // Same bare id, later occurrence, content-deduplicated against the original.
+    idx.registerDuplicate("bash_23@9150", "bash_23@1150", () => {});
+
+    const records = idx.getRecordsForId("bash_23");
+    expect(records).toHaveLength(2);
+
+    const text = await runTool(idx, ["bash_23"]);
+    expect(text.match(/## toolRef:/g)).toHaveLength(2);
+    expect(text).toContain("bash_23@1150");
+    expect(text).toContain("bash_23@9150");
+  });
+
+  test("G4/C1: colliding short refs each resolve to their OWN batch through the registered tool", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "bash_23", 1150, "FIRST", 0);
+    capture(idx, "bash_23", 2150, "SECOND", 1);
+    idx.registerSummaryRefs([
+      { shortId: "t1", toolCallId: "bash_23", resultTimestamp: 1150 },
+      { shortId: "t2", toolCallId: "bash_23", resultTimestamp: 2150 },
+    ]);
+
+    const firstText = await runTool(idx, ["t1"]);
+    expect(firstText.match(/## toolRef:/g)).toHaveLength(1);
+    expect(firstText).toContain("FIRST");
+    expect(firstText).not.toContain("SECOND");
+
+    const secondText = await runTool(idx, ["t2"]);
+    expect(secondText.match(/## toolRef:/g)).toHaveLength(1);
+    expect(secondText).toContain("SECOND");
+    expect(secondText).not.toContain("FIRST");
+  });
+
+  test("mixed legacy + new occurrence under the same bare id: legacy record labels with the bare id plus an explicit note, not a fake @legacy key", async () => {
+    const idx = new ToolCallIndexer();
+    captureLegacy(idx, "bash_23", 1000, "OLD", 0);
+    capture(idx, "bash_23", 2150, "NEW", 1);
+    const text = await runTool(idx, ["bash_23"]);
+    expect(text.match(/## toolRef:/g)).toHaveLength(2);
+    expect(text).toContain("## toolRef: bash_23\n");
+    expect(text).toContain("Occurrence: legacy (no resultTimestamp)");
+    expect(text).toContain("bash_23@2150");
+    expect(text).not.toContain("undefined");
+    expect(text).not.toContain("@legacy");
+  });
+});

package/src/query-tool.ts

@@ -5,19 +5,28 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ToolCallIndexer } from "./indexer.js";
 import { QUERY_TOOL_NAME } from "./types.js";
 
+// Legacy records (persisted before resultTimestamp existed) have no timestamp
+// to disambiguate. Do NOT mint an `id@legacy` string: it is occurrence-key-
+// SHAPED but not a real key — parseOccKey would treat "legacy" as part of a
+// literal id, so echoing it back into context_tree_query would fail lookup.
+// Label with the bare id and call out the ambiguity in the block body instead.
+function occurrenceLabel(id: string, resultTimestamp: number | undefined): string {
+  return resultTimestamp === undefined ? id : `${id}@${resultTimestamp}`;
+}
+
 export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): void {
   pi.registerTool({
     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.",
+      "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. A raw id that was reused returns every occurrence, each labelled id@timestamp.",
     promptSnippet: "Retrieve original pruned tool outputs by short ref",
     promptGuidelines: [
       "When you need the full output of a tool call that was summarized and pruned from context, use context_tree_query with the short refs listed in the relevant pruner-summary message.",
     ],
     parameters: Type.Object({
       toolCallIds: Type.Array(Type.String(), {
-        description: 'Required. One or more short refs (e.g. "t12") or raw tool call IDs from a pruner-summary message.',
+        description: 'Required. One or more short refs (e.g. "t12") or raw tool call IDs from a pruner-summary message. A reused raw id returns every occurrence, each labelled id@timestamp.',
       }),
     }),
 
@@ -26,46 +35,53 @@ export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): v
       const blocks: string[] = [];
 
       for (const id of params.toolCallIds) {
-        const record = indexer.getRecord(id);
+        const records = indexer.getRecordsForId(id);
 
-        if (!record) {
+        if (records.length === 0) {
           blocks.push(`## toolRef: ${id}\n(not found in index — may not have been summarized yet)`);
           continue;
         }
 
-        foundRecords[id] = record;
+        for (const record of records) {
+          // A reused provider id denotes several occurrences; return all of
+          // them rather than silently picking one. `tN` refs stay 1:1.
+          const label = records.length > 1 ? occurrenceLabel(id, record.resultTimestamp) : id;
 
-        const status = record.isError ? "ERROR" : "OK";
-        const header = [
-          `## toolRef: ${id}`,
-          `Tool: ${record.toolName}`,
-          `Args: ${JSON.stringify(record.args, null, 2)}`,
-          `Status: ${status}`,
-          `Turn: ${record.turnIndex}`,
-          "",
-        ].join("\n");
+          foundRecords[label] = record;
 
-        let raw = record.resultText;
-        if (record.spillPath) {
-          try {
-            raw = await readFile(record.spillPath, "utf-8");
-          } catch (err) {
-            console.error(`context_tree_query: failed to read spilled output at ${record.spillPath}:`, err);
-            raw = record.resultPreview ?? "(spilled output unavailable — sidecar file missing)";
+          const status = record.isError ? "ERROR" : "OK";
+          const header = [
+            `## toolRef: ${label}`,
+            ...(records.length > 1 && record.resultTimestamp === undefined ? ["Occurrence: legacy (no resultTimestamp)"] : []),
+            `Tool: ${record.toolName}`,
+            `Args: ${JSON.stringify(record.args, null, 2)}`,
+            `Status: ${status}`,
+            `Turn: ${record.turnIndex}`,
+            "",
+          ].join("\n");
+
+          let raw = record.resultText;
+          if (record.spillPath) {
+            try {
+              raw = await readFile(record.spillPath, "utf-8");
+            } catch (err) {
+              console.error(`context_tree_query: failed to read spilled output at ${record.spillPath}:`, err);
+              raw = record.resultPreview ?? "(spilled output unavailable — sidecar file missing)";
+            }
           }
-        }
 
-        const t = truncateHead(raw, {
-          maxLines: DEFAULT_MAX_LINES,
-          maxBytes: DEFAULT_MAX_BYTES,
-        });
+          const t = truncateHead(raw, {
+            maxLines: DEFAULT_MAX_LINES,
+            maxBytes: DEFAULT_MAX_BYTES,
+          });
 
-        let body = t.content;
-        if (t.truncated) {
-          body += `\n[Output truncated: ${t.outputLines}/${t.totalLines} lines shown]`;
-        }
+          let body = t.content;
+          if (t.truncated) {
+            body += `\n[Output truncated: ${t.outputLines}/${t.totalLines} lines shown]`;
+          }
 
-        blocks.push(`${header}\n${body}`);
+          blocks.push(`${header}\n${body}`);
+        }
       }
 
       const combined = blocks.join("\n\n---\n\n");

package/src/range-compression.integration.test.ts

@@ -5,6 +5,7 @@ import { compressEligible } from "./chain-compressor.js";
 import { pruneMessages } from "./pruner.js";
 import { detectChains } from "./chain-detector.js";
 import { isProtected } from "./protected.js";
+import { bareToolCallId } from "./occurrence-key.js";
 import type { ChainRange, ChainCompressionConfig } from "./types.js";
 
 // End-to-end of the in-memory B path (everything except the LLM call, which is
@@ -185,8 +186,12 @@ describe("range compression integration", () => {
     expect(chains[0].protectedToolCallIds).toEqual(["tc2"]);
 
     // Only unprotected tc1 has a per-batch summary; tc2 is protected, no short ref.
+    // Keyed by the occurrence key detectChains actually produced for tc1's result
+    // (id + resultTimestamp), not the bare toolCallId, so this can't silently drift.
+    const tc1OccKey = chains[0].middleOccurrenceKeys!.find((k) => bareToolCallId(k) === "tc1")!;
+    expect(tc1OccKey).toBeDefined();
     indexer.registerSummaryRefs([{ shortId: "t1", toolCallId: "tc1" }]);
-    indexer.registerSummaryBody(["tc1"], "read app.ts summary");
+    indexer.registerSummaryBody([tc1OccKey], "read app.ts summary");
 
     const { compressedEntries } = await compressEligible(chains, 0, {
       indexer,

package/src/recovery-grace.test.ts

@@ -3,6 +3,7 @@ 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 ctqAt = (id: string, timestamp: number) => ({ role: "toolResult", toolCallId: id, toolName: "context_tree_query", content: [{ type: "text", text: "x" }], timestamp });
 const bash = (id: string) => ({ role: "toolResult", toolCallId: id, toolName: "bash", content: [{ type: "text", text: "x" }] });
 
 describe("inGraceRecoveryToolCallIds", () => {
@@ -32,4 +33,16 @@ describe("inGraceRecoveryToolCallIds", () => {
     expect(set.has("t1")).toBe(false);
     expect(set.has("t2")).toBe(true);
   });
+  it("keys a timestamped recovery output by occurrence (id@timestamp), not the bare id", () => {
+    const msgs = [user(), ctqAt("reused", 100)];
+    const set = inGraceRecoveryToolCallIds(msgs, 3);
+    expect(set.has("reused@100")).toBe(true);
+    expect(set.has("reused")).toBe(false);
+  });
+  it("does not conflate two occurrences of the same reused bare id", () => {
+    const msgs = [user(), ctqAt("reused", 100), user(), user(), user(), user(), ctqAt("reused", 200)];
+    const set = inGraceRecoveryToolCallIds(msgs, 3);
+    expect(set.has("reused@100")).toBe(false);
+    expect(set.has("reused@200")).toBe(true);
+  });
 });

package/src/recovery-grace.ts

@@ -1,8 +1,16 @@
 import { QUERY_TOOL_NAME } from "./types.js";
+import { occKey } from "./occurrence-key.js";
 
 /**
- * Set of `context_tree_query` toolCallIds still inside the recovery grace
- * window, computed positionally from the message array (no stored metadata).
+ * Set of `context_tree_query` occurrence keys (or bare ids when the message
+ * carries no timestamp) still inside the recovery grace window, computed
+ * positionally from the message array (no stored metadata).
+ *
+ * Keyed by occurrence, not bare id: the pruner's fail-closed ladder in
+ * `pruneMessages` looks this set up with the SAME `occKey(id, timestamp)` it
+ * computed for the message under test, so a graced occurrence never leaks
+ * protection onto a different, later occurrence that happens to reuse the
+ * same provider id.
  *
  * 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
@@ -26,7 +34,8 @@ export function inGraceRecoveryToolCallIds(messages: any[], graceTurns: number):
       continue;
     }
     if (m?.role === "toolResult" && m.toolName === QUERY_TOOL_NAME && typeof m.toolCallId === "string") {
-      if (nowUTG - seen <= graceTurns) result.add(m.toolCallId);
+      const key = typeof m.timestamp === "number" ? occKey(m.toolCallId, m.timestamp) : m.toolCallId;
+      if (nowUTG - seen <= graceTurns) result.add(key);
     }
   }
   return result;

package/src/spill.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect } from "bun:test";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { sanitizeId, blobDirFor, blobPathFor, headPreview, spillOversizedBatch } from "./spill.js";
 import { ToolCallIndexer } from "./indexer.js";
+import { registerQueryTool } from "./query-tool.js";
+import { occKey } from "./occurrence-key.js";
+import { CUSTOM_TYPE_INDEX } from "./types.js";
 import type { CapturedBatch } from "./types.js";
 
 describe("sanitizeId", () => {
@@ -36,6 +39,94 @@ describe("headPreview", () => {
   });
 });
 
+describe("occurrence-keyed spill", () => {
+  it("blobPathFor distinguishes two occurrences of one id", () => {
+    const a = blobPathFor("/tmp/s", "sess", occKey("bash_23", 1150));
+    const b = blobPathFor("/tmp/s", "sess", occKey("bash_23", 3150));
+    expect(a).not.toBe(b);
+    expect(a.endsWith("bash_23_1150.txt")).toBe(true);
+  });
+
+  it("legacy bare-id sidecar path is unchanged", () => {
+    expect(blobPathFor("/tmp/s", "sess", "bash_23").endsWith("bash_23.txt")).toBe(true);
+  });
+
+  it("registerDuplicate is called with occurrence keys on both sides", async () => {
+    const calls: string[][] = [];
+    const indexer = {
+      lookupByContent: () => "bash_1@1000",
+      registerDuplicate: (a: string, b: string) => calls.push([a, b]),
+    } as any;
+    const batch = {
+      turnIndex: 0,
+      timestamp: 2000,
+      assistantText: "",
+      toolCalls: [
+        { toolCallId: "bash_2", toolName: "bash", args: {}, resultText: "x".repeat(100), isError: false, resultTimestamp: 2150 },
+      ],
+    };
+    await spillOversizedBatch({
+      batch: batch as any,
+      indexer,
+      config: { spillThreshold: 10, spillPreviewBytes: 10, dedupByContentHash: true },
+      sessionDir: "/tmp/s",
+      sessionId: "sess",
+      appendEntry: () => {},
+    });
+    expect(calls).toEqual([["bash_2@2150", "bash_1@1000"]]);
+  });
+});
+
+describe("G4/C4: legacy bare-id sidecar recovery", () => {
+  it("a pre-upgrade legacy record whose spillPath points at a bare-id-named sidecar still resolves through context_tree_query", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-legacy-"));
+    try {
+      // A pre-occurrence-key sidecar, written and named exactly the way a
+      // pre-upgrade session would have (bare id, no resultTimestamp suffix).
+      const sidecarPath = blobPathFor(dir, "sid", "bash_7");
+      await mkdir(blobDirFor(dir, "sid"), { recursive: true });
+      await writeFile(sidecarPath, "OLD SPILLED BODY".repeat(20));
+
+      const indexEntry = {
+        type: "custom",
+        customType: CUSTOM_TYPE_INDEX,
+        data: {
+          toolCalls: [
+            {
+              toolCallId: "bash_7",
+              toolName: "fetch",
+              args: { url: "https://x" },
+              resultText: "",
+              resultPreview: "OLD SPILLED",
+              spillPath: sidecarPath,
+              spillBytes: 340,
+              isError: false,
+              turnIndex: 0,
+              timestamp: 500,
+            },
+          ],
+        },
+      };
+      // No matching ToolResultMessage in the branch (a genuinely pre-upgrade,
+      // truncated session) - an index entry persisted without resultTimestamp
+      // stays bare-keyed (no migration), so its sidecar keeps its bare-id
+      // filename and still resolves via the persisted spillPath.
+      const indexer = new ToolCallIndexer();
+      indexer.reconstructFromSession({ sessionManager: { getBranch: () => [indexEntry] } } as any);
+      expect(indexer.hasLegacyBareRecord("bash_7")).toBe(true);
+
+      let registered: any;
+      registerQueryTool({ registerTool: (def: any) => (registered = def) } as any, indexer);
+      const result = await registered.execute("call-1", { toolCallIds: ["bash_7"] }, undefined, undefined, undefined);
+      const text = result.content[0].text as string;
+
+      expect(text).toContain("OLD SPILLED BODY");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("spillOversizedBatch", () => {
   const cfg = { spillThreshold: 10, spillPreviewBytes: 8, dedupByContentHash: true };
   const mkBatch = (toolCalls: any[]): CapturedBatch => ({ turnIndex: 0, timestamp: 1, assistantText: "", toolCalls });
@@ -85,6 +176,22 @@ describe("spillOversizedBatch", () => {
     }
   });
 
+  it("two occurrences of one toolCallId spill to distinct sidecar files", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const batch1 = mkBatch([{ toolCallId: "bash_23", toolName: "bash", args: {}, resultText: "FIRST".repeat(20), isError: false, resultTimestamp: 1150 }]);
+      const batch2 = mkBatch([{ toolCallId: "bash_23", toolName: "bash", args: {}, resultText: "SECOND".repeat(20), isError: false, resultTimestamp: 3150 }]);
+      await spillOversizedBatch({ batch: batch1, indexer, config: { ...cfg, dedupByContentHash: false }, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      await spillOversizedBatch({ batch: batch2, indexer, config: { ...cfg, dedupByContentHash: false }, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      const rec1 = indexer.getRecord("bash_23@1150")!;
+      const rec2 = indexer.getRecord("bash_23@3150")!;
+      expect(rec1.spillPath).not.toBe(rec2.spillPath);
+      expect(await readFile(rec1.spillPath!, "utf-8")).toBe("FIRST".repeat(20));
+      expect(await readFile(rec2.spillPath!, "utf-8")).toBe("SECOND".repeat(20));
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
   it("dedups an oversized duplicate to the original without a second file", async () => {
     const dir = await mkdtemp(join(tmpdir(), "spill-"));
     try {

package/src/spill.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import { hashToolResult } from "./content-hash.js";
+import { occKey } from "./occurrence-key.js";
 
 /** Replace anything outside [A-Za-z0-9_-] so the id can't escape the blob dir. */
 export function sanitizeId(toolCallId: string): string {
@@ -50,18 +51,19 @@ export async function spillOversizedBatch(args: {
   for (const tc of batch.toolCalls) {
     if (tc.resultText.length < config.spillThreshold) continue;
 
+    const key = occKey(tc.toolCallId, tc.resultTimestamp);
     const hash = hashToolResult(tc.toolName, tc.resultText);
 
     if (config.dedupByContentHash) {
       const original = indexer.lookupByContent(tc.toolName, tc.resultText);
-      if (original && original !== tc.toolCallId) {
-        indexer.registerDuplicate(tc.toolCallId, original, appendEntry);
+      if (original && original !== key) {
+        indexer.registerDuplicate(key, original, appendEntry);
         handled.add(tc.toolCallId);
         continue;
       }
     }
 
-    const path = blobPathFor(sessionDir, sessionId, tc.toolCallId);
+    const path = blobPathFor(sessionDir, sessionId, key);
     try {
       await mkdir(blobDirFor(sessionDir, sessionId), { recursive: true });
       await writeFile(path, tc.resultText, "utf-8");