@north-light/cli 0.0.0-stage → 0.3.413

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.ts

@@ -0,0 +1,1409 @@
+import { spawn } from 'node:child_process';
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  createAssistantMessageEventStream,
+  type AssistantMessage,
+  type AssistantMessageEventStream,
+  type AuthEvent,
+  type AuthPrompt,
+  type TranscriptContext,
+  type FetchFunction,
+  type Model,
+  type OAuthAuth,
+  type SimpleStreamOptions,
+} from '@earendil-works/pi-ai';
+import { anthropicMessagesApi, openAICodexResponsesApi, openAIResponsesApi } from '@earendil-works/pi-ai/compat';
+import {
+  ANTHROPIC_PROVIDER_ID,
+  OPENAI_CHATGPT_PROVIDER_ID,
+  OPENAI_CODEX_PROVIDER_ID,
+  INVALID_REFRESH_TOKEN_BACKOFF_MS,
+  openAIDeviceId,
+  coolingUntilFor,
+  formatCooldowns,
+  formatStatusLine,
+  getProviderLabel,
+  isManagedProvider,
+  isInvalidRefreshTokenError,
+  addSubscription,
+  enrichManagedLoginIdentity,
+  markSubscriptionAuthenticationFailed,
+  markSubscriptionRateLimited,
+  markSubscriptionSuccess,
+  retryAfterMsFromHeaders,
+  retryAfterMsFromError,
+  promoteSubscription,
+  readRotationConfig,
+  readSubscriptionPool,
+  refreshSubscriptionCredential,
+  removeManagedAccount,
+  resolveProviderCandidates,
+  upsertSubscriptionWithUniqueAccount,
+  type ManagedProviderId,
+  type SubscriptionCredential,
+  subscriptionNeedsSuccessWrite,
+} from '../../../core/subscription-state.js';
+import { classifyRateLimit, describeRateLimitScope, rateLimitHeaders, type RateLimitObservation } from '../../../core/rate-limit-scope.js';
+import { readMergedLaunchConfig, type MergedLaunchConfig } from '../../../core/config.js';
+import type { ProviderOptionsConfig } from '../../../types.js';
+import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from '../../../core/model-routes.js';
+import { envModelExact, envNodeId } from '../../../shared/env.js';
+import { ManagedProviderCoolingError } from '../../../core/runtime/managed-provider-cooling.js';
+import { recordBrokerTurn } from '../../../core/runtime/broker/daemon-ops.js';
+import { recognizeProviderError, type ProviderErrorSignal } from '../../../core/provider-error-recognition.js';
+import { normalizeProviderFailure, providerFailureDiagnostic, type NormalizedProviderFailure } from '../../../core/provider-failure.js';
+
+// A response without Retry-After proves only that THIS attempt was throttled; it
+// does not authorize crouter to invent a five-minute provider-wide outage. Keep
+// a short turn-local probe backoff to avoid an immediate retry loop, then let a
+// fresh turn prove whether the credential is usable again. Real
+// server-provided Retry-After deadlines are still honored exactly.
+const DEFAULT_RATE_LIMIT_BACKOFF_MS = 15 * 1000;
+// Short in-place retry budget for a transient network/5xx blip on the same credential.
+// Once this budget is exhausted, surface the error and rotate to another candidate.
+const TRANSIENT_RETRY_BACKOFFS_MS = [250, 750];
+// After the in-place transient retry budget is exhausted, rotate instead of failing: the
+// credential itself is probably healthy (this is a provider-side blip like "overloaded"),
+// so cool it down only briefly -- long enough to rotate to another credential / fallback
+// provider, short enough that it comes back quickly if it was the only option.
+const TRANSIENT_ROTATE_COOLDOWN_MS = 60 * 1000;
+// A 401/403 before any content means the provider refused this credential (a lapsed
+// plan, a revoked server-side key). That is not a transient blip, but it is not proof
+// the account is gone either: cool the account for 30 minutes and rotate, rather than
+// the 30-day invalid_grant backoff. Exact requests keep the auth error.
+const AUTH_REJECTED_COOLDOWN_MS = 30 * 60 * 1000;
+// A few short outer retries absorb a normal multi-broker collision; if the metadata file
+// remains busy, the provider call still proceeds. Subscription bookkeeping must never turn a
+// healthy model response into a fatal generation fault.
+const SUBSCRIPTION_LOCK_RETRY_BACKOFFS_MS = [25, 75, 150];
+
+// A declared non-managed provider is re-registered with the route driver at
+// session start, after its owning extension has registered its real transport.
+// Keep that composed transport here: calling the registry after our wrapper is
+// installed would recurse back into the route driver.
+type ProviderStream = (model: Model<any>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+
+const { streamSimple: streamAnthropicMessages } = anthropicMessagesApi();
+const { streamSimple: streamOpenAICodexResponses } = openAICodexResponsesApi();
+const { streamSimple: streamOpenAIResponses } = openAIResponsesApi();
+
+export interface ProviderRotationOptions {
+  modelIntent?: string;
+  nodeCwd?: string;
+  profileId?: string;
+}
+
+type ProviderRotationState = {
+  runtimeContext?: ExtensionContext;
+  extensionAPI?: ExtensionAPI;
+  delegatedProviderStreams: Map<string, ProviderStream>;
+  options?: Readonly<ProviderRotationOptions>;
+  /** Per-provider behavior options from merged config, refreshed at session
+   *  start and before every agent turn so a settings toggle reaches a broker
+   *  that is already live. */
+  providerOptions?: Record<string, ProviderOptionsConfig>;
+  /** Consecutive route-queue passes that exhausted every route without a single
+   * HTTP response — the poisoned-process signature counted across turns. */
+  transportOnlyExhaustedPasses: number;
+};
+
+function createProviderRotationState(options?: ProviderRotationOptions): ProviderRotationState {
+  return { delegatedProviderStreams: new Map(), transportOnlyExhaustedPasses: 0, ...(options === undefined ? {} : { options: { ...options } }) };
+}
+
+function configuredValue(state: ProviderRotationState, key: keyof ProviderRotationOptions, envName: string): string | undefined {
+  return state.options === undefined ? process.env[envName] : state.options[key];
+}
+
+function isExactModel(state: ProviderRotationState): boolean {
+  return state.options === undefined && envModelExact();
+}
+
+type AttemptResult = {
+  result: "success" | "rate_limited" | "transient_exhausted" | "fatal";
+  retryAfterMs?: number;
+  attemptAt: number;
+  attempts?: number;
+  classification?: ProviderErrorClassification;
+  failure?: NormalizedProviderFailure;
+  failureMessage?: string;
+  /** The 429's rate-limit headers classified for the attempted model: which scope (account or model family) to cool. */
+  rateLimit?: RateLimitObservation;
+};
+
+// A genuine rate limit (HTTP 429, or 503 with a real Retry-After header) must
+// cool the credential down and rotate to the next one; a transient network/5xx blip
+// (connection reset, socket errors, timeouts, plain 500/502/504, or 503 with NO
+// retry-after) is not evidence the credential itself is bad -- it gets a short in-place
+// retry on the same credential, never a cooldown. Everything else is fatal. Bare
+// `usage`/`quota` substrings stay out of the message match: they are false-positive
+// magnets (e.g. "usage" appears in normal assistant text), while the precise
+// terminal usage-limit signals above still cool the credential down and rotate to the
+// next one. A status 401/403 rotates with AUTH_REJECTED_COOLDOWN_MS unless the request
+// is exact.
+type ProviderErrorClassification = {
+  kind: "rate_limit" | "transient" | "fatal";
+  status?: number;
+  reason: string;
+  hadRetryAfterHeader: boolean;
+  /** Cooldown this classification imposes regardless of any Retry-After header. */
+  cooldownMs?: number;
+};
+
+type ProviderClassificationPolicy = { rotateOnAuth: boolean };
+
+function classifyProviderSignal(signal: ProviderErrorSignal, policy: ProviderClassificationPolicy): ProviderErrorClassification {
+  const hadRetryAfterHeader = signal.retryAfterMs !== undefined;
+  if (signal.kind === 'rate-limit' && signal.matchedOn === 'status') {
+    return { kind: 'rate_limit', status: signal.status, reason: 'http 429', hadRetryAfterHeader };
+  }
+  if (signal.kind === 'transient-http') {
+    if (signal.status === 503 && hadRetryAfterHeader) {
+      return { kind: 'rate_limit', status: signal.status, reason: 'http 503 with retry-after', hadRetryAfterHeader };
+    }
+    return { kind: 'transient', status: signal.status, reason: `http ${signal.status}`, hadRetryAfterHeader };
+  }
+  const textMatches = signal.textMatches ?? (signal.matchedOn === 'text' && signal.match ? [{ kind: signal.kind, match: signal.match }] : []);
+  if (policy.rotateOnAuth && signal.kind === 'auth' && signal.matchedOn === 'status' && !textMatches.some(({ kind }) => kind === 'rate-limit')) {
+    return { kind: 'rate_limit', status: signal.status, reason: `http ${signal.status}`, hadRetryAfterHeader, cooldownMs: AUTH_REJECTED_COOLDOWN_MS };
+  }
+  const transientMatch = textMatches.find(({ kind }) => kind === 'connection' || kind === 'socket' || kind === 'service-unavailable' || kind === 'overloaded');
+  if (transientMatch) {
+    return { kind: 'transient', status: signal.status, reason: transientMatch.match.toLowerCase(), hadRetryAfterHeader };
+  }
+  const rateLimitMatch = textMatches.find(({ kind }) => kind === 'rate-limit');
+  if (rateLimitMatch) {
+    return { kind: 'rate_limit', status: signal.status, reason: rateLimitMatch.match.toLowerCase(), hadRetryAfterHeader };
+  }
+  return { kind: 'fatal', status: signal.status, reason: 'unclassified', hadRetryAfterHeader };
+}
+
+function classifyProviderFailure(failure: NormalizedProviderFailure, retryAfterMs: number | undefined, policy: ProviderClassificationPolicy): ProviderErrorClassification {
+  const nested = failure.causes ?? [];
+  const code = failure.code ?? nested.find((cause) => cause.code !== undefined)?.code;
+  const errno = failure.errno ?? nested.find((cause) => cause.errno !== undefined)?.errno;
+  const message = [failure.message, failure.body, ...nested.flatMap((cause) => [cause.message, cause.body])]
+    .filter((part): part is string => typeof part === 'string' && part.length > 0)
+    .join(' ');
+  return classifyProviderSignal(recognizeProviderError({
+    status: failure.status,
+    retryAfterMs,
+    code,
+    errno,
+    message,
+  }), policy);
+}
+
+/** Test seam for the policy mapping over the shared recognition signal. */
+export function __classifyProviderErrorForTest(
+  error: unknown,
+  observed: { status?: number; retryAfterMs?: number } = {},
+  policy: ProviderClassificationPolicy = { rotateOnAuth: false },
+): ProviderErrorClassification {
+  return classifyProviderFailure(normalizeProviderFailure(error, { status: observed.status }), observed.retryAfterMs, policy);
+}
+
+function providerFailureAssistantMessage(model: Model<any>, failure: NormalizedProviderFailure): AssistantMessage {
+  const message = toAssistantError(model, failure.message);
+  message.diagnostics = [providerFailureDiagnostic(failure)];
+  return message;
+}
+
+async function defaultSleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+// Indirection so tests can inject deterministic waits without real timers.
+let activeSleep: typeof defaultSleep = defaultSleep;
+
+/** Test-only seam: override the sleep implementation used for in-place/wait-out retries. Pass undefined to restore the default. */
+export function __setSleepForTest(fn: typeof defaultSleep | undefined): void {
+  activeSleep = fn ?? defaultSleep;
+}
+
+// After this many CONSECUTIVE route-queue passes in which every failure was
+// transport-level (no HTTP status and no Retry-After header — the provider was
+// never reached at all), the broker process itself is presumed poisoned: a
+// corrupted large TLS upload can leave Node/undici's HTTP/2 session permanently
+// destroyed, after which EVERY provider request from this process fails while
+// curl and fresh processes on the same host succeed. There is no clean in-process
+// heal (the dispatcher cannot be safely re-instantiated), so the recovery is a
+// fresh process: self-terminate via SIGTERM and let the daemon's exit policy
+// respawn this broker against the same session. A genuine full network outage
+// trips this too, and a fresh process cannot heal that one — so the daemon's
+// respawn path probes network reachability before it counts a relaunch, and an
+// offline box parks the node until the network returns instead of spending its
+// respawn budget (daemon/fleet.ts, `deferRespawnWhileOffline`).
+export const POISONED_TRANSPORT_PASS_LIMIT = 2;
+
+async function defaultTerminatePoisonedProcess(tried: string): Promise<boolean> {
+  // Only the broker process itself may self-terminate: runBroker stamps
+  // CRTR_BROKER_PID with its own pid at boot. Any other host (tests, tooling)
+  // keeps the ordinary terminal-error path.
+  if (process.env["CRTR_BROKER_PID"] !== String(process.pid)) return false;
+  const routes = tried.split(', ').filter((route) => route !== '');
+  const nodeId = envNodeId();
+  if (nodeId === undefined || routes.length === 0) {
+    throw new Error('poisoned broker is missing CRTR_NODE_ID or attempted routes');
+  }
+  await recordBrokerTurn(nodeId, {
+    event: 'exit-diagnostic',
+    exit_diagnostic: {
+      schema: 'crtr.execution-exit-diagnostic/v1',
+      transport_poison: { consecutive_passes: POISONED_TRANSPORT_PASS_LIMIT, routes },
+    },
+  });
+  logRotation(
+    `process transport poisoned: ${POISONED_TRANSPORT_PASS_LIMIT} consecutive route-queue passes failed with no HTTP response (tried ${tried}); exiting so the daemon respawns this broker fresh`,
+  );
+  process.kill(process.pid, "SIGTERM");
+  return true;
+}
+
+let activeTerminatePoisonedProcess = defaultTerminatePoisonedProcess;
+
+/** Test-only seam: override poisoned-process self-termination. Pass undefined to restore the default. */
+export function __setTerminatePoisonedProcessForTest(fn: typeof defaultTerminatePoisonedProcess | undefined): void {
+  activeTerminatePoisonedProcess = fn ?? defaultTerminatePoisonedProcess;
+}
+
+function isSubscriptionLockContention(error: unknown): boolean {
+  const value = error as { code?: unknown; message?: unknown } | undefined;
+  return value?.code === "ELOCKED" || (typeof value?.message === "string" && /lock file is already being held/i.test(value.message));
+}
+
+async function recordSubscriptionMutation(description: string, mutate: () => Promise<unknown>): Promise<boolean> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await mutate();
+      return true;
+    } catch (error) {
+      if (!isSubscriptionLockContention(error)) throw error;
+      const backoffMs = SUBSCRIPTION_LOCK_RETRY_BACKOFFS_MS[attempt];
+      if (backoffMs === undefined) {
+        logRotation(`subscription metadata lock remained busy while ${description}; continuing without failing the provider turn`);
+        return false;
+      }
+      await activeSleep(backoffMs);
+    }
+  }
+}
+
+/** Test-only seam for the bounded, non-fatal subscription bookkeeping path. */
+export async function __recordSubscriptionMutationForTest(description: string, mutate: () => Promise<unknown>): Promise<boolean> {
+  return recordSubscriptionMutation(description, mutate);
+}
+
+// A user/host abort (ESC, a critical-tier interrupt, a torn-down window) is NOT a provider
+// failure — it must never cool down a credential or rotate providers. The upstream pi-ai
+// providers set `reason: "aborted"` / `stopReason: "aborted"` (and throw "Request was aborted")
+// ONLY when the request's AbortSignal fired, so those markers alone are a reliable abort
+// signal; we do NOT require the signal to be threaded back through our own options (it may not
+// be), which is what made an ESC drain both provider pools.
+function isUserAbortEvent(event: Parameters<AssistantMessageEventStream["push"]>[0], signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  if (event.type !== "error") return false;
+  return event.reason === "aborted" || event.error.stopReason === "aborted" || /request was aborted/i.test(event.error.errorMessage ?? "");
+}
+
+function isUserAbortError(error: unknown, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  const value = error as { name?: unknown; errorMessage?: unknown; message?: unknown } | undefined;
+  const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : String(error ?? "")]
+    .filter((part): part is string => typeof part === "string" && part.length > 0)
+    .join(" ");
+  return (error instanceof Error && /abort/i.test(error.name)) || /request was aborted|operation was aborted|the user aborted/i.test(message);
+}
+
+function setStatus(state: ProviderRotationState, text: string): void {
+  state.runtimeContext?.ui.setStatus("provider-rotation", text);
+}
+
+function logRotation(message: string): void {
+  process.stderr.write(`[provider-rotation] ${message}\n`);
+}
+
+function getCurrentModelRef(model?: Model<any>): { providerId: ManagedProviderId; modelId: string } | undefined {
+  return isManagedProvider(model?.provider) ? { providerId: model.provider, modelId: model.id } : undefined;
+}
+
+function toAssistantError(model: Model<any>, errorMessage: string): AssistantMessage {
+  return {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "error",
+    errorMessage,
+    timestamp: Date.now(),
+  };
+}
+
+// ChatGPT (`openai`) credentials also carry the per-login issued OAuth `clientId`, which its
+// refresh requires and may rotate.
+type RefreshedCredential = { refresh: string; access: string; expires: number; clientId?: string };
+// Codex login carries the ChatGPT `accountId`; Anthropic identity is enriched from its OAuth
+// profile after login. Optional so every provider and the test seam fit.
+type LoginCredential = { refresh: string; access: string; expires: number; accountId?: string; clientId?: string };
+
+function loginClientId(cred: { clientId?: unknown }): string | undefined {
+  return typeof cred.clientId === "string" && cred.clientId.trim() ? cred.clientId.trim() : undefined;
+}
+
+// Extract an account identity supplied directly by the OAuth credential.
+function loginAccountId(cred: { accountId?: unknown }): string | undefined {
+  return typeof cred.accountId === "string" && cred.accountId.trim() ? cred.accountId.trim() : undefined;
+}
+
+// Short, display-only rendering of a Codex account id for `/provider-sub list`, so distinct
+// accounts are observable without dumping the full opaque id.
+function shortAccountId(accountId: string): string {
+  return accountId.length > 12 ? `${accountId.slice(0, 8)}\u2026${accountId.slice(-4)}` : accountId;
+}
+
+// A credential that has been through refresh/reauth for this turn: `.access` is guaranteed
+// populated. Every account stores its own value in the pool, so downstream stream-attempt code
+// can rely on `.access` directly.
+type ResolvedCredential = SubscriptionCredential & { access: string };
+
+// The registered provider exposes its OAuth flow through `provider.auth.oauth`. Composed managed
+// providers retain that flow, so the session registry supplies the Anthropic and Codex flows.
+function oauthFlow(providerId: ManagedProviderId, ctx: ExtensionContext | undefined): OAuthAuth {
+  const oauth = ctx?.modelRegistry.getProvider(providerId)?.auth.oauth;
+  if (!oauth) throw new Error(`${getProviderLabel(providerId)} has no OAuth flow registered`);
+  return oauth;
+}
+
+// `refresh` is a pure token exchange that reads only `credential.refresh` and persists
+// nothing; crouter records the rotated token in the selected pool row.
+async function defaultRefreshForProvider(
+  state: ProviderRotationState,
+  providerId: ManagedProviderId,
+  refreshToken: string,
+  parentSignal?: AbortSignal,
+  clientId?: string,
+): Promise<RefreshedCredential> {
+  const localController = parentSignal === undefined ? new AbortController() : undefined;
+  const signal = parentSignal ?? localController!.signal;
+  try {
+    const refreshed = await oauthFlow(providerId, state.runtimeContext).refresh({ type: "oauth", refresh: refreshToken, access: "", expires: 0, ...(clientId ? { clientId } : {}) }, signal);
+    const nextClientId = loginClientId(refreshed as { clientId?: unknown });
+    return { refresh: refreshed.refresh, access: refreshed.access, expires: refreshed.expires, ...(nextClientId ? { clientId: nextClientId } : {}) };
+  } finally {
+    localController?.abort();
+  }
+}
+
+type RefreshForProvider = (providerId: ManagedProviderId, refreshToken: string, signal?: AbortSignal, clientId?: string) => Promise<RefreshedCredential>;
+
+// Indirection so tests can inject refresh failures without real network calls.
+let activeRefreshForProvider: RefreshForProvider | undefined;
+
+/** Test-only seam: override the per-provider refresh function. Pass undefined to restore the default. */
+export function __setRefreshForProviderForTest(fn: RefreshForProvider | undefined): void {
+  activeRefreshForProvider = fn;
+}
+
+function openBrowser(url: string): void {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+      /* best effort -- the manual-code dialog's title carries the URL too */
+    });
+    child.unref();
+  } catch {
+    /* best effort */
+  }
+}
+
+// Every account refreshes the same way: the pool holds its value, so an expired token is a
+// token exchange serialized on the pool file's lock. A still-fresh access token takes the
+// side-effect-free fast path and never joins the lock. We do NOT route through pi's public
+// `getApiKey`, which wraps pi-ai's `getOAuthApiKey` and collapses a refresh failure into a
+// generic message; calling `activeRefreshForProvider` directly keeps the real error intact so
+// `isInvalidRefreshTokenError` can classify it (cooldown -> reauth -> cross-provider-fallback).
+async function refreshCredentialIfNeeded(
+  state: ProviderRotationState,
+  providerId: ManagedProviderId,
+  credential: SubscriptionCredential,
+  signal?: AbortSignal,
+): Promise<ResolvedCredential> {
+  if (!credential.refresh || !credential.access || credential.expires === undefined) {
+    throw new Error(`${getProviderLabel(providerId)} subscription "${credential.label}" is missing its credential value`);
+  }
+  if (credential.expires > Date.now()) return credential as ResolvedCredential;
+  const refreshed = await refreshSubscriptionCredential(providerId, credential.label, (token, clientId) =>
+    activeRefreshForProvider?.(providerId, token, signal, clientId) ?? defaultRefreshForProvider(state, providerId, token, signal, clientId),
+  );
+  return { ...credential, ...refreshed } as ResolvedCredential;
+}
+
+/** Test-only seam: exercises the real `refreshCredentialIfNeeded` (including its locked refresh
+ * transaction) without duplicating its logic. */
+export async function __refreshCredentialIfNeededForTest(
+  providerId: ManagedProviderId,
+  credential: SubscriptionCredential,
+  signal?: AbortSignal,
+): Promise<ResolvedCredential> {
+  return refreshCredentialIfNeeded(createProviderRotationState(), providerId, credential, signal);
+}
+
+async function defaultLoginForProvider(providerId: ManagedProviderId, ctx: ExtensionContext): Promise<LoginCredential> {
+  return loginProvider(providerId, ctx);
+}
+
+let activeLoginForProvider: typeof defaultLoginForProvider = defaultLoginForProvider;
+
+/** Test-only seam: override the per-provider login function. Pass undefined to restore the default. */
+export function __setLoginForProviderForTest(fn: typeof defaultLoginForProvider | undefined): void {
+  activeLoginForProvider = fn ?? defaultLoginForProvider;
+}
+
+async function reauthenticateCredential(state: ProviderRotationState, providerId: ManagedProviderId, credential: SubscriptionCredential): Promise<ResolvedCredential | undefined> {
+  const ctx = state.runtimeContext;
+  if (!ctx?.hasUI) return undefined;
+  ctx.ui.notify(`${getProviderLabel(providerId)} subscription "${credential.label}" needs re-authentication. Opening OAuth login...`, "warning");
+  const authenticated = await activeLoginForProvider(providerId, ctx);
+  const identity = await enrichManagedLoginIdentity(providerId, authenticated);
+  // A failed Anthropic profile lookup leaves identity unknown. Do not carry the old row's identity
+  // onto newly issued tokens: it could describe a different account and bypass that account's
+  // duplicate check. Codex supplies its identity directly, so it can retain its existing claim
+  // only when that provider's login result omits one.
+  const reauthedAccountId =
+    identity.accountId ?? (providerId === ANTHROPIC_PROVIDER_ID ? undefined : loginAccountId(authenticated) ?? credential.accountId);
+  const { authFailure: _authFailure, clientId: _oldClientId, ...healthyCredential } = credential;
+  const reauthedClientId = loginClientId(authenticated);
+  const next: SubscriptionCredential = {
+    ...healthyCredential,
+    refresh: authenticated.refresh,
+    access: authenticated.access,
+    expires: authenticated.expires,
+    ...(reauthedAccountId ? { accountId: reauthedAccountId } : {}),
+    ...(reauthedClientId ? { clientId: reauthedClientId } : {}),
+    rateLimitedUntil: 0,
+    lastAttemptAt: Date.now(),
+    lastRateLimitedAt: credential.lastRateLimitedAt,
+  };
+  // Identity-checked upsert: reauthenticating this explicit slot into an account already held by
+  // ANOTHER slot throws DuplicateSubscriptionError rather than creating a duplicate quota entry.
+  return ((await upsertSubscriptionWithUniqueAccount(providerId, next)).find((entry) => entry.label === next.label) ?? next) as ResolvedCredential;
+}
+
+function defaultStreamForProvider(model: Model<any>, context: TranscriptContext, options: SimpleStreamOptions | undefined): AssistantMessageEventStream {
+  if (model.provider === ANTHROPIC_PROVIDER_ID) {
+    return streamAnthropicMessages(model as Model<"anthropic-messages">, context, options);
+  }
+  if (model.provider === OPENAI_CHATGPT_PROVIDER_ID) {
+    return streamOpenAIResponses(model as Model<"openai-responses">, context, options);
+  }
+  return streamOpenAICodexResponses(model as Model<"openai-codex-responses">, context, options);
+}
+
+// Indirection so tests can inject a fake per-provider stream without real network calls.
+let activeStreamForProvider: typeof defaultStreamForProvider = defaultStreamForProvider;
+
+function streamForProvider(model: Model<any>, context: TranscriptContext, options: SimpleStreamOptions | undefined): AssistantMessageEventStream {
+  return activeStreamForProvider(model, context, options);
+}
+
+const ANTHROPIC_SERVER_SIDE_FALLBACK_BETA = "server-side-fallback-2026-07-01";
+const ANTHROPIC_SERVER_SIDE_FALLBACK_PRIMARY_MODELS = new Set(["claude-fable-5", "claude-opus-5"]);
+
+function supportsAnthropicServerSideFallback(model: Model<any>): boolean {
+  return ANTHROPIC_SERVER_SIDE_FALLBACK_PRIMARY_MODELS.has(model.id);
+}
+
+function includesAnthropicBetaToken(value: string): boolean {
+  return value.split(",").some((token) => token.trim() === ANTHROPIC_SERVER_SIDE_FALLBACK_BETA);
+}
+
+function appendAnthropicFallbackBeta(headers: HeadersInit | undefined): HeadersInit {
+  if (headers instanceof Headers) {
+    const next = new Headers(headers);
+    const current = next.get("anthropic-beta");
+    if (current === null || !includesAnthropicBetaToken(current)) {
+      next.set("anthropic-beta", current === null ? ANTHROPIC_SERVER_SIDE_FALLBACK_BETA : `${current},${ANTHROPIC_SERVER_SIDE_FALLBACK_BETA}`);
+    }
+    return next;
+  }
+
+  if (Array.isArray(headers)) {
+    const next = headers.map(([name, value]) => [name, value] as [string, string]);
+    const index = next.findIndex(([name]) => name.toLowerCase() === "anthropic-beta");
+    if (index === -1) next.push(["anthropic-beta", ANTHROPIC_SERVER_SIDE_FALLBACK_BETA]);
+    else if (!includesAnthropicBetaToken(next[index][1])) next[index][1] = `${next[index][1]},${ANTHROPIC_SERVER_SIDE_FALLBACK_BETA}`;
+    return next;
+  }
+
+  const next = { ...(headers ?? {}) } as Record<string, string>;
+  const headerName = Object.keys(next).find((name) => name.toLowerCase() === "anthropic-beta");
+  if (headerName === undefined) next["anthropic-beta"] = ANTHROPIC_SERVER_SIDE_FALLBACK_BETA;
+  else if (!includesAnthropicBetaToken(next[headerName])) next[headerName] = `${next[headerName]},${ANTHROPIC_SERVER_SIDE_FALLBACK_BETA}`;
+  return next;
+}
+
+function withAnthropicFallbackBeta(fetch: FetchFunction): FetchFunction {
+  return (input, init) => {
+    const headers = init?.headers ?? (input instanceof Request ? input.headers : undefined);
+    return fetch(input, { ...init, headers: appendAnthropicFallbackBeta(headers) });
+  };
+}
+
+/** Test-only seam: override the per-provider stream factory. Pass undefined to restore the default. */
+export function __setStreamForProviderForTest(fn: typeof defaultStreamForProvider | undefined): void {
+  activeStreamForProvider = fn ?? defaultStreamForProvider;
+}
+
+/** Test-only seam: exercise `fallbackRejectionHint` for one rejection discriminant
+ *  (with an optional resolved-but-rejected candidate) without staging a full turn. */
+// Drives one credential, retrying transient (non-rate-limit) failures in place on the
+// same credential and reporting a classified result for rotation logging.
+// A genuine rate limit ends the attempt immediately (the caller cools the credential down
+// and rotates); a transient blip gets a short in-place retry budget before giving up.
+async function streamProviderAttempt(
+  state: ProviderRotationState,
+  providerId: string,
+  model: Model<any>,
+  context: TranscriptContext,
+  options: SimpleStreamOptions | undefined,
+  credential: ResolvedCredential | undefined,
+  outer: AssistantMessageEventStream,
+): Promise<AttemptResult> {
+  const policy: ProviderClassificationPolicy = { rotateOnAuth: !isExactModel(state) };
+  for (let attempt = 1; ; attempt++) {
+    const attemptAt = Date.now();
+    let observedStatus: number | undefined;
+    let requestedRetryAfterMs: number | undefined;
+    let limitHeaders: Record<string, string> | undefined;
+    const useAnthropicServerSideFallback =
+      credential !== undefined
+      && providerId === ANTHROPIC_PROVIDER_ID
+      && supportsAnthropicServerSideFallback(model);
+    const streamOptions = {
+      ...options,
+      ...(credential ? { apiKey: credential.access } : {}),
+      ...(useAnthropicServerSideFallback
+        ? {
+            onPayload: async (payload: unknown, payloadModel: Model<any>) => {
+              const callerPayload = await options?.onPayload?.(payload, payloadModel);
+              return { ...((callerPayload === undefined ? payload : callerPayload) as Record<string, unknown>), fallbacks: "default" };
+            },
+            // `headers` would overwrite pi-ai's OAuth beta list. Compose at fetch time so the
+            // SDK's generated headers stay intact; replace this shim with pi-ai's `fallbacks`
+            // option when that upstream option ships.
+            fetch: withAnthropicFallbackBeta(options?.fetch ?? globalThis.fetch),
+          }
+        : {}),
+      // Codex fast mode: the ChatGPT backend serves the turn at its priority
+      // tier. The wire value is `priority` (`fast` is rejected 400), and the
+      // response always echoes `service_tier: "default"` regardless — only
+      // generation timing shows whether it took effect.
+      ...(providerId === OPENAI_CODEX_PROVIDER_ID && state.providerOptions?.[OPENAI_CODEX_PROVIDER_ID]?.fastMode === true
+        ? {
+            onPayload: async (payload: unknown, payloadModel: Model<any>) => {
+              const callerPayload = await options?.onPayload?.(payload, payloadModel);
+              return { ...((callerPayload === undefined ? payload : callerPayload) as Record<string, unknown>), service_tier: "priority" };
+            },
+          }
+        : {}),
+      onResponse: async (response: { status: number; headers: Record<string, string> }, responseModel: Model<any>) => {
+        observedStatus = response.status;
+        if (response.status === 429 || response.status === 503) {
+          requestedRetryAfterMs = retryAfterMsFromHeaders(response.headers);
+          limitHeaders = rateLimitHeaders(response.headers);
+        }
+        await options?.onResponse?.(response as any, responseModel);
+      },
+    };
+    const provider = state.runtimeContext?.modelRegistry.getProvider?.(model.provider);
+    const inner = isManagedProvider(providerId)
+      ? streamForProvider(model, context, streamOptions)
+      : state.delegatedProviderStreams.get(providerId)?.(model, context, streamOptions)
+        ?? provider?.streamSimple(model, context, streamOptions)
+        ?? streamForProvider(model, context, streamOptions);
+
+    const bufferedEvents: Parameters<AssistantMessageEventStream["push"]>[0][] = [];
+    let sawContent = false;
+    let committed = false;
+    let classification: ProviderErrorClassification | undefined;
+    let failure: NormalizedProviderFailure | undefined;
+    let failureMessage: string | undefined;
+
+    // Events are buffered ONLY until this attempt commits to the provider -- i.e. until the
+    // first real content event (thinking/text/toolcall) arrives, after which rotating away is
+    // no longer possible. Before commit the buffer lets a clean pre-content rate-limit rotate
+    // to another credential with nothing yet shown. Once committed we flush and forward every
+    // subsequent event LIVE, so viewers stream token-by-token instead of receiving the whole
+    // message at once when the turn finally completes.
+    const emit = (event: Parameters<AssistantMessageEventStream["push"]>[0]): void => {
+      if (committed) outer.push(event);
+      else bufferedEvents.push(event);
+    };
+    const flush = (): void => {
+      for (const event of bufferedEvents) outer.push(event);
+      bufferedEvents.length = 0;
+      committed = true;
+    };
+
+    try {
+      for await (const event of inner) {
+        if (event.type === "error") {
+          if (isUserAbortEvent(event, options?.signal)) {
+            emit(event);
+            flush();
+            return { result: "fatal", attemptAt };
+          }
+          failure = normalizeProviderFailure(event.error, { status: observedStatus });
+          failureMessage = failure.message;
+          classification = classifyProviderFailure(failure, requestedRetryAfterMs, policy);
+          if (classification.kind === "fatal" || sawContent) {
+            emit({ ...event, error: providerFailureAssistantMessage(model, failure) });
+            flush();
+            return { result: "fatal", attemptAt, classification, failure };
+          }
+          break;
+        }
+        if (event.type !== "start" && event.type !== "done") sawContent = true;
+        emit(event);
+        // First content event: commit to this provider -- flush the buffer and switch to live
+        // forwarding so the rest of the turn streams incrementally.
+        if (sawContent && !committed) flush();
+      }
+    } catch (error) {
+      if (isUserAbortError(error, options?.signal)) {
+        emit({
+          type: "error",
+          reason: "aborted",
+          error: { ...toAssistantError(model, error instanceof Error ? error.message : String(error)), stopReason: "aborted" },
+        });
+        flush();
+        return { result: "fatal", attemptAt };
+      }
+      requestedRetryAfterMs ??= retryAfterMsFromError(error);
+      if (limitHeaders === undefined && error && typeof error === "object" && "headers" in error && error.headers && typeof error.headers === "object") {
+        const fromError = rateLimitHeaders(error.headers as Headers | Record<string, string>);
+        if (Object.keys(fromError).length) limitHeaders = fromError;
+      }
+      failure = normalizeProviderFailure(error, { status: observedStatus });
+      failureMessage = failure.message;
+      classification = classifyProviderFailure(failure, requestedRetryAfterMs, policy);
+      if (classification.kind === "fatal" || sawContent) {
+        emit({
+          type: "error",
+          reason: "error",
+          error: providerFailureAssistantMessage(model, failure),
+        });
+        flush();
+        return { result: "fatal", attemptAt, classification, failure };
+      }
+    }
+
+    if (!classification && requestedRetryAfterMs !== undefined && !sawContent) {
+      // Some providers signal a 429/503 purely via the response header without ever raising
+      // a stream "error" event; treat that the same as an explicit rate-limit classification.
+      classification = { kind: "rate_limit", status: observedStatus, reason: "retry-after header on success path", hadRetryAfterHeader: true };
+    }
+
+    if (!classification) {
+      flush();
+      return { result: "success", attemptAt };
+    }
+
+    if (classification.kind === "rate_limit") {
+      // Only a genuine 429 is classified for scope; a 401/403 or 503 cooldown stays account-wide.
+      const rateLimit = classification.status === 429 || (classification.status === undefined && classification.cooldownMs === undefined)
+        ? classifyRateLimit(limitHeaders, model.id)
+        : undefined;
+      let retryAfterMs = classification.cooldownMs ?? requestedRetryAfterMs;
+      // No Retry-After but a rejected window's reset: wait for the window, not the default backoff.
+      if (retryAfterMs === undefined && rateLimit?.resetAt !== undefined) retryAfterMs = Math.max(0, rateLimit.resetAt - Date.now());
+      if (rateLimit && Object.keys(rateLimit.headers).length) {
+        logRotation(`${credential ? `${getProviderLabel(providerId as ManagedProviderId)} subscription "${credential.label}"` : providerId} 429 on ${model.id}: scope=${describeRateLimitScope(rateLimit.scope)} headers=${JSON.stringify(rateLimit.headers)}`);
+      }
+      return { result: "rate_limited", retryAfterMs, attemptAt, classification, failureMessage, ...(rateLimit ? { rateLimit } : {}) };
+    }
+
+    // Transient: retry the SAME credential/provider in place first -- no cooldown for the
+    // quick in-place budget.
+    const backoffMs = TRANSIENT_RETRY_BACKOFFS_MS[attempt - 1];
+    if (backoffMs === undefined) {
+      // In-place retry budget exhausted. Rather than hard-failing the turn, hand back a
+      // transient-exhausted result so the caller surfaces the error to the user AND rotates
+      // to another credential / fallback provider. Nothing is emitted into the stream here:
+      // the buffered (pre-content) events are discarded exactly like the rate-limit path, so
+      // the rotation target streams a clean turn.
+      return { result: "transient_exhausted", attemptAt, classification, attempts: attempt, failure, failureMessage };
+    }
+    logRotation(
+      `${credential ? `${getProviderLabel(providerId as ManagedProviderId)} subscription "${credential.label}"` : providerId} hit a transient error (${classification.reason}, status=${classification.status ?? "n/a"}); retrying same route in ${backoffMs}ms (attempt ${attempt + 1})`,
+    );
+    await activeSleep(backoffMs);
+  }
+}
+
+function emitTerminalError(stream: AssistantMessageEventStream, model: Model<any>, message: string, failure?: NormalizedProviderFailure): void {
+  stream.push({ type: "error", reason: "error", error: failure === undefined ? toAssistantError(model, message) : providerFailureAssistantMessage(model, failure) });
+  stream.end();
+}
+
+// Routes, rather than provider ids, own queue bookkeeping: a route may share a
+// provider with another credential source while still having distinct ordering and
+// turn-local cooling state.
+type RouteCandidate = {
+  routeId: string;
+  credentialSource: string;
+  rank: number;
+  providerId: string;
+  model: Model<any>;
+  thinkingLevel: string | undefined;
+};
+
+function enqueueFreshRouteCandidates(
+  candidates: RouteCandidate[],
+  queuedRouteIds: Set<string>,
+  knownRoutes: Map<string, RouteCandidate>,
+  seenReadyLabels: Map<string, Set<string>>,
+  cooldownAttempts: Map<string, number>,
+  localCoolingDeadlines: Map<string, number>,
+): void {
+  const now = Date.now();
+  for (const [routeId, candidate] of knownRoutes) {
+    if (queuedRouteIds.has(routeId) || (localCoolingDeadlines.get(routeId) ?? 0) > now || !isManagedProvider(candidate.providerId)) continue;
+    const seenLabels = seenReadyLabels.get(routeId) ?? new Set<string>();
+    const hasFreshCredential = readSubscriptionPool(candidate.providerId).some((credential) => {
+      if (credential.authFailure !== undefined || coolingUntilFor(credential, candidate.model.id) > now) return false;
+      const cooldownAttempt = cooldownAttempts.get(`${routeId}/${credential.label}`);
+      return !seenLabels.has(credential.label) || (cooldownAttempt !== undefined && credential.lastAttemptAt > cooldownAttempt);
+    });
+    if (hasFreshCredential) {
+      candidates.push(candidate);
+      queuedRouteIds.add(routeId);
+    }
+  }
+}
+
+async function switchToRoute(pi: ExtensionAPI, ctx: ExtensionContext, candidate: RouteCandidate): Promise<boolean> {
+  if (ctx.model?.provider !== candidate.providerId || ctx.model.id !== candidate.model.id) {
+    if (!await pi.setModel(candidate.model)) return false;
+  }
+  pi.setThinkingLevel((candidate.thinkingLevel ?? 'off') as any);
+  return ctx.model?.provider === candidate.providerId && ctx.model.id === candidate.model.id;
+}
+
+function logRouteQueueAdvance(from: RouteCandidate, to: RouteCandidate | undefined, result: AttemptResult): void {
+  logRotation(
+    `from=${from.providerId}/${from.model.id} from_route_id=${from.routeId} from_credential_source=${from.credentialSource} from_rank=${from.rank} to=${to ? `${to.providerId}/${to.model.id}` : "none"} to_route_id=${to?.routeId ?? "none"} to_credential_source=${to?.credentialSource ?? "none"} to_rank=${to?.rank ?? "none"} reason=${result.classification?.reason ?? result.result}; advancing route queue`,
+  );
+}
+
+// Drive the deterministic route queue from the live rank. Managed routes walk
+// their pool rows; every other declared route is one configured credential.
+async function runManagedProvider(
+  state: ProviderRotationState,
+  model: Model<any>,
+  context: TranscriptContext,
+  options: SimpleStreamOptions | undefined,
+  stream: AssistantMessageEventStream,
+): Promise<void> {
+  const liveThinking = state.runtimeContext?.thinkingLevel === undefined || state.runtimeContext?.thinkingLevel === 'off'
+    ? undefined
+    : state.runtimeContext.thinkingLevel;
+  const request = modelRequestFromConfig(
+    `${model.provider}/${model.id}${liveThinking ? `:${liveThinking}` : ''}`,
+    configuredValue(state, 'modelIntent', 'CRTR_MODEL_INTENT'),
+    isExactModel(state),
+  );
+  const expanded = request ? expandModelCandidates(
+    request,
+    configuredValue(state, 'nodeCwd', 'CRTR_NODE_CWD'),
+    configuredValue(state, 'profileId', 'CRTR_PROFILE_ID'),
+  ) : [];
+  // The node's thinking level holds on its own model; a route to another
+  // provider or model takes that cell's thinking.
+  const onLiveModel = (candidate: { providerId: string; modelId: string }): boolean =>
+    candidate.providerId === model.provider && candidate.modelId === model.id;
+  const liveRank = (expanded.find((candidate) => onLiveModel(candidate) && candidate.thinkingLevel === liveThinking) ?? expanded.find(onLiveModel))?.rank ?? 0;
+  const routeCandidates: RouteCandidate[] = expanded.slice(liveRank)
+    .map((route) => {
+      const registry = state.runtimeContext?.modelRegistry;
+      const routeModel = registry?.find(route.providerId, route.modelId);
+      if (!registry || !routeModel) return undefined;
+      const availability = probeRouteAvailability(route, registry);
+      if (!availability.registered || (!isManagedProvider(route.providerId) && !availability.authenticated)) return undefined;
+      return { routeId: route.routeId, credentialSource: route.credentialSource, rank: route.rank, providerId: route.providerId, model: routeModel, thinkingLevel: onLiveModel(route) ? liveThinking : route.thinkingLevel };
+    })
+    .filter((candidate): candidate is RouteCandidate => candidate !== undefined)
+    .filter((candidate, index, all) => all.findIndex((other) => other.routeId === candidate.routeId && other.providerId === candidate.providerId && other.model.id === candidate.model.id && other.thinkingLevel === candidate.thinkingLevel) === index);
+  const isLiveRoute = (candidate: RouteCandidate): boolean =>
+    candidate.providerId === model.provider && candidate.model.id === model.id && candidate.thinkingLevel === liveThinking;
+  // A cooling or unauthenticated managed route contributes its diagnostic and may
+  // later re-enter when a credential becomes ready, but it is never selected now.
+  const candidates = routeCandidates.filter((candidate) => {
+    if (isLiveRoute(candidate) || !isManagedProvider(candidate.providerId)) return true;
+    const pool = readSubscriptionPool(candidate.providerId);
+    return pool.length === 0
+      ? state.runtimeContext!.modelRegistry.hasConfiguredAuth(candidate.model)
+      : pool.some((entry) => entry.authFailure === undefined && coolingUntilFor(entry, candidate.model.id) <= Date.now());
+  });
+  if (!candidates.some(isLiveRoute)) {
+    candidates.unshift({ routeId: `live:${model.provider}/${model.id}`, credentialSource: 'live', rank: liveRank, providerId: model.provider, model, thinkingLevel: liveThinking });
+  }
+
+  const queuedRouteIds = new Set(candidates.map((candidate) => candidate.routeId));
+  const knownRoutes = new Map([...routeCandidates, ...candidates].map((candidate) => [candidate.routeId, candidate]));
+  const attemptedRoutes = new Set<string>();
+  const authFailures = new Set<string>();
+  const localCoolingDeadlines = new Map<string, number>();
+  const seenReadyLabels = new Map<string, Set<string>>();
+  const cooldownAttempts = new Map<string, number>();
+  let terminalModel = model;
+  let lastTransientFailure: AttemptResult | undefined;
+  // The last pre-content 401/403 that cooled a route; its text is the only
+  // record of why the routes ran out when they end in a cooling error.
+  let lastAuthRejection: AttemptResult | undefined;
+  // The last 429 whose response carried rate-limit headers: recorded on the
+  // cooling fault so an incident traces to the account or to one model family.
+  let lastRateLimit: { providerId: string; model: Model<any>; account?: string; observation: RateLimitObservation } | undefined;
+  // Any HTTP response observed this pass (a status, a Retry-After header, or a
+  // rate-limit classification) proves this process can still reach a provider,
+  // clearing the poisoned-transport suspicion.
+  let sawHttpEvidence = false;
+
+  for (let candidate = candidates.shift(); candidate !== undefined; candidate = candidates.shift()) {
+    const { routeId, providerId, model: candidateModel } = candidate;
+    queuedRouteIds.delete(routeId);
+    knownRoutes.set(routeId, candidate);
+    attemptedRoutes.add(routeId);
+    terminalModel = candidateModel;
+
+    if (!await switchToRoute(state.extensionAPI!, state.runtimeContext!, candidate)) {
+      emitTerminalError(stream, candidateModel, `Provider route ${routeId} is unavailable: failed to select ${providerId}/${candidateModel.id}`);
+      return;
+    }
+
+    const rawPool = isManagedProvider(providerId) ? readSubscriptionPool(providerId) : [];
+    if (!isManagedProvider(providerId) || rawPool.length === 0) {
+      const liveKey = isLiveRoute(candidate) ? options?.apiKey : undefined;
+      if (isManagedProvider(providerId) && !liveKey && !state.runtimeContext!.modelRegistry.hasConfiguredAuth(candidateModel)) continue;
+      const auth = isManagedProvider(providerId) && !liveKey
+        ? await state.runtimeContext!.modelRegistry.getApiKeyAndHeaders(candidateModel)
+        : undefined;
+      if (isManagedProvider(providerId) && !liveKey && (!auth?.ok || !auth.apiKey)) continue;
+      const headers = { ...options?.headers };
+      for (const [name, value] of Object.entries(auth?.ok ? auth.headers ?? {} : {})) {
+        for (const existing of Object.keys(headers)) if (existing.toLowerCase() === name.toLowerCase()) delete headers[existing];
+        headers[name] = value;
+      }
+      const attemptOptions = auth?.ok ? { ...options, apiKey: auth.apiKey, headers } : options;
+      const result = await streamProviderAttempt(state, providerId, candidateModel, context, attemptOptions, undefined, stream);
+      if (result.result === 'success' || result.result === 'fatal') { state.transportOnlyExhaustedPasses = 0; stream.end(); return; }
+      if (result.result === 'rate_limited' || result.classification?.status !== undefined || result.classification?.hadRetryAfterHeader === true) sawHttpEvidence = true;
+      const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
+      if (result.result === 'transient_exhausted') lastTransientFailure = result;
+      if (result.result === 'rate_limited' && (result.classification?.status === 401 || result.classification?.status === 403)) lastAuthRejection = result;
+      if (result.rateLimit && Object.keys(result.rateLimit.headers).length) lastRateLimit = { providerId, model: candidateModel, observation: result.rateLimit };
+      localCoolingDeadlines.set(routeId, Math.max(localCoolingDeadlines.get(routeId) ?? 0, Date.now() + cooldownMs));
+      logRouteQueueAdvance(candidate, candidates[0], result);
+      continue;
+    }
+    for (const entry of rawPool) if (entry.authFailure === 'invalid_grant') authFailures.add(`${providerId}/${entry.label}`);
+    const available = rawPool.filter((entry) => entry.authFailure === undefined && coolingUntilFor(entry, candidateModel.id) <= Date.now());
+    const seenLabels = seenReadyLabels.get(routeId) ?? new Set<string>();
+    for (const credential of available) seenLabels.add(credential.label);
+    seenReadyLabels.set(routeId, seenLabels);
+
+    let advanceResult: AttemptResult | undefined;
+    for (const credential of available) {
+      let freshCredential: ResolvedCredential;
+      try {
+        freshCredential = await refreshCredentialIfNeeded(state, providerId, credential, options?.signal);
+      } catch (error) {
+        if (!isInvalidRefreshTokenError(error)) throw error;
+        let reauthenticated: ResolvedCredential | undefined;
+        try { reauthenticated = await reauthenticateCredential(state, providerId, credential); } catch (loginError) {
+          state.runtimeContext?.ui.notify(`${getProviderLabel(providerId)} re-authentication failed: ${loginError instanceof Error ? loginError.message : String(loginError)}`, 'error');
+        }
+        if (!reauthenticated) {
+          const attemptAt = Date.now();
+          await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} authentication failure`, () => markSubscriptionAuthenticationFailed(providerId, credential.label, credential, INVALID_REFRESH_TOKEN_BACKOFF_MS, attemptAt));
+          authFailures.add(`${providerId}/${credential.label}`);
+          continue;
+        }
+        freshCredential = reauthenticated;
+      }
+      const result = await streamProviderAttempt(state, providerId, candidateModel, context, options, freshCredential, stream);
+      if (result.result === 'success') {
+        state.transportOnlyExhaustedPasses = 0;
+        if (subscriptionNeedsSuccessWrite(freshCredential, candidateModel.id)) await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} success`, () => markSubscriptionSuccess(providerId, freshCredential.label, result.attemptAt, candidateModel.id));
+        stream.end();
+        return;
+      }
+      if (result.result === 'fatal') { state.transportOnlyExhaustedPasses = 0; stream.end(); return; }
+      if (result.result === 'rate_limited' || result.classification?.status !== undefined || result.classification?.hadRetryAfterHeader === true) sawHttpEvidence = true;
+      const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
+      if (result.result === 'transient_exhausted') lastTransientFailure = result;
+      if (result.result === 'rate_limited' && (result.classification?.status === 401 || result.classification?.status === 403)) lastAuthRejection = result;
+      if (result.rateLimit && Object.keys(result.rateLimit.headers).length) lastRateLimit = { providerId, model: candidateModel, account: freshCredential.label, observation: result.rateLimit };
+      if (result.result === 'rate_limited' && result.retryAfterMs !== undefined) {
+        const persisted = await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} server cooldown`, () => markSubscriptionRateLimited(providerId, freshCredential.label, cooldownMs, result.attemptAt, Date.now(), result.rateLimit?.scope ?? { kind: 'account' }));
+        if (persisted) cooldownAttempts.set(`${routeId}/${freshCredential.label}`, result.attemptAt);
+        else localCoolingDeadlines.set(routeId, Math.max(localCoolingDeadlines.get(routeId) ?? 0, Date.now() + cooldownMs));
+      } else {
+        localCoolingDeadlines.set(routeId, Math.max(localCoolingDeadlines.get(routeId) ?? 0, Date.now() + cooldownMs));
+      }
+      advanceResult = result;
+    }
+
+    enqueueFreshRouteCandidates(candidates, queuedRouteIds, knownRoutes, seenReadyLabels, cooldownAttempts, localCoolingDeadlines);
+    if (advanceResult !== undefined) logRouteQueueAdvance(candidate, candidates[0], advanceResult);
+  }
+
+  const coolingDeadline = earliestCoolingDeadline([...knownRoutes.values()], localCoolingDeadlines);
+  const tried = [...attemptedRoutes].join(', ');
+  if (lastTransientFailure !== undefined) {
+    state.transportOnlyExhaustedPasses = sawHttpEvidence ? 0 : state.transportOnlyExhaustedPasses + 1;
+    if (state.transportOnlyExhaustedPasses >= POISONED_TRANSPORT_PASS_LIMIT && await activeTerminatePoisonedProcess(tried)) {
+      // The stream is deliberately left OPEN: the SIGTERM handler sees a live
+      // turn, so it either certifies a clean abort (→ the daemon respawns and
+      // resumes with a continuation prompt) or marks the turn dirty (→ the
+      // respawn re-cycles the turn). Ending the stream first could settle the
+      // turn idle before the signal lands, leaving the respawned node parked
+      // with a terminal error and nothing to re-drive it.
+      return;
+    }
+    const detail = lastTransientFailure.failureMessage ?? lastTransientFailure.classification?.reason ?? 'unknown connection failure';
+    emitTerminalError(stream, terminalModel, `Provider routes failed after transient retries: ${detail} (tried ${tried})`, lastTransientFailure.failure);
+    return;
+  }
+  state.transportOnlyExhaustedPasses = 0;
+  if (coolingDeadline !== undefined) {
+    const cooling = `cooling down ~${Math.ceil((coolingDeadline - Date.now()) / 1000)}s`;
+    const message = lastAuthRejection === undefined
+      ? `All provider routes are rate limited (${cooling}; tried ${tried})`
+      : `All provider routes are rate limited or rejected (${cooling}; last rejection ${lastAuthRejection.classification!.reason}: ${lastAuthRejection.failureMessage ?? 'no error message'}; tried ${tried})`;
+    emitCoolingError(stream, terminalModel, new ManagedProviderCoolingError(message, coolingDeadline), lastRateLimit);
+    return;
+  }
+  const authFailure = [...authFailures][0];
+  if (authFailure !== undefined) {
+    emitTerminalError(stream, terminalModel, `Provider authentication failed (invalid_grant) for ${authFailure}; re-authenticate the credential and retry (tried ${tried})`);
+    return;
+  }
+  emitTerminalError(stream, terminalModel, `All provider routes exhausted (tried ${tried})`);
+}
+
+// The earliest strictly-future deadline only when every attempted route is cooling.
+function earliestCoolingDeadline(
+  attempted: Iterable<RouteCandidate>,
+  localCoolingDeadlines: Map<string, number>,
+): number | undefined {
+  const now = Date.now();
+  let earliest: number | undefined;
+  let sawRoute = false;
+  for (const route of attempted) {
+    const localUntil = localCoolingDeadlines.get(route.routeId) ?? 0;
+    if (localUntil > now) { sawRoute = true; earliest = earliest === undefined ? localUntil : Math.min(earliest, localUntil); continue; }
+    if (!isManagedProvider(route.providerId)) return undefined;
+    const pool = readSubscriptionPool(route.providerId).filter((entry) => entry.authFailure === undefined);
+    // Routes with no usable credential were never runnable this turn, so they do
+    // not defeat the cooling outcome of another route. An auth-failed-only pool
+    // is likewise unauthenticated; a valid cooling row still contributes its
+    // deadline even when a sibling row carries invalid_grant.
+    if (pool.length === 0) continue;
+    sawRoute = true;
+    if (pool.some((entry) => coolingUntilFor(entry, route.model.id) <= now)) return undefined;
+    const routeEarliest = Math.min(...pool.map((entry) => coolingUntilFor(entry, route.model.id)));
+    earliest = earliest === undefined ? routeEarliest : Math.min(earliest, routeEarliest);
+  }
+  return sawRoute ? earliest : undefined;
+}
+
+// Emit the typed cooling terminal error, attaching its diagnostic (the earliest
+// deadline) to the assistant error message so the deadline survives verbatim into
+// agent_end.messages for the stophook to read.
+function emitCoolingError(
+  stream: AssistantMessageEventStream,
+  model: Model<any>,
+  error: ManagedProviderCoolingError,
+  rateLimit?: { providerId: string; model: Model<any>; account?: string; observation: RateLimitObservation },
+): void {
+  const message = toAssistantError(model, error.message);
+  message.diagnostics = [
+    error.toDiagnostic(),
+    ...(rateLimit === undefined ? [] : [providerFailureDiagnostic({
+      status: 429,
+      ratelimit: {
+        scope: describeRateLimitScope(rateLimit.observation.scope),
+        // The rate-limited route may be a fallback, not the model the error is stamped with.
+        model: `${rateLimit.providerId}/${rateLimit.model.id}`,
+        ...(rateLimit.observation.claim !== undefined ? { claim: rateLimit.observation.claim } : {}),
+        ...(rateLimit.account !== undefined ? { account: rateLimit.account } : {}),
+        headers: rateLimit.observation.headers,
+      },
+    })]),
+  ];
+  stream.push({ type: "error", reason: "error", error: message });
+  stream.end();
+}
+
+function streamManagedProvider(state: ProviderRotationState, model: Model<any>, context: TranscriptContext, options?: SimpleStreamOptions): AssistantMessageEventStream {
+  const stream = createAssistantMessageEventStream();
+
+  runManagedProvider(state, model, context, options, stream).catch((error) => {
+    stream.push({
+      type: "error",
+      reason: "error",
+      error: toAssistantError(model, error instanceof Error ? error.message : String(error)),
+    });
+    stream.end();
+  });
+
+  return stream;
+}
+
+function parseCommand(args: string): string[] {
+  return args
+    .trim()
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function parseProvider(value: string | undefined): ManagedProviderId | undefined {
+  return isManagedProvider(value) ? value : undefined;
+}
+
+/** Merged config for the NODE's scope (its own cwd/profile), not this
+ *  process's ambient one. */
+function readTargetLaunchConfig(state: ProviderRotationState, ctx: ExtensionContext): MergedLaunchConfig {
+  return readMergedLaunchConfig(ctx.cwd, configuredValue(state, 'profileId', 'CRTR_PROFILE_ID') || null);
+}
+
+function installDeclaredRouteProviders(state: ProviderRotationState, pi: ExtensionAPI, ctx: ExtensionContext, config: MergedLaunchConfig): void {
+  const providerIds = new Set(Object.values({ ...(config.modelRoutes ?? {}), ...(config.legacyModelRoutes ?? {}) }).map((route) => route.providerId));
+  for (const providerId of providerIds) {
+    if (isManagedProvider(providerId) || state.delegatedProviderStreams.has(providerId)) continue;
+    const provider = ctx.modelRegistry.getProvider?.(providerId);
+    const model = ctx.modelRegistry.getAll?.().find((entry) => entry.provider === providerId);
+    if (!provider || !model) continue;
+    state.delegatedProviderStreams.set(providerId, provider.streamSimple.bind(provider));
+    // `api` is required by pi whenever a registration supplies streamSimple.
+    // Re-registration merges this wrapper over the existing declaration, so the
+    // provider's models, auth, and captured composed transport remain intact.
+    pi.registerProvider(providerId, { api: model.api, streamSimple: (model, context, options) => streamManagedProvider(state, model, context, options) });
+  }
+}
+
+function updateRotationStatus(state: ProviderRotationState, ctx: ExtensionContext): void {
+  const current = getCurrentModelRef(ctx.model);
+  if (current && isManagedProvider(current.providerId)) setStatus(state, formatStatusLine(current.providerId, Date.now(), current.modelId));
+}
+
+/** Restore only when the deterministic route rank improves; no shared-home
+ * preferred-model state is needed or consulted. */
+async function restoreHigherRankIfAvailable(state: ProviderRotationState, pi: ExtensionAPI, ctx: ExtensionContext): Promise<boolean> {
+  if (!readRotationConfig().revertWhenAvailable) return false;
+  const liveThinking = ctx.thinkingLevel === undefined || ctx.thinkingLevel === 'off' ? undefined : ctx.thinkingLevel;
+  const request = modelRequestFromConfig(
+    `${ctx.model?.provider ?? ''}/${ctx.model?.id ?? ''}${liveThinking ? `:${liveThinking}` : ''}`,
+    configuredValue(state, 'modelIntent', 'CRTR_MODEL_INTENT'),
+    isExactModel(state),
+  );
+  if (!request || !ctx.model) return false;
+  const candidates = expandModelCandidates(
+    request,
+    configuredValue(state, 'nodeCwd', 'CRTR_NODE_CWD'),
+    configuredValue(state, 'profileId', 'CRTR_PROFILE_ID'),
+  );
+  const onLiveModel = (candidate: { providerId: string; modelId: string }): boolean =>
+    candidate.providerId === ctx.model?.provider && candidate.modelId === ctx.model?.id;
+  const liveRank = (candidates.find((candidate) => onLiveModel(candidate) && candidate.thinkingLevel === liveThinking) ?? candidates.find(onLiveModel))?.rank;
+  if (liveRank === undefined) return false;
+  const preferred = candidates.find((candidate) => candidate.rank < liveRank && resolveProviderCandidates([{
+    ...candidate,
+    ...probeRouteAvailability(candidate, ctx.modelRegistry),
+    automaticFallback: true,
+  }]).candidates.length > 0);
+  if (!preferred) return false;
+  const model = ctx.modelRegistry.find(preferred.providerId, preferred.modelId);
+  if (!model || !await pi.setModel(model)) return false;
+  pi.setThinkingLevel((preferred.thinkingLevel ?? 'off') as any);
+  return true;
+}
+
+// Manual-code input is a human-in-the-loop OAuth round-trip (open link, log in on
+// whatever device, copy the localhost redirect URL back) that routinely exceeds
+// DEFAULT_DIALOG_TIMEOUT_MS -- give it a human-scale bound instead of the ordinary
+// confirm/select default.
+const OAUTH_MANUAL_INPUT_TIMEOUT_MS = 600_000;
+
+/**
+ * pi-ai races the manual-code-paste dialog against its loopback callback server. When the
+ * callback supplies a code, the manual-input promise can remain pending, so `run` receives:
+ *  - `readCode`, a `ctx.ui.input` wrapper with an AbortSignal. Aborting it removes the pending
+ *    broker entry and emits an `extension_ui_dismiss` frame for exactly that dialog.
+ *  - `dismissManual`, which aborts the signal at the post-code `onProgress` boundary before
+ *    the token exchange completes. `onProgress` is emitted only after a code is available, so
+ *    dismissing then cannot close a dialog the user still needs; `finally` covers paths without
+ *    progress, and repeated AbortController calls are inert.
+ *
+ * `undefined` from `readCode` means cancellation or timeout. It throws so OAuth ends directly
+ * instead of opening a second paste-only dialog.
+ */
+export async function loginWithManualInputCleanup<T>(
+  ctx: ExtensionContext,
+  run: (
+    readCode: (title: string, placeholder: string) => Promise<string>,
+    dismissManual: () => void,
+  ) => Promise<T>,
+): Promise<T> {
+  const controller = new AbortController();
+  const readCode = async (title: string, placeholder: string): Promise<string> => {
+    const result = await ctx.ui.input(title, placeholder, { timeout: OAUTH_MANUAL_INPUT_TIMEOUT_MS, signal: controller.signal });
+    if (result === undefined) throw new Error("OAuth login cancelled");
+    return result;
+  };
+  try {
+    return await run(readCode, () => controller.abort());
+  } finally {
+    controller.abort();
+  }
+}
+
+// The manual-code dialog carries the authorize URL in its title (rendered as a tappable link
+// on web), so a headless remote box where `openBrowser` opens nothing still has a real path
+// through login. pi's own `manual_code` message is URL-less, hence these per-provider titles.
+const MANUAL_CODE_DIALOG: Record<ManagedProviderId, { title: (url: string | undefined) => string; placeholder: string }> = {
+  [ANTHROPIC_PROVIDER_ID]: {
+    title: (url) => `Open this URL to authenticate Claude:\n${url}\n\nPaste the redirect URL or code`,
+    placeholder: "http://localhost:53692/callback?...",
+  },
+  [OPENAI_CODEX_PROVIDER_ID]: {
+    title: (url) => `Open this URL to authenticate OpenAI Codex:\n${url}\n\nPaste the redirect URL or code`,
+    placeholder: "http://localhost:1455/auth/callback?...",
+  },
+  [OPENAI_CHATGPT_PROVIDER_ID]: {
+    title: (url) => `Open this URL to sign in with ChatGPT:\n${url}\n\nPaste the final redirect URL`,
+    placeholder: "http://127.0.0.1:1455/auth/callback?...",
+  },
+};
+
+// This extension adapts the provider OAuth interaction onto `ctx.ui`. The attach viewer and
+// `crtr sys setup` use LoginDialogComponent with `core/auth-interaction.ts`; the broker uses
+// the dialog primitives below.
+async function loginProvider(providerId: ManagedProviderId, ctx: ExtensionContext): Promise<LoginCredential> {
+  const oauth = oauthFlow(providerId, ctx);
+  const manual = MANUAL_CODE_DIALOG[providerId];
+  const controller = new AbortController();
+  let authorizeUrl: string | undefined;
+  // ChatGPT sign-in identifies this install to OpenAI by a stable device UUID.
+  const loginOptions = providerId === OPENAI_CHATGPT_PROVIDER_ID ? { getDeviceId: openAIDeviceId } : undefined;
+  return loginWithManualInputCleanup(ctx, (readCode, dismissManual) =>
+    oauth.login({
+      signal: controller.signal,
+      notify: (event: AuthEvent): void => {
+        switch (event.type) {
+          case "auth_url":
+            authorizeUrl = event.url;
+            openBrowser(event.url);
+            if (event.instructions) ctx.ui.notify(event.instructions, "info");
+            break;
+          case "device_code":
+            openBrowser(event.verificationUri);
+            ctx.ui.notify(`Enter code ${event.userCode} at ${event.verificationUri}`, "info");
+            break;
+          case "progress":
+            // Progress follows receipt of an OAuth code, so dismiss the now-unneeded manual
+            // dialog before token exchange. The browser path may emit no progress; `finally`
+            // closes that dialog when the OAuth attempt settles.
+            dismissManual();
+            ctx.ui.notify(event.message, "info");
+            break;
+          case "info":
+            ctx.ui.notify(event.message, "info");
+            break;
+        }
+      },
+      prompt: async (prompt: AuthPrompt): Promise<string> => {
+        if (prompt.type === "manual_code") return readCode(manual.title(authorizeUrl), manual.placeholder);
+        if (prompt.type === "select") {
+          // Codex now opens its login with a browser-vs-device-code choice.
+          const labels = prompt.options.map((option) => option.label);
+          const chosen = await ctx.ui.select(prompt.message, labels);
+          const selected = chosen === undefined ? undefined : prompt.options[labels.indexOf(chosen)];
+          if (!selected) throw new Error("OAuth login cancelled");
+          return selected.id;
+        }
+        return (await ctx.ui.input(prompt.message, prompt.placeholder ?? "")) ?? "";
+      },
+    }, loginOptions),
+  ).finally(() => controller.abort());
+}
+
+export function createProviderRotationExtension(options?: ProviderRotationOptions): (pi: ExtensionAPI) => Promise<void> {
+  const state = createProviderRotationState(options);
+
+  return async (pi: ExtensionAPI): Promise<void> => {
+    state.extensionAPI = pi;
+
+    pi.registerProvider(ANTHROPIC_PROVIDER_ID, {
+      api: "anthropic-messages",
+      streamSimple: (model, context, streamOptions) => streamManagedProvider(state, model, context, streamOptions),
+    });
+
+    pi.registerProvider(OPENAI_CODEX_PROVIDER_ID, {
+      api: "openai-codex-responses",
+      streamSimple: (model, context, streamOptions) => streamManagedProvider(state, model, context, streamOptions),
+    });
+
+    // pi's built-in `openai` provider (Responses API). Its pool holds ChatGPT sign-ins; with an
+    // empty pool the route falls back to the provider's own auth (OPENAI_API_KEY / auth.json).
+    pi.registerProvider(OPENAI_CHATGPT_PROVIDER_ID, {
+      api: "openai-responses",
+      streamSimple: (model, context, streamOptions) => streamManagedProvider(state, model, context, streamOptions),
+    });
+
+    pi.on("session_start", async (_event, ctx) => {
+      state.runtimeContext = ctx;
+      const config = readTargetLaunchConfig(state, ctx);
+      state.providerOptions = config.providerOptions;
+      installDeclaredRouteProviders(state, pi, ctx, config);
+      updateRotationStatus(state, ctx);
+    });
+
+    pi.on("before_agent_start", async (_event, ctx) => {
+      state.runtimeContext = ctx;
+      // Re-read per turn: this is what makes a provider-options toggle apply to
+      // a broker that is already running, on its next turn.
+      state.providerOptions = readTargetLaunchConfig(state, ctx).providerOptions;
+      const restored = await restoreHigherRankIfAvailable(state, pi, ctx);
+      if (restored && ctx.model && isManagedProvider(ctx.model.provider)) {
+        logRotation(`restored higher-ranked route ${ctx.model.provider}/${ctx.model.id}`);
+        setStatus(state, formatStatusLine(ctx.model.provider, Date.now(), ctx.model.id));
+      }
+    });
+
+    pi.on("model_select", async (_event, ctx) => {
+      state.runtimeContext = ctx;
+      updateRotationStatus(state, ctx);
+    });
+
+    pi.registerCommand("provider-sub", {
+      description: "Manage subscription credential pools for provider rotation",
+      handler: async (args, ctx) => {
+        const [providerArg, verb, ...rest] = parseCommand(args);
+        const providerId = parseProvider(providerArg);
+        if (!providerId) {
+          ctx.ui.notify("Usage: /provider-sub <anthropic|openai-codex|openai> <list|add|select|rm>", "error");
+          return;
+        }
+
+        const action = verb === "rm" ? "remove" : verb || "list";
+
+        if (action === "status" || action === "list") {
+          const pool = readSubscriptionPool(providerId);
+          const lines = [formatStatusLine(providerId, Date.now(), ctx.model?.provider === providerId ? ctx.model.id : undefined), ""];
+          for (const [index, entry] of pool.entries()) {
+            const cooling = formatCooldowns(entry);
+            const cooldown = cooling ? ` ${cooling}` : "";
+            const account = entry.accountId ? ` account=${shortAccountId(entry.accountId)}` : "";
+            lines.push(`${index + 1}. ${entry.label}${account}${cooldown}`);
+          }
+          ctx.ui.notify(lines.join("\n"), "info");
+          return;
+        }
+
+        if (action === "add") {
+          if (!ctx.hasUI) {
+            ctx.ui.notify(`${getProviderLabel(providerId)} login requires an interactive UI.`, "error");
+            return;
+          }
+          const pool = readSubscriptionPool(providerId);
+          const label = (rest.join(" ") || (await ctx.ui.input(`${getProviderLabel(providerId)} subscription label`, "")) || "").trim();
+          if (!label) return;
+          if (pool.some((entry) => entry.label.toLowerCase() === label.toLowerCase())) {
+            ctx.ui.notify(`${getProviderLabel(providerId)} subscription already exists: ${label}`, "error");
+            return;
+          }
+          try {
+            const cred = await activeLoginForProvider(providerId, ctx);
+            const identity = await enrichManagedLoginIdentity(providerId, cred);
+            // Explicit add always creates a new label, so a matching real account is rejected by
+            // the locked uniqueness gate rather than creating a second quota slot.
+            await addSubscription(providerId, {
+              label,
+              refresh: cred.refresh,
+              access: cred.access,
+              expires: cred.expires,
+              ...(identity.accountId ? { accountId: identity.accountId } : {}),
+              ...(loginClientId(cred) ? { clientId: loginClientId(cred)! } : {}),
+              rateLimitedUntil: 0,
+              lastAttemptAt: 0,
+              lastRateLimitedAt: 0,
+            });
+            logRotation(`added ${getProviderLabel(providerId)} subscription "${label}"`);
+            ctx.ui.notify(`Added ${getProviderLabel(providerId)} subscription: ${label}`, "info");
+            updateRotationStatus(state, ctx);
+          } catch (error) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
+          return;
+        }
+
+        if (action === "select") {
+          const ref = rest.join(" ");
+          if (!ref) {
+            ctx.ui.notify(`Usage: /provider-sub ${providerId} select <label|index>`, "error");
+            return;
+          }
+          try {
+            await promoteSubscription(providerId, ref);
+            logRotation(`selected ${getProviderLabel(providerId)} subscription "${ref}"`);
+            ctx.ui.notify(`Preferred ${getProviderLabel(providerId)} subscription: ${ref}`, "info");
+            updateRotationStatus(state, ctx);
+          } catch (error) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
+          return;
+        }
+
+        if (action === "remove") {
+          const ref = rest.join(" ");
+          if (!ref) {
+            ctx.ui.notify(`Usage: /provider-sub ${providerId} rm <label|index>`, "error");
+            return;
+          }
+          try {
+            await removeManagedAccount(providerId, ref);
+            logRotation(`removed ${getProviderLabel(providerId)} subscription "${ref}"`);
+            ctx.ui.notify(`Removed ${getProviderLabel(providerId)} subscription: ${ref}`, "info");
+            updateRotationStatus(state, ctx);
+          } catch (error) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
+          return;
+        }
+
+        ctx.ui.notify(`Unknown /provider-sub verb: ${verb}`, "error");
+      },
+    });
+  };
+}
+
+const defaultProviderRotationExtension = createProviderRotationExtension();
+export default defaultProviderRotationExtension;