pi-condense 2.9.1 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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.
+
 ## [2.9.1] - 2026-08-18
 
 - **Orphan sweep: any foreign message is now a barrier ([#11](https://github.com/jjuraszek/pi-condense/issues/11)).** `sweepOrphanToolResults` only reset its open-call set on `assistant` messages, while pi-ai flushes synthetic tool results at both `assistant` and `user` boundaries (`convertToLlm` maps `custom`/`branchSummary`/`compactionSummary`/`bashExecution` to `user`). A foreign message spliced between a toolCall and its toolResult (observed: a pi-cohort control notice) let the real result through alongside pi-ai's synthetic - a duplicate `tool_use_id` the provider rejects permanently (Anthropic 400, branch bricked). Now any message that is neither `assistant` nor `toolResult` clears the open set, so the interleaved result is swept and pi-ai's repairable synthetic stands alone; already-broken branches un-brick on the next render. Deliberate conservative over-sweep (unknown roles, `excludeFromContext` bashExecution) - no role allowlist. Test helper `expectNoOrphanToolResults` carries the identical rule. Spec: `doc/specs/2026-08-18-gh-11-orphan-sweep-barrier.md` (partially supersedes the 2026-08-12 spec's section C).

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 |
@@ -995,7 +1003,7 @@ Phase 1 (per-batch summarization) is unaffected by chain closure and remains the
 
 Neither knob makes a chain close; they just keep Phase 1 flushing on schedule so raw toolResults do not pile up unsummarized for the whole run.
 
-**Observability metrics** (`src/context-metrics.ts`, `computeContextMetrics`) exist precisely to make this shape of session visible instead of silently reporting `calls: 1` the way the triggering incident did. All three are chars/4 token estimates (`Math.round`, same convention as the reclaim footer) and surface on `/pruner status` (a `--- context ---` block), the footer status line (a compact suffix, shown only when the frontier gap is non-zero), and a `context-prune-flush-metrics` session entry written once per flush attempt regardless of outcome:
+**Observability metrics** (`src/context-metrics.ts`, `computeContextMetrics`) exist precisely to make this shape of session visible instead of silently reporting `calls: 1` the way the triggering incident did. All three are chars/4 token estimates (`Math.round`, same convention as the reclaim footer) and surface on `/pruner status` (a `--- context ---` block) and a `context-prune-flush-metrics` session entry written once per flush attempt regardless of outcome:
 
 | Metric | Definition |
 |---|---|

package/README.md

@@ -69,6 +69,8 @@ pi install npm:pi-condense
 | `agent-message` (default) | When the agent sends a final text-only reply | ~1 cache rewrite per task batch |
 | `on-demand` | Only when you run `/pruner now` | None until you ask |
 
+With the default `agent-message` trigger (and `autoBudgetThreshold`/`budgetTurnDelta` unset), a non-interactive (`pi -p`) session sees its first flush only at the final reply - set `autoBudgetThreshold` (e.g. `0.8`) so flushes also fire mid-run. This is a property of single-prompt sessions, not a defect in the default.
+
 Before any summarizer call, a pre-flush pipeline can drop or redirect a batch at zero LLM cost: protected tools/paths are never touched, content-hash duplicates are aliased to the original, batches too small to be worth summarizing are skipped outright, and oversized single results are spilled straight to a sidecar file. Closed tool-call chains older than a rolling window are additionally range-compressed. Full pipeline and each safeguard: [PRUNING.md § Pre-flush Pipeline & Safeguards](PRUNING.md#pre-flush-pipeline--safeguards), [§ Chain Compression](PRUNING.md#chain-compression).
 
 ### External cost channel
@@ -84,7 +86,7 @@ Every summarizer cost update is emitted on the shared `pi.events` channel `cost:
 | Batch vs chain | A batch is one flush's worth of tool calls; a chain is a longer closed sequence eligible for range compression |
 | Prune frontier | The last attempted prune boundary - advances even on a skip, so nothing is reconsidered twice |
 | Diagnostics (`diag u/m/o/b`) | A self-hiding status-line segment surfacing prune-time degradations: `u` = unresolved chain range, `m` = detection/render id mismatch (informational, does not change what's dropped), `o` = orphan tool-result sweep, `b` = a zero-coverage chain with nothing left to backfill (genuine span mismatch, see below). Each letter's count is omitted when zero; the whole segment disappears when all four are zero. Backing session entries are `context-prune-diagnostic` - see below |
-| Context metrics (`think`/`gap`/`chain`) | Open-cycle thinking tokens, largest-chain share, frontier gap - what the pruner cannot (yet) reclaim, notably in single-chain sessions. See below and [PRUNING.md § Single-chain sessions](PRUNING.md#single-chain-sessions) |
+| Context metrics (`thinking`/`chain share`/`frontier gap`) | Open-cycle thinking tokens, largest-chain share, frontier gap - what the pruner cannot (yet) reclaim, notably in single-chain sessions. Shown on `/pruner status`, never on the footer. See below and [PRUNING.md § Single-chain sessions](PRUNING.md#single-chain-sessions) |
 | Prompt-cache interaction | Why batching (not per-turn pruning) is the default - see [PRUNING.md](PRUNING.md#how-prefix-caching-works) |
 | `cost:external` | The shared cost-reporting channel pi-condense emits on (see above) |
 
@@ -100,10 +102,9 @@ The status-line `diag u<N>/m<N>/o<N>/b<N>` segment above is backed by `context-p
 
 ### Context metrics (`context-prune-flush-metrics`)
 
-Three metrics the pruner cannot yet reclaim - open-cycle thinking tokens, largest-chain share (%), frontier gap tokens - surface in three places, all backed by `computeContextMetrics` (`src/context-metrics.ts`):
+Three metrics the pruner cannot yet reclaim - open-cycle thinking tokens, largest-chain share (%), frontier gap tokens - surface in two places, both backed by `computeContextMetrics` (`src/context-metrics.ts`). They are deliberately kept off the footer status line, which stays limited to prune state, reclaim, and diagnostics:
 
 - `/pruner status` prints a `--- context ---` block: `thinking:`, `chain share:`, `frontier gap:`, plus a `rearmed: yes` line while a reload-rearm probe (below) has recoverable work armed.
-- The footer status line appends `· think Nk · gap Nk · chain P%` - only when the frontier gap is non-zero, so an idle session's footer is unchanged.
 - Each flush attempt (every outcome, including empty/error) writes one `context-prune-flush-metrics` session entry with the pre-flush snapshot - session-log-only, never added to what the model sees, and not reconstructed on reload.
 
 These are most informative for long single-chain sessions where Phase 3 (chain compression) never gets a closed chain to act on - see [PRUNING.md § Single-chain sessions](PRUNING.md#single-chain-sessions) for the limitation and config guidance, and [PRUNING.md § Reload rearm](PRUNING.md#reload-rearm) for how a reload with recoverable pending work re-arms the automatic flush trigger.
@@ -167,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 |
 
@@ -180,6 +182,10 @@ pi-condense is the context-economy layer: it has no code dependency on the other
 
 No committed roadmap beyond what's already tracked in [CHANGELOG.md](CHANGELOG.md); proposals and in-progress work show up there and in repo issues first.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) - issues follow a Context / Problem / Idea / Acceptance Criteria template; PRs run the [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) workflow (one-liners exempt from ceremony, never from keeping docs truthful).
+
 ## Support
 
 If this saves you tokens, [buy me a coffee](https://buymeacoffee.com/jjurasszek).

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";
@@ -93,28 +93,15 @@ export default function (pi: ExtensionAPI) {
   // Cleared on every non-concurrent flushPending invocation.
   let rearmedPending = false;
 
-  // Latest ContextMetricsSnapshot, recomputed at reload probes, batch capture,
-  // and flush entry. Cached (rather than recomputed on every widget refresh)
-  // because computeContextMetrics walks the full branch.
-  let metricsCache: ContextMetricsSnapshot | undefined;
   const computeMetricsSnapshot = (ctx: any): ContextMetricsSnapshot | undefined => {
     try {
       // 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,
-        );
-      metricsCache = computeContextMetrics(
+      // 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(),
         (k: string) => indexer.isSummarized(k),
@@ -122,8 +109,8 @@ export default function (pi: ExtensionAPI) {
       );
     } catch (err) {
       console.error("pi-condense: context metrics computation failed", err);
+      return undefined;
     }
-    return metricsCache;
   };
 
   type FlushResult =
@@ -566,7 +553,7 @@ export default function (pi: ExtensionAPI) {
 
       if (processedBatches.length === 0) {
         // Nothing was persisted (all calls failed or first call failed)
-        setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+        setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
         outcome = "error";
         return { ok: false, reason: "summarizer-failed" };
       }
@@ -601,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 = {
@@ -644,7 +629,7 @@ export default function (pi: ExtensionAPI) {
         return { ok: false, reason: isStaleContextError(err) ? "stale-context" : "failed", error: errorMessage(err) };
       }
 
-      setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+      setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
       emitExternalCost(pi, statsAccum);
 
       // Chain compression — compress closed chains beyond the rolling window.
@@ -771,7 +756,7 @@ export default function (pi: ExtensionAPI) {
       // When the abort signal fired, summarizeBatch rethrows rather than
       // swallowing the error.  Don't show a UI error — the user intended this.
       if (options.signal?.aborted) {
-        setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+        setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
         return { ok: false, reason: "aborted" };
       }
       if (isStaleContextError(err)) {
@@ -816,10 +801,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    computeMetricsSnapshot(ctx);
-
     // Update footer status
-    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
 
     ctx.ui.setWidget(
       "pruner-boot",
@@ -856,8 +839,7 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    computeMetricsSnapshot(ctx);
-    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
   });
 
   // ── turn_end: capture batch, flush immediately or queue ──────────────────
@@ -934,13 +916,6 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Recompute regardless of whether trim produced a batch: a turn whose
-    // toolResults are all protected/spilled/summarized/trimmed-empty still
-    // changes the branch (thinking, open-segment size), so the cache must not
-    // go stale on it. Placed before the pushedBatch/rearmedPending early
-    // return below — a cache write is not gate evaluation.
-    if (hasToolResults) computeMetricsSnapshot(ctx);
-
     // Mirrors main's `if (!batch) return;`: no freshly pushed batch this turn
     // means no gate evaluation, regardless of leftover pendingBatches from an
     // earlier turn — UNLESS a reload probe armed rearmedPending, in which case
@@ -954,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",
+      });
     }
   });
 
@@ -1026,7 +1011,7 @@ export default function (pi: ExtensionAPI) {
       changed = true;
       statsAccum.setLiveReclaim(result.beforeChars, result.afterChars);
     }
-    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts(), metricsCache);
+    setPruneStatusWidget(ctx, currentConfig.value, statsAccum.getLiveReclaim(), diagnostics.counts());
 
     if (!changed) return undefined;
     return { messages };
@@ -1037,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(
@@ -1082,7 +1064,6 @@ export default function (pi: ExtensionAPI) {
     compactChains,
     () => diagnostics.counts(),
     (ctx: any) => computeMetricsSnapshot(ctx) ?? EMPTY_METRICS_SNAPSHOT,
-    () => metricsCache,
     () => rearmedPending,
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.9.1",
+  "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.