diff --git a/.changeset/subagent-model-failover.md b/.changeset/subagent-model-failover.md
new file mode 100644
index 0000000000..bbabe75ae7
--- /dev/null
+++ b/.changeset/subagent-model-failover.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+web: Add experimental runtime model failover for subagents so exhausted retries or structured quota failures can replay the current step on an ordered fallback route. Enable `KIMI_CODE_EXPERIMENTAL_MODEL_FAILOVER=1` and configure `[subagent_failover]`.
diff --git a/apps/kimi-web/src/api/daemon/agentEventProjector.ts b/apps/kimi-web/src/api/daemon/agentEventProjector.ts
index d4ebbd09a0..f50896a454 100644
--- a/apps/kimi-web/src/api/daemon/agentEventProjector.ts
+++ b/apps/kimi-web/src/api/daemon/agentEventProjector.ts
@@ -46,6 +46,7 @@ const MAIN_AGENT_TRANSCRIPT_FRAMES = new Set<string>([
   'turn.step.started',
   'turn.step.completed',
   'turn.step.retrying',
+  'turn.step.failover',
   'turn.step.interrupted',
   'turn.ended',
   'thinking.delta',
@@ -225,6 +226,12 @@ export function subagentProgressText(rawType: string, payload: Record<string, un
   // "Started a step" fires on every step and adds no information — the phase
   // badge already shows the subagent is working, so skip it to cut the noise.
   if (rawType === 'turn.step.started') return null;
+  if (rawType === 'turn.step.failover') {
+    const fromModel = stringField(payload, 'fromModel');
+    const toModel = stringField(payload, 'toModel');
+    if (fromModel && toModel) return `Model failover: ${fromModel} → ${toModel}`;
+    return 'Model failover';
+  }
   if (rawType === 'tool.use' || rawType === 'tool.call.started') {
     const name = stringField(payload, 'name') ?? stringField(payload, 'toolName') ?? 'tool';
     const label = toolLabel(cleanToolName(name));
@@ -282,6 +289,32 @@ function projectSubagentProgress(
   // placeholders like "Started a step".
   if (sideChannelAgents.has(subagentId) && rawType === 'turn.step.started') return [];
 
+  if (rawType === 'turn.step.retrying' || rawType === 'turn.step.failover') {
+    if (sideChannelAgents.has(subagentId)) {
+      return [{ type: 'agentStreamReset', sessionId, agentId: subagentId }];
+    }
+    const previous = state.subagentMeta.get(subagentId);
+    const task = patchSubagent(state, sessionId, subagentId, {
+      status: 'running',
+      subagentPhase: 'working',
+      startedAt: previous?.startedAt ?? new Date().toISOString(),
+    });
+    const out: AppEvent[] = [];
+    if (task) out.push({ type: 'taskCreated', sessionId, task });
+    out.push({ type: 'taskTextReset', sessionId, taskId: subagentId });
+    const text = subagentProgressText(rawType, payload);
+    if (text !== null) {
+      out.push({
+        type: 'taskProgress',
+        sessionId,
+        taskId: subagentId,
+        outputChunk: text,
+        stream: 'stdout',
+      });
+    }
+    return out;
+  }
+
   // The subagent's own streamed text: forward each delta as a `text`-kind
   // progress chunk so the reducer concatenates it into `AppTask.text`, letting
   // the right-side detail panel show the subagent's output growing live (like
@@ -1052,7 +1085,8 @@ export function createAgentProjector(): AgentProjector {
       }
 
       // -----------------------------------------------------------------------
-      case 'turn.step.retrying': {
+      case 'turn.step.retrying':
+      case 'turn.step.failover': {
         // The step's stream restarts from offset 0. Reuse the abandoned
         // bubble instead of stacking a new one: strip its streamed parts and
         // keep the id in retryReuseMsgId so the retried step.started refills
@@ -1445,6 +1479,7 @@ const KNOWN_AGENT_CORE_TYPES = new Set([
   'turn.step.started',
   'turn.step.completed',
   'turn.step.retrying',
+  'turn.step.failover',
   'turn.step.interrupted',
   'turn.ended',
   'thinking.delta',
diff --git a/apps/kimi-web/src/api/daemon/eventReducer.ts b/apps/kimi-web/src/api/daemon/eventReducer.ts
index 4916bfa7b7..9f707ccafb 100644
--- a/apps/kimi-web/src/api/daemon/eventReducer.ts
+++ b/apps/kimi-web/src/api/daemon/eventReducer.ts
@@ -693,6 +693,18 @@ export function reduceAppEvent(
       break;
     }
 
+    case 'taskTextReset': {
+      const sid = event.sessionId;
+      const list = next.tasksBySession[sid] ?? [];
+      next.tasksBySession[sid] = list.map((task) =>
+        task.id === event.taskId ? { ...task, text: undefined } : task,
+      );
+      break;
+    }
+
+    case 'agentStreamReset':
+      break;
+
     // -------------------------------------------------------------------------
     case 'taskCompleted': {
       const sid = event.sessionId;
diff --git a/apps/kimi-web/src/api/types.ts b/apps/kimi-web/src/api/types.ts
index 6c4679f165..2b1b6c3802 100644
--- a/apps/kimi-web/src/api/types.ts
+++ b/apps/kimi-web/src/api/types.ts
@@ -460,6 +460,8 @@ export type AppEvent =
        */
       kind?: 'line' | 'text';
     }
+  | { type: 'taskTextReset'; sessionId: string; taskId: string }
+  | { type: 'agentStreamReset'; sessionId: string; agentId: string }
   | { type: 'taskCompleted'; sessionId: string; taskId: string; status: AppTaskStatus; outputPreview?: string; outputBytes?: number }
   // Prompt-level lifecycle (distinct from turn-level): a prompt that never
   // produced a turn — blocked by a pre-submit hook, or aborted while queued —
diff --git a/apps/kimi-web/src/composables/client/useSideChat.ts b/apps/kimi-web/src/composables/client/useSideChat.ts
index 10322ae46a..14a3961331 100644
--- a/apps/kimi-web/src/composables/client/useSideChat.ts
+++ b/apps/kimi-web/src/composables/client/useSideChat.ts
@@ -142,6 +142,12 @@ export function useSideChat(rawState: ExtendedState, deps: UseSideChatDeps) {
     });
   }
 
+  function resetSideChatAssistantText(agentId: string): void {
+    updateSideChatMessages(agentId, (messages) =>
+      messages.at(-1)?.role === 'assistant' ? messages.slice(0, -1) : messages,
+    );
+  }
+
   function finishSideChatAgent(agentId: string, sessionId: string, outputPreview?: string): void {
     rawState.sideChatSendingByAgent = { ...rawState.sideChatSendingByAgent, [agentId]: false };
     if (!outputPreview) return;
@@ -281,6 +287,7 @@ export function useSideChat(rawState: ExtendedState, deps: UseSideChatDeps) {
     sideChatRunning,
     sideChatTurns,
     appendSideChatAssistantText,
+    resetSideChatAssistantText,
     finishSideChatAgent,
     openSideChat,
     openSideChatOn,
diff --git a/apps/kimi-web/src/composables/useKimiWebClient.ts b/apps/kimi-web/src/composables/useKimiWebClient.ts
index f6e3f6a694..19ff356542 100644
--- a/apps/kimi-web/src/composables/useKimiWebClient.ts
+++ b/apps/kimi-web/src/composables/useKimiWebClient.ts
@@ -908,6 +908,8 @@ function processEvent(appEvent: AppEvent, meta: KimiEventMeta): void {
       }
     } else if (appEvent.type === 'agentTurnEnded' && appEvent.agentId === agentId) {
       sideChat.finishSideChatAgent(agentId, parentId);
+    } else if (appEvent.type === 'agentStreamReset' && appEvent.agentId === agentId) {
+      sideChat.resetSideChatAssistantText(agentId);
     } else if (appEvent.type === 'taskProgress' && appEvent.taskId === agentId) {
       sideChat.appendSideChatAssistantText(agentId, parentId, appEvent.outputChunk);
     } else if (appEvent.type === 'taskCompleted' && appEvent.taskId === agentId) {
diff --git a/apps/kimi-web/test/agent-event-projector.test.ts b/apps/kimi-web/test/agent-event-projector.test.ts
index 763e2fe2b9..1e5665cc87 100644
--- a/apps/kimi-web/test/agent-event-projector.test.ts
+++ b/apps/kimi-web/test/agent-event-projector.test.ts
@@ -1,6 +1,8 @@
 /**
  * Web daemon projector contract for transcript isolation, task progress, and
- * client-visible error projection.
+ * client-visible error projection. The real pure projector is used directly.
+ * Run with `pnpm --filter @moonshot-ai/kimi-web exec vitest run
+ * test/agent-event-projector.test.ts`.
  */
 
 import { describe, expect, it } from 'vitest';
@@ -11,6 +13,15 @@ describe('subagentProgressText', () => {
     expect(subagentProgressText('turn.step.started', {})).toBeNull();
   });
 
+  it('summarizes a model failover with both aliases', () => {
+    expect(
+      subagentProgressText('turn.step.failover', {
+        fromModel: 'secondary-model',
+        toModel: 'primary-model',
+      }),
+    ).toBe('Model failover: secondary-model → primary-model');
+  });
+
   it('summarizes a read tool call with its path', () => {
     const text = subagentProgressText('tool.use', { name: 'read', args: { path: 'src/foo.ts' } });
     expect(text).toContain('src/foo.ts');
@@ -64,6 +75,59 @@ describe('subagent streaming text', () => {
     const events = projector.project('assistant.delta', { agentId: 'sub-1', delta: '' }, 's1');
     expect(events).toEqual([]);
   });
+
+  it('resets abandoned subagent text when failover starts', () => {
+    const projector = createAgentProjector();
+    projector.project('assistant.delta', { agentId: 'sub-1', delta: 'partial' }, 's1');
+
+    const events = projector.project(
+      'turn.step.failover',
+      {
+        agentId: 'sub-1',
+        turnId: 1,
+        step: 1,
+        fromModel: 'secondary-model',
+        toModel: 'primary-model',
+      },
+      's1',
+    );
+
+    expect(events).toContainEqual({
+      type: 'taskTextReset',
+      sessionId: 's1',
+      taskId: 'sub-1',
+    });
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: 'taskProgress',
+        taskId: 'sub-1',
+        outputChunk: 'Model failover: secondary-model → primary-model',
+      }),
+    );
+  });
+
+  it('resets a side-channel stream when failover starts', () => {
+    const projector = createAgentProjector();
+    projector.markSideChannelAgent('side-1');
+
+    expect(
+      projector.project(
+        'turn.step.failover',
+        {
+          agentId: 'side-1',
+          turnId: 1,
+          step: 1,
+        },
+        's1',
+      ),
+    ).toEqual([
+      {
+        type: 'agentStreamReset',
+        sessionId: 's1',
+        agentId: 'side-1',
+      },
+    ]);
+  });
 });
 
 describe('agent error projection', () => {
diff --git a/apps/kimi-web/test/event-reducer.test.ts b/apps/kimi-web/test/event-reducer.test.ts
index 9df96de2ed..52dbcdf46a 100644
--- a/apps/kimi-web/test/event-reducer.test.ts
+++ b/apps/kimi-web/test/event-reducer.test.ts
@@ -1,3 +1,10 @@
+/**
+ * Scenario: projected daemon events reduce into immutable web application
+ * state. Responsibilities include messages, sessions, tasks, streaming, and
+ * recovery resets. The real pure reducer is used directly. Run with
+ * `pnpm --filter @moonshot-ai/kimi-web test`.
+ */
+
 import { describe, expect, it } from 'vitest';
 import { createInitialState, reduceAppEvent } from '../src/api/daemon/eventReducer';
 import type { AppMessage, AppSession, AppTask } from '../src/api/types';
@@ -429,6 +436,30 @@ describe('reduceAppEvent taskProgress', () => {
     expect(task?.outputLines ?? []).toHaveLength(0);
   });
 
+  it('clears abandoned subagent text when taskTextReset arrives', () => {
+    const state = {
+      ...createInitialState(),
+      tasksBySession: {
+        s1: [
+          {
+            ...makeSubagentTask('t1', 's1'),
+            text: 'abandoned partial',
+            outputLines: ['Calling Read'],
+          },
+        ],
+      },
+    };
+
+    const next = reduceAppEvent(
+      state,
+      { type: 'taskTextReset', sessionId: 's1', taskId: 't1' },
+      { sessionId: 's1', seq: 1 },
+    );
+
+    expect(next.tasksBySession['s1']?.[0]?.text).toBeUndefined();
+    expect(next.tasksBySession['s1']?.[0]?.outputLines).toEqual(['Calling Read']);
+  });
+
   it('preserves accumulated text across a taskCreated replacement', () => {
     const state = {
       ...createInitialState(),
diff --git a/apps/kimi-web/test/side-chat.test.ts b/apps/kimi-web/test/side-chat.test.ts
index 9c76f1fbf1..83aac0f072 100644
--- a/apps/kimi-web/test/side-chat.test.ts
+++ b/apps/kimi-web/test/side-chat.test.ts
@@ -1,4 +1,8 @@
-// apps/kimi-web/test/side-chat.test.ts
+/**
+ * Scenario: side-channel chat preserves parent runtime controls and manages
+ * its isolated optimistic transcript. The real composable uses a mocked daemon
+ * boundary. Run with `pnpm --filter @moonshot-ai/kimi-web test`.
+ */
 import { describe, expect, it, vi } from 'vitest';
 import { createInitialState } from '../src/api/daemon/eventReducer';
 import { useSideChat } from '../src/composables/client/useSideChat';
@@ -140,3 +144,40 @@ describe('useSideChat — sendSideChatPromptOn', () => {
     );
   });
 });
+
+describe('useSideChat — recovery reset', () => {
+  it('removes the abandoned assistant message when a model replay starts', () => {
+    const state = createState();
+    state.sideChatMessagesByAgent = {
+      agent_btw_1: [
+        {
+          id: 'user-1',
+          sessionId: 'sess_1',
+          role: 'user',
+          content: [{ type: 'text', text: 'question' }],
+          createdAt: '2026-01-01T00:00:00.000Z',
+        },
+        {
+          id: 'assistant-1',
+          sessionId: 'sess_1',
+          role: 'assistant',
+          content: [{ type: 'text', text: 'abandoned partial' }],
+          createdAt: '2026-01-01T00:00:01.000Z',
+        },
+      ],
+    };
+    const sideChat = useSideChat(state, {
+      pushOperationFailure: vi.fn(),
+      nextOptimisticMsgId: () => 'msg-opt',
+      connectEventsIfNeeded: vi.fn(),
+      getEventConn: () => null,
+      resolveThinkingForPrompt: async () => undefined,
+    });
+
+    sideChat.resetSideChatAssistantText('agent_btw_1');
+
+    expect(state.sideChatMessagesByAgent['agent_btw_1']).toEqual([
+      expect.objectContaining({ id: 'user-1' }),
+    ]);
+  });
+});
diff --git a/packages/agent-core-v2/docs/config-manifest.toml b/packages/agent-core-v2/docs/config-manifest.toml
index d89be92abe..30af1ec31f 100644
--- a/packages/agent-core-v2/docs/config-manifest.toml
+++ b/packages/agent-core-v2/docs/config-manifest.toml
@@ -8,7 +8,7 @@
 # commented "# field: type" lines describe the remaining schema fields.
 # Values resolve as: default -> config.toml -> env overlay -> memory.
 
-# Index (22 sections · 3 overlay(s))
+# Index (23 sections · 3 overlay(s))
 #   background               src/agent/task/configSection.ts
 #   cron                     src/app/cron/configSection.ts
 #   defaultPermissionMode    src/agent/permissionMode/configSection.ts
@@ -28,6 +28,7 @@
 #   secondaryModel           src/app/kosongConfig/configSection.ts
 #   services                 src/app/auth/configSection.ts
 #   subagent                 src/session/subagent/configSection.ts
+#   subagentFailover         src/agent/modelFailover/configSection.ts
 #   task                     src/agent/task/configSection.ts
 #   thinking                 src/app/kosongConfig/configSection.ts
 #   tools                    src/agent/toolPolicy/configSection.ts
@@ -352,6 +353,17 @@ merge_all_available_skills = true
 [subagent]
 timeout_ms = 7200000
 
+# ##########################################################################
+# subagentFailover (config.toml: subagent_failover)
+#   owner: src/agent/modelFailover/configSection.ts
+#   scope: core
+# ##########################################################################
+
+[subagent_failover]
+fallbacks = []
+on = ["retry_exhausted", "quota_exhausted"]
+max_switches_per_turn = 1
+
 # ##########################################################################
 # task
 #   owner: src/agent/task/configSection.ts
diff --git a/packages/agent-core-v2/docs/state-manifest.d.ts b/packages/agent-core-v2/docs/state-manifest.d.ts
index 4f6bded88c..9762fbadbd 100644
--- a/packages/agent-core-v2/docs/state-manifest.d.ts
+++ b/packages/agent-core-v2/docs/state-manifest.d.ts
@@ -23,7 +23,7 @@
 // references become '(circular)', and class instances collapse to a '(ClassName)'
 // marker — the wire shape of an entry is the JSON projection of the type here.
 //
-// Index (Session: 28 keys · Agent: 68 keys)
+// Index (Session: 28 keys · Agent: 72 keys)
 //   Session
 //     cron.inFlight                             src/session/cron/sessionCronServiceImpl.ts
 //     cron.lastSeenAt                           src/session/cron/sessionCronServiceImpl.ts
@@ -94,6 +94,10 @@
 //     mcp.mcpToolsByServer                            src/agent/mcp/mcpService.ts
 //     media.registeredKey                             src/agent/media/mediaToolsRegistrar.ts
 //     media.resolved                                  src/agent/media/videoResolverService.ts
+//     modelFailover.activeTurnId                      src/agent/modelFailover/modelFailoverService.ts
+//     modelFailover.emittedWarnings                   src/agent/modelFailover/modelFailoverService.ts
+//     modelFailover.nextFallbackIndex                 src/agent/modelFailover/modelFailoverService.ts
+//     modelFailover.switchesInTurn                    src/agent/modelFailover/modelFailoverService.ts
 //     permissionMode.lastMode                         src/agent/permissionMode/injection/permissionModeInjection.ts
 //     plan.wasActive                                  src/agent/plan/injection/planModeInjection.ts
 //     profile.activeToolNamesOverlay                  src/agent/profile/profileService.ts
@@ -1010,7 +1014,7 @@ export interface AgentStateSnapshot {
   'llmRequester.lastConfigLogSignature': string | undefined;
   'llmRequester.mediaDegradedTurns': Set<number>;
   'llmRequester.mediaStrippedTurns': Map<number, /* MediaStripSnapshot — packages/agent-core-v2/src/agent/contextProjector/contextProjector.ts */ {
-    readonly "__@mediaStripSnapshotBrand@2671": undefined;
+    readonly "__@mediaStripSnapshotBrand@2723": undefined;
   }>;
   'llmRequester.turnConfigs': Map<number, /* TurnRequestConfig — packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts */ {
     readonly resolved: /* ProfileModelContext — packages/agent-core-v2/src/agent/profile/profile.ts */ {
@@ -1082,6 +1086,11 @@ export interface AgentStateSnapshot {
       id?: string;
     };
   }>;
+  // src/agent/modelFailover/modelFailoverService.ts
+  'modelFailover.activeTurnId': number | undefined;
+  'modelFailover.emittedWarnings': Set<string>;
+  'modelFailover.nextFallbackIndex': number;
+  'modelFailover.switchesInTurn': number;
   // src/agent/permissionMode/injection/permissionModeInjection.ts
   'permissionMode.lastMode': 'manual' | 'yolo' | 'auto' | undefined;
   // src/agent/plan/injection/planModeInjection.ts
diff --git a/packages/agent-core-v2/docs/wire-manifest.d.ts b/packages/agent-core-v2/docs/wire-manifest.d.ts
index 01917f495d..cec05a1a2d 100644
--- a/packages/agent-core-v2/docs/wire-manifest.d.ts
+++ b/packages/agent-core-v2/docs/wire-manifest.d.ts
@@ -21,7 +21,7 @@
 // owning model offloads inline media to blob storage), cross-reducers
 // (foreign models that also reduce this record on dispatch and replay).
 
-// Index (44 record types)
+// Index (45 record types)
 //   config.update                      profile              persisted  src/agent/profile/profileOps.ts
 //   context_size.measured              contextSize          transient  src/agent/contextSize/contextSizeOps.ts
 //   context.append_loop_event          contextMemory        persisted  src/agent/contextMemory/contextOps.ts
@@ -44,6 +44,7 @@
 //   llm.request                        llm.requestTrace     persisted  src/agent/llmRequester/llmRequestOps.ts
 //   llm.tools_snapshot                 llm.requestTrace     persisted  src/agent/llmRequester/llmRequestOps.ts
 //   mcp.tools_discovered               mcp.discovery        persisted  src/agent/mcp/mcpDiscoveryOps.ts
+//   model.failover                     modelFailover        persisted  src/agent/modelFailover/modelFailoverOps.ts
 //   permission.record_approval_result  permissionRules      persisted  src/agent/permissionRules/permissionRulesOps.ts
 //   permission.rules.add               permissionRules      transient  src/agent/permissionRules/permissionRulesOps.ts
 //   permission.set_mode                permissionMode       persisted  src/agent/permissionMode/permissionModeOps.ts
@@ -365,6 +366,26 @@ interface McpToolsDiscoveredPayload {
   }[];
 }
 
+/**
+ * model: modelFailover · persisted · toEvent
+ * owner: src/agent/modelFailover/modelFailoverOps.ts
+ */
+interface ModelFailoverPayload {
+  _name: 'model.failover';
+  turnId: number;
+  step: number;
+  stepId?: string;
+  fromModel: string;
+  toModel: string;
+  fromProvider: string;
+  toProvider: string;
+  fromEffort: string;
+  toEffort: string;
+  reason: 'retry_exhausted' | 'quota_exhausted';
+  switchIndex: number;
+  maxSwitches: number;
+}
+
 /**
  * model: permissionRules · persisted
  * owner: src/agent/permissionRules/permissionRulesOps.ts
@@ -637,6 +658,7 @@ interface WirePayloadMap {
   "llm.request": LlmRequestPayload;
   "llm.tools_snapshot": LlmToolsSnapshotPayload;
   "mcp.tools_discovered": McpToolsDiscoveredPayload;
+  "model.failover": ModelFailoverPayload;
   "permission.record_approval_result": PermissionRecordApprovalResultPayload;
   "permission.rules.add": PermissionRulesAddPayload;
   "permission.set_mode": PermissionSetModePayload;
diff --git a/packages/agent-core-v2/scripts/check-domain-layers.mjs b/packages/agent-core-v2/scripts/check-domain-layers.mjs
index b29f110e9e..2e2bcaf52c 100644
--- a/packages/agent-core-v2/scripts/check-domain-layers.mjs
+++ b/packages/agent-core-v2/scripts/check-domain-layers.mjs
@@ -196,6 +196,7 @@ const DOMAIN_LAYER = new Map([
   ['fullCompaction', 4],
   ['loop', 4],
   ['stepRetry', 4],
+  ['modelFailover', 4],
   ['media', 4],
   // `edit` spans two scopes: the App-scope `IFileEditService` capability (pure
   // TextModel / EditService + os-backed read/write over the L1 hostFs bridge)
diff --git a/packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts b/packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts
index a7a9f694d1..ea1c2ffce5 100644
--- a/packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts
+++ b/packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts
@@ -58,6 +58,7 @@ export interface IAgentLLMRequesterService {
   readonly _serviceBrand: undefined;
 
   prepareTurnConfig(turnId: number): PreparedTurnRequestConfig | undefined;
+  invalidateTurnConfig(turnId: number): void;
 
   request(
     overrides?: AgentLLMRequestOverrides,
diff --git a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
index 057bebd882..e71455d2c5 100644
--- a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
+++ b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
@@ -15,7 +15,10 @@
  * `<video path>` tag) so the internal reference never reaches the wire. When a
  * model is configured, `prepareTurnConfig` snapshots the
  * model, effective thinking effort, and system prompt at the turn boundary
- * so loop telemetry and every request in that turn share one configuration.
+ * so loop telemetry and every request in that turn share one configuration;
+ * `invalidateTurnConfig` discards that snapshot and provider-specific
+ * recovery projections when an explicit runtime model transition must take
+ * effect inside the same turn.
  * Forwards streamed `part` events to the caller's `onPart`
  * handler, records `usage` through `IAgentUsageService`, resolves to an
  * `AgentLLMRequestFinish` on the `finish` event, logs the request lifecycle
@@ -225,6 +228,12 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     return { thinkingEffort: config.resolved.thinkingLevel };
   }
 
+  invalidateTurnConfig(turnId: number): void {
+    this.turnConfigs.delete(turnId);
+    this.mediaDegradedTurns.delete(turnId);
+    this.mediaStrippedTurns.delete(turnId);
+  }
+
   async request(
     overrides: AgentLLMRequestOverrides = {},
     onPart: AgentLLMRequestPartHandler = noopOnPart,
diff --git a/packages/agent-core-v2/src/agent/loop/loopService.ts b/packages/agent-core-v2/src/agent/loop/loopService.ts
index 69a67fd771..e6ff957b16 100644
--- a/packages/agent-core-v2/src/agent/loop/loopService.ts
+++ b/packages/agent-core-v2/src/agent/loop/loopService.ts
@@ -19,11 +19,13 @@
  * assistant message enqueues nothing, so the queue empties and the turn
  * completes), and orchestrators (`prompt`, `goal`, `externalHooks`, `task`)
  * steer the turn by enqueueing further requests. A failed step is dispatched
- * to the registered error handlers (first match wins); a handler that claims
- * and catches the error has already enqueued the turn's continuation itself —
- * `stepRetry` re-enqueues the failed driver after backoff, `fullCompaction`
- * compacts and re-enqueues it — so the loop only learns caught-or-not, while
- * an unclaimed or uncaught error fails the turn. Emits `turn.*` / delta
+ * to the registered error handlers in order until one both matches and
+ * recovers it; a matching handler may decline so a later recovery policy can
+ * take over. A handler that catches the error has already enqueued the turn's
+ * continuation itself — `stepRetry` re-enqueues the failed driver after
+ * backoff, `fullCompaction` compacts and re-enqueues it — so the loop only
+ * learns caught-or-not, while an unclaimed or uncaught error fails the turn.
+ * Emits `turn.*` / delta
  * events through `event`, persists loop events through `contextMemory`, and
  * reads the step budget from `config`. The plain-data loop state
  * (`nextReservedTurnId`, `lastRequestTraceId`, `disposing`) is registered
@@ -760,17 +762,18 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
         };
       },
     };
-    const handler = this.errorHandlers.find((entry) => entry.match(context));
-    if (handler === undefined) return undefined;
-    try {
-      if (await handler.handle(context)) {
-        runtime.current = undefined;
-        return { type: 'continue' };
+    for (const handler of this.errorHandlers) {
+      if (!handler.match(context)) continue;
+      try {
+        if (await handler.handle(context)) {
+          runtime.current = undefined;
+          return { type: 'continue' };
+        }
+      } catch (handlerError) {
+        return this.handleLoopCancellation(runtime, handlerError) ?? this.failLoopStep(runtime, handlerError);
       }
-      return undefined;
-    } catch (handlerError) {
-      return this.handleLoopCancellation(runtime, handlerError) ?? this.failLoopStep(runtime, handlerError);
     }
+    return undefined;
   }
 
   private failLoopStep(runtime: LoopRuntime, error: unknown): LoopErrorDisposition {
diff --git a/packages/agent-core-v2/src/agent/modelFailover/configSection.ts b/packages/agent-core-v2/src/agent/modelFailover/configSection.ts
new file mode 100644
index 0000000000..96ec9ab6be
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/modelFailover/configSection.ts
@@ -0,0 +1,89 @@
+/**
+ * `modelFailover` domain (L4) — runtime subagent model-failover preferences.
+ *
+ * Owns the `[subagent_failover]` configuration section: an ordered fallback
+ * route, the failure classes that may advance it, and the per-turn switch
+ * limit. `primary` resolves through the live default-model pointer;
+ * `secondary` resolves through the existing secondary-model recipe; every
+ * other value is a model alias. Self-registered at module load through
+ * `config`.
+ */
+
+import { z } from 'zod';
+
+import { IConfigService } from '#/app/config/config';
+import { registerConfigSection } from '#/app/config/configSectionContributions';
+import {
+  DEFAULT_MODEL_SECTION,
+  SECONDARY_MODEL_SECTION,
+  type SecondaryModelConfig,
+} from '#/app/kosongConfig/configSection';
+import {
+  SECONDARY_DERIVED_MODEL_ID,
+  secondaryModelPatch,
+} from '#/app/kosongConfig/secondaryModelOverlay';
+
+export const MODEL_FAILOVER_SECTION = 'subagentFailover';
+
+export const ModelFailoverTriggerSchema = z.enum(['retry_exhausted', 'quota_exhausted']);
+
+export type ModelFailoverTrigger = z.infer<typeof ModelFailoverTriggerSchema>;
+
+export const ModelFailoverBindingSchema = z.object({
+  model: z.string().min(1),
+  effort: z.string().min(1).optional(),
+});
+
+export type ModelFailoverBinding = z.infer<typeof ModelFailoverBindingSchema>;
+
+export const ModelFailoverConfigSchema = z.object({
+  fallbacks: z.array(ModelFailoverBindingSchema),
+  on: z.array(ModelFailoverTriggerSchema).optional(),
+  maxSwitchesPerTurn: z.number().int().min(0).optional(),
+});
+
+export type ModelFailoverConfig = z.infer<typeof ModelFailoverConfigSchema>;
+
+export const DEFAULT_MODEL_FAILOVER_TRIGGERS: readonly ModelFailoverTrigger[] = [
+  'retry_exhausted',
+  'quota_exhausted',
+];
+
+export const DEFAULT_MAX_MODEL_SWITCHES_PER_TURN = 1;
+
+registerConfigSection(MODEL_FAILOVER_SECTION, ModelFailoverConfigSchema, {
+  defaultValue: {
+    fallbacks: [],
+    on: [...DEFAULT_MODEL_FAILOVER_TRIGGERS],
+    maxSwitchesPerTurn: DEFAULT_MAX_MODEL_SWITCHES_PER_TURN,
+  },
+});
+
+export interface ResolvedModelFailoverBinding {
+  readonly model: string;
+  readonly effort?: string;
+}
+
+export function resolveModelFailoverBinding(
+  binding: ModelFailoverBinding,
+  config: IConfigService,
+): ResolvedModelFailoverBinding | undefined {
+  const choice = binding.model.trim();
+  if (choice === 'primary') {
+    const model = config.get<string | undefined>(DEFAULT_MODEL_SECTION)?.trim();
+    return model === undefined || model.length === 0
+      ? undefined
+      : { model, effort: binding.effort };
+  }
+  if (choice === 'secondary') {
+    const secondary = config.get<SecondaryModelConfig | undefined>(SECONDARY_MODEL_SECTION);
+    if (secondary === undefined) return undefined;
+    const model = secondary.model?.trim();
+    if (model === undefined || model.length === 0) return undefined;
+    return {
+      model: secondaryModelPatch(secondary) === undefined ? model : SECONDARY_DERIVED_MODEL_ID,
+      effort: binding.effort ?? secondary.defaultEffort,
+    };
+  }
+  return choice.length === 0 ? undefined : { model: choice, effort: binding.effort };
+}
diff --git a/packages/agent-core-v2/src/agent/modelFailover/flag.ts b/packages/agent-core-v2/src/agent/modelFailover/flag.ts
new file mode 100644
index 0000000000..92e94027bb
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/modelFailover/flag.ts
@@ -0,0 +1,25 @@
+/**
+ * `modelFailover` domain (L4) — registers the runtime model-failover
+ * experimental flag into `flag`.
+ *
+ * Gates automatic cross-model recovery independently from secondary-model
+ * spawn routing. Off by default; enabled through the per-feature env value,
+ * the master experimental env value, or `[experimental]`.
+ */
+
+import { type FlagDefinitionInput, registerFlagDefinition } from '#/app/flag/flagRegistry';
+
+export const MODEL_FAILOVER_FLAG_ID = 'model-failover';
+export const MODEL_FAILOVER_FLAG_ENV = 'KIMI_CODE_EXPERIMENTAL_MODEL_FAILOVER';
+
+export const modelFailoverFlag: FlagDefinitionInput = {
+  id: MODEL_FAILOVER_FLAG_ID,
+  title: 'Runtime model failover',
+  description:
+    'Let subagents switch to an ordered fallback model after retry exhaustion or provider quota exhaustion.',
+  env: MODEL_FAILOVER_FLAG_ENV,
+  default: false,
+  surface: 'core',
+};
+
+registerFlagDefinition(modelFailoverFlag);
diff --git a/packages/agent-core-v2/src/agent/modelFailover/modelFailover.ts b/packages/agent-core-v2/src/agent/modelFailover/modelFailover.ts
new file mode 100644
index 0000000000..0402db1130
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/modelFailover/modelFailover.ts
@@ -0,0 +1,16 @@
+/**
+ * `modelFailover` domain (L4) — `IAgentModelFailoverService` contract.
+ *
+ * Marks the Agent-scoped runtime recovery policy that advances a subagent
+ * through its configured model route. Bound at Agent scope.
+ */
+
+import { createDecorator } from '#/_base/di/instantiation';
+
+export interface IAgentModelFailoverService {
+  readonly _serviceBrand: undefined;
+}
+
+export const IAgentModelFailoverService = createDecorator<IAgentModelFailoverService>(
+  'agentModelFailoverService',
+);
diff --git a/packages/agent-core-v2/src/agent/modelFailover/modelFailoverOps.ts b/packages/agent-core-v2/src/agent/modelFailover/modelFailoverOps.ts
new file mode 100644
index 0000000000..89910fc13f
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/modelFailover/modelFailoverOps.ts
@@ -0,0 +1,69 @@
+/**
+ * `modelFailover` domain (L4) — persisted model-switch audit records.
+ *
+ * Defines the replayable `ModelFailoverModel`, its `model.failover` Op, and
+ * the `turn.step.failover` event projected from each live dispatch through
+ * `wire`. The Model keeps only the latest switch; the append-only wire record
+ * remains the complete audit trail.
+ */
+
+import { z } from 'zod';
+
+import { defineModel } from '#/wire/model';
+
+import { ModelFailoverTriggerSchema } from './configSection';
+
+export interface TurnStepFailoverEvent {
+  readonly type: 'turn.step.failover';
+  readonly turnId: number;
+  readonly step: number;
+  readonly stepId?: string;
+  readonly fromModel: string;
+  readonly toModel: string;
+  readonly fromProvider: string;
+  readonly toProvider: string;
+  readonly fromEffort: string;
+  readonly toEffort: string;
+  readonly reason: 'retry_exhausted' | 'quota_exhausted';
+  readonly switchIndex: number;
+  readonly maxSwitches: number;
+}
+
+export type ModelFailoverSwitch = Omit<TurnStepFailoverEvent, 'type'>;
+
+export interface ModelFailoverState {
+  readonly last?: ModelFailoverSwitch;
+}
+
+export const ModelFailoverModel = defineModel<ModelFailoverState>('modelFailover', () => ({}));
+
+declare module '#/app/event/eventBus' {
+  interface DomainEventMap {
+    'turn.step.failover': TurnStepFailoverEvent;
+  }
+}
+
+declare module '#/wire/types' {
+  interface PersistedOpMap {
+    'model.failover': typeof modelFailoverSwitch;
+  }
+}
+
+export const modelFailoverSwitch = ModelFailoverModel.defineOp('model.failover', {
+  schema: z.object({
+    turnId: z.number().int().min(0),
+    step: z.number().int().min(1),
+    stepId: z.string().optional(),
+    fromModel: z.string().min(1),
+    toModel: z.string().min(1),
+    fromProvider: z.string().min(1),
+    toProvider: z.string().min(1),
+    fromEffort: z.string(),
+    toEffort: z.string(),
+    reason: ModelFailoverTriggerSchema,
+    switchIndex: z.number().int().min(1),
+    maxSwitches: z.number().int().min(1),
+  }),
+  apply: (_state, payload) => ({ last: payload }),
+  toEvent: (payload) => ({ type: 'turn.step.failover' as const, ...payload }),
+});
diff --git a/packages/agent-core-v2/src/agent/modelFailover/modelFailoverService.ts b/packages/agent-core-v2/src/agent/modelFailover/modelFailoverService.ts
new file mode 100644
index 0000000000..e0e8cd55fd
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/modelFailover/modelFailoverService.ts
@@ -0,0 +1,364 @@
+/**
+ * `modelFailover` domain (L4) — `IAgentModelFailoverService` implementation.
+ *
+ * Participates after `stepRetry` in the Agent loop's ordered error-recovery
+ * chain. For non-main agents, it classifies provider failures through
+ * `kosong`, advances the configured fallback route within a bounded per-turn
+ * state machine, atomically updates the persisted `profile` model/effort
+ * binding, invalidates the current `llmRequester` turn snapshot, records the
+ * switch through `wire`, and re-enqueues the same failed driver. Reads
+ * preferences from `config`, the experiment from `flag`, model/provider data
+ * from `modelCatalog`, identity from `scopeContext`, turn facts from `event`,
+ * and mutable counters from `agentState`; warnings and diagnostics go through
+ * `event` and `log`. Bound at Agent scope and activated with the scope so its
+ * recovery handler exists before the first turn.
+ */
+
+import { Disposable } from '#/_base/di/lifecycle';
+import { LifecycleScope, ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { ILogService } from '#/_base/log/log';
+import { defineState } from '#/_base/state/stateRegistry';
+import { IAgentLLMRequesterService } from '#/agent/llmRequester/llmRequester';
+import { IAgentLoopService, type LoopErrorContext } from '#/agent/loop/loop';
+import { IAgentProfileService } from '#/agent/profile/profile';
+import { IAgentScopeContext } from '#/agent/scopeContext/scopeContext';
+import { IAgentStateService } from '#/agent/state/agentState';
+import { IAgentStepRetryService } from '#/agent/stepRetry/stepRetry';
+import { IConfigService } from '#/app/config/config';
+import { IEventBus } from '#/app/event/eventBus';
+import { IFlagService } from '#/app/flag/flag';
+import { unwrapErrorCause } from '#/errors';
+import {
+  APIEmptyResponseError,
+  classifyApiError,
+  isRetryableGenerateError,
+} from '#/kosong/contract/errors';
+import { IModelCatalog, type Model } from '#/kosong/model/catalog';
+import { normalizeRequestedThinkingEffort } from '#/kosong/model/thinking';
+import { IWireService } from '#/wire/wire';
+
+import {
+  DEFAULT_MAX_MODEL_SWITCHES_PER_TURN,
+  DEFAULT_MODEL_FAILOVER_TRIGGERS,
+  MODEL_FAILOVER_SECTION,
+  type ModelFailoverBinding,
+  type ModelFailoverConfig,
+  type ModelFailoverTrigger,
+  resolveModelFailoverBinding,
+  type ResolvedModelFailoverBinding,
+} from './configSection';
+import { MODEL_FAILOVER_FLAG_ID } from './flag';
+import { IAgentModelFailoverService } from './modelFailover';
+import { modelFailoverSwitch } from './modelFailoverOps';
+
+export const modelFailoverActiveTurnIdKey = defineState<number | undefined>(
+  'modelFailover.activeTurnId',
+  () => undefined as number | undefined,
+);
+export const modelFailoverSwitchesInTurnKey = defineState<number>(
+  'modelFailover.switchesInTurn',
+  () => 0,
+);
+export const modelFailoverNextFallbackIndexKey = defineState<number>(
+  'modelFailover.nextFallbackIndex',
+  () => 0,
+);
+export const modelFailoverEmittedWarningsKey = defineState<Set<string>>(
+  'modelFailover.emittedWarnings',
+  () => new Set(),
+);
+
+export class AgentModelFailoverService extends Disposable implements IAgentModelFailoverService {
+  declare readonly _serviceBrand: undefined;
+
+  constructor(
+    @IAgentLoopService private readonly loop: IAgentLoopService,
+    @IAgentStepRetryService _stepRetry: IAgentStepRetryService,
+    @IAgentLLMRequesterService private readonly llmRequester: IAgentLLMRequesterService,
+    @IAgentProfileService private readonly profile: IAgentProfileService,
+    @IAgentScopeContext private readonly scopeContext: IAgentScopeContext,
+    @IAgentStateService private readonly states: IAgentStateService,
+    @IConfigService private readonly config: IConfigService,
+    @IFlagService private readonly flags: IFlagService,
+    @IModelCatalog private readonly modelCatalog: IModelCatalog,
+    @IEventBus private readonly eventBus: IEventBus,
+    @IWireService private readonly wire: IWireService,
+    @ILogService private readonly log: ILogService,
+  ) {
+    super();
+    this.states.register(modelFailoverActiveTurnIdKey);
+    this.states.register(modelFailoverSwitchesInTurnKey);
+    this.states.register(modelFailoverNextFallbackIndexKey);
+    this.states.register(modelFailoverEmittedWarningsKey);
+    this._register(
+      this.loop.registerLoopErrorHandler(
+        {
+          id: 'model-failover',
+          match: (context) => this.match(context),
+          handle: (context) => this.recover(context),
+        },
+        { after: 'step-retry' },
+      ),
+    );
+    this._register(
+      this.eventBus.subscribe('turn.started', (event) => {
+        this.resetForTurn(event.turnId);
+      }),
+    );
+    this.validateConfiguration();
+  }
+
+  private get activeTurnId(): number | undefined {
+    return this.states.get(modelFailoverActiveTurnIdKey);
+  }
+
+  private set activeTurnId(value: number | undefined) {
+    this.states.set(modelFailoverActiveTurnIdKey, value);
+  }
+
+  private get switchesInTurn(): number {
+    return this.states.get(modelFailoverSwitchesInTurnKey);
+  }
+
+  private set switchesInTurn(value: number) {
+    this.states.set(modelFailoverSwitchesInTurnKey, value);
+  }
+
+  private get nextFallbackIndex(): number {
+    return this.states.get(modelFailoverNextFallbackIndexKey);
+  }
+
+  private set nextFallbackIndex(value: number) {
+    this.states.set(modelFailoverNextFallbackIndexKey, value);
+  }
+
+  private get emittedWarnings(): Set<string> {
+    return this.states.get(modelFailoverEmittedWarningsKey);
+  }
+
+  private match(context: LoopErrorContext): boolean {
+    if (this.scopeContext.agentId === 'main') return false;
+    if (!this.flags.enabled(MODEL_FAILOVER_FLAG_ID)) return false;
+    const settings = this.settings();
+    if (settings.fallbacks.length === 0) return false;
+    const trigger = this.triggerFor(context.error);
+    return trigger !== undefined && settings.on.includes(trigger);
+  }
+
+  private async recover(context: LoopErrorContext): Promise<boolean> {
+    const driver = context.failedDriver;
+    if (
+      driver === undefined ||
+      context.step === undefined ||
+      context.signal.aborted ||
+      currentStepAborted(context)
+    ) {
+      return false;
+    }
+    const trigger = this.triggerFor(context.error);
+    if (trigger === undefined) return false;
+    const settings = this.settings();
+    if (!settings.on.includes(trigger)) return false;
+    this.ensureTurn(context.turnId, settings.fallbacks);
+    if (this.switchesInTurn >= settings.maxSwitchesPerTurn) return false;
+
+    const current = this.profile.data();
+    const fromModel = current.modelAlias;
+    if (fromModel === undefined) return false;
+    const fromResolved = this.tryResolveModel(fromModel, `active model "${fromModel}"`);
+    if (fromResolved === undefined) return false;
+
+    while (this.nextFallbackIndex < settings.fallbacks.length) {
+      const fallbackIndex = this.nextFallbackIndex;
+      this.nextFallbackIndex = fallbackIndex + 1;
+      const target = this.resolveAndValidate(settings.fallbacks[fallbackIndex]!);
+      if (target === undefined) return false;
+      if (target.binding.model === fromModel) continue;
+
+      try {
+        await this.profile.setModelBinding(target.binding.model, target.binding.effort);
+      } catch (error) {
+        this.warn(
+          'model-failover-binding-rejected',
+          `Model failover cannot switch to "${target.binding.model}": ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return false;
+      }
+      if (context.signal.aborted || currentStepAborted(context)) return false;
+
+      const switched = this.profile.data();
+      const toModel = switched.modelAlias;
+      if (toModel === undefined) return false;
+      this.llmRequester.invalidateTurnConfig(context.turnId);
+      this.switchesInTurn += 1;
+      this.log.info('Switching subagent to fallback model', {
+        turnId: context.turnId,
+        step: context.step,
+        fromModel,
+        toModel,
+        fromProvider: fromResolved.providerName,
+        toProvider: target.model.providerName,
+        reason: trigger,
+        switchIndex: this.switchesInTurn,
+        maxSwitches: settings.maxSwitchesPerTurn,
+      });
+      this.wire.dispatch(
+        modelFailoverSwitch({
+          turnId: context.turnId,
+          step: context.step,
+          stepId: context.stepId,
+          fromModel,
+          toModel,
+          fromProvider: fromResolved.providerName,
+          toProvider: target.model.providerName,
+          fromEffort: current.thinkingLevel,
+          toEffort: switched.thinkingLevel,
+          reason: trigger,
+          switchIndex: this.switchesInTurn,
+          maxSwitches: settings.maxSwitchesPerTurn,
+        }),
+      );
+      context.retry(driver, { at: 'head' });
+      return true;
+    }
+    return false;
+  }
+
+  private settings(): {
+    readonly fallbacks: readonly ModelFailoverBinding[];
+    readonly on: readonly ModelFailoverTrigger[];
+    readonly maxSwitchesPerTurn: number;
+  } {
+    const configured = this.config.get<ModelFailoverConfig | undefined>(MODEL_FAILOVER_SECTION);
+    return {
+      fallbacks: configured?.fallbacks ?? [],
+      on: configured?.on ?? DEFAULT_MODEL_FAILOVER_TRIGGERS,
+      maxSwitchesPerTurn: configured?.maxSwitchesPerTurn ?? DEFAULT_MAX_MODEL_SWITCHES_PER_TURN,
+    };
+  }
+
+  private triggerFor(error: unknown): ModelFailoverTrigger | undefined {
+    const unwrapped = unwrapErrorCause(error);
+    if (unwrapped instanceof APIEmptyResponseError && unwrapped.finishReason === 'filtered') {
+      return undefined;
+    }
+    const classification = classifyApiError(unwrapped);
+    if (classification.kind === 'quota_exhausted') {
+      return 'quota_exhausted';
+    }
+    if (!isRetryableGenerateError(unwrapped)) return undefined;
+    if (
+      classification.kind === 'overloaded' ||
+      classification.kind === 'rate_limit' ||
+      classification.kind === '5xx_server' ||
+      classification.kind === 'network' ||
+      classification.kind === 'timeout' ||
+      classification.kind === 'empty_response'
+    ) {
+      return 'retry_exhausted';
+    }
+    return classification.kind === '4xx_client' &&
+      (classification.statusCode === 408 || classification.statusCode === 409)
+      ? 'retry_exhausted'
+      : undefined;
+  }
+
+  private resetForTurn(turnId: number): void {
+    this.activeTurnId = turnId;
+    this.switchesInTurn = 0;
+    this.nextFallbackIndex = 0;
+  }
+
+  private ensureTurn(turnId: number, fallbacks: readonly ModelFailoverBinding[]): void {
+    if (this.activeTurnId !== turnId) this.resetForTurn(turnId);
+    if (this.switchesInTurn !== 0 || this.nextFallbackIndex !== 0) return;
+    const currentModel = this.profile.data().modelAlias;
+    if (currentModel === undefined) return;
+    for (let index = 0; index < fallbacks.length; index += 1) {
+      const resolved = resolveModelFailoverBinding(fallbacks[index]!, this.config);
+      if (resolved?.model === currentModel) this.nextFallbackIndex = index + 1;
+    }
+  }
+
+  private validateConfiguration(): void {
+    if (this.scopeContext.agentId !== 'main') return;
+    if (!this.flags.enabled(MODEL_FAILOVER_FLAG_ID)) return;
+    for (const binding of this.settings().fallbacks) {
+      this.resolveAndValidate(binding);
+    }
+  }
+
+  private resolveAndValidate(
+    binding: ModelFailoverBinding,
+  ): { readonly binding: ResolvedModelFailoverBinding; readonly model: Model } | undefined {
+    const resolved = resolveModelFailoverBinding(binding, this.config);
+    if (resolved === undefined) {
+      this.warn(
+        'model-failover-unresolved-binding',
+        `Model failover fallback "${binding.model}" does not resolve to a configured model alias.`,
+      );
+      return undefined;
+    }
+    const model = this.tryResolveModel(resolved.model, `fallback "${binding.model}"`);
+    if (model === undefined) return undefined;
+    const requestedEffort = normalizeRequestedThinkingEffort(resolved.effort);
+    const supportedEfforts = (model.supportEfforts ?? [])
+      .map((effort) => effort.trim().toLowerCase())
+      .filter((effort) => effort.length > 0);
+    if (
+      requestedEffort !== undefined &&
+      requestedEffort !== 'off' &&
+      requestedEffort !== 'on' &&
+      supportedEfforts.length > 0 &&
+      !supportedEfforts.includes(requestedEffort)
+    ) {
+      this.warn(
+        'model-failover-invalid-effort',
+        `Model failover fallback "${binding.model}" requests effort "${resolved.effort}" but model "${resolved.model}" lists: ${supportedEfforts.join(', ')}.`,
+      );
+      return undefined;
+    }
+    try {
+      this.profile.validateModelBinding(resolved.model, resolved.effort);
+    } catch (error) {
+      this.warn(
+        'model-failover-invalid-effort',
+        `Model failover fallback "${binding.model}" has an invalid effort for "${resolved.model}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+    return { binding: resolved, model };
+  }
+
+  private tryResolveModel(alias: string, label: string): Model | undefined {
+    try {
+      return this.modelCatalog.get(alias);
+    } catch (error) {
+      this.warn(
+        'model-failover-invalid-model',
+        `Model failover ${label} resolved to invalid alias "${alias}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+  }
+
+  private warn(code: string, message: string): void {
+    const key = `${code}\u0000${message}`;
+    if (this.emittedWarnings.has(key)) return;
+    this.emittedWarnings.add(key);
+    this.log.warn(message, { code });
+    this.eventBus.publish({ type: 'warning', code, message });
+  }
+}
+
+function currentStepAborted(context: LoopErrorContext): boolean {
+  return context.currentStep?.signal.aborted === true;
+}
+
+registerScopedService(
+  LifecycleScope.Agent,
+  IAgentModelFailoverService,
+  AgentModelFailoverService,
+  ScopeActivation.OnScopeCreated,
+  'modelFailover',
+);
diff --git a/packages/agent-core-v2/src/agent/profile/profile.ts b/packages/agent-core-v2/src/agent/profile/profile.ts
index 72e5359e0e..703e2d68d0 100644
--- a/packages/agent-core-v2/src/agent/profile/profile.ts
+++ b/packages/agent-core-v2/src/agent/profile/profile.ts
@@ -126,6 +126,8 @@ export interface IAgentProfileService {
   applyBindingSnapshot(snapshot: ProfileBindingSnapshot): void;
   bind(input: BindAgentInput): Promise<void>;
   setModel(model: string): Promise<ProfileSetModelResult>;
+  validateModelBinding(model: string, thinking?: string): ProfileSetModelResult;
+  setModelBinding(model: string, thinking?: string): Promise<ProfileSetModelResult>;
   setThinking(level: string): void;
   getModel(): string;
   useProfile(profile: ResolvedAgentProfile, context: SystemPromptContext): void;
diff --git a/packages/agent-core-v2/src/agent/profile/profileService.ts b/packages/agent-core-v2/src/agent/profile/profileService.ts
index 9c282609b5..0bf36f98ec 100644
--- a/packages/agent-core-v2/src/agent/profile/profileService.ts
+++ b/packages/agent-core-v2/src/agent/profile/profileService.ts
@@ -375,6 +375,49 @@ export class AgentProfileService extends Disposable implements IAgentProfileServ
     };
   }
 
+  async setModelBinding(alias: string, thinking?: string): Promise<ProfileSetModelResult> {
+    const result = this.validateModelBinding(alias, thinking);
+    const model = this.modelCatalog.get(alias);
+    const previousModel = this.modelAlias;
+    const previousEffort = this.thinkingLevel;
+    if (this.profileName === undefined) {
+      await this.bind({
+        profile: DEFAULT_AGENT_PROFILE_NAME,
+        model: alias,
+        thinking,
+        strictThinking: thinking !== undefined,
+      });
+    } else {
+      this.update({
+        modelAlias: alias,
+        thinkingLevel: this.resolveThinkingEffort(thinking, model),
+      });
+    }
+    if (this.modelAlias !== previousModel) {
+      this.telemetry.track2('model_switch', { model: alias });
+    }
+    const effort = this.thinkingLevel;
+    if (effort !== previousEffort) {
+      this.telemetry.track2('thinking_toggle', {
+        enabled: effort !== 'off',
+        effort,
+        from: previousEffort,
+      });
+    }
+    return result;
+  }
+
+  validateModelBinding(alias: string, thinking?: string): ProfileSetModelResult {
+    const model = this.modelCatalog.get(alias);
+    if (thinking !== undefined) {
+      this.assertThinkingEffortSupported(thinking, model, alias);
+    }
+    return {
+      model: alias,
+      providerName: model.providerName,
+    };
+  }
+
   setThinking(level: string): void {
     const previousEffort = this.thinkingLevel;
     this.assertThinkingEffortSupported(level, this.tryResolveRawModel(), this.modelAlias ?? '');
diff --git a/packages/agent-core-v2/src/index.ts b/packages/agent-core-v2/src/index.ts
index 3f667afe1e..23b5a22d67 100644
--- a/packages/agent-core-v2/src/index.ts
+++ b/packages/agent-core-v2/src/index.ts
@@ -482,6 +482,11 @@ export * from '#/agent/fullCompaction/fullCompaction';
 export * from '#/agent/fullCompaction/fullCompactionService';
 export * from '#/agent/fullCompaction/compactionOps';
 export * from '#/agent/fullCompaction/types';
+import '#/agent/modelFailover/configSection';
+import '#/agent/modelFailover/flag';
+export * from '#/agent/modelFailover/modelFailover';
+export * from '#/agent/modelFailover/modelFailoverService';
+export * from '#/agent/modelFailover/modelFailoverOps';
 export * from '#/agent/llmRequester/llmRequester';
 export * from '#/agent/llmRequester/llmRequesterService';
 export * from '#/agent/faultInjection/faultInjection';
diff --git a/packages/agent-core-v2/test/agent/llmRequester/llmRequester.test.ts b/packages/agent-core-v2/test/agent/llmRequester/llmRequester.test.ts
index e50876301c..408c33fbfc 100644
--- a/packages/agent-core-v2/test/agent/llmRequester/llmRequester.test.ts
+++ b/packages/agent-core-v2/test/agent/llmRequester/llmRequester.test.ts
@@ -245,6 +245,29 @@ describe('LLMRequester service migration coverage', () => {
       expect((requests[0]?.args as Record<string, unknown> | undefined)?.['projection']).toBeUndefined();
       expect(requests[1]?.args).toMatchObject({ projection: 'strict' });
     });
+
+    it('rebuilds the same-turn model snapshot after explicit invalidation', async () => {
+      const turnId = 7;
+      expect(llmRequester.prepareTurnConfig(turnId)).toEqual({ thinkingEffort: 'off' });
+      ctx.configureRuntimeModel({
+        type: 'openai',
+        model: 'fallback-model',
+        apiKey: 'YOUR_API_KEY',
+      });
+
+      ctx.mockNextResponse({ type: 'text', text: 'before invalidation' });
+      await llmRequester.request({ source: { type: 'turn', turnId } });
+      expect(wireEvents(ctx, 'llm.request').at(-1)?.args).toMatchObject({
+        modelAlias: 'mock-model',
+      });
+
+      llmRequester.invalidateTurnConfig(turnId);
+      ctx.mockNextResponse({ type: 'text', text: 'after invalidation' });
+      await llmRequester.request({ source: { type: 'turn', turnId } });
+      expect(wireEvents(ctx, 'llm.request').at(-1)?.args).toMatchObject({
+        modelAlias: 'fallback-model',
+      });
+    });
   });
 
   describe('tool-call deltas', () => {
diff --git a/packages/agent-core-v2/test/agent/loop/loop.test.ts b/packages/agent-core-v2/test/agent/loop/loop.test.ts
index 02a7a24767..349693e451 100644
--- a/packages/agent-core-v2/test/agent/loop/loop.test.ts
+++ b/packages/agent-core-v2/test/agent/loop/loop.test.ts
@@ -225,6 +225,71 @@ describe('Agent loop', () => {
     );
   });
 
+  it('continues to a later matching error handler when an earlier handler declines recovery', async () => {
+    profile.update({ activeToolNames: [] });
+    const handledBy: string[] = [];
+
+    loop.registerLoopErrorHandler({
+      id: 'test-decline-generate-error',
+      match: () => true,
+      handle: async () => {
+        handledBy.push('declined');
+        return false;
+      },
+    });
+    loop.registerLoopErrorHandler({
+      id: 'test-recover-after-decline',
+      match: () => true,
+      handle: async (hookCtx) => {
+        handledBy.push('recovered');
+        ctx.mockNextResponse({ type: 'text', text: 'Recovered later.' });
+        if (hookCtx.failedDriver === undefined) return false;
+        hookCtx.retry(hookCtx.failedDriver, { at: 'head' });
+        return true;
+      },
+    });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
+    await ctx.untilTurnEnd();
+
+    expect(handledBy).toEqual(['declined', 'recovered']);
+    expect(ctx.allEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'completed' }),
+      }),
+    );
+  });
+
+  it('stops dispatching error handlers after the first successful recovery', async () => {
+    profile.update({ activeToolNames: [] });
+    let laterHandlerCalled = false;
+
+    loop.registerLoopErrorHandler({
+      id: 'test-first-successful-recovery',
+      match: () => true,
+      handle: async (hookCtx) => {
+        ctx.mockNextResponse({ type: 'text', text: 'Recovered first.' });
+        if (hookCtx.failedDriver === undefined) return false;
+        hookCtx.retry(hookCtx.failedDriver, { at: 'head' });
+        return true;
+      },
+    });
+    loop.registerLoopErrorHandler({
+      id: 'test-must-not-run-after-recovery',
+      match: () => true,
+      handle: async () => {
+        laterHandlerCalled = true;
+        return false;
+      },
+    });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
+    await ctx.untilTurnEnd();
+
+    expect(laterHandlerCalled).toBe(false);
+  });
+
   it('reports an untyped LLM error message without an internal-code prefix', async () => {
     profile.update({ activeToolNames: [] });
 
@@ -1070,6 +1135,7 @@ function createTimingRequester(): IAgentLLMRequesterService {
   const requester: IAgentLLMRequesterService = {
     _serviceBrand: undefined,
     prepareTurnConfig: () => ({ thinkingEffort: 'off' }),
+    invalidateTurnConfig: () => {},
     async request(_overrides, onPart = () => {}) {
       await onPart({ type: 'text', text: 'answer' });
       return {
diff --git a/packages/agent-core-v2/test/agent/modelFailover/modelFailover.test.ts b/packages/agent-core-v2/test/agent/modelFailover/modelFailover.test.ts
new file mode 100644
index 0000000000..f772eee814
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/modelFailover/modelFailover.test.ts
@@ -0,0 +1,725 @@
+/**
+ * Scenario: a subagent recovers model-generation failures through an ordered,
+ * bounded fallback route.
+ * Responsibilities: eligibility, retry handoff, atomic model/effort rebinding,
+ * same-driver replay, audit events, persistence, and Agent-scope isolation.
+ * Wiring: the real Agent loop/profile/requester/wire services with only the
+ * external model generation boundary stubbed.
+ * Run: pnpm --filter @moonshot-ai/agent-core-v2 exec vitest run
+ * test/agent/modelFailover/modelFailover.test.ts
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { IAgentLoopService } from '#/agent/loop/loop';
+import { ContinuationStepRequest } from '#/agent/loop/stepRequest';
+import { IAgentProfileService } from '#/agent/profile/profile';
+import { IAgentScopeContext } from '#/agent/scopeContext/scopeContext';
+import { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
+import { IEventBus } from '#/app/event/eventBus';
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIEmptyResponseError,
+  APIProviderQuotaExhaustedError,
+  APIProviderRateLimitError,
+  APIStatusError,
+  ChatProviderError,
+  createAbortError,
+} from '#/kosong/contract/errors';
+import { emptyUsage } from '#/kosong/contract/usage';
+import type { ExecutableTool } from '#/tool/toolContract';
+
+import {
+  InMemoryWireRecordPersistence,
+  agentService,
+  createTestAgent,
+  llmGenerateServices,
+  logServices,
+  permissionModeServices,
+  type TestAgentContext,
+  type TestAgentOptions,
+  type WireRecordPersistence,
+} from '../../harness';
+
+type GenerateFn = Parameters<typeof llmGenerateServices>[0];
+
+interface FallbackBinding {
+  readonly model: string;
+  readonly effort?: string;
+}
+
+interface TestLogger {
+  info(message: string, payload?: unknown): void;
+  warn(message: string, payload?: unknown): void;
+  error(message: string, payload?: unknown): void;
+  debug(message: string, payload?: unknown): void;
+  child(): TestLogger;
+}
+
+interface RigOptions {
+  readonly agentId?: string;
+  readonly enabled?: boolean;
+  readonly includeRoute?: boolean;
+  readonly fallbacks?: readonly FallbackBinding[];
+  readonly triggers?: readonly ('retry_exhausted' | 'quota_exhausted')[];
+  readonly maxSwitchesPerTurn?: number;
+  readonly maxRetriesPerStep?: number;
+  readonly fallbackOneEfforts?: readonly string[];
+  readonly persistence?: WireRecordPersistence;
+  readonly autoConfigure?: boolean;
+  readonly logger?: TestLogger;
+  readonly yolo?: boolean;
+}
+
+const contexts = new Set<TestAgentContext>();
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  for (const context of [...contexts]) {
+    try {
+      await context.expectResumeMatches();
+    } finally {
+      await context.dispose();
+      contexts.delete(context);
+    }
+  }
+});
+
+describe('subagent model failover (failure eligibility and bounded recovery)', () => {
+  it('keeps the initial model when generation succeeds, no fallback is observed', async () => {
+    const calls: string[] = [];
+    const context = createRig(async (chat) => {
+      calls.push(chat.modelName);
+      return successfulResponse('initial success');
+    });
+
+    const result = await runTurn(context, 1);
+
+    expect(result).toEqual({ type: 'completed', steps: 1, truncated: false });
+    expect(calls).toEqual(['mock-model']);
+    expect(context.get(IAgentProfileService).data()).toMatchObject({
+      modelAlias: 'mock-model',
+      thinkingLevel: 'off',
+    });
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it.each([
+    {
+      condition: 'the experimental flag is disabled',
+      options: { enabled: false },
+    },
+    {
+      condition: 'the fallback route is absent',
+      options: { includeRoute: false },
+    },
+  ])('keeps the original failure when $condition, no model switch occurs', async ({ options }) => {
+    const calls: string[] = [];
+    const context = createRig(async (chat) => {
+      calls.push(chat.modelName);
+      throw new APIConnectionError('primary unavailable');
+    }, options);
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('failed');
+    expect(calls).toEqual(expect.arrayContaining(['mock-model']));
+    expect(calls).not.toContain('fallback-one-upstream');
+    expect(context.get(IAgentProfileService).getModel()).toBe('mock-model');
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it('does not apply a subagent fallback route to the main agent', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        throw new APIConnectionError('primary unavailable');
+      },
+      { agentId: 'main' },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('failed');
+    expect(calls).toEqual(['mock-model']);
+    expect(context.get(IAgentProfileService).getModel()).toBe('mock-model');
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it('uses the original model retry budget when a retry succeeds, no fallback is observed', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        if (calls.length === 1) {
+          throw new APIProviderRateLimitError('try again', null, 0);
+        }
+        return successfulResponse('same-model recovery');
+      },
+      { maxRetriesPerStep: 2 },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result).toEqual({ type: 'completed', steps: 2, truncated: false });
+    expect(calls).toEqual(['mock-model', 'mock-model']);
+    expect(rpcEvents(context, 'turn.step.retrying')).toHaveLength(1);
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it('switches after the original retry budget is exhausted, the same turn completes', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        if (chat.modelName === 'mock-model') {
+          throw new APIProviderRateLimitError('still throttled', null, 0);
+        }
+        return successfulResponse('fallback recovery');
+      },
+      { maxRetriesPerStep: 2 },
+    );
+
+    const result = await runTurn(context, 1);
+    await context.wire.flush();
+
+    expect(result).toEqual({ type: 'completed', steps: 3, truncated: false });
+    expect(calls).toEqual(['mock-model', 'mock-model', 'fallback-one-upstream']);
+    expect(context.get(IAgentProfileService).data()).toMatchObject({
+      modelAlias: 'fallback-one',
+      thinkingLevel: 'high',
+    });
+    const persistedBindings = ['config.update', 'profile.bind']
+      .flatMap((event) => wireEvents(context, event))
+      .filter((entry) => (entry.args as { modelAlias?: string }).modelAlias === 'fallback-one');
+    expect(persistedBindings).toEqual([
+      expect.objectContaining({
+        args: expect.objectContaining({
+          modelAlias: 'fallback-one',
+          thinkingEffort: 'high',
+        }),
+      }),
+    ]);
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([
+      expect.objectContaining({
+        args: expect.objectContaining({
+          turnId: 1,
+          fromModel: 'mock-model',
+          toModel: 'fallback-one',
+          fromProvider: 'test-provider',
+          toProvider: 'fallback-provider',
+          fromEffort: 'off',
+          toEffort: 'high',
+          reason: 'retry_exhausted',
+          switchIndex: 1,
+          maxSwitches: 1,
+        }),
+      }),
+    ]);
+    expect(wireEvents(context, 'model.failover')).toHaveLength(1);
+    expect(context.contextData().history).toEqual([
+      expect.objectContaining({
+        role: 'assistant',
+        content: [{ type: 'text', text: 'fallback recovery' }],
+      }),
+    ]);
+  });
+
+  it('switches immediately when provider quota is exhausted, no same-model retry is observed', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        if (chat.modelName === 'mock-model') {
+          throw new APIProviderQuotaExhaustedError('quota exhausted');
+        }
+        return successfulResponse('quota fallback');
+      },
+      { maxRetriesPerStep: 10 },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result).toEqual({ type: 'completed', steps: 2, truncated: false });
+    expect(calls).toEqual(['mock-model', 'fallback-one-upstream']);
+    expect(rpcEvents(context, 'turn.step.retrying')).toEqual([]);
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([
+      expect.objectContaining({
+        args: expect.objectContaining({
+          reason: 'quota_exhausted',
+          switchIndex: 1,
+        }),
+      }),
+    ]);
+  });
+
+  it('advances through the ordered route when the first fallback fails, the second fallback completes', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        if (chat.modelName !== 'fallback-two-upstream') {
+          throw new APIConnectionError(`${chat.modelName} unavailable`);
+        }
+        return successfulResponse('second fallback recovery');
+      },
+      {
+        fallbacks: [
+          { model: 'fallback-one', effort: 'high' },
+          { model: 'fallback-two', effort: 'low' },
+        ],
+        maxSwitchesPerTurn: 2,
+      },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result).toEqual({ type: 'completed', steps: 3, truncated: false });
+    expect(calls).toEqual(['mock-model', 'fallback-one-upstream', 'fallback-two-upstream']);
+    expect(
+      rpcEvents(context, 'turn.step.failover').map(
+        (entry) => (entry.args as { toModel: string }).toModel,
+      ),
+    ).toEqual(['fallback-one', 'fallback-two']);
+    expect(context.get(IAgentProfileService).data()).toMatchObject({
+      modelAlias: 'fallback-two',
+      thinkingLevel: 'low',
+    });
+  });
+
+  it('stops at the per-turn switch limit when the fallback fails, the turn remains failed', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        throw new APIConnectionError(`${chat.modelName} unavailable`);
+      },
+      {
+        fallbacks: [
+          { model: 'fallback-one', effort: 'high' },
+          { model: 'fallback-two', effort: 'low' },
+        ],
+        maxSwitchesPerTurn: 1,
+      },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('failed');
+    expect(calls).toEqual(['mock-model', 'fallback-one-upstream']);
+    expect(rpcEvents(context, 'turn.step.failover')).toHaveLength(1);
+    expect(context.get(IAgentProfileService).getModel()).toBe('fallback-one');
+  });
+
+  it('honors the configured trigger allowlist when retry exhaustion is excluded, no switch occurs', async () => {
+    const calls: string[] = [];
+    const context = createRig(
+      async (chat) => {
+        calls.push(chat.modelName);
+        throw new APIConnectionError('primary unavailable');
+      },
+      { triggers: ['quota_exhausted'] },
+    );
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('failed');
+    expect(calls).toEqual(['mock-model']);
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it.each([
+    {
+      condition: 'the context window overflows',
+      error: new APIContextOverflowError(400, 'context length exceeded'),
+    },
+    {
+      condition: 'provider authentication fails',
+      error: new APIStatusError(401, 'unauthorized'),
+    },
+    {
+      condition: 'the provider rejects content',
+      error: new APIEmptyResponseError('content filtered', { finishReason: 'filtered' }),
+    },
+    {
+      condition: 'the provider rejects the request as unsafe',
+      error: new APIStatusError(400, 'safety policy rejected the request'),
+    },
+    {
+      condition: 'a non-provider operation fails',
+      error: new Error('tool execution failed'),
+    },
+    {
+      condition: 'a provider error has no safe structured classification',
+      error: new ChatProviderError('unclassified provider failure'),
+    },
+  ])('leaves the active binding unchanged when $condition, no switch occurs', async ({ error }) => {
+    const calls: string[] = [];
+    const context = createRig(async (chat) => {
+      calls.push(chat.modelName);
+      throw error;
+    });
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('failed');
+    expect(calls).toEqual(expect.arrayContaining(['mock-model']));
+    expect(calls).not.toContain('fallback-one-upstream');
+    expect(context.get(IAgentProfileService).getModel()).toBe('mock-model');
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it('leaves the active binding unchanged when generation is cancelled, no switch occurs', async () => {
+    const calls: string[] = [];
+    const context = createRig(async (chat) => {
+      calls.push(chat.modelName);
+      throw createAbortError();
+    });
+
+    const result = await runTurn(context, 1);
+
+    expect(result.type).toBe('cancelled');
+    expect(calls).toEqual(['mock-model']);
+    expect(context.get(IAgentProfileService).getModel()).toBe('mock-model');
+    expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+  });
+
+  it.each([
+    {
+      condition: 'the model alias is unknown',
+      fallbacks: [{ model: 'missing-model', effort: 'high' }],
+      fallbackOneEfforts: ['high'],
+      warningCode: 'model-failover-invalid-model',
+    },
+    {
+      condition: 'the effort is not declared by the model',
+      fallbacks: [{ model: 'fallback-one', effort: 'high' }],
+      fallbackOneEfforts: ['low'],
+      warningCode: 'model-failover-invalid-effort',
+    },
+  ])(
+    'fails closed when $condition, a runtime warning is recorded',
+    async ({ fallbacks, fallbackOneEfforts, warningCode }) => {
+      const warnings: Array<{ message: string; payload?: unknown }> = [];
+      const logger = captureLogger(warnings);
+      const context = createRig(
+        async () => {
+          throw new APIConnectionError('primary unavailable');
+        },
+        {
+          fallbacks,
+          fallbackOneEfforts,
+          logger,
+        },
+      );
+
+      const result = await runTurn(context, 1);
+
+      expect(result.type).toBe('failed');
+      expect(context.get(IAgentProfileService).getModel()).toBe('mock-model');
+      expect(rpcEvents(context, 'turn.step.failover')).toEqual([]);
+      expect(warnings).toContainEqual(
+        expect.objectContaining({
+          payload: { code: warningCode },
+        }),
+      );
+    },
+  );
+
+  it.each([
+    {
+      condition: 'the model alias is unknown',
+      fallbacks: [{ model: 'missing-model', effort: 'high' }],
+      fallbackOneEfforts: ['high'],
+      warningCode: 'model-failover-invalid-model',
+    },
+    {
+      condition: 'the effort is not declared by the model',
+      fallbacks: [{ model: 'fallback-one', effort: 'high' }],
+      fallbackOneEfforts: ['low'],
+      warningCode: 'model-failover-invalid-effort',
+    },
+  ])(
+    'emits a startup warning when $condition',
+    ({ fallbacks, fallbackOneEfforts, warningCode }) => {
+      const warnings: Array<{ message: string; payload?: unknown }> = [];
+      createRig(async () => successfulResponse('unused'), {
+        agentId: 'main',
+        fallbacks,
+        fallbackOneEfforts,
+        logger: captureLogger(warnings),
+      });
+
+      expect(warnings).toContainEqual(
+        expect.objectContaining({
+          payload: { code: warningCode },
+        }),
+      );
+    },
+  );
+
+  it('restores the switched binding after restart, the next turn starts on the fallback', async () => {
+    const persistence = new InMemoryWireRecordPersistence();
+    const firstCalls: string[] = [];
+    const first = createRig(
+      async (chat) => {
+        firstCalls.push(chat.modelName);
+        if (chat.modelName === 'mock-model') {
+          throw new APIConnectionError('primary unavailable');
+        }
+        return successfulResponse('first turn recovered');
+      },
+      { persistence },
+    );
+
+    expect(await runTurn(first, 1)).toMatchObject({ type: 'completed' });
+    expect(firstCalls).toEqual(['mock-model', 'fallback-one-upstream']);
+    await first.wire.flush();
+    await first.dispose();
+    contexts.delete(first);
+
+    const resumedCalls: string[] = [];
+    const resumed = createRig(
+      async (chat) => {
+        resumedCalls.push(chat.modelName);
+        return successfulResponse('resumed on fallback');
+      },
+      { persistence, autoConfigure: false },
+    );
+    await resumed.restorePersisted();
+
+    expect(resumed.get(IAgentProfileService).getModel()).toBe('fallback-one');
+    expect(await runTurn(resumed, 2)).toMatchObject({ type: 'completed' });
+    expect(resumedCalls).toEqual(['fallback-one-upstream']);
+  });
+
+  it('keeps a failing subagent switch isolated from a peer, the peer retains its original model', async () => {
+    const failing = createRig(
+      async (chat) => {
+        if (chat.modelName === 'mock-model') {
+          throw new APIConnectionError('primary unavailable');
+        }
+        return successfulResponse('failing agent recovered');
+      },
+      { agentId: 'subagent-a' },
+    );
+    const peerCalls: string[] = [];
+    const peer = createRig(
+      async (chat) => {
+        peerCalls.push(chat.modelName);
+        return successfulResponse('peer success');
+      },
+      { agentId: 'subagent-b' },
+    );
+
+    expect(await runTurn(failing, 1)).toMatchObject({ type: 'completed' });
+    expect(await runTurn(peer, 1)).toMatchObject({ type: 'completed' });
+
+    expect(failing.get(IAgentProfileService).getModel()).toBe('fallback-one');
+    expect(peer.get(IAgentProfileService).getModel()).toBe('mock-model');
+    expect(peerCalls).toEqual(['mock-model']);
+    expect(rpcEvents(peer, 'turn.step.failover')).toEqual([]);
+  });
+
+  it('drops abandoned streamed text when fallback succeeds, only the final result is committed', async () => {
+    const context = createRig(async (chat, _system, _tools, _messages, callbacks) => {
+      if (chat.modelName === 'mock-model') {
+        await callbacks?.onMessagePart?.({ type: 'text', text: 'abandoned partial' });
+        throw new APIConnectionError('stream disconnected');
+      }
+      await callbacks?.onMessagePart?.({ type: 'text', text: 'final answer' });
+      return successfulResponse('final answer');
+    });
+
+    const result = await runTurn(context, 1);
+
+    expect(result).toMatchObject({ type: 'completed' });
+    expect(context.contextData().history).toEqual([
+      expect.objectContaining({
+        role: 'assistant',
+        content: [{ type: 'text', text: 'final answer' }],
+      }),
+    ]);
+    expect(JSON.stringify(context.contextData().history)).not.toContain('abandoned partial');
+  });
+
+  it('replays the failed driver without duplicating fallback tool results or assistant content', async () => {
+    let fallbackRequests = 0;
+    let toolExecutions = 0;
+    const context = createRig(
+      async (chat) => {
+        if (chat.modelName === 'mock-model') {
+          throw new APIConnectionError('primary unavailable');
+        }
+        fallbackRequests += 1;
+        if (fallbackRequests === 1) {
+          return {
+            id: 'response-tool-call',
+            message: {
+              role: 'assistant' as const,
+              content: [{ type: 'text' as const, text: 'checking once' }],
+              toolCalls: [
+                {
+                  type: 'function' as const,
+                  id: 'call_lookup',
+                  name: 'Lookup',
+                  arguments: '{}',
+                },
+              ],
+            },
+            usage: emptyUsage(),
+            finishReason: 'tool_calls' as const,
+            rawFinishReason: 'tool_calls',
+          };
+        }
+        return successfulResponse('tool result consumed once');
+      },
+      { yolo: true },
+    );
+    const tool: ExecutableTool = {
+      name: 'Lookup',
+      description: 'Return a deterministic lookup result.',
+      parameters: { type: 'object', properties: {}, additionalProperties: false },
+      resolveExecution: () => ({
+        approvalRule: 'Lookup',
+        execute: async () => {
+          toolExecutions += 1;
+          return { output: 'lookup-result' };
+        },
+      }),
+    };
+    context.get(IAgentProfileService).update({
+      profileName: 'agent',
+      activeToolNames: ['Lookup'],
+    });
+    context.get(IAgentToolRegistryService).register(tool);
+
+    expect(await runTurn(context, 1)).toMatchObject({ type: 'completed' });
+
+    const history = context.contextData().history;
+    expect(toolExecutions).toBe(1);
+    expect(
+      history.filter(
+        (message) => message.role === 'tool' && message.toolCallId === 'call_lookup',
+      ),
+    ).toHaveLength(1);
+    expect(
+      history.filter(
+        (message) =>
+          message.role === 'assistant' &&
+          message.toolCalls.some((call) => call.id === 'call_lookup'),
+      ),
+    ).toHaveLength(1);
+    expect(JSON.stringify(history).match(/tool result consumed once/g)).toHaveLength(1);
+  });
+});
+
+function createRig(generate: GenerateFn, options: RigOptions = {}): TestAgentContext {
+  const agentId = options.agentId ?? 'subagent-1';
+  const initialConfig: TestAgentOptions['initialConfig'] = {
+    experimental: { 'model-failover': options.enabled ?? true },
+    loopControl: { maxRetriesPerStep: options.maxRetriesPerStep ?? 1 },
+    providers: {
+      'fallback-provider': {
+        type: 'openai',
+        apiKey: 'YOUR_API_KEY',
+        baseUrl: 'https://api.example.test/v1',
+      },
+    },
+    models: {
+      'fallback-one': {
+        provider: 'fallback-provider',
+        model: 'fallback-one-upstream',
+        maxContextSize: 1_000_000,
+        capabilities: ['thinking', 'tool_use'],
+        supportEfforts: options.fallbackOneEfforts ?? ['high'],
+        defaultEffort: 'high',
+      },
+      'fallback-two': {
+        provider: 'fallback-provider',
+        model: 'fallback-two-upstream',
+        maxContextSize: 1_000_000,
+        capabilities: ['thinking', 'tool_use'],
+        supportEfforts: ['low'],
+        defaultEffort: 'low',
+      },
+    },
+    subagentFailover:
+      options.includeRoute === false
+        ? undefined
+        : {
+            fallbacks: options.fallbacks ?? [{ model: 'fallback-one', effort: 'high' }],
+            on: options.triggers,
+            maxSwitchesPerTurn: options.maxSwitchesPerTurn,
+          },
+  };
+
+  const overrides = [
+    llmGenerateServices(generate),
+    agentService(IAgentScopeContext, {
+      _serviceBrand: undefined,
+      agentId,
+      scope: (subKey?: string) =>
+        subKey === undefined || subKey === ''
+          ? `test/agents/${agentId}`
+          : `test/agents/${agentId}/${subKey}`,
+    }),
+  ];
+  if (options.logger !== undefined) overrides.push(logServices(options.logger));
+  if (options.yolo === true) overrides.push(permissionModeServices('yolo'));
+  const context = createTestAgent(...overrides, {
+    initialConfig,
+    persistence: options.persistence,
+    autoConfigure: options.autoConfigure,
+  });
+  contexts.add(context);
+  return context;
+}
+
+async function runTurn(context: TestAgentContext, turnId: number) {
+  context.get(IEventBus).publish({
+    type: 'turn.started',
+    turnId,
+    origin: { kind: 'user' },
+  });
+  const loop = context.get(IAgentLoopService);
+  loop.enqueue(new ContinuationStepRequest());
+  return loop.run({ turnId });
+}
+
+function successfulResponse(text: string) {
+  return {
+    id: `response-${text}`,
+    message: {
+      role: 'assistant' as const,
+      content: [{ type: 'text' as const, text }],
+      toolCalls: [],
+    },
+    usage: emptyUsage(),
+    finishReason: 'completed' as const,
+    rawFinishReason: 'stop',
+  };
+}
+
+function rpcEvents(context: TestAgentContext, name: string) {
+  return context.allEvents.filter((entry) => entry.type === '[rpc]' && entry.event === name);
+}
+
+function wireEvents(context: TestAgentContext, name: string) {
+  return context.allEvents.filter((entry) => entry.type === '[wire]' && entry.event === name);
+}
+
+function captureLogger(warnings: Array<{ message: string; payload?: unknown }>) {
+  const logger = {
+    info: () => {},
+    warn: (message: string, payload?: unknown) => {
+      warnings.push({ message, payload });
+    },
+    error: () => {},
+    debug: () => {},
+    child: () => logger,
+  };
+  return logger;
+}
diff --git a/packages/agent-core-v2/test/app/config/config.test.ts b/packages/agent-core-v2/test/app/config/config.test.ts
index fe51e6af4b..03b8e72492 100644
--- a/packages/agent-core-v2/test/app/config/config.test.ts
+++ b/packages/agent-core-v2/test/app/config/config.test.ts
@@ -45,6 +45,11 @@ import {
   LOOP_MAX_STEPS_PER_TURN_ENV,
   type LoopControl,
 } from '#/agent/loop/configSection';
+import {
+  MODEL_FAILOVER_SECTION,
+  resolveModelFailoverBinding,
+  type ModelFailoverConfig,
+} from '#/agent/modelFailover/configSection';
 import {
   MODELS_SECTION,
   SECONDARY_MODEL_EFFORT_ENV,
@@ -1538,6 +1543,115 @@ describe('subagent config section', () => {
   });
 });
 
+describe('subagentFailover config section', () => {
+  async function createConfig(toml?: string) {
+    const disposables = new DisposableStore();
+    const ix = disposables.add(new TestInstantiationService());
+    const storage = new InMemoryStorageService();
+    if (toml !== undefined) {
+      await storage.write('', 'config.toml', new TextEncoder().encode(toml));
+    }
+    ix.stub(ILogService, stubLog());
+    ix.stub(IBootstrapService, stubBootstrap('/tmp/kimi-cfg', {}));
+    ix.stub(IFileSystemStorageService, storage);
+    ix.set(IAtomicTomlDocumentStore, new SyncDescriptor(TomlAtomicDocumentStore));
+    ix.set(IConfigRegistry, new SyncDescriptor(ConfigRegistry));
+    ix.set(IConfigService, new SyncDescriptor(ConfigService));
+    const config = ix.get(IConfigService);
+    await config.ready;
+    return { config, disposables };
+  }
+
+  it('validates an ordered fallback route and rejects invalid trigger controls', () => {
+    const registry = new ConfigRegistry();
+
+    expect(
+      registry.validate(MODEL_FAILOVER_SECTION, {
+        fallbacks: [
+          { model: 'secondary', effort: 'high' },
+          { model: 'primary', effort: 'high' },
+        ],
+        on: ['retry_exhausted', 'quota_exhausted'],
+        maxSwitchesPerTurn: 2,
+      }),
+    ).toEqual({
+      fallbacks: [
+        { model: 'secondary', effort: 'high' },
+        { model: 'primary', effort: 'high' },
+      ],
+      on: ['retry_exhausted', 'quota_exhausted'],
+      maxSwitchesPerTurn: 2,
+    });
+    expect(() =>
+      registry.validate(MODEL_FAILOVER_SECTION, {
+        fallbacks: [{ model: '' }],
+      }),
+    ).toThrow();
+    expect(() =>
+      registry.validate(MODEL_FAILOVER_SECTION, {
+        fallbacks: [],
+        on: ['authentication'],
+      }),
+    ).toThrow();
+    expect(() =>
+      registry.validate(MODEL_FAILOVER_SECTION, {
+        fallbacks: [],
+        maxSwitchesPerTurn: -1,
+      }),
+    ).toThrow();
+  });
+
+  it('reads snake-case TOML and resolves primary and secondary symbolic bindings', async () => {
+    const { config, disposables } = await createConfig(`
+default_model = "provider/primary"
+
+[secondary_model]
+model = "provider/secondary"
+default_effort = "medium"
+
+[subagent_failover]
+on = ["retry_exhausted", "quota_exhausted"]
+max_switches_per_turn = 2
+
+[[subagent_failover.fallbacks]]
+model = "secondary"
+effort = "high"
+
+[[subagent_failover.fallbacks]]
+model = "primary"
+`);
+
+    const section = config.get<ModelFailoverConfig>(MODEL_FAILOVER_SECTION);
+    expect(section).toEqual({
+      fallbacks: [{ model: 'secondary', effort: 'high' }, { model: 'primary' }],
+      on: ['retry_exhausted', 'quota_exhausted'],
+      maxSwitchesPerTurn: 2,
+    });
+    expect(resolveModelFailoverBinding(section.fallbacks[0]!, config)).toEqual({
+      model: SECONDARY_DERIVED_MODEL_ID,
+      effort: 'high',
+    });
+    expect(resolveModelFailoverBinding(section.fallbacks[1]!, config)).toEqual({
+      model: 'provider/primary',
+      effort: undefined,
+    });
+
+    disposables.dispose();
+  });
+
+  it('uses a fail-closed empty route when the section is absent', async () => {
+    const { config, disposables } = await createConfig();
+
+    expect(config.get<ModelFailoverConfig>(MODEL_FAILOVER_SECTION)).toEqual({
+      fallbacks: [],
+      on: ['retry_exhausted', 'quota_exhausted'],
+      maxSwitchesPerTurn: 1,
+    });
+
+    disposables.dispose();
+  });
+});
+
 describe('secondaryModel config section', () => {
   async function createConfig(env: Record<string, string>, toml?: string) {
     const disposables = new DisposableStore();
diff --git a/packages/agent-core-v2/test/index.test.ts b/packages/agent-core-v2/test/index.test.ts
index db7cd48bad..ee4cf685cb 100644
--- a/packages/agent-core-v2/test/index.test.ts
+++ b/packages/agent-core-v2/test/index.test.ts
@@ -79,14 +79,15 @@ const V2_ONLY_RECORD_TYPES: ReadonlySet<string> = new Set([
 // Persisted record types introduced after the v1 vocabulary: the task
 // lifecycle journal (the restore seed for ghosts and the cold transcript
 // fold), the interaction request/resolution journal, and the plan revision
-// reference journal. Replay tolerates unknown record types (skip + warn), so
-// older readers degrade gracefully.
+// reference journal, and runtime model failover audit records. Replay tolerates
+// unknown record types (skip + warn), so older readers degrade gracefully.
 const V2_RECORD_TYPES: ReadonlySet<string> = new Set([
   'task.started',
   'task.terminated',
   'interaction.request',
   'interaction.resolved',
   'plan.revision',
+  'model.failover',
 ]);
 
 describe('v1 wire vocabulary', () => {
diff --git a/packages/kap-server/src/protocol/events-zod.ts b/packages/kap-server/src/protocol/events-zod.ts
index 79de1337ca..d950b6f7b9 100644
--- a/packages/kap-server/src/protocol/events-zod.ts
+++ b/packages/kap-server/src/protocol/events-zod.ts
@@ -60,6 +60,7 @@ import type {
   ToolListUpdatedReason,
 } from '@moonshot-ai/agent-core-v2/agent/mcp/mcpService';
 import type { McpOAuthAuthorizationUrlUpdateData } from '@moonshot-ai/agent-core-v2/agent/mcp/tools/auth';
+import type { TurnStepFailoverEvent } from '@moonshot-ai/agent-core-v2/agent/modelFailover/modelFailoverOps';
 import type { PermissionMode } from '@moonshot-ai/agent-core-v2/agent/permissionPolicy/types';
 import type { WarningEvent } from '@moonshot-ai/agent-core-v2/agent/profile/profileService';
 import type { PluginCommandActivatedEvent } from '@moonshot-ai/agent-core-v2/agent/rpc/rpcService';
@@ -686,6 +687,22 @@ export const turnStepRetryingEventSchema = z.object({
   statusCode: z.number().optional(),
 }) satisfies z.ZodType<TurnStepRetryingEvent>;
 
+export const turnStepFailoverEventSchema = z.object({
+  type: z.literal('turn.step.failover'),
+  turnId: z.number(),
+  step: z.number(),
+  stepId: z.string().optional(),
+  fromModel: z.string(),
+  toModel: z.string(),
+  fromProvider: z.string(),
+  toProvider: z.string(),
+  fromEffort: z.string(),
+  toEffort: z.string(),
+  reason: z.enum(['retry_exhausted', 'quota_exhausted']),
+  switchIndex: z.number(),
+  maxSwitches: z.number(),
+}) satisfies z.ZodType<TurnStepFailoverEvent>;
+
 export const turnStepInterruptedEventSchema = z.object({
   type: z.literal('turn.step.interrupted'),
   turnId: z.number(),
@@ -929,6 +946,7 @@ export const agentEventSchema = z.discriminatedUnion('type', [
   turnStepStartedEventSchema,
   turnStepCompletedEventSchema,
   turnStepRetryingEventSchema,
+  turnStepFailoverEventSchema,
   turnStepInterruptedEventSchema,
   assistantDeltaEventSchema,
   hookResultEventSchema,
diff --git a/packages/kap-server/src/services/transcript/coreEventMap.ts b/packages/kap-server/src/services/transcript/coreEventMap.ts
index 157904ad4d..0314069726 100644
--- a/packages/kap-server/src/services/transcript/coreEventMap.ts
+++ b/packages/kap-server/src/services/transcript/coreEventMap.ts
@@ -18,9 +18,10 @@
  *   - Step headers carry the LLM accounting: `turn.step.completed` fills
  *     `usage` (the wire `TokenUsage` verbatim), `finishReason`
  *     (`finishReason ?? rawFinishReason ?? providerFinishReason`) and the
- *     full `timing` breakdown; `turn.step.retrying` sets `retry` on the still
- *     'running' step (the terminal upsert carries no `retry`, which clears
- *     it); `turn.step.interrupted` fills `endReason` / `endMessage`.
+ *     full `timing` breakdown; `turn.step.retrying` sets `retry` and
+ *     `turn.step.failover` sets `failover` on the still-running failed step.
+ *     Both discard abandoned streamed frames before the same driver is
+ *     replayed; `turn.step.interrupted` fills `endReason` / `endMessage`.
  *   - `turn.ended` fills the turn header's `durationMs` / `error` plus the
  *     accumulated `usage`: the projector sums this turn's step usages
  *     (`inputTokens = inputOther + inputCacheCreation`,
@@ -219,6 +220,8 @@ export class AgentTranscriptProjector {
         return this.onStepFinished(event);
       case 'turn.step.retrying':
         return this.onStepRetrying(event);
+      case 'turn.step.failover':
+        return this.onStepFailover(event);
       case 'assistant.delta':
         return this.onTextDelta(event.turnId, 'assistant', event.delta);
       case 'thinking.delta':
@@ -500,6 +503,7 @@ export class AgentTranscriptProjector {
     const ops: TranscriptOperation[] = [];
     const turnId = `t${event.turnId}`;
     const stepId = `${turnId}.${event.step}`;
+    this.discardStepFrames(turnId, stepId, ops);
     const prev = this.currentStep?.stepId === stepId ? this.currentStep : undefined;
     this.currentStep = {
       kind: 'step',
@@ -522,6 +526,47 @@ export class AgentTranscriptProjector {
     return ops;
   }
 
+  private onStepFailover(event: {
+    turnId: number;
+    step: number;
+    fromModel: string;
+    toModel: string;
+    fromProvider: string;
+    toProvider: string;
+    fromEffort: string;
+    toEffort: string;
+    reason: 'retry_exhausted' | 'quota_exhausted';
+    switchIndex: number;
+    maxSwitches: number;
+  }): TranscriptOperation[] {
+    const ops: TranscriptOperation[] = [];
+    const turnId = `t${event.turnId}`;
+    const stepId = `${turnId}.${event.step}`;
+    this.discardStepFrames(turnId, stepId, ops);
+    const prev = this.currentStep?.stepId === stepId ? this.currentStep : undefined;
+    this.currentStep = {
+      kind: 'step',
+      stepId,
+      turnId,
+      ordinal: event.step,
+      state: 'running',
+      startedAt: prev?.startedAt,
+      failover: {
+        fromModel: event.fromModel,
+        toModel: event.toModel,
+        fromProvider: event.fromProvider,
+        toProvider: event.toProvider,
+        fromEffort: event.fromEffort,
+        toEffort: event.toEffort,
+        reason: event.reason,
+        switchIndex: event.switchIndex,
+        maxSwitches: event.maxSwitches,
+      },
+    };
+    ops.push({ op: 'step.upsert', turnId, step: this.currentStep });
+    return ops;
+  }
+
   private onTextDelta(
     turnNumber: number,
     kind: 'assistant' | 'thinking',
@@ -623,6 +668,32 @@ export class AgentTranscriptProjector {
     this.openThinking = undefined;
   }
 
+  private discardStepFrames(turnId: string, stepId: string, ops: TranscriptOperation[]): void {
+    const frameIds = new Set<string>();
+    for (const open of [this.openText, this.openThinking]) {
+      if (open !== undefined && this.currentStep?.stepId === stepId) {
+        frameIds.add(open.frameId);
+      }
+    }
+    for (const [toolCallId, record] of this.toolFrames) {
+      if (record.turnId !== turnId || record.stepId !== stepId) continue;
+      frameIds.add(record.frame.frameId);
+      this.toolFrames.delete(toolCallId);
+    }
+    for (const frame of this.lookups?.stepFrames?.(turnId, stepId) ?? []) {
+      if (frame.kind === 'text' || frame.kind === 'thinking' || frame.kind === 'tool') {
+        frameIds.add(frame.frameId);
+      }
+    }
+    for (const frameId of frameIds) {
+      ops.push({ op: 'frame.remove', turnId, stepId, frameId });
+    }
+    if (this.currentStep?.stepId === stepId) {
+      this.openText = undefined;
+      this.openThinking = undefined;
+    }
+  }
+
   /**
    * Resolve the step a content event belongs to. When the projector missed
    * `turn.step.started` (mid-stream attach), prefer the engine-reported
diff --git a/packages/kap-server/src/transport/ws/v1/inFlightTurnTracker.ts b/packages/kap-server/src/transport/ws/v1/inFlightTurnTracker.ts
index db26579be1..4fbe1fa67d 100644
--- a/packages/kap-server/src/transport/ws/v1/inFlightTurnTracker.ts
+++ b/packages/kap-server/src/transport/ws/v1/inFlightTurnTracker.ts
@@ -76,6 +76,15 @@ export class InFlightTurnTracker {
         turn.thinkingText = '';
         return {};
       }
+      case 'turn.step.retrying':
+      case 'turn.step.failover': {
+        const turn = this.bySession.get(sessionId);
+        if (!turn || turn.turnId !== event.turnId) return {};
+        turn.assistantText = '';
+        turn.thinkingText = '';
+        turn.tools.clear();
+        return {};
+      }
       case 'assistant.delta': {
         const turn = this.bySession.get(sessionId);
         if (!turn || turn.turnId !== event.turnId) return {};
diff --git a/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts b/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
index 2d968c8e00..401ce15619 100644
--- a/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
+++ b/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
@@ -1368,6 +1368,7 @@ const TRANSCRIPT_PROJECTED_EVENT_TYPES: ReadonlySet<string> = new Set([
   'turn.step.completed',
   'turn.step.interrupted',
   'turn.step.retrying',
+  'turn.step.failover',
   'assistant.delta',
   'thinking.delta',
   'tool.call.delta',
diff --git a/packages/kap-server/test/inFlightTurnTracker.test.ts b/packages/kap-server/test/inFlightTurnTracker.test.ts
index 1a64553335..98fc440c09 100644
--- a/packages/kap-server/test/inFlightTurnTracker.test.ts
+++ b/packages/kap-server/test/inFlightTurnTracker.test.ts
@@ -1,5 +1,8 @@
 /**
- * `InFlightTurnTracker` — volatile accumulation + delta offsets.
+ * Scenario: volatile main-turn state is accumulated between snapshots.
+ * Responsibilities: stream offsets, running tools, step resets, and terminal
+ * cleanup. The pure tracker is wired directly. Run with
+ * `pnpm --filter @moonshot-ai/kap-server exec vitest run test/inFlightTurnTracker.test.ts`.
  */
 
 import type { Event } from '../src/transport/ws/v1/events';
@@ -48,6 +51,34 @@ describe('InFlightTurnTracker', () => {
     expect(t.get(SID)).toBeNull();
   });
 
+  it.each(['turn.step.retrying', 'turn.step.failover'])(
+    'clears abandoned volatile content when %s arrives',
+    (type) => {
+      const tracker = new InFlightTurnTracker();
+      tracker.apply(SID, ev({ type: 'turn.started', turnId: 1 }));
+      tracker.apply(SID, ev({ type: 'assistant.delta', turnId: 1, delta: 'partial' }));
+      tracker.apply(SID, ev({ type: 'thinking.delta', turnId: 1, delta: 'draft' }));
+      tracker.apply(
+        SID,
+        ev({
+          type: 'tool.call.started',
+          turnId: 1,
+          toolCallId: 'call-1',
+          name: 'Read',
+          args: {},
+        }),
+      );
+
+      tracker.apply(SID, ev({ type, turnId: 1, step: 1 }));
+
+      expect(tracker.get(SID)).toMatchObject({
+        assistant_text: '',
+        thinking_text: '',
+        running_tools: [],
+      });
+    },
+  );
+
   it('ignores non-main agents', () => {
     const t = new InFlightTurnTracker();
     t.apply(SID, ev({ type: 'turn.started', turnId: 1 }));
diff --git a/packages/kap-server/test/services/transcript.test.ts b/packages/kap-server/test/services/transcript.test.ts
index 28c25fc766..7198b92274 100644
--- a/packages/kap-server/test/services/transcript.test.ts
+++ b/packages/kap-server/test/services/transcript.test.ts
@@ -543,6 +543,85 @@ describe('AgentTranscriptProjector', () => {
     expect(step().retry).toBeUndefined();
   });
 
+  it('records the model transition when turn.step.failover arrives, the failed step stays recoverable', () => {
+    const projector = new AgentTranscriptProjector('subagent-1');
+    const tx = new AgentTranscript('subagent-1');
+    const feed = (event: DomainEvent): void => void tx.apply(projector.map(event));
+
+    feed(ev({ type: 'turn.started', turnId: 1, origin: { kind: 'task', taskId: 'task-1' } }));
+    feed(ev({ type: 'turn.step.started', turnId: 1, step: 1 }));
+    feed(
+      ev({
+        type: 'turn.step.failover',
+        turnId: 1,
+        step: 1,
+        fromModel: 'secondary-model',
+        toModel: 'primary-model',
+        fromProvider: 'secondary-provider',
+        toProvider: 'primary-provider',
+        fromEffort: 'high',
+        toEffort: 'high',
+        reason: 'retry_exhausted',
+        switchIndex: 1,
+        maxSwitches: 1,
+      }),
+    );
+
+    expect(turnOps('t1', tx.getItems()).steps[0]).toMatchObject({
+      state: 'running',
+      failover: {
+        fromModel: 'secondary-model',
+        toModel: 'primary-model',
+        fromProvider: 'secondary-provider',
+        toProvider: 'primary-provider',
+        fromEffort: 'high',
+        toEffort: 'high',
+        reason: 'retry_exhausted',
+        switchIndex: 1,
+        maxSwitches: 1,
+      },
+    });
+  });
+
+  it('removes streamed frames when turn.step.failover arrives, the replay starts cleanly', () => {
+    const projector = new AgentTranscriptProjector('subagent-1');
+    const tx = new AgentTranscript('subagent-1');
+    const feed = (event: DomainEvent): void => void tx.apply(projector.map(event));
+
+    feed(ev({ type: 'turn.started', turnId: 1, origin: { kind: 'task', taskId: 'task-1' } }));
+    feed(ev({ type: 'turn.step.started', turnId: 1, step: 1 }));
+    feed(ev({ type: 'assistant.delta', turnId: 1, delta: 'abandoned text' }));
+    feed(
+      ev({
+        type: 'tool.call.started',
+        turnId: 1,
+        toolCallId: 'call-1',
+        name: 'Read',
+        args: { path: 'src/example.ts' },
+      }),
+    );
+    expect(turnOps('t1', tx.getItems()).steps[0]?.frames).toHaveLength(2);
+
+    feed(
+      ev({
+        type: 'turn.step.failover',
+        turnId: 1,
+        step: 1,
+        fromModel: 'secondary-model',
+        toModel: 'primary-model',
+        fromProvider: 'secondary-provider',
+        toProvider: 'primary-provider',
+        fromEffort: 'high',
+        toEffort: 'high',
+        reason: 'quota_exhausted',
+        switchIndex: 1,
+        maxSwitches: 1,
+      }),
+    );
+
+    expect(turnOps('t1', tx.getItems()).steps[0]?.frames).toEqual([]);
+  });
+
   it('fills durationMs / error / accumulated step usage on turn.ended', () => {
     const projector = new AgentTranscriptProjector('main');
     const tx = new AgentTranscript('main');
diff --git a/packages/kap-server/test/sessionEventBroadcaster.test.ts b/packages/kap-server/test/sessionEventBroadcaster.test.ts
index 71c900f2cf..f86a062c02 100644
--- a/packages/kap-server/test/sessionEventBroadcaster.test.ts
+++ b/packages/kap-server/test/sessionEventBroadcaster.test.ts
@@ -1,5 +1,9 @@
 /**
- * `SessionEventBroadcaster` — seq stamping, volatile vs durable, fan-out, replay.
+ * Scenario: session events fan out across legacy and transcript-aware WebSocket
+ * clients. Responsibilities: sequence stamping, durability, replay,
+ * suppression, and global delivery. Real broadcaster logic uses in-memory
+ * lifecycle/target boundaries. Run with
+ * `pnpm --filter @moonshot-ai/kap-server exec vitest run test/sessionEventBroadcaster.test.ts`.
  */
 
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -2287,6 +2291,21 @@ describe('SessionEventBroadcaster', () => {
       main.bus.emit(agentEvent('turn.started', { turnId: 1, origin: { kind: 'user' } }));
       main.bus.emit(agentEvent('turn.step.started', { turnId: 1, step: 1 }));
       main.bus.emit(agentEvent('assistant.delta', { turnId: 1, delta: 'Hi' }));
+      main.bus.emit(
+        agentEvent('turn.step.failover', {
+          turnId: 1,
+          step: 1,
+          fromModel: 'secondary-model',
+          toModel: 'primary-model',
+          fromProvider: 'secondary-provider',
+          toProvider: 'primary-provider',
+          fromEffort: 'high',
+          toEffort: 'high',
+          reason: 'retry_exhausted',
+          switchIndex: 1,
+          maxSwitches: 1,
+        }),
+      );
       main.bus.emit(agentEvent('tool.result', { turnId: 1, toolCallId: 'tc-1', output: 'ok' }));
       await bc.getCursor('s1');
 
@@ -2299,6 +2318,7 @@ describe('SessionEventBroadcaster', () => {
       expect(gradedTypes).not.toContain('turn.started');
       expect(gradedTypes).not.toContain('turn.step.started');
       expect(gradedTypes).not.toContain('assistant.delta');
+      expect(gradedTypes).not.toContain('turn.step.failover');
       expect(gradedTypes).not.toContain('tool.result');
       expect(gradedTypes).not.toContain('agent.status.updated');
 
@@ -2308,6 +2328,7 @@ describe('SessionEventBroadcaster', () => {
       expect(legacyTypes).toContain('turn.started');
       expect(legacyTypes).toContain('turn.step.started');
       expect(legacyTypes).toContain('assistant.delta');
+      expect(legacyTypes).toContain('turn.step.failover');
       expect(legacyTypes).toContain('tool.result');
       expect(transcriptEnvelopes(legacy.envelopes)).toHaveLength(0);
     });
diff --git a/packages/transcript/src/contract/schema.ts b/packages/transcript/src/contract/schema.ts
index ce55f347a3..6962965fde 100644
--- a/packages/transcript/src/contract/schema.ts
+++ b/packages/transcript/src/contract/schema.ts
@@ -83,6 +83,18 @@ export const stepRetrySchema = z.object({
   statusCode: z.number().optional(),
 });
 
+export const stepFailoverSchema = z.object({
+  fromModel: z.string(),
+  toModel: z.string(),
+  fromProvider: z.string(),
+  toProvider: z.string(),
+  fromEffort: z.string(),
+  toEffort: z.string(),
+  reason: z.enum(['retry_exhausted', 'quota_exhausted']),
+  switchIndex: z.number().int().positive(),
+  maxSwitches: z.number().int().positive(),
+});
+
 export const turnStateSchema = z.enum(['queued', 'running', 'completed', 'failed', 'cancelled']);
 export const stepStateSchema = z.enum(['running', 'completed', 'interrupted', 'failed']);
 
@@ -171,6 +183,7 @@ export const transcriptStepSchema = z.object({
   finishReason: z.string().optional(),
   timing: stepTimingSchema.optional(),
   retry: stepRetrySchema.optional(),
+  failover: stepFailoverSchema.optional(),
   endReason: z.string().optional(),
   endMessage: z.string().optional(),
 });
@@ -415,6 +428,12 @@ export const transcriptOperationSchema = z.discriminatedUnion('op', [
     stepId: stepIdSchema,
     frame: transcriptFrameSchema,
   }),
+  z.object({
+    op: z.literal('frame.remove'),
+    turnId: turnIdSchema,
+    stepId: stepIdSchema,
+    frameId: frameIdSchema,
+  }),
   z.object({
     op: z.literal('append'),
     target: appendTargetSchema,
diff --git a/packages/transcript/src/granularity/filterOps.ts b/packages/transcript/src/granularity/filterOps.ts
index 26d4041017..c30add7c97 100644
--- a/packages/transcript/src/granularity/filterOps.ts
+++ b/packages/transcript/src/granularity/filterOps.ts
@@ -7,7 +7,7 @@
  * a client that upgrades gets a full reset snapshot.
  *
  * Content-bearing ops gated below 'block':
- *  - step.upsert / frame.upsert (step & frame detail)
+ *  - step.upsert / frame.upsert / frame.remove (step & frame detail)
  * Everything else (turn headers, markers, taskrefs, tasks, interactions,
  * prompts, meta, removals, resets) flows at 'turn' and up. `off` admits
  * nothing.
@@ -32,6 +32,7 @@ function admits(grade: TranscriptGrade, op: TranscriptOperation): boolean {
       return GRADE_RANK[grade] >= GRADE_RANK.delta;
     case 'step.upsert':
     case 'frame.upsert':
+    case 'frame.remove':
       return GRADE_RANK[grade] >= GRADE_RANK.block;
     default:
       return true;
diff --git a/packages/transcript/src/history/foldFacts.ts b/packages/transcript/src/history/foldFacts.ts
index c038988439..5994935b0b 100644
--- a/packages/transcript/src/history/foldFacts.ts
+++ b/packages/transcript/src/history/foldFacts.ts
@@ -329,6 +329,10 @@ export function foldWireRecordFacts(
         pushMarker('plan.revision', record);
         break;
       }
+      case 'model.failover': {
+        pushMarker('model.failover', record);
+        break;
+      }
       case 'swarm_mode.enter': {
         swarmActive = true;
         pushMarker('swarm.enter', record);
diff --git a/packages/transcript/src/model/turn.ts b/packages/transcript/src/model/turn.ts
index 22224edb64..5a217f1d31 100644
--- a/packages/transcript/src/model/turn.ts
+++ b/packages/transcript/src/model/turn.ts
@@ -69,6 +69,19 @@ export interface StepRetry {
   readonly statusCode?: number;
 }
 
+/** A runtime model switch that will replay this failed step on a fallback. */
+export interface StepFailover {
+  readonly fromModel: string;
+  readonly toModel: string;
+  readonly fromProvider: string;
+  readonly toProvider: string;
+  readonly fromEffort: string;
+  readonly toEffort: string;
+  readonly reason: 'retry_exhausted' | 'quota_exhausted';
+  readonly switchIndex: number;
+  readonly maxSwitches: number;
+}
+
 export interface TranscriptTurn {
   readonly kind: 'turn';
   readonly turnId: TurnId;
@@ -108,6 +121,7 @@ export interface TranscriptStep {
   readonly finishReason?: string;
   readonly timing?: StepTiming;
   readonly retry?: StepRetry;
+  readonly failover?: StepFailover;
   /** `turn.step.interrupted` reason / message. */
   readonly endReason?: string;
   readonly endMessage?: string;
diff --git a/packages/transcript/src/ops/apply.ts b/packages/transcript/src/ops/apply.ts
index 5b15e8576b..d4e5f34996 100644
--- a/packages/transcript/src/ops/apply.ts
+++ b/packages/transcript/src/ops/apply.ts
@@ -74,6 +74,8 @@ export function applyOperation(state: AgentState, op: TranscriptOperation): Appl
       return applyStepUpsert(state, op.turnId, op.step);
     case 'frame.upsert':
       return applyFrameUpsert(state, op);
+    case 'frame.remove':
+      return applyFrameRemove(state, op);
     case 'append':
       return applyAppend(state, op);
     case 'marker.upsert':
@@ -252,6 +254,7 @@ function stepEquals(step: TranscriptStep, header: StepHeader): boolean {
     step.finishReason === header.finishReason &&
     step.timing === header.timing &&
     step.retry === header.retry &&
+    step.failover === header.failover &&
     step.endReason === header.endReason &&
     step.endMessage === header.endMessage
   );
@@ -288,6 +291,33 @@ function applyFrameUpsert(
   };
 }
 
+function applyFrameRemove(
+  state: AgentState,
+  op: Extract<TranscriptOperation, { op: 'frame.remove' }>,
+): ApplyResult {
+  const turn = getTurn(state, op.turnId);
+  const step = turn?.steps.find((entry) => entry.stepId === op.stepId);
+  if (turn === undefined || step === undefined) return { state, changed: false };
+  if (!step.frames.some((frame) => frame.frameId === op.frameId)) {
+    return { state, changed: false };
+  }
+  const nextStep: TranscriptStep = {
+    ...step,
+    frames: step.frames.filter((frame) => frame.frameId !== op.frameId),
+  };
+  const nextTurn: TranscriptTurn = {
+    ...turn,
+    steps: turn.steps.map((entry) => (entry.stepId === op.stepId ? nextStep : entry)),
+  };
+  return {
+    state: {
+      ...state,
+      items: replaceTurn(state.items, op.turnId, () => nextTurn),
+    },
+    changed: true,
+  };
+}
+
 function frameEquals(a: TranscriptFrame, b: TranscriptFrame): boolean {
   if (a.kind !== b.kind) return false;
   if (a.kind === 'text' && b.kind === 'text') {
diff --git a/packages/transcript/src/ops/operation.ts b/packages/transcript/src/ops/operation.ts
index f4f3817787..0e3468c8d1 100644
--- a/packages/transcript/src/ops/operation.ts
+++ b/packages/transcript/src/ops/operation.ts
@@ -57,6 +57,14 @@ export interface FrameUpsertOp {
   readonly frame: TranscriptFrame;
 }
 
+/** Remove an abandoned frame from one step; idempotent when already absent. */
+export interface FrameRemoveOp {
+  readonly op: 'frame.remove';
+  readonly turnId: TurnId;
+  readonly stepId: StepId;
+  readonly frameId: FrameId;
+}
+
 export type AppendTarget =
   | { readonly type: 'frame'; readonly turnId: TurnId; readonly stepId: StepId; readonly frameId: FrameId }
   | { readonly type: 'task'; readonly taskId: TaskId };
@@ -146,6 +154,7 @@ export type TranscriptOperation =
   | TurnUpsertOp
   | StepUpsertOp
   | FrameUpsertOp
+  | FrameRemoveOp
   | AppendOp
   | MarkerUpsertOp
   | TaskRefUpsertOp
diff --git a/packages/transcript/test/layers.test.ts b/packages/transcript/test/layers.test.ts
index 3ce1b213cd..b1b2b7ad4b 100644
--- a/packages/transcript/test/layers.test.ts
+++ b/packages/transcript/test/layers.test.ts
@@ -1,3 +1,10 @@
+/**
+ * Scenario: transcript contract layers preserve granularity, pagination,
+ * history folding, validation, and view dispatch semantics. The suite uses
+ * only the package's pure public helpers. Run with
+ * `pnpm --filter @moonshot-ai/transcript test`.
+ */
+
 import { describe, expect, it } from 'vitest';
 
 import { filterOpsForGrade, isAppendOnly, redactSnapshotForGrade } from '#/granularity/filterOps';
@@ -82,6 +89,19 @@ describe('granularity', () => {
     ]);
   });
 
+  it('frame removal follows frame detail granularity', () => {
+    const removal: TranscriptOperation = {
+      op: 'frame.remove',
+      turnId: 't1',
+      stepId: 't1.1',
+      frameId: 't1.1.f1',
+    };
+
+    expect(filterOpsForGrade('turn', [removal])).toEqual([]);
+    expect(filterOpsForGrade('block', [removal])).toEqual([removal]);
+    expect(filterOpsForGrade('delta', [removal])).toEqual([removal]);
+  });
+
   it('delta admits everything', () => {
     expect(filterOpsForGrade('delta', ops)).toHaveLength(ops.length);
   });
@@ -260,6 +280,7 @@ describe('contract schemas', () => {
       turnOp(1),
       stepOp,
       frameOp,
+      { op: 'frame.remove', turnId: 't1', stepId: 't1.1', frameId: 't1.1.f1' },
       appendOp,
       { op: 'marker.upsert', item: { kind: 'marker', markerId: 'm1', marker: 'goal' } },
       { op: 'taskref.upsert', item: { kind: 'taskref', refId: 'r1', taskId: 'task1' } },
@@ -348,6 +369,17 @@ describe('contract schemas', () => {
             llmClientConsumeMs: 950,
           },
           retry: { failedAttempt: 1, nextAttempt: 2, maxAttempts: 3, delayMs: 500, errorName: 'RateLimit', errorMessage: 'slow down', statusCode: 429 },
+          failover: {
+            fromModel: 'secondary-model',
+            toModel: 'primary-model',
+            fromProvider: 'secondary-provider',
+            toProvider: 'primary-provider',
+            fromEffort: 'high',
+            toEffort: 'high',
+            reason: 'retry_exhausted',
+            switchIndex: 1,
+            maxSwitches: 1,
+          },
           endReason: 'aborted',
           endMessage: 'user pressed escape',
         },
@@ -851,6 +883,44 @@ describe('foldWireRecordFacts (cold facts)', () => {
     expect(reentered.meta.modes).toEqual({ plan: {} });
   });
 
+  it('folds persisted model failover records into an audit marker', () => {
+    const folded = foldWireRecordFacts(
+      [
+        {
+          type: 'model.failover',
+          turnId: 3,
+          step: 2,
+          fromModel: 'secondary-model',
+          toModel: 'primary-model',
+          fromProvider: 'secondary-provider',
+          toProvider: 'primary-provider',
+          fromEffort: 'high',
+          toEffort: 'high',
+          reason: 'retry_exhausted',
+          switchIndex: 1,
+          maxSwitches: 1,
+          time: 2000,
+        },
+      ],
+      baseWithMarker(),
+    );
+
+    expect(folded.items).toContainEqual(
+      expect.objectContaining({
+        kind: 'marker',
+        marker: 'model.failover',
+        payload: expect.objectContaining({
+          turnId: 3,
+          step: 2,
+          fromModel: 'secondary-model',
+          toModel: 'primary-model',
+          reason: 'retry_exhausted',
+        }),
+        at: new Date(2000).toISOString(),
+      }),
+    );
+  });
+
   it('folds task records into task entities and timeline taskrefs', () => {
     const base = baseWithMarker();
     const folded = foldWireRecordFacts(
diff --git a/packages/transcript/test/store.test.ts b/packages/transcript/test/store.test.ts
index f7a6d728db..3e6df39670 100644
--- a/packages/transcript/test/store.test.ts
+++ b/packages/transcript/test/store.test.ts
@@ -1,3 +1,10 @@
+/**
+ * Scenario: transcript operations converge into an agent-scoped materialized
+ * store. Responsibilities include parent synthesis, idempotent upsert/removal,
+ * offset-safe append, global entities, and snapshots. All collaborators are
+ * the real pure reducers. Run with `pnpm --filter @moonshot-ai/transcript test`.
+ */
+
 import { describe, expect, it } from 'vitest';
 
 import { AgentTranscript } from '#/store/agentTranscript';
@@ -70,6 +77,32 @@ describe('AgentTranscript', () => {
     expect(turn.steps[0]?.frames.map((f) => f.kind)).toEqual(['tool']);
   });
 
+  it('removes an abandoned frame when addressed twice, the second removal is absorbed', () => {
+    const tx = new AgentTranscript('main');
+    tx.apply(toolFrame('running'));
+
+    const first = tx.apply([
+      {
+        op: 'frame.remove',
+        turnId: 't1',
+        stepId: 't1.1',
+        frameId: 't1.1.call_1',
+      },
+    ]);
+    const second = tx.apply([
+      {
+        op: 'frame.remove',
+        turnId: 't1',
+        stepId: 't1.1',
+        frameId: 't1.1.call_1',
+      },
+    ]);
+
+    expect(first.accepted).toHaveLength(1);
+    expect(second.accepted).toEqual([]);
+    expect(tx.getTurn('t1')?.steps[0]?.frames).toEqual([]);
+  });
+
   it('auto-vivifies missing parents so any op order stays self-consistent', () => {
     const tx = new AgentTranscript('main');
     tx.apply([