mixdog 1.3.0 → 1.3.2

package/src/runtime/agent/orchestrator/session/loop/fresh-context.mjs

@@ -5,7 +5,6 @@ import { getProvider, initProviders } from '../../providers/registry.mjs';
 import { resolveMaintenanceRoute } from '../../agent-runtime/maintenance-route.mjs';
 import { resolveSessionContextMeta } from '../manager/context-meta.mjs';
 import { isAccountQuotaError } from '../../providers/account-pool.mjs';
-import { builtinFeatureActive } from '../../runtime-core/builtin-features.mjs';
 import { positiveInt } from '../../../../shared/numbers.mjs';
 import { estimateMessagesTokens, providerTokenCalibration } from '../context-utils.mjs';
 import {
@@ -16,6 +15,8 @@ import {
   COMPACT_TARGET_MIN_TOKENS,
 } from '../compact.mjs';
 import { summarizeOnSharedPrefix } from '../compact/forked-summary.mjs';
+import { normalizeCompactionSummaryMode } from '../compact/summary-mode.mjs';
+import { compactionCacheWarm, lighterSubscriptionModel } from '../compact/summary-route.mjs';
 import { retireCompactionFork } from '../side-question-store.mjs';
 
 // Conversation summarization triggers independently of the post-compact target:
@@ -24,52 +25,103 @@ import { retireCompactionFork } from '../side-question-store.mjs';
 const CONVERSATION_COMPACT_TRIGGER_RATIO = 0.05;
 const CONVERSATION_COMPACT_TRIGGER_MAX_TOKENS = 20_000;
 
-// Select an explicitly configured, enabled maintenance route only. An absent
-// or disabled maintenance role falls back to the conversation's own model,
-// not an unrelated global default. Provider failures/cancellation are not
-// absence and must propagate without silently routing around them.
-export async function resolveCompactionRoute({
+// One summary route: the provider, its model and the window the summary
+// request must fit. `source` names the step: 'session' (the conversation's
+// own model), 'maintenance' (the Maintainer) or 'lighter' (the subscription
+// provider's lighter model).
+function summaryRoute({ sessionRef, provider, providerName, model, fast, source }) {
+  if (!provider || typeof provider.send !== 'function' || !model) {
+    throw new Error(`compact summary route unavailable: ${providerName || 'unknown'}/${model || 'unknown'}`);
+  }
+  const sameModel = providerName === sessionRef?.provider && model === sessionRef?.model;
+  const contextWindow =
+    sameModel && positiveInt(sessionRef?.contextWindow)
+      ? positiveInt(sessionRef.contextWindow)
+      : resolveSessionContextMeta(provider, model, {}, { wholeWindow: true }).contextWindow;
+  return { provider, providerName, model, contextWindow, fast, source };
+}
+
+// The Maintainer's own model when one is set and enabled, whatever the memory
+// or recap settings; null otherwise (an unrelated global default is never
+// borrowed). Provider failures/cancellation are not absence and propagate.
+async function resolveMaintainerRoute({ sessionRef, config, signal, getProviderFn, initProvidersFn }) {
+  const route = resolveMaintenanceRoute({ agent: 'cycle1-agent', config, includeDefault: false });
+  if (!(route?.provider && route?.model && config.providers?.[route.provider]?.enabled !== false)) return null;
+  await initProvidersFn(config.providers || {}, { signal });
+  signal?.throwIfAborted();
+  return summaryRoute({
+    sessionRef,
+    provider: getProviderFn(route.provider),
+    providerName: route.provider,
+    model: route.model,
+    fast: route.fast === true,
+    source: 'maintenance',
+  });
+}
+
+function resolveSessionRoute({ sessionRef, provider, model, getProviderFn }) {
+  const providerName = sessionRef?.provider || provider?.name;
+  return summaryRoute({
+    sessionRef,
+    provider: provider || getProviderFn(providerName),
+    providerName,
+    model: model || sessionRef?.model,
+    source: 'session',
+  });
+}
+
+// The newest lighter model of a subscription provider's saved account
+// catalog; null on any other provider, without a saved catalog, when none is
+// listed, or when the conversation already runs on it.
+async function resolveLighterRoute(input) {
+  const session = resolveSessionRoute(input);
+  const lighter = await lighterSubscriptionModel(session.providerName);
+  input.signal?.throwIfAborted();
+  if (!lighter || lighter === session.model) return null;
+  return summaryRoute({
+    sessionRef: input.sessionRef,
+    provider: session.provider,
+    providerName: session.providerName,
+    model: lighter,
+    source: 'lighter',
+  });
+}
+
+/**
+ * The compaction summary plan (compact/summary-mode.mjs): the saved mode,
+ * whether the session's prompt cache is warm, and the routes in the order
+ * they are tried, each resolved only when reached (null = unavailable, the
+ * next one runs). The conversation's own model is always the last step.
+ */
+export function compactionSummaryPlan({
   sessionRef,
+  sessionId = sessionRef?.id,
   provider,
   model,
   config = loadConfig(),
   signal,
   getProviderFn = getProvider,
   initProvidersFn = initProviders,
-  allowMaintenance = true,
+  now = Date.now(),
 } = {}) {
   signal?.throwIfAborted();
-  const route =
-    allowMaintenance && builtinFeatureActive(config, 'memory') && config.recap?.enabled !== false
-      ? resolveMaintenanceRoute({ agent: 'cycle1-agent', config, includeDefault: false })
-      : null;
-  const useMaintenance = !!(route?.provider && route?.model && config.providers?.[route.provider]?.enabled !== false);
-  const providerName = useMaintenance ? route.provider : sessionRef?.provider || provider?.name;
-  const selectedModel = useMaintenance ? route.model : model || sessionRef?.model;
-  if (useMaintenance) await initProvidersFn(config.providers || {}, { signal });
-  signal?.throwIfAborted();
-  const selectedProvider = useMaintenance ? getProviderFn(providerName) : provider || getProviderFn(providerName);
-  if (!selectedProvider || typeof selectedProvider.send !== 'function' || !selectedModel) {
-    throw new Error(`compact summary route unavailable: ${providerName || 'unknown'}/${selectedModel || 'unknown'}`);
-  }
-  const sameModel = providerName === sessionRef?.provider && selectedModel === sessionRef?.model;
-  const contextWindow =
-    sameModel && positiveInt(sessionRef?.contextWindow)
-      ? positiveInt(sessionRef.contextWindow)
-      : resolveSessionContextMeta(selectedProvider, selectedModel, {}, { wholeWindow: true }).contextWindow;
-  return {
-    provider: selectedProvider,
-    providerName,
-    model: selectedModel,
-    contextWindow,
-    fast: useMaintenance ? route.fast === true : undefined,
-    source: useMaintenance ? 'maintenance' : 'session',
-  };
+  const input = { sessionRef, provider, model, config, signal, getProviderFn, initProvidersFn };
+  const mode = normalizeCompactionSummaryMode(config.compaction);
+  const warm = compactionCacheWarm(sessionId, now);
+  const session = async () => resolveSessionRoute(input);
+  const maintainer = () => resolveMaintainerRoute(input);
+  const lighter = () => resolveLighterRoute(input);
+  let steps = [session];
+  if (mode === 'maintainer') steps = [maintainer, session];
+  else if (mode === 'smart' && !warm) steps = [maintainer, lighter, session];
+  return { mode, warm, steps };
 }
 
-// The isolated summary request on one route. Its input budget belongs to
-// its OWN model, whereas the rebuilt conversation must fit the original
-// session's target/window.
+// The summary request on one route: the conversation alone (earlier summary
+// and dialogue; tool output, skills and injections excluded), never the
+// cached context. Its input budget belongs to its OWN model, split into
+// batches when the conversation is larger, whereas the rebuilt conversation
+// must fit the original session's target/window.
 function summarizeConversation(target, ctx) {
   const { sessionRef, sessionId, signal, sendOpts, compactPolicy } = ctx;
   const summaryWindow = positiveInt(target.contextWindow) || ctx.contextWindow;
@@ -117,24 +169,24 @@ function sumUsage(a, b) {
   return Object.fromEntries(Object.keys(a).map((key) => [key, (a[key] || 0) + (Number(b[key]) || 0)]));
 }
 
-// Summary policy. On the session's own provider and model the summary forks
-// the latest cached request (compact/forked-summary.mjs): the context is
-// already in the prompt cache, so reading it costs a tenth to a twentieth of
-// sending the text-only transcript uncached, and the summary sees the full
-// execution context. A different summary route (the maintenance model)
-// cannot share that cache; there the isolated text-only request runs: on
-// the usage ledger it cost a median $0.16 and 24.5 s against a projected
-// $0.19 and 27 s for a cache-read fork of the main model's median 500k-token
-// context (the fork is cheaper than a same-model isolated request, $0.20).
-// A fork that cannot run or fails falls back to the isolated request.
-async function summarizeOnRoute(route, ctx) {
-  const shared = await summarizeOnSharedPrefix({
-    sessionId: ctx.sessionId,
-    route,
-    conversationInput: ctx.conversationInput,
-    signal: ctx.signal,
-    timeoutMs: ctx.compactPolicy.handoffTimeoutMs,
-  });
+// The summary on one route. While the session's prompt cache is warm, the
+// summary forks the latest cached request on the conversation's own model
+// (compact/forked-summary.mjs): reading the cached context costs a tenth to a
+// twentieth of sending the text-only transcript uncached, and the summary
+// sees the full execution context. A cold cache would be rewritten in full,
+// so the isolated text-only request runs instead; so does any other route
+// (a cache is never shared across models). A fork that cannot run or fails
+// falls back to the isolated request on the same route.
+async function summarizeOnRoute(route, ctx, warm) {
+  const shared = warm
+    ? await summarizeOnSharedPrefix({
+        sessionId: ctx.sessionId,
+        route,
+        conversationInput: ctx.conversationInput,
+        signal: ctx.signal,
+        timeoutMs: ctx.compactPolicy.handoffTimeoutMs,
+      })
+    : { fallback: 'cold_cache' };
   if (shared.generated) return shared.generated;
   ctx.signal?.throwIfAborted();
   const generated = await summarizeConversation(route, ctx);
@@ -145,34 +197,45 @@ async function summarizeOnRoute(route, ctx) {
   };
 }
 
-// A maintenance summary model that is out of quota must not take the whole
-// turn down: the conversation's own model still has budget and can
-// summarize. Only exhaustion reroutes — every other compaction failure
-// (overflow, malformed summary, transport) keeps its existing handling, and
-// an aborted turn stays aborted.
-async function summarizeWithQuotaFallback(ctx, routeInput) {
-  const route = await resolveCompactionRoute(routeInput);
-  try {
-    return { route, generated: await summarizeOnRoute(route, ctx) };
-  } catch (error) {
-    ctx.signal?.throwIfAborted();
-    const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
-    const exhausted = error?.code === 'provider_accounts_exhausted' || status === 429 || isAccountQuotaError(error);
-    const fallback =
-      route.source === 'maintenance' && exhausted
-        ? await resolveCompactionRoute({ ...routeInput, allowMaintenance: false })
-        : null;
-    if (!fallback || (fallback.providerName === route.providerName && fallback.model === route.model)) {
-      error.compactRoute = { provider: route.providerName, model: route.model };
-      throw error;
-    }
+// A Maintainer or lighter model that is out of quota or not available to the
+// account must not take the whole turn down: the next route still can
+// summarize. Every other compaction failure (overflow, malformed summary,
+// transport) keeps its existing handling, and an aborted turn stays aborted.
+function fallsToNextRoute(error) {
+  const status = Number(error?.status || error?.httpStatus || error?.response?.status || 0);
+  return (
+    error?.code === 'provider_accounts_exhausted' ||
+    error?.code === 'model_not_found' ||
+    status === 429 ||
+    status === 404 ||
+    isAccountQuotaError(error)
+  );
+}
+
+// Resolving a route (provider init, catalog lookup) is part of its step: a
+// quota or availability failure there moves to the next route like one from
+// the summary request. The conversation's own model is the last step, so its
+// failure always ends the compaction.
+async function summarizeOnPlan(ctx, plan) {
+  const tried = new Set();
+  let failure = null;
+  for (const step of plan.steps) {
+    let route = null;
     try {
-      return { route: fallback, generated: await summarizeOnRoute(fallback, ctx) };
-    } catch (fallbackError) {
-      fallbackError.compactRoute = { provider: fallback.providerName, model: fallback.model };
-      throw fallbackError;
+      route = await step();
+      ctx.signal?.throwIfAborted();
+      const key = route && `${route.providerName}\u0000${route.model}`;
+      if (!route || tried.has(key)) continue;
+      tried.add(key);
+      return { route, generated: await summarizeOnRoute(route, ctx, plan.warm) };
+    } catch (error) {
+      ctx.signal?.throwIfAborted();
+      if (route) error.compactRoute = { provider: route.providerName, model: route.model };
+      if (route?.source === 'session' || !fallsToNextRoute(error)) throw error;
+      failure = error;
     }
   }
+  throw failure;
 }
 
 // The window this compaction must fit (calibrated to the provider's token
@@ -200,7 +263,10 @@ function freshContextBudget({ compactPolicy, sessionRef, provider, compactBudget
   return { contextWindow, hardBudget, conversationInput, conversationTokens, conversationThresholdTokens };
 }
 
-function freshContextBuildOptions({ compactPolicy = {}, sessionId, goalReminderText, activeTurn }, budget) {
+function freshContextBuildOptions(
+  { compactPolicy = {}, sessionId, goalReminderText, activeTurn, referenceLatestAttachments },
+  budget
+) {
   return {
     reserveTokens: compactPolicy.reserveTokens,
     maxBudgetTokens: budget.hardBudget,
@@ -209,6 +275,7 @@ function freshContextBuildOptions({ compactPolicy = {}, sessionId, goalReminderT
     sessionId,
     latestUserPrefix: goalReminderText,
     activeTurn,
+    referenceLatestAttachments: referenceLatestAttachments === true,
   };
 }
 
@@ -230,6 +297,27 @@ export function previewFreshContextCompaction(input) {
   return { beforeTokens, afterTokens, reducesTokens: afterTokens < beforeTokens, summaryTriggered };
 }
 
+function buildFreshContextResult(
+  { messages, compactBudgetTokens, buildOptions, requireReduction, sessionId },
+  handoffText
+) {
+  const result = freshContextCompactMessages(messages, compactBudgetTokens, { ...buildOptions, handoffText });
+  // A generated summary can differ from its prediction. Never replace the
+  // original with an automatic result that is equal-sized or larger.
+  if (requireReduction && estimateMessagesTokens(result.messages) >= estimateMessagesTokens(messages)) {
+    return {
+      ...result,
+      messages,
+      freshContext: false,
+      skipped: true,
+      diagnostics: { ...result.diagnostics, noOp: true, reason: 'no_token_reduction' },
+    };
+  }
+  // The rewritten transcript is no longer what the saved request carried.
+  if (result.freshContext) retireCompactionFork(sessionId);
+  return result;
+}
+
 export async function runFreshContextCompact({
   sessionRef,
   messages,
@@ -246,35 +334,19 @@ export async function runFreshContextCompact({
   getProviderFn,
   initProvidersFn,
   requireReduction = false,
+  referenceLatestAttachments = false,
 } = {}) {
   const startedAt = Date.now();
   signal?.throwIfAborted();
   const { contextWindow, hardBudget, conversationInput, conversationTokens, conversationThresholdTokens } =
     freshContextBudget({ compactPolicy, sessionRef, provider, compactBudgetTokens, messages });
   const summaryTriggered = conversationTokens >= conversationThresholdTokens;
-  const build = (handoffText) => {
-    const result = freshContextCompactMessages(messages, compactBudgetTokens, {
-      ...freshContextBuildOptions(
-        { compactPolicy, sessionId, goalReminderText, activeTurn },
-        { contextWindow, hardBudget }
-      ),
-      handoffText,
-    });
-    // A generated summary can differ from its prediction. Never replace the
-    // original with an automatic result that is equal-sized or larger.
-    if (requireReduction && estimateMessagesTokens(result.messages) >= estimateMessagesTokens(messages)) {
-      return {
-        ...result,
-        messages,
-        freshContext: false,
-        skipped: true,
-        diagnostics: { ...result.diagnostics, noOp: true, reason: 'no_token_reduction' },
-      };
-    }
-    // The rewritten transcript is no longer what the saved request carried.
-    if (result.freshContext) retireCompactionFork(sessionId);
-    return result;
-  };
+  const buildOptions = freshContextBuildOptions(
+    { compactPolicy, sessionId, goalReminderText, activeTurn, referenceLatestAttachments },
+    { contextWindow, hardBudget }
+  );
+  const build = (handoffText) =>
+    buildFreshContextResult({ messages, compactBudgetTokens, buildOptions, requireReduction, sessionId }, handoffText);
   const pipeline = {
     mode: summaryTriggered ? 'conversation-summary' : 'rules',
     conversationTokens,
@@ -291,7 +363,17 @@ export async function runFreshContextCompact({
       pipeline: { ...pipeline, totalMs: Date.now() - startedAt },
     });
   }
-  const { route, generated } = await summarizeWithQuotaFallback(
+  const plan = compactionSummaryPlan({
+    sessionRef,
+    sessionId,
+    provider,
+    model,
+    config,
+    signal,
+    getProviderFn,
+    initProvidersFn,
+  });
+  const { route, generated } = await summarizeOnPlan(
     {
       sessionRef,
       sessionId,
@@ -303,7 +385,7 @@ export async function runFreshContextCompact({
       contextWindow,
       conversationInput,
     },
-    { sessionRef, provider, model, config, signal, getProviderFn, initProvidersFn }
+    plan
   );
   signal?.throwIfAborted();
   const result = build(generated.summary);
@@ -315,6 +397,8 @@ export async function runFreshContextCompact({
     pipeline: {
       ...pipeline,
       handoffSource: 'session-local',
+      summaryMode: plan.mode,
+      cacheWarm: plan.warm,
       summaryRoute: route.source,
       summaryProvider: route.providerName,
       summaryModel: route.model,

package/src/runtime/agent/orchestrator/session/loop/loop-state.mjs

@@ -8,6 +8,7 @@ import { resolveLiveToolCwd } from './tool-exec.mjs';
 import { createSteeringDrain } from './steering.mjs';
 import { createNoToolTurnResolver } from './no-tool-turn.mjs';
 import { classifyTerminationReason } from './termination.mjs';
+import { routeUsageSegments } from './usage.mjs';
 
 // Consecutive identical-AND-failing tool calls (same name+args, error result)
 // tolerated across iterations before the loop refuses to re-execute and steers
@@ -153,5 +154,13 @@ export function finishLoop(state) {
     providerStateUpdated: state.providerStateUpdated,
     terminationReason: classifyTerminationReason(response, { sessionAgent: state.sessionAgent }),
     providerContinuations: state.noToolTurn.providerContinuations,
+    ...(state.routeUsageHops?.length
+      ? {
+          usageSegments: routeUsageSegments(state.routeUsageHops, state.lastUsage, {
+            provider: state.sessionRef?.provider,
+            model: state.sessionRef?.model,
+          }),
+        }
+      : {}),
   };
 }

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -16,7 +16,8 @@ import { isOffReadonlySurface } from './deferred-call-through.mjs';
 import { BRIDGE_CALL_TOOL_NAME, bridgeErrorText, isToolBridgeEnabled } from '../../runtime-core/tool-bridge.mjs';
 import { sessionAllowlistExcludes, sessionDisallows } from '../../runtime-core/deferred-tool-availability.mjs';
 import { providerToolExclusionReason } from './provider-tool-exclusions.mjs';
-import { agentMcpToolPermission, projectMcpToolDisabled } from '../../mcp/agent-connectors.mjs';
+import { workflowOverlayDenial } from '../manager/workflow-switch-notice.mjs';
+import { agentMcpToolPermission, connectorPolicyAgentOf, projectMcpToolDisabled } from '../../mcp/agent-connectors.mjs';
 
 const WORKER_DENIED_TOOLS = new Set(['agent', 'ask_user', 'session']);
 const BRIDGE_DISCOVERY_TOOL_NAMES = new Set(['load_tool']);
@@ -120,12 +121,15 @@ export function preDispatchDenyForSession(sessionRef, call) {
   if (!bridgeDiscovery && sessionAllowlistExcludes(sessionRef, schemaName)) {
     return `Error: tool "${name}" is not available on this session's schema allowlist.`;
   }
+  // A workflow switched mid-conversation keeps the schema; its denials apply here.
+  const workflowDenial = workflowOverlayDenial(sessionRef, schemaName);
+  if (workflowDenial) return workflowDenial;
   if (sessionDisallows(sessionRef, schemaName)) {
     return `Error: tool "${name}" is not available in this session.`;
   }
   // An agent's connectors: a tool of a server it does not mount, or one set
   // to `disabled`, stays refused though the process-wide registry knows it.
-  if (agentMcpToolPermission(sessionRef?.agent, schemaName) === 'disabled') {
+  if (agentMcpToolPermission(connectorPolicyAgentOf(sessionRef), schemaName) === 'disabled') {
     return `Error: tool "${name}" is not available to this agent.`;
   }
   // The project the session runs in may switch a connector off as well.

package/src/runtime/agent/orchestrator/session/loop/route-fallback.mjs

@@ -1,4 +1,7 @@
-import { canFallbackRoute } from '../../../../shared/model-route-fallback.mjs';
+import { routeFallbackVerdict } from '../../../../shared/model-route-fallback.mjs';
+import { providerErrorKind } from '../../providers/provider-error-kind.mjs';
+import { displayModelName } from '../../../../shared/model-display.mjs';
+import { presentErrorText } from '../../../../shared/err-text.mjs';
 import { getProvider, initProviders } from '../../providers/registry.mjs';
 import { loadConfig } from '../../config.mjs';
 import { ensureProviderEnabled } from '../../runtime-core/config-helpers.mjs';
@@ -7,19 +10,105 @@ import { pinSessionWireRoute } from '../../providers/wire-route.mjs';
 import { buildRequestSendOptions } from '../manager/ask-turn-loop-options.mjs';
 import { prepareTurnEffortConfiguration } from '../../providers/effort-configuration.mjs';
 import { resolveSessionContextMeta } from '../manager/context-meta.mjs';
+import { stripProviderReplayMessages } from '../manager/provider-replay.mjs';
+
+// The short reason a notice gives for leaving a model, by provider kind.
+const HOP_REASONS = {
+  quota_exhausted: 'usage limit reached',
+  entitlement: 'not included in the plan',
+  billing: 'out of credits',
+  rate_limited: 'rate-limited',
+  overloaded: 'unavailable',
+  transient: 'unavailable',
+  service_tier_unavailable: 'unavailable',
+  auth: 'sign-in failed',
+  permission: 'access denied',
+  invalid_request: 'model not available',
+  context_overflow: 'context too long',
+};
+
+const routeLabel = (route) => displayModelName(route.model, route.provider) || `${route.provider}/${route.model}`;
+
+/** The muted transcript line for a hop: `<from> <reason> — switched to <to>.` */
+export function routeFallbackNoticeText(from, to, error) {
+  const reason = HOP_REASONS[providerErrorKind(error).kind] || 'unavailable';
+  return `${routeLabel(from)} ${reason} — switched to ${routeLabel(to)}.`;
+}
+
+function routeFailure(route, error) {
+  return {
+    provider: route.provider,
+    model: route.model,
+    kind: providerErrorKind(error).kind,
+    error: presentErrorText(error),
+  };
+}
+
+// The chain ended after at least one hop: the final error keeps its own kind
+// and names every model that was tried and why each failed. `skipped` is the
+// next route when the chain stopped before it (a context overflow whose next
+// window is no larger), so the text says why instead of "every model failed".
+function annotateEndedChain(session, error, skipped = null) {
+  const tried = session?.routeFallbackFailures;
+  if (!tried?.length || !error || typeof error !== 'object' || error.routeFallbackAttempts) return;
+  const attempts = [...tried, routeFailure(session, error)];
+  try {
+    error.routeFallbackAttempts = attempts;
+    const lines = attempts.map((attempt) => `${routeLabel(attempt)}: ${attempt.error}`).join('; ');
+    const head = skipped
+      ? `Fallback chain stopped before ${routeLabel(skipped)} (its context window is not larger) — tried`
+      : 'Every model in the fallback chain failed —';
+    error.message = `${error.message}\n${head} ${lines}`;
+    if (skipped) error.routeFallbackStoppedBefore = { provider: skipped.provider, model: skipped.model };
+  } catch {
+    /* frozen errors keep their own message */
+  }
+}
+
+// A context overflow moves only to a model whose window is larger.
+async function nextContextGrows(state, next) {
+  await initProviders(ensureProviderEnabled(loadConfig(), next.provider), { signal: state.signal });
+  state.throwIfAborted();
+  const provider = getProvider(next.provider);
+  if (!provider) return false;
+  const current = resolveSessionContextMeta(state.provider, state.sessionRef.model, state.sessionRef).rawContextWindow;
+  const window = resolveSessionContextMeta(provider, next.model, next).rawContextWindow;
+  return Number(window) > Number(current || state.sessionRef.selectedContextWindow || 0);
+}
 
 export async function advanceAgentRoute(state, error) {
   const session = state.sessionRef;
-  const index = session?.routeFallbackIndex || 0;
-  const next = session?.routeFallbacks?.[index];
-  const committed = state.toolCallsTotal > 0 || state.response != null;
-  if (!session?.agent || !next || !canFallbackRoute(error, { signal: state.signal, committed })) return false;
+  if (!session?.agent || !session.routeFallbacks?.length) return false;
+  const index = session.routeFallbackIndex || 0;
+  const next = session.routeFallbacks[index];
+  // Only THIS request must have produced nothing (its stream outcome says so):
+  // earlier requests of the turn may have run tools. Their calls and results
+  // are already in the live turn, which the next model continues from, so no
+  // completed tool runs again.
+  const verdict = routeFallbackVerdict(error, { signal: state.signal });
+  const hops = verdict === 'hop' || (verdict === 'context' && next && (await nextContextGrows(state, next)));
+  if (!next || !hops) {
+    if (verdict !== 'stay') annotateEndedChain(session, error, next || null);
+    return false;
+  }
   state.throwIfAborted();
-  const config = ensureProviderEnabled(loadConfig(), next.provider);
-  await initProviders(config.providers, { signal: state.signal });
+  await initProviders(ensureProviderEnabled(loadConfig(), next.provider), { signal: state.signal });
   state.throwIfAborted();
   const provider = getProvider(next.provider);
   if (!provider) throw new Error(`Provider "${next.provider}" not available`);
+  const failed = routeFailure(session, error);
+  // The left model's share of the turn ends here: the running total at the
+  // switch bounds it, so each model's tokens are booked at its own rates.
+  state.routeUsageHops = [
+    ...(state.routeUsageHops || []),
+    { provider: session.provider, model: session.model, usage: state.lastUsage ? { ...state.lastUsage } : null },
+  ];
+  const notice = routeFallbackNoticeText(session, next, error);
+  // Saved with the new route: a crash before the live turn is checkpointed
+  // again recovers that turn without the previous provider's native state.
+  if (session.activeTurnCheckpoint && typeof session.activeTurnCheckpoint === 'object') {
+    session.activeTurnCheckpoint = { ...session.activeTurnCheckpoint, routeChanged: true };
+  }
   const oldOptions = buildRequestSendOptions({
     sessionId: state.sessionId,
     session,
@@ -37,13 +126,18 @@ export async function advanceAgentRoute(state, error) {
       contextTokens: next.contextTokens,
       selectedContextWindow: resolveSessionContextMeta(provider, next.model, next).rawContextWindow,
     },
-    { crossProvider: true }
+    // The live turn object is what changes: the route is applied to it in place, never to
+    // another copy of the id (a disk reload after a generation takeover).
+    { crossProvider: true, session }
   );
   if (!updated) throw new Error('agent session closed during model fallback');
   updated.routeFallbackIndex = index + 1;
+  updated.routeFallbackFailures = [...(session.routeFallbackFailures || []), failed];
   await pinSessionWireRoute(updated, provider);
   state.throwIfAborted();
-  state.messages.splice(0, state.messages.length, ...updated.messages);
+  // The live turn (prompt, assistant tool calls, tool results) carries on;
+  // only the previous provider's native replay state is dropped from it.
+  state.messages.splice(0, state.messages.length, ...stripProviderReplayMessages(state.messages));
   updated.liveTurnMessages = state.messages;
   state.sessionRef = updated;
   state.provider = provider;
@@ -67,6 +161,14 @@ export async function advanceAgentRoute(state, error) {
       signal: state.signal,
     })
   );
+  try {
+    process.stderr.write(
+      `[route-fallback] ${failed.provider}/${failed.model} (${failed.kind}) -> ${updated.provider}/${updated.model}\n`
+    );
+    state.opts.onStageChange?.('notice', { tone: 'info', message: notice });
+  } catch {
+    /* display-only */
+  }
   state.opts.onStageChange?.('connecting', {
     provider: updated.provider,
     model: updated.model,