pi-condense 2.5.0 → 2.7.0

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");

package/src/summarizer-wiring.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, mock } from "bun:test";
+import * as actualCompat from "@earendil-works/pi-ai/compat";
 
 // Stub pi-ai's `stream` so runSummarization can be exercised without a network
 // call. `streamImpl` is swapped per test to simulate primary/fallback outcomes.
@@ -6,6 +7,7 @@ let streamImpl: (model: any, input?: any, opts?: any) => any = () => {
   throw new Error("streamImpl not set");
 };
 mock.module("@earendil-works/pi-ai/compat", () => ({
+  ...actualCompat,
   stream: (...args: any[]) => streamImpl(...args),
 }));
 

package/src/summary-refs.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { substituteInlineRefs, formatSummaryToolCallRefs, type SummaryToolCallRef } from "./summary-refs.js";
+import {
+  substituteInlineRefs,
+  formatSummaryToolCallRefs,
+  buildShortToolCallRefs,
+  normalizeSummaryToolCallRefs,
+  type SummaryToolCallRef,
+} from "./summary-refs.js";
 
 describe("substituteInlineRefs", () => {
   const refs: SummaryToolCallRef[] = [
@@ -120,3 +126,47 @@ describe("substituteInlineRefs", () => {
     }
   });
 });
+
+describe("occurrence-aware summary refs", () => {
+  test("buildShortToolCallRefs carries resultTimestamp through", () => {
+    const { refs, nextIndex } = buildShortToolCallRefs(
+      [
+        { toolCallId: "bash_23", resultTimestamp: 2150 },
+        { toolCallId: "bash_23", resultTimestamp: 3150 },
+      ],
+      5,
+    );
+    expect(refs).toEqual([
+      { shortId: "t5", toolCallId: "bash_23", resultTimestamp: 2150 },
+      { shortId: "t6", toolCallId: "bash_23", resultTimestamp: 3150 },
+    ]);
+    expect(nextIndex).toBe(7);
+  });
+
+  test("buildShortToolCallRefs omits resultTimestamp when absent", () => {
+    const { refs } = buildShortToolCallRefs([{ toolCallId: "bash_1" }], 1);
+    expect(refs).toEqual([{ shortId: "t1", toolCallId: "bash_1" }]);
+    expect("resultTimestamp" in refs[0]).toBe(false);
+  });
+
+  test("normalizeSummaryToolCallRefs preserves a numeric resultTimestamp", () => {
+    const refs = normalizeSummaryToolCallRefs({
+      toolCallRefs: [{ shortId: "t1", toolCallId: "bash_1", resultTimestamp: 1150 }],
+    });
+    expect(refs).toEqual([{ shortId: "t1", toolCallId: "bash_1", resultTimestamp: 1150 }]);
+  });
+
+  test("normalizeSummaryToolCallRefs drops a non-numeric resultTimestamp", () => {
+    const refs = normalizeSummaryToolCallRefs({
+      toolCallRefs: [{ shortId: "t1", toolCallId: "bash_1", resultTimestamp: "nope" }],
+    });
+    expect(refs).toEqual([{ shortId: "t1", toolCallId: "bash_1" }]);
+    expect("resultTimestamp" in refs[0]).toBe(false);
+  });
+
+  test("legacy toolCallIds-only details still normalize", () => {
+    expect(normalizeSummaryToolCallRefs({ toolCallIds: ["bash_1"] })).toEqual([
+      { shortId: "bash_1", toolCallId: "bash_1" },
+    ]);
+  });
+});

package/src/summary-refs.ts

@@ -1,8 +1,11 @@
 import type { CapturedBatch } from "./types.js";
+import { resultTimestampOf } from "./occurrence-key.js";
 
 export interface SummaryToolCallRef {
   shortId: string;
   toolCallId: string;
+  /** ToolResultMessage timestamp; combines with toolCallId into the occurrence key. */
+  resultTimestamp?: number;
 }
 
 export interface SummaryMessageDetailsLike {
@@ -13,12 +16,13 @@ export interface SummaryMessageDetailsLike {
 const SHORT_ID_PREFIX = "t";
 
 export function buildShortToolCallRefs(
-  toolCallIds: string[],
+  calls: { toolCallId: string; resultTimestamp?: number }[],
   startIndex: number,
 ): { refs: SummaryToolCallRef[]; nextIndex: number } {
-  const refs = toolCallIds.map((toolCallId, offset) => ({
+  const refs = calls.map((call, offset) => ({
     shortId: `${SHORT_ID_PREFIX}${startIndex + offset}`,
-    toolCallId,
+    toolCallId: call.toolCallId,
+    ...(call.resultTimestamp !== undefined ? { resultTimestamp: call.resultTimestamp } : {}),
   }));
   return { refs, nextIndex: startIndex + refs.length };
 }
@@ -33,7 +37,14 @@ export function normalizeSummaryToolCallRefs(details: unknown): SummaryToolCallR
         (ref): ref is SummaryToolCallRef =>
           !!ref && typeof ref.shortId === "string" && typeof ref.toolCallId === "string",
       )
-      .map((ref) => ({ shortId: ref.shortId, toolCallId: ref.toolCallId }));
+      .map((ref) => {
+        const resultTimestamp = resultTimestampOf((ref as any).resultTimestamp);
+        return {
+          shortId: ref.shortId,
+          toolCallId: ref.toolCallId,
+          ...(resultTimestamp !== undefined ? { resultTimestamp } : {}),
+        };
+      });
   }
 
   if (Array.isArray(raw.toolCallIds)) {

package/src/test-support.ts

@@ -0,0 +1,54 @@
+import { expect } from "bun:test";
+import { sweepOrphanToolResults } from "./orphan-sweep.js";
+import { pruneMessages } from "./pruner.js";
+import { DiagnosticSink } from "./diagnostics.js";
+
+/** Shared by chain-range-prune.test.ts and id-collision.integration.test.ts. */
+export function expectNoOrphanToolResults(messages: any[]): void {
+  let open = new Set<string>();
+  for (const m of messages) {
+    if (m.role === "assistant") {
+      open = new Set((m.content ?? []).filter((c: any) => c.type === "toolCall").map((c: any) => c.id));
+    } else if (m.role === "toolResult") {
+      expect(open.has(m.toolCallId)).toBe(true);
+      open.delete(m.toolCallId);
+    }
+  }
+}
+
+/**
+ * G4/C3: proof that the orphan sweep (src/pruner.ts Phase 4) is a net, not a
+ * crutch. Runs the real `sweepOrphanToolResults` (the exact function backing
+ * Phase 4's diagnostic) over an already-pruned message array and fails if it
+ * finds anything to sweep. Equivalent to asserting the Phase 4 diagnostic
+ * never fires for this output: `sweepOrphanToolResults` returns the input
+ * array reference and an empty `sweptIds` when nothing is orphaned, which is
+ * precisely the condition under which `pruneMessages` skips the
+ * `diagnostics?.report("orphan-sweep", ...)` call.
+ */
+export function expectZeroOrphanSweep(messages: any[]): void {
+  const { messages: swept, sweptIds } = sweepOrphanToolResults(messages);
+  expect(sweptIds).toEqual([]);
+  expect(swept).toBe(messages);
+}
+
+/**
+ * G4/C3: wraps a `pruneMessages` call with a counting `DiagnosticSink` and
+ * fails if the `orphan-sweep` diagnostic fires. For fixtures that already go
+ * through the full pruner pipeline (pruner.test.ts), this is the more direct
+ * proof than `expectZeroOrphanSweep` since it exercises the actual Phase 4
+ * call site, not just the underlying pure function.
+ */
+export function pruneWithZeroSweepAssertion(
+  messages: any[],
+  indexer: any,
+  chainCompression?: any,
+  errorPurge?: any,
+  protection?: any,
+  recoveryGraceTurns: number = 0,
+): ReturnType<typeof pruneMessages> {
+  const sink = new DiagnosticSink(() => {});
+  const result = pruneMessages(messages, indexer, chainCompression, errorPurge, protection, recoveryGraceTurns, sink);
+  expect(sink.counts()["orphan-sweep"]).toBe(0);
+  return result;
+}

package/src/tree-browser.ts

@@ -7,6 +7,7 @@ import type { ToolCallRecord } from "./types.js";
 import { CUSTOM_TYPE_SUMMARY } from "./types.js";
 import { normalizeSummaryToolCallRefs } from "./summary-refs.js";
 import type { ToolCallIndexer } from "./indexer.js";
+import { occKey } from "./occurrence-key.js";
 
 // ── Tree node types ─────────────────────────────────────────────────────────
 
@@ -119,7 +120,7 @@ export function buildPruneTree(
 
     const children: TreeNode[] = [];
     for (const ref of toolCallRefs) {
-      const record = indexer.getRecord(ref.toolCallId);
+      const record = indexer.getRecord(occKey(ref.toolCallId, ref.resultTimestamp));
       if (!record) continue;
       children.push(toolCallNode(record, 1));
     }

package/src/types.ts

@@ -10,7 +10,7 @@
  *   event.toolResults = ToolResultMessage[] (one per tool call in this turn)
  *
  * STATE MODEL (Ph1 step 3):
- *   - Runtime state: Map<toolCallId, ToolCallRecord> rebuilt on session_start
+ *   - Runtime state: Map<occurrenceKey, ToolCallRecord> rebuilt on session_start
  *   - Session metadata: pi.appendEntry("context-prune-index", IndexEntryData)
  *     stored once per summarized batch; NOT in LLM context
  *   - User config: .pi/settings.json → "contextPrune" key (JSON merge safe,
@@ -78,6 +78,29 @@ export const CUSTOM_TYPE_DEDUP_ALIAS = "context-prune-dedup-alias";
  */
 export const CUSTOM_TYPE_CHAIN = "context-prune-chain";
 
+/**
+ * Written via pi.appendEntry(CUSTOM_TYPE_DIAGNOSTIC, data) when a prune-time
+ * invariant degrades. NOT in LLM context: zero tokens, zero cache-prefix
+ * change. Deduplication is a runtime concern of the diagnostic sink
+ * (src/diagnostics.ts), which takes a caller-supplied dedup key and never
+ * persists it - the persisted entry carries only `kind` plus a freeform `detail`.
+ */
+export const CUSTOM_TYPE_DIAGNOSTIC = "context-prune-diagnostic";
+
+/**
+ * Per-flush-attempt observability record. Written once per non-concurrent
+ * flushPending invocation, regardless of outcome (including "empty" and
+ * "error"). Append-only log: never in LLM context, never reconstructed.
+ */
+export const CUSTOM_TYPE_FLUSH_METRICS = "context-prune-flush-metrics";
+
+export type DiagnosticKind = "unresolved-range" | "range-id-mismatch" | "orphan-sweep";
+
+export interface DiagnosticEntryData {
+  kind: DiagnosticKind;
+  detail: string;
+}
+
 /** 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";
@@ -397,13 +420,22 @@ export interface ChainRange {
   /** Timestamp of the user message that opens the chain. */
   startUserTimestamp: number;
   /**
-   * All toolCallIds in the chain's middle (deduplicated).
-   * Collected from both AssistantMessage ToolCall blocks AND matching
-   * ToolResultMessages. Used to: (1) drop ToolResultMessages, (2) identify
-   * and drop middle AssistantMessages, (3) suppress per-batch summary
-   * CustomMessages whose toolCallRefs overlap.
+   * All toolCallIds in the chain's middle (deduplicated). Collected from both
+   * AssistantMessage ToolCall blocks AND matching ToolResultMessages.
+   * Identifies the chain's middle tool calls for detection, recovery-grace
+   * filtering and diagnostics. NOT used for the load-bearing indexer lookups
+   * (summary bodies, tool refs) - those maps are occurrence-keyed, so use
+   * the sibling `middleOccurrenceKeys` instead. Drops themselves are decided
+   * positionally by `resolveRange` in chain-range-prune.ts, not by these ids.
    */
   middleToolCallIds: string[];
+  /**
+   * Occurrence keys (`id@resultTimestamp`) for the chain's middle tool
+   * results, collected from the ToolResultMessages themselves. Used for
+   * indexer summary-body / toolRef lookups, which are occurrence-keyed.
+   * Optional so hand-built ChainRange fixtures need not set it.
+   */
+  middleOccurrenceKeys?: string[];
   /**
    * Subset of middleToolCallIds whose tool name ∈ protectedTools (detection-time
    * fact). The detector always emits it ([] when no protected tool ran); optional
@@ -425,12 +457,19 @@ export interface ChainCompressionEntry {
   /** Timestamp of the user message that opens the chain. Keep raw; synthetic inserted after. */
   startUserTimestamp: number;
   /**
-   * ToolCallIds of all dropped middle messages.
-   * Used at context-transform time to: drop matching ToolResultMessages,
-   * drop AssistantMessages that contain any of these as ToolCall blocks,
-   * and suppress per-batch summary messages whose toolCallRefs overlap.
+   * All toolCallIds in the chain's middle. **Diagnostic only** since the
+   * positional-range change: drops are decided by index range (see
+   * resolveRange in chain-range-prune.ts). Retained as a cross-check - a
+   * mismatch against the ids actually dropped emits `range-id-mismatch`.
    */
   droppedToolCallIds: string[];
+  /**
+   * Occurrence keys for the same calls as droppedToolCallIds. Load-bearing at
+   * render time: summaryBodies are occurrence-keyed, so the synthetic chain
+   * body is looked up by these. Absent on pre-upgrade entries, which fall back
+   * to droppedToolCallIds against their own bare-keyed summaryBodies.
+   */
+  droppedOccurrenceKeys?: string[];
   /**
    * Subset of droppedToolCallIds whose tool was user-protected. Membership is decided
    * per call by tool name (every call whose name ∈ protectedTools), not a per-id allowlist.
@@ -523,6 +562,13 @@ export interface CapturedToolCall {
   args: Record<string, unknown>;
   resultText: string;
   isError: boolean;
+  /**
+   * Timestamp of the ToolResultMessage this call was paired with. The
+   * occurrence discriminant (see src/occurrence-key.ts): provider ids repeat
+   * within a session, this does not. Optional so pre-upgrade persisted
+   * entries stay readable; absent => the record is legacy bare-id keyed.
+   */
+  resultTimestamp?: number;
   spillPath?: string;
   spillBytes?: number;
   resultPreview?: string;
@@ -565,6 +611,8 @@ export interface ToolCallRecord {
   isError: boolean;
   turnIndex: number;
   timestamp: number;
+  /** See CapturedToolCall.resultTimestamp. */
+  resultTimestamp?: number;
   /** Absolute path to the sidecar blob holding the full body (set only when the result was spilled). */
   spillPath?: string;
   /** Full byte length of the spilled body. */
@@ -603,6 +651,9 @@ export interface IndexEntryData {
 export interface DedupAliasEntryData {
   newToolCallId: string;
   originalToolCallId: string;
+  /** Occurrence timestamps for each side; absent on pre-upgrade entries. */
+  newResultTimestamp?: number;
+  originalResultTimestamp?: number;
   hash?: string;
 }
 
@@ -613,6 +664,8 @@ export interface DedupAliasEntryData {
 export interface SummaryToolCallRef {
   shortId: string;
   toolCallId: string;
+  /** ToolResultMessage timestamp; with toolCallId this forms the occurrence key. */
+  resultTimestamp?: number;
 }
 
 /**
@@ -626,6 +679,30 @@ export interface SummaryMessageDetails {
   timestamp: number;
 }
 
+/** Snapshot of what the pruner cannot (yet) reclaim. All token values are Math.round(JSON-chars / 4). */
+export interface ContextMetricsSnapshot {
+  /** Est. tokens of thinking blocks retained in the trailing open segment. */
+  openCycleThinkingTokens: number;
+  /** max(largest closed chain, open segment) chars / total branch chars, 0-100. */
+  largestChainSharePct: number;
+  /** Est. tokens of summarization-eligible unsummarized toolResults after the frontier. */
+  frontierGapTokens: number;
+}
+
+export type FlushTrigger = "budget" | "delta" | "message-end" | "manual" | "rearmed";
+
+/** Payload of CUSTOM_TYPE_FLUSH_METRICS. */
+export interface FlushMetricsEntry {
+  ts: number;
+  trigger: FlushTrigger;
+  /** Batches after rescan+trim, before processing. */
+  capturedBatches: number;
+  processedBatches: number;
+  outcome: "summarized" | "skipped-oversized" | "skipped-deduped" | "skipped-trivial" | "empty" | "error";
+  /** Computed at flush ENTRY (pre-flush pressure). */
+  metrics: ContextMetricsSnapshot;
+}
+
 // ── Summarizer stats ────────────────────────────────────────────────────────
 
 /**
@@ -748,6 +825,8 @@ export interface FlushOptions {
    * the frontier. All pending batches are restored so the next flush can retry.
    */
   signal?: AbortSignal;
+  /** Which trigger initiated this flush. Defaults to "manual" when absent. */
+  trigger?: FlushTrigger;
   /**
    * The final text-only assistant message that triggered an agent-message flush.
    * pi emits `message_end` to extensions before persisting it to the session, so it