@north-light/crouter 0.3.161 → 0.3.163

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

@@ -17,7 +17,6 @@ import {
   OPENAI_CODEX_PROVIDER_ID,
   INVALID_REFRESH_TOKEN_BACKOFF_MS,
   formatStatusLine,
-  getLadderProviderId,
   getProviderLabel,
   isManagedProvider,
   isInvalidRefreshTokenError,
@@ -32,19 +31,14 @@ import {
   readSubscriptionPool,
   refreshSubscriptionCredential,
   removeManagedAccount,
-  resolveFallbackTarget,
   resolveProviderCandidates,
-  restorePreferredModelIfPossible,
-  switchToFallbackIfPossible,
   upsertSubscriptionWithUniqueAccount,
-  type FallbackTarget,
   type ManagedProviderId,
   type SubscriptionCredential,
 } from "../../../core/subscription-state.js";
-import {
-  ManagedProviderCoolingError,
-  readManagedProviderRotationPolicy,
-} from "../../../core/runtime/managed-provider-cooling.js";
+import { readMergedLaunchConfig } from "../../../core/config.js";
+import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from "../../../core/model-routes.js";
+import { ManagedProviderCoolingError } from "../../../core/runtime/managed-provider-cooling.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
@@ -68,6 +62,13 @@ const SUBSCRIPTION_LOCK_RETRY_BACKOFFS_MS = [25, 75, 150];
 let runtimeContext: ExtensionContext | undefined;
 let extensionAPI: ExtensionAPI | undefined;
 
+// 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: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+const delegatedProviderStreams = new Map<string, ProviderStream>();
+
 type AttemptResult = {
   result: "success" | "rate_limited" | "transient_exhausted" | "fatal";
   retryAfterMs?: number;
@@ -369,37 +370,39 @@ export function __setStreamForProviderForTest(fn: typeof defaultStreamForProvide
 
 /** Test-only seam: exercise `fallbackRejectionHint` for one rejection discriminant
  *  (with an optional resolved-but-rejected candidate) without staging a full turn. */
-export function __fallbackRejectionHintForTest(reason: FallbackRejectionReason, candidate?: FallbackTarget): string {
-  return fallbackRejectionHint({ reason, candidate });
-}
-
 // 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(
-  providerId: ManagedProviderId,
+  providerId: string,
   model: Model<any>,
   context: Context,
   options: SimpleStreamOptions | undefined,
-  credential: ResolvedCredential,
+  credential: ResolvedCredential | undefined,
   outer: AssistantMessageEventStream,
 ): Promise<AttemptResult> {
   for (let attempt = 1; ; attempt++) {
     const attemptAt = Date.now();
     let observedStatus: number | undefined;
     let requestedRetryAfterMs: number | undefined;
-    const inner = streamForProvider(model, context, {
+    const streamOptions = {
       ...options,
-      apiKey: credential.access,
-      onResponse: async (response, responseModel) => {
+      ...(credential ? { apiKey: credential.access } : {}),
+      onResponse: async (response: { status: number; headers: Record<string, string> }, responseModel: Model<any>) => {
         observedStatus = response.status;
         if (response.status === 429 || response.status === 503) {
           requestedRetryAfterMs = retryAfterMs(response.headers);
         }
-        await options?.onResponse?.(response, responseModel);
+        await options?.onResponse?.(response as any, responseModel);
       },
-    });
+    };
+    const provider = runtimeContext?.modelRegistry.getProvider?.(model.provider);
+    const inner = credential
+      ? streamForProvider(model, context, streamOptions)
+      : delegatedProviderStreams.get(providerId)?.(model, context, streamOptions)
+        ?? provider?.streamSimple(model, context, streamOptions)
+        ?? streamForProvider(model, context, streamOptions);
 
     const bufferedEvents: Parameters<AssistantMessageEventStream["push"]>[0][] = [];
     let sawContent = false;
@@ -493,7 +496,7 @@ async function streamProviderAttempt(
       return { result: "transient_exhausted", attemptAt, classification, attempts: attempt };
     }
     logRotation(
-      `${getProviderLabel(providerId)} subscription "${credential.label}" hit a transient error (${classification.reason}, status=${classification.status ?? "n/a"}); retrying same credential in ${backoffMs}ms (attempt ${attempt + 1})`,
+      `${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);
   }
@@ -504,446 +507,207 @@ function emitTerminalError(stream: AssistantMessageEventStream, model: Model<any
   stream.end();
 }
 
-// Why a candidate fallback was rejected -- each reason gets its OWN accurate hint
-// (`fallbackRejectionHint`) so the terminal error never gives advice that can't fix the
-// actual blocker. Only `no_credentials` is a genuine "go authenticate" case; the others
-// are config/exhaustion states where telling the user to authenticate would be misleading.
-type FallbackRejectionReason =
-  | "no_ladder_entry"
-  | "already_attempted"
-  | "no_credentials"
-  | "model_unregistered"
-  | "cooling"
-  | "provider_pinned";
-
-// On rejection we carry the resolved-but-rejected `candidate` FallbackTarget whenever one
-// exists (every reason except `no_ladder_entry`, where no target resolved at all), so the
-// hint can name the exact provider/model and build an executable repair command from the
-// candidate's config ladder key + strength.
-type FallbackResolution =
-  | { target: FallbackTarget }
-  | { target?: undefined; reason: FallbackRejectionReason; candidate?: FallbackTarget };
-
-// Cross-provider fallback requires a target that is usable right now: authenticated
-// (its subscription pool has at least one credential, even if currently
-// cooling down) AND registered in the model registry -- rather than blindly switching the
-// session model to a provider nobody logged into. Returns the rejection reason (config has
-// no ladder rung, the target was already tried this turn, the target has zero credentials,
-// or its resolved model isn't in the registry) rather than just `undefined`, so callers can
-// surface an accurate terminal error instead of always defaulting to "authenticate a
-// fallback provider" -- which is actively wrong when the real blocker is a stale ladder.
-function resolveViableFallback(
-  providerId: ManagedProviderId,
-  modelId: string | undefined,
-  attempted: Set<ManagedProviderId>,
-): FallbackResolution {
-  const target = resolveFallbackTarget(providerId, modelId, readRotationConfig(), extensionAPI?.getThinkingLevel?.());
-  if (!target) return { reason: "no_ladder_entry" };
-  if (attempted.has(target.providerId)) return { reason: "already_attempted", candidate: target };
-  // Pool occupancy IS authentication: every stored row carries a token pair, so an empty pool
-  // means switching the session model onto this provider would make pi fail the NEXT turn with a
-  // non-retryable "Provider is not configured" that no agent can clear from inside its own turn.
-  const pool = readSubscriptionPool(target.providerId);
-  const resolution = resolveProviderCandidates([{
-    providerId: target.providerId,
-    modelId: target.modelId,
-    thinkingLevel: target.thinkingLevel,
-    registered: Boolean(runtimeContext?.modelRegistry.find(target.providerId, target.modelId)),
-    authenticated: pool.length > 0,
-    coolingUntil: pool.length > 0 && pool.every((entry) => (entry.rateLimitedUntil || 0) > Date.now())
-      ? Math.min(...pool.map((entry) => entry.rateLimitedUntil || 0))
-      : undefined,
-  }]);
-  if (resolution.candidates.length > 0) return { target };
-  switch (resolution.rejected[0]?.reason) {
-    case "unauthenticated": return { reason: "no_credentials", candidate: target };
-    case "unregistered": return { reason: "model_unregistered", candidate: target };
-    // Do not churn the session model merely to wait on an unavailable target.
-    // The caller includes this candidate's pool in the typed cooling deadline,
-    // so the broker can re-drive when either provider becomes ready.
-    case "cooling": return { reason: "cooling", candidate: target };
-    default: return { reason: "no_credentials", candidate: target };
-  }
-}
-
-// Actionable hint appended to a terminal error when no fallback is viable. Each rejection
-// reason gets advice that can resolve it; only `no_credentials` advises authentication because
-// it is the sole case where a login supplies the missing capability.
-function fallbackRejectionHint(resolution: FallbackResolution): string {
-  if (resolution.target) return "try again later";
-  const candidate = resolution.candidate;
-  switch (resolution.reason) {
-    case "no_credentials": {
-      const who = candidate ? ` (${getProviderLabel(candidate.providerId)}, e.g. /provider-sub ${candidate.providerId} add)` : " with /provider-sub";
-      return `authenticate a fallback provider${who}, or try again later`;
-    }
-    case "model_unregistered": {
-      // Repair command must be EXECUTABLE as printed: `--value`, and the CONFIG ladder
-      // provider key (`openai`, not the runtime `openai-codex`) plus the candidate's own
-      // strength -- so the user pastes it, swaps in an installed model id, and it works.
-      const ladderKey = candidate ? getLadderProviderId(candidate.providerId) : "<provider>";
-      const strength = candidate?.strength ?? "<strength>";
-      const named = candidate ? candidate.label : "the configured fallback";
-      return `configured fallback ${named} is not in this build's model registry -- the modelLadders config is out of sync with the installed model catalog. Point it at an installed model with \`crtr sys config set modelLadders.${ladderKey}.${strength} --value <installed-model-id>\`, or upgrade/downgrade to a build whose ladder matches`;
-    }
-    case "already_attempted":
-      return "every managed provider was already tried this turn and is exhausted or cooling down -- try again later";
-    case "cooling":
-      return "the configured fallback provider is also cooling down -- retrying when the first provider becomes ready";
-    case "provider_pinned":
-      return "the selected provider is explicitly pinned -- retrying it when its first credential becomes ready";
-    case "no_ladder_entry":
-      return "no cross-provider fallback is configured for this model -- set one with `crtr sys config set modelLadders.<provider>.<strength> --value <model-id>`, or try again later";
-  }
-}
-
-// Switches the session model to an already-viability-checked fallback target. On the rare
-// race where the switch itself still fails (e.g. `setModel` rejects it), emits a graceful,
-// actionable terminal error on `stream` instead of throwing a generic "failed to switch".
-async function switchToFallbackModel(
-  stream: AssistantMessageEventStream,
-  model: Model<any>,
-  originalModel: { providerId: ManagedProviderId; modelId: string },
-): Promise<FallbackTarget | undefined> {
-  const ctx = runtimeContext;
-  if (!extensionAPI || !ctx) {
-    emitTerminalError(stream, model, `Provider fallback unavailable: runtime not initialized for ${originalModel.providerId}/${originalModel.modelId}`);
-    return undefined;
-  }
-  const target = await switchToFallbackIfPossible(extensionAPI, ctx, originalModel);
-  if (!target) {
-    emitTerminalError(stream, model, `Provider fallback unavailable: failed to switch models for ${getProviderLabel(originalModel.providerId)}`);
-    return undefined;
-  }
-  return target;
-}
-
-// Drives the ordered recovery candidates for one managed turn. Each candidate is a
-// provider/model whose ready credentials are tried in order. A provider returns to
-// the list only for a newly ready label or a success that followed this turn's
-// cooldown, so bookkeeping updates never retry an exhausted pool.
-type ManagedProviderCandidate = {
+// 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>;
-  providerId: ManagedProviderId;
+  thinkingLevel: string | undefined;
 };
 
-type ManagedProviderTerminalState = {
-  model: Model<any>;
-  providerId: ManagedProviderId;
-  currentPool: SubscriptionCredential[];
-  fallbackResolution: FallbackResolution;
-};
-
-function credentialKey(providerId: ManagedProviderId, label: string): string {
-  return `${providerId}/${label}`;
-}
-
-function enqueueFreshProviderCandidates(
-  candidates: ManagedProviderCandidate[],
-  queuedProviderIds: Set<ManagedProviderId>,
-  knownModels: Map<ManagedProviderId, Model<any>>,
-  seenReadyLabels: Map<ManagedProviderId, Set<string>>,
+function enqueueFreshRouteCandidates(
+  candidates: RouteCandidate[],
+  queuedRouteIds: Set<string>,
+  knownRoutes: Map<string, RouteCandidate>,
+  seenReadyLabels: Map<string, Set<string>>,
   cooldownAttempts: Map<string, number>,
-  localCoolingDeadlines: Map<ManagedProviderId, number>,
+  localCoolingDeadlines: Map<string, number>,
 ): void {
   const now = Date.now();
-  for (const [providerId, model] of knownModels) {
-    if (queuedProviderIds.has(providerId) || (localCoolingDeadlines.get(providerId) ?? 0) > now) continue;
-    const seenLabels = seenReadyLabels.get(providerId) ?? new Set<string>();
-    const hasFreshCredential = readSubscriptionPool(providerId).some((credential) => {
-      if (credential.rateLimitedUntil && credential.rateLimitedUntil > now) return false;
-      const cooldownAttempt = cooldownAttempts.get(credentialKey(providerId, credential.label));
+  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 || (credential.rateLimitedUntil || 0) > now) return false;
+      const cooldownAttempt = cooldownAttempts.get(`${routeId}/${credential.label}`);
       return !seenLabels.has(credential.label) || (cooldownAttempt !== undefined && credential.lastAttemptAt > cooldownAttempt);
     });
     if (hasFreshCredential) {
-      candidates.push({ model, providerId });
-      queuedProviderIds.add(providerId);
+      candidates.push(candidate);
+      queuedRouteIds.add(routeId);
     }
   }
 }
 
-// Drives managed providers through an explicit candidate list. The list is exhausted
-// only when no provider has a newly-ready credential or recovered cooldown and no viable fallback remains.
-// The broker owns delayed retry through typed cooling errors; this loop never sleeps
-// while waiting for a provider pool to recover.
+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(
   model: Model<any>,
   context: Context,
   options: SimpleStreamOptions | undefined,
   stream: AssistantMessageEventStream,
 ): Promise<void> {
-  const initialProviderId = model.provider as ManagedProviderId;
-  const candidates: ManagedProviderCandidate[] = [{ model, providerId: initialProviderId }];
-  const queuedProviderIds = new Set<ManagedProviderId>([initialProviderId]);
-  const knownModels = new Map<ManagedProviderId, Model<any>>([[initialProviderId, model]]);
-  const attempted = new Set<ManagedProviderId>();
+  const liveThinking = runtimeContext?.thinkingLevel === undefined || runtimeContext?.thinkingLevel === 'off'
+    ? undefined
+    : runtimeContext.thinkingLevel;
+  const request = modelRequestFromConfig(`${model.provider}/${model.id}${liveThinking ? `:${liveThinking}` : ''}`, process.env['CRTR_MODEL_INTENT'], false);
+  const expanded = request ? expandModelCandidates(request, process.env['CRTR_NODE_CWD'], process.env['CRTR_PROFILE_ID']) : [];
+  const liveRank = expanded.find((candidate) => candidate.providerId === model.provider && candidate.modelId === model.id && candidate.thinkingLevel === liveThinking)?.rank ?? 0;
+  const routeCandidates: RouteCandidate[] = expanded.slice(liveRank)
+    .map((route) => {
+      const registry = 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: route.thinkingLevel };
+    })
+    .filter((candidate): candidate is RouteCandidate => candidate !== undefined);
+  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) => isLiveRoute(candidate) || !isManagedProvider(candidate.providerId) || readSubscriptionPool(candidate.providerId).some((entry) => entry.authFailure === undefined && (entry.rateLimitedUntil || 0) <= 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<ManagedProviderId, number>();
-  const seenReadyLabels = new Map<ManagedProviderId, Set<string>>();
+  const localCoolingDeadlines = new Map<string, number>();
+  const seenReadyLabels = new Map<string, Set<string>>();
   const cooldownAttempts = new Map<string, number>();
-  let terminal: ManagedProviderTerminalState | undefined;
+  let terminalModel = model;
 
   for (let candidate = candidates.shift(); candidate !== undefined; candidate = candidates.shift()) {
-    const { model: candidateModel, providerId } = candidate;
-    queuedProviderIds.delete(providerId);
-    knownModels.set(providerId, candidateModel);
-    attempted.add(providerId);
-
-    const liveModel = getCurrentModelRef(runtimeContext?.model);
-    if (liveModel && (liveModel.providerId !== providerId || liveModel.modelId !== candidateModel.id)) {
-      const target = await switchToFallbackModel(stream, candidateModel, liveModel);
-      if (!target) return; // terminal error already emitted
-      if (target.providerId !== providerId || target.modelId !== candidateModel.id) {
-        emitTerminalError(stream, candidateModel, `Provider re-entry unavailable: expected ${providerId}/${candidateModel.id} but switched to ${target.label}`);
-        return;
-      }
-      logRotation(`${getProviderLabel(liveModel.providerId)} pool recovered -> ${target.label}`);
-      setStatus(`${getProviderLabel(liveModel.providerId)} -> ${target.label}`);
+    const { routeId, providerId, model: candidateModel } = candidate;
+    queuedRouteIds.delete(routeId);
+    knownRoutes.set(routeId, candidate);
+    attemptedRoutes.add(routeId);
+    terminalModel = candidateModel;
+
+    if (!await switchToRoute(extensionAPI!, runtimeContext!, candidate)) {
+      emitTerminalError(stream, candidateModel, `Provider route ${routeId} is unavailable: failed to select ${providerId}/${candidateModel.id}`);
+      return;
     }
 
-    const rawPool = readSubscriptionPool(providerId);
-    for (const entry of rawPool) {
-      if (entry.authFailure === "invalid_grant") authFailures.add(`${providerId}/${entry.label}`);
+    if (!isManagedProvider(providerId)) {
+      const result = await streamProviderAttempt(providerId, candidateModel, context, options, undefined, stream);
+      if (result.result === 'success') { stream.end(); return; }
+      if (result.result === 'fatal') { stream.end(); return; }
+      const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
+      localCoolingDeadlines.set(routeId, Math.max(localCoolingDeadlines.get(routeId) ?? 0, Date.now() + cooldownMs));
+      logRouteQueueAdvance(candidate, candidates[0], result);
+      continue;
     }
-    const available = rawPool.filter((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= Date.now());
-    const seenLabels = seenReadyLabels.get(providerId) ?? new Set<string>();
+
+    const rawPool = readSubscriptionPool(providerId);
+    for (const entry of rawPool) if (entry.authFailure === 'invalid_grant') authFailures.add(`${providerId}/${entry.label}`);
+    const available = rawPool.filter((entry) => entry.authFailure === undefined && (!entry.rateLimitedUntil || entry.rateLimitedUntil <= Date.now()));
+    const seenLabels = seenReadyLabels.get(routeId) ?? new Set<string>();
     for (const credential of available) seenLabels.add(credential.label);
-    seenReadyLabels.set(providerId, seenLabels);
+    seenReadyLabels.set(routeId, seenLabels);
 
+    let advanceResult: AttemptResult | undefined;
     for (const credential of available) {
       let freshCredential: ResolvedCredential;
       try {
         freshCredential = await refreshCredentialIfNeeded(providerId, credential);
       } catch (error) {
-        const attemptAt = Date.now();
-        if (isInvalidRefreshTokenError(error)) {
-          let reauthenticated: ResolvedCredential | undefined;
-          try {
-            reauthenticated = await reauthenticateCredential(providerId, credential);
-          } catch (loginError) {
-            runtimeContext?.ui.notify(
-              `${getProviderLabel(providerId)} re-authentication failed: ${loginError instanceof Error ? loginError.message : String(loginError)}`,
-              "error",
-            );
-          }
-          if (reauthenticated) {
-            freshCredential = reauthenticated;
-          } else {
-            // Keep the unusable credential out of ordinary rotation, but retain
-            // its auth cause for this turn. A 30-day exclusion is not a transient
-            // rate limit and must never author an auto rate-limit recovery fault.
-            await recordSubscriptionMutation(
-              `recording ${getProviderLabel(providerId)} authentication failure`,
-              () => markSubscriptionAuthenticationFailed(providerId, credential.label, INVALID_REFRESH_TOKEN_BACKOFF_MS, attemptAt),
-            );
-            authFailures.add(`${providerId}/${credential.label}`);
-            setStatus(formatStatusLine(providerId));
-            continue;
-          }
-        } else {
-          throw error;
+        if (!isInvalidRefreshTokenError(error)) throw error;
+        let reauthenticated: ResolvedCredential | undefined;
+        try { reauthenticated = await reauthenticateCredential(providerId, credential); } catch (loginError) {
+          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, INVALID_REFRESH_TOKEN_BACKOFF_MS, attemptAt));
+          authFailures.add(`${providerId}/${credential.label}`);
+          continue;
         }
+        freshCredential = reauthenticated;
       }
       const result = await streamProviderAttempt(providerId, candidateModel, context, options, freshCredential, stream);
-
-      if (result.result === "success") {
-        // The common healthy state already has nothing to clear. Avoid two global
-        // file locks just to advance display-only lastAttemptAt telemetry.
-        if (freshCredential.rateLimitedUntil || freshCredential.authFailure) {
-          await recordSubscriptionMutation(
-            `recording ${getProviderLabel(providerId)} success`,
-            () => markSubscriptionSuccess(providerId, freshCredential.label, result.attemptAt),
-          );
-        }
-        logRotation(`${getProviderLabel(providerId)} subscription "${freshCredential.label}" succeeded; cooldown cleared`);
-        setStatus(formatStatusLine(providerId));
+      if (result.result === 'success') {
+        if (freshCredential.rateLimitedUntil || freshCredential.authFailure) await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} success`, () => markSubscriptionSuccess(providerId, freshCredential.label, result.attemptAt));
         stream.end();
         return;
       }
-
-      if (result.result === "rate_limited") {
-        const cooldownMs = result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS;
-        if (result.retryAfterMs !== undefined) {
-          // A server-declared deadline is authoritative for every broker sharing
-          // this credential, so persist it in the cross-process pool.
-          const persisted = await recordSubscriptionMutation(
-            `recording ${getProviderLabel(providerId)} server cooldown`,
-            () => markSubscriptionRateLimited(providerId, freshCredential.label, cooldownMs, result.attemptAt),
-          );
-          if (persisted) {
-            // A zero server deadline is immediately eligible, but it still needs
-            // a later causal success before it becomes a new recovery candidate.
-            cooldownAttempts.set(credentialKey(providerId, freshCredential.label), result.attemptAt);
-          } else {
-            localCoolingDeadlines.set(
-              providerId,
-              Math.max(localCoolingDeadlines.get(providerId) ?? 0, Date.now() + cooldownMs),
-            );
-          }
-        } else {
-          // A headerless 429/usage-limit response proves only that this request
-          // failed. Persisting an invented deadline globally let one busy node
-          // gate unrelated nodes that were succeeding concurrently. Keep the
-          // short probe deadline turn-local instead.
-          localCoolingDeadlines.set(
-            providerId,
-            Math.max(localCoolingDeadlines.get(providerId) ?? 0, Date.now() + cooldownMs),
-          );
-        }
-        const retryAfterPart = result.retryAfterMs !== undefined ? `retry-after=${Math.ceil(result.retryAfterMs / 1000)}s` : "no retry-after header (default backoff)";
-        logRotation(
-          `${getProviderLabel(providerId)} subscription "${freshCredential.label}" rate-limited (status=${result.classification?.status ?? "n/a"}, reason=${result.classification?.reason ?? "unclassified"}, ${retryAfterPart}); ${result.retryAfterMs !== undefined ? "shared cooldown" : "turn-local retry backoff"} ${Math.ceil(cooldownMs / 1000)}s, trying next credential`,
-        );
-        runtimeContext?.ui.notify?.(
-          `${getProviderLabel(providerId)} "${freshCredential.label}" rate-limited (${result.retryAfterMs !== undefined ? "cooling down" : "retrying this turn in"} ${Math.ceil(cooldownMs / 1000)}s); rotating to another credential/provider.`,
-          "warning",
-        );
-        continue;
+      if (result.result === 'fatal') { stream.end(); return; }
+      const cooldownMs = result.result === 'rate_limited' ? result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS : TRANSIENT_ROTATE_COOLDOWN_MS;
+      if ((result.result === 'rate_limited' && result.retryAfterMs !== undefined) || result.result === 'transient_exhausted') {
+        const source = result.result === 'transient_exhausted' ? 'transient cooldown' : 'server cooldown';
+        const persisted = await recordSubscriptionMutation(`recording ${getProviderLabel(providerId)} ${source}`, () => markSubscriptionRateLimited(providerId, freshCredential.label, cooldownMs, result.attemptAt));
+        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));
       }
-
-      if (result.result === "transient_exhausted") {
-        // The credential is likely healthy -- this was a provider-side transient blip (e.g.
-        // "overloaded") that survived the in-place retries. Surface it to the user and rotate:
-        // cool the credential down briefly so this loop moves on to the next credential or fallback.
-        const reason = result.classification?.reason ?? "transient error";
-        const persisted = await recordSubscriptionMutation(
-          `recording ${getProviderLabel(providerId)} transient cooldown`,
-          () => markSubscriptionRateLimited(providerId, freshCredential.label, TRANSIENT_ROTATE_COOLDOWN_MS, result.attemptAt),
-        );
-        if (persisted) {
-          cooldownAttempts.set(credentialKey(providerId, freshCredential.label), result.attemptAt);
-        } else {
-          localCoolingDeadlines.set(
-            providerId,
-            Math.max(localCoolingDeadlines.get(providerId) ?? 0, Date.now() + TRANSIENT_ROTATE_COOLDOWN_MS),
-          );
-        }
-        runtimeContext?.ui.notify?.(
-          `${getProviderLabel(providerId)} "${freshCredential.label}" hit a transient error after ${result.attempts ?? 1} attempts (${reason}); rotating to another credential/provider.`,
-          "warning",
-        );
-        logRotation(
-          `${getProviderLabel(providerId)} subscription "${freshCredential.label}" transient error exhausted (reason=${reason}, status=${result.classification?.status ?? "n/a"}); cooling down ${Math.ceil(TRANSIENT_ROTATE_COOLDOWN_MS / 1000)}s and rotating`,
-        );
-        setStatus(formatStatusLine(providerId));
-        continue;
-      }
-
-      // Fatal (or partial content already streamed): cannot safely switch providers mid-turn.
-      if (result.classification) {
-        logRotation(
-          `${getProviderLabel(providerId)} subscription "${freshCredential.label}" failed fatally (status=${result.classification.status ?? "n/a"}, reason=${result.classification.reason})`,
-        );
-      }
-      stream.end();
-      return;
-    }
-
-    // Read a fresh pool after the attempts above so terminal cooling state reflects
-    // mutations made by this candidate, not its initial lock-free snapshot.
-    const currentPool = readSubscriptionPool(providerId);
-    enqueueFreshProviderCandidates(candidates, queuedProviderIds, knownModels, seenReadyLabels, cooldownAttempts, localCoolingDeadlines);
-    if (candidates.length > 0) continue;
-
-    const originalModel = getCurrentModelRef(candidateModel);
-    if (!originalModel) throw new Error(`Provider fallback unavailable: missing current model`);
-
-    const rotationPolicy = readManagedProviderRotationPolicy(runtimeContext?.ui);
-    const fallbackResolution: FallbackResolution = rotationPolicy.allowCrossProviderFallback
-      ? resolveViableFallback(originalModel.providerId, originalModel.modelId, attempted)
-      : { reason: "provider_pinned" };
-    if (fallbackResolution.target) {
-      const target = await switchToFallbackModel(stream, candidateModel, originalModel);
-      if (!target) return; // terminal error already emitted
-      logRotation(`${getProviderLabel(providerId)} pool exhausted -> ${target.label}`);
-      setStatus(`${getProviderLabel(providerId)} -> ${target.label}`);
-
-      const fallbackModel = runtimeContext?.modelRegistry.find(target.providerId, target.modelId);
-      if (!fallbackModel) {
-        emitTerminalError(stream, candidateModel, `Provider fallback unavailable: ${target.label} not in model registry`);
-        return;
-      }
-
-      candidates.push({ model: fallbackModel, providerId: target.providerId });
-      queuedProviderIds.add(target.providerId);
-      knownModels.set(target.providerId, fallbackModel);
-      continue;
+      advanceResult = result;
     }
 
-    terminal = { model: candidateModel, providerId, currentPool, fallbackResolution };
+    enqueueFreshRouteCandidates(candidates, queuedRouteIds, knownRoutes, seenReadyLabels, cooldownAttempts, localCoolingDeadlines);
+    if (advanceResult !== undefined) logRouteQueueAdvance(candidate, candidates[0], advanceResult);
   }
 
-  if (!terminal) throw new Error("Managed provider recovery exhausted without a terminal state");
-
-  const { model: terminalModel, providerId, currentPool, fallbackResolution } = terminal;
-  const label = getProviderLabel(providerId);
-  const triedList = [...attempted].join(", ");
-
-  if (currentPool.length === 0) {
-    emitTerminalError(stream, terminalModel, `${label} not authenticated — run \`crtr sys setup\` (or /provider-sub ${providerId} add) (tried ${triedList})`);
-    return;
-  }
-
-  const fallbackHint = fallbackRejectionHint(fallbackResolution);
-  const coolingProviders = new Set(attempted);
-  if (!fallbackResolution.target && fallbackResolution.reason === "cooling" && fallbackResolution.candidate) {
-    coolingProviders.add(fallbackResolution.candidate.providerId);
-  }
-  const coolingDeadline = earliestCoolingDeadline(coolingProviders, localCoolingDeadlines);
+  const coolingDeadline = earliestCoolingDeadline([...knownRoutes.values()], localCoolingDeadlines);
+  const tried = [...attemptedRoutes].join(', ');
   if (coolingDeadline !== undefined) {
-    const coolingSecs = Math.ceil((coolingDeadline - Date.now()) / 1000);
-    emitCoolingError(
-      stream,
-      terminalModel,
-      new ManagedProviderCoolingError(
-        `All managed providers are rate limited (cooling down ~${coolingSecs}s); ${fallbackHint} (tried ${triedList})`,
-        coolingDeadline,
-      ),
-    );
+    emitCoolingError(stream, terminalModel, new ManagedProviderCoolingError(`All provider routes are rate limited (cooling down ~${Math.ceil((coolingDeadline - Date.now()) / 1000)}s; tried ${tried})`, coolingDeadline));
     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 ${triedList})`);
+    emitTerminalError(stream, terminalModel, `Provider authentication failed (invalid_grant) for ${authFailure}; re-authenticate the credential and retry (tried ${tried})`);
     return;
   }
-
-  emitTerminalError(
-    stream,
-    terminalModel,
-    `All managed provider pools exhausted; ${fallbackHint} (tried ${triedList})`,
-  );
+  emitTerminalError(stream, terminalModel, `All provider routes exhausted (tried ${tried})`);
 }
 
-// The earliest strictly-future cooldown deadline across every managed pool tried
-// this turn, or undefined unless EVERY existing credential in those pools is
-// cooling (a single ready credential, or an empty attempted set, means this is not
-// an all-cooling condition and must not be typed as such). Read fresh under each
-// pool's lock-free snapshot, mirroring the wait-out math above.
+// The earliest strictly-future deadline only when every attempted route is cooling.
 function earliestCoolingDeadline(
-  attempted: Set<ManagedProviderId>,
-  localCoolingDeadlines = new Map<ManagedProviderId, number>(),
+  attempted: Iterable<RouteCandidate>,
+  localCoolingDeadlines: Map<string, number>,
 ): number | undefined {
   const now = Date.now();
   let earliest: number | undefined;
-  let sawCredential = false;
-  for (const attemptedProvider of attempted) {
-    const localUntil = localCoolingDeadlines.get(attemptedProvider) ?? 0;
-    if (localUntil > now) {
-      sawCredential = true;
-      if (earliest === undefined || localUntil < earliest) earliest = localUntil;
-      continue;
-    }
-    for (const entry of readSubscriptionPool(attemptedProvider)) {
-      if (entry.authFailure !== undefined) continue;
-      sawCredential = true;
-      const until = entry.rateLimitedUntil || 0;
-      if (until <= now) return undefined; // a ready credential exists — not all cooling
-      if (earliest === undefined || until < earliest) earliest = until;
-    }
+  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) => (entry.rateLimitedUntil || 0) <= now)) return undefined;
+    const routeEarliest = Math.min(...pool.map((entry) => entry.rateLimitedUntil || 0));
+    earliest = earliest === undefined ? routeEarliest : Math.min(earliest, routeEarliest);
   }
-  return sawCredential ? earliest : undefined;
+  return sawRoute ? earliest : undefined;
 }
 
 // Emit the typed cooling terminal error, attaching its diagnostic (the earliest
@@ -957,10 +721,6 @@ function emitCoolingError(stream: AssistantMessageEventStream, model: Model<any>
 }
 
 function streamManagedProvider(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
-  if (!isManagedProvider(model.provider)) {
-    return streamForProvider(model, context, options);
-  }
-
   const stream = createAssistantMessageEventStream();
 
   runManagedProvider(model, context, options, stream).catch((error) => {
@@ -987,9 +747,51 @@ function parseProvider(value: string | undefined): ManagedProviderId | undefined
   return isManagedProvider(value) ? value : undefined;
 }
 
+function installDeclaredRouteProviders(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const config = readMergedLaunchConfig(ctx.cwd, process.env['CRTR_PROFILE_ID'] || null);
+  const providerIds = new Set(Object.values(config.modelRoutes ?? {}).map((route) => route.providerId));
+  for (const providerId of providerIds) {
+    if (isManagedProvider(providerId) || delegatedProviderStreams.has(providerId)) continue;
+    const provider = ctx.modelRegistry.getProvider?.(providerId);
+    const model = ctx.modelRegistry.getAll?.().find((entry) => entry.provider === providerId);
+    if (!provider || !model) continue;
+    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: streamManagedProvider });
+  }
+}
+
 function updateRotationStatus(ctx: ExtensionContext): void {
   const current = getCurrentModelRef(ctx.model);
-  if (current) setStatus(formatStatusLine(current.providerId));
+  if (current && isManagedProvider(current.providerId)) setStatus(formatStatusLine(current.providerId));
+}
+
+/** Restore only when the deterministic route rank improves; no shared-home
+ * preferred-model state is needed or consulted. */
+async function restoreHigherRankIfAvailable(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}` : ''}`,
+    process.env['CRTR_MODEL_INTENT'],
+    false,
+  );
+  if (!request || !ctx.model) return false;
+  const candidates = expandModelCandidates(request, process.env['CRTR_NODE_CWD'], process.env['CRTR_PROFILE_ID']);
+  const liveRank = candidates.find((candidate) => candidate.providerId === ctx.model?.provider && candidate.modelId === ctx.model?.id && candidate.thinkingLevel === liveThinking)?.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
@@ -1108,22 +910,16 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
   pi.on("session_start", async (_event, ctx) => {
     runtimeContext = ctx;
-    const restored = readManagedProviderRotationPolicy(ctx.ui).allowCrossProviderFallback
-      && await restorePreferredModelIfPossible(pi, ctx);
-    if (restored && ctx.model) {
-      logRotation(`restored preferred ${ctx.model.provider}/${ctx.model.id}`);
-      setStatus(formatStatusLine(ctx.model.provider as ManagedProviderId));
-    }
+    installDeclaredRouteProviders(pi, ctx);
     updateRotationStatus(ctx);
   });
 
   pi.on("before_agent_start", async (_event, ctx) => {
     runtimeContext = ctx;
-    const restored = readManagedProviderRotationPolicy(ctx.ui).allowCrossProviderFallback
-      && await restorePreferredModelIfPossible(pi, ctx);
-    if (restored && ctx.model) {
-      logRotation(`restored preferred ${ctx.model.provider}/${ctx.model.id}`);
-      setStatus(formatStatusLine(ctx.model.provider as ManagedProviderId));
+    const restored = await restoreHigherRankIfAvailable(pi, ctx);
+    if (restored && ctx.model && isManagedProvider(ctx.model.provider)) {
+      logRotation(`restored higher-ranked route ${ctx.model.provider}/${ctx.model.id}`);
+      setStatus(formatStatusLine(ctx.model.provider));
     }
   });