pi-condense 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -9,6 +9,24 @@ publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-07-06
+
+- **Summarizer outage fallback to the session model.** Per-model provider outages (e.g. a cheap `summarizerModel` like Haiku degraded while the session's main model stays healthy) previously stalled pruning for the whole outage - `runSummarization` returned null and the batch retried the same dead model every flush, growing context unbounded. A new sticky in-memory `FallbackController` (`src/summarizer-fallback.ts`) now routes summarization to `ctx.model` on a **transient** failure of the configured model, retrying the failed call once on the session model. Fallback is sticky: while engaged, all calls use the session model until a single probe batch re-tests the configured model after a 10-minute cooldown, then auto-recovers. Trigger is transient-only - auth (pre-flight key failure), unusable (empty/truncated), and abort never trip it. A one-time `warning` fires on enter and an `info` on recovery via `ctx.ui.notify` (UI only, never injected into LLM context). No config key: the target is always `ctx.model`, and the controller is inert when no distinct fallback model exists (`summarizerModel: default` or the resolved model equals `ctx.model`), preserving today's single-attempt behavior byte-for-byte. State is in-memory only (reset on `session_start`, no `context-prune-*` entry).
+
+## [2.1.2] - 2026-07-05
+
+Branding, funding, and gallery preview. No behavior change.
+
+### Added
+
+- **Logo + pi.dev gallery preview.** Repo-root `pi-condense.png` (640x640), shown in the README and wired as `pi.image`.
+- **Buy Me a Coffee funding.** `funding` in `package.json`, `.github/FUNDING.yml`, and a README badge.
+
+### Changed
+
+- Sharpened `description`; added `context-pruning`, `llm`, `prompt-caching` keywords.
+- README reframed product-first (credit to `championswimmer/pi-context-prune` kept as attribution); fixed a stale `pi-superpowers` -> `pi-gauntlet` reference in a spec doc.
+
 ## [2.1.1] - 2026-07-04
 
 - **`release.yml` posts GitHub Release notes.** A new `release-notes` job (`needs: publish`, `contents: write`) extracts the CHANGELOG section matching the pushed tag with `awk` (skipping `## [Unreleased]`) and publishes it as the GitHub Release body via `gh release create` (falling back to `gh release edit`). No LLM or API key; only `github.token`.

package/PRUNING.md

@@ -688,6 +688,38 @@ The last attempted prune boundary is persisted as `context-prune-frontier` so `f
 - **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all four reclaim mechanisms in a single point (stub-replace, error-purge, chain-range-prune, thinking-strip); appears on the status line as `│ prune: ON · 92k->14k (-85%) │` once at least one prune has occurred (the `│ … │` wrapper keeps the segment visually isolated in the shared footer, load-order independent).
 - **Live progress for `/pruner now`:** an `aboveEditor` widget shows one row per pending batch with braille spinner, streamed summary-char count, and ✓ / ⚠ status.
 
+### Summarizer outage fallback
+
+Provider incidents are routinely per-model: a cheap summarizer model (e.g.
+Haiku) can be down while the session's main model (Sonnet/Opus) stays healthy.
+Without a fallback, `runSummarization` returns `null`, the batch is re-queued,
+and the next flush retries the same dead model — pruning stalls for the whole
+outage and context grows unbounded.
+
+`src/summarizer-fallback.ts` adds a sticky, in-memory `FallbackController` that
+engages only on **transient** failures of the configured summarizer model and
+only when a distinct fallback model exists (`summarizerModel` != `default` and
+the resolved model differs from `ctx.model`):
+
+- **Classification is coarse** (pi-ai surfaces no status code on the throw):
+  `auth` (pre-flight key failure) and `unusable` (empty / length-truncated)
+  never trip the controller; a `transient` stream error / `stopReason: error`
+  does. Aborts propagate unchanged.
+- **Enter:** a transient primary failure is retried once on the session model.
+  If that succeeds, the session flips to fallback and a one-time warning fires.
+- **Sticky + probe:** while in fallback, all calls route to the session model.
+  After a 10-minute cooldown (`COOLDOWN_MS`, internal, not configurable) one
+  batch of the next flush probes the primary; success recovers (info notify),
+  failure stays in fallback.
+- **In-memory only:** no `context-prune-*` entry; `reset()` on `session_start`.
+  A restart mid-outage re-detects on the next flush.
+
+Cost note: the initial detection flush can fire up to N doomed primary calls
+before the outage is known; steady state is 0 doomed calls, plus exactly 1
+probe per 10 minutes. After the primary recovers, summarization keeps running
+on the (often pricier) session model for up to one cooldown before the probe
+switches back.
+
 ---
 
 ## Why Summarization Works: Research Evidence

package/README.md

@@ -1,10 +1,16 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jjuraszek/pi-condense/main/pi-condense.png" alt="pi-condense" width="180">
+</p>
+
 # pi-condense
 
-A [Pi coding-agent](https://github.com/badlogic/pi-mono) extension that summarizes completed tool-call batches, replaces raw tool outputs with short stubs in future context, and lets the LLM recover any original via the `context_tree_query` tool.
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-donate-yellow?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/jjurasszek)
+
+A [Pi coding-agent](https://github.com/earendil-works/pi) extension that summarizes completed tool-call batches, replaces raw tool outputs with short stubs in future context, and lets the LLM recover any original via the `context_tree_query` tool.
 
 The session JSONL file is never modified — pruning only affects what each *next* request sees.
 
-Fork of [`championswimmer/pi-context-prune`](https://github.com/championswimmer/pi-context-prune) with additional pre-flush safeguards, agent-message batching, chain compression, and an npm release flow.
+Adds pre-flush safeguards, agent-message batching, chain compression, and an npm release flow on top of the original approach from [`championswimmer/pi-context-prune`](https://github.com/championswimmer/pi-context-prune).
 
 📖 For the algorithm, design rationale, prompt-cache interaction, and the research behind summarization-based context management, see **[PRUNING.md](PRUNING.md)**.
 
@@ -42,7 +48,7 @@ pi -e ~/repos/pi-condense/index.ts
 
 Pin a specific version with `npm:pi-condense@X.Y.Z`. Upgrade by re-running `pi install`. Remove with `pi remove pi-condense`. Once installed, the extension auto-loads on every `pi` invocation; no flags needed.
 
-> Diverges from upstream `championswimmer/pi-context-prune`; see [CHANGELOG.md](CHANGELOG.md) for what differs.
+> See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## Quick start
 
@@ -152,6 +158,8 @@ Single tool results larger than `spillThreshold` chars are written to `<session-
 
 The `default` setting reuses whatever model you have active in pi — convenient but wasteful, since summary writing doesn't need a top-tier coding model. Picking the smallest/fastest model on your plan saves both latency and cost.
 
+If the configured summarizer model suffers a transient outage while your active pi model is healthy, pi-condense automatically falls back to the session model for the duration (with a one-time notice) and probes the configured model back every few minutes — no configuration needed.
+
 | Plan | Suggested summarizer |
 |---|---|
 | OpenAI / Codex / Copilot | `openai/gpt-4.1-mini`, `google/gemini-2.5-flash`, `xai/grok-3-fast` |
@@ -236,6 +244,10 @@ Semantics:
 - Content-hash dedup only matches against records already in the indexer (cross-flush). Two identical outputs within the *same* flush are not deduped — both go through the summarizer.
 - The tree browser does not inline original tool outputs — use `context_tree_query` for that.
 
+## Support
+
+If this saves you tokens, [buy me a coffee](https://buymeacoffee.com/jjurasszek).
+
 ## References
 
 - Anthropic prompt caching: <https://docs.claude.com/en/docs/build-with-claude/prompt-caching>

package/index.ts

@@ -17,6 +17,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 { summarizeBatch, summarizeBatches, summarizeRange } from "./src/summarizer.js";
+import { FallbackController } from "./src/summarizer-fallback.js";
 import { ToolCallIndexer } from "./src/indexer.js";
 import { pruneMessages } from "./src/pruner.js";
 import { isProtected } from "./src/protected.js";
@@ -52,6 +53,9 @@ export default function (pi: ExtensionAPI) {
   // Shared stats accumulator — tracks cumulative token/cost stats for summarizer calls
   const statsAccum = new StatsAccumulator();
 
+  // Session-scoped summarizer outage-fallback controller (in-memory; reset on session_start).
+  const fallbackController = new FallbackController();
+
   // Shared prune frontier — tracks the last completed prune attempt boundary
   const frontier = new PruneFrontierTracker();
 
@@ -152,7 +156,7 @@ export default function (pi: ExtensionAPI) {
   const makeFuseRange = (ctx: any): ((text: string) => Promise<string | null>) | undefined => {
     if (!currentConfig.value.chainCompression.fuseRangeSummary) return undefined;
     return async (text: string) => {
-      const r = await summarizeRange(text, currentConfig.value, ctx, {});
+      const r = await summarizeRange(text, currentConfig.value, ctx, { controller: fallbackController });
       if (r) {
         statsAccum.add(r.usage);
         statsAccum.addRangesSummarized(1);
@@ -303,6 +307,7 @@ export default function (pi: ExtensionAPI) {
           options.onProgress(i, batches.length, batches[i], "start");
           const r = await summarizeBatch(batches[i], currentConfig.value, ctx, {
             signal: options.signal,
+            controller: fallbackController,
             onTextProgress: (receivedChars) => {
               reportBatchTextProgress(i, batches.length, batches[i], receivedChars);
             },
@@ -326,6 +331,7 @@ export default function (pi: ExtensionAPI) {
               reportBatchTextProgress(origIndex, batches.length, batch, receivedChars);
             },
             signal: options.signal,
+            controller: fallbackController,
           });
           for (let k = 0; k < nonTrivialIndices.length; k++) {
             results[nonTrivialIndices[k]] = ntResults[k];
@@ -647,6 +653,7 @@ export default function (pi: ExtensionAPI) {
 
     // Rebuild stats accumulator from persisted session entries
     statsAccum.reconstructFromSession(ctx);
+    fallbackController.reset();
 
     // Rebuild prune frontier from persisted session entries
     frontier.reconstructFromSession(ctx);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-condense",
-  "version": "2.1.1",
-  "description": "Pi extension that summarizes completed tool-call batches, replaces raw outputs with short stubs in future context, and recovers any original on demand via context_tree_query.",
+  "version": "2.2.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",
   "type": "module",
@@ -19,8 +19,11 @@
     "pi-coding-agent",
     "context",
     "context-management",
+    "context-pruning",
     "pruning",
     "summarization",
+    "llm",
+    "prompt-caching",
     "ai"
   ],
   "engines": {
@@ -40,7 +43,12 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/jjuraszek/pi-condense/main/pi-condense.png"
+  },
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://buymeacoffee.com/jjurasszek"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/summarizer-fallback.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "bun:test";
+import { FallbackController, COOLDOWN_MS } from "./summarizer-fallback.js";
+
+const HAIKU = { id: "claude-haiku", provider: "anthropic", name: "Haiku" };
+const SONNET = { id: "claude-sonnet", provider: "anthropic", name: "Sonnet" };
+
+function clockAt(t: { now: number }) {
+  return () => t.now;
+}
+
+describe("hasDistinctFallback", () => {
+  it("false when models are identical", () => {
+    expect(FallbackController.hasDistinctFallback(HAIKU, HAIKU)).toBe(false);
+  });
+  it("false when either model is missing", () => {
+    expect(FallbackController.hasDistinctFallback(undefined, SONNET)).toBe(false);
+    expect(FallbackController.hasDistinctFallback(HAIKU, undefined)).toBe(false);
+  });
+  it("true when id or provider differ", () => {
+    expect(FallbackController.hasDistinctFallback(HAIKU, SONNET)).toBe(true);
+    expect(
+      FallbackController.hasDistinctFallback(
+        { id: "m", provider: "a" },
+        { id: "m", provider: "b" },
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("chooseTarget", () => {
+  it("targets primary when not in fallback", () => {
+    const c = new FallbackController();
+    expect(c.chooseTarget()).toEqual({ target: "primary", wasProbe: false });
+  });
+
+  it("targets fallback while in fallback and before cooldown", () => {
+    const t = { now: 1_000_000 };
+    const c = new FallbackController(clockAt(t));
+    c.onPrimaryFailFallbackOk(false);
+    expect(c.inFallback).toBe(true);
+    t.now += COOLDOWN_MS - 1;
+    expect(c.chooseTarget()).toEqual({ target: "fallback", wasProbe: false });
+  });
+
+  it("elects exactly one probe after cooldown elapses", () => {
+    const t = { now: 0 };
+    const c = new FallbackController(clockAt(t));
+    c.onPrimaryFailFallbackOk(false); // enter, lastProbeAt = 0
+    t.now = COOLDOWN_MS;
+    expect(c.chooseTarget()).toEqual({ target: "primary", wasProbe: true });
+    expect(c.chooseTarget()).toEqual({ target: "fallback", wasProbe: false });
+  });
+});
+
+describe("enter fallback (single notify across N)", () => {
+  it("first rescued transient returns 'enter', rest return 'none'", () => {
+    const c = new FallbackController();
+    expect(c.onPrimaryFailFallbackOk(false)).toBe("enter");
+    expect(c.inFallback).toBe(true);
+    expect(c.onPrimaryFailFallbackOk(false)).toBe("none");
+    expect(c.onPrimaryFailFallbackOk(false)).toBe("none");
+  });
+});
+
+describe("recover", () => {
+  it("probe success while in fallback returns 'recover' and clears state", () => {
+    const c = new FallbackController();
+    c.onPrimaryFailFallbackOk(false); // enter
+    expect(c.onPrimarySuccess(true)).toBe("recover");
+    expect(c.inFallback).toBe(false);
+  });
+  it("non-probe primary success is a no-op", () => {
+    const c = new FallbackController();
+    expect(c.onPrimarySuccess(false)).toBe("none");
+    expect(c.inFallback).toBe(false);
+  });
+});
+
+describe("probe transient failure keeps fallback (stay)", () => {
+  it("rescued probe returns 'none' and stays in fallback", () => {
+    const t = { now: 0 };
+    const c = new FallbackController(clockAt(t));
+    c.onPrimaryFailFallbackOk(false); // enter
+    t.now = COOLDOWN_MS;
+    const d = c.chooseTarget(); // claims probe
+    expect(d.wasProbe).toBe(true);
+    t.now = COOLDOWN_MS + 5;
+    expect(c.onPrimaryFailFallbackOk(true)).toBe("none");
+    expect(c.inFallback).toBe(true);
+  });
+});
+
+describe("both-down owes a deferred enter warning", () => {
+  it("owed warning fires on the first later fallback success", () => {
+    const c = new FallbackController();
+    c.onBothDown(); // initial detection both-down: enter silently, owe warning
+    expect(c.inFallback).toBe(true);
+    expect(c.onFallbackSuccess()).toBe("enter");
+    expect(c.onFallbackSuccess()).toBe("none");
+  });
+  it("both-down while already in fallback does not owe a new warning", () => {
+    const c = new FallbackController();
+    c.onPrimaryFailFallbackOk(false); // enter (warning already shown)
+    c.onBothDown(); // probe both-down while in fallback
+    expect(c.onFallbackSuccess()).toBe("none");
+  });
+});
+
+describe("recover clears an owed enter warning", () => {
+  it("a probe recovery after both-down does not later emit a stale enter", () => {
+    const t = { now: 0 };
+    const c = new FallbackController(clockAt(t));
+    c.onBothDown(); // enter silently, owe warning
+    t.now = COOLDOWN_MS;
+    const d = c.chooseTarget(); // claims probe
+    expect(d.wasProbe).toBe(true);
+    expect(c.onPrimarySuccess(true)).toBe("recover");
+    expect(c.inFallback).toBe(false);
+    // owed warning must be cleared by recovery
+    expect(c.onFallbackSuccess()).toBe("none");
+  });
+});
+
+describe("unusable probe does not falsely recover", () => {
+  it("no onPrimarySuccess call means inFallback is retained", () => {
+    const t = { now: 0 };
+    const c = new FallbackController(clockAt(t));
+    c.onPrimaryFailFallbackOk(false); // enter
+    t.now = COOLDOWN_MS;
+    const d = c.chooseTarget();
+    expect(d.wasProbe).toBe(true);
+    expect(c.inFallback).toBe(true);
+  });
+});
+
+describe("reset", () => {
+  it("clears all state", () => {
+    const t = { now: 5 };
+    const c = new FallbackController(clockAt(t));
+    c.onBothDown();
+    c.reset();
+    expect(c.inFallback).toBe(false);
+    expect(c.onFallbackSuccess()).toBe("none"); // owed cleared
+    expect(c.chooseTarget()).toEqual({ target: "primary", wasProbe: false });
+  });
+});

package/src/summarizer-fallback.ts

@@ -0,0 +1,122 @@
+/**
+ * Session-scoped, in-memory state machine for summarizer-model outage fallback.
+ *
+ * Pure of model IO and notify plumbing: transition methods mutate state and
+ * return a transition tag; the caller (runSummarization) performs the LLM runs
+ * and emits any notify text. `now()` is injected for deterministic tests.
+ *
+ * Engaged ONLY on transient (outage-shaped) failures of the configured
+ * summarizer model, and only when a distinct fallback model exists. Sticky:
+ * once in fallback, all calls route to the session model until a single
+ * per-cooldown probe of the primary succeeds. See
+ * doc/specs/2026-07-06-summarizer-outage-fallback.md.
+ */
+
+/** Re-probe cooldown while in fallback. Internal; deliberately not configurable. */
+export const COOLDOWN_MS = 10 * 60 * 1000;
+
+export type FallbackTransition = "enter" | "recover" | "none";
+export type CallTarget = "primary" | "fallback";
+
+export interface TargetDecision {
+  target: CallTarget;
+  wasProbe: boolean;
+}
+
+/** Minimal structural view of a pi-ai Model (avoids the generic Api type param). */
+export interface ModelLike {
+  id: string;
+  provider: string;
+  name?: string;
+}
+
+export class FallbackController {
+  inFallback = false;
+  private lastProbeAt = 0;
+  private owedEnterWarning = false;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  reset(): void {
+    this.inFallback = false;
+    this.lastProbeAt = 0;
+    this.owedEnterWarning = false;
+  }
+
+  /**
+   * True when primary and the session model are genuinely different. When
+   * false the controller must NOT be consulted (behavior identical to today).
+   * `Model.provider` is a plain string in pi-ai, not an object.
+   */
+  static hasDistinctFallback(
+    primary: ModelLike | undefined,
+    sessionModel: ModelLike | undefined,
+  ): boolean {
+    if (!primary || !sessionModel) return false;
+    return primary.provider !== sessionModel.provider || primary.id !== sessionModel.id;
+  }
+
+  /**
+   * Pick the model target for the next call and, if eligible, claim the single
+   * per-cooldown probe. The claim is synchronous: the first of N concurrent
+   * callers in a flush advances `lastProbeAt`, so siblings see the cooldown as
+   * not elapsed and route to the fallback. Call before the first await.
+   */
+  chooseTarget(): TargetDecision {
+    if (!this.inFallback) return { target: "primary", wasProbe: false };
+    if (this.now() - this.lastProbeAt >= COOLDOWN_MS) {
+      this.lastProbeAt = this.now();
+      return { target: "primary", wasProbe: true };
+    }
+    return { target: "fallback", wasProbe: false };
+  }
+
+  /** Primary (initial or probe) failed transiently but the fallback retry succeeded. */
+  onPrimaryFailFallbackOk(_wasProbe: boolean): FallbackTransition {
+    this.lastProbeAt = this.now();
+    if (this.owedEnterWarning) {
+      this.owedEnterWarning = false;
+      this.inFallback = true;
+      return "enter";
+    }
+    if (!this.inFallback) {
+      this.inFallback = true;
+      return "enter";
+    }
+    // probe transient, rescued by fallback -> stay, no notify
+    return "none";
+  }
+
+  /** Both the primary call and the fallback retry failed transiently. */
+  onBothDown(): void {
+    this.lastProbeAt = this.now();
+    if (!this.inFallback) {
+      this.inFallback = true;
+      this.owedEnterWarning = true;
+    }
+  }
+
+  /** A steady-state fallback call (already in fallback) failed transiently. */
+  onFallbackOnlyFail(): void {
+    this.lastProbeAt = this.now();
+  }
+
+  /** A primary call succeeded. Recover only when it was the probe. */
+  onPrimarySuccess(wasProbe: boolean): FallbackTransition {
+    if (wasProbe && this.inFallback) {
+      this.inFallback = false;
+      this.owedEnterWarning = false;
+      return "recover";
+    }
+    return "none";
+  }
+
+  /** A steady-state fallback call succeeded. Fire the deferred enter warning if owed. */
+  onFallbackSuccess(): FallbackTransition {
+    if (this.owedEnterWarning) {
+      this.owedEnterWarning = false;
+      return "enter";
+    }
+    return "none";
+  }
+}

package/src/summarizer-wiring.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, mock } from "bun:test";
+
+// Stub pi-ai's `stream` so runSummarization can be exercised without a network
+// call. `streamImpl` is swapped per test to simulate primary/fallback outcomes.
+let streamImpl: (model: any) => any = () => {
+  throw new Error("streamImpl not set");
+};
+mock.module("@earendil-works/pi-ai", () => ({
+  stream: (model: any) => streamImpl(model),
+}));
+
+const { summarizeBatch } = await import("./summarizer.js");
+const { FallbackController } = await import("./summarizer-fallback.js");
+const { DEFAULT_CONFIG } = await import("./types.js");
+
+const PRIMARY = { id: "primary-model", provider: "provider-a", name: "Primary" };
+const SESSION = { id: "session-model", provider: "provider-b", name: "Session" };
+
+const USAGE = {
+  input: 1,
+  output: 1,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 2,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
+function okStream(text: string) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      // no events; runOnce only needs .result()
+    },
+    async result() {
+      return { stopReason: "stop", content: [{ type: "text", text }], usage: USAGE };
+    },
+  };
+}
+
+function errStream(message: string) {
+  return {
+    async *[Symbol.asyncIterator]() {},
+    async result() {
+      return { stopReason: "error", errorMessage: message, content: [], usage: USAGE };
+    },
+  };
+}
+
+interface Note {
+  msg: string;
+  level: string;
+}
+
+function makeCtx(notes: Note[], sessionModel: any = SESSION, primaryModel: any = PRIMARY) {
+  return {
+    model: sessionModel,
+    modelRegistry: {
+      find: () => primaryModel,
+      getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "k", headers: {} }),
+    },
+    ui: { notify: (msg: string, level: string) => notes.push({ msg, level }) },
+  } as any;
+}
+
+function makeBatch() {
+  return {
+    turnIndex: 0,
+    timestamp: 0,
+    assistantText: "",
+    toolCalls: [
+      { toolCallId: "t1", toolName: "read", args: {}, resultText: "x".repeat(50), isError: false },
+    ],
+  } as any;
+}
+
+const distinctConfig = { ...DEFAULT_CONFIG, summarizerModel: "provider-a/primary-model" };
+
+describe("runSummarization wiring — same-model no-op (legacy path)", () => {
+  it("summarizerModel=default: transient failure notifies error, returns null, controller untouched", async () => {
+    streamImpl = () => errStream("provider overloaded");
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const r = await summarizeBatch(makeBatch(), { ...DEFAULT_CONFIG, summarizerModel: "default" }, ctx, {
+      controller,
+    });
+    expect(r).toBeNull();
+    expect(controller.inFallback).toBe(false);
+    expect(notes).toHaveLength(1);
+    expect(notes[0].level).toBe("error");
+    expect(notes[0].msg).toContain("provider overloaded");
+  });
+});
+
+describe("runSummarization wiring — enter fallback", () => {
+  it("primary transient + fallback ok: returns summary, one warning, no error notify, sticky", async () => {
+    streamImpl = (model) => (model.id === PRIMARY.id ? errStream("down") : okStream("- fallback summary"));
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const r = await summarizeBatch(makeBatch(), distinctConfig, ctx, { controller });
+    expect(r?.summaryText).toBe("- fallback summary");
+    expect(controller.inFallback).toBe(true);
+    const warnings = notes.filter((n) => n.level === "warning");
+    const errors = notes.filter((n) => n.level === "error");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].msg).toContain("Primary");
+    expect(warnings[0].msg).toContain("Session");
+    expect(errors).toHaveLength(0);
+  });
+
+  it("steady-state after enter routes to the session model only (no primary call, no notify)", async () => {
+    const seen: string[] = [];
+    streamImpl = (model) => {
+      seen.push(model.id);
+      return model.id === PRIMARY.id ? errStream("down") : okStream("- ok");
+    };
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController(); // real clock: cooldown (10m) will not elapse in-test
+    await summarizeBatch(makeBatch(), distinctConfig, ctx, { controller }); // enter
+    seen.length = 0;
+    notes.length = 0;
+    const r = await summarizeBatch(makeBatch(), distinctConfig, ctx, { controller }); // steady-state
+    expect(r?.summaryText).toBe("- ok");
+    expect(seen).toEqual([SESSION.id]); // primary never called again before cooldown
+    expect(notes).toHaveLength(0);
+  });
+});
+
+describe("runSummarization wiring — both-down + deferred warning", () => {
+  it("primary + fallback both transient: null, error notify, enters fallback with owed warning", async () => {
+    streamImpl = () => errStream("everything down");
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const r = await summarizeBatch(makeBatch(), distinctConfig, ctx, { controller });
+    expect(r).toBeNull();
+    expect(controller.inFallback).toBe(true);
+    const warnings = notes.filter((n) => n.level === "warning");
+    const errors = notes.filter((n) => n.level === "error");
+    expect(warnings).toHaveLength(0); // warning is owed, not yet fired
+    expect(errors).toHaveLength(1);
+
+    // Next flush: fallback now succeeds -> owed warning fires once.
+    streamImpl = (model) => (model.id === PRIMARY.id ? errStream("still down") : okStream("- rescued"));
+    notes.length = 0;
+    const r2 = await summarizeBatch(makeBatch(), distinctConfig, ctx, { controller });
+    expect(r2?.summaryText).toBe("- rescued");
+    expect(notes.filter((n) => n.level === "warning")).toHaveLength(1);
+  });
+});
+
+describe("runSummarization wiring — abort", () => {
+  it("re-throws when the signal is already aborted", async () => {
+    streamImpl = () => okStream("- never");
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const ac = new AbortController();
+    ac.abort();
+    await expect(
+      summarizeBatch(makeBatch(), distinctConfig, ctx, { controller, signal: ac.signal }),
+    ).rejects.toThrow();
+  });
+});

package/src/summarizer.ts

@@ -10,6 +10,7 @@ import type {
   SummarizeResult,
 } from "./types.js";
 import { serializeBatchForSummarizer } from "./batch-capture.js";
+import { FallbackController, type FallbackTransition } from "./summarizer-fallback.js";
 
 const SYSTEM_PROMPT = `You are summarizing a batch of tool calls made by an AI coding assistant.
 For each tool call provide:
@@ -85,30 +86,38 @@ export function isUsableSummary(llmText: string, stopReason: string): boolean {
   return llmText.trim().length > 0 && stopReason !== "length";
 }
 
+type RunOutcome =
+  | { kind: "ok"; result: SummarizeResult }
+  | { kind: "auth"; message: string }
+  | { kind: "unusable" }
+  | { kind: "transient"; message: string };
+
+/** Human label for a model in notify text: prefer name, fall back to provider/id. */
+function modelLabel(model: any): string {
+  if (!model) return "unknown model";
+  return model.name || `${model.provider}/${model.id}`;
+}
+
 /**
- * Shared LLM-call machinery for both per-batch and range summarization.
- * `userMessage` already embeds the relevant system prompt as leading text
- * (the summarizer is a single-user-message call). Returns the formatted text
- * + usage, or null on failure. Abort errors are re-thrown so flushPending can
- * detect options.signal.aborted and restore state without a UI error.
+ * One summarization attempt against a specific model. Returns a classified
+ * outcome instead of throwing (except aborts, which propagate so flushPending
+ * can restore state). Auth failure is detected pre-stream and never reaches
+ * the fallback path. `unusable` = empty or length-truncated. Everything else
+ * that reaches the catch is `transient` (the outage bucket) — pi-ai surfaces
+ * no structured status code on the throw, so classification is coarse by design.
  */
-async function runSummarization(
+async function runOnce(
+  model: any,
   userMessage: string,
   config: ContextPruneConfig,
   ctx: ExtensionContext,
   options: SummarizeBatchOptions
-): Promise<SummarizeResult | null> {
-  // Fast-fail if already aborted before we even start.
-  if (options.signal?.aborted) throw new Error("summarize: aborted before start");
-
+): Promise<RunOutcome> {
   try {
-    const model = resolveModel(config, ctx);
-
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
     if (!auth.ok) {
       const authMessage = "error" in auth ? auth.error : "authentication failed";
-      ctx.ui.notify(`pruner: summarization failed: ${authMessage}`, "error");
-      return null;
+      return { kind: "auth", message: authMessage };
     }
 
     // Pass the abort signal so the underlying fetch is cancelled immediately
@@ -153,12 +162,12 @@ async function runSummarization(
     reportTextProgress(response);
     // stopReason "aborted" means the provider cut the stream short (e.g. signal
     // fired just before the final chunk). Treat identically to the signal check
-    // above — throw so flushPending's catch can detect options.signal.aborted.
+    // above — throw so the catch below can detect options.signal.aborted.
     if (response.stopReason === "aborted") {
       throw new Error("summarize: stream stopped with reason aborted");
     }
     if (response.stopReason === "error") {
-      throw new Error(response.errorMessage ?? "Summarizer stopped with reason: error");
+      return { kind: "transient", message: response.errorMessage ?? "Summarizer stopped with reason: error" };
     }
 
     const llmText = response.content
@@ -166,21 +175,101 @@ async function runSummarization(
       .map((c: any) => c.text)
       .join("\n");
 
-    if (!isUsableSummary(llmText, response.stopReason)) return null;
+    if (!isUsableSummary(llmText, response.stopReason)) return { kind: "unusable" };
 
-    return {
-      summaryText: llmText,
-      usage: response.usage,
-    };
+    return { kind: "ok", result: { summaryText: llmText, usage: response.usage } };
   } catch (err: any) {
     // Propagate abort errors upward so flushPending can check signal.aborted
     // and return { ok: false, reason: "aborted" } without showing a UI error.
     if (options.signal?.aborted) throw err;
-    ctx.ui.notify(
-      `pruner: summarization failed: ${err.message}`,
-      "error"
-    );
-    return null;
+    return { kind: "transient", message: err.message };
+  }
+}
+
+/**
+ * Shared LLM-call machinery for both per-batch and range summarization.
+ * `userMessage` already embeds the relevant system prompt as leading text
+ * (the summarizer is a single-user-message call). Returns the formatted text
+ * + usage, or null on failure. Abort errors are re-thrown so flushPending can
+ * detect options.signal.aborted and restore state without a UI error.
+ *
+ * When options.controller is set AND a distinct fallback model exists, a
+ * transient failure of the configured summarizer model is retried once on the
+ * session model, and the controller stays sticky in fallback until a
+ * per-cooldown probe of the primary succeeds.
+ */
+async function runSummarization(
+  userMessage: string,
+  config: ContextPruneConfig,
+  ctx: ExtensionContext,
+  options: SummarizeBatchOptions
+): Promise<SummarizeResult | null> {
+  // Fast-fail if already aborted before we even start.
+  if (options.signal?.aborted) throw new Error("summarize: aborted before start");
+
+  const primary = resolveModel(config, ctx);
+  const controller = options.controller;
+  const sessionModel = ctx.model;
+
+  const notifyError = (msg: string) =>
+    ctx.ui.notify(`pruner: summarization failed: ${msg}`, "error");
+
+  // No controller or no distinct fallback: single attempt, legacy behavior.
+  if (!controller || !FallbackController.hasDistinctFallback(primary, sessionModel)) {
+    const r = await runOnce(primary, userMessage, config, ctx, options);
+    switch (r.kind) {
+      case "ok":
+        return r.result;
+      case "auth":
+      case "transient":
+        notifyError(r.message);
+        return null;
+      case "unusable":
+        return null;
+    }
+  }
+
+  const emit = (t: FallbackTransition) => {
+    if (t === "enter") {
+      ctx.ui.notify(
+        `pi-condense: summarizer model ${modelLabel(primary)} failing, using session model ${modelLabel(sessionModel)} until it recovers`,
+        "warning"
+      );
+    } else if (t === "recover") {
+      ctx.ui.notify(`pi-condense: summarizer model ${modelLabel(primary)} recovered`, "info");
+    }
+  };
+
+  const decision = controller.chooseTarget();
+  const model = decision.target === "primary" ? primary : sessionModel;
+  const r = await runOnce(model, userMessage, config, ctx, options);
+
+  switch (r.kind) {
+    case "ok":
+      if (decision.target === "primary") emit(controller.onPrimarySuccess(decision.wasProbe));
+      else emit(controller.onFallbackSuccess());
+      return r.result;
+    case "auth":
+      notifyError(r.message); // auth never trips the controller
+      return null;
+    case "unusable":
+      return null; // probe unusable => stay (no state change)
+    case "transient": {
+      if (decision.target === "fallback") {
+        controller.onFallbackOnlyFail();
+        notifyError(r.message);
+        return null;
+      }
+      // target was primary (initial detection or probe): retry once on the session model.
+      const r2 = await runOnce(sessionModel, userMessage, config, ctx, options);
+      if (r2.kind === "ok") {
+        emit(controller.onPrimaryFailFallbackOk(decision.wasProbe));
+        return r2.result; // suppress the legacy error notify — fallback rescued the call
+      }
+      controller.onBothDown();
+      notifyError(r2.kind === "transient" || r2.kind === "auth" ? r2.message : r.message);
+      return null;
+    }
   }
 }
 
@@ -243,6 +332,7 @@ export async function summarizeBatches(
     return [
       await summarizeBatch(batches[0], config, ctx, {
         signal: options.signal,
+        controller: options.controller,
         onTextProgress: (receivedChars) => {
           options.onBatchTextProgress?.(0, 1, batches[0], receivedChars);
         },
@@ -255,6 +345,7 @@ export async function summarizeBatches(
     batches.map((batch, index) =>
       summarizeBatch(batch, config, ctx, {
         signal: options.signal,
+        controller: options.controller,
         onTextProgress: (receivedChars) => {
           options.onBatchTextProgress?.(index, batches.length, batch, receivedChars);
         },

package/src/types.ts

@@ -42,6 +42,8 @@
  *     NOT a hidden side-channel. It makes an explicit LLM call from turn_end.
  */
 
+import type { FallbackController } from "./summarizer-fallback.js";
+
 // ── Constants ──────────────────────────────────────────────────────────────
 
 /** customType for summary custom_message entries (appear in LLM context) */
@@ -728,6 +730,12 @@ export interface SummarizeBatchOptions {
    * batch is treated as aborted (not a summarizer failure).
    */
   signal?: AbortSignal;
+  /**
+   * Session-scoped outage-fallback controller. When present AND a distinct
+   * fallback model exists, runSummarization routes/retries via the controller
+   * (see src/summarizer-fallback.ts). Absent => today's single-attempt behavior.
+   */
+  controller?: FallbackController;
 }
 
 /** Options for summarizeBatches() when callers want live per-batch text progress. */
@@ -739,6 +747,12 @@ export interface SummarizeBatchesOptions {
    * When fired, all in-flight stream calls are cancelled.
    */
   signal?: AbortSignal;
+  /**
+   * Session-scoped outage-fallback controller. When present AND a distinct
+   * fallback model exists, runSummarization routes/retries via the controller
+   * (see src/summarizer-fallback.ts). Absent => today's single-attempt behavior.
+   */
+  controller?: FallbackController;
 }
 
 /**