pi-condense 2.9.2 → 2.10.1

package/src/reload-rearm.integration.test.ts

@@ -49,6 +49,18 @@ function okStream() {
   };
 }
 
+// Classified "transient" by runOnce (src/summarizer.ts) — with
+// summarizerModel: "default" (no distinct fallback model) this yields a
+// null SummarizeResult after exactly one stream() call, no retries.
+function errStream(message: string) {
+  return {
+    async *[Symbol.asyncIterator]() {},
+    async result() {
+      return { stopReason: "error", errorMessage: message, content: [], usage: USAGE };
+    },
+  };
+}
+
 let streamImpl: (model: any, input?: any, opts?: any) => any = () => {
   summarizerCalls++;
   return okStream();
@@ -117,6 +129,26 @@ function closedChainBranch(count: number): any[] {
   return msgs;
 }
 
+// Builds one independent pending batch: user -> assistant toolCall -> toolResult,
+// with no closing text-only assistant (chain stays open, matching defaultBranch's
+// shape). Used by the frontier-gap tests below to grow/shrink the branch's
+// un-pruned tail across turns by direct array mutation (bootExtension returns
+// the live `branch` array reference, so pushing onto it after boot is visible
+// to every later getBranch() call).
+function pendingBatchEntries(toolCallId: string, text: string, timestamp: number): any[] {
+  return [
+    { type: "message", message: { role: "user", content: [{ type: "text", text: `do ${toolCallId}` }], timestamp } },
+    {
+      type: "message",
+      message: { role: "assistant", content: [{ type: "toolCall", id: toolCallId, name: "read", arguments: {} }], timestamp: timestamp + 500 },
+    },
+    {
+      type: "message",
+      message: { role: "toolResult", toolCallId, toolName: "read", content: [{ type: "text", text }], timestamp: timestamp + 1000 },
+    },
+  ];
+}
+
 // Boots a fresh index.ts extension instance against an isolated agent dir +
 // session, mirroring the fixtures shared across the three scenarios below.
 //
@@ -137,35 +169,45 @@ function closedChainBranch(count: number): any[] {
 function bootExtension(
   options: {
     chainCompressionEnabled?: boolean;
+    rollingWindow?: number;
     separatePiAppended?: boolean;
     piAppendEntry?: (push: (type: string, data?: unknown) => void) => (type: string, data?: unknown) => void;
     sessionAppendCustomEntry?: (push: (type: string, data?: unknown) => void) => (type: string, data?: unknown) => string;
     branch?: any[];
     protectedTools?: string[];
+    autoBudgetThreshold?: number | null;
+    budgetTurnDelta?: number | null;
+    frontierGapThresholdTokens?: number | null;
   } = {},
 ) {
   const agentDir = mkdtempSync(join(tmpdir(), "pi-condense-rearm-"));
   process.env.PI_CODING_AGENT_DIR = agentDir;
+  const contextPruneSettings: any = {
+    enabled: true,
+    pruneOn: "agent-message",
+    batchingMode: "agent-message",
+    autoBudgetThreshold: options.autoBudgetThreshold === undefined ? 0.5 : options.autoBudgetThreshold,
+    summarizerModel: "default",
+    minBatchChars: 1,
+    showPruneStatusLine: true,
+    protectedTools: options.protectedTools ?? [],
+    chainCompression: {
+      enabled: options.chainCompressionEnabled ?? false,
+      rollingWindow: options.rollingWindow ?? 3,
+      stripFinalAssistantThinking: true,
+      fuseRangeSummary: true,
+    },
+  };
+  // Omitted unless the test explicitly passes them, so the "default-null
+  // inert" scenario can assert behavior with no key present at all (not an
+  // explicit null), matching config.ts's own default.
+  if (options.budgetTurnDelta !== undefined) contextPruneSettings.budgetTurnDelta = options.budgetTurnDelta;
+  if (options.frontierGapThresholdTokens !== undefined) {
+    contextPruneSettings.frontierGapThresholdTokens = options.frontierGapThresholdTokens;
+  }
   writeFileSync(
     join(agentDir, "settings.json"),
-    JSON.stringify({
-      contextPrune: {
-        enabled: true,
-        pruneOn: "agent-message",
-        batchingMode: "agent-message",
-        autoBudgetThreshold: 0.5,
-        summarizerModel: "default",
-        minBatchChars: 1,
-        showPruneStatusLine: true,
-        protectedTools: options.protectedTools ?? [],
-        chainCompression: {
-          enabled: options.chainCompressionEnabled ?? false,
-          rollingWindow: 3,
-          stripFinalAssistantThinking: true,
-          fuseRangeSummary: true,
-        },
-      },
-    }),
+    JSON.stringify({ contextPrune: contextPruneSettings }),
   );
 
   const sessionDir = mkdtempSync(join(tmpdir(), "pi-condense-rearm-session-"));
@@ -577,4 +619,300 @@ describe("reload rearm (issue #6)", () => {
     expect(text).toContain(`chain share:  ${expectedPct}%`);
     expect(expectedPct).toBeLessThan(inflatedPct);
   });
+
+  it("feeds persisted custom_message steers into chain detection via the shared projection (#13)", async () => {
+    // A production-feed regression: chain detection/compaction/metrics must
+    // all see custom_message entries projected as role "custom" (src/batch-
+    // capture.ts projectBranchMessages), not just plain "message" entries.
+    // A non-pruner customType (isChainAnchorCustom) opens a chain while idle
+    // and anchors resolveRange the same way a user message does; a pruner-
+    // namespaced customType (context-prune-*) must NOT anchor one.
+    const t0 = new Date().toISOString();
+    let t = new Date(t0).getTime();
+
+    const customAnchoredChain: any[] = [
+      {
+        type: "custom_message",
+        customType: "pi-gauntlet-transition-recovery",
+        content: [{ type: "text", text: "continue" }],
+        timestamp: t0,
+      },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-custom", name: "read", arguments: {} }] },
+      },
+      {
+        type: "message",
+        message: {
+          role: "toolResult",
+          toolCallId: "tc-custom",
+          toolName: "read",
+          content: [{ type: "text", text: "x".repeat(400) }],
+          timestamp: (t += 1000),
+        },
+      },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "text", text: "done custom" }], timestamp: (t += 1000) },
+      },
+    ];
+
+    // A second closed, user-anchored chain so the custom-anchored chain above
+    // is not the newest/frontier chain (rollingWindow: 0 makes every closed
+    // chain not already compressed eligible regardless, but this mirrors a
+    // realistic multi-turn session and rules out any "only chain" special case).
+    const trailingChain: any[] = [
+      { type: "message", message: { role: "user", content: [{ type: "text", text: "do more" }], timestamp: (t += 1000) } },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-trail", name: "read", arguments: {} }] },
+      },
+      {
+        type: "message",
+        message: {
+          role: "toolResult",
+          toolCallId: "tc-trail",
+          toolName: "read",
+          content: [{ type: "text", text: "y".repeat(400) }],
+          timestamp: (t += 1000),
+        },
+      },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "text", text: "done trailing" }], timestamp: (t += 1000) },
+      },
+    ];
+
+    const branch = [...customAnchoredChain, ...trailingChain];
+
+    const { handlers, ctx, appended } = await boot({ chainCompressionEnabled: true, rollingWindow: 0, branch });
+
+    await handlers.get("session_start")!({}, ctx);
+    await handlers.get("turn_end")!(
+      { toolResults: [], message: { role: "assistant", content: [{ type: "text", text: "hi" }] }, turnIndex: 2 },
+      ctx,
+    );
+    await handlers.get("message_end")!(
+      { message: { role: "assistant", content: [{ type: "text", text: "done" }] } },
+      ctx,
+    );
+
+    const chainEntries = appended.filter((e) => e.type === "context-prune-chain");
+    const anchoredAtCustom = chainEntries.find(
+      (e) => (e.data as any).startUserTimestamp === new Date(t0).getTime(),
+    );
+    expect(anchoredAtCustom).toBeDefined();
+  });
+
+  it("does not let a pruner-namespaced custom_message (context-prune-*) anchor a chain (#13)", async () => {
+    const t0 = new Date().toISOString();
+    let t = new Date(t0).getTime();
+
+    const pruneSummaryEntry: any[] = [
+      {
+        type: "custom_message",
+        customType: "context-prune-summary",
+        content: [{ type: "text", text: "prior summary" }],
+        timestamp: t0,
+      },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-p", name: "read", arguments: {} }] },
+      },
+      {
+        type: "message",
+        message: {
+          role: "toolResult",
+          toolCallId: "tc-p",
+          toolName: "read",
+          content: [{ type: "text", text: "x".repeat(400) }],
+          timestamp: (t += 1000),
+        },
+      },
+      {
+        type: "message",
+        message: { role: "assistant", content: [{ type: "text", text: "done p" }], timestamp: (t += 1000) },
+      },
+    ];
+
+    const { handlers, ctx, appended } = await boot({ chainCompressionEnabled: true, rollingWindow: 0, branch: pruneSummaryEntry });
+
+    await handlers.get("session_start")!({}, ctx);
+    await handlers.get("turn_end")!(
+      { toolResults: [], message: { role: "assistant", content: [{ type: "text", text: "hi" }] }, turnIndex: 2 },
+      ctx,
+    );
+    await handlers.get("message_end")!(
+      { message: { role: "assistant", content: [{ type: "text", text: "done" }] } },
+      ctx,
+    );
+
+    const chainEntries = appended.filter((e) => e.type === "context-prune-chain");
+    const anchoredAtSummary = chainEntries.find(
+      (e) => (e.data as any).startUserTimestamp === new Date(t0).getTime(),
+    );
+    expect(anchoredAtSummary).toBeUndefined();
+  });
+
+  it("frontier-gap trigger fires at turn_end when the un-pruned tail exceeds the threshold (#13)", async () => {
+    const { handlers, ctx, notifications, appended } = await boot({
+      autoBudgetThreshold: null,
+      frontierGapThresholdTokens: 10,
+    });
+
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+
+    await handlers.get("session_start")!({}, ctx);
+
+    // defaultBranch() already carries an unsummarized ~400-char toolResult
+    // (~100 tokens), well past the threshold of 10.
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc1", toolName: "read", content: [{ type: "text", text: "x".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 2,
+      },
+      ctx,
+    );
+
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(flushMetricsEntries.length).toBe(1);
+    const fm = flushMetricsEntries[0].data as any;
+    expect(fm.trigger).toBe("frontier-gap");
+    expect(fm.metrics.frontierGapTokens).toBeGreaterThanOrEqual(10);
+
+    expect(notifications.some((n) => n.includes("un-pruned tail exceeded frontier gap threshold"))).toBe(true);
+  });
+
+  it("budget trigger takes precedence over frontier-gap when both conditions are met at turn_end (#13)", async () => {
+    const { handlers, ctx, appended } = await boot({
+      autoBudgetThreshold: 0.5,
+      frontierGapThresholdTokens: 10,
+    });
+
+    await handlers.get("session_start")!({}, ctx);
+
+    // Usage fraction 0.9 crosses the 0.5 budget threshold; defaultBranch()'s
+    // un-pruned tail also crosses the 10-token gap threshold. Budget must win.
+    ctx.getContextUsage = () => ({ tokens: 900000, contextWindow: 1000000 });
+
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc1", toolName: "read", content: [{ type: "text", text: "x".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 2,
+      },
+      ctx,
+    );
+
+    const flushMetricsEntries = appended.filter((e) => e.type === "context-prune-flush-metrics");
+    expect(flushMetricsEntries.length).toBe(1);
+    expect((flushMetricsEntries[0].data as any).trigger).toBe("budget");
+  });
+
+  it("frontier-gap trigger stays inert when frontierGapThresholdTokens is unset (default null), even with a huge un-pruned tail (#13)", async () => {
+    const { handlers, ctx, appended } = await boot({
+      autoBudgetThreshold: null,
+    });
+
+    await handlers.get("session_start")!({}, ctx);
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc1", toolName: "read", content: [{ type: "text", text: "x".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 2,
+      },
+      ctx,
+    );
+
+    expect(appended.some((e) => e.type === "context-prune-flush-metrics")).toBe(false);
+  });
+
+  it("frontier-gap cadence: a partial-failure flush persists the surviving prefix and advances the frontier; the next gap-triggered flush advances it further (#13)", async () => {
+    const { handlers, ctx, appended } = await boot({
+      autoBudgetThreshold: null,
+      frontierGapThresholdTokens: 10,
+      branch: [],
+    });
+
+    await handlers.get("session_start")!({}, ctx);
+    ctx.getContextUsage = () => ({ tokens: 10, contextWindow: 1000000 });
+
+    // Turn 1: branch still empty -> frontierGapTokens is 0 -> no flush, even
+    // though this turn's own toolResults are pushed into pendingBatches.
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-warmup", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc-warmup", toolName: "read", content: [{ type: "text", text: "w".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 1,
+      },
+      ctx,
+    );
+    expect(appended.some((e) => e.type === "context-prune-flush-metrics")).toBe(false);
+
+    // Grow the branch with two independent unindexed batches (tc-a, tc-b) —
+    // capturePendingBatches rescans the branch, not the in-memory queue, so
+    // this is what actually makes the upcoming flush see two batches.
+    let t = Date.now();
+    ctx.sessionManager.getBranch().push(...pendingBatchEntries("tc-a", "a".repeat(400), (t += 1000)));
+    ctx.sessionManager.getBranch().push(...pendingBatchEntries("tc-b", "b".repeat(400), (t += 1000)));
+
+    let callCount = 0;
+    streamImpl = () => {
+      callCount++;
+      summarizerCalls++;
+      if (callCount === 2) return errStream("simulated summarizer failure on second batch");
+      return okStream();
+    };
+
+    // Turn 2: gap now over threshold (tc-a + tc-b unsummarized) -> flush fires,
+    // processes tc-a successfully, tc-b's summarization call fails.
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-a", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc-a", toolName: "read", content: [{ type: "text", text: "a".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 2,
+      },
+      ctx,
+    );
+
+    let frontierEntries = appended.filter((e) => e.type === "context-prune-frontier");
+    expect(frontierEntries.length).toBe(1);
+    const firstFrontier = frontierEntries[0].data as any;
+    expect(firstFrontier.lastAttemptedToolCallId).toBe("tc-a");
+
+    // Grow the branch again (tc-b is still unsummarized/pending after the
+    // restore; add tc-c as this turn's new work) — gap stays over threshold.
+    ctx.sessionManager.getBranch().push(...pendingBatchEntries("tc-c", "c".repeat(400), (t += 1000)));
+
+    // Turn 3: gap still over threshold -> flush fires again, this time both
+    // tc-b (restored) and tc-c succeed (streamImpl only fails on call #2).
+    await handlers.get("turn_end")!(
+      {
+        message: { role: "assistant", content: [{ type: "toolCall", id: "tc-c", name: "read", arguments: {} }] },
+        toolResults: [
+          { role: "toolResult", toolCallId: "tc-c", toolName: "read", content: [{ type: "text", text: "c".repeat(400) }], timestamp: Date.now() },
+        ],
+        turnIndex: 3,
+      },
+      ctx,
+    );
+
+    frontierEntries = appended.filter((e) => e.type === "context-prune-frontier");
+    expect(frontierEntries.length).toBe(2);
+    const secondFrontier = frontierEntries[1].data as any;
+    expect(secondFrontier.lastAttemptedTimestamp).toBeGreaterThan(firstFrontier.lastAttemptedTimestamp);
+  });
 });

package/src/spill.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "bun:test";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { sanitizeId, blobDirFor, blobPathFor, headPreview, spillOversizedBatch } from "./spill.js";
 import { ToolCallIndexer } from "./indexer.js";
 import { registerQueryTool } from "./query-tool.js";
@@ -24,6 +24,41 @@ describe("blobDirFor / blobPathFor", () => {
   });
 });
 
+describe("blobPathFor byte cap (gh-14)", () => {
+  const nameBytes = (p: string) => Buffer.byteLength(basename(p), "utf8");
+
+  it("251-byte sanitized base keeps today's formula (AC5 boundary, just-under)", () => {
+    const id = "a".repeat(251);
+    const p = blobPathFor("/s", "sid", id);
+    expect(p).toBe(join("/s", "sid-blobs", `${id}.txt`));
+    expect(nameBytes(p)).toBe(255);
+  });
+
+  it("252-byte sanitized base is capped to exactly 255 bytes (AC5 boundary, just-over)", () => {
+    const p = blobPathFor("/s", "sid", "a".repeat(252));
+    expect(nameBytes(p)).toBe(255);
+    expect(basename(p)).toMatch(/^a{234}\.[0-9a-f]{16}\.txt$/);
+  });
+
+  it("is deterministic: same long key -> identical path", () => {
+    const key = "x".repeat(500);
+    expect(blobPathFor("/s", "sid", key)).toBe(blobPathFor("/s", "sid", key));
+  });
+
+  it("two long ids sharing the first 300 chars map to distinct filenames (AC3)", () => {
+    const a = "t".repeat(300) + "A".repeat(200);
+    const b = "t".repeat(300) + "B".repeat(200);
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+
+  it("hashes the unsanitized key: long ids that sanitize identically stay distinct", () => {
+    const a = "p".repeat(300) + "/x";
+    const b = "p".repeat(300) + "\\x";
+    expect(sanitizeId(a)).toBe(sanitizeId(b));
+    expect(blobPathFor("/s", "sid", a)).not.toBe(blobPathFor("/s", "sid", b));
+  });
+});
+
 describe("headPreview", () => {
   it("returns the whole string when under the byte cap", () => {
     expect(headPreview("hello", 1024)).toBe("hello");
@@ -206,4 +241,39 @@ describe("spillOversizedBatch", () => {
       await expect(readFile(blobPathFor(dir, "sid", "tc2"), "utf-8")).rejects.toBeDefined();
     } finally { await rm(dir, { recursive: true, force: true }); }
   });
+
+  it("spills a 500-char tool-call id: file created, capped basename, record mutated (AC1)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494); // 500 chars
+      const body = "LONG-ID BODY ".repeat(10);
+      const batch = mkBatch([{ toolCallId: longId, toolName: "fetch", args: {}, resultText: body, isError: false, resultTimestamp: 1150 }]);
+      const spilled = await spillOversizedBatch({ batch, indexer, config: cfg, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      expect(spilled.has(longId)).toBe(true);
+      const rec = indexer.getRecord(occKey(longId, 1150))!;
+      expect(rec.resultText).toBe("");
+      expect(rec.resultPreview!.length).toBeGreaterThan(0);
+      expect(Buffer.byteLength(basename(rec.spillPath!), "utf8")).toBeLessThanOrEqual(255);
+      expect(await readFile(rec.spillPath!, "utf-8")).toBe(body);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  it("same 500-char id at two occurrences spills to two distinct files (AC2)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const longId = "toolu_" + "k".repeat(494);
+      const noDedup = { ...cfg, dedupByContentHash: false };
+      const b1 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "FIRST".repeat(20), isError: false, resultTimestamp: 1150 }]);
+      const b2 = mkBatch([{ toolCallId: longId, toolName: "bash", args: {}, resultText: "SECOND".repeat(20), isError: false, resultTimestamp: 3150 }]);
+      await spillOversizedBatch({ batch: b1, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      await spillOversizedBatch({ batch: b2, indexer, config: noDedup, sessionDir: dir, sessionId: "sid", appendEntry: () => {} });
+      const rec1 = indexer.getRecord(occKey(longId, 1150))!;
+      const rec2 = indexer.getRecord(occKey(longId, 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 }); }
+  });
 });

package/src/spill.ts

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import { hashToolResult } from "./content-hash.js";
@@ -15,7 +16,18 @@ export function blobDirFor(sessionDir: string, sessionId: string): string {
 }
 
 export function blobPathFor(sessionDir: string, sessionId: string, toolCallId: string): string {
-  return join(blobDirFor(sessionDir, sessionId), `${sanitizeId(toolCallId)}.txt`);
+  const base = sanitizeId(toolCallId);
+  // 255-byte basename cap (gh-14). Uncapped budget: 255 - ".txt" = 251.
+  // Capped: 234-byte prefix + "." + 16-hex sha1 + ".txt" = 255 exactly.
+  // sanitizeId output is ASCII, so slice counts bytes. The "." separator is
+  // unreachable by sanitizeId, keeping capped names disjoint from short-key
+  // names. The hash covers the UNsanitized key so ids that sanitize
+  // identically stay distinct.
+  const name =
+    Buffer.byteLength(base, "utf8") <= 251
+      ? `${base}.txt`
+      : `${base.slice(0, 234)}.${createHash("sha1").update(toolCallId).digest("hex").slice(0, 16)}.txt`;
+  return join(blobDirFor(sessionDir, sessionId), name);
 }
 
 /** Head of `text` capped at `maxBytes` (UTF-8 safe), preferring a line boundary. */

package/src/types.ts

@@ -414,6 +414,12 @@ export interface ContextPruneConfig {
    * null (default) = disabled. Out-of-range (<= 0 or > 1) normalizes to null.
    */
   budgetTurnDelta: number | null;
+  /**
+   * Opt-in flush trigger: when the un-pruned tail past the frontier
+   * (frontierGapTokens) reaches this many tokens, flush at turn_end.
+   * null (default) disables. Config-file-only — no settings overlay row.
+   */
+  frontierGapThresholdTokens: number | null;
 }
 
 /**
@@ -426,7 +432,10 @@ export interface ContextPruneConfig {
  * into a ChainCompressionEntry by adding blockId, toolRefs, and compressedAt.
  */
 export interface ChainRange {
-  /** Timestamp of the user message that opens the chain. */
+  /**
+   * Start anchor timestamp — a user message or an eligible (non-pruner)
+   * custom message. Field name kept for persisted-entry compatibility.
+   */
   startUserTimestamp: number;
   /**
    * All toolCallIds in the chain's middle (deduplicated). Collected from both
@@ -463,7 +472,11 @@ export interface ChainRange {
 export interface ChainCompressionEntry {
   /** Stable block ID, monotonic per session: "b1", "b2", ... */
   blockId: string;
-  /** Timestamp of the user message that opens the chain. Keep raw; synthetic inserted after. */
+  /**
+   * Start anchor timestamp — a user message or an eligible (non-pruner)
+   * custom message. Field name kept for persisted-entry compatibility.
+   * Keep raw; synthetic inserted after.
+   */
   startUserTimestamp: number;
   /**
    * All toolCallIds in the chain's middle. **Diagnostic only** since the
@@ -566,6 +579,7 @@ export const DEFAULT_CONFIG: ContextPruneConfig = {
   spillThreshold: 65536,
   spillPreviewBytes: 2048,
   budgetTurnDelta: null,
+  frontierGapThresholdTokens: null,
 };
 
 // ── Captured batch ─────────────────────────────────────────────────────────
@@ -708,7 +722,7 @@ export interface ContextMetricsSnapshot {
   frontierGapTokens: number;
 }
 
-export type FlushTrigger = "budget" | "delta" | "message-end" | "manual" | "rearmed";
+export type FlushTrigger = "budget" | "delta" | "frontier-gap" | "message-end" | "manual" | "rearmed";
 
 /** Payload of CUSTOM_TYPE_FLUSH_METRICS. */
 export interface FlushMetricsEntry {