ytdb-slate 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,50 @@
 
 Slate is a thread-weaving orchestration extension for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent).
 
-The orchestrator (your main pi session) dispatches **bounded actions** to persistent **worker threads**. Each completed action is compressed by an LLM into an **episode** — a durable, structured record (intent, actions, findings, artifacts, open issues, handoff notes) that the orchestrator composes into further dispatches instead of re-reading raw transcripts. On top of that, Slate injects a mandatory workflow doctrine: research before design, design review, adversarial review, and track review — with optional umbrella **draft-PR publishing** for tracks.
+The orchestrator (your main pi session) dispatches **bounded actions** to persistent **worker threads**. Each completed action is compressed by an LLM into an **episode** — a durable, structured record (intent, actions, findings, artifacts, open issues, handoff notes) that the orchestrator composes into further dispatches instead of re-reading raw transcripts. On top of that, Slate injects a mandatory workflow doctrine: research before design, design review, adversarial review, and track review — with optional umbrella **draft-PR publishing** for tracks. An opt-in **model-failover** map adds high availability: when a model API fails, the orchestrator, worker threads, and episode compression each retry once on a configured equal-quality alternative.
+
+## Why Slate?
+
+Long-horizon agentic work fails on context management, not model capability. Existing architectures each solve a piece of the problem and trade away the rest. Compaction is unpredictably lossy; naive subagents isolate context but hand back only a single response string; markdown plans go stale and get under-executed. Rigid task trees can't adapt to information discovered mid-task, and planner/executor stacks synchronize through compress-and-return boundaries that risk dropping critical state.
+
+Slate's answer is the **thread**: the orchestrator dispatches one bounded action at a time; the worker executes it and returns an **episode**. The orchestrator keeps the reactivity of a plain agent loop while gaining the context isolation, compaction, and parallelism that the single-context loop lacks.
+
+| Aspect | ReAct | Markdown plan | Task trees | RLM (Recursive Language Models) | Devin / Manus / Altera | Claude Code / Codex subagents | Slate |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Planning | implicit | file | explicit tree | REPL | planning agent | plan mode | implicit / adaptive — no upfront static plan |
+| Decomposition | none | none | direct tree | REPL functions | task-based | subagent delegation | implicit |
+| Synchronization | single thread | single thread | gated steps | REPL return | reduce & return | message passing | episodes |
+| Intermediate feedback | per step | per step | on task failure | on execution end | after compress | message passing | per episode |
+| Context isolation | none | none | per subtask | per subcall | subagent | subagent | per thread |
+| Context compaction | none | none | task-based | REPL slicing | subagent compress | compaction | episode compress |
+| Parallel execution | none | none | none | in REPL | Altera only | native | native |
+| Expressivity | high | high | low | high | medium | medium | high |
+| Adaptability | yes | if plan updated | no | limited — no mid-run course correction | yes | limited by message passing | yes |
+
+Characterizations of third-party systems reflect their publicly described designs at the time of writing. The taxonomy is adapted from the Random Labs technical report introducing the thread-weaving "Slate" architecture (its agent ships as the npm package `@randomlabs/slate`); ytdb-slate is an independent implementation of that architecture for pi.
+
+**Threads are not subagents:**
+
+- **Per-episode feedback.** Each thread executes one bounded action and hands control back. The orchestrator adapts after every episode — reactive like a ReAct loop — instead of firing off a subagent and hoping the result comes back usable.
+- **Compaction at a chosen boundary.** Compression happens at a predictable point — action completion — instead of mid-stream when context overflows. The compression itself is still LLM-performed and lossy, but the boundary is chosen, not forced.
+- **Episodes compose.** One thread's episode can seed another thread's context, so conclusions travel across the system by reference. Subagents pass back a single response string; episodes are durable, structured, reusable records.
+
+Full rationale: [`docs/design-principles.md`](docs/design-principles.md), shipped in the package — if this summary and that document disagree, the document wins.
+
+## Feature development workflow
+
+In orchestrator mode, Slate injects a track-based development workflow as doctrine — it is not optional; project configuration can extend it (`doctrineExtraPath`) but never replace it. The flow:
+
+1. **Research** — interactive exploration; a research log opens lazily when defined triggers fire (non-trivial decisions, surprises, risky invariants, session boundaries).
+2. **User design review** — the user approves the design direction before any machine review.
+3. **Adversarial review** — a fresh-context reviewer attacks the design pre-implementation; findings are triaged with the user.
+4. **Track split approval** — the user approves how the change splits into independently reviewable tracks.
+5. **Per-track loop** — implement → agent code review → fixes → mandatory user review → marker commit (an empty commit marking the track's boundary in history).
+6. **Delivery** — with draft-PR publishing enabled, the squash-merge is performed by the user; the agent never merges. With it disabled (the default), the change lands as a squashed commit that carries the workflow log's key content in its message.
+
+The workflow scales with change size: multi-track changes get the full flow, single-track changes skip the split and the marker commits, and trivial changes shrink the pre-implementation reviews to consent plus a micro-review (skippable with explicit user consent) — the agent code review and the mandatory user review still apply at every tier. Umbrella draft-PR publishing activates only when `workflow.draftPRs` is `true`.
+
+This summary is orientation only; the shipped docs listed below are normative.
 
 ## Install
 
@@ -24,12 +67,13 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `episodeModel` | string | newest available Anthropic Sonnet, else the worker's own model | Model (`provider/id`) used to compress a finished action into an episode. |
 | `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Tools available to worker threads (an empty list also falls back to the default). |
 | `maxConcurrent` | number | `4` | Maximum number of worker actions running concurrently (must be ≥ 1 — unenforced: a value of 0 or less silently hangs all dispatches). Excess dispatches wait in a queue; actions on the same thread always run in dispatch order. Default rationale: shipped `docs/design-principles.md` §5 (repo-local note). |
-| `pauseThresholdPercent` | number | `40` | Orchestrator context budget (percent, in `(0, 100]`) at which Slate auto-pauses and prepares a fresh-session handoff. |
+| `contextBudget` | number \| object | `256000` (Anthropic models: `400000`) | Absolute orchestrator context budget (tokens) at which Slate auto-pauses and prepares a fresh-session handoff — semantics, defaults, per-model overrides, and rationale in [`docs/context-budget.md`](docs/context-budget.md). |
 | `orchestratorPromptDocs` | string[] | `[]` | Project markdown files (paths relative to the project root) whose **contents** are appended to the orchestrator system prompt. |
 | `workerPromptDocs` | string[] | `[]` | Project markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable umbrella draft-PR publishing for tracks. |
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
+| `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):
 
@@ -38,12 +82,12 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "orchestratorModeDefault": true,
   "episodeModel": "anthropic/claude-sonnet-5",
   "maxConcurrent": 4,
-  "pauseThresholdPercent": 40,
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
-  "reviewPerspectivesPath": "docs/agents/review-perspectives.md"
+  "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
+  "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" }
 }
 ```
 
@@ -61,6 +105,8 @@ In orchestrator mode, Slate appends a short **doctrine** (a block of numbered ru
 - `docs/pr-publishing.md` — umbrella draft-PR publishing (cited only when `workflow.draftPRs` is `true`)
 - `docs/review-rules.md` — review discipline and finding rules
 - `docs/design-principles.md` — Slate's own design rationale
+- `docs/model-failover.md` — the opt-in `modelFailover` map (**reference documentation** — unlike the entries above it is not workflow doctrine and is not cited by the doctrine)
+- `docs/context-budget.md` — the orchestrator `contextBudget`: defaults, per-model overrides, the window clamp, and the pricing rationale (also **reference documentation**, not cited by the doctrine)
 
 Project-specific additions layer on top — they extend, not replace, the shipped doctrine — via two distinct mechanisms:
 

package/docs/context-budget.md

@@ -0,0 +1,176 @@
+# Orchestrator context budget
+
+`contextBudget` in the project's `slate.json` sets the ABSOLUTE
+token count at which Slate pauses the orchestrator and prepares the
+fresh-session handoff. It replaces the deprecated percentage knob.
+This document is reference documentation, not workflow doctrine.
+
+## Why absolute tokens, not a percentage
+
+pi's registry context windows differ per model: current Anthropic
+flagships are registered at 1,000,000 tokens; `claude-haiku-4-5`,
+`claude-opus-4-1`, and `claude-opus-4-5` (and their dated aliases)
+at 200,000; direct-OpenAI GPT-5.6 models default to 272,000 as a
+pricing-tier guard (the full 1.05M window is opt-in). One percentage
+cannot express a consistent orchestrator budget across those
+denominators — 40% of a flagship Claude is 400K tokens; 40% of a
+GPT-5.6 is 108.8K. An absolute budget says what it means on every
+model.
+
+## The OpenAI pricing cliff
+
+OpenAI long-context pricing is request-wide: a request whose total
+input exceeds 272K tokens bills the ENTIRE request at long-context
+rates. The multipliers are the tier pattern — 2× input, 1.5×
+output, 2× cache read, 2× cache write; the dollar figures are
+`gpt-5.6-sol`'s registered rates (absolute rates vary per model):
+input $5→$10/M, output $30→$45/M, cache read $0.5→$1/M, cache
+write $6.25→$12.5/M. In an agent loop the whole conversation is
+resent every turn, so once the boundary is
+crossed, every subsequent turn stays at those rates. The budget's
+job is to stop the orchestrator before that happens.
+
+## Defaults
+
+- **256,000** — the built-in default, ≈16K under the 272K boundary
+  so the pause turn and the handoff brief itself stay on
+  short-context rates.
+- **`anthropic/.*` → 400,000** — a built-in override for Anthropic
+  models, preserving continuity with the previous 40%-of-1M default
+  on flagship Claude.
+
+## Configuration (`.pi/slate.json`)
+
+`contextBudget` lives in `.pi/slate.json` and, like the rest of
+that file, is honored **only in trusted projects** — untrusted
+projects load no project config, so the built-in defaults apply. It
+accepts a bare positive integer — shorthand for `{"tokens": N}` —
+or an object:
+
+```json
+{
+  "contextBudget": {
+    "tokens": 256000,
+    "overrides": [
+      { "match": "openai/gpt-5\\.6-.*", "tokens": 240000 },
+      { "match": "anthropic/.*", "tokens": 400000 }
+    ]
+  }
+}
+```
+
+Each override's `match` is an anchored regex tested against the full
+`provider/id` spec. The FIRST matching override wins, in config
+order. Precedence overall: user override → user scalar (`tokens`) →
+built-in `anthropic/.*` rule → built-in default. Invalid input is
+warned about and never silently changes behavior; what applies
+afterwards depends on where the damage is:
+
+- An invalid WHOLE value (bad number, wrong type) is treated as if
+  `contextBudget` were unset: legacy percent mode if
+  `pauseThresholdPercent` is configured, built-in budget defaults
+  otherwise.
+- An invalid `tokens` inside an otherwise valid object is dropped —
+  the object still opts into budget mode, so the built-in defaults
+  fill the scalar layer.
+- An invalid override entry is skipped — the next layer of the
+  precedence chain applies.
+
+Legacy note: `pauseThresholdPercent` is deprecated; it keeps its
+exact old semantics only when it is set AND `contextBudget` is
+absent or entirely invalid — an invalid budget sanitizes to absent
+and never disables the percent. A PARTIALLY invalid object (e.g.
+`{"tokens": -1}`) remains a valid budget object: budget mode with
+built-in defaults, percent ignored.
+
+## The clamp
+
+The configured budget is clamped against the model's registry
+context window:
+
+```
+effective = min(budget,
+                max(contextWindow − compactionReserve − 32768,
+                    ceil(contextWindow / 2)))
+```
+
+`compactionReserve` comes from pi's compaction settings
+(`compaction.reserveTokens`, default 16,384).
+
+| Context window | Effective budget |
+| --- | --- |
+| 200K | 150,848 |
+| 272K | 222,848 |
+| 400K | 256,000 (default binds) |
+| 1M (Anthropic) | 400,000 |
+
+Rationale: the clamp guarantees the pause fires before pi's
+auto-compaction and leaves room to write the handoff brief; the
+half-window floor keeps small-window models usable.
+
+## Compaction policy
+
+In orchestrator mode, for budget-driven configs only: a
+threshold-triggered compaction that arrives while the session is
+unpaused is cancelled and converted into the Slate pause — the
+handoff, not lossy compaction, handles the full context. Once
+paused, threshold compactions pass through as an escape valve.
+Overflow-recovery compaction and manual `/compact` are never
+touched.
+
+## Using GPT-5.6's full 1.05M window
+
+Two deliberate steps. First, raise the registry window in
+`~/.pi/agent/models.json` (pi's custom-models file — NOT
+`settings.json`, where this block is silently ignored):
+
+```json
+{
+  "providers": {
+    "openai": {
+      "modelOverrides": {
+        "gpt-5.6-sol": { "contextWindow": 1050000 }
+      }
+    }
+  }
+}
+```
+
+(repeat for `gpt-5.6-terra` / `gpt-5.6-luna`). Second, raise the
+Slate budget with an override in `.pi/slate.json` — the full nested
+form matters: a bare `{"match": …, "tokens": …}` pasted as the
+`contextBudget` value becomes a global scalar with `match` silently
+dropped:
+
+```json
+{
+  "contextBudget": {
+    "overrides": [
+      { "match": "openai/gpt-5\\.6-.*", "tokens": 900000 }
+    ]
+  }
+}
+```
+
+WARNING: beyond 272K total input every request bills at the
+long-context rates listed above.
+
+## Accepted limitations
+
+- On models with a 272K pricing tier and a larger registry window
+  (`gpt-5.4-pro`, `gpt-5.5-pro`, GPT-5.6 after the opt-in above), a
+  >16K single-turn overshoot near the 256K default can bill the
+  final turns at long-context rates — override to 240,000 to widen
+  the margin.
+- The 32K margin in the clamp covers typical turns, not extreme
+  single-turn ingestion (several parallel large file reads) — hand
+  off earlier or set a lower override when running tier-priced
+  models hard.
+- The pause-fires-before-compaction guarantee holds for single-turn
+  ingestion under 32,768 tokens — and only where the margin branch
+  of the clamp binds (context window ≥ ~98K with the default
+  16,384-token reserve); on smaller, floor-clamped windows the
+  pre-compaction margin is narrower. Beyond the margin a pass-through
+  compaction can land in the same cycle and the handoff brief is
+  written from compacted context — episodes and thread state survive
+  on disk, so handoff still functions.

package/docs/model-failover.md

@@ -0,0 +1,153 @@
+# Model failover
+
+Opt-in high availability for model outages. `modelFailover` in the
+project's `slate.json` maps a model to an equal-quality alternative;
+when a Slate action fails because of a model API failure, the
+affected site retries ONCE on the mapped model, at code level,
+without user intervention (in worker and orchestrator sessions only
+after pi's own retries are exhausted — see below). The map is empty
+by default: with no entries the feature is off and failures surface
+exactly as before. This document is reference documentation, not
+workflow doctrine.
+
+## Configuration
+
+`modelFailover` lives in `.pi/slate.json` and, like the rest of that
+file, is honored **only in trusted projects**. Both sides of every
+entry are full model specs in `provider/id` form:
+
+```json
+{
+  "modelFailover": {
+    "anthropic/claude-sonnet-5": "openai/gpt-5.2",
+    "openai/gpt-5.2": "anthropic/claude-sonnet-5",
+    "anthropic/claude-haiku-4": "google/gemini-3-flash"
+  }
+}
+```
+
+Validation rules:
+
+- Key and value must both have the `provider/id` shape.
+- Key and value must differ (mapping a model to itself is invalid).
+- Invalid entries are dropped with a warning; valid entries in the
+  same map still apply.
+
+Mutual entries (A→B and B→A, as above) are fine — see the single-hop
+rule below.
+
+The map is read ONCE, at session start. Editing `slate.json`
+mid-session — e.g. adding a mapping in the middle of an outage —
+takes effect only in a NEW pi session.
+
+Configuring the map is the whole opt-in: in a trusted project with a
+`modelFailover` entry, ORCHESTRATOR failover is active in every pi
+session regardless of whether Slate's orchestrator mode is on — a
+matching model failure switches the session's model (and pi's global
+default, see the caveats) even if you never use threads.
+
+## When failover fires
+
+A failure is eligible for failover when it is either:
+
+- an error stop reason that is NOT a context overflow, or
+- a preflight failure: a worker prompt that throws is confirmed by
+  re-running the auth check on the current model (a transient throw
+  with healthy credentials does not switch models); the episode
+  compressor treats any thrown attempt as eligible.
+
+pi's own retry settings (`retry.enabled` / `retry.maxRetries`, with
+exponential backoff) run first inside worker and orchestrator
+sessions — there, failover fires only after pi gives up on the
+original model. Quota and billing errors are non-retryable in pi, so
+those fail over promptly. The episode compressor is a single direct
+API call with no retry loop of its own, so its mapped retry fires on
+the first failure.
+
+What NEVER triggers failover:
+
+- **Aborts** — a user abort is not a model failure.
+- **Context overflow** — a different model does not fix an oversized
+  prompt; the existing overflow handling applies unchanged.
+- **Worker task-level failures** — the model answered but the action's
+  outcome was bad; those surface as failed episodes, as before.
+
+Before any switch, the mapped model is resolved against pi's model
+registry and auth-checked. If it is unknown or unauthenticated, no
+switch happens and the original failure stands. The map is applied a
+single hop per failure — it is never chained, so cycles (A→B, B→A)
+cannot loop.
+
+## Per-site behavior
+
+Failover applies at three sites:
+
+- **Worker threads.** The live worker session switches to the mapped
+  model and the failed action is re-prompted once with a continuation
+  nudge. The transcript is preserved; usage and cost accumulate across
+  both attempts. The thread stays on the mapped model while its
+  session is live and returns to its configured model when the session
+  is reopened (e.g. after a pi restart). The `threads` listing marks a
+  switched live session as `model=A ⇒B (live)` — the marker means a
+  live failover switch happened (it is not a value comparison) and
+  disappears when the session is reopened.
+- **Episode compression.** The compression call is retried once with
+  the mapped compressor model — only if it is distinct from the
+  original, resolvable, and authed. If the retry also fails, the
+  uncompressed fallback applies exactly as today. Compression cost
+  accumulates across both attempts — a failed first attempt may still
+  bill.
+- **Orchestrator.** Once pi's retries are exhausted, Slate switches
+  the session to the mapped model and automatically re-issues the
+  failed turn. A one-shot guard prevents loops; it re-arms only when a
+  run settles without a model error (an abort also re-arms it) or on a
+  genuine new user prompt. The session STAYS on the mapped model
+  afterwards. Failover runs even while Slate is paused for handoff, so
+  the handoff brief is written by a working model.
+
+## What you'll see when failover fires
+
+- **Orchestrator:** a `slate: model failover <old> ⇒ <new> — retrying
+  the failed turn` warning notification, then a visible `[slate]`
+  steer message in the conversation instructing the model to re-issue
+  the failed action. A skipped or failed switch (no API key, auth
+  throw) also notifies, and the original failure stands.
+- **Worker threads:** a `⚠ failover <old> ⇒ <new>` line in the thread
+  tool's progress output; if the retry also fails, the episode's
+  failure diagnostics carry a `(failover to <new> also failed)`
+  suffix. The `threads` listing shows the live-model marker while the
+  switched session is live.
+- **Episode compression:** no live signal — the episode header's
+  `compressor:` line names whichever model actually produced the
+  episode.
+
+## Caveats & accepted limitations
+
+- Orchestrator failover persists the mapped model as the user's
+  **global default model** — that is pi's `setModel` semantics. Switch
+  back with `/model` once the outage is over.
+- Worker sessions use a read-only settings view, so worker failover
+  persists nothing.
+- Orchestrator **preflight** auth failures (e.g. an OAuth token that
+  expired before any run starts) bypass failover — pi surfaces the
+  error itself; recover manually with `/model`.
+- A worker retry holds its concurrency slot across both attempts.
+- Stickiness is per-thread only: each NEW thread still starts on its
+  configured/default model during an outage.
+- Cancelling a run while pi is sleeping between its internal retry
+  attempts is not reliably distinguishable from pi exhausting those
+  retries — pi emits no extension-visible signal for that cancel.
+  Slate mitigates by counting consecutive retryable errors against
+  pi's retry settings, which blocks failover in the normal cancel
+  case; a narrow residual window remains (e.g. retry settings changed
+  mid-session) where a cancelled run could still fail over.
+
+## Troubleshooting
+
+Failover looked eligible but was skipped: check the mapped model. It
+must be a well-formed `provider/id` spec, present in pi's model
+registry, and pass its auth check at failure time — otherwise the
+original failure stands (malformed entries are additionally dropped
+with a warning when the config is read). If you edited the map
+mid-session, remember it is read only at session start — start a new
+pi session for the change to apply.

package/extension/episodes.ts

@@ -19,6 +19,9 @@ import {
 	serializeConversation,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { isFailoverCandidate, resolveMappedModel } from "./failover.ts";
+
+type CompressorModel = NonNullable<ReturnType<ExtensionContext["modelRegistry"]["find"]>>;
 
 const MAX_TRANSCRIPT_CHARS = 300_000;
 const COMPRESSOR_MAX_TOKENS = 4096;
@@ -88,6 +91,7 @@ export interface CompressEpisodeOptions {
 	messages: unknown[]; // AgentMessages produced during this action
 	workerModel?: { provider: string; id: string };
 	configuredModel?: string;
+	modelFailover?: Record<string, string>; // "provider/id" → "provider/id" retry map (single hop, one retry)
 	signal?: AbortSignal;
 }
 
@@ -98,6 +102,71 @@ export interface CompressedEpisode {
 	costUsd: number; // USD cost of the compression LLM call (0 on fallback)
 }
 
+type CompressionAttempt =
+	| { kind: "ok"; body: string; costUsd: number }
+	| { kind: "failed"; costUsd: number; retriable: boolean }
+	| { kind: "aborted"; costUsd: number };
+
+/**
+ * ONE compression attempt on ONE model. Failure classification (AF7/AF11):
+ * - stopReason "error" → failed; treated as failed even when partial text came
+ *   back (a half-written episode is worse than the uncompressed fallback);
+ *   retriable unless it is a context overflow — a mapped model cannot shrink
+ *   the prompt (isFailoverCandidate).
+ * - stopReason "aborted" (or a throw with the signal already aborted) →
+ *   aborted; NEVER retried — cancellation must not spend a mapped attempt.
+ * - missing auth or a thrown preflight error → failed & retriable (state-based
+ *   classification, AF10: the mapped model may be authed when this one isn't).
+ * - empty text on a clean stop → failed, not retriable (nothing suggests the
+ *   mapped model would answer differently).
+ */
+async function attemptCompression(
+	ctx: ExtensionContext,
+	model: CompressorModel,
+	promptText: string,
+	signal: AbortSignal | undefined,
+): Promise<CompressionAttempt> {
+	let costUsd = 0;
+	try {
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok || !auth.apiKey) return { kind: "failed", costUsd, retriable: true };
+		const response = await complete(
+			model,
+			{
+				messages: [
+					{
+						role: "user" as const,
+						content: [{ type: "text" as const, text: promptText }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				env: auth.env,
+				maxTokens: COMPRESSOR_MAX_TOKENS,
+				signal,
+			},
+		);
+		costUsd = response.usage?.cost?.total ?? 0;
+		if (response.stopReason === "aborted") return { kind: "aborted", costUsd };
+		if (response.stopReason === "error") {
+			return { kind: "failed", costUsd, retriable: isFailoverCandidate(response, model.contextWindow) };
+		}
+		const text = response.content
+			.filter((c: { type: string }): c is { type: "text"; text: string } => c.type === "text")
+			.map((c: { text: string }) => c.text)
+			.join("\n")
+			.trim();
+		if (!text) return { kind: "failed", costUsd, retriable: false };
+		return { kind: "ok", body: text, costUsd };
+	} catch {
+		if (signal?.aborted) return { kind: "aborted", costUsd };
+		return { kind: "failed", costUsd, retriable: true };
+	}
+}
+
 function lastAssistantText(messages: unknown[]): string {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const m = messages[i] as { role?: string; content?: Array<{ type: string; text?: string }> };
@@ -126,43 +195,44 @@ export async function compressEpisode(opts: CompressEpisodeOptions): Promise<Com
 	try {
 		const model = await resolveCompressorModel(ctx, opts.configuredModel, opts.workerModel);
 		if (model) {
-			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-			if (auth.ok && auth.apiKey) {
-				let transcript = serializeConversation(convertToLlm(opts.messages as never));
-				if (transcript.length > MAX_TRANSCRIPT_CHARS) {
-					transcript = `[transcript head truncated]\n...${transcript.slice(-MAX_TRANSCRIPT_CHARS)}`;
-				}
-				if (opts.diagnostics) {
-					transcript += `\n\n[dispatch diagnostics: ${opts.diagnostics}]`;
-				}
-				const response = await complete(
-					model,
-					{
-						messages: [
-							{
-								role: "user" as const,
-								content: [{ type: "text" as const, text: compressorPrompt(opts.task, transcript) }],
-								timestamp: Date.now(),
-							},
-						],
-					},
-					{
-						apiKey: auth.apiKey,
-						headers: auth.headers,
-						env: auth.env,
-						maxTokens: COMPRESSOR_MAX_TOKENS,
-						signal: opts.signal,
-					},
-				);
-				costUsd = response.usage?.cost?.total ?? 0;
-				const text = response.content
-					.filter((c: { type: string }): c is { type: "text"; text: string } => c.type === "text")
-					.map((c: { text: string }) => c.text)
-					.join("\n")
-					.trim();
-				if (text) {
-					body = text;
-					compressor = `${model.provider}/${model.id}`;
+			let transcript = serializeConversation(convertToLlm(opts.messages as never));
+			if (transcript.length > MAX_TRANSCRIPT_CHARS) {
+				transcript = `[transcript head truncated]\n...${transcript.slice(-MAX_TRANSCRIPT_CHARS)}`;
+			}
+			if (opts.diagnostics) {
+				transcript += `\n\n[dispatch diagnostics: ${opts.diagnostics}]`;
+			}
+			const promptText = compressorPrompt(opts.task, transcript);
+
+			const first = await attemptCompression(ctx, model, promptText, opts.signal);
+			// Cost ACCUMULATES across attempts — a failed first attempt may still bill.
+			costUsd += first.costUsd;
+			if (first.kind === "ok") {
+				body = first.body;
+				compressor = `${model.provider}/${model.id}`;
+			} else if (first.kind === "failed" && first.retriable && !opts.signal?.aborted) {
+				// Model failover — single hop, at most ONCE: retry iff the mapped
+				// model resolves, is authed, and differs from the attempt-1 model.
+				const mapped = await resolveMappedModel(ctx, opts.modelFailover ?? {}, model.provider, model.id);
+				// CQ4: resolveMappedModel keeps the looser auth.ok semantics shared
+				// with the setModel-based sites, but attemptCompression additionally
+				// requires an explicit apiKey — pre-check it so an env/header-auth
+				// mapped model does not buy a guaranteed-futile retry.
+				const mappedAuth = mapped ? await ctx.modelRegistry.getApiKeyAndHeaders(mapped) : undefined;
+				if (
+					mapped &&
+					mappedAuth?.ok &&
+					mappedAuth.apiKey &&
+					(mapped.provider !== model.provider || mapped.id !== model.id)
+				) {
+					const second = await attemptCompression(ctx, mapped, promptText, opts.signal);
+					costUsd += second.costUsd;
+					if (second.kind === "ok") {
+						body = second.body;
+						// The header's compressor line shows whichever model actually
+						// produced the episode — that is where failover stays visible.
+						compressor = `${mapped.provider}/${mapped.id}`;
+					}
 				}
 			}
 		}