pi-condense 2.9.2 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,11 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.10.0] - 2026-09-01
+
+- **Custom-message chain anchors ([#13](https://github.com/jjuraszek/pi-condense/issues/13)).** A non-pruner `role: "custom"` message (`customType` not prefixed `context-prune-`) can now open a chain, but only while the chain detector is idle - a non-pruner custom seen mid-chain stays passthrough, not a new anchor. `resolveRange` accepts these as start anchors fail-closed; persisted `custom_message` steers reach chain detection through a shared projection (`src/batch-capture.ts` `projectBranchMessages`); in `agent-message` batching, eligible customs also bound summary groups.
+- **Opt-in `frontierGapThresholdTokens` flush trigger.** New absolute-token flush trigger (default `null`, disabled), ORed with `autoBudgetThreshold`/`budgetTurnDelta` (precedence: budget, then delta, then frontier-gap) - fires at `turn_end` once the un-pruned tail past the prune frontier (`frontierGapTokens`) reaches the configured token count, independent of window size. Config-file-only, no `/pruner settings` row; self-throttling via frontier advance on processed flush outcomes (empty attempts advance nothing and rewrite nothing) - after a mid-flush summarizer failure the next gated turn may re-fire while consuming the remaining backlog, so the cadence bound is amortized per new tail growth rather than per-turn-exact. New `"frontier-gap"` value on `context-prune-flush-metrics` entries.
+
 ## [2.9.2] - 2026-08-31
 
 - **Context metrics removed from the footer status line.** The ` · think Nk · gap Nk · chain P%` suffix rendered on nearly every non-idle session and crowded the footer for no actionable signal. The metrics stay on `/pruner status` (`--- context ---`) and in the `context-prune-flush-metrics` session entries; the footer is back to prune state, reclaim, and `diag`. The snapshot cache that existed only to feed the widget is gone - both remaining consumers compute on demand.

package/PRUNING.md

@@ -838,6 +838,14 @@ Use case: a single enormous tool result can jump context usage by 20–30 percen
 
 `null` = off (default).
 
+### Frontier-gap flush trigger
+
+`frontierGapThresholdTokens: number | null` (default `null`) is a third flush trigger, ORed with `autoBudgetThreshold` and `budgetTurnDelta` at `turn_end` (precedence within that handler: budget, then delta, then frontier-gap - only the first that fires flushes that turn). Unlike the other two, which measure a *fraction* of the context window, this one is an absolute token count against `frontierGapTokens` (the un-pruned tail past the persisted prune frontier, same metric as `/pruner status` and `computeContextMetrics`). Rationale: a window-fraction trigger becomes unreachable on a large enough advertised window (the same problem `MAX_BUDGET_WINDOW` addresses for the level form) long before the un-pruned tail is actually a problem in tokens - this trigger is the absolute-token complement, independent of window size.
+
+It only evaluates at `turn_end`, same call site as the other two triggers, and is self-throttling: `frontierGapTokens` is measured against the persisted prune frontier, which advances on every processed flush outcome (summarized and skipped-* alike, including one this trigger itself causes) - an attempt that finds zero capturable batches does not advance it, and rewrites nothing, so it cannot churn the cache - so under normal operation it cannot fire again until the un-pruned tail regrows by another threshold-worth of tokens; on a mid-flush summarizer failure the frontier advances only to the persisted prefix, so the next gated turn may re-fire while consuming the remaining backlog, making the bound amortized (one extra prefix rewrite per threshold-worth of new tail growth) rather than per-turn-exact under failures. Recommended starting value `80000` - well above the ~5k-15k tokens a session typically accumulates per flush, so it only fires when flushes stop happening for an unusually long stretch (e.g. a long auto-continued run). Config-file-only - no `/pruner settings` row.
+
+`null` = off (default).
+
 ---
 
 ## Chain Compression
@@ -846,7 +854,7 @@ Chain compression is a second layer on top of the per-batch tool-result stub pru
 
 ### What a closed chain is
 
-A **closed chain** is a span of messages from one user message through any number of tool-using assistant turns and their results, ending in a final text-only assistant reply:
+A **closed chain** is a span of messages from one user message - or a non-pruner custom message (`role: "custom"` with a `customType` not prefixed `context-prune-`), the latter only accepted as a chain start while the chain detector is idle (mid-chain, a non-pruner custom is passthrough, not a new anchor) - through any number of tool-using assistant turns and their results, ending in a final text-only assistant reply:
 
 ```
 [user msg]                         ← chain start (kept raw)
@@ -861,7 +869,7 @@ A **closed chain** is a span of messages from one user message through any numbe
 
 | Part | After chain compression |
 |---|---|
-| Start user message | **Kept raw** |
+| Start user message (or idle-anchored custom message) | **Kept raw** |
 | Middle assistant turns (all) | **Dropped** — assistant thinking + signatures + toolCall argument blocks |
 | Middle tool results (all) | **Dropped** — already stub-replaced by the per-batch pruner; now fully removed |
 | Per-batch summary message(s) for this chain | **Suppressed** — replaced by the chain-level synthetic |

package/README.md

@@ -168,6 +168,7 @@ Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_A
 | `summarizerModel` | `"default"` | Pin a cheap model instead of reusing your active one - see the plan-by-plan table in [doc/configuration.md](doc/configuration.md#choosing-a-summarizer-model) |
 | `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
 | `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn`; the trigger point is capped at 300k tokens |
+| `frontierGapThresholdTokens` | `null` | Opt-in absolute-token flush trigger: fires at `turn_end` once the un-pruned tail past the prune frontier reaches N tokens, regardless of window size; recommended starting value `80000` |
 | `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md"]` | Tool names / path globs that are never pruned |
 | `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
 

package/index.ts

@@ -15,7 +15,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./src/config.js";
-import { captureBatch, captureUnindexedBatchesFromSession, groupBatchesByMode } from "./src/batch-capture.js";
+import { captureBatch, captureUnindexedBatchesFromSession, groupBatchesByMode, projectBranchMessages } from "./src/batch-capture.js";
 import { summarizeBatch, summarizeBatches, summarizeRange } from "./src/summarizer.js";
 import { FallbackController } from "./src/summarizer-fallback.js";
 import { ToolCallIndexer } from "./src/indexer.js";
@@ -47,7 +47,7 @@ import { BlockRefIssuer } from "./src/block-refs.js";
 import { compressEligible } from "./src/chain-compressor.js";
 import { detectChains, withClosingMessage } from "./src/chain-detector.js";
 import { inGraceRecoveryToolCallIds } from "./src/recovery-grace.js";
-import { shouldBudgetFlush, shouldDeltaFlush, usageFraction } from "./src/budget.js";
+import { shouldBudgetFlush, shouldDeltaFlush, shouldFrontierGapFlush, usageFraction } from "./src/budget.js";
 import { spillOversizedBatch } from "./src/spill.js";
 import { occKey } from "./src/occurrence-key.js";
 import { DiagnosticSink } from "./src/diagnostics.js";
@@ -98,18 +98,9 @@ export default function (pi: ExtensionAPI) {
       // Includes persisted custom_message entries (e.g. this extension's own
       // summary messages) alongside plain "message" entries: both are retained
       // LLM context, so both belong in the largest-chain-share denominator.
-      // Projected inline (rather than importing pi-coding-agent's
-      // createCustomMessage) because that helper isn't re-exported from the
-      // package's "." export map -- shape mirrors createCustomMessage's output
-      // (role "custom"), which never matches the user/assistant/toolResult
-      // roles computeContextMetrics keys off, so it only inflates totalChars.
-      const branch = ctx.sessionManager.getBranch()
-        .filter((e: any) => (e.type === "message" && e.message) || e.type === "custom_message")
-        .map((e: any) =>
-          e.type === "custom_message"
-            ? { role: "custom", customType: e.customType, content: e.content, display: e.display, details: e.details, timestamp: new Date(e.timestamp).getTime() }
-            : e.message,
-        );
+      // Shared projection (src/batch-capture.ts projectBranchMessages) so this
+      // matches the chain-detection feed sites exactly.
+      const branch = projectBranchMessages(ctx.sessionManager.getBranch());
       return computeContextMetrics(
         branch,
         frontier.get(),
@@ -597,13 +588,11 @@ export default function (pi: ExtensionAPI) {
               ? "skipped-deduped"
               : "skipped-trivial";
 
-      // Raw session branch, unwrapped once for the chain-compression block below.
+      // Projected session branch (message + custom_message entries) for the chain-compression block below.
       // Only materialized when chain compression is enabled.
       let branchMessages: any[] | undefined;
       if (currentConfig.value.chainCompression.enabled) {
-        branchMessages = ctx.sessionManager.getBranch()
-          .filter((e: any) => e.type === "message" && e.message)
-          .map((e: any) => e.message);
+        branchMessages = projectBranchMessages(ctx.sessionManager.getBranch());
       }
 
       const frontierSnapshot: PruneFrontier = {
@@ -940,24 +929,34 @@ export default function (pi: ExtensionAPI) {
     const usage = ctx.getContextUsage?.();
     const budgetHit = shouldBudgetFlush(usage, currentConfig.value.autoBudgetThreshold);
     const deltaHit = shouldDeltaFlush(usage, previousFraction, currentConfig.value.budgetTurnDelta);
+    // Frontier-gap auto-flush (opt-in): absolute un-pruned tail size, for huge
+    // windows where fractional thresholds never trip. Threshold null (default)
+    // skips the metrics snapshot entirely; a failed snapshot fails closed.
+    const gapThreshold = currentConfig.value.frontierGapThresholdTokens;
+    const gapHit = gapThreshold != null && shouldFrontierGapFlush(computeMetricsSnapshot(ctx), gapThreshold);
     // Update the per-turn baseline; leave it unchanged when tokens is null (e.g.
     // right after a compaction) so the next real reading compares to the last known.
     const f = usageFraction(usage);
     if (f != null) previousFraction = f;
 
     const n = pendingBatches.length;
-    if ((n > 0 || rearmedPending) && !isFlushing && (budgetHit || deltaHit)) {
+    if ((n > 0 || rearmedPending) && !isFlushing && (budgetHit || deltaHit || gapHit)) {
+      const reason = budgetHit ? "context budget reached" : deltaHit ? "context jumped this turn" : "un-pruned tail exceeded frontier gap threshold";
       // Always surface this flush (even when the routine status line is off): it's a
-      // significant, infrequent event — context crossed a threshold or jumped sharply
-      // this turn — and it self-throttles because pendingBatches is drained right after.
+      // significant, infrequent event — context crossed a threshold, jumped sharply
+      // this turn, or the un-pruned tail grew past the gap threshold — and it
+      // self-throttles because pendingBatches is drained right after.
       safeNotify(
         ctx,
         n > 0
-          ? `pruner: ${budgetHit ? "context budget reached" : "context jumped this turn"} — compacting ${n} pending turn${n === 1 ? "" : "s"}`
-          : `pruner: ${budgetHit ? "context budget reached" : "context jumped this turn"} — compacting work recovered after reload`,
+          ? `pruner: ${reason} — compacting ${n} pending turn${n === 1 ? "" : "s"}`
+          : `pruner: ${reason} — compacting work recovered after reload`,
         "info",
       );
-      await flushPending(ctx, { delivery: "session", trigger: n === 0 ? "rearmed" : budgetHit ? "budget" : "delta" });
+      await flushPending(ctx, {
+        delivery: "session",
+        trigger: n === 0 ? "rearmed" : budgetHit ? "budget" : deltaHit ? "delta" : "frontier-gap",
+      });
     }
   });
 
@@ -1023,10 +1022,7 @@ export default function (pi: ExtensionAPI) {
 
   // ── Register /pruner command + summary message renderer ────────────
   const compactChains = async (ctx: any) => {
-    const branch = ctx.sessionManager.getBranch();
-    const branchMessages = branch
-      .filter((e: any) => e.type === "message" && e.message)
-      .map((e: any) => e.message);
+    const branchMessages = projectBranchMessages(ctx.sessionManager.getBranch());
     const chains = detectChains(branchMessages, protectionPredicate);
     const inGrace = inGraceRecoveryToolCallIds(branchMessages, currentConfig.value.recoveryGraceTurns);
     const result = await compressEligible(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/batch-capture.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { captureBatch, captureUnindexedBatchesFromSession, serializeBatchForSummarizer } from "./batch-capture.js";
+import {
+  captureBatch,
+  captureUnindexedBatchesFromSession,
+  projectBranchMessages,
+  serializeBatchForSummarizer,
+} from "./batch-capture.js";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
 
 function toolCall(overrides: Partial<CapturedToolCall> = {}): CapturedToolCall {
@@ -123,3 +128,113 @@ describe("occurrence capture", () => {
     expect(captureUnindexedBatchesFromSession(branch, { isSummarized: () => false })).toEqual([]);
   });
 });
+
+describe("captureUnindexedBatchesFromSession entry timestamp fallback", () => {
+  test("uses the entry's timestamp when the inner message lacks one", () => {
+    const branch = [
+      {
+        type: "message",
+        timestamp: "2026-08-31T10:00:00.000Z",
+        message: { role: "assistant", content: [{ type: "toolCall", id: "bash_23", name: "bash", input: {} }] },
+      },
+      {
+        type: "message",
+        message: { role: "toolResult", toolCallId: "bash_23", toolName: "bash", content: [{ type: "text", text: "ok" }], isError: false, timestamp: 1150 },
+      },
+    ];
+
+    const batches = captureUnindexedBatchesFromSession(branch, { isSummarized: () => false });
+
+    expect(batches).toHaveLength(1);
+    expect(batches[0].timestamp).toBe(new Date("2026-08-31T10:00:00.000Z").getTime());
+  });
+});
+
+describe("projectBranchMessages", () => {
+  test("projects custom_message entries as role custom and drops unknown entry types", () => {
+    const branch = [
+      { type: "message", message: { role: "user", content: [{ type: "text", text: "hi" }] } },
+      {
+        type: "custom_message",
+        customType: "x",
+        content: "c",
+        display: true,
+        details: {},
+        timestamp: "2026-08-31T10:00:00.000Z",
+      },
+      { type: "other" },
+    ];
+
+    const msgs = projectBranchMessages(branch);
+
+    expect(msgs).toHaveLength(2);
+    expect(msgs[0]).toBe((branch[0] as any).message);
+    expect(msgs[1]).toEqual({
+      role: "custom",
+      customType: "x",
+      content: "c",
+      display: true,
+      details: {},
+      timestamp: new Date("2026-08-31T10:00:00.000Z").getTime(),
+    });
+  });
+});
+
+describe("custom-anchor group boundary", () => {
+  function buildBranch(customType: string) {
+    const entry = (message: any) => ({ type: "message", message });
+    return [
+      entry({ role: "user", content: [{ type: "text", text: "go" }], timestamp: 1000 }),
+      entry({
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc1", name: "bash", input: {} }],
+        timestamp: 1100,
+      }),
+      entry({
+        role: "toolResult",
+        toolCallId: "tc1",
+        toolName: "bash",
+        content: [{ type: "text", text: "ok1" }],
+        isError: false,
+        timestamp: 1150,
+      }),
+      {
+        type: "custom_message",
+        customType,
+        content: "c",
+        display: true,
+        details: {},
+        timestamp: "2026-08-31T10:00:00.000Z",
+      },
+      entry({
+        role: "assistant",
+        content: [{ type: "toolCall", id: "tc2", name: "bash", input: {} }],
+        timestamp: 2100,
+      }),
+      entry({
+        role: "toolResult",
+        toolCallId: "tc2",
+        toolName: "bash",
+        content: [{ type: "text", text: "ok2" }],
+        isError: false,
+        timestamp: 2150,
+      }),
+    ];
+  }
+
+  test("an eligible custom anchor (pi-gauntlet-transition-recovery) pins a new userTurnGroup", () => {
+    const branch = buildBranch("pi-gauntlet-transition-recovery");
+    const batches = captureUnindexedBatchesFromSession(branch, { isSummarized: () => false });
+
+    expect(batches).toHaveLength(2);
+    expect(batches[0].userTurnGroup).not.toBe(batches[1].userTurnGroup);
+  });
+
+  test("a pruner custom (context-prune-summary) passes through without a new group", () => {
+    const branch = buildBranch("context-prune-summary");
+    const batches = captureUnindexedBatchesFromSession(branch, { isSummarized: () => false });
+
+    expect(batches).toHaveLength(2);
+    expect(batches[0].userTurnGroup).toBe(batches[1].userTurnGroup);
+  });
+});

package/src/batch-capture.ts

@@ -1,5 +1,31 @@
 import type { CapturedBatch, CapturedToolCall, BatchingMode } from "./types.js";
 import { occKey, resultTimestampOf } from "./occurrence-key.js";
+import { isChainAnchorCustom } from "./chain-detector.js";
+
+/**
+ * Unwraps a SessionEntry[] branch into AgentMessage-like objects, including
+ * persisted custom_message entries (extension steers) projected as
+ * role "custom". Shared by computeMetricsSnapshot, flushPending chain detection,
+ * compactChains, and the rescan below so chain anchor timestamps are identical
+ * at every site. Projected inline (rather than importing pi-coding-agent's
+ * createCustomMessage) because that helper isn't re-exported from the
+ * package's "." export map.
+ */
+export function projectBranchMessages(branch: any[]): any[] {
+  return branch
+    .filter(isProjectableEntry)
+    .map((e: any) => (e.type === "custom_message" ? projectCustomMessageEntry(e) : e.message));
+}
+
+/** True for SessionEntry shapes that project into an AgentMessage-like object (see projectBranchMessages). */
+function isProjectableEntry(e: any): boolean {
+  return (e.type === "message" && e.message) || e.type === "custom_message";
+}
+
+/** Projects a single custom_message SessionEntry into its role "custom" message shape. */
+function projectCustomMessageEntry(e: any): any {
+  return { role: "custom", customType: e.customType, content: e.content, display: e.display, details: e.details, timestamp: new Date(e.timestamp).getTime() };
+}
 
 /** Joins the text blocks of a ToolResultMessage into a single string. */
 export function extractToolResultText(msg: any): string {
@@ -71,9 +97,13 @@ export function captureUnindexedBatchesFromSession(
   indexer: { isSummarized(id: string): boolean },
   exclude: (toolName: string, args: unknown) => boolean = () => false
 ): CapturedBatch[] {
-  // branch is SessionEntry[]. Each message entry has { type: "message", message: AgentMessage }.
-  // We must unwrap the SessionEntry wrapper before accessing role/toolCallId.
-  const entries = branch.filter((entry: any) => entry.type === "message");
+  // Keep the SessionEntry wrapper alongside each projected message so the
+  // entry's own timestamp remains available as the preferred source below
+  // (projection alone loses that wrapper for "message" entries).
+  const projected = branch
+    .filter(isProjectableEntry)
+    .map((e: any) => ({ entry: e, msg: e.type === "custom_message" ? projectCustomMessageEntry(e) : e.message }));
+  const msgs = projected.map((p) => p.msg);
 
   const batches: CapturedBatch[] = [];
   // turnCounter increments for EVERY assistant message (not just prunable ones).
@@ -83,19 +113,19 @@ export function captureUnindexedBatchesFromSession(
   // always matches Pi's own event.turnIndex numbering.
   let turnCounter = 0;
 
-  // userTurnGroup increments on every user message seen while walking the branch.
-  // All assistant tool-call batches between two consecutive user messages share the
-  // same userTurnGroup. This is used by groupBatchesByMode to merge turns within
-  // a single user → final-agent-message span when batchingMode === "agent-message".
+  // userTurnGroup increments on every user message or eligible custom anchor seen
+  // while walking the branch. All assistant tool-call batches between two
+  // consecutive boundaries share the same userTurnGroup. This is used by
+  // groupBatchesByMode to merge turns within a single user → final-agent-message
+  // span when batchingMode === "agent-message".
   let userTurnGroup = 0;
 
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    const msg = entry.message;
+  for (let i = 0; i < msgs.length; i++) {
+    const msg = msgs[i];
 
-    // Advance userTurnGroup on every user message so all subsequent assistant
-    // batches get a new group number.
-    if (msg.role === "user") {
+    // Advance userTurnGroup on every user message or eligible custom anchor so
+    // all subsequent assistant batches get a new group number.
+    if (msg.role === "user" || isChainAnchorCustom(msg)) {
       userTurnGroup++;
       continue;
     }
@@ -108,8 +138,8 @@ export function captureUnindexedBatchesFromSession(
     // Per-turn result map: only the results between this assistant message and
     // the next one. A branch-wide map is last-wins and mis-pairs repeated ids.
     const turnResults = new Map<string, any>();
-    for (let j = i + 1; j < entries.length; j++) {
-      const m = entries[j].message;
+    for (let j = i + 1; j < msgs.length; j++) {
+      const m = msgs[j];
       if (m.role === "assistant") break;
       if (m.role === "toolResult" && m.toolCallId && !turnResults.has(m.toolCallId)) {
         turnResults.set(m.toolCallId, m);
@@ -138,7 +168,8 @@ export function captureUnindexedBatchesFromSession(
       // an intermediate completed subset in the middle of a longer tool chain
       // without accidentally capturing later unresolved calls from the same
       // assistant message as "(no result)" placeholders.
-      const ts = entry.timestamp ? new Date(entry.timestamp).getTime() : (msg.timestamp ?? Date.now());
+      const entryTimestamp = projected[i].entry.timestamp;
+      const ts = entryTimestamp ? new Date(entryTimestamp).getTime() : (msg.timestamp ?? Date.now());
       const batch = captureBatch(msg, results, currentTurnIndex, ts);
       batches.push({
         ...batch,

package/src/budget.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "bun:test";
-import { shouldBudgetFlush, shouldDeltaFlush, usageFraction, MAX_BUDGET_WINDOW } from "./budget.js";
+import {
+  shouldBudgetFlush,
+  shouldDeltaFlush,
+  shouldFrontierGapFlush,
+  usageFraction,
+  MAX_BUDGET_WINDOW,
+} from "./budget.js";
 
 const usage = (tokens: number | null, contextWindow: number) =>
   ({ tokens, contextWindow, percent: null }) as any;
@@ -111,3 +117,17 @@ describe("shouldDeltaFlush", () => {
     expect(shouldDeltaFlush(usage(620_000, 1_000_000), prev, 0.1)).toBe(false);
   });
 });
+
+describe("shouldFrontierGapFlush", () => {
+  it("returns false when threshold is null", () => {
+    expect(shouldFrontierGapFlush({ frontierGapTokens: 999999 }, null)).toBe(false);
+  });
+  it("returns false when snapshot is undefined (fail closed)", () => {
+    // the spec's `snap === undefined` branch: metrics computation failed
+    expect(shouldFrontierGapFlush(undefined, 80000)).toBe(false);
+  });
+  it("fires at and above the threshold", () => {
+    expect(shouldFrontierGapFlush({ frontierGapTokens: 80000 }, 80000)).toBe(true);
+    expect(shouldFrontierGapFlush({ frontierGapTokens: 79999 }, 80000)).toBe(false);
+  });
+});

package/src/budget.ts

@@ -1,4 +1,5 @@
 import type { ContextUsage } from "@earendil-works/pi-coding-agent";
+import type { ContextMetricsSnapshot } from "./types.js";
 
 // Ceiling on what the budget triggers treat as the context window. Advertised
 // windows reach 1M, which makes any (0,1] fraction unreachable in a real session.
@@ -51,3 +52,12 @@ export function shouldDeltaFlush(
   if (current == null) return false;
   return current - previousFraction >= delta;
 }
+
+/** Fail-closed: an undefined snapshot (metrics computation failed) never fires. */
+export function shouldFrontierGapFlush(
+  snapshot: ContextMetricsSnapshot | undefined,
+  threshold: number | null,
+): boolean {
+  if (threshold == null) return false;
+  return snapshot != null && snapshot.frontierGapTokens >= threshold;
+}

package/src/chain-compressor.test.ts

@@ -710,6 +710,23 @@ describe("compressEligible - deterministic zero-LLM branch", () => {
     expect(registerChainCalls).toHaveLength(1);
   });
 
+  test("custom-anchored uncovered chain still compresses deterministically and backfills", async () => {
+    const messages = [
+      { role: "custom", customType: "pi-gauntlet-transition-recovery", timestamp: 1000 },
+      { role: "assistant", timestamp: 1001, content: [{ type: "toolCall", id: "c1", name: "bash", input: { cmd: "a" } }] },
+      { role: "toolResult", toolCallId: "c1", toolName: "bash", timestamp: 1050, isError: false, content: [{ type: "text", text: "out1" }] },
+      { role: "assistant", timestamp: 1002, content: [{ type: "toolCall", id: "c2", name: "read", input: { path: "x" } }] },
+      { role: "toolResult", toolCallId: "c2", toolName: "read", timestamp: 1150, isError: false, content: [{ type: "text", text: "out2" }] },
+      { role: "assistant", timestamp: 1200, content: [{ type: "text", text: "done" }] },
+    ];
+    const { deps, backfillCalls } = makeDeterministicDeps({ messages });
+    const result = await compressEligible([uncoveredChain()], 0, deps as any);
+    expect(result.compressedEntries).toHaveLength(1);
+    expect(result.compressedEntries[0].bodySource).toBe("deterministic");
+    expect(result.compressedEntries[0].startUserTimestamp).toBe(1000);
+    expect(backfillCalls).toHaveLength(1);
+  });
+
   test("covered path is untouched: backfill never invoked, entry matches identity pin", async () => {
     const { deps, backfillCalls } = makeDeterministicDeps();
     // Override to simulate coverage so the covered branch (not the deterministic one) runs.

package/src/chain-detector.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { detectChains, withClosingMessage } from "./chain-detector.js";
+import { detectChains, isChainAnchorCustom, withClosingMessage } from "./chain-detector.js";
+
+const custom = (customType: string, timestamp: number) => ({ role: "custom", customType, timestamp });
 
 // ── Minimal message factories ──────────────────────────────────────────────
 
@@ -349,3 +351,77 @@ describe("withClosingMessage", () => {
     expect(ranges[1].finalAssistantTimestamp).toBe(800);
   });
 });
+
+describe("chain-anchor custom messages", () => {
+  test("custom message while idle opens a chain", () => {
+    const messages = [
+      custom("pi-gauntlet-transition-recovery", 100),
+      { role: "assistant", timestamp: 200, content: [{ type: "toolCall", id: "tc1", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc1", toolName: "read", timestamp: 250, content: [] },
+      { role: "assistant", timestamp: 300, content: [{ type: "text", text: "done" }] },
+    ];
+    const ranges = detectChains(messages);
+    expect(ranges).toHaveLength(1);
+    expect(ranges[0].startUserTimestamp).toBe(100);
+    expect(ranges[0].finalAssistantTimestamp).toBe(300);
+    expect(ranges[0].middleToolCallIds).toEqual(["tc1"]);
+  });
+
+  test("custom message mid-chain is passthrough; enclosing chain closes as one range", () => {
+    const messages = [
+      { role: "user", timestamp: 100, content: [{ type: "text", text: "go" }] },
+      { role: "assistant", timestamp: 200, content: [{ type: "toolCall", id: "tc1", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc1", toolName: "read", timestamp: 250, content: [] },
+      custom("pi-gauntlet-transition-recovery", 260),
+      { role: "assistant", timestamp: 300, content: [{ type: "toolCall", id: "tc2", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc2", toolName: "read", timestamp: 350, content: [] },
+      { role: "assistant", timestamp: 400, content: [{ type: "text", text: "done" }] },
+    ];
+    const ranges = detectChains(messages);
+    expect(ranges).toHaveLength(1);
+    expect(ranges[0].startUserTimestamp).toBe(100);
+    expect(ranges[0].middleToolCallIds).toEqual(["tc1", "tc2"]);
+  });
+
+  test("context-prune-summary custom is passthrough in both states", () => {
+    // idle state: a summary custom must not anchor anything
+    const idleMessages = [
+      custom("context-prune-summary", 50),
+      { role: "assistant", timestamp: 200, content: [{ type: "toolCall", id: "tc1", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc1", toolName: "read", timestamp: 250, content: [] },
+      { role: "assistant", timestamp: 300, content: [{ type: "text", text: "done" }] },
+    ];
+    expect(detectChains(idleMessages)).toHaveLength(0);
+    // in-chain: a summary custom between turns leaves the chain unbroken
+    const midMessages = [
+      { role: "user", timestamp: 100, content: [{ type: "text", text: "go" }] },
+      { role: "assistant", timestamp: 200, content: [{ type: "toolCall", id: "tc1", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc1", toolName: "read", timestamp: 250, content: [] },
+      custom("context-prune-summary", 260),
+      { role: "assistant", timestamp: 300, content: [{ type: "toolCall", id: "tc2", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc2", toolName: "read", timestamp: 350, content: [] },
+      { role: "assistant", timestamp: 400, content: [{ type: "text", text: "done" }] },
+    ];
+    const ranges = detectChains(midMessages);
+    expect(ranges).toHaveLength(1);
+    expect(ranges[0].middleToolCallIds).toEqual(["tc1", "tc2"]);
+  });
+
+  test("future context-prune-* customType is excluded", () => {
+    const messages = [
+      custom("context-prune-whatever", 100),
+      { role: "assistant", timestamp: 200, content: [{ type: "toolCall", id: "tc1", name: "read", input: {} }] },
+      { role: "toolResult", toolCallId: "tc1", toolName: "read", timestamp: 250, content: [] },
+      { role: "assistant", timestamp: 300, content: [{ type: "text", text: "done" }] },
+    ];
+    expect(detectChains(messages)).toHaveLength(0);
+  });
+
+  test("isChainAnchorCustom predicate", () => {
+    expect(isChainAnchorCustom({ role: "custom", customType: "pi-gauntlet-transition-recovery" })).toBe(true);
+    expect(isChainAnchorCustom({ role: "custom", customType: "context-prune-summary" })).toBe(false);
+    expect(isChainAnchorCustom({ role: "custom" })).toBe(true); // missing customType -> not pruner-namespaced
+    expect(isChainAnchorCustom({ role: "user" })).toBe(false);
+    expect(isChainAnchorCustom(undefined)).toBe(false);
+  });
+});

package/src/chain-detector.ts

@@ -23,12 +23,22 @@ function collectToolCalls(msg: any): { id: string; name: string; args: unknown }
     .map((b: any) => ({ id: b.id as string, name: b.name as string, args: b.input ?? b.arguments }));
 }
 
+/**
+ * A non-pruner custom message: eligible to open a chain (while the detector is
+ * idle) and to act as a resolveRange start anchor. The `context-prune-`
+ * namespace prefix excludes every pruner-emitted custom message — today
+ * context-prune-summary; by construction any future pruner customType.
+ */
+export function isChainAnchorCustom(msg: any): boolean {
+  return msg?.role === "custom" && !String(msg.customType ?? "").startsWith("context-prune-");
+}
+
 type State = "idle" | "inChain";
 
 /**
  * Walks an AgentMessage array and emits ChainRange records for each detectable chain.
  *
- * A chain is: [user message] → [assistant+toolResult turns...] → [text-only assistant].
+ * A chain is: [user message or eligible custom message] → [assistant+toolResult turns...] → [text-only assistant].
  * Synthetic chain messages (injected by chain-range-prune) are treated as passthroughs —
  * not chain starts. This is defensive; the detector normally runs pre-compression.
  *
@@ -49,6 +59,12 @@ export function detectChains(
   let middleKeys = new Set<string>();
   let protectedIds = new Set<string>();
 
+  const resetChain = () => {
+    middleIds = new Set();
+    middleKeys = new Set();
+    protectedIds = new Set();
+  };
+
   const emitInterrupted = () => {
     if (state === "inChain" && chainStart) {
       ranges.push({
@@ -66,9 +82,14 @@ export function detectChains(
       if (isSyntheticChainMessage(msg)) continue; // passthrough — not a chain start
       emitInterrupted();
       chainStart = { timestamp: msg.timestamp };
-      middleIds = new Set();
-      middleKeys = new Set();
-      protectedIds = new Set();
+      resetChain();
+      state = "inChain";
+      continue;
+    }
+
+    if (state === "idle" && isChainAnchorCustom(msg)) {
+      chainStart = { timestamp: msg.timestamp };
+      resetChain();
       state = "inChain";
       continue;
     }
@@ -103,9 +124,7 @@ export function detectChains(
         finalAssistantTimestamp: msg.timestamp,
       });
       chainStart = null;
-      middleIds = new Set();
-      middleKeys = new Set();
-      protectedIds = new Set();
+      resetChain();
       state = "idle";
     }
   }