feat(provider-switch): switch agents off an exhausted provider without a source-side summarization turn

[Juliusolsson05]

Problem

The bulk provider switch exists for one moment: a subscription window is
exhausted and every agent on that provider needs to move. Until this branch, the
transaction asked the source provider for a live turn in most of those cases —
and a provider that is out of quota cannot answer.

Two shapes forced the source turn, and the Stage 0 census
(docs/decomposition/evidence/provider-switch/census.md, 3,328 local
transcripts and 7.15 GB, no sampling) says how common they are:

• Any Codex session that has ever compacted. A modern rollout persists
  type=compacted with a provider-encrypted item, which no client can read, so
  the planner returned requires-portable-handoff and asked the live Codex
  session to write a plaintext handoff. 146 of the newest 300 local rollouts
  carry such a record. But a Codex rollout usually keeps its pre-compaction
  records on disk in plaintext: of 230 single-compaction rollouts, 211
  (91.7 %) keep a median 74.3 % of their characters ahead of the compaction.
  For those the history the encrypted summary describes was never gone. (The
  remaining 18 have nothing before the compaction at all; see "Carry the raw
  history" for what the switch says about them.)
• Any conversation over the target's budget. The planner returned
  requires-compaction, and the host delivered /compact to the source — which
  destroys the history the switch was trying to rescue before the request
  fails. 91 local Claude transcripts exceed the 581,400-character Codex budget.

The cost of that design when the source is exhausted: 300 seconds of waiting per
agent, one native dialog per agent, and nothing moved.

A second, sharper failure hid inside the same path (#820). Claude Code's own
compaction only rejects a summary that starts with API Error, so a usage limit
hit during /compact can be persisted as the summary — behind the standard
"This session is being continued from a previous conversation…" preamble, which
makes it look entirely healthy to a fingerprint-and-availability check. Accepting
that carrier switched the pane onto a transcript whose history had been replaced
by "You've hit your monthly spend limit".

Implemented behavior

Parser (agent-transcript-parser, merged as
#25,
main 9c99db00)

• planConversationContext(..., { allowSourceTurns }). It defaults to true,
  keeping all four existing outcomes and their ordering for every existing
  caller. (Not byte for byte: a conversation whose latest carrier is a Claude
  usage-limit message used to classify portable and be sliced at, discarding
  every pre-limit turn. It is no longer sliced at on either path — a bug(provider-switch): compaction wait may accept a Claude rate-limit message as the portable summary #820 fix
  that reaches the default-true path too, and the only behaviour a pre-existing
  caller can observe changing.) With false
  the outcomes are ready, existing-compaction, raw-history (the unreadable
  carrier is stripped and the plaintext records it claimed to replace are
  carried) and shrunk, or a thrown ConversationUnfittableError. Six outcomes
  total, and the two that cost a live source turn are unreachable on the new
  path.
• operations/shrink.ts, a deterministic ladder with one consumer (the
  planner): strip compactions the target cannot read → clear tool results oldest
  first, with a net-savings floor and a placeholder quoting the raw length →
  trim long tool-call inputs, object-preserving, capped on the serialized length
  → drop the oldest complete turns at a safe resume boundary behind a
  budget-aware marker that indexes the dropped prompts. Every rung reports what
  it removed (ShrinkReport).
• Hazard fixes: compactionAvailability returns rejected for a Claude carrier
  containing a rate-limit line at any line start (the match is line-start, not
  startsWith, because the persisted record is wrapped in a ~150-character
  continuation preamble; it is gated on the Claude provider). Claude assistant
  records with isApiErrorMessage: true decode to opaque /
  nativeType: 'api_error' instead of assistant text.

codex-headless (merged as
#47, main
96c5c146) — a 429 whose body says usage_limit_reached is published as its own
api_error errorType carrying resetsAt, limitId and limitName, instead of
falling through to retryable; rate-limit response headers are allowlisted onto
the proxy response event.

Host transaction — SwitchProviderRequest.contextPolicy { allowSourceTurns, compactOnArrival }, defaulting to { false, false }. On
that path runtime.compactSource is never reachable. The result reports
strategy: 'native' | 'raw' | 'shrunk' plus a one-line shrinkSummary, and a
new shrinking progress phase carries the same line while the switch runs.
overflowPolicy: 'truncate' now routes to the ladder (a strict upgrade over the
whole-turn fitter it replaces, which refused outright when an encrypted Codex
carrier was in the way); fail keeps its legacy branch unchanged. The opt-in
source path is otherwise the old transaction, plus three fast-fails: a
rejected carrier persisted by the source's own /compact, an api_error
record after the /compact baseline line, and — new in the review pass — an
abort before planning when the source's latest carrier is already rejected.
That last one closes the #820 hazard on the opt-in path specifically: nothing
strips the carrier there, the planner returns ready with it still inside, and
the Codex projector demotes any non-empty summary to a developer handoff without
consulting availability, so the limit text would reach the target framed as its
prior context.

Arrival compaction — new session:compact-after-switch IPC over
providerSwitch/compactOnArrival.ts, with its own in-flight lock keyed on the
new session id. One 30-second wait with two exits (a visible
claude.resume-prompt is answered with selectedIndex Ups + Enter; a ready
input with no prompt gets /compact), then the same compaction wait pointed at
the target. Failure is { ok: false, message } with arrival-specific wording and
is never thrown — the pane is already live with its full history. The renderer
fires it fire-and-forget, only for Claude targets and only when the policy asked.

Exhaustion signal — UsageLimitRow.scope
(all-models | model-family | unknown), classified in the normalizers:
Claude session / weekly_all → all-models, weekly_scoped → model-family;
the Codex main rate_limit windows → all-models, additional_rate_limits
entries → model-family. src/shared/usage/exhaustion.ts derives
{ exhausted, scope, resetsAt, label } purely from a snapshot at ≥ 100 %, with
all-models reported ahead of model-family. Live per-pane signal
SessionRuntime.limitHit, set from an appended Claude rate_limit record using
the record's own timestamp (a resumed pane replays its tail through the same
channel; Date.now() would date a days-old episode as current) or a Codex
usage_limit_reached semantic error; cleared on turn_completed and on
turn_started, deliberately not on turn_stopped. The turn_started clear is
a review fix: a pane that auto-continues once its window resets keeps its
original turnStartedAt (the phase machine stamps that field only when it is
null), so the stale timestamp stays older than limitHit.at and the pane read as
limit-idle for the whole of a live answer — the switch modal would have labelled
a working pane idle and a switch would have killed the turn. A turn the provider
accepted is the earliest honest proof the episode is over, and a fresh 429 re-arms
the signal with a newer timestamp. isLimitIdle widens the switch guard with it,
on the belief that both providers keep processActive true while a window is
exhausted — that belief is unrecorded (limitation 1 below), which is why the
predicate is written so it can only widen the guard, never narrow it.

Bulk modal — banner per exhausted provider with a relative reset ("resets in
2h"); direction defaults to the single exhausted source; "compact on arrival"
offered for Claude targets, default on above 150,000 estimated characters in the
batch's largest pane; "compact on source first" default off and disabled while
the source is exhausted; a "switch model instead" row for Claude family-scoped
limits, suppressed when the exhausted family is the one the command would land
on; one arm-and-confirm per batch instead of a native dialog per agent; strategy
counts in the batch summary (the single-pane switch is what shows a strategy in
the pane toast — the bulk path only tallies). Usage polling is
gated on open (the modal is a permanently mounted surface, and its previous
unconditional hook call polled the usage IPC every 60 s for the life of the app).

Design decisions and tradeoffs

Carry the raw history instead of asking for a summary. The encrypted Codex
carrier is the only opaque part of a compacted rollout, and OpenAI's server —
not the client — decrypts it. The plaintext it summarizes is usually still in the
same file. Stripping the carrier and carrying those records costs nothing, works
with the provider offline, and the census says it applies to 211 of 230
single-compaction rollouts (91.7 %), which keep a median 74.3 % of their
characters ahead of the compaction. The tradeoff is a larger projection, which is
what arrival compaction exists to absorb.

The other 7.8 % matter and are now disclosed. 18 of 230 rollouts have zero
characters before the compaction — a rollout that begins at one, and a session
resumed into a fresh rollout file both look like that. There the stripped carrier
was the only account of everything prior and nothing on disk replaces it, so
raw would otherwise report "nothing was lost" in exactly the case where the
most was. switchProvider detects the shape (no non-opaque entry ahead of the
first stripped carrier, after mirroring the planner's own slice at the latest
portable compaction) and fills shrinkSummary with a line the pane toast already
knows how to show. The switch is still the right outcome — the alternative is a
source turn an exhausted source cannot spend — and keeping that earlier history
while the source is alive is precisely what the opt-in source handoff is for.

A deterministic ladder, not a model call. Both vendors ship exactly this:
Anthropic's clear_tool_uses context editing, and OpenAI's
externalAgentConfig/import, which narrates tool calls and truncates results.
Ordering rungs by what the loss costs the model means a conversation 5 % over
budget loses a few old tool outputs rather than a third of its history. The
alternative — a summarization prompt — was ruled out by the user twice over: no
speculative pre-summarization, and no custom summarization prompt as a product
path.

Developer messages are retained by default, and the planner decides. The
ladder is provider-neutral by construction and must stay that way, but somebody
has to know what the target persists. The Claude projector drops developer and
system messages outright, so retaining them for a Claude target would charge the
budget for content deleted on arrival and could refuse a switch to protect
messages the target throws away; Codex preserves the role verbatim and OpenCode
demotes it to labeled user context. So keepDeveloperMessages defaults to
targetProvider !== 'claude' in planConversationContext. That is a hard-coded
provider string in a planner that otherwise derives everything from
compactionPortability — the durable shape is a capability flag on the projector
profile, and it was not built because no projector exposes capabilities today
and inventing that surface here is out of scope. If a third target that discards
the role appears, build the flag rather than adding a second comparison.

Compaction happens on arrival, on the target's quota. The target's own
native compaction is the only summarizer, and it runs after the pane is live, so
its failure cannot fail a committed transaction. That is also why it is a
separate module and a separate IPC rather than a tail on switchProvider:
folding it in would either move pane replacement before the transcript write or
give the transaction a step whose failure must not fail it.

The source path survives as an opt-in. Some users will prefer a native
summary over a larger raw history when the source is alive. It keeps its
existing failure list, gains the two hazard checks, and its checkbox is disabled
while the source is exhausted, because that combination spends quota the
provider has already refused.

Host tests derive budgets from each fixture's own decoded size. Census caveat
1: the committed fixtures are redacted to 0.3–2.4 % of real byte totals, so a
literal 581,400-character budget in a test would assert against the redactor
rather than against the ladder. Relative budgets keep the tests reacting to real
transcript shape.

Repository plumbing

• Submodule pointers moved to the merged package mains (9c99db00,
  96c5c146). No lockfile resync was needed, and that is checked rather
  than assumed: git diff <old>..<new> -- package.json is empty in both
  submodules (parser 2fdfc09a..9c99db00, codex-headless 4ff1fd91..96c5c146).
  file: deps embed the package tree in package-lock.json, so a submodule bump
  that changes a package's own package.json breaks npm ci in CI before tsc
  ever runs; neither of these does.
• The vendored Codex checkout moved to upstream main (7754c04a): the design
  cites its current remote compaction, rollout persistence and external-agent
  import code, and the April checkout predates all three.
• package-lock.json is not in this branch. A lock-only resync produced a
  512-line diff consisting entirely of nested vitest/@esbuild optional-arch
  entries; the identical diff reproduces on main with no submodule involvement,
  so it is local npm-version churn, not this branch's, and was reverted.

Linked issues

• Fixes feat(provider-switch): switch agents off an exhausted provider without a source-side summarization turn #821 — with two acceptance criteria explicitly deferred to test(provider-switch): run the live probe for quota-independent switching #833 (see
  Known limitations 10). feat(provider-switch): switch agents off an exhausted provider without a source-side summarization turn #821's body carries an "Amended 2026-09-07" note saying
  the same thing, and a comment on it explains why.
• Fixes bug(provider-switch): compaction wait may accept a Claude rate-limit message as the portable summary #820
• Refs Bulk provider switch with remembered last batch (usage-limit escape) #360 perf(provider-switch): compaction wait pins full conversation copies and re-decodes the rollout every 250 ms #720 feat(provider-switch): choose the destination from a provider picker #756
• #833 — the Stage 7
  live probe, deferred out of this PR by the user's decision on 2026-09-07.
• agent-transcript-parser#26
  — open follow-up found in review: the projectors and
  fitConversationToCharacterBudget's previousSummary are availability-blind,
  and conversationAfterLatestPortableCompaction returns the whole conversation
  when the latest carrier is rejected/incomplete while an earlier portable
  one exists. Defended host-side by this PR; the durable fix is in the parser.
• agent-transcript-parser#25 — merged, main 9c99db00 (closes parser#24)
• codex-headless#47 — merged, main 96c5c146 (closes codex-headless#46)
• codex-headless#48 — open follow-up found while writing proxy: filter Claude Code title-gen / sidecar calls by request shape #47: a bodyless non-2xx /responses reply never reaches classification, so a bodyless 429 publishes no api_error at all and is reaped as a timeout.

Tests and verification

Run on the branch at the full-gate commit, Node 24.14.1, macOS. These are the
gate's own numbers, not a summary of them.

Command	Result
npm run typecheck	exit 0 (re-run once with an explicit echo EXIT_CODE=$? to confirm the silent tsc -b really was clean)
npx tsc -p tsconfig.node.json --pretty false	exit 0, no diagnostics
npx tsc -p tsconfig.web.json --pretty false	exit 0, no diagnostics
npm run check:keybindings	exit 0 — 42 command binding sets, 15 reserved interactions, 5 approved overlaps
npm run test:package	exit 0 — full electron-vite build + verify-build-output.mjs ("Application build contains every required entry point")
npm test (all projects)	2,840 passed, 12 skipped, 7 failed of 2,859 tests; 414 of 420 files passed; 475 s

Both tsc projects are run separately and deliberately: electron-vite build
and vitest do not type-check, and the web project caught a 'shrinking' union
gap that a node-only run had missed mid-branch.

The seven failures, attributed one by one. None is a regression from this
branch, and that was checked rather than asserted — git diff fcb8d0ca..HEAD for
each failing path and its directory is empty, and every one was re-run in
isolation on both this branch and main:

• 2 are known pre-existing: lazy-prose/index.renderer.test.tsx (a
  dynamic-import timeout under full-suite parallelism, issue bug(testing): lazy-prose renderer test times out at 5s under load #700) and
  imageAttachment.test.ts (a corpus invariant citing a local ~/.claude
  transcript that has since been deleted on this machine; it fails on main too).
• 2 are transient, and did not reproduce when re-run:
  WorkflowViewSelector.renderer.test.tsx "bounds history detail reads…" and
  store.test.ts "starts in the command list", both 5 s timeouts.
• 3 reproduced only under load and pass deterministically in isolation on
  both checkouts: store.test.ts × 2 (8/8 twice on branch and on main),
  store.performance.test.ts (12/12 twice on each, beforeAll nowhere near its
  10 s budget), WebSocketSessionFeed.integration.test.ts (13/13 twice on each,
  including the "backfills a previously loaded session after overflow…" case that
  had returned an empty array). All three are in src/renderer/src/app-state/ or
  src/remote-client/, which this branch does not touch at all.

Focused re-runs for the review-fix commit (its diff is host + renderer +
docs, so the full suite was not re-run):

Command	Result
NODE_ENV=test npx vitest run --project unit src/main/providerSwitch	6 files, 59 passed
NODE_ENV=test npx vitest run --project renderer providerSwitchCore.renderer.test.ts useIpcSubscriptions.renderer.test.tsx	2 files, 26 passed
NODE_ENV=test npx vitest run --project renderer src/renderer/src/workspace/hook/actions	11 files, 57 passed
NODE_ENV=test npx vitest run --project unit src/renderer/.../hook/actions src/main/usage src/shared	15 files, 75 passed
npx tsc -p tsconfig.node.json --pretty false	exit 0
npx tsc -p tsconfig.web.json --pretty false	exit 0

New coverage worth naming: the shrink ladder and planner outcomes against
decoded Stage 0 fixtures (never invented literals); switchProvider cases
asserting compactSource is not called on the default path, that the
compaction-first fixture reports its disclosure line while the majority-shape one
reports shrinkSummary: null, and that the opt-in path aborts on a rejected
carrier before projecting; compactBeforeSwitch rejected-carrier and
api-error-after-baseline cases; compactOnArrival on both branches with a fake
SessionManager; exhaustion over the real usage payloads already in the suite;
both limitHit reducers in the injected-feed harness, including that a replayed
burst does not re-arm the guard and that a turn the provider accepts after a
reset clears it; the renderer's refusal to start a second switch on a pane whose
arrival compaction is still running; and the modal's policy state machine.

The Stage 7 live probe was NOT run — deferred to
#833 by the user's
decision on 2026-09-07. No projected transcript was resumed through a real Claude
or Codex CLI on this branch. That leaves four questions open that only the probe
answers: whether a shrunk projection's real token count matches the 2.5
characters-per-token estimate closely enough to stay under Codex's 90 %
auto-compact limit (Unknown 2); whether a live Codex tolerates a
custom_tool_call_output whose output is a placeholder or treats it as an error
(Unknown 3); whether a 1M Claude target refuses arrival compaction on this
account with "Usage credits required for 1M context" (Unknown 6); and what
OpenCode's import size limits are for shrunk envelopes (Unknown 7). Structural
projection tests prove the shapes are legal; they cannot prove a provider
includes translated history in its next model request.

Known limitations and follow-ups

1. Unknown 1 is unrecorded. Nobody captured a Claude "Usage limit reached ·
   continuing automatically" screen, so nothing proves processActive stays true
   under the banner. isLimitIdle is therefore defensive: it can only widen the
   guard, never narrow it, so being wrong costs nothing.
2. Restored-pane gap, deliberately shipped. A restored pane whose replayed
   tail contains a genuine rate-limit carrier reads as limit-idle, because
   turnStartedAt is null there. That is the intended reading of "no turn to
   protect", and the guard is only consulted when something else already says the
   pane is busy. If it proves wrong, the fix belongs in isLimitIdle.
3. The 30-second arrival readiness deadline and the ladder's
   keepRecentTurns: 3 / maxInputChars: 8,000 are estimates, not
   measurements. The census measured no per-turn size distribution and no
   tool-call input percentiles, and rung 3 never fired on realistic data — it is
   exercised only by its own unit test with an explicit small cap.
4. The api-error fast-fail on the Codex and OpenCode handoff waits is inert in
   production. Only the Claude decoder classifies opaque/api_error, so a
   Codex limit during a handoff turn still ends in the 300-second timeout. The
   code is the right shape and starts working the moment those decoders classify
   error records; its tests hand-build the entry and say so.
5. Arrival compaction reads the resume prompt through the neutral shape.
   compactOnArrival originally imported type ResumePromptState from
   claude-code-headless, which would have been the first such import in
   src/main — Plug-and-play provider architecture: modularize and standardize all provider implementations #394 phase 2a deliberately removed them all (see the WHY block at
   the top of sessionManager.ts). It now reads AgentResumePromptState from
   @shared/types/session.ts, which is field-identical and is the shape
   SessionManager actually emits, so the module's declaration matches its real
   source. Nothing about the runtime behaviour changed.
6. Arrival compaction has an entry guard but no retry. A second call while
   one is running returns { ok: false, message: 'Arrival compaction already running.' }; a pane that was merely slow past 30 s is reported as a failure
   and the user runs /compact by hand.
7. ProviderId is an open string. targetProvider !== 'claude' is
   therefore a comparison against an unconstrained type; a typo produces
   developer retention rather than a compile error.
8. Rung 1 does not re-validate the head of the conversation. Stripping a
   leading unreadable compaction can leave the retained history starting at a
   non-boundary entry; rung 4 only enforces the boundary invariant on the cuts it
   makes. Not observed in the corpus (a stripped carrier is always followed by
   the records it claimed to summarize), but not proven either.
9. Deferred minors from the review rounds. /model sonnet is hard-coded in
   the modal's model-switch row (no renderer-side Claude model registry exists).
   The 150,000-character default reads the live entry window, so a pane whose
   oldest entries were trimmed to disk under-reports — erring toward "no
   compaction", which is the safe side. The bulk path has no per-agent pane
   toast; strategies are reported as counts in one global toast, because per-pane
   wiring would change the workspace hook signature beyond parameter
   pass-through. Codex's exhaustion derivation is unproven against real bytes (no
   local rollout carries a rate_limit_reached_type). The drop marker has no
   "prompts omitted from the index" count. src/main/providerSwitch/testing/ is a
   new directory shape for src/main; it ships in no bundle. And OpenCode's
   projector was not audited for the same developer-role defect that motivated
   the Claude rule.
10. The Stage 7 live probe is deferred to
    #833, not met
    here. Fixes #821 is kept because everything else on that issue's
    acceptance list is implemented and verified, but two of its criteria —
    "a 10-agent batch completes without any 300 s wait" with the source at
    100 %, and "opt-in live probe run once and its report attached to the PR" —
    can only be met by that run. test(provider-switch): run the live probe for quota-independent switching #833 carries both verbatim, the four Unknowns
    the probe settles (2, 3, 6, 7), and the two ladder placeholders
    (keepRecentTurns: 3, maxInputChars: 8_000) it would replace with
    measurements. feat(provider-switch): switch agents off an exhausted provider without a source-side summarization turn #821 has been amended and commented to say so.

Residuals parked at the final re-review (all bounded; none can kill a live turn or lose history):

• A return-batch run that is refused pane by pane (for example during a compact-on-arrival window) clears the remembered batch even when nothing returned (bulkProviderSwitch.ts), so the user must switch panes back by hand.
• The compaction-first disclosure line always says "encrypted compaction dropped", although the detector also fires for a Claude incomplete or rejected first carrier.
• That disclosure reaches the single-pane toast only; the bulk summary reports strategy counts, so a compaction-first pane switched in a batch shows "raw" without the line.
• Clearing limitHit on turn_started means a pane whose provider auto-continued without writing a new rate-limit record reads busy for the rest of that episode and is refused (never killed) until the next 429 re-arms it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013SULm3ApxebET2a8eLxKHd