muonroi-cli 1.2.2 → 1.3.1

package/src/orchestrator/orchestrator.ts

@@ -1,44 +1,35 @@
 // Multi-provider wired — runtime dispatch via providers/runtime.ts.
 
-import { APICallError } from "@ai-sdk/provider";
-import { convertToBase64 } from "@ai-sdk/provider-utils";
-import { generateText, type ModelMessage, stepCountIs, streamText, type ToolSet } from "ai";
+import type { ModelMessage, ToolSet } from "ai";
+import { extractSession } from "../ee/extract-session.js";
+import { bootstrapEEClient, getDefaultEEClient, getLastSurfacedState } from "../ee/intercept.js";
+import { getTenantId } from "../ee/tenant.js";
 import { createRun, getActiveRunId, setActiveRunId } from "../flow/run-manager.js";
 import { ensureFlowDir } from "../flow/scaffold.js";
 import { executeEventHooks } from "../hooks/index";
-import type { PreToolUseHookInput, PostToolUseHookInput } from "../hooks/types";
-import { bootstrapEEClient, getDefaultEEClient, getLastSurfacedState } from "../ee/intercept.js";
-import { getTenantId } from "../ee/tenant.js";
-import { routeFeedback, routeModel } from "../ee/bridge.js";
-import { reportRouteOutcome } from "../router/decide.js";
-import { routerStore } from "../router/store.js";
-import { statusBarStore } from "../ui/status-bar/store.js";
-import { taskTypeToTier, taskTypeToMaxTokens, taskTypeToReasoningEffort } from "../pil/task-tier-map.js";
 import type {
   NotificationHookInput,
   PostCompactHookInput,
   PreCompactHookInput,
   SessionEndHookInput,
-  SessionStartHookInput,
-  StopFailureHookInput,
-  StopHookInput,
   SubagentStartHookInput,
   SubagentStopHookInput,
   TaskCompletedHookInput,
   TaskCreatedHookInput,
-  UserPromptSubmitHookInput,
 } from "../hooks/types";
 import { shutdownWorkspaceLspManager } from "../lsp/runtime";
-import { extractSession } from "../ee/extract-session.js";
 import { ensureDefaultMcpServers } from "../mcp/auto-setup.js";
-import { buildMcpToolSet } from "../mcp/runtime";
-import { createBuiltinTools } from "../tools/registry.js";
+import { getModelByTier, getModelInfo, normalizeModelId } from "../models/registry.js";
+import { getProviderCapabilities } from "../providers/capabilities.js";
+import { apiBaseFor } from "../providers/endpoints.js";
 import { loadKeyForProvider } from "../providers/keychain.js";
-import { captureToolSchemas } from "../providers/patch-zod-schema.js";
-import { getModelInfo, normalizeModelId } from "../models/registry.js";
-import { needsVisionProxy, proxyVision } from "../providers/vision-proxy.js";
-import { isDebugEnabled, recordTurnTrace, type PipelineStep, type TurnTrace } from "../ui/slash/debug.js";
-import { applyPilSuffix, getResponseToolSet, isResponseTool, getResponseTaskType, runPipeline } from "../pil/index.js";
+import {
+  createProviderFactory,
+  createProviderFactoryAsync,
+  detectProviderForModel,
+  resolveModelRuntime as resolveRuntime,
+} from "../providers/runtime.js";
+import type { ProviderId } from "../providers/types.js";
 import {
   appendCompaction,
   appendMessages,
@@ -48,16 +39,17 @@ import {
   getSessionTotalTokens,
   loadTranscript,
   loadTranscriptState,
+  logInteraction,
+  markMessageCompleted,
   recordUsageEvent,
   SessionStore,
 } from "../storage/index";
 import { BashTool } from "../tools/bash";
+import { createBuiltinTools } from "../tools/registry.js";
 import { type ScheduleDaemonStatus, ScheduleManager, type StoredSchedule } from "../tools/schedule";
 import type {
   AgentMode,
   ChatEntry,
-  ModelInfo,
-  Plan,
   SessionInfo,
   SessionSnapshot,
   StreamChunk,
@@ -69,114 +61,82 @@ import type {
   VerifyRecipe,
   WorkspaceInfo,
 } from "../types/index";
-import { loadCustomInstructions } from "../utils/instructions";
-import { type PermissionMode, toolNeedsApproval } from "../utils/permission-mode.js";
+import { statusBarStore } from "../ui/status-bar/store.js";
+import { appendCostLog } from "../usage/cost-log.js";
+import { appendDecisionLog } from "../usage/decision-log.js";
+import { projectCostUSD } from "../usage/estimator.js";
+import type { PermissionMode } from "../utils/permission-mode.js";
 import {
   type CustomSubagentConfig,
+  getAutoCompactThresholdPct,
+  getCouncilRounds,
   getCurrentModel,
+  getCurrentShellSettings,
   getModeSpecificModel,
-  getCouncilRounds,
   getRoleModel,
   getRoleModels,
   isAutoCompactAfterTurnEnabled,
-  isAutoCouncilEnabled,
-  loadMcpServers,
-  loadValidSubAgents,
+  isCouncilMultiProviderPreferred,
+  isProviderDisabled,
   type ModelRole,
   type SandboxMode,
   type SandboxSettings,
 } from "../utils/settings";
 import { runSideQuestion, type SideQuestionResult } from "../utils/side-question";
-import { discoverSkills, formatSkillsForPrompt } from "../utils/skills";
-import { buildVerifyDetectPrompt, normalizeVerifyRecipe, prepareVerifySandbox } from "../verify/entrypoint";
+import { buildVerifyDetectPrompt, normalizeVerifyRecipe } from "../verify/entrypoint";
 import { runVerifyOrchestration } from "../verify/orchestrator";
+import {
+  type AgentOptions,
+  type BatchChatCompletionResponse,
+  type BatchClientOptions,
+  type BatchFunctionTool,
+  COUNCIL_COLOR_BG,
+  COUNCIL_COLOR_RESET,
+  COUNCIL_ROLE_COLORS,
+  type LegacyProvider,
+  type ProcessMessageObserver,
+  type ProcessMessageUsage,
+  type ResolvedModelRuntime,
+} from "./agent-options";
+import { BatchTurnRunner, type BatchTurnRunnerDeps } from "./batch-turn-runner.js";
+import {
+  accumulateUsage,
+  buildAssistantBatchMessage,
+  buildBatchChatCompletionRequest,
+  buildBatchName,
+  buildToolBatchMessage,
+  type ExecutedBatchTool,
+  extractJsonObject,
+  getBatchFinishReason,
+  getBatchUsage,
+  hasUsage,
+  parseToolArgumentsOrRaw,
+  toLocalToolCall,
+} from "./batch-utils";
 import {
   type CompactionSettings,
   createCompactionSummaryMessage,
   DEFAULT_KEEP_RECENT_TOKENS,
   DEFAULT_RESERVE_TOKENS,
-  POST_TURN_MIN_TOKENS,
   estimateConversationTokens,
+  extractUserContent,
   generateCompactionSummary,
+  POST_TURN_MIN_TOKENS,
   prepareCompaction,
-  relaxCompactionSettings,
   shouldCompactContext,
 } from "./compaction";
+import { CouncilManager } from "./council-manager.js";
+import { CrossTurnDedup, isCrossTurnDedupEnabled } from "./cross-turn-dedup.js";
 import { DelegationManager } from "./delegations";
 import { loadFlowResumeDigest } from "./flow-resume.js";
-import { stableCallId } from "./pending-calls.js";
-import { containsEncryptedReasoning, sanitizeModelMessages } from "./reasoning";
-import {
-  createProviderFactory,
-  resolveModelRuntime as resolveRuntime,
-  detectProviderForModel,
-  type ProviderFactory,
-  type ResolvedModelRuntime as RuntimeResult,
-} from "../providers/runtime.js";
-import type { ProviderId } from "../providers/types.js";
-
-// ---------------------------------------------------------------------------
-// Re-export types from shared runtime module for back-compat
-// ---------------------------------------------------------------------------
-
-export type { ProviderFactory as LegacyProvider, ResolvedModelRuntime } from "../providers/runtime.js";
-type LegacyProvider = ProviderFactory;
-type ResolvedModelRuntime = RuntimeResult;
-
-/** @deprecated Use ModelInfo from "../types/index" instead. */
-export type ModelInfoStub = ModelInfo;
-
-// Batch API type stubs
-export interface BatchClientOptions {
-  apiKey: string;
-  baseURL?: string;
-  signal?: AbortSignal;
-}
-
-export interface BatchChatMessage {
-  role: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  content: any;
-  tool_call_id?: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tool_calls?: any[];
-  name?: string;
-}
-
-export interface BatchFunctionTool {
-  type: "function";
-  function: { name: string; description?: string; parameters?: unknown };
-}
-
-export interface BatchToolCall {
-  id: string;
-  type: "function";
-  function: { name: string; arguments: string };
-}
-
-export interface BatchChatCompletionRequest {
-  model: string;
-  messages: BatchChatMessage[];
-  tools?: BatchFunctionTool[];
-  temperature?: number;
-  max_tokens?: number;
-  reasoning_effort?: string;
-}
-
-export interface BatchChatCompletionResponse {
-  choices: Array<{
-    message: { role: string; content: string | null; tool_calls?: BatchToolCall[] };
-    finish_reason: string;
-  }>;
-  usage?: {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    input_tokens?: number;
-    output_tokens?: number;
-    cost_in_usd_ticks?: number;
-  };
-}
+import { MessageProcessor, type MessageProcessorDeps } from "./message-processor.js";
+import { lastPersistedSeq } from "./message-seq.js";
+import { buildSystemPrompt, MAX_TOOL_ROUNDS } from "./prompts";
+import { getReadPathBudgetCap, ReadPathBudget } from "./read-path-budget.js";
+import { withStreamRetry } from "./retry-stream.js";
+import { StreamRunner, type StreamRunnerDeps } from "./stream-runner.js";
+import { setProviderHint } from "./token-counter.js";
+import { firstLine, formatSubagentActivity, toToolResult } from "./tool-utils";
 
 // ---------------------------------------------------------------------------
 // Provider implementations
@@ -251,514 +211,27 @@ function createTools(
     subagents?: unknown[];
     sendTelegramFile?: (filePath: string) => Promise<ToolResult>;
     sessionId?: string;
+    modelId?: string;
   },
 ): ToolSet {
-  return createBuiltinTools(
-    _bash as BashTool,
-    (_mode ?? "agent") as AgentMode,
-    {
-      runTask: _opts?.runTask,
-      runDelegation: _opts?.runDelegation,
-      readDelegation: _opts?.readDelegation,
-      listDelegations: _opts?.listDelegations,
-    },
-  );
-}
-
-async function buildVisionUserMessages(_prompt: string, _cwd: string, _signal?: AbortSignal): Promise<ModelMessage[]> {
-  // Vision input is an anti-feature per PROJECT.md Out-of-Scope. Always throws.
-  throw new Error("Vision input is not supported in muonroi-cli (anti-feature per PROJECT.md).");
+  return createBuiltinTools(_bash as BashTool, (_mode ?? "agent") as AgentMode, {
+    runTask: _opts?.runTask,
+    runDelegation: _opts?.runDelegation,
+    readDelegation: _opts?.readDelegation,
+    listDelegations: _opts?.listDelegations,
+    modelId: _opts?.modelId,
+  });
 }
 
 // ---------------------------------------------------------------------------
 // END Plan 00-05 provider implementations
+// (Phase 12.3 — `buildVisionUserMessages` was inlined into StreamRunner;
+// vision is an anti-feature per PROJECT.md Out-of-Scope so the helper is gone.)
 // ---------------------------------------------------------------------------
 
-const MAX_TOOL_ROUNDS = 75;
-const VISION_MODEL = "grok-4-1-fast-reasoning";
-const COMPUTER_MODEL = "grok-4.20-0309-reasoning";
-
-interface AgentOptions {
-  persistSession?: boolean;
-  session?: string;
-  sandboxMode?: SandboxMode;
-  sandboxSettings?: SandboxSettings;
-  batchApi?: boolean;
-  /** Optional external AbortContext (from src/index.ts SIGINT handler). When provided,
-   *  the orchestrator uses its signal instead of creating a new AbortController per turn.
-   *  TUI-04: Ctrl+C mid-tool-call abort safety. */
-  abortContext?: import("./abort.js").AbortContext;
-  /** Optional PendingCallsLog for Pitfall 9 staged-write tracking per tool call. */
-  pendingCalls?: import("./pending-calls.js").PendingCallsLog;
-  /** Permission mode controlling which tool calls require manual approval.
-   *  safe (default) = confirm all; auto-edit = auto-approve file ops; yolo = auto-approve all. */
-  permissionMode?: PermissionMode;
-}
-
-type ProcessMessageFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other";
-
-export interface ProcessMessageUsage {
-  inputTokens?: number;
-  outputTokens?: number;
-  totalTokens?: number;
-  costUsdTicks?: number;
-  cacheReadTokens?: number;
-  cacheCreationTokens?: number;
-}
-
-export interface ProcessMessageStepStart {
-  stepNumber: number;
-  timestamp: number;
-}
-
-export interface ProcessMessageStepFinish {
-  stepNumber: number;
-  timestamp: number;
-  finishReason: ProcessMessageFinishReason;
-  usage: ProcessMessageUsage;
-}
-
-export interface ProcessMessageToolStart {
-  toolCall: ToolCall;
-  timestamp: number;
-}
-
-export interface ProcessMessageToolFinish {
-  toolCall: ToolCall;
-  toolResult: ToolResult;
-  timestamp: number;
-}
-
-export interface ProcessMessageError {
-  message: string;
-  timestamp: number;
-}
-
-export interface ProcessMessageObserver {
-  onStepStart?(info: ProcessMessageStepStart): void;
-  onStepFinish?(info: ProcessMessageStepFinish): void;
-  onToolStart?(info: ProcessMessageToolStart): void;
-  onToolFinish?(info: ProcessMessageToolFinish): void;
-  onError?(info: ProcessMessageError): void;
-}
-
-const ENVIRONMENT = `ENVIRONMENT:
-You are running inside a terminal (CLI). Your text output is rendered in a plain terminal — not a browser, not a rich text editor.
-- Use plain text only. No markdown tables, no HTML, no images, no colored text.
-- Use simple markers like dashes (-) or asterisks (*) for lists.
-- Use indentation and blank lines for structure.
-- Keep lines under 100 characters when possible.
-- Use backticks for inline code and triple backticks for code blocks — these are rendered.
-- Never use unicode box-drawing, fancy borders, or ASCII art in your responses.`;
-
-const MODE_PROMPTS: Record<AgentMode, string> = {
-  agent: `You are muonroi-cli in Agent mode — a powerful AI coding agent. You execute tasks directly using tools.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents with start_line/end_line for iterative reading. Use for examining code.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files. Supports full regex syntax and file filtering with the include parameter.
-- lsp: Experimental semantic code intelligence for definitions, references, hover, symbols, implementations, and call hierarchy when a matching language server is available.
-- write_file: Create new files or overwrite existing ones with full content.
-- edit_file: Replace a unique string in a file with new content. The old_string must be unique — include enough context lines.
-- bash: Execute shell commands. Set background=true for long-running processes (dev servers, watchers, builds). Returns a process ID immediately.
-- process_logs: View recent output from a background process by ID.
-- process_stop: Stop a background process by ID.
-- process_list: List all background processes with status and uptime.
-- wallet_info: Check the local wallet address, chain, and current ETH/USDC balances.
-- wallet_history: Show recent x402 payment history from the audit log.
-- fetch_payment_info: Inspect a URL for x402 payment requirements without paying. Returns payment options and a brin security score. Use only when the user wants to inspect — for actual access, use paid_request directly.
-- paid_request: Access an x402-protected URL using the local wallet. Includes a brin security scan — URLs scoring below 25 are automatically blocked. The user will be prompted to approve the payment before it executes. Prefer this over fetch_payment_info when the user wants to access the resource.
-- task: Delegate a focused foreground task to a sub-agent. Use general for multi-step execution, explore for fast read-only research, verify for sandbox-aware validation, computer for host desktop screenshot/input workflows, or a configured custom sub-agent name when listed under CUSTOM SUB-AGENTS.
-- delegate: Launch a read-only background agent for longer research while you continue working.
-- delegation_read: Retrieve a completed background delegation result by ID.
-- delegation_list: List running and completed background delegations. Do not poll it repeatedly.
-- schedule_create: Create a recurring or one-time scheduled headless run.
-- schedule_list: List saved schedules and their status.
-- schedule_remove: Remove a saved schedule.
-- schedule_read_log: Read recent log output from a schedule.
-- schedule_daemon_status: Check whether the schedule daemon is running.
-- schedule_daemon_start: Start the schedule daemon in the background.
-- schedule_daemon_stop: Stop the schedule daemon.
-- search_web: Search the web for current information, documentation, APIs, tutorials, etc.
-- search_x: Search X/Twitter for real-time posts, discussions, opinions, and trends.
-- generate_image: Generate a new image or edit an existing image. It saves image files locally and returns their paths.
-- generate_video: Generate a new video or animate an existing image. It saves video files locally and returns their paths.
-- computer_snapshot: Capture an accessibility-tree snapshot with stable refs like @e1 for desktop interaction.
-- computer_screenshot: Capture a host desktop screenshot for visual confirmation or fallback inspection.
-- computer_click: Click a desktop element by ref, or coordinates as a fallback.
-- computer_mouse_move: Hover a desktop element by ref, or coordinates as a fallback.
-- computer_type: Type text into a specific desktop element ref.
-- computer_press: Press a key or key chord in the focused host application.
-- computer_scroll: Scroll a desktop element by ref.
-- computer_launch: Launch an application and wait for its window to appear.
-- computer_list_windows: List visible windows and their ids.
-- computer_focus_window: Bring a target window to the front.
-- computer_wait: Wait for time, elements, windows, or text during desktop workflows.
-- computer_get: Read a property from a desktop element ref.
-- MCP tools: Enabled servers appear as tools named like mcp_<server>__<tool>.
-
-WORKFLOW:
-1. Understand the request
-2. Decide whether a sub-agent should handle the first investigation pass
-3. Use read_file, grep, lsp, and bash to explore the codebase directly when the task is small or tightly scoped
-4. Use bash with background=true for dev servers, watchers, or any long-running process — then continue working
-5. Use delegate for read-only work that can run in parallel, then continue productive work
-6. Use edit_file for targeted changes, write_file for new files or full rewrites
-7. Verify changes by reading modified files
-8. Run tests or builds with bash to confirm correctness
-9. Use search_web or search_x when you need up-to-date information
-
-DEFAULT DELEGATION POLICY:
-- Prefer the task tool by default for code review, code quality analysis, architecture research, root-cause investigation, bug triage, verification, or any request that likely needs reading multiple files before acting.
-- Prefer delegate for longer-running read-only exploration when you can keep making progress without blocking.
-- Use the explore sub-agent for read-only investigation, reviews, research, and "how does this work?" tasks.
-- Use the general sub-agent for delegated work that may need editing files, running commands, or producing a concrete implementation.
-- Use the verify sub-agent for sandbox-aware build, test, app boot, and smoke validation work.
-- Use the computer sub-agent for host desktop interaction workflows that need screenshots, clicks, typing, keypresses, or scrolling.
-- Use a matching custom sub-agent when the task fits one of the configured specializations.
-- Never use delegate for tasks that should edit files or make shell changes.
-- When a background delegation is running, do not wait idly and do not spam delegation_list(). Continue useful work.
-- Do not wait for the user to explicitly ask for a sub-agent when delegation would clearly help.
-- Skip delegation only when the task is trivial, single-file, or you already have the exact answer.
-
-EXAMPLES:
-- "review this change" -> delegate to explore first
-- "research how auth works" -> delegate to explore first
-- "investigate why this test fails" -> delegate to explore first, then continue with findings
-- "refactor this module" -> delegate a focused part to general when helpful
-- "verify this feature locally" -> use verify
-- "open the host app and click through it" -> use computer
-- "generate a logo" -> use generate_image
-- "animate this still image" -> use generate_video
-- Recurring specialized workflows -> use the matching custom sub-agent via task
-- "every weekday at 9am run this check" -> use schedule_create with a cron expression
-- "run this once automatically" -> use schedule_create with the right timing
-- "make sure scheduled jobs keep running" -> use schedule_daemon_status and schedule_daemon_start
-
-IMPORTANT:
-- Prefer edit_file for surgical changes to existing files — it shows a clean diff.
-- Prefer grep over bash for searching file contents. Use bash only for find, ls, git, and other shell commands.
-- Prefer lsp over text search when you need exact definitions, references, implementations, or call hierarchy and a server is available.
-- Use write_file only for new files or when most of the file is changing.
-- Use read_file instead of cat/head/tail for reading files.
-- When the user asks for an automated recurring or one-time run, use the schedule tools instead of only describing the setup.
-- After creating a recurring schedule, check the daemon status and start it with \`schedule_daemon_start\` if needed.
-
-Be direct. Execute, don't just describe. Show results, not plans.`,
-
-  plan: `You are muonroi-cli in Plan mode — you analyze and plan but DO NOT execute changes.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents for analysis.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
-- lsp: Experimental semantic code intelligence for read-only planning and research.
-- bash: ONLY for searching (find, ls), git inspection — NEVER modify files.
-- task: Delegate a focused task to a sub-agent when deeper research or specialized analysis would help.
-- generate_plan: ALWAYS use this to present your plan. Creates an interactive UI with steps and questions.
-
-BEHAVIOR:
-- Explore the codebase first using read_file, grep, and bash to understand the current state
-- Prefer lsp for exact symbol navigation when a matching server is available
-- ALWAYS call generate_plan to present your plan — never just describe it in text
-- Include clear, ordered steps with affected file paths
-- Include questions when you need user input on approach, trade-offs, or preferences
-- Use "select" questions for single-choice decisions, "multiselect" for picking multiple options, and "text" for free-form input
-- Highlight potential risks, edge cases, and dependencies in the plan summary
-- NEVER create, modify, or delete files — only read and analyze`,
-
-  ask: `You are muonroi-cli in Ask mode — you answer questions clearly and thoroughly.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents for context.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
-- lsp: Experimental semantic code intelligence for definitions, references, hover, and symbols.
-- bash: ONLY for searching (find, ls), git inspection — NEVER modify.
-- task: Delegate a focused task to a sub-agent when specialized analysis or deeper investigation would help.
-
-BEHAVIOR:
-- Answer the user's question directly and thoroughly
-- Use tools to gather context when needed, preferring lsp for exact symbol questions when available
-- Provide code examples when helpful
-- NEVER create, modify, or delete files
-- Focus on explanation, not execution`,
-};
-
-function findCustomSubagent(
-  agent: string,
-  subagents: CustomSubagentConfig[] = loadValidSubAgents(),
-): CustomSubagentConfig | undefined {
-  return (
-    subagents.find((item) => item.name === agent) ??
-    subagents.find((item) => item.name.toLowerCase() === agent.toLowerCase())
-  );
-}
-
-function formatCustomSubagentsPromptSection(subagents: CustomSubagentConfig[]): string {
-  if (subagents.length === 0) return "";
-
-  const lines = subagents.map((agent) => {
-    const instruction = agent.instruction.trim() || "(none)";
-    return `### ${agent.name}\n- model: ${agent.model}\n- instruction:\n${instruction}`;
-  });
-
-  return `\n\nCUSTOM SUB-AGENTS:\nUser-defined foreground sub-agents from ~/.muonroi-cli/user-settings.json. When one matches the task, call the task tool with agent set to the exact name.\n\n${lines.join("\n\n")}\n`;
-}
-
-interface SystemPromptParts {
-  staticPrefix: string;
-  dynamicSuffix: string;
-}
-
-const NON_ANTHROPIC_TOOL_PREAMBLE = `\n\nIMPORTANT — TOOL CALLING:
-You MUST invoke tools ONLY via the structured function calling API provided to you.
-NEVER output XML tags like <tool_name>, <bash>, <read_file>, or <delegate> as text.
-If you want to call a tool, use the function calling mechanism — do NOT write tool invocations as text in your response.
-Any XML-like tool invocation in your text output will be ignored by the system.\n`;
-
-/**
- * Strip the TOOLS: listing section from system prompt.
- * Non-Anthropic models receive tool definitions via the API's structured `tools` parameter;
- * keeping the text listing causes them to output raw XML instead of structured tool calls.
- */
-function stripToolsSection(text: string): string {
-  return text.replace(/\nTOOLS:\n[\s\S]*?\n(?=WORKFLOW:|BEHAVIOR:|IMPORTANT:|DEFAULT DELEGATION|EXAMPLES:|$)/g, "\n");
-}
-
-function buildSystemPromptParts(
-  cwd: string,
-  mode: AgentMode,
-  sandboxMode: SandboxMode,
-  planContext?: string | null,
-  subagents?: CustomSubagentConfig[],
-  sandboxSettings?: SandboxSettings,
-  providerId?: string,
-): SystemPromptParts {
-  const custom = loadCustomInstructions(cwd);
-  const customSection = custom
-    ? `\n\nCUSTOM INSTRUCTIONS:\n${custom}\n\nFollow the above alongside standard instructions.\n`
-    : "";
-
-  const skillsText = formatSkillsForPrompt(discoverSkills(cwd));
-  const skillsSection = skillsText ? `\n\n${skillsText}\n` : "";
-  const subagentsSection = formatCustomSubagentsPromptSection(subagents ?? loadValidSubAgents());
-  const sandboxSection = formatSandboxPromptSection(sandboxMode, sandboxSettings);
-
-  let modePrompt = MODE_PROMPTS[mode];
-  if (providerId && providerId !== "anthropic") {
-    modePrompt = stripToolsSection(modePrompt) + NON_ANTHROPIC_TOOL_PREAMBLE;
-  }
-
-  const staticPrefix = `${modePrompt}${sandboxSection}${customSection}${skillsSection}${subagentsSection}`;
-
-  const planSection = planContext
-    ? `\n\nAPPROVED PLAN:\nThe following plan has been approved by the user. Execute it now.\n${planContext}\n`
-    : "";
-
-  const dynamicSuffix = `${planSection}\n\nCurrent working directory: ${cwd}`;
-
-  return { staticPrefix, dynamicSuffix };
-}
-
-function buildSystemPrompt(
-  cwd: string,
-  mode: AgentMode,
-  sandboxMode: SandboxMode,
-  planContext?: string | null,
-  subagents?: CustomSubagentConfig[],
-  sandboxSettings?: SandboxSettings,
-  providerId?: string,
-): string {
-  const { staticPrefix, dynamicSuffix } = buildSystemPromptParts(cwd, mode, sandboxMode, planContext, subagents, sandboxSettings, providerId);
-  return `${staticPrefix}${dynamicSuffix}`;
-}
-
-function buildSubagentPrompt(
-  request: TaskRequest,
-  cwd: string,
-  custom: CustomSubagentConfig | null,
-  sandboxMode: SandboxMode,
-  subagents?: CustomSubagentConfig[],
-  sandboxSettings?: SandboxSettings,
-  providerId?: string,
-): string {
-  const isExplore = request.agent === "explore";
-  const isVision = request.agent === "vision";
-  const isVerify = request.agent === "verify";
-  const isVerifyDetect = request.agent === "verify-detect";
-  const isVerifyManifest = request.agent === "verify-manifest";
-  const isComputer = request.agent === "computer";
-  const mode: AgentMode = isExplore || isVerifyDetect ? "ask" : "agent";
-  const role = custom
-    ? `You are the custom sub-agent "${custom.name}". You can investigate, edit files, and run commands unless the delegated task says otherwise.`
-    : request.agent === "explore"
-      ? "You are the Explore sub-agent. You are read-only and focus on fast codebase research."
-      : isVision
-        ? "You are the Vision sub-agent."
-        : isVerifyDetect
-          ? "You are the Verify Detect sub-agent. You inspect a repository to produce a structured verification recipe. You are read-only."
-          : isVerifyManifest
-            ? "You are the Verify Manifest sub-agent. You inspect a repository and create or update .muonroi-cli/environment.json so verification can run reproducibly."
-            : isVerify
-              ? "You are the Verify sub-agent. You specialize in sandbox-aware local verification using builds, tests, app boot checks, and optional browser smoke tests."
-              : isComputer
-                ? "You are the Computer sub-agent. You specialize in host desktop automation using accessibility snapshots, semantic element refs, screenshots, and careful mouse and keyboard actions."
-                : "You are the General sub-agent. You can investigate, edit files, and run commands to complete delegated work.";
-
-  const rules = isExplore
-    ? [
-        "Do not create, modify, or delete files.",
-        "Prefer `read_file` and search commands over broad shell exploration.",
-        "Return concise findings for the parent agent.",
-      ]
-    : isVerifyDetect
-      ? [
-          "Do not create, modify, or delete files.",
-          "Read config files, package manifests, scripts, and source layout to understand the project.",
-          "Return ONLY a valid JSON object with the VerifyRecipe schema. No markdown, no prose, no explanation outside the JSON.",
-        ]
-      : isVerifyManifest
-        ? [
-            "Focus on creating or updating .muonroi-cli/environment.json as the primary verification contract for this repository.",
-            "Read package.json and key config files to understand the project, then write .muonroi-cli/environment.json.",
-            "Prefer editing only .muonroi-cli/environment.json unless the delegated task explicitly requires something else.",
-            "",
-            "SANDBOX ENVIRONMENT (Shuru):",
-            "- OS: Debian GNU/Linux 13 (trixie)",
-            "- Architecture: aarch64 (ARM64)",
-            "- Pre-installed: NOTHING. No node, npm, npx, bun, python3, pip, go, cargo, java, or any runtime.",
-            "- Only basic system tools exist (sh, apt-get, curl, etc).",
-            "- Network access is available during bootstrap and install.",
-            "- The workspace is mounted at /workspace.",
-            "",
-            "MANIFEST REQUIREMENTS:",
-            "- bootstrapCommands: MUST install every runtime and build tool the project needs from scratch via apt-get or curl.",
-            "- For Node.js/Next.js/Vite/etc: `apt-get update && apt-get install -y curl unzip ca-certificates git python3 make g++ pkg-config nodejs npm`",
-            "- For Bun projects: also `curl -fsSL https://bun.sh/install | bash` and shellInitCommands with BUN_INSTALL/PATH exports.",
-            "- For Python: `apt-get update && apt-get install -y python3 python3-pip python3-venv ca-certificates git`",
-            "- For Go: `apt-get update && apt-get install -y golang ca-certificates git`",
-            "- For Rust: `apt-get update && apt-get install -y curl ca-certificates git build-essential && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y`",
-            "- installCommands: The package install command (npm install, pip install, etc).",
-            "- buildCommands: Build commands if applicable.",
-            "- testCommands: Test/lint commands if applicable.",
-            "- startCommand + startPort: How to start the app for smoke testing.",
-            "- smokeKind: 'http' if the app has a web UI, 'cli' for CLI tools, 'none' otherwise.",
-            "- Do NOT leave bootstrapCommands empty. The sandbox has nothing.",
-            "",
-            "Return a concise summary of what you wrote and why.",
-          ]
-        : isVision
-          ? ["Validate the image."]
-          : isComputer
-            ? [
-                "Operate carefully on the HOST desktop, not inside the shell sandbox.",
-                "Start with `computer_snapshot` when possible. It returns stable refs like @e1 that remain valid until the next snapshot.",
-                "Prefer accessibility refs over coordinates. Use `computer_click`, `computer_type`, `computer_scroll`, and `computer_get` with refs from the latest snapshot.",
-                "After any meaningful UI transition, launch, dialog open, or menu change, take another `computer_snapshot` before reusing old refs.",
-                "Use `computer_launch`, `computer_list_windows`, `computer_focus_window`, and `computer_wait` to manage apps and window state.",
-                "Use `computer_press` for shortcuts like Enter or cmd+k. Use `computer_screenshot` only for visual confirmation or when the accessibility tree is insufficient.",
-                "If `agent-desktop` is unavailable, permissions are missing, refs go stale, or the state is ambiguous, stop and return the blocker clearly to the parent agent.",
-                "Do not perform destructive or high-risk desktop actions unless the delegated task explicitly requires them.",
-              ]
-            : isVerify
-              ? [
-                  "You are a QA engineer. Your job is to prove the app works end-to-end, not just that it builds.",
-                  "Do not make durable source edits unless the delegated task explicitly asks for fixes.",
-                  "",
-                  "MANDATORY VERIFICATION STEPS (do ALL of these in order):",
-                  "1. Install dependencies (run installCommands from the recipe).",
-                  "2. Build the project (run buildCommands from the recipe).",
-                  "3. Run tests/lint if available (run testCommands from the recipe).",
-                  "4. Start the app (run startCommand from the recipe in the background).",
-                  "5. Wait for the app to be ready (curl readiness check or agent-browser wait).",
-                  "6. Run browser smoke tests like a real human QA tester:",
-                  "   - Open the app in the browser, record a video, take screenshots.",
-                  "   - Navigate the app: click links, buttons, menus. Verify pages load.",
-                  "   - Check for JavaScript console errors.",
-                  "   - Spend 3-5 interactions testing the critical path.",
-                  "7. Stop recording, close browser, then stop the dev server.",
-                  "",
-                  "Do NOT stop after build/lint. Starting the app and testing it in the browser is the most important part.",
-                  "agent-browser commands run on the HOST, not inside the sandbox. They WILL work. Do not skip them.",
-                  "Return a concise verification report. Keep it compact but always include Evidence with artifact file paths.",
-                ]
-              : [
-                  "Work only on the delegated task below.",
-                  "Use tools directly instead of narrating your intent.",
-                  "Return a concise summary for the parent agent with key outcomes and any open risks.",
-                ];
-
-  const instructionLines = custom?.instruction.trim() ? ["", "SUB-AGENT INSTRUCTIONS:", custom.instruction.trim()] : [];
-
-  return [
-    role,
-    ...instructionLines,
-    "",
-    "You are helping a parent agent. Do not address the end user directly.",
-    "Focus tightly on the delegated scope and summarize what matters back to the parent agent.",
-    "",
-    ...rules,
-    "",
-    `Delegated task: ${request.description}`,
-    "",
-    buildSystemPrompt(cwd, mode, sandboxMode, undefined, subagents, sandboxSettings, providerId),
-  ].join("\n");
-}
-
-function formatSandboxPromptSection(sandboxMode: SandboxMode, settings?: SandboxSettings): string {
-  if (sandboxMode === "off") return "";
-
-  const s = settings ?? {};
-  let networkLine: string;
-  if (s.allowNet) {
-    networkLine = s.allowedHosts?.length
-      ? `- Network access is restricted to: ${s.allowedHosts.join(", ")}.`
-      : "- Network access is enabled.";
-  } else {
-    networkLine = "- Network is disabled.";
-  }
-
-  const lines = [
-    "",
-    "SANDBOX MODE:",
-    "- Bash commands run inside a Shuru sandbox.",
-    networkLine,
-    "- The current workspace is mounted inside the sandbox at `/workspace`.",
-    "- Shell-side workspace file changes do not persist back to the host in this version.",
-    "- Use `read_file`, `edit_file`, and `write_file` for durable source edits.",
-    "- If a task needs a host-persistent shell mutation, explain that sandbox mode blocks that workflow and ask whether to disable sandbox mode.",
-  ];
-
-  if (s.ports?.length) {
-    lines.push(`- Port forwards: ${s.ports.join(", ")}.`);
-  }
-  if (s.from) {
-    lines.push(`- Starting from checkpoint: ${s.from}.`);
-  }
-
-  return lines.join("\n");
-}
-
-function applyModelConstraints(system: string, modelId: string): string {
-  const modelInfo = getModelInfo(modelId);
-  if (modelInfo?.supportsClientTools !== false) {
-    return system;
-  }
-
-  return [
-    system,
-    "",
-    "MODEL CONSTRAINTS:",
-    "- The selected model does not support client-side CLI tool calls in this environment.",
-    "- Do not call bash, read_file, lsp, write_file, edit_file, task, delegate, delegation, or MCP tools.",
-    "- Answer directly using only the conversation context already provided.",
-  ].join("\n");
-}
+// ============================================================================
+// Agent class — fields, constructor, session management, core processing loop
+// ============================================================================
 
 export class Agent {
   private provider: LegacyProvider | null = null;
@@ -786,6 +259,20 @@ export class Agent {
   /** PIL context for current turn — set after runPipeline, cleared after recordUsage. */
   private _pilActive = false;
   private _pilEnrichmentDelta = 0;
+  /**
+   * Breakdown of the system prompt + messages + tools sent on the last call.
+   * Captured immediately before streamText and consumed by recordUsage to
+   * attach to the cost-log entry. Cleared after recordUsage so subsequent
+   * non-message calls don't reuse stale data.
+   */
+  private _lastPromptBreakdown: Record<string, number> | null = null;
+  /**
+   * Phase O1 — JSON-shape of the providerOptions object on the most
+   * recent streamText call. Captured immediately before streamText and
+   * consumed by recordUsage; cleared after. Cost-leak forensics surfaces
+   * this so we can answer "did this billed call carry store=true?" etc.
+   */
+  private _lastProviderOptionsShape: string | null = null;
   /** External abort context from src/index.ts SIGINT handler (TUI-04). */
   private externalAbortContext: import("./abort.js").AbortContext | null = null;
   /** Pending calls log for Pitfall 9 staged-write tracking. */
@@ -798,8 +285,50 @@ export class Agent {
   private _activeRunId: string | null = null;
   /** Resume digest loaded from active flow run state.md. */
   private _resumeDigest: string | null = null;
+  /**
+   * Phase 12.1-02: All council state (synthesis/continuation flags, resolver
+   * + buffer maps, stats) lives inside CouncilManager. Agent holds one ref.
+   */
+  private councilManager: CouncilManager;
   /** Whether compaction already ran during the current turn (prevents double-compact). */
   private _compactedThisTurn = false;
+  /** Guard: OAuth provider init runs at most once per Agent instance. */
+  private _oauthInitDone = false;
+  /** P0 native observation: warning IDs surfaced earlier in this session — sent as intent_context.priorWarningIdsInSession. */
+  private _priorWarningIdsInSession = new Set<string>();
+  /** EE session guidance: structured warnings accumulated across turns — injected into model context at turn start. Keyed by principle_uuid to deduplicate. */
+  private _sessionEEGuidance = new Map<
+    string,
+    { toolName: string; message: string; why: string; confidence: number }
+  >();
+  /** P0 native observation: rolling buffer of assistant reasoning text in current turn — last 200 chars sent as intent_context.assistantReasoningExcerpt. */
+  private _turnAssistantReasoning = "";
+  /** Per-call correlation id for top-level streamText; set in MessageProcessor, consumed by recordUsage / onFinish llm-done. */
+  private _currentCallId = "";
+  /** P0 native observation: first 200 chars of the user's current turn — sent as intent_context.userGoalExcerpt to PreToolUse. */
+  private _turnUserGoalExcerpt = "";
+  /** Compaction statistics tracking count and total tokens saved. */
+  private _compactionStats: { count: number; totalSaved: number } = { count: 0, totalSaved: 0 };
+  /**
+   * Pinned message sequences. A pinned user message is preserved verbatim across
+   * compaction — it is re-injected as a system note immediately after the
+   * compaction summary, so the model still sees the original wording.
+   * V1 only supports user messages (avoids splitting tool-call/result pairs).
+   */
+  private _pinnedSeqs = new Set<number>();
+  /** One-shot cwd note injected at the start of the next processMessage turn after setCwd(). Cleared after injection. */
+  private _pendingCwdNote: string | null = null;
+
+  // Phase C3: cross-turn tool-output dedup. One instance per session; bumped
+  // on each user turn. Lazily initialized so disabled-via-env path stays cheap.
+  private _crossTurnDedup: CrossTurnDedup | null = isCrossTurnDedupEnabled() ? new CrossTurnDedup() : null;
+  // Phase C4 — input-keyed read-path budget. Complements C3 (output hash) by
+  // catching re-reads of files the agent edited between rounds. Disabled
+  // when MUONROI_MAX_READS_PER_PATH=0.
+  private _readBudget: ReadPathBudget | null = (() => {
+    const cap = getReadPathBudgetCap();
+    return cap > 0 ? new ReadPathBudget(cap) : null;
+  })();
 
   constructor(
     apiKey: string | undefined,
@@ -812,12 +341,25 @@ export class Agent {
     this.bash = new BashTool(process.cwd(), {
       sandboxMode: options.sandboxMode ?? "off",
       sandboxSettings: options.sandboxSettings,
+      shellSettings: options.shellSettings ?? getCurrentShellSettings(),
     });
     this.delegations = new DelegationManager(() => this.bash.getCwd());
+    // Phase 12.1-02: council state + helpers live in CouncilManager. DI via
+    // getter callbacks so the manager reads live Agent state without holding
+    // a circular reference to the Agent instance.
+    this.councilManager = new CouncilManager({
+      getModelId: () => this.modelId,
+      getSessionId: () => this.session?.id ?? null,
+      hasSessionStore: () => this.sessionStore !== null,
+      getMessages: () => this.messages,
+      getBash: () => this.bash,
+      getMode: () => this.mode,
+    });
 
     const initialMode: AgentMode = "agent";
     this.modelId = normalizeModelId(model || getCurrentModel(initialMode));
     this.providerId = detectProviderForModel(this.modelId);
+    setProviderHint(this.providerId);
     if (apiKey) {
       this.setApiKey(apiKey, baseURL);
     }
@@ -855,7 +397,7 @@ export class Agent {
    * Fail-open: any error sets _activeRunId = null silently.
    */
   private async _initFlow(): Promise<void> {
-    bootstrapEEClient().catch(() => {});
+    await bootstrapEEClient().catch(() => {});
     try {
       const flowDir = await ensureFlowDir(this.bash.getCwd());
       const existing = await getActiveRunId(flowDir);
@@ -891,9 +433,11 @@ export class Agent {
     const newProviderId = detectProviderForModel(this.modelId);
     if (newProviderId !== this.providerId && this.apiKey) {
       this.providerId = newProviderId;
-      const effectiveBaseURL = this.providerId !== "anthropic" && this.baseURL === "https://api.anthropic.com"
-        ? undefined
-        : (this.baseURL ?? undefined);
+      setProviderHint(this.providerId);
+      const effectiveBaseURL =
+        this.providerId !== "anthropic" && this.baseURL === apiBaseFor("anthropic")
+          ? undefined
+          : (this.baseURL ?? undefined);
       this.provider = createProvider(this.providerId, this.apiKey, effectiveBaseURL);
     }
     if (this.sessionStore && this.session) {
@@ -954,14 +498,14 @@ export class Agent {
     this.baseURL = baseURL || null;
     // Only pass baseURL to provider factory if it's an explicit override,
     // not the default Anthropic URL (which would break non-Anthropic providers).
-    const effectiveBaseURL = this.providerId !== "anthropic" && baseURL === "https://api.anthropic.com"
-      ? undefined
-      : baseURL;
+    const effectiveBaseURL =
+      this.providerId !== "anthropic" && baseURL === apiBaseFor("anthropic") ? undefined : baseURL;
     this.provider = createProvider(this.providerId, apiKey, effectiveBaseURL);
   }
 
   setProviderAndKey(providerId: ProviderId, apiKey: string, baseURL?: string): void {
     this.providerId = providerId;
+    setProviderHint(this.providerId);
     this.setApiKey(apiKey, baseURL);
   }
 
@@ -973,6 +517,11 @@ export class Agent {
     return this.bash.getCwd();
   }
 
+  setCwd(dir: string): void {
+    this.bash.setCwd(dir);
+    this._pendingCwdNote = `(system: working directory has been changed to ${dir} — subsequent shell commands run from there; do NOT cd to that path again)`;
+  }
+
   getMessages(): ModelMessage[] {
     return this.messages;
   }
@@ -1097,8 +646,7 @@ export class Agent {
 
   async clearHistory(): Promise<void> {
     // D-09: Extract messages accumulated since last clear BEFORE reset
-    await extractSession(this.messages, this.bash.getCwd(), "cli-clear", this.getSessionId())
-      .catch(() => {}); // D-05: redundant safety — extractSession already swallows
+    await extractSession(this.messages, this.bash.getCwd(), "cli-clear", this.getSessionId()).catch(() => {}); // D-05: redundant safety — extractSession already swallows
     this.startNewSession();
   }
 
@@ -1113,15 +661,20 @@ export class Agent {
       this.sessionStartHookFired = false;
     }
 
-    // Reset token counters and cost for the new session
+    // Reset token counters, cost, and compaction state for the new session
     statusBarStore.setState({
       in_tokens: 0,
       out_tokens: 0,
       cache_read_tokens: 0,
       cache_creation_tokens: 0,
       session_usd: 0,
+      ctx_tokens: 0,
+      compaction_summary: undefined,
     });
 
+    this._compactionStats = { count: 0, totalSaved: 0 };
+    this._pinnedSeqs.clear();
+
     if (!this.sessionStore) {
       this.messages = [];
       this.messageSeqs = [];
@@ -1148,6 +701,44 @@ export class Agent {
     return this.session?.title || null;
   }
 
+  getCompactionStats(): { count: number; totalSaved: number } {
+    return { ...this._compactionStats };
+  }
+
+  /**
+   * Pin a user message by its sequence number. Pinned messages survive
+   * compaction verbatim — re-injected as a system note after the summary.
+   * Returns true if the message was found, is a user message, and got pinned.
+   */
+  pinMessageBySeq(seq: number): boolean {
+    const idx = this.messageSeqs.indexOf(seq);
+    if (idx < 0) return false;
+    if (this.messages[idx]?.role !== "user") return false;
+    this._pinnedSeqs.add(seq);
+    return true;
+  }
+
+  /** Pin the most recent user message in the live conversation. Returns its seq, or null. */
+  pinLastUserMessage(): number | null {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      if (this.messages[i]?.role !== "user") continue;
+      const seq = this.messageSeqs[i];
+      if (typeof seq === "number") {
+        this._pinnedSeqs.add(seq);
+        return seq;
+      }
+    }
+    return null;
+  }
+
+  unpinMessageBySeq(seq: number): boolean {
+    return this._pinnedSeqs.delete(seq);
+  }
+
+  getPinnedSeqs(): number[] {
+    return [...this._pinnedSeqs].sort((a, b) => a - b);
+  }
+
   getChatEntries(): ChatEntry[] {
     if (!this.session) return [];
     return buildChatEntries(this.session.id);
@@ -1180,13 +771,24 @@ export class Agent {
   private discardAbortedTurn(userMessage: ModelMessage): void {
     const idx = this.messages.lastIndexOf(userMessage);
     if (idx >= 0) {
-      this.messages.splice(idx, 1);
-      this.messageSeqs.splice(idx, 1);
+      // Keep the user message but add a stub assistant response so the
+      // conversation remains valid for follow-up messages after ESC.
+      const alreadyHasResponse = idx < this.messages.length - 1 && this.messages[idx + 1]?.role === "assistant";
+      if (!alreadyHasResponse) {
+        this.messages.splice(idx + 1, 0, { role: "assistant", content: "[Interrupted]" });
+        this.messageSeqs.splice(idx + 1, 0, null);
+      }
     }
   }
 
   private recordUsage(
-    usage?: { totalTokens?: number; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheCreationTokens?: number },
+    usage?: {
+      totalTokens?: number;
+      inputTokens?: number;
+      outputTokens?: number;
+      cacheReadTokens?: number;
+      cacheCreationTokens?: number;
+    },
     source: UsageSource = "message",
     model = this.modelId,
   ): void {
@@ -1194,12 +796,55 @@ export class Agent {
     if (this.session) {
       const pilActive = source === "message" ? this._pilActive : false;
       const enrichmentDelta = source === "message" ? this._pilEnrichmentDelta : 0;
-      recordUsageEvent(this.session.id, source, model, usage, null, pilActive, enrichmentDelta);
+      // Attribute usage to the most recent persisted message — this lets
+      // per-prompt cost analysis work (was null hardcoded → impossible).
+      const lastSeq = lastPersistedSeq(this.messageSeqs);
+      // Phase O1 — providerOptions shape (types only, no values) attached
+      // to every usage event so post-mortem can answer "what provider
+      // options did this billed call carry?". Cleared below for "message"
+      // sources so non-message calls don't reuse stale data.
+      const providerOptionsShape = this._lastProviderOptionsShape;
+      recordUsageEvent(
+        this.session.id,
+        source,
+        model,
+        usage,
+        lastSeq,
+        pilActive,
+        enrichmentDelta,
+        providerOptionsShape,
+      );
       if (source === "message") {
         this._pilActive = false;
         this._pilEnrichmentDelta = 0;
+        this._lastProviderOptionsShape = null;
       }
     }
+    // Phase D — surfaced for harness E2E verification. Mirror the recorded usage
+    // event onto the agent-mode sidechannel so spec processes can assert on
+    // cacheReadTokens / cacheCreationTokens normalization without poking at the
+    // child's sqlite. Best-effort, only fires when agent-mode runtime is set.
+    try {
+      const rt = (globalThis as Record<string, unknown>).__muonroiAgentRuntime as
+        | { emitEvent?: (e: unknown) => void }
+        | undefined;
+      if (rt?.emitEvent) {
+        const lastSeqForEvent = this.session ? lastPersistedSeq(this.messageSeqs) : null;
+        rt.emitEvent({
+          t: "event",
+          kind: "usage",
+          source,
+          model,
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+          cacheReadTokens: usage.cacheReadTokens,
+          cacheCreationTokens: usage.cacheCreationTokens,
+          messageSeq: lastSeqForEvent,
+        });
+      }
+    } catch {
+      // best-effort: do not let sidechannel failures interrupt usage recording
+    }
     // Update status bar token counters + provider/model + cache metrics + cost
     const prev = statusBarStore.getState();
     const info = getModelInfo(model);
@@ -1212,7 +857,8 @@ export class Agent {
     const priceOut = info?.outputPrice ?? 0;
     // API inputTokens includes cacheRead — subtract to get non-cached portion
     const nonCachedInput = Math.max(0, totalInput - cacheRead - cacheCreate);
-    const turnCostMicros = nonCachedInput * priceIn + cacheRead * priceCached + cacheCreate * priceIn + output * priceOut;
+    const turnCostMicros =
+      nonCachedInput * priceIn + cacheRead * priceCached + cacheCreate * priceIn + output * priceOut;
     statusBarStore.setState({
       in_tokens: prev.in_tokens + totalInput,
       out_tokens: prev.out_tokens + output,
@@ -1222,6 +868,28 @@ export class Agent {
       provider: this.providerId,
       model,
     });
+
+    // Append to cost-log JSONL so `usage report --by callsite` can surface
+    // where orchestrator/task/title traffic is actually spending.
+    // Best-effort: failures inside appendCostLog are swallowed (see cost-log.ts).
+    const breakdown = source === "message" ? (this._lastPromptBreakdown ?? undefined) : undefined;
+    appendCostLog({
+      ts: Date.now(),
+      provider: this.providerId,
+      model,
+      estimatedUsd: turnCostMicros / 1_000_000,
+      callsite: `orchestrator.${source}`,
+      phase: source,
+      actualInputTokens: totalInput,
+      actualOutputTokens: output,
+      cachedInputTokens: cacheRead,
+      systemChars: breakdown?.systemChars,
+      promptChars: breakdown?.messagesChars,
+      breakdown,
+    }).catch(() => undefined);
+    // Don't clear breakdown — onStepFinish fires recordUsage per step within
+    // the same streamText call, and they all share the same prompt structure.
+    // It is overwritten on the next streamText setup, which is the right scope.
   }
 
   async consumeBackgroundNotifications(): Promise<string[]> {
@@ -1340,12 +1008,14 @@ export class Agent {
       signal,
     } = args;
 
-    if (childRuntime.modelInfo?.responsesOnly) {
+    const childCaps = getProviderCapabilities(childRuntime.modelInfo?.provider ?? "anthropic");
+    if (childCaps.usesResponsesAPI(childRuntime.modelInfo)) {
       throw new Error("Batch mode currently supports chat-completions models only.");
     }
 
-    const batchTools =
-      childRuntime.modelInfo?.supportsClientTools === false ? [] : await toolSetToBatchTools(childTools);
+    const batchTools = !childCaps.supportsClientTools(childRuntime.modelInfo)
+      ? []
+      : await toolSetToBatchTools(childTools);
     const batch = await createBatch({
       ...this.getBatchClientOptions(signal),
       name: buildBatchName(`task-${request.agent}`, request.description),
@@ -1370,10 +1040,9 @@ export class Agent {
                 system: childSystem,
                 messages: [...childMessages, ...turnMessages],
                 temperature: request.agent === "explore" ? 0.2 : 0.5,
-                maxOutputTokens:
-                  childRuntime.modelInfo?.supportsMaxOutputTokens === false
-                    ? undefined
-                    : Math.min(this.maxTokens, 8_192),
+                maxOutputTokens: !childCaps.acceptsParam("maxOutputTokens", childRuntime.modelInfo)
+                  ? undefined
+                  : Math.min(this.maxTokens, 8_192),
                 reasoningEffort: childRuntime.providerOptions?.xai.reasoningEffort,
                 tools: batchTools,
               }),
@@ -1462,244 +1131,42 @@ export class Agent {
     };
   }
 
+  /**
+   * Run a sub-agent task by spawning a child `streamText` session.
+   *
+   * Phase 12.3 — body extracted to `StreamRunner` (`./stream-runner.ts`).
+   * This method now builds the DI dep set and delegates to
+   * `StreamRunner.run()`. Public signature is unchanged so all callers
+   * (`runTask`, `tools/registry`, batch path, council path) work as before.
+   */
   async runTaskRequest(
     request: TaskRequest,
     onActivity?: (detail: string) => void,
     abortSignal?: AbortSignal,
   ): Promise<ToolResult> {
     const provider = this.requireProvider();
-    const signal = abortSignal;
-    const agentKey = String(request.agent);
-    const isExplore = agentKey === "explore";
-    const isGeneral = agentKey === "general";
-    const isVision = agentKey === "vision";
-    const isVerify = agentKey === "verify";
-    const isVerifyDetect = agentKey === "verify-detect";
-    const isVerifyManifest = agentKey === "verify-manifest";
-    const isComputer = agentKey === "computer";
-    const subagents = loadValidSubAgents();
-    const custom =
-      !isExplore && !isGeneral && !isVision && !isVerify && !isVerifyDetect && !isVerifyManifest && !isComputer
-        ? findCustomSubagent(agentKey, subagents)
-        : undefined;
-
-    if (
-      !isExplore &&
-      !isGeneral &&
-      !isVision &&
-      !isVerify &&
-      !isVerifyDetect &&
-      !isVerifyManifest &&
-      !isComputer &&
-      !custom
-    ) {
-      const message = `Unknown sub-agent "${agentKey}". Use general, explore, vision, verify, verify-detect, verify-manifest, computer, or a configured name from ~/.muonroi-cli/user-settings.json.`;
-      return {
-        success: false,
-        output: message,
-        task: {
-          agent: agentKey,
-          description: request.description,
-          summary: message,
-        },
-      };
-    }
-
-    const childMode: AgentMode = isExplore || isVerifyDetect ? "ask" : "agent";
-    const verifySandboxOverrides: SandboxSettings = isVerify
-      ? { allowNet: true, allowedHosts: undefined, allowEphemeralInstall: true, hostBrowserCommandsOnHost: true }
-      : {};
-    let verifyPreparedSettings: SandboxSettings | null = null;
-    let verifyPreparedRecipe: VerifyRecipe | null = null;
-    if (isVerify) {
-      const prepared = await prepareVerifySandbox(
-        this.bash.getCwd(),
-        { ...this.bash.getSandboxSettings(), ...verifySandboxOverrides },
-        undefined,
-        onActivity,
-      );
-      verifyPreparedSettings = prepared.sandboxSettings;
-      verifyPreparedRecipe = prepared.profile.recipe;
-    }
-    const childBash = new BashTool(this.bash.getCwd(), {
-      sandboxMode: isVerify ? "shuru" : this.bash.getSandboxMode(),
-      sandboxSettings: isVerify
-        ? (verifyPreparedSettings ?? { ...this.bash.getSandboxSettings(), ...verifySandboxOverrides })
-        : this.bash.getSandboxSettings(),
-    });
-    const childBaseTools = createTools(childBash, provider, childMode);
-    const initialDetail = isExplore
-      ? "Scanning the codebase"
-      : isVerifyDetect
-        ? "Detecting verification recipe"
-        : isVerifyManifest
-          ? "Creating verification manifest"
-          : isVerify
-            ? "Preparing verification pass"
-            : isComputer
-              ? "Preparing computer control pass"
-              : "Planning delegated work";
-    let assistantText = "";
-    let lastActivity = initialDetail;
-    let childTools: ToolSet = childBaseTools;
-    let closeMcp: (() => Promise<void>) | undefined;
-    const childModelId = normalizeModelId(
-      isVision
-        ? VISION_MODEL
-        : isComputer
-          ? COMPUTER_MODEL
-          : isExplore
-            ? DEFAULT_MODEL
-            : custom
-              ? custom.model
-              : this.modelId,
-    );
-    const childRuntime = isVision
-      ? { ...resolveModelRuntime(provider, childModelId), model: provider.responses?.(childModelId) ?? provider(childModelId) }
-      : resolveModelRuntime(provider, childModelId);
-    if (isComputer && childRuntime.modelInfo?.supportsClientTools === false) {
-      return {
-        success: false,
-        output:
-          "Computer sub-agent requires a tool-capable model, but the selected runtime does not support client tools.",
-        task: {
-          agent: agentKey,
-          description: request.description,
-          summary: "Computer sub-agent could not start because the chosen model does not support tools.",
-        },
-      };
-    }
-    const childSystem = applyModelConstraints(
-      buildSubagentPrompt(
-        request,
-        childBash.getCwd(),
-        custom ?? null,
-        childBash.getSandboxMode(),
-        subagents,
-        childBash.getSandboxSettings(),
-        childRuntime.modelInfo?.provider ?? this.providerId,
-      ),
-      childRuntime.modelId,
-    );
-
-    onActivity?.(initialDetail);
-
-    try {
-      if (childMode === "agent" && childRuntime.modelInfo?.supportsClientTools !== false) {
-        const mcpBundle = await buildMcpToolSet(loadMcpServers(), {
-          onOAuthRequired: (_serverId, url) => {
-            const urlStr = url.toString();
-            import("child_process").then(({ exec }) => {
-              const cmd = process.platform === "win32" ? `start "" "${urlStr}"`
-                : process.platform === "darwin" ? `open "${urlStr}"`
-                : `xdg-open "${urlStr}"`;
-              exec(cmd);
-            });
-          },
-        });
-        closeMcp = mcpBundle.close;
-        childTools = { ...childBaseTools, ...mcpBundle.tools };
-        captureToolSchemas(childTools);
-        if (mcpBundle.errors.length > 0) {
-          lastActivity = `MCP unavailable: ${mcpBundle.errors.join(" | ")}`;
-          onActivity?.(lastActivity);
-        }
-      }
-
-      const childPrompt =
-        isVerify && verifyPreparedRecipe
-          ? `${request.prompt}\n\nPrepared verify recipe JSON (use this as the primary execution recipe and keep .muonroi-cli/environment.json aligned with it if present):\n${JSON.stringify(verifyPreparedRecipe, null, 2)}`
-          : request.prompt;
-
-      const childMessages = isVision
-        ? await buildVisionUserMessages(request.prompt, childBash.getCwd(), signal)
-        : [{ role: "user" as const, content: childPrompt }];
-
-      if (this.batchApi) {
-        return await this.runTaskRequestBatch({
-          request,
-          childMessages,
-          childSystem,
-          childRuntime,
-          childTools,
-          maxSteps: Math.min(this.maxToolRounds, isExplore ? 60 : 120),
-          initialDetail,
-          onActivity,
-          signal,
-        });
-      }
-
-      const result = streamText({
-        model: childRuntime.model,
-        system: childSystem,
-        messages: childMessages,
-        tools: childRuntime.modelInfo?.supportsClientTools === false ? {} : childTools,
-        stopWhen: stepCountIs(Math.min(this.maxToolRounds, isExplore ? 60 : 120)),
-        maxRetries: 0,
-        abortSignal: signal,
-        temperature: isExplore ? 0.2 : 0.5,
-        ...(childRuntime.modelInfo?.supportsMaxOutputTokens === false
-          ? {}
-          : { maxOutputTokens: Math.min(this.maxTokens, 8_192) }),
-        ...(childRuntime.providerOptions ? { providerOptions: childRuntime.providerOptions } : {}),
-        onFinish: ({ totalUsage, providerMetadata }) => {
-          const anthropicMeta = providerMetadata?.anthropic as Record<string, unknown> | undefined;
-          const cacheReadTokens = asNumber(anthropicMeta?.cacheReadInputTokens) ?? 0;
-          const cacheCreationTokens = asNumber(anthropicMeta?.cacheCreationInputTokens) ?? 0;
-          this.recordUsage({ ...totalUsage, cacheReadTokens, cacheCreationTokens }, "task", childRuntime.modelId);
-        },
-      });
-
-      for await (const part of result.fullStream) {
-        if (signal?.aborted) {
-          break;
-        }
-
-        if (part.type === "text-delta") {
-          assistantText += part.text;
-          continue;
-        }
-
-        if (part.type === "tool-call") {
-          lastActivity = formatSubagentActivity(part.toolName, part.input);
-          onActivity?.(lastActivity);
-        }
-      }
-
-      if (signal?.aborted) {
-        return { success: false, output: "[Cancelled]" };
-      }
-
-      await result.response;
-
-      const output = assistantText.trim() || `Task completed. Last action: ${lastActivity}`;
-      return {
-        success: true,
-        output,
-        task: {
-          agent: request.agent,
-          description: request.description,
-          summary: firstLine(output),
-          activity: lastActivity,
-        },
-      };
-    } catch (err: unknown) {
-      if (signal?.aborted) throw err;
-      const msg = err instanceof Error ? err.message : String(err);
-      const output = `Task failed: ${msg}`;
-      return {
-        success: false,
-        output,
-        task: {
-          agent: request.agent,
-          description: request.description,
-          summary: output,
-          activity: lastActivity,
-        },
-      };
-    } finally {
-      await closeMcp?.().catch(() => {});
-    }
+    const deps: StreamRunnerDeps = {
+      getProvider: () => provider,
+      resolveModelForTask: (task) => this._resolveModelForTask(task),
+      getModelId: () => this.modelId,
+      getProviderId: () => this.providerId,
+      getBash: () => this.bash,
+      getMaxToolRounds: () => this.maxToolRounds,
+      getMaxTokens: () => this.maxTokens,
+      isBatchApiEnabled: () => this.batchApi,
+      getCrossTurnDedup: () => this._crossTurnDedup,
+      getReadBudget: () => this._readBudget,
+      recordUsage: (usage, source, model) => this.recordUsage(usage, source, model),
+      setCurrentCallId: (id) => {
+        this._currentCallId = id;
+      },
+      setLastProviderOptionsShape: (shape) => {
+        this._lastProviderOptionsShape = shape;
+      },
+      runTaskRequestBatch: (args) => this.runTaskRequestBatch(args),
+    };
+    const runner = new StreamRunner(deps);
+    return runner.run(request, onActivity, abortSignal);
   }
 
   private async runTask(request: TaskRequest, abortSignal?: AbortSignal): Promise<ToolResult> {
@@ -1714,17 +1181,53 @@ export class Agent {
 
     let result: ToolResult;
     try {
-      result = await this.runTaskRequest(
-        request,
-        (detail) => {
-          if (abortSignal?.aborted) return;
-          this.emitSubagentStatus({
-            agent: request.agent,
-            description: request.description,
-            detail,
-          });
+      result = await withStreamRetry(
+        () =>
+          this.runTaskRequest(
+            request,
+            (detail) => {
+              if (abortSignal?.aborted) return;
+              this.emitSubagentStatus({
+                agent: request.agent,
+                description: request.description,
+                detail,
+              });
+            },
+            abortSignal,
+          ),
+        {
+          signal: abortSignal,
+          onRetry: (info) => {
+            // Emit harness telemetry
+            try {
+              const _ar = (globalThis as Record<string, unknown>).__muonroiAgentRuntime as
+                | { emitEvent: (e: unknown) => void }
+                | undefined;
+              _ar?.emitEvent({
+                t: "event",
+                kind: "stream-retry",
+                ...info,
+              });
+            } catch {
+              /* best-effort */
+            }
+            try {
+              if (this.session) {
+                logInteraction(this.session.id, "stream_retry", {
+                  data: {
+                    attempt: info.attempt,
+                    maxAttempts: info.maxAttempts,
+                    errorName: info.errorName,
+                    errorMessage: info.errorMessage.slice(0, 200),
+                    nextDelayMs: info.nextDelayMs,
+                  },
+                });
+              }
+            } catch {
+              /* fail-open */
+            }
+          },
         },
-        abortSignal,
       );
     } finally {
       this.emitSubagentStatus(null);
@@ -1832,19 +1335,49 @@ export class Agent {
     }
   }
 
-  private getCompactionSettings(): CompactionSettings {
+  private getCompactionSettings(contextWindow?: number): CompactionSettings {
+    let keepRecentTokens = DEFAULT_KEEP_RECENT_TOKENS;
+
+    // For models with very large context windows, keep more recent tokens
+    if (contextWindow && contextWindow > 200_000) {
+      keepRecentTokens = Math.min(100_000, Math.max(20_000, Math.floor(contextWindow * 0.1)));
+    }
+
+    // Compact more aggressively for long sessions to prevent runaway token growth
+    if (this._compactionStats.count >= 2) {
+      keepRecentTokens = Math.floor(keepRecentTokens * 0.75);
+    }
+
     return {
       reserveTokens: Math.max(this.maxTokens, DEFAULT_RESERVE_TOKENS),
-      keepRecentTokens: DEFAULT_KEEP_RECENT_TOKENS,
+      keepRecentTokens,
     };
   }
 
+  private _resolveCompactModel(): string {
+    return this._resolveModelForTask("compact");
+  }
+
+  private _resolveModelForTask(task: "compact" | "explore" | "general" | "title"): string {
+    const tierPrefs: Record<string, Array<"fast" | "balanced" | "premium">> = {
+      compact: ["fast", "balanced"],
+      title: ["fast", "balanced"],
+      explore: ["balanced", "fast"],
+      general: ["premium", "balanced"],
+    };
+    for (const tier of tierPrefs[task] ?? ["balanced"]) {
+      const m = getModelByTier(tier, this.providerId);
+      if (m?.provider === this.providerId) return m.id;
+    }
+    return this.modelId;
+  }
+
   private async compactForContext(
     provider: LegacyProvider,
     system: string,
     contextWindow: number,
     signal: AbortSignal,
-    settings = this.getCompactionSettings(),
+    settings = this.getCompactionSettings(contextWindow),
     force = false,
   ): Promise<boolean> {
     if (!this.session) return false;
@@ -1878,11 +1411,84 @@ export class Agent {
 
     const keptSeqs = this.messageSeqs.slice(preparation.firstKeptIndex);
     const firstKeptSeq = keptSeqs.find((seq): seq is number => seq !== null) ?? getNextMessageSequence(this.session.id);
-    const summary = await generateCompactionSummary(provider, this.modelId, preparation, undefined, signal);
+    const compactModelId = this._resolveCompactModel();
+    const compactStartedAt = Date.now();
+    const { summary, usage: compactUsage } = await generateCompactionSummary(
+      provider,
+      compactModelId,
+      preparation,
+      undefined,
+      signal,
+    );
+
+    // Record compaction call in cost-log — bypasses recordUsage because
+    // compaction returns usage separately and isn't routed through the
+    // status-bar / usage event pipeline (intentional: it's overhead, not user spend).
+    const compactProvider = detectProviderForModel(compactModelId);
+    appendCostLog({
+      ts: compactStartedAt,
+      provider: compactProvider,
+      model: compactModelId,
+      estimatedUsd: projectCostUSD(
+        compactProvider,
+        compactModelId,
+        compactUsage.promptTokens,
+        compactUsage.completionTokens,
+      ),
+      callsite: "orchestrator.compaction",
+      phase: "compaction",
+      iteration: this._compactionStats.count + 1,
+      actualInputTokens: compactUsage.promptTokens,
+      actualOutputTokens: compactUsage.completionTokens,
+      durationMs: Date.now() - compactStartedAt,
+    }).catch(() => undefined);
 
     appendCompaction(this.session.id, firstKeptSeq, summary, preparation.tokensBefore);
-    this.messages = [createCompactionSummaryMessage(summary), ...preparation.keptMessages];
-    this.messageSeqs = [null, ...keptSeqs];
+
+    // Re-inject pinned user messages that were about to be summarized away.
+    // Pinned seqs that are still inside keptMessages don't need re-injection.
+    const keptSeqSet = new Set(keptSeqs.filter((s): s is number => s !== null));
+    const pinnedReinjections: ModelMessage[] = [];
+    const pinnedReinjectionSeqs: Array<number | null> = [];
+    for (const seq of [...this._pinnedSeqs].sort((a, b) => a - b)) {
+      if (keptSeqSet.has(seq)) continue;
+      const idx = this.messageSeqs.indexOf(seq);
+      if (idx < 0) {
+        // Pinned seq no longer present (shouldn't happen, but stay defensive).
+        this._pinnedSeqs.delete(seq);
+        continue;
+      }
+      const original = this.messages[idx];
+      if (!original || original.role !== "user") continue;
+      const text = extractUserContent(original.content).trim();
+      if (!text) continue;
+      pinnedReinjections.push({
+        role: "system",
+        content: `[Pinned user message — kept verbatim across compaction]\n${text}`,
+      });
+      pinnedReinjectionSeqs.push(null);
+    }
+
+    this.messages = [createCompactionSummaryMessage(summary), ...pinnedReinjections, ...preparation.keptMessages];
+    this.messageSeqs = [null, ...pinnedReinjectionSeqs, ...keptSeqs];
+
+    // Track compaction stats — net of the tokens spent ON compaction itself.
+    const tokensAfter = estimateConversationTokens(system, this.messages);
+    const grossSaved = Math.max(0, preparation.tokensBefore - tokensAfter);
+    const compactCost = compactUsage.promptTokens + compactUsage.completionTokens;
+    const saved = Math.max(0, grossSaved - compactCost);
+    const pct = preparation.tokensBefore > 0 ? ((saved / preparation.tokensBefore) * 100).toFixed(1) : "0.0";
+    this._compactionStats.count++;
+    this._compactionStats.totalSaved += saved;
+
+    // Update status bar with current context size and compaction summary
+    const fmtCompact = (n: number) => (n >= 1000 ? `${(n / 1000).toFixed(1)}K` : String(n));
+    const modelSuffix = compactModelId !== this.modelId ? ` via ${compactModelId}` : "";
+    const userMsgCount = this.messages.filter((m) => m.role === "user").length;
+    const isLongSession = this._compactionStats.count >= 3 || userMsgCount >= 200;
+    const sessionHint = isLongSession ? " ⚠ long session — consider /clear" : "";
+    const compactLabel = `${this._compactionStats.count} cmp, ${fmtCompact(this._compactionStats.totalSaved)} saved${modelSuffix}${sessionHint}`;
+    statusBarStore.setState({ ctx_tokens: tokensAfter, compaction_summary: compactLabel });
 
     const postCompactInput: PostCompactHookInput = {
       hook_event_name: "PostCompact",
@@ -1892,6 +1498,26 @@ export class Agent {
     };
     await this.fireHook(postCompactInput, signal).catch(() => {});
 
+    // Interaction log: compaction
+    try {
+      if (this.session) {
+        logInteraction(this.session.id, "compaction", {
+          data: {
+            count: this._compactionStats.count,
+            tokensBefore: preparation.tokensBefore,
+            tokensAfter,
+            saved,
+            grossSaved,
+            compactCost,
+            pct,
+            isLongSession,
+          },
+        });
+      }
+    } catch {
+      /* fail-open */
+    }
+
     this._compactedThisTurn = true;
     return true;
   }
@@ -1902,135 +1528,330 @@ export class Agent {
     contextWindow: number,
     signal: AbortSignal,
   ): Promise<void> {
-    if (this._compactedThisTurn) return;
-    if (!isAutoCompactAfterTurnEnabled()) return;
-    const tokens = estimateConversationTokens(system, this.messages);
-    if (tokens < POST_TURN_MIN_TOKENS) return;
-    await this.compactForContext(provider, system, contextWindow, signal, this.getCompactionSettings(), true).catch(
-      () => {},
-    );
+    const log = (taken: boolean, reason: string, extra?: Record<string, unknown>): void => {
+      appendDecisionLog({
+        ts: Date.now(),
+        sessionId: this.session?.id ?? null,
+        kind: "post-turn-compact",
+        taken,
+        reason,
+        meta: { contextWindow, ...extra },
+      }).catch(() => undefined);
+    };
+
+    if (this._compactedThisTurn) return log(false, "already-compacted-this-turn");
+    if (!isAutoCompactAfterTurnEnabled()) return log(false, "feature-disabled");
+    const tokens = estimateConversationTokens(system, this.messages);
+    const thresholdPct = getAutoCompactThresholdPct();
+    const minMeaningfulTokens = Math.max(POST_TURN_MIN_TOKENS, Math.floor(contextWindow * thresholdPct));
+    if (tokens < minMeaningfulTokens) {
+      return log(false, `under-threshold (${tokens} < ${minMeaningfulTokens})`, {
+        tokens,
+        thresholdPct,
+        minMeaningfulTokens,
+      });
+    }
+    log(true, `over-threshold (${tokens} >= ${minMeaningfulTokens})`, { tokens, thresholdPct, minMeaningfulTokens });
+    await this.compactForContext(
+      provider,
+      system,
+      contextWindow,
+      signal,
+      this.getCompactionSettings(contextWindow),
+      true,
+    ).catch((err) => console.warn("[compact] failed:", (err as Error)?.message));
   }
 
-  private _councilStats = { calls: 0, startMs: 0 };
+  // ========================================================================
+  // Council system — delegated to CouncilManager (Phase 12.1-02)
+  //
+  // All council state + sub-call helpers (generate/research/prompt builders/
+  // outcome parser/executor/candidate resolution) live in CouncilManager.
+  // The thin facade below preserves the public API the UI + tests rely on
+  // (respondToCouncilQuestion/Preflight + the internal _create*Responder
+  // hooks used by orchestrator.agent.test.ts).
+  // ========================================================================
 
-  private async _councilGenerate(
-    modelId: string,
-    system: string,
-    prompt: string,
-    maxTokens = 2048,
-  ): Promise<string> {
-    const providerId = detectProviderForModel(modelId);
-    const key = await loadKeyForProvider(providerId);
-    const provider = createProvider(providerId, key);
-    const runtime = resolveModelRuntime(provider, modelId);
-    const { text } = await generateText({
-      model: runtime.model,
-      system,
-      prompt,
-      maxOutputTokens: maxTokens,
-      temperature: 0.7,
-      ...(runtime.providerOptions ? { providerOptions: runtime.providerOptions } : {}),
-    });
-    this._councilStats.calls++;
-    return text;
-  }
-
-  private _buildDiscussPrompt(
-    phase: "open" | "respond" | "followup" | "convergence-check",
-    ctx: {
-      speakerRole: string;
-      partnerRole: string;
-      topic: string;
-      speakerPosition?: string;
-      partnerPosition?: string;
-      exchangeHistory?: string;
-      round?: number;
+  respondToCouncilQuestion(questionId: string, answer: string): void {
+    this.councilManager.respondToQuestion(questionId, answer);
+  }
+
+  respondToCouncilPreflight(preflightId: string, approved: boolean): void {
+    this.councilManager.respondToPreflight(preflightId, approved);
+  }
+
+  // Internal hooks used by orchestrator.agent.test.ts to exercise buffered
+  // question / preflight delivery through CouncilManager. They are reached
+  // through `as unknown as` casts in the test; keep them private but stable.
+  private _createQuestionResponder(): (questionId: string) => Promise<string> {
+    return this.councilManager.createQuestionResponder();
+  }
+
+  private _createPreflightResponder(): (preflightId: string) => Promise<boolean> {
+    return this.councilManager.createPreflightResponder();
+  }
+
+  // ========================================================================
+  // Council v2 — Clarify → Confirm → Debate → Plan → Execute
+  // ========================================================================
+
+  async *runCouncilV2(
+    topic: string,
+    options?: {
+      skipClarification?: boolean;
+      observer?: ProcessMessageObserver;
+      userModelMessage?: ModelMessage;
     },
-  ): { system: string; prompt: string } {
-    switch (phase) {
-      case "open":
-        return {
-          system:
-            `You are a ${ctx.speakerRole} specialist. You are entering a discussion with a ${ctx.partnerRole} specialist about a technical topic.\n\n` +
-            `Share your analysis naturally — explain your reasoning, the trade-offs you see, and what concerns you.\n` +
-            `End by asking the ${ctx.partnerRole} for their perspective on your analysis. What do they see differently?`,
-          prompt: `Topic for discussion:\n${ctx.topic}`,
-        };
+  ): AsyncGenerator<StreamChunk, void, unknown> {
+    const { runCouncil } = await import("../council/index.js");
+    const { createCouncilLLM } = await import("../council/llm.js");
+    const councilStats = { calls: 0, startMs: Date.now(), phases: [] as Array<{ name: string; durationMs: number }> };
+    const llm = createCouncilLLM(this.bash, this.mode, this.session?.id, councilStats);
+
+    const processMessageFn = (message: string) => this.processMessage(message, options?.observer);
+
+    const gen = runCouncil(
+      topic,
+      this.modelId,
+      this.messages as Array<{ role: string; content: string | unknown }>,
+      this.session?.id,
+      llm,
+      this.councilManager.createQuestionResponder(),
+      this.councilManager.createPreflightResponder(),
+      processMessageFn,
+      {
+        skipClarification: options?.skipClarification,
+        userModelMessage: options?.userModelMessage,
+        cwd: this.bash.getCwd(),
+        councilStats, // NEW — share orchestrator's stats object with runCouncil (Phase 14 CQ-01)
+      },
+    );
 
-      case "respond":
-        return {
-          system:
-            `You are a ${ctx.speakerRole} specialist in a discussion with a ${ctx.partnerRole} specialist.\n\n` +
-            `A colleague shared their analysis below. Give your honest take:\n` +
-            `- Where you agree, say so briefly and build on it\n` +
-            `- Where you disagree, explain why with your own reasoning — not to attack, but to offer a different lens\n` +
-            `- Share what you think they might be missing from your ${ctx.speakerRole} perspective\n\n` +
-            `End with a question back to them: based on your analysis, what's their view? Do they agree, or do they see it differently?`,
-          prompt:
-            `Their analysis (${ctx.partnerRole}):\n${ctx.partnerPosition}\n\n` +
-            `Your own analysis for context:\n${ctx.speakerPosition}`,
-        };
+    let result: IteratorResult<StreamChunk, string | null>;
+    do {
+      result = await gen.next();
+      if (!result.done && result.value) {
+        yield result.value;
+      }
+    } while (!result.done);
 
-      case "followup":
-        return {
-          system:
-            `You are a ${ctx.speakerRole} specialist continuing a discussion (round ${ctx.round}) with a ${ctx.partnerRole} specialist.\n\n` +
-            `Read their latest response and the exchange so far. Then:\n` +
-            `- If they raised valid points, acknowledge them and update your thinking\n` +
-            `- If you still disagree on something, explain why — bring new evidence or a different angle, not the same argument again\n` +
-            `- If you've changed your mind on something, say so explicitly\n\n` +
-            `End with: do you agree with where we've landed? Or is there something we're still seeing differently?`,
-          prompt:
-            `Discussion so far:\n${ctx.exchangeHistory}\n\n` +
-            `Their latest response (${ctx.partnerRole}):\n${ctx.partnerPosition}`,
-        };
+    const synthesis = result.value;
+    this.councilManager.setLastSynthesis(synthesis);
 
-      case "convergence-check":
-        return {
-          system:
-            `Analyze this discussion between a ${ctx.speakerRole} and a ${ctx.partnerRole}. ` +
-            `Respond with ONLY a JSON object, no other text:\n` +
-            `{"converged": true/false, "reason": "one sentence explaining why"}`,
-          prompt: `Discussion:\n${ctx.exchangeHistory}`,
-        };
+    if (options?.userModelMessage && synthesis) {
+      this.appendCompletedTurn(options.userModelMessage, [{ role: "assistant", content: synthesis }]);
+    }
+  }
+
+  // ========================================================================
+  // Product Ideal Loop (Phase 13) — mirror of runCouncilV2 wiring.
+  // ========================================================================
+
+  async *runProductLoopV1(
+    payload: {
+      subcommand: "start" | "status" | "resume" | "abort" | "ship";
+      idea?: string;
+      runId?: string;
+      flags: {
+        maxCost: number;
+        maxSprints: number;
+        doneThreshold: number;
+        stack?: string;
+        noCustomerDebate?: boolean;
+        noPriorContext?: boolean;
+        forceCouncil?: boolean;
+      };
+    },
+    options?: {
+      observer?: ProcessMessageObserver;
+      userModelMessage?: ModelMessage;
+    },
+  ): AsyncGenerator<StreamChunk, void, unknown> {
+    const { runProductLoop } = await import("../product-loop/index.js");
+    const { createCouncilLLM } = await import("../council/llm.js");
+    const nodePath = await import("node:path");
+
+    const productStats = {
+      calls: 0,
+      startMs: Date.now(),
+      phases: [] as Array<{ name: string; durationMs: number }>,
+    };
+    const llm = createCouncilLLM(this.bash, this.mode, this.session?.id, productStats);
+    const processMessageFn = (m: string) => this.processMessage(m, options?.observer);
+    const flowDir = nodePath.join(this.bash.getCwd(), ".muonroi-flow");
+
+    // P2.7: compute complexity from the idea using PIL Layer 1 heuristics (cheap,
+    // no LLM calls). Only meaningful for "start"; other subcommands ignore it.
+    let complexity: "low" | "medium" | "high" | undefined;
+    let sufficiencyMissing: readonly import("../pil/layer1-intent.js").SufficiencyMissing[] | undefined;
+    if (payload.subcommand === "start" && payload.idea) {
+      const { scoreComplexity, scoreSufficiency } = await import("../pil/layer1-intent.js");
+      const result = scoreComplexity({
+        rawText: payload.idea,
+        taskType: null,
+        t0HitCount: 0,
+        hasMaxSprintsOne: payload.flags.maxSprints === 1,
+      });
+      complexity = result.complexity;
+      // Sufficiency gate — vague briefs ("todo app") force Council so the
+      // discovery AskCard can fill in persona/MVP/architecture/verify before
+      // any code is scaffolded.
+      const suff = scoreSufficiency({ rawText: payload.idea });
+      sufficiencyMissing = suff.sufficient ? undefined : suff.missing;
+    }
+
+    const gen = runProductLoop({
+      subcommand: payload.subcommand,
+      idea: payload.idea ?? "",
+      runId: payload.runId,
+      flowDir,
+      sessionModelId: this.modelId,
+      llm,
+      flags: {
+        maxCost: payload.flags.maxCost,
+        maxSprints: payload.flags.maxSprints,
+        doneThreshold: payload.flags.doneThreshold,
+        stack: payload.flags.stack,
+        forceCouncil: payload.flags.forceCouncil,
+      },
+      respondToQuestion: this.councilManager.createQuestionResponder(),
+      respondToPreflight: this.councilManager.createPreflightResponder(),
+      cwd: this.bash.getCwd(),
+      processMessageFn,
+      skipPriorContext: payload.flags.noPriorContext === true,
+      complexity,
+      sufficiencyMissing,
+      // Chat session id — used as the FK key for interaction_logs telemetry.
+      // The /ideal runId is NOT a sessions.id and would silently fail FK insert.
+      sessionId: this.session?.id,
+    } as Parameters<typeof runProductLoop>[0]);
+
+    for await (const chunk of gen) {
+      yield chunk;
     }
   }
 
+  // ========================================================================
+  // Legacy council — kept for backward compatibility, will be removed
+  // ========================================================================
+
   async *runCouncilRound(
     topic: string,
-    observer?: ProcessMessageObserver,
+    _observer?: ProcessMessageObserver,
     rounds?: number,
+    userModelMessage?: ModelMessage,
   ): AsyncGenerator<StreamChunk, void, unknown> {
     const maxRounds = rounds ?? getCouncilRounds();
     const ALL_ROLES: ModelRole[] = ["implement", "verify", "research"];
-    this._councilStats = { calls: 0, startMs: Date.now() };
+    this.councilManager.resetStats(Date.now());
 
-    // Resolve available role models upfront
+    // Resolve council participants: same-provider by default, multi-provider only when configured
     const candidates: Array<{ role: ModelRole; model: string }> = [];
-    for (const role of ALL_ROLES) {
-      const modelId = getRoleModel(role);
-      if (!modelId) continue;
-      const canReach = await loadKeyForProvider(detectProviderForModel(modelId)).then(() => true).catch(() => false);
-      if (canReach) candidates.push({ role, model: modelId });
+    const configuredRoleModels = getRoleModels();
+    const hasExplicitMultiProvider = this.councilManager.hasMultiProviderConfig(configuredRoleModels);
+
+    if (hasExplicitMultiProvider && isCouncilMultiProviderPreferred()) {
+      // Multi-provider path: use explicitly configured role models across providers
+      for (const role of ALL_ROLES) {
+        const modelId = getRoleModel(role);
+        if (!modelId) continue;
+        const provider = detectProviderForModel(modelId);
+        if (isProviderDisabled(provider as ProviderId)) continue;
+        const canReach = await loadKeyForProvider(provider)
+          .then(() => true)
+          .catch(() => false);
+        if (canReach) candidates.push({ role, model: modelId });
+      }
+      if (candidates.length >= 2) {
+        const providers = new Set(candidates.map((c) => detectProviderForModel(c.model)));
+        yield {
+          type: "content",
+          content: `\n[Multi-provider mode: ${candidates.length} roles across ${providers.size} provider(s)]\n`,
+        };
+      }
+    }
+
+    // Default: same-provider mode — pick diverse models from the session's provider
+    if (candidates.length < 2) {
+      const mainProviderId = detectProviderForModel(this.modelId);
+      // Skip same-provider resolution if the session's provider is disabled
+      if (!isProviderDisabled(mainProviderId as ProviderId)) {
+        const sameCandidates = await this.councilManager.resolveSameProviderCandidates(mainProviderId, ALL_ROLES);
+        if (sameCandidates.length >= 2) {
+          candidates.length = 0;
+          candidates.push(...sameCandidates);
+          const uniqueModels = new Set(sameCandidates.map((c) => c.model));
+          yield {
+            type: "content",
+            content: `\n[Same-provider mode: ${uniqueModels.size} ${mainProviderId} model(s) for ${sameCandidates.length} roles]\n`,
+          };
+        }
+      }
+    }
+
+    // Final fallback: use main model for all roles
+    if (candidates.length < 2) {
+      const mainProviderId = detectProviderForModel(this.modelId);
+      const mainDisabled = isProviderDisabled(mainProviderId as ProviderId);
+      const mainCanReach =
+        !mainDisabled &&
+        (await loadKeyForProvider(mainProviderId)
+          .then(() => true)
+          .catch(() => false));
+      if (mainCanReach) {
+        candidates.length = 0;
+        for (const role of ALL_ROLES) {
+          candidates.push({ role, model: this.modelId });
+        }
+        yield {
+          type: "content",
+          content: `\n[Fallback: using \x1b[36m${this.modelId}\x1b[0m for all roles]\n`,
+        };
+      }
     }
 
     if (candidates.length < 2) {
-      yield { type: "content", content: "\nNeed at least 2 reachable role models. Configure `roleModels` + provider keys in user-settings.json.\n" };
+      yield {
+        type: "content",
+        content: "\nNo reachable provider. Check API keys in user-settings.json or environment.\n",
+      };
       yield { type: "done" };
       return;
     }
 
+    // Build conversation context for all participants
+    const conversationContext = this.councilManager.buildContext();
+
+    // ── Phase 0: Research — gather facts from codebase before discussion ──
+    const p0Start = Date.now();
+    yield { type: "content", content: `\n## Phase 0 — Codebase Research\n` };
+
+    // Find the research candidate (prefer configured research role, fallback to first available)
+    const researchCandidate = candidates.find((c) => c.role === "research") ?? candidates[0];
+    yield { type: "content", content: `\n### \x1b[35m[research]\x1b[0m ${researchCandidate.model}\n` };
+
+    const researchFindings = await this.councilManager.research(researchCandidate.model, topic, conversationContext);
+    yield { type: "content", content: `${researchFindings}\n` };
+    yield { type: "content", content: `\n> Phase 0: ${((Date.now() - p0Start) / 1000).toFixed(1)}s\n` };
+
+    // Inject research findings into conversation context for subsequent phases
+    const enrichedContext = conversationContext
+      ? `${conversationContext}\n\n---\n\n## Research Findings (Phase 0)\n${researchFindings}`
+      : `## Research Findings (Phase 0)\n${researchFindings}`;
+
     // ── Phase 1: Parallel opening statements ──
     const p1Start = Date.now();
     yield { type: "content", content: "\n## Phase 1 — Opening Analysis\n" };
 
     const openingPromises = candidates.map(({ role, model }) => {
-      const { system, prompt } = this._buildDiscussPrompt("open", {
+      const { system, prompt } = this.councilManager.buildDiscussPrompt("open", {
         speakerRole: role,
         partnerRole: candidates.find((c) => c.role !== role)?.role ?? "colleague",
         topic,
+        conversationContext: enrichedContext,
       });
-      return this._councilGenerate(model, system, prompt)
+      return this.councilManager
+        .generate(model, system, prompt)
         .then((text) => ({ role, model, position: text, error: null as string | null }))
         .catch((err: unknown) => ({
           role,
@@ -2044,16 +1865,21 @@ export class Agent {
     const active: Array<{ role: ModelRole; model: string; position: string }> = [];
 
     for (const o of openings) {
-      yield { type: "content", content: `\n### [${o.role}] ${o.model}\n` };
+      const roleColor = COUNCIL_ROLE_COLORS[o.role] ?? "";
+      yield { type: "content", content: `\n### ${roleColor}[${o.role}]${COUNCIL_COLOR_RESET} ${o.model}\n` };
       if (o.error) {
         yield { type: "content", content: `[Error: ${o.error}]\n` };
       } else {
         active.push({ role: o.role, model: o.model, position: o.position });
-        yield { type: "content", content: o.position + "\n" };
+        const bgColor = COUNCIL_COLOR_BG[o.role] ?? "";
+        yield { type: "content", content: `${bgColor} ${o.role.toUpperCase()} ${COUNCIL_COLOR_RESET} ${o.position}\n` };
       }
     }
 
-    yield { type: "content", content: `\n> Phase 1: ${active.length} participants, ${((Date.now() - p1Start) / 1000).toFixed(1)}s (parallel)\n` };
+    yield {
+      type: "content",
+      content: `\n> Phase 1: ${active.length} participants, ${((Date.now() - p1Start) / 1000).toFixed(1)}s (parallel)\n`,
+    };
 
     if (active.length < 2) {
       yield { type: "content", content: "\nNot enough successful openings for discussion.\n" };
@@ -2064,6 +1890,7 @@ export class Agent {
     // ── Phase 2: Discussion rounds with parallel pair debates ──
     const exchangeLogs: Map<string, string[]> = new Map();
     const pairConverged: Map<string, boolean> = new Map();
+    let runningSummary = "";
 
     for (let round = 1; round <= maxRounds; round++) {
       const p2Start = Date.now();
@@ -2093,36 +1920,56 @@ export class Agent {
             let bResponse: string;
 
             if (round === 1) {
-              const aPrompt = this._buildDiscussPrompt("respond", {
-                speakerRole: a.role, partnerRole: b.role, topic,
-                speakerPosition: a.position, partnerPosition: b.position,
+              const aPrompt = this.councilManager.buildDiscussPrompt("respond", {
+                speakerRole: a.role,
+                partnerRole: b.role,
+                topic,
+                speakerPosition: a.position,
+                partnerPosition: b.position,
+                conversationContext: enrichedContext,
               });
-              aResponse = await this._councilGenerate(a.model, aPrompt.system, aPrompt.prompt);
+              aResponse = await this.councilManager.generate(a.model, aPrompt.system, aPrompt.prompt);
               log.push(`[${a.role}]: ${aResponse}`);
               chunks.push({ label: `[${a.role}] → [${b.role}]`, text: aResponse });
 
-              const bPrompt = this._buildDiscussPrompt("respond", {
-                speakerRole: b.role, partnerRole: a.role, topic,
-                speakerPosition: b.position, partnerPosition: aResponse,
+              const bPrompt = this.councilManager.buildDiscussPrompt("respond", {
+                speakerRole: b.role,
+                partnerRole: a.role,
+                topic,
+                speakerPosition: b.position,
+                partnerPosition: aResponse,
+                conversationContext: enrichedContext,
               });
-              bResponse = await this._councilGenerate(b.model, bPrompt.system, bPrompt.prompt);
+              bResponse = await this.councilManager.generate(b.model, bPrompt.system, bPrompt.prompt);
               log.push(`[${b.role}]: ${bResponse}`);
               chunks.push({ label: `[${b.role}] → [${a.role}]`, text: bResponse });
             } else {
               const historyText = log.join("\n\n");
-              const aPrompt = this._buildDiscussPrompt("followup", {
-                speakerRole: a.role, partnerRole: b.role, topic,
-                partnerPosition: b.position, exchangeHistory: historyText, round,
+              const aPrompt = this.councilManager.buildDiscussPrompt("followup", {
+                speakerRole: a.role,
+                partnerRole: b.role,
+                topic,
+                partnerPosition: b.position,
+                exchangeHistory: historyText,
+                round,
+                conversationContext: enrichedContext,
+                runningSummary,
               });
-              aResponse = await this._councilGenerate(a.model, aPrompt.system, aPrompt.prompt);
+              aResponse = await this.councilManager.generate(a.model, aPrompt.system, aPrompt.prompt, 1024);
               log.push(`[${a.role}] (round ${round}): ${aResponse}`);
               chunks.push({ label: `[${a.role}] → [${b.role}]`, text: aResponse });
 
-              const bPrompt = this._buildDiscussPrompt("followup", {
-                speakerRole: b.role, partnerRole: a.role, topic,
-                partnerPosition: aResponse, exchangeHistory: historyText, round,
+              const bPrompt = this.councilManager.buildDiscussPrompt("followup", {
+                speakerRole: b.role,
+                partnerRole: a.role,
+                topic,
+                partnerPosition: aResponse,
+                exchangeHistory: historyText,
+                round,
+                conversationContext: enrichedContext,
+                runningSummary,
               });
-              bResponse = await this._councilGenerate(b.model, bPrompt.system, bPrompt.prompt);
+              bResponse = await this.councilManager.generate(b.model, bPrompt.system, bPrompt.prompt, 1024);
               log.push(`[${b.role}] (round ${round}): ${bResponse}`);
               chunks.push({ label: `[${b.role}] → [${a.role}]`, text: bResponse });
             }
@@ -2131,26 +1978,34 @@ export class Agent {
             a.position = aResponse;
 
             // Convergence check
-            const convPrompt = this._buildDiscussPrompt("convergence-check", {
-              speakerRole: a.role, partnerRole: b.role, topic,
+            const convPrompt = this.councilManager.buildDiscussPrompt("convergence-check", {
+              speakerRole: a.role,
+              partnerRole: b.role,
+              topic,
               exchangeHistory: log.slice(-4).join("\n\n"),
+              conversationContext: enrichedContext,
             });
             let converged = false;
             let convReason = "";
             try {
-              const raw = await this._councilGenerate(a.model, convPrompt.system, convPrompt.prompt, 256);
+              const raw = await this.councilManager.generate(a.model, convPrompt.system, convPrompt.prompt, 256);
               const match = raw.match(/\{[\s\S]*\}/);
               if (match) {
                 const parsed = JSON.parse(match[0]) as { converged?: boolean; reason?: string };
                 converged = parsed.converged === true;
                 convReason = parsed.reason ?? "";
               }
-            } catch { /* not converged */ }
+            } catch {
+              /* not converged */
+            }
 
             return { key, chunks, converged, convReason, error: null as string | null };
           } catch (err: unknown) {
             return {
-              key, chunks, converged: false, convReason: "",
+              key,
+              chunks,
+              converged: false,
+              convReason: "",
               error: err instanceof Error ? err.message : String(err),
             };
           }
@@ -2161,7 +2016,14 @@ export class Agent {
       let allConverged = true;
       for (const pr of pairResults) {
         for (const chunk of pr.chunks) {
-          yield { type: "content", content: `\n### ${chunk.label}\n${chunk.text}\n` };
+          const labelParts = chunk.label.match(/\[(\w+)\] → \[(\w+)\]/);
+          let coloredLabel = chunk.label;
+          if (labelParts) {
+            const fromColor = COUNCIL_ROLE_COLORS[labelParts[1]] ?? "";
+            const toColor = COUNCIL_ROLE_COLORS[labelParts[2]] ?? "";
+            coloredLabel = `${fromColor}[${labelParts[1]}]${COUNCIL_COLOR_RESET} → ${toColor}[${labelParts[2]}]${COUNCIL_COLOR_RESET}`;
+          }
+          yield { type: "content", content: `\n### ${coloredLabel}\n${chunk.text}\n` };
         }
         if (pr.error) {
           yield { type: "content", content: `[Discussion error: ${pr.error}]\n` };
@@ -2174,12 +2036,32 @@ export class Agent {
         }
       }
 
-      yield { type: "content", content: `\n> Round ${round}: ${((Date.now() - p2Start) / 1000).toFixed(1)}s (${pairs.length} pairs parallel)\n` };
+      yield {
+        type: "content",
+        content: `\n> Round ${round}: ${((Date.now() - p2Start) / 1000).toFixed(1)}s (${pairs.length} pairs parallel)\n`,
+      };
 
       if (allConverged) {
         yield { type: "content", content: `\n> All pairs converged at round ${round}. Moving to synthesis.\n` };
         break;
       }
+
+      // Generate inter-round summary for next round's focus
+      if (round < maxRounds) {
+        try {
+          runningSummary = await this.councilManager.generateRoundSummary(exchangeLogs, topic, round, active[0].model);
+          yield {
+            type: "content",
+            content: `\n> **Discussion state:** ${runningSummary
+              .split("\n")
+              .filter((l) => l.trim())
+              .slice(0, 3)
+              .join(" | ")}\n`,
+          };
+        } catch {
+          // Non-critical — continue without summary
+        }
+      }
     }
 
     // ── Phase 3: Leader synthesis ──
@@ -2187,41 +2069,78 @@ export class Agent {
     yield { type: "content", content: "\n## Phase 3 — Leader Synthesis\n" };
 
     const leaderModelId = getRoleModel("leader") ?? this.modelId;
-    yield { type: "content", content: `\n### [leader] ${leaderModelId}\n` };
+    yield { type: "content", content: `\n### \x1b[32m[leader]\x1b[0m ${leaderModelId}\n` };
 
     const allExchanges = [...exchangeLogs.entries()]
       .map(([pair, log]) => `### Discussion: ${pair}\n${log.join("\n\n")}`)
       .join("\n\n---\n\n");
 
-    const finalPositions = active
-      .map((p) => `**${p.role}** (${p.model}): ${p.position.slice(0, 500)}...`)
-      .join("\n\n");
+    const finalPositions = active.map((p) => `**${p.role}** (${p.model}): ${p.position.slice(0, 500)}...`).join("\n\n");
 
     let synthesisText = "";
     try {
-      synthesisText = await this._councilGenerate(
+      synthesisText = await this.councilManager.generate(
         leaderModelId,
-        "You are the team lead. Multiple specialists just had a structured discussion. Synthesize:\n" +
-        "1. What everyone agreed on — these are your strongest foundations\n" +
-        "2. Where genuine disagreement remains — these are real trade-offs, not resolvable by more discussion\n" +
-        "3. Your decisive recommendation based on the full discussion\n" +
-        "4. Specific next steps and risks to watch\n\n" +
-        "Be decisive. The discussion has happened — now it's time to decide.",
+        "You are the team lead. Multiple specialists just had a structured discussion about a topic.\n\n" +
+          "Output TWO parts separated by the exact line `---READABLE---`:\n\n" +
+          "**Part 1: JSON** — a single JSON object:\n" +
+          "```\n" +
+          '{ "type": "decision"|"action_items"|"plan_update"|"resolve_question",\n' +
+          '  "summary": "1-2 sentence executive summary",\n' +
+          '  "agreed": ["point 1", "point 2"],\n' +
+          '  "tradeoffs": ["trade-off 1"],\n' +
+          '  "recommendation": "Your decisive recommendation",\n' +
+          '  "actionItems": ["step 1", "step 2"],\n' +
+          '  "planUpdate": "paragraph for plan update (only if type=plan_update)",\n' +
+          '  "resolvedQuestion": {"question": "...", "answer": "..."} }\n' +
+          "```\n" +
+          "Choose type: decision (general), action_items (concrete steps), plan_update (modify active plan), resolve_question (answer a specific question).\n\n" +
+          "**Part 2: Human-readable** — after `---READABLE---`, write the synthesis in markdown:\n" +
+          "## AGREED\n## TRADE-OFFS\n## RECOMMENDATION\n## NEXT STEPS\n\n" +
+          "Be decisive. Output Part 1 JSON first, then ---READABLE---, then Part 2.",
         `Topic: ${topic}\n\nFinal positions:\n${finalPositions}\n\nFull discussion:\n${allExchanges}`,
         4096,
       );
-      yield { type: "content", content: synthesisText + "\n" };
+
+      // Display human-readable part
+      const readablePart = synthesisText.includes("---READABLE---")
+        ? synthesisText.split("---READABLE---")[1]?.trim()
+        : synthesisText;
+      yield { type: "content", content: `${readablePart || synthesisText}\n` };
+
+      // Parse structured outcome and execute actions
+      const structuredOutcome = this.councilManager.parseOutcome(synthesisText, topic);
+      if (structuredOutcome) {
+        yield* this.councilManager.executeOutcome(structuredOutcome, topic);
+        if (this.session) {
+          try {
+            appendSystemMessage(this.session.id, `[Council Outcome]\n${JSON.stringify(structuredOutcome)}`);
+          } catch {
+            /* non-critical */
+          }
+        }
+      } else {
+        // Fallback: store text-only outcome (backward compatible)
+        if (this.session) {
+          try {
+            appendSystemMessage(this.session.id, `[Council Outcome]\nTopic: ${topic}\n${synthesisText.slice(0, 2000)}`);
+          } catch {
+            /* non-critical */
+          }
+        }
+      }
     } catch (err: unknown) {
       yield { type: "content", content: `[Synthesis error: ${err instanceof Error ? err.message : err}]\n` };
     }
 
     // ── Stats + Memory ──
-    const totalMs = Date.now() - this._councilStats.startMs;
+    const councilStats = this.councilManager.stats;
+    const totalMs = Date.now() - councilStats.startMs;
     yield {
       type: "content",
       content:
         `\n---\n` +
-        `> Council stats: ${this._councilStats.calls} API calls, ${(totalMs / 1000).toFixed(1)}s total, ` +
+        `> Council stats: ${councilStats.calls} API calls, ${(totalMs / 1000).toFixed(1)}s total, ` +
         `${active.length} participants, synthesis ${((Date.now() - p3Start) / 1000).toFixed(1)}s\n`,
     };
 
@@ -2233,17 +2152,34 @@ export class Agent {
         finalPositions: active.map((a) => ({ role: a.role, position: a.position.slice(0, 1000) })),
         synthesis: synthesisText.slice(0, 2000),
         convergedPairs: [...pairConverged.entries()].filter(([, v]) => v).map(([k]) => k),
-        stats: { calls: this._councilStats.calls, durationMs: totalMs },
+        stats: { calls: councilStats.calls, durationMs: totalMs },
         timestamp: new Date().toISOString(),
       };
       try {
         appendSystemMessage(this.session.id, `[Council Memory] ${JSON.stringify(councilRecord)}`);
-      } catch { /* non-critical */ }
+      } catch {
+        /* non-critical */
+      }
+    }
+
+    // Store council output as assistant message so the conversation history
+    // stays valid (user→assistant alternation required by most APIs).
+    const councilResponse = synthesisText || "[Council completed — see discussion above]";
+    if (userModelMessage) {
+      this.appendCompletedTurn(userModelMessage, [{ role: "assistant", content: councilResponse }]);
     }
+    this.councilManager.setLastSynthesis(councilResponse);
 
     yield { type: "done" };
   }
 
+  // ========================================================================
+  // processMessageBatchTurn — batch API message processing loop.
+  // Body extracted into BatchTurnRunner (Phase 12.5). Thin wrapper preserved
+  // so MessageProcessorDeps' `processMessageBatchTurn` callback continues to
+  // dispatch through `Agent.processMessageBatchTurn` unchanged.
+  // ========================================================================
+
   private async *processMessageBatchTurn(args: {
     userModelMessage: ModelMessage;
     observer?: ProcessMessageObserver;
@@ -2254,226 +2190,65 @@ export class Agent {
     modelInfo: ReturnType<typeof getModelInfo>;
     signal: AbortSignal;
   }): AsyncGenerator<StreamChunk, void, unknown> {
-    const { userModelMessage, observer, provider, subagents, system, runtime, modelInfo, signal } = args;
-    let attemptedOverflowRecovery = false;
-
-    while (true) {
-      this._compactedThisTurn = false;
-      let closeMcp: (() => Promise<void>) | undefined;
-      const turnMessages: ModelMessage[] = [];
-      const totalUsage: ProcessMessageUsage = {};
-
-      try {
-        const settings = attemptedOverflowRecovery
-          ? relaxCompactionSettings(this.getCompactionSettings())
-          : this.getCompactionSettings();
-        if (modelInfo?.contextWindow) {
-          await this.compactForContext(
-            provider,
-            system,
-            modelInfo.contextWindow,
-            signal,
-            settings,
-            attemptedOverflowRecovery,
-          );
-        }
-
-        if (runtime.modelInfo?.responsesOnly) {
-          throw new Error("Batch mode currently supports chat-completions models only.");
-        }
-
-        const baseTools = createTools(this.bash, provider, this.mode, {
-          runTask: (request, abortSignal) => this.runTask(request, combineAbortSignals(signal, abortSignal)),
-          runDelegation: (request, abortSignal) =>
-            this.runDelegation(request, combineAbortSignals(signal, abortSignal)),
-          readDelegation: (id) => this.readDelegation(id),
-          listDelegations: () => this.listDelegations(),
-          scheduleManager: this.schedules,
-          subagents,
-          sendTelegramFile: this.sendTelegramFile ?? undefined,
-          sessionId: this.session?.id ?? undefined,
-        });
-        let tools: ToolSet = runtime.modelInfo?.supportsClientTools === false ? {} : baseTools;
-        if (this.mode === "agent" && runtime.modelInfo?.supportsClientTools !== false) {
-          const mcpBundle = await buildMcpToolSet(loadMcpServers(), {
-          onOAuthRequired: (_serverId, url) => {
-            const urlStr = url.toString();
-            import("child_process").then(({ exec }) => {
-              const cmd = process.platform === "win32" ? `start "" "${urlStr}"`
-                : process.platform === "darwin" ? `open "${urlStr}"`
-                : `xdg-open "${urlStr}"`;
-              exec(cmd);
-            });
-          },
-        });
-          closeMcp = mcpBundle.close;
-          tools = { ...baseTools, ...mcpBundle.tools };
-          if (mcpBundle.errors.length > 0) {
-            yield { type: "content", content: `MCP unavailable: ${mcpBundle.errors.join(" | ")}\n\n` };
-          }
-        }
-
-        const batchTools = runtime.modelInfo?.supportsClientTools === false ? [] : await toolSetToBatchTools(tools);
-        const batch = await createBatch({
-          ...this.getBatchClientOptions(signal),
-          name: buildBatchName("session", this.getSessionId() || runtime.modelId),
-        });
-
-        for (let round = 0; round < this.maxToolRounds; round++) {
-          const stepNumber = round + 1;
-          notifyObserver(observer?.onStepStart, {
-            stepNumber,
-            timestamp: Date.now(),
-          });
-
-          const batchRequestId = `turn-${Date.now()}-${stepNumber}`;
-          await addBatchRequests({
-            ...this.getBatchClientOptions(signal),
-            batchId: batch.batch_id,
-            batchRequests: [
-              {
-                batch_request_id: batchRequestId,
-                batch_request: {
-                  chat_get_completion: buildBatchChatCompletionRequest({
-                    modelId: runtime.modelId,
-                    system,
-                    messages: [...this.messages, ...turnMessages],
-                    temperature: 0.7,
-                    maxOutputTokens: runtime.modelInfo?.supportsMaxOutputTokens === false ? undefined : this.maxTokens,
-                    reasoningEffort: runtime.providerOptions?.xai.reasoningEffort,
-                    tools: batchTools,
-                  }),
-                },
-              },
-            ],
-          });
-
-          const result = await pollBatchRequestResult({
-            ...this.getBatchClientOptions(signal),
-            batchId: batch.batch_id,
-            batchRequestId,
-          });
-          const response = getBatchChatCompletion(result);
-          const choice = response.choices[0];
-          if (!choice) {
-            throw new Error("Batch response did not contain any choices.");
-          }
-
-          const usage = getBatchUsage(response);
-          accumulateUsage(totalUsage, usage);
-          const finishReason = getBatchFinishReason(choice.finish_reason);
-
-          const content = choice.message.content ?? "";
-          if (content) {
-            yield { type: "content", content };
-          }
-
-          const requestMessages = [...this.messages, ...turnMessages];
-          const toolCalls = (choice.message.tool_calls ?? []).map(toLocalToolCall);
-          const assistantMessage = buildAssistantBatchMessage(content, toolCalls);
-          if (assistantMessage) {
-            turnMessages.push(assistantMessage);
-          }
-
-          if (toolCalls.length === 0) {
-            notifyObserver(observer?.onStepFinish, {
-              stepNumber,
-              timestamp: Date.now(),
-              finishReason,
-              usage,
-            });
-            if (hasUsage(totalUsage)) {
-              this.recordUsage(totalUsage, "message", runtime.modelId);
-            }
-            this.appendCompletedTurn(userModelMessage, turnMessages);
-            if (modelInfo?.contextWindow) {
-              await this.postTurnCompact(provider, system, modelInfo.contextWindow, signal);
-            }
-            yield { type: "done" };
-            return;
-          }
-
-          yield { type: "tool_calls", toolCalls };
-
-          const toolParts: ExecutedBatchTool[] = [];
-          for (const toolCall of toolCalls) {
-            notifyObserver(observer?.onToolStart, {
-              toolCall,
-              timestamp: Date.now(),
-            });
-
-            const executed = await this.executeBatchToolCall(tools, toolCall, requestMessages, signal);
-            notifyObserver(observer?.onToolFinish, {
-              toolCall,
-              toolResult: executed.result,
-              timestamp: Date.now(),
-            });
-            yield { type: "tool_result", toolCall, toolResult: executed.result };
-            toolParts.push({
-              toolCall,
-              input: executed.input,
-              toolResult: executed.result,
-            });
-          }
-
-          const toolMessage = buildToolBatchMessage(toolParts);
-          if (toolMessage) {
-            turnMessages.push(toolMessage);
-          }
-          notifyObserver(observer?.onStepFinish, {
-            stepNumber,
-            timestamp: Date.now(),
-            finishReason,
-            usage,
-          });
-        }
-
-        const message = `Error: Reached max tool rounds (${this.maxToolRounds}) in batch mode.`;
-        notifyObserver(observer?.onError, {
-          message,
-          timestamp: Date.now(),
-        });
-        if (hasUsage(totalUsage)) {
-          this.recordUsage(totalUsage, "message", runtime.modelId);
-        }
-        this.appendCompletedTurn(userModelMessage, turnMessages);
-        yield { type: "error", content: message };
-        yield { type: "done" };
-        return;
-      } catch (err: unknown) {
-        if (signal.aborted) {
-          this.discardAbortedTurn(userModelMessage);
-          yield { type: "content", content: "\n\n[Cancelled]" };
-          yield { type: "done" };
-          return;
-        }
-
-        if (!attemptedOverflowRecovery && turnMessages.length === 0 && modelInfo && isContextLimitError(err)) {
-          attemptedOverflowRecovery = true;
-          continue;
-        }
+    const runner = new BatchTurnRunner(this._buildBatchTurnRunnerDeps());
+    yield* runner.run(args);
+  }
 
-        const authError = isAuthenticationError(err);
-        const friendly = humanizeApiError(err);
-        notifyObserver(observer?.onError, {
-          message: friendly,
-          timestamp: Date.now(),
-        });
-        if (hasUsage(totalUsage)) {
-          this.recordUsage(totalUsage, "message", runtime.modelId);
-        }
-        this.appendCompletedTurn(userModelMessage, turnMessages);
-        yield {
-          type: "error",
-          content: friendly,
-          isAuthError: authError,
-        };
-        yield { type: "done" };
-        return;
-      } finally {
-        await closeMcp?.().catch(() => {});
-      }
-    }
+  /**
+   * Build the DI surface BatchTurnRunner (Phase 12.5) needs to reach back
+   * into Agent state without holding a circular reference. Callback names
+   * align with `MessageProcessorDeps` where the signature matches so a
+   * future `TurnRunnerDepsBase` hoist is mechanical. Built per call —
+   * allocation cost is negligible against the batch polling spend.
+   */
+  private _buildBatchTurnRunnerDeps(): BatchTurnRunnerDeps {
+    const self = this;
+    return {
+      get messages() {
+        return self.messages;
+      },
+      get bash() {
+        return self.bash;
+      },
+      get mode() {
+        return self.mode;
+      },
+      get maxToolRounds() {
+        return self.maxToolRounds;
+      },
+      get maxTokens() {
+        return self.maxTokens;
+      },
+      get schedules() {
+        return self.schedules;
+      },
+      get sendTelegramFile() {
+        return self.sendTelegramFile;
+      },
+      getSessionId: () => self.session?.id ?? null,
+      getCompactedThisTurn: () => self._compactedThisTurn,
+      setCompactedThisTurn: (v) => {
+        self._compactedThisTurn = v;
+      },
+      setLastProviderOptionsShape: (shape) => {
+        self._lastProviderOptionsShape = shape;
+      },
+      getBatchClientOptions: (signal) => self.getBatchClientOptions(signal),
+      getCompactionSettings: (cw) => self.getCompactionSettings(cw),
+      compactForContext: (provider, system, cw, signal, settings, overflow) =>
+        self.compactForContext(provider, system, cw, signal, settings, overflow),
+      postTurnCompact: (provider, system, cw, signal) => self.postTurnCompact(provider, system, cw, signal),
+      createTools: (bash, provider, mode, opts) => createTools(bash, provider, mode, opts),
+      runTask: (request, signal) => self.runTask(request, signal),
+      runDelegation: (request, signal) => self.runDelegation(request, signal),
+      readDelegation: (id) => self.readDelegation(id),
+      listDelegations: () => self.listDelegations(),
+      executeBatchToolCall: (tools, toolCall, messages, signal) =>
+        self.executeBatchToolCall(tools, toolCall, messages, signal),
+      appendCompletedTurn: (user, asst) => self.appendCompletedTurn(user, asst),
+      discardAbortedTurn: (user) => self.discardAbortedTurn(user),
+      recordUsage: (usage, source, model) => self.recordUsage(usage, source, model),
+    };
   }
 
   private appendCompletedTurn(userMessage: ModelMessage, newMessages: ModelMessage[]): void {
@@ -2489,6 +2264,28 @@ export class Agent {
       return;
     }
 
+    // Phase A5 — if the user message already has a persisted seq (set by
+    // the write-ahead path), skip re-inserting it. The write-ahead row
+    // will be upserted to status='completed' on the next `appendMessages`
+    // call that sees it via ON CONFLICT, but here we only need to insert
+    // the *new* assistant/tool messages so they get fresh sequence
+    // numbers contiguous with the user row.
+    const existingUserSeq = userIndex >= 0 ? this.messageSeqs[userIndex] : null;
+    if (typeof existingUserSeq === "number") {
+      // User row is already persisted (write-ahead). Insert only the new
+      // assistant/tool messages so they get fresh sequence numbers
+      // contiguous with the user row. Then flip the user row's status
+      // from 'pending' to 'completed' so forensics + replay tooling can
+      // tell the turn settled cleanly.
+      const insertedSeqs = appendMessages(this.session.id, newMessages);
+      markMessageCompleted(this.session.id, existingUserSeq);
+      this.messages.push(...newMessages);
+      this.messageSeqs.push(...insertedSeqs);
+      this.sessionStore.touchSession(this.session.id, this.bash.getCwd());
+      this.session = this.sessionStore.getRequiredSession(this.session.id);
+      return;
+    }
+
     const insertedSeqs = appendMessages(this.session.id, [userMessage, ...newMessages]);
     if (userIndex >= 0) {
       this.messageSeqs[userIndex] = insertedSeqs[0] ?? this.messageSeqs[userIndex];
@@ -2506,844 +2303,212 @@ export class Agent {
     return executeEventHooks(input, this.bash.getCwd(), signal);
   }
 
+  // ========================================================================
+  // processMessage — main streaming turn loop (PIL enrichment, routing, LLM
+  // stream, tool execution, compaction, hooks, observer notifications)
+  // ========================================================================
+
   async *processMessage(
     userMessage: string,
     observer?: ProcessMessageObserver,
     images?: Array<{ path: string; mediaType: string; base64: string }>,
   ): AsyncGenerator<StreamChunk, void, unknown> {
-    // TUI-04: prefer the external AbortContext (from SIGINT handler) so that
-    // Ctrl+C mid-tool-call triggers a single, unified abort across all I/O.
-    // If no external context, fall back to creating a local AbortController.
-    if (this.externalAbortContext) {
-      // Wrap the external signal in a local controller so existing cleanup
-      // paths (this.abortController = null) still work without side-effects.
-      this.abortController = new AbortController();
-      // Forward external abort to the local controller.
-      this.externalAbortContext.signal.addEventListener(
-        "abort",
-        () => {
-          this.abortController?.abort(this.externalAbortContext?.reason());
-        },
-        { once: true },
-      );
-    } else {
-      this.abortController = new AbortController();
-    }
-    const signal = this.abortController.signal;
-    this.emitSubagentStatus(null);
+    const processor = new MessageProcessor(this._buildMessageProcessorDeps());
+    yield* processor.run(userMessage, observer, images);
+  }
+
+  /**
+   * Build the DI surface MessageProcessor (Phase 12.4) needs to reach back
+   * into Agent state without holding a circular reference. Exposes array
+   * references for in-place mutation (messages/messageSeqs) and bound
+   * callbacks for behavior. Built per call — allocation cost is negligible
+   * against the streamText spend.
+   */
+  private _buildMessageProcessorDeps(): MessageProcessorDeps {
+    const self = this;
+    return {
+      get messages() {
+        return self.messages;
+      },
+      get messageSeqs() {
+        return self.messageSeqs;
+      },
+      get session() {
+        return self.session;
+      },
+      get sessionStore() {
+        return self.sessionStore;
+      },
+      get bash() {
+        return self.bash;
+      },
+      get mode() {
+        return self.mode;
+      },
+      get modelId() {
+        return self.modelId;
+      },
+      get providerId() {
+        return self.providerId;
+      },
+      get maxToolRounds() {
+        return self.maxToolRounds;
+      },
+      get batchApi() {
+        return self.batchApi;
+      },
+      get permissionMode() {
+        return self.permissionMode;
+      },
+      get schedules() {
+        return self.schedules;
+      },
+      get sendTelegramFile() {
+        return self.sendTelegramFile;
+      },
+      get externalAbortContext() {
+        return self.externalAbortContext;
+      },
+      get pendingCalls() {
+        return self.pendingCalls;
+      },
+      get councilManager() {
+        return self.councilManager;
+      },
+      get crossTurnDedup() {
+        return self._crossTurnDedup;
+      },
+      get readBudget() {
+        return self._readBudget;
+      },
+      get priorWarningIdsInSession() {
+        return self._priorWarningIdsInSession;
+      },
+      get sessionEEGuidance() {
+        return self._sessionEEGuidance;
+      },
+      get flowReady() {
+        return self._flowReady;
+      },
+      getAbortController: () => self.abortController,
+      setAbortController: (c) => {
+        self.abortController = c;
+      },
+      getSessionStartHookFired: () => self.sessionStartHookFired,
+      setSessionStartHookFired: (v) => {
+        self.sessionStartHookFired = v;
+      },
+      getPlanContext: () => self.planContext,
+      setPlanContext: (v) => {
+        self.planContext = v;
+      },
+      getResumeDigest: () => self._resumeDigest,
+      setResumeDigest: (v) => {
+        self._resumeDigest = v;
+      },
+      getActiveRunId: () => self._activeRunId,
+      getPendingCwdNote: () => self._pendingCwdNote,
+      setPendingCwdNote: (v) => {
+        self._pendingCwdNote = v;
+      },
+      setPilActive: (v) => {
+        self._pilActive = v;
+      },
+      setPilEnrichmentDelta: (n) => {
+        self._pilEnrichmentDelta = n;
+      },
+      setCurrentCallId: (id) => {
+        self._currentCallId = id;
+      },
+      setLastProviderOptionsShape: (shape) => {
+        self._lastProviderOptionsShape = shape;
+      },
+      setLastPromptBreakdown: (b) => {
+        self._lastPromptBreakdown = b;
+      },
+      setCompactedThisTurn: (v) => {
+        self._compactedThisTurn = v;
+      },
+      getCompactedThisTurn: () => self._compactedThisTurn,
+      setTurnUserGoalExcerpt: (v) => {
+        self._turnUserGoalExcerpt = v;
+      },
+      setTurnAssistantReasoning: (v) => {
+        self._turnAssistantReasoning = v;
+      },
+      appendTurnAssistantReasoning: (delta) => {
+        self._turnAssistantReasoning = (self._turnAssistantReasoning + delta).slice(-400);
+      },
+      getTurnAssistantReasoning: () => self._turnAssistantReasoning,
+      setPriorWarningIdsInSession: (s) => {
+        self._priorWarningIdsInSession = s;
+      },
+      setMessages: (m) => {
+        self.messages = m;
+      },
+      requireProvider: () => self.requireProvider(),
+      emitSubagentStatus: (s) => self.emitSubagentStatus(s),
+      fireHook: (input, signal) =>
+        self.fireHook(input as Parameters<Agent["fireHook"]>[0], signal) as ReturnType<
+          MessageProcessorDeps["fireHook"]
+        >,
+      consumeBackgroundNotifications: () => self.consumeBackgroundNotifications(),
+      initOAuthProvider: () => self._initOAuthProvider(),
+      buildRecentTurnsSummary: () => self._buildRecentTurnsSummary(),
+      estimateProjectSize: () => self._estimateProjectSize(),
+      countFilesTouched: () => self._countFilesTouched(),
+      getCompactionSettings: (cw) => self.getCompactionSettings(cw),
+      compactForContext: (provider, system, cw, signal, settings, overflow) =>
+        self.compactForContext(provider, system, cw, signal, settings, overflow),
+      postTurnCompact: (provider, system, cw, signal) => self.postTurnCompact(provider, system, cw, signal),
+      runTask: (request, signal) => self.runTask(request, signal),
+      runDelegation: (request, signal) => self.runDelegation(request, signal),
+      readDelegation: (id) => self.readDelegation(id),
+      listDelegations: () => self.listDelegations(),
+      appendCompletedTurn: (user, asst) => self.appendCompletedTurn(user, asst),
+      discardAbortedTurn: (user) => self.discardAbortedTurn(user),
+      recordUsage: (usage, source, model) => self.recordUsage(usage, source, model),
+      respondToToolApproval: (id, ok) => self.respondToToolApproval(id, ok),
+      runCouncilV2: (msg, opts) => self.runCouncilV2(msg, opts),
+      processMessage: (msg, obs, imgs) => self.processMessage(msg, obs, imgs),
+      processMessageBatchTurn: (args) => self.processMessageBatchTurn(args),
+    };
+  }
 
-    // Ensure flow run is ready before processing (fail-open).
-    await this._flowReady?.catch(() => {});
+  // ========================================================================
+  // processMessage body extracted into MessageProcessor (Phase 12.4).
+  // The single original implementation now lives in
+  // `src/orchestrator/message-processor.ts`. The thin wrapper above is the
+  // only entry point.
+  // ========================================================================
 
-    if (!this.sessionStartHookFired) {
-      this.sessionStartHookFired = true;
-      const isResume = this.messages.length > 0;
-      const sessionStartInput: SessionStartHookInput = {
-        hook_event_name: "SessionStart",
-        source: isResume ? "resume" : "startup",
-        session_id: this.session?.id,
-        cwd: this.bash.getCwd(),
-      };
-      await this.fireHook(sessionStartInput, signal).catch(() => {});
-    }
+  // ========================================================================
+  // Private helper methods — summary, estimation, verify
+  // ========================================================================
 
-    const promptInput: UserPromptSubmitHookInput = {
-      hook_event_name: "UserPromptSubmit",
-      user_prompt: userMessage,
-      session_id: this.session?.id,
-      cwd: this.bash.getCwd(),
-    };
-    await this.fireHook(promptInput, signal).catch(() => {});
-
-    await this.consumeBackgroundNotifications();
-
-    const _debugOn = isDebugEnabled();
-    const _debugSteps: PipelineStep[] = [];
-    const _debugTurnId = this.messages.filter((m) => m.role === "user").length + 1;
-
-    // PIL: enrich prompt before pushing to messages (D-01, D-03, D-04)
-    // Promise.race timeout of 200ms is inside runPipeline — fail-open guaranteed
-    const _pilStart = Date.now();
-    const pilCtx = await runPipeline(userMessage, {
-      resumeDigest: this._resumeDigest,
-      activeRunId: this._activeRunId,
-    }).catch(() => ({
-      raw: userMessage,
-      enriched: userMessage,
-      taskType: null,
-      domain: null,
-      confidence: 0,
-      outputStyle: null,
-      tokenBudget: 500,
-      metrics: null,
-      layers: [],
-      gsdPhase: null,
-      activeRunId: null,
-    }));
-    const enrichedMessage = pilCtx.enriched;
-    this._pilActive = pilCtx.taskType !== null;
-    this._pilEnrichmentDelta =
-      pilCtx.metrics?.estimatedTokensSaved ?? Math.round((enrichedMessage.length - userMessage.length) / 4);
-
-    if (_debugOn) {
-      const appliedLayers = pilCtx.layers?.filter((l) => l.applied).map((l) => l.name) ?? [];
-      _debugSteps.push({
-        name: "PIL Pipeline",
-        duration_ms: Date.now() - _pilStart,
-        input_summary: `"${userMessage.slice(0, 60)}${userMessage.length > 60 ? "..." : ""}"`,
-        output_summary: `task=${pilCtx.taskType ?? "none"} domain=${pilCtx.domain ?? "none"} layers=[${appliedLayers.join(",")}]`,
-        tokens_saved: this._pilEnrichmentDelta > 0 ? this._pilEnrichmentDelta : undefined,
-      });
+  private _buildRecentTurnsSummary(): string | null {
+    if (this.messages.length < 2) return null;
+    const recent = this.messages.slice(-6);
+    const parts: string[] = [];
+    for (const msg of recent) {
+      if (msg.role !== "user" && msg.role !== "assistant") continue;
+      const text =
+        typeof msg.content === "string"
+          ? msg.content
+          : Array.isArray(msg.content)
+            ? msg.content
+                .filter((p: { type: string }) => p.type === "text")
+                .map((p: { type: string; text?: string }) => p.text ?? "")
+                .join("")
+            : "";
+      if (!text) continue;
+      const snippet = text.length > 80 ? `${text.slice(0, 77)}...` : text;
+      parts.push(`[${msg.role}]: ${snippet}`);
     }
+    return parts.length > 0 ? parts.join(" | ") : null;
+  }
 
-    // ROUTE-11: Per-turn model routing via decide() — picks cheapest capable model
-    const turnStartMs = Date.now();
-    let turnModelId = this.modelId;
-    let taskHash: string | null = null;
-    const _routeStart = Date.now();
-    try {
-      const { decide } = await import("../router/decide.js");
-      const routeDecision = await decide(userMessage, {
-        tenantId: "local",
-        cwd: this.bash.getCwd(),
-        defaultModel: this.modelId,
-        defaultProvider: this.providerId,
-        pil: {
-          domain: pilCtx.domain,
-          taskType: pilCtx.taskType,
-          confidence: pilCtx.confidence,
-          gsdPhase: pilCtx.gsdPhase ?? null,
-          activeRunId: pilCtx.activeRunId ?? null,
-          recentTurnsSummary: this._buildRecentTurnsSummary(),
-          projectSize: this._estimateProjectSize(),
-          filesTouched: this._countFilesTouched(),
-          mode: this.mode,
-        },
-      });
-      if (routeDecision.model && routeDecision.model !== "HALT") {
-        turnModelId = routeDecision.model;
-      }
-      taskHash = routeDecision.taskHash ?? null;
-      // Update status bar with router switch info
-      if (turnModelId !== this.modelId) {
-        statusBarStore.setState({ routed_from: this.modelId, model: turnModelId });
-      }
-      if (_debugOn) {
-        _debugSteps.push({
-          name: "Router",
-          duration_ms: Date.now() - _routeStart,
-          input_summary: `default=${this.modelId}`,
-          output_summary: turnModelId !== this.modelId ? `routed→${turnModelId}` : `kept ${turnModelId}`,
-        });
-      }
-    } catch {
-      // Router unavailable — use session default model
-      const eeRoute = await routeModel(userMessage, {}, "claude").catch(() => null);
-      taskHash = eeRoute?.taskHash ?? null;
-    }
-
-    // Re-detect provider if router picked a model from a different provider
-    const turnProviderId = detectProviderForModel(turnModelId);
-    let turnProvider: LegacyProvider;
-    if (turnProviderId !== this.providerId) {
-      const turnKey = await loadKeyForProvider(turnProviderId).catch(() => null);
-      if (turnKey) {
-        turnProvider = createProvider(turnProviderId, turnKey);
-      } else {
-        turnModelId = this.modelId;
-        turnProvider = this.requireProvider();
-      }
-    } else {
-      turnProvider = this.requireProvider();
-    }
-
-    let userModelMessage: ModelMessage;
-    if (images?.length) {
-      const parts: Array<{ type: "text"; text: string } | { type: "image"; image: string; mediaType: string }> = [
-        { type: "text", text: enrichedMessage },
-      ];
-      for (const img of images) {
-        parts.push({ type: "image", image: img.base64, mediaType: img.mediaType });
-      }
-      userModelMessage = { role: "user", content: parts };
-    } else {
-      userModelMessage = { role: "user", content: enrichedMessage };
-    }
-
-    // Vision proxy: convert images to text for models that don't support vision
-    if (images?.length && needsVisionProxy(turnModelId)) {
-      try {
-        const proxyResult = await proxyVision([userModelMessage], turnModelId, signal);
-        if (proxyResult.proxied) {
-          userModelMessage = proxyResult.messages[0];
-          yield { type: "content", content: `[Vision proxy: ${proxyResult.imageCount} image(s) → ${turnModelId} via SiliconFlow]\n` };
-        }
-      } catch {
-        yield { type: "content", content: "[Vision proxy: failed, images dropped]\n" };
-        userModelMessage = { role: "user", content: enrichedMessage };
-      }
-    }
-
-    this.messages.push(userModelMessage);
-    this.messageSeqs.push(null);
-
-    const provider = turnProvider;
-    const subagents = loadValidSubAgents();
-    const _pilResponseTools = getResponseToolSet(pilCtx);
-    const _hasResponseTools = Object.keys(_pilResponseTools).length > 0;
-    const systemParts = buildSystemPromptParts(
-      this.bash.getCwd(),
-      this.mode,
-      this.bash.getSandboxMode(),
-      this.planContext,
-      subagents,
-      this.bash.getSandboxSettings(),
-      this.providerId,
-    );
-    const system = applyModelConstraints(
-      applyPilSuffix(
-        `${systemParts.staticPrefix}${systemParts.dynamicSuffix}`,
-        pilCtx,
-        _hasResponseTools,
-      ),
-      turnModelId,
-    );
-    const runtime = resolveModelRuntime(provider, turnModelId);
-    const modelInfo = runtime.modelInfo;
-    this.planContext = null;
-    let attemptedOverflowRecovery = false;
-
-    // Auto-council: for plan/analyze tasks with high confidence, run multi-model debate
-    const autoCouncilTypes = new Set(["plan", "analyze"]);
-    const councilRoles = getRoleModels();
-    const configuredRoleCount = Object.values(councilRoles).filter(Boolean).length;
-    if (
-      isAutoCouncilEnabled() &&
-      pilCtx.taskType &&
-      autoCouncilTypes.has(pilCtx.taskType) &&
-      pilCtx.confidence >= 0.75 &&
-      configuredRoleCount >= 2
-    ) {
-      yield { type: "content", content: `\n[Auto-council triggered: ${pilCtx.taskType} task detected with ${(pilCtx.confidence * 100).toFixed(0)}% confidence]\n` };
-      yield* this.runCouncilRound(userMessage, observer);
-      return;
-    }
-
-    if (this.batchApi) {
-      try {
-        yield* this.processMessageBatchTurn({
-          userModelMessage,
-          observer,
-          provider,
-          subagents,
-          system,
-          runtime,
-          modelInfo,
-          signal,
-        });
-      } finally {
-        if (this.abortController?.signal === signal) {
-          this.abortController = null;
-        }
-      }
-      return;
-    }
-
-    try {
-      while (true) {
-        this._compactedThisTurn = false;
-        let assistantText = "";
-        let reasoningPreview = "";
-        let encryptedReasoningHidden = false;
-        let streamOk = false;
-        let closeMcp: (() => Promise<void>) | undefined;
-        let stepNumber = -1;
-        const activeToolCalls: ToolCall[] = [];
-
-        try {
-          const settings = attemptedOverflowRecovery
-            ? relaxCompactionSettings(this.getCompactionSettings())
-            : this.getCompactionSettings();
-          if (modelInfo?.contextWindow) {
-            await this.compactForContext(
-              provider,
-              system,
-              modelInfo.contextWindow,
-              signal,
-              settings,
-              attemptedOverflowRecovery,
-            );
-          }
-
-          const baseTools = createTools(this.bash, provider, this.mode, {
-            runTask: (request, abortSignal) => this.runTask(request, combineAbortSignals(signal, abortSignal)),
-            runDelegation: (request, abortSignal) =>
-              this.runDelegation(request, combineAbortSignals(signal, abortSignal)),
-            readDelegation: (id) => this.readDelegation(id),
-            listDelegations: () => this.listDelegations(),
-            scheduleManager: this.schedules,
-            subagents,
-            sendTelegramFile: this.sendTelegramFile ?? undefined,
-            sessionId: this.session?.id ?? undefined,
-          });
-          let tools: ToolSet = runtime.modelInfo?.supportsClientTools === false ? {} : baseTools;
-          if (this.mode === "agent" && runtime.modelInfo?.supportsClientTools !== false) {
-            const mcpBundle = await buildMcpToolSet(loadMcpServers(), {
-          onOAuthRequired: (_serverId, url) => {
-            const urlStr = url.toString();
-            import("child_process").then(({ exec }) => {
-              const cmd = process.platform === "win32" ? `start "" "${urlStr}"`
-                : process.platform === "darwin" ? `open "${urlStr}"`
-                : `xdg-open "${urlStr}"`;
-              exec(cmd);
-            });
-          },
-        });
-            closeMcp = mcpBundle.close;
-            tools = { ...baseTools, ...mcpBundle.tools };
-            captureToolSchemas(tools);
-            if (mcpBundle.errors.length > 0) {
-              yield { type: "content", content: `MCP unavailable: ${mcpBundle.errors.join(" | ")}\n\n` };
-            }
-          }
-
-          // PIL response tools: inject structured output tool when taskType detected
-          if (_hasResponseTools && runtime.modelInfo?.supportsClientTools !== false) {
-            tools = { ...tools, ..._pilResponseTools };
-            captureToolSchemas(_pilResponseTools);
-          }
-          let responseToolCalled = false;
-
-          // Build provider options, optionally adding reasoning budget for capable models
-          const baseProviderOpts = runtime.providerOptions ?? {};
-          const providerOpts = runtime.modelInfo?.reasoning
-            ? {
-                ...baseProviderOpts,
-                anthropic: {
-                  ...(baseProviderOpts.anthropic ?? {}),
-                  thinking: {
-                    type: "enabled" as const,
-                    budgetTokens:
-                      taskTypeToReasoningEffort(pilCtx.taskType) === "high"
-                        ? 32_768
-                        : taskTypeToReasoningEffort(pilCtx.taskType) === "medium"
-                          ? 8_192
-                          : 2_048,
-                  },
-                },
-              }
-            : baseProviderOpts;
-          // Use catalog's thinkingType field instead of regex matching
-          const thinkingModelInfo = getModelInfo(runtime.modelId);
-          if (providerOpts.anthropic?.thinking?.type === "enabled" && thinkingModelInfo?.thinkingType === "adaptive") {
-            providerOpts.anthropic.thinking = { type: "adaptive" as any };
-          }
-
-          // Multi-provider caching: OpenAI stored completions, DeepSeek prefix cache
-          const turnProvider = runtime.modelInfo?.provider ?? this.providerId;
-          if (turnProvider === "openai") {
-            providerOpts.openai = { ...(providerOpts.openai ?? {}), store: true };
-          }
-
-          const systemForModel = runtime.modelId.startsWith("claude")
-            ? [
-                { role: "system" as const, content: systemParts.staticPrefix, providerOptions: { anthropic: { cacheControl: { type: "ephemeral" as const } } } },
-                { role: "system" as const, content: system.slice(systemParts.staticPrefix.length) },
-              ]
-            : system;
-
-          const result = streamText({
-            model: runtime.model,
-            system: systemForModel,
-            messages: this.messages,
-            tools,
-            toolChoice:
-              _hasResponseTools && runtime.modelInfo?.supportsClientTools !== false
-                ? "auto"
-                : undefined,
-            stopWhen: stepCountIs(this.maxToolRounds),
-            maxRetries: 0,
-            abortSignal: signal,
-            temperature: 0.7,
-            ...(runtime.modelInfo?.supportsMaxOutputTokens === false ? {} : { maxOutputTokens: taskTypeToMaxTokens(pilCtx.taskType) }),
-            ...(Object.keys(providerOpts).length > 0 ? { providerOptions: providerOpts } : {}),
-            experimental_onStepStart: (event: unknown) => {
-              stepNumber = getStepNumber(event, stepNumber + 1);
-              notifyObserver(observer?.onStepStart, {
-                stepNumber,
-                timestamp: Date.now(),
-              });
-            },
-            onStepFinish: (event: unknown) => {
-              const currentStep = getStepNumber(event, Math.max(stepNumber, 0));
-              stepNumber = Math.max(stepNumber, currentStep);
-              const stepUsage = getUsage(event);
-              notifyObserver(observer?.onStepFinish, {
-                stepNumber: currentStep,
-                timestamp: Date.now(),
-                finishReason: getFinishReason(event),
-                usage: stepUsage,
-              });
-              // Realtime status bar update per step
-              if (stepUsage.inputTokens || stepUsage.outputTokens) {
-                this.recordUsage(stepUsage, "message", runtime.modelId);
-              }
-            },
-            onFinish: ({ providerMetadata }) => {
-              // Cache metrics only available in onFinish (Anthropic provider metadata)
-              const anthropicMeta = providerMetadata?.anthropic as Record<string, unknown> | undefined;
-              const cacheReadTokens = asNumber(anthropicMeta?.cacheReadInputTokens) ?? 0;
-              const cacheCreationTokens = asNumber(anthropicMeta?.cacheCreationInputTokens) ?? 0;
-              if (cacheReadTokens || cacheCreationTokens) {
-                const prev = statusBarStore.getState();
-                statusBarStore.setState({
-                  cache_read_tokens: (prev.cache_read_tokens ?? 0) + cacheReadTokens,
-                  cache_creation_tokens: (prev.cache_creation_tokens ?? 0) + cacheCreationTokens,
-                });
-              }
-            },
-          });
-
-          for await (const part of result.fullStream) {
-            if (signal.aborted) {
-              yield { type: "content", content: "\n\n[Cancelled]" };
-              break;
-            }
-
-            switch (part.type) {
-              case "text-delta":
-                assistantText += part.text;
-                yield { type: "content", content: part.text };
-                break;
-
-              case "reasoning-delta":
-                reasoningPreview = `${reasoningPreview}${part.text}`.slice(-256);
-                if (containsEncryptedReasoning(reasoningPreview)) {
-                  if (!encryptedReasoningHidden) {
-                    encryptedReasoningHidden = true;
-                    yield { type: "reasoning", content: "[Encrypted reasoning hidden]" };
-                  }
-                  break;
-                }
-                yield { type: "reasoning", content: part.text };
-                break;
-
-              case "tool-call": {
-                const tc = toToolCall(part);
-                activeToolCalls.push(tc);
-
-                // EE PreToolUse hook: fire intercept before tool execution.
-                {
-                  const preInput: PreToolUseHookInput = {
-                    hook_event_name: "PreToolUse",
-                    tool_name: tc.function.name,
-                    tool_input: JSON.parse(tc.function.arguments || "{}"),
-                    session_id: this.session?.id,
-                    cwd: this.bash.getCwd(),
-                  };
-                  const preResult = await this.fireHook(preInput, signal).catch(() => ({
-                    blocked: false,
-                    blockingErrors: [],
-                    preventContinuation: false,
-                    additionalContexts: [] as string[],
-                    results: [],
-                  }));
-                  for (const ctx of preResult.additionalContexts ?? []) {
-                    yield { type: "content", content: `${ctx}\n` };
-                  }
-                }
-
-                // Pitfall 9: log the pending call so reconcile() can recover any
-                // staged .tmp files if the process is killed before tool-result.
-                if (this.pendingCalls) {
-                  const turnId = this.session?.id ?? "anon";
-                  const callId = stableCallId(turnId, tc.function.name, tc.function.arguments);
-                  // Phase 0: predictStagedPaths = [] for all tools (refined in Phase 1).
-                  void this.pendingCalls.begin({ call_id: callId, tool_name: tc.function.name }).catch(() => {});
-                  // Attach callId to the ToolCall so tool-result can end it.
-                  (tc as ToolCall & { _pendingCallId?: string })._pendingCallId = callId;
-                }
-                notifyObserver(observer?.onToolStart, {
-                  toolCall: tc,
-                  timestamp: Date.now(),
-                });
-                yield { type: "tool_calls", toolCalls: [tc] };
-                break;
-              }
-
-              case "tool-result": {
-                const tc: ToolCall = {
-                  id: part.toolCallId,
-                  type: "function",
-                  function: { name: part.toolName, arguments: JSON.stringify(part.input ?? {}) },
-                };
-                const tr = toToolResult(part.output);
-                // Pitfall 9: settle the pending call log entry.
-                if (this.pendingCalls) {
-                  const pending = activeToolCalls.find((t) => t.id === part.toolCallId);
-                  const callId = (pending as ToolCall & { _pendingCallId?: string })?._pendingCallId;
-                  if (callId) {
-                    const endStatus = signal.aborted ? "aborted" : "settled";
-                    void this.pendingCalls.end(callId, endStatus).catch(() => {});
-                  }
-                }
-                // EE PostToolUse hook: fire-and-forget after tool execution.
-                {
-                  const postInput: PostToolUseHookInput = {
-                    hook_event_name: "PostToolUse",
-                    tool_name: part.toolName,
-                    tool_input: (part.input as Record<string, unknown>) ?? {},
-                    tool_output: typeof tr.output === "string" ? { text: tr.output } : ((tr.output as unknown as Record<string, unknown>) ?? {}),
-                    session_id: this.session?.id,
-                    cwd: this.bash.getCwd(),
-                  };
-                  await this.fireHook(postInput, signal).catch(() => {});
-                }
-
-                // Response tool: yield as structured_response instead of tool_result
-                if (isResponseTool(part.toolName)) {
-                  responseToolCalled = true;
-                  const taskType = getResponseTaskType(part.toolName);
-                  yield {
-                    type: "structured_response" as StreamChunk["type"],
-                    structuredResponse: {
-                      taskType: taskType ?? part.toolName,
-                      data: (part.output ?? {}) as Record<string, unknown>,
-                    },
-                  };
-                  notifyObserver(observer?.onToolFinish, { toolCall: tc, toolResult: tr, timestamp: Date.now() });
-                  break;
-                }
-
-                notifyObserver(observer?.onToolFinish, {
-                  toolCall: tc,
-                  toolResult: tr,
-                  timestamp: Date.now(),
-                });
-                yield { type: "tool_result", toolCall: tc, toolResult: tr };
-                break;
-              }
-
-              case "tool-approval-request": {
-                const approvalPart = part as unknown as {
-                  approvalId: string;
-                  toolCall: { toolCallId: string; toolName: string; input: unknown };
-                };
-                const toolCallId = approvalPart.toolCall?.toolCallId ?? "";
-                const pendingTc = activeToolCalls.find((tc) => tc.id === toolCallId);
-                const tcForChunk = pendingTc ?? {
-                  id: toolCallId,
-                  type: "function" as const,
-                  function: {
-                    name: approvalPart.toolCall?.toolName ?? "paid_request",
-                    arguments: JSON.stringify(approvalPart.toolCall?.input ?? {}),
-                  },
-                };
-
-                // Payment pre-check disabled — Stripe billing pending.
-                const paymentPrecheck: import("../types/index").PaymentPrecheck | undefined = undefined;
-
-                // Plan 03-01: check permission mode before yielding approval request to UI.
-                // auto-edit auto-approves file ops; yolo auto-approves everything.
-                const toolName = approvalPart.toolCall?.toolName ?? "";
-                if (!toolNeedsApproval(toolName, this.permissionMode)) {
-                  // Auto-approve: respond directly without surfacing to UI.
-                  this.respondToToolApproval(approvalPart.approvalId, true);
-                  break;
-                }
-
-                yield {
-                  type: "tool_approval_request",
-                  approvalId: approvalPart.approvalId,
-                  toolCall: tcForChunk,
-                  paymentPrecheck,
-                };
-                break;
-              }
-
-              case "error": {
-                const authError = isAuthenticationError(part.error);
-                const friendly = humanizeApiError(part.error);
-                notifyObserver(observer?.onError, {
-                  message: friendly,
-                  timestamp: Date.now(),
-                });
-                yield {
-                  type: "error",
-                  content: friendly,
-                  isAuthError: authError,
-                };
-                break;
-              }
-
-              case "abort":
-                yield { type: "content", content: "\n\n[Cancelled]" };
-                break;
-            }
-          }
-
-          if (signal.aborted) {
-            this.discardAbortedTurn(userModelMessage);
-            yield { type: "done" };
-            return;
-          }
-
-          try {
-            const response = await result.response;
-            if (!signal.aborted) {
-              this.appendCompletedTurn(userModelMessage, sanitizeModelMessages(response.messages));
-              streamOk = true;
-            }
-          } catch (responseError: unknown) {
-            if (
-              !attemptedOverflowRecovery &&
-              !assistantText.trim() &&
-              modelInfo &&
-              isContextLimitError(responseError)
-            ) {
-              attemptedOverflowRecovery = true;
-              continue;
-            }
-          }
-
-          if (signal.aborted) {
-            this.discardAbortedTurn(userModelMessage);
-            yield { type: "done" };
-            return;
-          }
-
-          if (!streamOk && assistantText.trim()) {
-            this.appendCompletedTurn(userModelMessage, [{ role: "assistant", content: assistantText }]);
-          }
-
-          // Fallback: model responded in text despite tool_choice=required
-          // Attempt JSON extraction from assistant text → yield as structured_response
-          if (_hasResponseTools && !responseToolCalled && pilCtx.taskType && assistantText.trim()) {
-            try {
-              const jsonMatch = assistantText.match(/\{[\s\S]*\}/);
-              if (jsonMatch) {
-                const parsed = JSON.parse(jsonMatch[0]) as Record<string, unknown>;
-                if (Object.keys(parsed).length > 0) {
-                  responseToolCalled = true;
-                  yield {
-                    type: "structured_response" as StreamChunk["type"],
-                    structuredResponse: {
-                      taskType: pilCtx.taskType,
-                      data: parsed,
-                    },
-                  };
-                }
-              }
-            } catch {
-              // JSON parse failed — leave as text-fallback
-            }
-          }
-
-          // Track PIL output mode for /optimize metrics
-          {
-            const { setLastOutputMode } = await import("../pil/store.js");
-            if (!_hasResponseTools) setLastOutputMode("conversational");
-            else if (responseToolCalled) setLastOutputMode("structured");
-            else setLastOutputMode("text-fallback");
-          }
-
-          // ROUTE-11: Fire routeFeedback after turn completes (success path).
-          // Must come AFTER posttool calls (posttool fires during tool-result processing above).
-          // Fire-and-forget — no await. Skipped when taskHash is null (bridge absent).
-          {
-            const turnDuration = Date.now() - turnStartMs;
-            if (taskHash) {
-              const tier = taskTypeToTier(pilCtx.taskType);
-              void routeFeedback(
-                taskHash,
-                tier,
-                runtime.modelId,
-                "success", // Phase 6: all normal completions = 'success'
-                0, // retryCount: 0 for first attempt
-                turnDuration,
-              );
-            }
-            // HTTP path: also report via router store taskHash (covers warm/cold EE routes)
-            const storeHash = routerStore.getState().taskHash;
-            if (storeHash) {
-              reportRouteOutcome(storeHash, "success", turnDuration);
-            }
-          }
-
-          const stopInput: StopHookInput = {
-            hook_event_name: "Stop",
-            session_id: this.session?.id,
-            cwd: this.bash.getCwd(),
-          };
-          await this.fireHook(stopInput, signal).catch(() => {});
-
-          // Debug trace: emit pipeline summary
-          if (_debugOn) {
-            const sb = statusBarStore.getState();
-            const defaultInfo = getModelInfo(this.modelId);
-            const usedInfo = getModelInfo(turnModelId);
-            const routerSaved = (defaultInfo && usedInfo && defaultInfo.outputPrice > usedInfo.outputPrice)
-              ? (sb.out_tokens * (defaultInfo.outputPrice - usedInfo.outputPrice)) / 1_000_000
-              : 0;
-            const cacheSaved = sb.cache_read_tokens > 0 && defaultInfo
-              ? (sb.cache_read_tokens * (defaultInfo.inputPrice - (defaultInfo.cachedInputPrice ?? defaultInfo.inputPrice * 0.1))) / 1_000_000
-              : 0;
-            const trace: TurnTrace = {
-              turn_id: _debugTurnId,
-              timestamp: turnStartMs,
-              raw_prompt: userMessage,
-              steps: _debugSteps,
-              model_requested: this.modelId,
-              model_used: turnModelId,
-              routed: turnModelId !== this.modelId,
-              input_tokens: sb.in_tokens,
-              output_tokens: sb.out_tokens,
-              cache_read_tokens: sb.cache_read_tokens,
-              cost_usd: sb.session_usd,
-              estimated_savings: {
-                pil_tokens_saved: this._pilEnrichmentDelta > 0 ? this._pilEnrichmentDelta : 0,
-                cache_tokens_saved: sb.cache_read_tokens,
-                router_cost_saved_usd: routerSaved,
-                total_tokens_saved: (this._pilEnrichmentDelta > 0 ? this._pilEnrichmentDelta : 0) + sb.cache_read_tokens,
-                total_cost_saved_usd: routerSaved + cacheSaved,
-              },
-            };
-            recordTurnTrace(trace);
-
-            const traceLines: string[] = [];
-            traceLines.push("\n┌─ Pipeline Trace ─────────────────────────");
-            for (const step of _debugSteps) {
-              const dur = step.duration_ms < 1 ? "<1ms" : `${step.duration_ms}ms`;
-              const saved = step.tokens_saved ? ` (saved ~${step.tokens_saved} tok)` : "";
-              traceLines.push(`│ ▸ ${step.name} [${dur}]${saved}`);
-              traceLines.push(`│   ${step.output_summary}`);
-            }
-            const routeLabel = trace.routed ? `${trace.model_requested}→${trace.model_used}` : trace.model_used;
-            traceLines.push(`│ Model: ${routeLabel} | ↑${sb.in_tokens} ↓${sb.out_tokens} | $${sb.session_usd.toFixed(4)}`);
-            if (trace.estimated_savings.total_cost_saved_usd > 0) {
-              traceLines.push(`│ Savings: ~${trace.estimated_savings.total_tokens_saved} tok, ~$${trace.estimated_savings.total_cost_saved_usd.toFixed(4)}`);
-            }
-            traceLines.push("└──────────────────────────────────────────\n");
-            yield { type: "content", content: traceLines.join("\n") };
-          }
-
-          if (modelInfo?.contextWindow) {
-            await this.postTurnCompact(provider, system, modelInfo.contextWindow, signal);
-          }
-          yield { type: "done" };
-          return;
-        } catch (err: unknown) {
-          if (signal.aborted) {
-            this.discardAbortedTurn(userModelMessage);
-            // ROUTE-11: Fire routeFeedback for cancelled turns (abort path).
-            // Fire-and-forget — no await. Skipped when taskHash is null.
-            {
-              const turnDuration = Date.now() - turnStartMs;
-              if (taskHash) {
-                const tier = taskTypeToTier(pilCtx.taskType);
-                void routeFeedback(
-                  taskHash,
-                  tier,
-                  runtime.modelId,
-                  "cancelled",
-                  0,
-                  turnDuration,
-                );
-              }
-              const storeHash = routerStore.getState().taskHash;
-              if (storeHash) {
-                reportRouteOutcome(storeHash, "cancelled", turnDuration);
-              }
-            }
-            yield { type: "content", content: "\n\n[Cancelled]" };
-            yield { type: "done" };
-            return;
-          }
-
-          if (!attemptedOverflowRecovery && !assistantText.trim() && modelInfo && isContextLimitError(err)) {
-            attemptedOverflowRecovery = true;
-            continue;
-          }
-
-          const authError = isAuthenticationError(err);
-          const friendly = humanizeApiError(err);
-          notifyObserver(observer?.onError, {
-            message: friendly,
-            timestamp: Date.now(),
-          });
-          yield {
-            type: "error",
-            content: friendly,
-            isAuthError: authError,
-          };
-          if (assistantText.trim()) {
-            this.appendCompletedTurn(userModelMessage, [{ role: "assistant", content: assistantText }]);
-          }
-
-          // ROUTE-11: Fire routeFeedback for failed turns (error path).
-          // Must come AFTER posttool calls. Fire-and-forget — no await.
-          {
-            const turnDuration = Date.now() - turnStartMs;
-            if (taskHash) {
-              const tier = taskTypeToTier(pilCtx.taskType);
-              void routeFeedback(
-                taskHash,
-                tier,
-                runtime.modelId,
-                "fail",
-                0,
-                turnDuration,
-              );
-            }
-            const storeHash = routerStore.getState().taskHash;
-            if (storeHash) {
-              reportRouteOutcome(storeHash, "fail", turnDuration);
-            }
-          }
-
-          const stopFailureInput: StopFailureHookInput = {
-            hook_event_name: "StopFailure",
-            error: friendly,
-            session_id: this.session?.id,
-            cwd: this.bash.getCwd(),
-          };
-          await this.fireHook(stopFailureInput, signal).catch(() => {});
-
-          if (modelInfo?.contextWindow) {
-            await this.postTurnCompact(provider, system, modelInfo.contextWindow, signal);
-          }
-          yield { type: "done" };
-          return;
-        } finally {
-          await closeMcp?.().catch(() => {});
-        }
-      }
-    } finally {
-      if (this.abortController?.signal === signal) {
-        this.abortController = null;
-      }
-    }
-  }
-
-  private _buildRecentTurnsSummary(): string | null {
-    if (this.messages.length < 2) return null;
-    const recent = this.messages.slice(-6);
-    const parts: string[] = [];
-    for (const msg of recent) {
-      if (msg.role !== "user" && msg.role !== "assistant") continue;
-      const text = typeof msg.content === "string"
-        ? msg.content
-        : Array.isArray(msg.content)
-          ? msg.content.filter((p: { type: string }) => p.type === "text").map((p: { type: string; text?: string }) => p.text ?? "").join("")
-          : "";
-      if (!text) continue;
-      const snippet = text.length > 80 ? `${text.slice(0, 77)}...` : text;
-      parts.push(`[${msg.role}]: ${snippet}`);
-    }
-    return parts.length > 0 ? parts.join(" | ") : null;
-  }
-
-  private _estimateProjectSize(): "small" | "medium" | "large" | null {
+  private _estimateProjectSize(): "small" | "medium" | "large" | null {
     try {
       const fs = require("fs");
       const path = require("path");
@@ -3390,6 +2555,45 @@ export class Agent {
     return this.provider;
   }
 
+  /**
+   * One-shot async init: upgrades the OpenAI provider to use OAuth tokens when
+   * stored tokens are available and no explicit API key was supplied by the user.
+   * Called at the start of processMessage so the first real LLM call benefits
+   * from OAuth without requiring a sync constructor change.
+   *
+   * Idempotent: skips on second call and for non-OpenAI providers.
+   * Fail-open: any error leaves the existing provider untouched.
+   */
+  private async _initOAuthProvider(): Promise<void> {
+    if (this._oauthInitDone) return;
+    this._oauthInitDone = true;
+
+    // Only upgrade when there is no explicit API key — OAuth is an alternative
+    // auth path, not an override when the user deliberately passed a key.
+    // The boot wizard in src/index.ts uses the literal "oauth" as a sentinel
+    // to signal "no API key but OAuth tokens exist", so treat that as "no
+    // key" here.
+    if (this.apiKey && this.apiKey !== "oauth") return;
+
+    try {
+      const { listOAuthProviderIds } = await import("../providers/auth/registry.js");
+      const ids = await listOAuthProviderIds();
+      if (!ids.includes(this.providerId)) return;
+
+      const effectiveBaseURL =
+        this.baseURL &&
+        this.baseURL !== (await import("../providers/endpoints.js").then((m) => m.apiBaseFor("anthropic")))
+          ? this.baseURL
+          : undefined;
+      const result = await createProviderFactoryAsync(this.providerId, {
+        baseURL: effectiveBaseURL ?? undefined,
+      });
+      this.provider = result.factory;
+    } catch {
+      // Fail-open — provider remains null; requireProvider() will surface the error
+    }
+  }
+
   async detectVerifyRecipe(settings?: SandboxSettings, abortSignal?: AbortSignal): Promise<VerifyRecipe | null> {
     try {
       const result = await this.runTaskRequest(
@@ -3435,531 +2639,3 @@ export class Agent {
     }
   }
 }
-
-interface ExecutedBatchTool {
-  toolCall: ToolCall;
-  input: unknown;
-  toolResult: ToolResult;
-}
-
-type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
-
-function extractJsonObject(text: string): string | null {
-  const start = text.indexOf("{");
-  const end = text.lastIndexOf("}");
-  if (start < 0 || end < start) return null;
-  return text.slice(start, end + 1);
-}
-
-function buildBatchName(prefix: string, label: string): string {
-  const compact =
-    label
-      .replace(/\s+/g, "-")
-      .replace(/[^a-zA-Z0-9._-]+/g, "")
-      .slice(0, 48) || "run";
-  return `muonroi-cli-${prefix}-${compact}`;
-}
-
-function buildBatchChatCompletionRequest(args: {
-  modelId: string;
-  system: string;
-  messages: ModelMessage[];
-  temperature: number;
-  maxOutputTokens?: number;
-  reasoningEffort?: BatchChatCompletionRequest["reasoning_effort"];
-  tools: BatchFunctionTool[];
-}): BatchChatCompletionRequest {
-  return {
-    model: args.modelId,
-    messages: toBatchChatMessages(args.system, args.messages),
-    temperature: args.temperature,
-    ...(args.maxOutputTokens != null ? { max_completion_tokens: args.maxOutputTokens } : {}),
-    ...(args.reasoningEffort ? { reasoning_effort: args.reasoningEffort } : {}),
-    ...(args.tools.length > 0 ? { tools: args.tools } : {}),
-  };
-}
-
-function toBatchChatMessages(system: string, messages: ModelMessage[]): BatchChatMessage[] {
-  const batchMessages: BatchChatMessage[] = [{ role: "system", content: system }];
-
-  for (const message of messages) {
-    const { role, content } = message;
-
-    switch (role) {
-      case "system":
-        batchMessages.push({ role: "system", content });
-        break;
-
-      case "user": {
-        if (typeof content === "string") {
-          batchMessages.push({ role: "user", content });
-          break;
-        }
-
-        if (!Array.isArray(content)) {
-          break;
-        }
-
-        if (content.length === 1 && content[0]?.type === "text") {
-          batchMessages.push({ role: "user", content: content[0].text });
-          break;
-        }
-
-        const userContent: Array<{ type: "text"; text: string } | { type: "image_url"; image_url: { url: string } }> =
-          [];
-        for (const part of content) {
-          switch (part.type) {
-            case "text":
-              userContent.push({ type: "text", text: part.text });
-              break;
-
-            case "image": {
-              const mediaType = part.mediaType === "image/*" || !part.mediaType ? "image/jpeg" : part.mediaType;
-              const data =
-                part.image instanceof URL
-                  ? part.image.toString()
-                  : `data:${mediaType};base64,${toBase64DataContent(part.image)}`;
-              userContent.push({ type: "image_url", image_url: { url: data } });
-              break;
-            }
-
-            case "file": {
-              if (!part.mediaType.startsWith("image/")) {
-                break;
-              }
-              const mediaType = part.mediaType === "image/*" ? "image/jpeg" : part.mediaType;
-              const data =
-                part.data instanceof URL
-                  ? part.data.toString()
-                  : `data:${mediaType};base64,${toBase64DataContent(part.data)}`;
-              userContent.push({ type: "image_url", image_url: { url: data } });
-              break;
-            }
-          }
-        }
-        batchMessages.push({
-          role: "user",
-          content: userContent,
-        });
-        break;
-      }
-
-      case "assistant": {
-        if (typeof content === "string") {
-          batchMessages.push({ role: "assistant", content });
-          break;
-        }
-
-        if (!Array.isArray(content)) {
-          break;
-        }
-
-        let assistantText = "";
-        const toolCalls: BatchToolCall[] = [];
-        for (const part of content) {
-          if (part.type === "text") {
-            assistantText += part.text;
-          } else if (part.type === "tool-call") {
-            toolCalls.push({
-              id: part.toolCallId,
-              type: "function",
-              function: {
-                name: part.toolName,
-                arguments: JSON.stringify(part.input),
-              },
-            });
-          }
-        }
-
-        if (assistantText || toolCalls.length > 0) {
-          batchMessages.push({
-            role: "assistant",
-            content: assistantText,
-            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
-          });
-        }
-        break;
-      }
-
-      case "tool":
-        for (const part of content) {
-          if (part.type === "tool-approval-response") {
-            continue;
-          }
-          batchMessages.push({
-            role: "tool",
-            tool_call_id: part.toolCallId,
-            content: toolOutputToText(part.output),
-          });
-        }
-        break;
-    }
-  }
-
-  return batchMessages;
-}
-
-function toBase64DataContent(value: string | Uint8Array | ArrayBuffer): string {
-  return convertToBase64(value instanceof ArrayBuffer ? new Uint8Array(value) : value);
-}
-
-function toolOutputToText(output: {
-  type: "text" | "json" | "execution-denied" | "error-text" | "error-json" | "content";
-  value?: unknown;
-  reason?: string;
-}): string {
-  switch (output.type) {
-    case "text":
-    case "error-text":
-      return String(output.value ?? "");
-    case "execution-denied":
-      return output.reason ?? "Tool execution denied.";
-    case "json":
-    case "error-json":
-    case "content":
-      return JSON.stringify(output.value ?? null);
-  }
-}
-
-function getBatchUsage(response: BatchChatCompletionResponse): ProcessMessageUsage {
-  const usage = response.usage as BatchChatCompletionResponse["usage"] | undefined;
-  const inputTokens = asNumber(usage?.input_tokens) ?? asNumber(usage?.prompt_tokens);
-  const outputTokens = asNumber(usage?.output_tokens) ?? asNumber(usage?.completion_tokens);
-  const totalTokens = asNumber(usage?.total_tokens) ?? sumDefined(inputTokens, outputTokens);
-  const u = usage as Record<string, unknown> | undefined;
-  return {
-    inputTokens,
-    outputTokens,
-    totalTokens,
-    costUsdTicks: asNumber(usage?.cost_in_usd_ticks),
-    cacheReadTokens: asNumber(u?.cache_read_input_tokens),
-    cacheCreationTokens: asNumber(u?.cache_creation_input_tokens),
-  };
-}
-
-function accumulateUsage(target: ProcessMessageUsage, usage: ProcessMessageUsage): void {
-  target.inputTokens = (target.inputTokens ?? 0) + (usage.inputTokens ?? 0);
-  target.outputTokens = (target.outputTokens ?? 0) + (usage.outputTokens ?? 0);
-  target.totalTokens = (target.totalTokens ?? 0) + (usage.totalTokens ?? 0);
-  target.costUsdTicks = (target.costUsdTicks ?? 0) + (usage.costUsdTicks ?? 0);
-  target.cacheReadTokens = (target.cacheReadTokens ?? 0) + (usage.cacheReadTokens ?? 0);
-  target.cacheCreationTokens = (target.cacheCreationTokens ?? 0) + (usage.cacheCreationTokens ?? 0);
-}
-
-function hasUsage(usage: ProcessMessageUsage): boolean {
-  return Boolean(
-    (usage.inputTokens ?? 0) || (usage.outputTokens ?? 0) || (usage.totalTokens ?? 0) || (usage.costUsdTicks ?? 0),
-  );
-}
-
-function getBatchFinishReason(finishReason: string | null | undefined): ProcessMessageFinishReason {
-  switch (finishReason) {
-    case "stop":
-    case "length":
-    case "content-filter":
-    case "tool-calls":
-    case "error":
-    case "other":
-      return finishReason;
-    case "tool_calls":
-      return "tool-calls";
-    default:
-      return "other";
-  }
-}
-
-function toLocalToolCall(toolCall: BatchToolCall): ToolCall {
-  return {
-    id: toolCall.id,
-    type: "function",
-    function: {
-      name: toolCall.function.name,
-      arguments: toolCall.function.arguments,
-    },
-  };
-}
-
-function buildAssistantBatchMessage(content: string, toolCalls: ToolCall[]): ModelMessage | null {
-  if (toolCalls.length === 0) {
-    return content ? { role: "assistant", content } : null;
-  }
-
-  const parts: Array<
-    { type: "text"; text: string } | { type: "tool-call"; toolCallId: string; toolName: string; input: unknown }
-  > = [];
-  if (content) {
-    parts.push({ type: "text", text: content });
-  }
-  for (const toolCall of toolCalls) {
-    parts.push({
-      type: "tool-call",
-      toolCallId: toolCall.id,
-      toolName: toolCall.function.name,
-      input: parseToolArgumentsOrRaw(toolCall.function.arguments),
-    });
-  }
-  return { role: "assistant", content: parts };
-}
-
-function buildToolBatchMessage(toolParts: ExecutedBatchTool[]): ModelMessage | null {
-  if (toolParts.length === 0) {
-    return null;
-  }
-
-  return {
-    role: "tool",
-    content: toolParts.map((part) => ({
-      type: "tool-result" as const,
-      toolCallId: part.toolCall.id,
-      toolName: part.toolCall.function.name,
-      output: part.toolResult.success
-        ? ({ type: "json", value: toSerializableValue(part.toolResult) } as const)
-        : ({ type: "error-json", value: toSerializableValue(part.toolResult) } as const),
-    })),
-  };
-}
-
-function parseToolArgumentsOrRaw(raw: string): unknown {
-  try {
-    return raw.trim() ? JSON.parse(raw) : {};
-  } catch {
-    return raw;
-  }
-}
-
-function toSerializableValue(value: unknown): JsonValue {
-  try {
-    return JSON.parse(JSON.stringify(value ?? null)) as JsonValue;
-  } catch {
-    return String(value);
-  }
-}
-
-function asNumber(value: unknown): number | undefined {
-  return typeof value === "number" ? value : undefined;
-}
-
-function sumDefined(left?: number, right?: number): number | undefined {
-  if (left == null && right == null) {
-    return undefined;
-  }
-  return (left ?? 0) + (right ?? 0);
-}
-
-function toToolCall(part: { toolCallId: string; toolName: string; args?: unknown; input?: unknown }): ToolCall {
-  return {
-    id: part.toolCallId,
-    type: "function",
-    function: {
-      name: part.toolName,
-      arguments: JSON.stringify(part.input ?? part.args ?? {}),
-    },
-  };
-}
-
-function notifyObserver<T>(listener: ((payload: T) => void) | undefined, payload: T): void {
-  if (!listener) {
-    return;
-  }
-
-  try {
-    listener(payload);
-  } catch {
-    // Observer failures should never break generation.
-  }
-}
-
-function getStepNumber(event: unknown, fallback: number): number {
-  if (event && typeof event === "object" && "stepNumber" in event && typeof event.stepNumber === "number") {
-    return event.stepNumber;
-  }
-
-  return fallback;
-}
-
-function getFinishReason(event: unknown): ProcessMessageFinishReason {
-  if (event && typeof event === "object" && "finishReason" in event) {
-    switch (event.finishReason) {
-      case "stop":
-      case "length":
-      case "content-filter":
-      case "tool-calls":
-      case "error":
-      case "other":
-        return event.finishReason;
-    }
-  }
-
-  return "other";
-}
-
-function getUsage(event: unknown): ProcessMessageUsage {
-  if (!(event && typeof event === "object" && "usage" in event)) {
-    return {};
-  }
-
-  const usage = event.usage;
-  if (!usage || typeof usage !== "object") {
-    return {};
-  }
-
-  const u = usage as Record<string, unknown>;
-  return {
-    inputTokens: typeof u.inputTokens === "number" ? u.inputTokens : undefined,
-    outputTokens: typeof u.outputTokens === "number" ? u.outputTokens : undefined,
-    totalTokens: typeof u.totalTokens === "number" ? u.totalTokens : undefined,
-    cacheReadTokens: typeof u.cacheReadTokens === "number" ? u.cacheReadTokens : undefined,
-    cacheCreationTokens: typeof u.cacheCreationTokens === "number" ? u.cacheCreationTokens : undefined,
-  };
-}
-
-function toToolResult(output: unknown): ToolResult {
-  if (output && typeof output === "object" && "success" in output) {
-    const r = output as {
-      success: boolean;
-      output?: string;
-      error?: string;
-      diff?: ToolResult["diff"];
-      plan?: Plan;
-      task?: ToolResult["task"];
-      delegation?: ToolResult["delegation"];
-      backgroundProcess?: ToolResult["backgroundProcess"];
-      media?: ToolResult["media"];
-      computer?: ToolResult["computer"];
-      lspDiagnostics?: ToolResult["lspDiagnostics"];
-    };
-    return {
-      success: r.success,
-      output: r.output,
-      error: r.error ?? (r.success ? undefined : r.output),
-      diff: r.diff,
-      plan: r.plan,
-      task: r.task,
-      delegation: r.delegation,
-      backgroundProcess: r.backgroundProcess,
-      media: r.media,
-      computer: r.computer,
-      lspDiagnostics: r.lspDiagnostics,
-    };
-  }
-  return { success: true, output: String(output) };
-}
-
-function formatSubagentActivity(toolName: string, args?: unknown): string {
-  const parsed = parseToolArgs(args);
-  if (toolName === "read_file") return `Read ${parsed.path || "file"}`;
-  if (toolName === "lsp") return `LSP ${parsed.operation || "query"} ${parsed.filePath || ""}`.trim();
-  if (toolName === "write_file") return `Write ${parsed.path || "file"}`;
-  if (toolName === "edit_file") return `Edit ${parsed.path || "file"}`;
-  if (toolName === "search_web") return `Web search "${truncate(parsed.query || "", 50)}"`;
-  if (toolName === "search_x") return `X search "${truncate(parsed.query || "", 50)}"`;
-  if (toolName === "generate_image") return `Generate image "${truncate(parsed.prompt || "", 50)}"`;
-  if (toolName === "generate_video") return `Generate video "${truncate(parsed.prompt || "", 50)}"`;
-  if (toolName === "computer_snapshot") return `Snapshot ${parsed.app || "desktop"}`;
-  if (toolName === "computer_screenshot") return "Capture desktop screenshot";
-  if (toolName === "computer_click")
-    return parsed.ref ? `Click ${parsed.ref}` : `Click at ${parsed.x || "?"},${parsed.y || "?"}`;
-  if (toolName === "computer_mouse_move")
-    return parsed.ref ? `Hover ${parsed.ref}` : `Move mouse to ${parsed.x || "?"},${parsed.y || "?"}`;
-  if (toolName === "computer_type") return `Type into ${parsed.ref || "element"}`;
-  if (toolName === "computer_press") return `Press ${parsed.key || "key"}`;
-  if (toolName === "computer_scroll") return `Scroll ${parsed.ref || "element"} ${parsed.direction || "down"}`;
-  if (toolName === "computer_launch") return `Launch ${parsed.app || "app"}`;
-  if (toolName === "computer_list_windows") return `List windows${parsed.app ? ` for ${parsed.app}` : ""}`;
-  if (toolName === "computer_focus_window")
-    return `Focus window ${parsed.window_id || parsed.title || parsed.app || ""}`.trim();
-  if (toolName === "computer_wait") return "Wait for desktop state";
-  if (toolName === "computer_get") return `Read ${parsed.property || "text"} from ${parsed.ref || "element"}`;
-  if (toolName === "bash") return truncate(parsed.command || "Run command", 70);
-  return truncate(`${toolName}`, 70);
-}
-
-function parseToolArgs(args: unknown): Record<string, string> {
-  if (!args || typeof args !== "object") return {};
-  const result: Record<string, string> = {};
-  for (const [key, value] of Object.entries(args)) {
-    result[key] = typeof value === "string" ? value : JSON.stringify(value);
-  }
-  return result;
-}
-
-function firstLine(text: string): string {
-  return text.trim().split("\n").find(Boolean)?.trim() || "Task completed.";
-}
-
-function truncate(text: string, max: number): string {
-  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
-}
-
-function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
-  const activeSignals = signals.filter((signal): signal is AbortSignal => Boolean(signal));
-  if (activeSignals.length === 0) return undefined;
-  if (activeSignals.length === 1) return activeSignals[0];
-
-  if (typeof AbortSignal.any === "function") {
-    return AbortSignal.any(activeSignals);
-  }
-
-  const controller = new AbortController();
-  for (const signal of activeSignals) {
-    if (signal.aborted) {
-      controller.abort();
-      break;
-    }
-
-    signal.addEventListener("abort", () => controller.abort(), { once: true });
-  }
-
-  return controller.signal;
-}
-
-function isContextLimitError(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  return /(context|token|prompt).*(limit|length|large|window|overflow)|too many tokens|maximum context/i.test(message);
-}
-
-function isAuthenticationError(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  return /\b(401|403)\b|unauthori[sz]ed|invalid.*(api[_ ]?key|token|credential)|authentication failed|forbidden|access denied/i.test(
-    message,
-  );
-}
-
-const STATUS_MESSAGES: Record<number, string> = {
-  400: "The request was invalid. This may be caused by an unsupported parameter or model.",
-  401: "Authentication failed. Your API key may be invalid or expired.",
-  403: "Access denied. Your API key does not have permission for this request.",
-  404: "The requested model or endpoint was not found. Check your model name and base URL.",
-  408: "The request timed out. Please try again.",
-  422: "The request could not be processed. Check your message format or parameters.",
-  429: "Rate limit exceeded. Please wait a moment and try again.",
-  500: "The API server encountered an internal error. Please try again later.",
-  502: "The API server is temporarily unavailable. Please try again later.",
-  503: "The API service is temporarily overloaded. Please try again later.",
-  529: "The API service is overloaded. Please try again later.",
-};
-
-function humanizeApiError(error: unknown): string {
-  if (APICallError.isInstance(error)) {
-    const detail = extractResponseDetail(error.responseBody);
-    if (detail) return detail;
-    if (error.statusCode && STATUS_MESSAGES[error.statusCode]) {
-      return STATUS_MESSAGES[error.statusCode];
-    }
-  }
-
-  const raw = error instanceof Error ? error.message : String(error);
-  return raw.replace(/^AI_\w+Error:\s*/i, "").trim() || raw;
-}
-
-function extractResponseDetail(body: string | undefined): string | null {
-  if (!body) return null;
-  try {
-    const parsed = JSON.parse(body);
-    const msg = parsed?.error?.message ?? parsed?.message ?? parsed?.detail;
-    if (typeof msg === "string" && msg.trim()) return msg.trim();
-  } catch {
-    /* not JSON */
-  }
-  return null;
-}