muonroi-cli 1.3.4 → 1.4.1

package/dist/src/orchestrator/message-processor.js

@@ -52,6 +52,7 @@
 import { stepCountIs, streamText } from "ai";
 import { getCachedAuthToken, getCachedServerBaseUrl } from "../ee/auth.js";
 import { routeFeedback, routeModel } from "../ee/bridge.js";
+import { getDefaultEEClient } from "../ee/intercept.js";
 import { getMistakeDetector } from "../ee/mistake-detector.js";
 import { fireAndForgetPhaseOutcome } from "../ee/phase-outcome.js";
 import * as phaseTracker from "../ee/phase-tracker.js";
@@ -59,14 +60,17 @@ import { buildScope as buildScopeForVeto } from "../ee/scope.js";
 import { fireTrajectoryEvent } from "../ee/session-trajectory.js";
 import { getTenantId as getTenantIdForVeto } from "../ee/tenant.js";
 import { buildMcpToolSet } from "../mcp/runtime.js";
+import { dropRedundantFsMcpTools, filterMcpServersByMessage } from "../mcp/smart-filter.js";
 import { getModelInfo } from "../models/registry.js";
-import { applyPilSuffix, getResponseTaskType, getResponseToolSet, isResponseTool, runPipeline } from "../pil/index.js";
+import { cheapModelShellLine, injectCheapModelPlaybook, injectCheapModelShellDirective, shouldInjectCheapModelPlaybook, } from "../pil/cheap-model-playbook.js";
+import { injectCheapModelWorkbook, shouldInjectCheapModelWorkbook } from "../pil/cheap-model-workbooks.js";
+import { applyPilSuffix, getResponseTaskType, getResponseToolSet, isResponseTool, runPipeline, shouldHaltOnResponseTool, } from "../pil/index.js";
 import { taskTypeToMaxTokens, taskTypeToReasoningEffort, taskTypeToTier } from "../pil/task-tier-map.js";
 import { getProviderCapabilities } from "../providers/capabilities.js";
 import { loadKeyForProvider } from "../providers/keychain.js";
-import { bridgeMcpToolResult, getVisionGuidanceForTextOnly, scrubImagePayloadsInMessages, } from "../providers/mcp-vision-bridge.js";
+import { bridgeMcpToolResult, getVisionGuidanceForTextOnly, listCachedImages, scrubImagePayloadsInMessages, } from "../providers/mcp-vision-bridge.js";
 import { captureToolSchemas } from "../providers/patch-zod-schema.js";
-import { buildTurnProviderOptions, detectProviderForModel, resolveModelRuntime, shouldDropParam, } from "../providers/runtime.js";
+import { buildTurnProviderOptions, detectProviderForModel, requireRuntimeProvider, resolveModelRuntime, shouldDropParam, } from "../providers/runtime.js";
 import { needsVisionProxy, proxyVision } from "../providers/vision-proxy.js";
 import { wireDebug } from "../providers/wire-debug.js";
 import { reportRouteOutcome } from "../router/decide.js";
@@ -74,22 +78,64 @@ import { decideStepRouting, getStepRouterConfig } from "../router/step-router.js
 import { routerStore } from "../router/store.js";
 import { getNextMessageSequence, logInteraction, markMessageErrored, markToolCallErrored, persistMessageWriteAhead, persistToolCallWriteAhead, } from "../storage/index.js";
 import { createBuiltinTools } from "../tools/registry.js";
+import { snapshotFromTodoWriteArgs } from "../tools/todo-write-snapshot.js";
+import { visionToolsNeeded } from "../tools/vision-gate.js";
 import { isDebugEnabled, recordTurnTrace } from "../ui/slash/debug.js";
 import { statusBarStore } from "../ui/status-bar/store.js";
 import { appendDecisionLog } from "../usage/decision-log.js";
-import { toolNeedsApproval } from "../utils/permission-mode.js";
-import { getAutoCouncilConfidence, getAutoCouncilMinRoles, getRoleModels, getTopLevelCompactKeepLast, getTopLevelCompactThresholdChars, getTopLevelToolBudgetChars, isAutoCouncilEnabled, isProviderDisabled, loadMcpServers, loadValidSubAgents, } from "../utils/settings.js";
+import { appendAudit, toolNeedsApproval } from "../utils/permission-mode.js";
+import { getAutoCouncilConfidence, getAutoCouncilMinRoles, getProviderStallTimeoutMs, getRoleModels, getTopLevelCompactKeepLast, getTopLevelCompactThresholdChars, getTopLevelToolBudgetChars, isAutoCouncilEnabled, isProviderDisabled, loadMcpServers, loadValidSubAgents, } from "../utils/settings.js";
+import { resolveShell } from "../utils/shell.js";
 import { relaxCompactionSettings } from "./compaction.js";
 import { wrapToolSetWithDedup } from "./cross-turn-dedup.js";
-import { humanizeApiError, isAuthenticationError, isContextLimitError } from "./error-utils.js";
+import { humanizeApiError, isAuthenticationError, isContextLimitError, summarizeApiErrorForLog } from "./error-utils.js";
+import { buildGroundingFootnote, findUnverifiedClaims } from "./grounding-check.js";
+import { buildInterruptedTurnNote } from "./interrupted-turn.js";
 import { stableCallId } from "./pending-calls.js";
 import { applyModelConstraints, buildSystemPromptParts } from "./prompts.js";
 import { extractProviderOptionsShape } from "./provider-options-shape.js";
 import { wrapToolSetWithReadBudget } from "./read-path-budget.js";
 import { containsEncryptedReasoning, sanitizeModelMessages } from "./reasoning.js";
+import { repairToolCallHook } from "./repair-tool-call.js";
+import { buildRepetitionReminder, recordAssistantBurst, shouldInjectRepetitionReminder, } from "./repetition-detector.js";
 import { classifyStreamError } from "./retry-classifier.js";
+import { forcedFinalize, getSessionLastTask, incSessionStep, parseBudgetOverride, recordSessionLastTask, resetSessionStep, resolveCeiling, } from "./scope-ceiling.js";
+import { attachReminderToMessages, buildCheckpointReminder, buildScopeReminder, cadenceForSize, shouldInjectCeilingCrossing, shouldInjectReminder, shouldInjectSoftWarn, } from "./scope-reminder.js";
+import { attemptStallRescue, pushStallToolResult } from "./stall-rescue.js";
+import { createStallWatchdog, STALL_ERROR_MESSAGE } from "./stall-watchdog.js";
 import { wrapToolSetWithCap } from "./sub-agent-cap.js";
 import { compactSubAgentMessages } from "./subagent-compactor.js";
+import { detectTextEmittedToolCall, parseDsmlToolCalls } from "./text-tool-call-detector.js";
+import { createToolLoopCapPredicate } from "./tool-loop-cap.js";
+import { buildToolRepetitionAbortMessage, recordToolError as recordToolRepetitionError, recordToolSuccess as recordToolRepetitionSuccess, } from "./tool-repetition-detector.js";
+/**
+ * F2 — approximate the char cost of the FIXED prompt envelope (system +
+ * tools JSON-Schema) that streamText re-sends on every step. Used to feed
+ * the compactor a realistic total-prompt size so it fires when billed input
+ * is actually large, not when only `messages[]` is.
+ */
+function computeEnvelopeChars(system, tools) {
+    let n = 0;
+    if (typeof system === "string")
+        n += system.length;
+    else if (system && typeof system === "object") {
+        try {
+            n += JSON.stringify(system).length;
+        }
+        catch {
+            /* ignore — best-effort estimate */
+        }
+    }
+    if (tools && typeof tools === "object") {
+        try {
+            n += JSON.stringify(tools).length;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return n;
+}
 import { combineAbortSignals, getFinishReason, getStepNumber, getUsage, notifyObserver, toToolCall, toToolResult, } from "./tool-utils.js";
 /**
  * MessageProcessor — extracted streaming turn loop.
@@ -101,6 +147,15 @@ import { combineAbortSignals, getFinishReason, getStepNumber, getUsage, notifyOb
  * Constructed per call (heap allocation is negligible against the streamText
  * cost), matching the StreamRunner / CouncilManager pattern.
  */
+/**
+ * Max response-tool (`respond_*`) calls tolerated within a single turn before
+ * the orchestrator finalizes early with the best answer buffered so far. A
+ * well-behaved turn emits the response tool ONCE; a hedge-then-answer emits 2.
+ * Beyond that is degenerate spam (session 8d8f498268ed: 80× identical
+ * respond_general in one generation). Set to 3 so the legitimate ≤2 patterns
+ * are never cut short.
+ */
+const RESPONSE_TOOL_SPAM_CAP = 3;
 export class MessageProcessor {
     deps;
     constructor(deps) {
@@ -126,6 +181,20 @@ export class MessageProcessor {
         }
         const signal = deps.getAbortController().signal;
         deps.emitSubagentStatus(null);
+        // Phase 5 Fix 1 — reset the per-session step counter at every user-turn
+        // boundary. The original Phase 4 design kept the counter per-SESSION so a
+        // wandering agent bursting 50 tools across pseudo-turns would still trip
+        // the ceiling. In practice that punishes legitimate multi-turn work: turn
+        // 1 fills the counter, turn 2 (even a deliberate continuation) is halted
+        // almost immediately because the ceiling row may resolve smaller for the
+        // continuation's classified task. A new user message is an explicit
+        // human-in-the-loop signal — the user has seen results and chose to
+        // continue. Reset the counter so each user turn gets the full budget the
+        // matrix specifies for its own (taskType, size). Within-turn wandering
+        // is still capped by the per-turn ceiling, which is the real concern.
+        if (deps.session?.id) {
+            resetSessionStep(deps.session.id);
+        }
         // Phase C3: advance the cross-turn dedup turn counter so stubs can point
         // back to the correct prior turn.
         deps.crossTurnDedup?.beginTurn();
@@ -195,6 +264,13 @@ export class MessageProcessor {
             };
             signal.addEventListener("abort", aborter, { once: true });
         }
+        // Phase 4 Plan 04 (4B) — parse `--budget-rounds N` flag BEFORE PIL so the
+        // flag never reaches the model and never biases intent classification.
+        // The stashed override is consumed after PIL produces taskType + size.
+        const _budgetOverride = parseBudgetOverride(userMessage);
+        if (_budgetOverride.override !== undefined) {
+            userMessage = _budgetOverride.cleanedPrompt;
+        }
         // P0 native observation: cache turn-level intent fields for PreToolUse.
         deps.setTurnUserGoalExcerpt(userMessage.slice(0, 200));
         deps.setTurnAssistantReasoning("");
@@ -226,32 +302,162 @@ export class MessageProcessor {
         const _debugTurnId = deps.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
+        // --- PIL with discovery (interactive path) ---
+        const pilChunkQueue = [];
+        const pilResponder = deps.councilManager.createQuestionResponder();
+        const discoveryHandler = {
+            askQuestion: async (question) => {
+                pilChunkQueue.push({
+                    type: "council_question",
+                    content: question.question,
+                    councilQuestion: question,
+                });
+                const text = await pilResponder(question.questionId);
+                return { questionId: question.questionId, text, kind: "choice" };
+            },
+            showAcceptance: async (card) => {
+                const { buildAcceptanceQuestion } = await import("../pil/layer18-acceptance.js");
+                const question = buildAcceptanceQuestion(card, crypto.randomUUID());
+                pilChunkQueue.push({
+                    type: "council_question",
+                    content: question.question,
+                    councilQuestion: question,
+                });
+                const text = await pilResponder(question.questionId);
+                return text.toLowerCase();
+            },
+        };
         const _pilStart = Date.now();
-        const pilCtx = await runPipeline(userMessage, {
-            resumeDigest: deps.getResumeDigest(),
-            activeRunId: deps.getActiveRunId(),
-            sessionId: deps.session?.id ?? null,
-        }).catch((err) => ({
-            raw: userMessage,
-            enriched: userMessage,
-            taskType: null,
-            domain: null,
-            confidence: 0,
-            outputStyle: null,
-            tokenBudget: 500,
-            metrics: null,
-            layers: [],
-            gsdPhase: null,
-            activeRunId: null,
-            intentKind: null,
-            fallbackReason: err instanceof Error ? `orchestrator-catch:${err.name}` : "orchestrator-catch:unknown",
-        }));
+        let pilCtxResolved = null;
+        let pilDone = false;
+        const pilTask = (async () => {
+            try {
+                // Build Pass 4 LLM fallback closure using the orchestrator's already-
+                // constructed provider factory + current model. PIL stays ignorant of
+                // provider wiring — it just receives a `classify(prompt)` callback.
+                let llmFallback;
+                try {
+                    const { createLlmClassifier } = await import("../pil/llm-classify.js");
+                    llmFallback = createLlmClassifier(deps.requireProvider(), deps.modelId);
+                }
+                catch (err) {
+                    console.error(`[pil] LLM fallback wiring failed: ${err?.message}`);
+                }
+                // Model-driven clarification proposer (for discovery interview).
+                // The actual task model (via the same provider + modelId) generates the
+                // questions based on raw + CLI enrichment. Then discovery asks user.
+                let clarificationProposer;
+                try {
+                    const { createModelClarificationProposer } = await import("../pil/discovery.js");
+                    clarificationProposer = createModelClarificationProposer(deps.requireProvider(), deps.modelId);
+                }
+                catch (err) {
+                    console.error(`[pil] clarification proposer wiring failed: ${err?.message}`);
+                }
+                pilCtxResolved = await runPipeline(userMessage, {
+                    resumeDigest: deps.getResumeDigest(),
+                    activeRunId: deps.getActiveRunId(),
+                    sessionId: deps.session?.id ?? null,
+                    interactionHandler: discoveryHandler,
+                    llmFallback,
+                    clarificationProposer,
+                    recentTurnsSummary: deps.buildRecentTurnsSummary(),
+                });
+            }
+            catch (err) {
+                pilCtxResolved = {
+                    raw: userMessage,
+                    enriched: userMessage,
+                    taskType: null,
+                    domain: null,
+                    confidence: 0,
+                    outputStyle: null,
+                    tokenBudget: 500,
+                    metrics: null,
+                    layers: [],
+                    gsdPhase: null,
+                    activeRunId: null,
+                    intentKind: null,
+                    fallbackReason: err instanceof Error ? `orchestrator-catch:${err.name}` : "orchestrator-catch:unknown",
+                };
+            }
+            finally {
+                pilDone = true;
+            }
+        })();
+        while (!pilDone) {
+            while (pilChunkQueue.length > 0) {
+                yield pilChunkQueue.shift();
+            }
+            if (!pilDone) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        while (pilChunkQueue.length > 0) {
+            yield pilChunkQueue.shift();
+        }
+        await pilTask;
+        const pilCtx = pilCtxResolved;
+        // Phase 4 Plan 04 (4B) — resolve per-session step ceiling using
+        // (task_type × complexitySize) matrix. Override (from --budget-rounds N
+        // parsed earlier) wins. When the override differs from the natural
+        // ceiling, emit info toast so the user sees the explicit cap.
+        //
+        // Phase 5 Fix 2 — continuation phrases ("tiếp tục" / "continue") are
+        // classified `general/chitchat` by PIL Layer 1 Pass 0. Resolving the
+        // ceiling from that label collapses the budget to general × small = 5,
+        // which is wrong: the user wants the agent to RESUME the prior task,
+        // not start a generic chitchat. When this session has a recorded
+        // non-chitchat task row, inherit it for ceiling resolution. The Pass 0
+        // classification itself stays general so downstream code (style /
+        // chitchat skip / tools-empty optimization in `BUG-A guard`) reads the
+        // correct intent; only the ceiling row is borrowed.
+        const _pilTaskType = pilCtx.taskType ?? "general";
+        const _pilSize = pilCtx.complexitySize?.size ?? "medium";
+        const _sessionIdForLastTask = deps.session?.id ?? "";
+        const _isContinuationChitchat = _pilTaskType === "general" && pilCtx.intentKind === "chitchat" && _sessionIdForLastTask !== "";
+        const _lastTask = _isContinuationChitchat ? getSessionLastTask(_sessionIdForLastTask) : null;
+        const _ceilingTaskType = _lastTask?.taskType ?? _pilTaskType;
+        const _ceilingSize = _lastTask?.size ?? _pilSize;
+        const _naturalCeiling = resolveCeiling(_ceilingTaskType, _ceilingSize);
+        // Phase 5 Fix 4 (Option A) — make ceiling mutable so the stopWhen
+        // closure can bump it on auto-continue checkpoints. See checkpoint
+        // logic at dynamicStopWhen below for the bump policy.
+        const _stepCeiling = _budgetOverride.override ?? _naturalCeiling;
+        // Record this turn's task row for future continuation inheritance.
+        // Only non-chitchat task turns update the slot.
+        if (_sessionIdForLastTask && _pilTaskType !== "general" && pilCtx.intentKind === "task") {
+            recordSessionLastTask(_sessionIdForLastTask, _pilTaskType, _pilSize);
+        }
+        if (_budgetOverride.override !== undefined && _budgetOverride.override !== _naturalCeiling) {
+            try {
+                const _ar = globalThis.__muonroiAgentRuntime;
+                _ar?.emitEvent({
+                    t: "event",
+                    kind: "toast",
+                    level: "info",
+                    text: `override active: ceiling ${_budgetOverride.override}, default was ${_naturalCeiling} (task=${_ceilingTaskType}/size=${_ceilingSize})`,
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        // Track whether forced-finalize is needed (set by stopWhen when the
+        // ceiling fires). Read AFTER the streamText fullStream finishes.
+        const _ceilingHit = false;
         // Cheap signal forwarded from PIL Layer 1 — true when input is greeting /
         // small-talk (≤10 chars + ≤2 words OR brain-classified "none"). Used to
         // skip the MCP tool catalog, which dominates input tokens (~20K) and is
         // useless for "hi" / "ok" / "thanks".
         const isChitchat = pilCtx.intentKind === "chitchat";
-        const enrichedMessage = pilCtx.enriched;
+        let enrichedMessage = pilCtx.enriched;
+        if (pilCtx.fallbackReason) {
+            // Surface PIL degradation to the model so it can calibrate trust in
+            // routing, taskType, and any injected directives. Without this the
+            // agent has no idea the 200ms fast-path or discovery timeout fired.
+            enrichedMessage = `[PIL fallback: ${pilCtx.fallbackReason} — classification/routing may be inaccurate or layers skipped; using raw input.]\n\n${enrichedMessage}`;
+        }
         deps.setPilActive(pilCtx.taskType !== null);
         deps.setPilEnrichmentDelta(pilCtx.metrics?.suffixInstructionTokens ?? Math.round((enrichedMessage.length - userMessage.length) / 4));
         const _pilEnrichmentDeltaSnapshot = pilCtx.metrics?.suffixInstructionTokens ?? Math.round((enrichedMessage.length - userMessage.length) / 4);
@@ -302,10 +508,16 @@ export class MessageProcessor {
         try {
             if (deps.session) {
                 const pilDurationMs = Date.now() - _pilStart;
+                // BUG-B telemetry — hash the raw user message so post-hoc queries can
+                // detect Layer 1 classifier drift on identical inputs within a session.
+                const { createHash } = await import("node:crypto");
+                const _userMsgSha8 = createHash("sha1").update(userMessage).digest("hex").slice(0, 8);
                 logInteraction(deps.session.id, "pil", {
                     eventSubtype: pilCtx.taskType ?? "none",
                     durationMs: pilDurationMs,
                     data: {
+                        userMsgSha8: _userMsgSha8,
+                        userMsgPreview: userMessage.slice(0, 60),
                         layers: pilCtx.layers?.filter((l) => l.applied).map((l) => l.name) ?? [],
                         fullLayers: pilCtx.layers?.map((l) => ({ name: l.name, applied: l.applied, delta: l.delta })) ?? [],
                         layerCount: pilCtx.layers?.length ?? 0,
@@ -407,7 +619,13 @@ export class MessageProcessor {
             if (deps.session) {
                 logInteraction(deps.session.id, "routing", {
                     model: turnModelId,
-                    data: { defaultModel: deps.modelId, routedModel: turnModelId, taskHash },
+                    data: {
+                        defaultModel: deps.modelId,
+                        routedModel: turnModelId,
+                        taskHash,
+                        pilTaskType: pilCtx.taskType ?? null,
+                        pilIntentKind: pilCtx.intentKind ?? null,
+                    },
                 });
             }
         }
@@ -578,20 +796,47 @@ export class MessageProcessor {
         // for the current turn. Reset to 0 on each new user turn (we're in processMessage).
         let streamRetryCount = 0;
         const MAX_STREAM_RETRIES = 2; // 3 total attempts = 1 first try + 2 retries
+        // Re-steer budget for a tool-call emitted as plain text (wrong dialect). One
+        // corrective retry: if the model still emits text instead of invoking the
+        // tool, we surface the warning and stop rather than loop. Loop-persistent so
+        // a model that degrades every step can't burn unbounded re-steers.
+        let textToolReSteerCount = 0;
+        const MAX_TEXT_TOOL_RESTEER = 1;
+        // Silent-hang guard: set true when the stall watchdog aborts a stuck stream.
+        // Reset before each streamText attempt; read in the stream catch to surface a
+        // clear toast and SKIP the transient-retry (a stalled provider just stalls
+        // again, wasting another full timeout of silence).
+        let stallTriggered = false;
         // Auto-council: route to multi-model debate when EITHER
-        //   (a) PIL classified taskType=plan|analyze with high confidence, OR
+        //   (a) PIL classified taskType=plan|analyze with high confidence AND the
+        //       prompt is complex enough to justify the debate cost, OR
         //   (b) GSD-native tier === "heavy" (wholesale / multi-step / cross-repo work).
         // After the debate finishes, runCouncilV2 records synthesis on
         // councilManager.lastSynthesis; we then re-enter processMessage with the synthesis
         // as the next user turn so the main loop continues with full debate context.
         // Skip if this is already a council continuation turn (prevent infinite recursion).
+        //
+        // Phase 5 BUG-I (session f1a2a2a547db) — the gate previously fired on
+        // taskType=analyze + conf≥0.85 alone, with no complexity check. Result:
+        // "improve test coverage cho src/X.ts" (single-file, scoreComplexity=low,
+        // score=2) sank 13 minutes into council debate, then halted on pattern-loop
+        // after sprint 1 read 6 files. The complexity gate below bypasses council
+        // for low-complexity analyze prompts — they get the hot-path direct exec
+        // and stay productive. `plan` keeps the old behaviour (architectural
+        // decisions deserve debate regardless of length).
         const autoCouncilTypes = new Set(["plan", "analyze"]);
         const councilRoles = getRoleModels();
         const configuredRoleCount = Object.values(councilRoles).filter(Boolean).length;
         const heavyTier = pilCtx.complexityTier === "heavy";
         const autoCouncilConfidence = getAutoCouncilConfidence();
         const autoCouncilMinRoles = getAutoCouncilMinRoles();
-        const taskTypeMatch = pilCtx.taskType && autoCouncilTypes.has(pilCtx.taskType) && pilCtx.confidence >= autoCouncilConfidence;
+        const _complexityFromTrace = pilCtx._intentTrace
+            ?.complexity;
+        const _complexityGatePassed = pilCtx.taskType === "plan" || _complexityFromTrace === undefined || _complexityFromTrace !== "low";
+        const taskTypeMatch = pilCtx.taskType &&
+            autoCouncilTypes.has(pilCtx.taskType) &&
+            pilCtx.confidence >= autoCouncilConfidence &&
+            _complexityGatePassed;
         const shouldAutoCouncil = !deps.councilManager.isContinuation &&
             isAutoCouncilEnabled() &&
             configuredRoleCount >= autoCouncilMinRoles &&
@@ -611,6 +856,8 @@ export class MessageProcessor {
                     return `taskType=${pilCtx.taskType ?? "null"} not in plan|analyze`;
                 if (pilCtx.confidence < autoCouncilConfidence)
                     return `confidence<${autoCouncilConfidence} (got ${pilCtx.confidence.toFixed(2)})`;
+                if (!_complexityGatePassed)
+                    return `complexity=low + taskType=${pilCtx.taskType} (analyze needs medium+; plan bypasses gate)`;
                 return "no-trigger";
             }
             return "taken";
@@ -625,6 +872,8 @@ export class MessageProcessor {
                 taskType: pilCtx.taskType ?? null,
                 confidence: pilCtx.confidence,
                 complexityTier: pilCtx.complexityTier ?? null,
+                complexityScore: _complexityFromTrace ?? null,
+                complexityGatePassed: _complexityGatePassed,
                 configuredRoleCount,
                 autoCouncilConfidence,
                 autoCouncilMinRoles,
@@ -681,12 +930,20 @@ export class MessageProcessor {
                 }
                 deps.setCompactedThisTurn(false);
                 let assistantText = "";
+                // Tracks where `assistantText` was at the previous step boundary so
+                // `onStepFinish` can compute the text emitted within the just-finished
+                // step (input to the self-repetition detector).
+                let _assistantTextAtLastStep = 0;
                 let reasoningPreview = "";
                 let encryptedReasoningHidden = false;
                 let streamOk = false;
                 let closeMcp;
                 let stepNumber = -1;
                 const activeToolCalls = [];
+                // Capped digest of tool outputs gathered this attempt — fuels the
+                // best-effort answer rescue if the stream stalls mid-turn (see
+                // stall-rescue.ts). Reset per attempt; only the most recent results win.
+                const turnToolResults = [];
                 // SAMR: track whether Phase 1 produced tool calls
                 let phase1HadToolCalls = false;
                 try {
@@ -696,12 +953,23 @@ export class MessageProcessor {
                     if (modelInfo?.contextWindow) {
                         await deps.compactForContext(provider, system, modelInfo.contextWindow, signal, settings, attemptedOverflowRecovery);
                     }
+                    // Vision-tool gate: for vision-proxy (text-only) models the registry
+                    // adds 3 image tools (~500-700 tok) on every turn. Drop them when the
+                    // turn has no plausible image involvement. Bias is KEEP — retained on
+                    // any image signal, attachment, cached image, or prior-tool turn.
+                    const includeVisionTools = visionToolsNeeded({
+                        userMessage,
+                        messages: deps.messages,
+                        cachedImageCount: listCachedImages().length,
+                        priorTurnHadTools: deps.messages.some((m) => m?.role === "tool"),
+                    });
                     const baseToolsRaw = createBuiltinTools(deps.bash, deps.mode, {
                         runTask: (request, abortSignal) => deps.runTask(request, combineAbortSignals(signal, abortSignal)),
                         runDelegation: (request, abortSignal) => deps.runDelegation(request, combineAbortSignals(signal, abortSignal)),
                         readDelegation: (id) => deps.readDelegation(id),
                         listDelegations: () => deps.listDelegations(),
                         modelId: turnModelId,
+                        includeVisionTools,
                     });
                     // Top-level cumulative cap state. We accumulate the raw tool set
                     // (base + MCP + PIL response tools) across the assembly below,
@@ -712,44 +980,96 @@ export class MessageProcessor {
                     // never needs bash/read_file/edit_file/grep — those schemas alone
                     // cost ~1.5K input tokens on this CLI. Falls back to baseTools for
                     // every non-chitchat turn (PIL gates conservatively).
-                    const turnCaps = getProviderCapabilities(runtime.modelInfo?.provider ?? "anthropic");
+                    //
+                    // BUG-A guard — when prior turns already issued tool_calls (their
+                    // results still live in the messages history), DROPPING tools on a
+                    // continuation chitchat ("tiếp tục" / "continue") causes two
+                    // failures: (1) DeepSeek goes into native DSML markup fallback
+                    // because it sees tool-call history but no schema (visible in
+                    // sessions 002df4014cb4 + fc19b4daee20); (2) the agent has no way
+                    // to actually CONTINUE the prior task — the user's clear intent.
+                    // Detect prior-tool-context and keep the base tool set in that
+                    // case. The 1.5K token saving for true greetings (no prior tool
+                    // history) is preserved.
+                    const turnCaps = getProviderCapabilities(requireRuntimeProvider(runtime));
+                    const _priorTurnHadTools = deps.messages.some((m) => m?.role === "tool");
                     let rawToolSet = !turnCaps.supportsClientTools(runtime.modelInfo)
                         ? {}
-                        : isChitchat
+                        : isChitchat && !_priorTurnHadTools
                             ? {}
                             : baseToolsRaw;
                     // MCP skip: chitchat / greeting inputs don't need 7 MCP servers'
                     // worth of tool schemas (~20K input tokens). PIL Layer 1 already
                     // gates this conservatively (≤10 chars + ≤2 words OR brain "none").
-                    if (deps.mode === "agent" && !isChitchat && turnCaps.supportsClientTools(runtime.modelInfo)) {
-                        // Smart MCP filter: skip browser/vision MCP servers unless the
-                        // user's current message has a URL or explicitly invokes the
-                        // browser/screenshot/design vocabulary. Local code work — which
-                        // is the majority of turns — does not need Playwright/Figma/Canva
-                        // tool schemas (each MCP contributes 8-15 tools at ~150 tok each).
+                    if (deps.mode === "agent" &&
+                        (!isChitchat || _priorTurnHadTools) &&
+                        turnCaps.supportsClientTools(runtime.modelInfo)) {
+                        // Smart MCP filter: drop OPTIONAL MCP servers whose category the
+                        // current message gives no signal for. Browser/vision servers
+                        // (Playwright/Chrome/Figma/Canva) skip unless the message touches a
+                        // page; docs/web servers (context7/fetch) skip unless the message
+                        // looks like an external lookup. Each MCP contributes 8-15 tools at
+                        // ~150 tok each, so local code work — the majority of turns — saves
+                        // ~13K input tokens it would otherwise pay every turn. Domain
+                        // servers (filesystem/tools/harness) always pass through. Logic is
+                        // a pure helper (src/mcp/smart-filter.ts) so it is unit-tested.
                         // Override with MUONROI_DISABLE_SMART_MCP=1.
-                        const smartMcp = process.env.MUONROI_DISABLE_SMART_MCP !== "1";
-                        const browserSignal = /https?:\/\/\S+|\b(screenshot|browser|playwright|chrome|figma|canva|render|webpage|website|url|hyperlink|navigate|click|scrape)\b/i.test(userMessage);
-                        const SKIP_WHEN_NO_BROWSER = /playwright|chrome|browser|devtools|vision|figma|canva/i;
-                        const allServers = loadMcpServers();
-                        const filteredServers = smartMcp && !browserSignal ? allServers.filter((s) => !SKIP_WHEN_NO_BROWSER.test(s.id)) : allServers;
-                        const mcpBundle = await buildMcpToolSet(filteredServers, {
-                            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);
-                                });
-                            },
+                        const filteredServers = filterMcpServersByMessage(loadMcpServers(), userMessage, {
+                            disabled: process.env.MUONROI_DISABLE_SMART_MCP === "1",
                         });
-                        closeMcp = mcpBundle.close;
-                        rawToolSet = { ...rawToolSet, ...mcpBundle.tools };
-                        if (mcpBundle.errors.length > 0) {
-                            yield { type: "content", content: `MCP unavailable: ${mcpBundle.errors.join(" | ")}\n\n` };
+                        // MCP non-blocking: race the build against a 2500ms cap so a slow
+                        // stdio MCP server spawn (or many optional servers) does not block
+                        // the main turn's first token / streamText indefinitely. On timeout
+                        // or error we fall back to builtins only (domain servers like fs/tools
+                        // are still valuable but the optional ones can be skipped for this turn).
+                        let mcpBundle = null;
+                        try {
+                            mcpBundle = await Promise.race([
+                                buildMcpToolSet(filteredServers, {
+                                    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);
+                                        });
+                                    },
+                                }),
+                                new Promise((_, reject) => setTimeout(() => reject(new Error("MCP build timeout (2500ms)")), 2500)),
+                            ]);
+                        }
+                        catch (err) {
+                            console.error("[MCP] buildMcpToolSet timed out or failed, proceeding with builtins only", err);
+                        }
+                        if (mcpBundle) {
+                            closeMcp = mcpBundle.close;
+                            // Drop filesystem-MCP read/write/edit tools that duplicate the
+                            // first-class builtin file tools. Without this, models re-read the
+                            // SAME file via both `read_file` and `mcp_filesystem__read_text_file`
+                            // (live grok session f5dfab0ce0ca: a 772-line file read 6×), wasting
+                            // ~150 tok/schema PLUS re-injecting whole files into context. The
+                            // builtins are strictly better (read-before-write, LSP, CRLF match,
+                            // dedup/read-budget wrappers). Non-duplicate fs tools are untouched.
+                            const _builtinToolNames = new Set(Object.keys(rawToolSet));
+                            const { tools: _dedupedMcpTools, dropped: _droppedFsMcp } = dropRedundantFsMcpTools(mcpBundle.tools, _builtinToolNames);
+                            rawToolSet = { ...rawToolSet, ..._dedupedMcpTools };
+                            if (_droppedFsMcp.length > 0 && deps.session) {
+                                try {
+                                    logInteraction(deps.session.id, "routing", {
+                                        model: turnModelId,
+                                        data: { droppedRedundantFsMcp: _droppedFsMcp },
+                                    });
+                                }
+                                catch {
+                                    /* telemetry best-effort */
+                                }
+                            }
+                            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
@@ -769,6 +1089,19 @@ export class MessageProcessor {
                     const tools = wrapToolSetWithReadBudget(wrapToolSetWithDedup(topLevelCap.tools, deps.crossTurnDedup), deps.readBudget);
                     captureToolSchemas(tools);
                     let responseToolCalled = false;
+                    // A turn must surface exactly ONE final structured answer. Cheap
+                    // models sometimes emit the response tool MORE THAN ONCE in a single
+                    // step (session 9b1b39bf4dc6: grok emitted respond_general twice —
+                    // a 278-char "I must read the code" hedge, then the 3782-char real
+                    // answer — both in one step). Yielding each inline appends two
+                    // stacked structured_response blocks and shows the hedge first.
+                    // Instead we BUFFER the response-tool payloads and yield only the
+                    // most complete one (longest serialized data) after the stream
+                    // drains — robust to either ordering (hedge-then-answer or
+                    // answer-then-summary).
+                    let _pendingStructuredResponse = null;
+                    let _pendingStructuredResponseLen = -1;
+                    let _responseToolEmitCount = 0;
                     // G3: providerOptions assembly is owned by the capability layer
                     // (src/providers/capabilities.ts). buildTurnProviderOptions feeds
                     // sessionId in so openai.promptCacheKey is derived per turn.
@@ -810,6 +1143,32 @@ export class MessageProcessor {
                     // Top-level dropParam — shared with sub-agent path via shouldDropParam.
                     // See src/providers/runtime.ts for the central rule.
                     const dropParam = (p) => shouldDropParam(runtime, p);
+                    // Tier-aware behavioural suffix. Cheap models (DeepSeek V4 Flash etc.)
+                    // ignore well-worded tool descriptions but DO adopt instructions when
+                    // surfaced in the system prompt. Smart models don't need this — gated
+                    // by `modelInfo.tier === "fast"`. See cheap-model-playbook.ts for
+                    // motivation + escape hatch (MUONROI_DISABLE_CHEAP_MODEL_PLAYBOOK=1).
+                    // Fast-tier steering, front-loaded for primacy: task convergence
+                    // workbook (anti-ramble — cuts tool-call count, the dominant
+                    // cheap-model cost) layered UNDER the tool-use playbook so the
+                    // CRITICAL tool rules stay at the very front. Both fixed per turn, so
+                    // they stay inside the cached prefix.
+                    const systemWithWorkbook = shouldInjectCheapModelWorkbook(runtime.modelInfo)
+                        ? injectCheapModelWorkbook(system, pilCtx.taskType)
+                        : system;
+                    const systemWithPlaybook = shouldInjectCheapModelPlaybook(runtime.modelInfo)
+                        ? injectCheapModelPlaybook(systemWithWorkbook)
+                        : systemWithWorkbook;
+                    // A2: front-load a one-line shell/env directive for fast-tier models.
+                    // The authoritative ENVIRONMENT block already states OS/shell/cwd in
+                    // the prompt body, but budget models underweight non-front-loaded
+                    // rules — so echo the correct-syntax line at the very front. Derived
+                    // from resolveShell({}) (same source as buildEnvironmentBlock) so it
+                    // is always accurate to the actual shell the bash tool will spawn.
+                    // Gated to fast tier, so the claude branch below still sees `system`.
+                    const systemWithShell = shouldInjectCheapModelPlaybook(runtime.modelInfo)
+                        ? injectCheapModelShellDirective(systemWithPlaybook, cheapModelShellLine(resolveShell({}).kind, process.platform))
+                        : systemWithPlaybook;
                     const systemForModel = runtime.modelId.startsWith("claude")
                         ? [
                             {
@@ -817,9 +1176,12 @@ export class MessageProcessor {
                                 content: systemParts.staticPrefix,
                                 providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
                             },
-                            { role: "system", content: system.slice(systemParts.staticPrefix.length) },
+                            {
+                                role: "system",
+                                content: systemWithShell.slice(systemParts.staticPrefix.length),
+                            },
                         ]
-                        : system;
+                        : systemWithShell;
                     // Capture prompt-size breakdown so recordUsage can attach it to the
                     // cost-log entry. Without this, "system prompt is huge" is unfalsifiable.
                     // chars/4 ≈ tokens for English; reported as chars to keep math obvious.
@@ -869,6 +1231,11 @@ export class MessageProcessor {
                     // Task 2.6a — assign a fresh correlation ID for this top-level streamText call.
                     const _topCallId = crypto.randomUUID();
                     deps.setCurrentCallId(_topCallId);
+                    // Capture finishReason so we can surface "round cap hit" as a visible
+                    // toast — without this, the agent silently stops mid-flight when
+                    // stepCountIs(maxToolRounds) fires and the user sees the TUI freeze
+                    // (session 7dcf8fd7d6a4 hit exactly 100 rounds → looked like a crash).
+                    let _lastFinishReason = null;
                     // Phase B4: compact older tool_result parts before each top-level
                     // step once cumulative message chars exceed the configured threshold.
                     // The compactor preserves system + first user verbatim and keeps the
@@ -890,32 +1257,333 @@ export class MessageProcessor {
                             providerOptions: providerOpts,
                         });
                     }
-                    // SiliconFlow DeepSeek thinking-mode reasoning_content workaround
-                    // (see siliconflow-history.ts). Sub-agent path applies the same strip
-                    // via the capability hook; identity for every other provider.
+                    // sanitizeHistory is identity for every provider (kept as a hook
+                    // for future provider-specific quirks). Reasoning round-trips
+                    // natively via @ai-sdk/openai-compatible — see
+                    // src/providers/__tests__/reasoning-roundtrip.test.ts.
                     const _topMessagesForCall = turnCaps.sanitizeHistory(deps.messages);
+                    // Closure-mutable cap for the tool-loop askcard rescue.
+                    // Phase 1 (SAMR) skips the dynamic cap (it's a single-step path).
+                    // Algorithm extracted to ./tool-loop-cap.ts so it can be unit-tested.
+                    const _baseDynamicStopWhen = createToolLoopCapPredicate({
+                        initialCap: deps.maxToolRounds,
+                        ask: deps.askToolLoopContinue,
+                        // Phase 5 BUG-H — thread the resolved natural ceiling down so the
+                        // pattern askcard can pick a context-aware default action (continue
+                        // early in the run, stop once we're past 50% of the natural budget).
+                        naturalCeiling: _naturalCeiling,
+                    });
+                    // Phase 4 Plan 04 (4B) — compose per-session ceiling alongside the
+                    // existing cap + pattern guard. Logical OR: any condition true → halt.
+                    // Counter is per-SESSION and increments once per stopWhen invocation
+                    // (i.e. once per finished tool step), persisting across user turns
+                    // so a wandering 3-turn burst still trips at the matrix limit.
+                    const _ceilingSessionId = deps.session?.id ?? "no-session";
+                    // Phase 5 Fix 3 — capture the actual step number when the ceiling
+                    // trips so the halt toast can report the real value, not the
+                    // ceiling/ceiling literal that always showed e.g. "5/5" regardless
+                    // of how many steps the turn actually ran.
+                    const _ceilingHitAtStep = 0;
+                    // Phase 5 Fix 5 — matrix ceiling is now a SOFT BOUNDARY, never a
+                    // hard halt. Phase 4's hard halt was a blunt anti-wandering
+                    // measure that also blocked legitimate multi-step work: every
+                    // long task (improve coverage, optimize startup, refactor) ran
+                    // out of budget mid-flight and required the user to manually
+                    // type "tiếp tục". Wrong philosophy — "done" must be the agent's
+                    // call, not the counter's.
+                    //
+                    // What replaced the hard halt:
+                    //  - Scope-reminders (4A path, prepareStep above) inject
+                    //    "[approaching ceiling]" reminder at floor(ceiling*0.7) and
+                    //    repeat at K cadence. Past the ceiling, every step gets a
+                    //    re-anchor so the model is repeatedly nudged toward closure.
+                    //  - The dynamicStopWhen no longer checks the matrix ceiling at
+                    //    all. The only halt source is `_baseDynamicStopWhen` which
+                    //    enforces `deps.maxToolRounds` as the ULTIMATE runaway safety
+                    //    net (default raised; see CLI default).
+                    //  - 4R bash repeat detector still catches the dominant wandering
+                    //    pattern (identical command twice in a row).
+                    //  - F6 synthesis still ensures any natural stream-end without
+                    //    text gets a final summary.
+                    //
+                    // _ceilingHit and _ceilingHitAtStep are kept for telemetry: a
+                    // crossing event is logged for forensics, but no action is taken.
+                    const dynamicStopWhen = (async (state) => {
+                        // Terminal response tool: a `respond_*` call IS the model's final
+                        // structured answer (its `execute` is identity — the payload lives
+                        // in the tool-call args). `shouldHaltOnResponseTool` decides if the
+                        // emission is terminal vs a premature "blind" announce:
+                        //  - response tool AFTER real tool work (read/grep/bash) → terminal,
+                        //    halt now (kills d95113d3be09 seq=27: 7 reads → 87× respond loop
+                        //    at call #1, no extra round-trip for the common case).
+                        //  - a single blind response (no prior investigation) → do NOT halt;
+                        //    give the model the step it announced it would use to read code
+                        //    (session e4a9d97a90: lone blind respond_general was force-stopped
+                        //    by the old halt-on-first rule and the agent never investigated).
+                        //  - a 2nd blind response with still no real work → narration loop,
+                        //    halt. In-step spam (80× in one generation) is bounded separately
+                        //    by RESPONSE_TOOL_SPAM_CAP — stopWhen only runs BETWEEN steps.
+                        // Read from `state.steps` (the SDK's own per-step record) rather than
+                        // the for-await consumer's `responseToolCalled` flag — stopWhen runs
+                        // between steps and may evaluate before our consumer processed the
+                        // tool-result part, so the flag would race.
+                        const _steps = state.steps;
+                        if (shouldHaltOnResponseTool(_steps))
+                            return true;
+                        const base = await _baseDynamicStopWhen(state);
+                        if (base)
+                            return true;
+                        const next = incSessionStep(_ceilingSessionId);
+                        // Telemetry-only: record the first time the counter crosses
+                        // the matrix ceiling, so post-hoc queries can correlate the
+                        // ceiling crossing with task completion outcomes. No halt.
+                        if (next === _stepCeiling) {
+                            try {
+                                if (deps.session?.id) {
+                                    logInteraction(deps.session.id, "f6_synthesis", {
+                                        data: {
+                                            outcome: "ceiling_crossed_softly",
+                                            stepAtCrossing: next,
+                                            naturalCeiling: _naturalCeiling,
+                                            taskType: _ceilingTaskType,
+                                            size: _ceilingSize,
+                                            hardCapMaxToolRounds: deps.maxToolRounds,
+                                        },
+                                    });
+                                }
+                            }
+                            catch {
+                                /* telemetry only */
+                            }
+                        }
+                        return false;
+                    });
+                    // BUG-A fix — when this turn carries an empty tool set (the
+                    // chitchat optimization at line ~1107 drops all schemas), AI SDK
+                    // sends `tools:[], tool_choice:undefined` to the provider. DeepSeek
+                    // V4 Flash sees prior `tool_call`/`tool_result` parts still in the
+                    // messages history (the previous turn used 20 tools) and the
+                    // model stays in agent-mode — but with no schema to call, it
+                    // falls back to its NATIVE DSML markup syntax and emits that as
+                    // plain text. AI SDK does not parse the native format, so the
+                    // markup leaks straight to the TUI as garbage and the turn
+                    // produces no useful output. Setting `toolChoice:"none"` is the
+                    // canonical way to tell the model "you cannot call tools this
+                    // turn" so it emits text-only. Verified by stream_start telemetry
+                    // on sessions 002df4014cb4 (leak) + fc19b4daee20 (leak): both had
+                    // toolCount=0 + toolChoice=undefined on chitchat continuation.
+                    const _toolsAreEmpty = Object.keys(tools).length === 0;
+                    const _finalToolChoice = _toolsAreEmpty
+                        ? "none"
+                        : _hasResponseTools && turnCaps.supportsClientTools(runtime.modelInfo)
+                            ? "auto"
+                            : undefined;
+                    // BUG-C telemetry — record tool availability + toolChoice at the
+                    // call site so future regressions show up in telemetry not in TUI.
+                    try {
+                        const _toolNamesAtCall = Object.keys(tools);
+                        logInteraction(deps.session?.id ?? "no-session", "stream_start", {
+                            model: turnModelId,
+                            data: {
+                                toolCount: _toolNamesAtCall.length,
+                                hasBash: _toolNamesAtCall.includes("bash"),
+                                toolNames: _toolNamesAtCall.slice(0, 25),
+                                toolChoice: _finalToolChoice ?? "undefined",
+                                hasResponseTools: _hasResponseTools,
+                                supportsClientTools: turnCaps.supportsClientTools(runtime.modelInfo),
+                                priorTurnHadTools: _topMessagesForCall.some((m) => m?.role === "tool"),
+                            },
+                        });
+                    }
+                    catch {
+                        /* telemetry only */
+                    }
+                    // Silent-hang guard: abort the stream (and surface a toast in the
+                    // catch below) if the provider sends no chunk for too long. Re-armed
+                    // on every chunk via stall.pet(), so it never kills an actively
+                    // streaming call. Disposed when the stream ends or errors.
+                    stallTriggered = false;
+                    const stall = createStallWatchdog(getProviderStallTimeoutMs(), () => {
+                        stallTriggered = true;
+                    });
                     const result = streamText({
                         model: runtime.model,
                         system: systemForModel,
                         messages: _topMessagesForCall,
                         tools,
-                        toolChoice: _hasResponseTools && turnCaps.supportsClientTools(runtime.modelInfo) ? "auto" : undefined,
-                        stopWhen: stepRouterPhase === "phase1"
-                            ? stepCountIs(1) // SAMR Phase 1: stop after reasoning step
-                            : stepCountIs(deps.maxToolRounds),
+                        toolChoice: _finalToolChoice,
+                        stopWhen: stepRouterPhase === "phase1" ? stepCountIs(1) : dynamicStopWhen,
                         maxRetries: 0,
-                        abortSignal: signal,
+                        abortSignal: combineAbortSignals(signal, stall.signal),
+                        // Repair malformed tool-call JSON args before they bubble up as
+                        // InvalidToolInputError → tool-error → repetition-detector abort.
+                        // Conservative: only fixes the two observed Qwen-style defects.
+                        // See src/orchestrator/tool-args-repair.ts for the transforms.
+                        experimental_repairToolCall: repairToolCallHook,
                         prepareStep: ({ stepNumber: sn, messages: stepMessages }) => {
                             if (sn < 1)
                                 return {};
                             const stripped = turnCaps.sanitizeHistory(stepMessages);
+                            // Agent-controlled veto (PRESERVE) or lighter selective keep (KEEP_TOOL_IDS) for this turn's B4 compaction.
+                            // PRESERVE_FULL_CONTEXT skips the compactor entirely (full history).
+                            // KEEP_TOOL_IDS: id1,id2 (from prior stub " (id=...) ") protects only those specific tool results
+                            // without the cost of a full veto. Parsed from reasoning or assistant note.
+                            let keepToolIds = [];
+                            const hasPreserve = stripped.some((m) => {
+                                const c = m?.content;
+                                const texts = [];
+                                if (typeof c === "string")
+                                    texts.push(c);
+                                if (Array.isArray(c)) {
+                                    for (const p of c)
+                                        if (typeof p?.text === "string")
+                                            texts.push(p.text);
+                                }
+                                const joined = texts.join(" ");
+                                if (joined.includes("PRESERVE_FULL_CONTEXT"))
+                                    return true;
+                                // Idea 3: parse lighter token
+                                const mKeep = joined.match(/KEEP_TOOL_IDS\s*[:=]\s*([a-z0-9_, -]+)/i);
+                                if (mKeep) {
+                                    keepToolIds = mKeep[1]
+                                        .split(/[,\s]+/)
+                                        .map((s) => s.trim())
+                                        .filter(Boolean);
+                                }
+                                return false;
+                            });
+                            if (hasPreserve) {
+                                return { messages: stripped };
+                            }
+                            // F2 — envelope = system prompt + JSON-Schema of every tool
+                            // re-sent on every step. Without this the threshold check
+                            // ignored 20-50K of fixed prompt overhead and the compactor
+                            // sat dormant just below its limit while billed input climbed.
+                            const envelopeChars = computeEnvelopeChars(systemForModel, tools);
+                            // G1 + G2 — feed the model's context window so the compactor
+                            // can pick a token-aware threshold and shrink keepLastTurns
+                            // when the window is approaching its ceiling.
+                            const contextWindowTokens = runtime.modelInfo?.contextWindow ?? 0;
+                            // Idea 4: fire-and-forget persist of elided tool outputs to EE (source=tool-artifact)
+                            // so later layer3/ee.query "tool-artifact id=xxx" or "full tool result id=..." can re-hydrate.
+                            // Use process-level fallbacks (prepareStep closure does not directly expose outer cwd/session in this scope).
+                            const _cwd = process.cwd();
+                            const _sess = undefined; // best-effort; EE artifact still indexable by content + meta.toolCallId
+                            const persistArtifact = (toolCallId, toolName, fullContent, reason) => {
+                                try {
+                                    getDefaultEEClient()
+                                        .extract({
+                                        transcript: fullContent.slice(0, 8000),
+                                        projectPath: _cwd,
+                                        meta: {
+                                            source: "tool-artifact",
+                                            toolCallId,
+                                            toolName,
+                                            reason,
+                                            sessionId: _sess,
+                                            elidedAtStep: sn,
+                                        },
+                                    }, AbortSignal.timeout(700))
+                                        .catch(() => { });
+                                }
+                                catch {
+                                    /* fail-open, no silent swallow of the decision */
+                                }
+                            };
                             const compacted = compactSubAgentMessages(stripped, {
                                 thresholdChars: topLevelCompactThreshold,
                                 keepLastTurns: topLevelCompactKeepLast,
                                 label: "top-level",
+                                envelopeChars,
+                                contextWindowTokens,
+                                keepToolIds: keepToolIds.length ? keepToolIds : undefined,
+                                persistArtifact,
                             });
+                            // Pre-compaction visibility: give the agent one step of notice
+                            // before B4 actually rewrites history into stubs. This is the
+                            // advance warning that was missing — agent can now decide to
+                            // summarize, finish, or request preservation.
+                            const _preCompactWarnAt = Math.floor(topLevelCompactThreshold * 0.78);
+                            if (stripped.length > _preCompactWarnAt && compacted === stripped) {
+                                const _cp = buildCheckpointReminder(sn, true);
+                                const _pre = `[pre-compaction warning at step ${sn} — next step(s) will likely rewrite older tool results to stubs (threshold ${topLevelCompactThreshold}, keepLast=${topLevelCompactKeepLast}). ${_cp} Summarize or finish if possible.]`;
+                                return { messages: attachReminderToMessages(stripped, _pre) };
+                            }
+                            // Phase 4A — scope reminder injection (REQ-005).
+                            // Cadence K = 3/5/8 for small/medium/large. Soft-warn fires
+                            // ONCE per session at floor(ceiling*0.7). Reminder lives in
+                            // the tool_result/system channel so B3/B4 compaction cannot
+                            // strip it (system-prompt path is unsafe at high step counts).
+                            // Ceiling reuses the 4B (task_type × size) matrix result
+                            // resolved above (`_stepCeiling`, `_ceilingTaskType`,
+                            // `_ceilingSize`, `_ceilingSessionId`) so the reminder and the
+                            // halt boundary agree on the same number.
+                            const _scopeSize = _ceilingSize;
+                            const _scopeK = cadenceForSize(_scopeSize);
+                            const _scopeCeiling = Math.max(1, _stepCeiling ?? deps.maxToolRounds ?? 30);
+                            const _scopeStep = sn;
+                            const _shouldRemind = shouldInjectReminder(_scopeStep, _scopeK);
+                            const _shouldWarn = shouldInjectSoftWarn(_scopeStep, _scopeCeiling, _ceilingSessionId);
+                            // Phase 5 Fix 5 (revised) — past the natural matrix ceiling the
+                            // orchestrator emits a STRONG re-anchor reminder, but only when
+                            //   (a) crossing the ceiling for the first time (one-shot), OR
+                            //   (b) hitting a normal cadence step (multiple of K).
+                            // Original Phase 5 Fix 5 fired on EVERY step past ceiling, which
+                            // on long-running sessions (e.g. step 77 / ceiling 6 in session
+                            // 1f29e238a816) produced 70+ redundant reminders that bloated
+                            // the tool_result channel and forced the model into a "YES still
+                            // on scope" loop on every tool call.
+                            const _pastNaturalCeiling = _scopeStep > _naturalCeiling;
+                            const _justCrossedCeiling = shouldInjectCeilingCrossing(_scopeStep, _naturalCeiling, _ceilingSessionId);
+                            const _pastCeilingAtCadence = _pastNaturalCeiling && _shouldRemind;
+                            // Fix #8 — self-repetition one-shot. Fires when the assistant
+                            // has opened the last 3 streamText steps with the same 4-word
+                            // phrase (e.g. "YES still on scope" — session 1f29e238a816
+                            // emitted 15 such bursts past ceiling). Reminder is attached
+                            // alongside (and before) any scope reminder so the model sees
+                            // the behavioural correction first.
+                            const _shouldRepeatReminder = shouldInjectRepetitionReminder(_ceilingSessionId);
+                            if (_shouldRemind || _shouldWarn || _justCrossedCeiling || _shouldRepeatReminder) {
+                                const _baseReminder = buildScopeReminder({
+                                    step: _scopeStep,
+                                    ceiling: _scopeCeiling,
+                                    taskType: _ceilingTaskType,
+                                    size: _scopeSize,
+                                    originalPrompt: userMessage,
+                                });
+                                // Strong "past natural budget" prefix only applies when we
+                                // ACTUALLY want the model to consider wrapping up — i.e. on
+                                // the crossing event or at a cadence step past ceiling, not
+                                // on every silent step in between.
+                                const _useStrong = _justCrossedCeiling || _pastCeilingAtCadence;
+                                const _scopePart = _shouldRemind || _shouldWarn || _justCrossedCeiling
+                                    ? _useStrong
+                                        ? `[past natural budget — step ${_scopeStep}/${_naturalCeiling}] If task is COMPLETE, emit final answer NOW. If wandering, simplify the next step. ${_baseReminder}`
+                                        : _shouldWarn
+                                            ? `[approaching ceiling] ${_baseReminder}`
+                                            : _baseReminder
+                                    : null;
+                                const _reminder = _shouldRepeatReminder
+                                    ? _scopePart
+                                        ? `${buildRepetitionReminder(_ceilingSessionId)}\n${_scopePart}`
+                                        : buildRepetitionReminder(_ceilingSessionId)
+                                    : _scopePart;
+                                const withReminder = attachReminderToMessages(compacted, _reminder);
+                                return { messages: withReminder };
+                            }
                             if (compacted === stripped && stripped === stepMessages)
                                 return {};
+                            // Self-awareness note: tell the model compaction happened so it
+                            // knows earlier context was elided and can adjust its behavior.
+                            // Enhanced per EE anti-mù plan (docs/ee-anti-mu-compaction-plan.md Phase 2): include proactive
+                            // "task finished?", "compacted yet?", "EE checkpoint" so agent can self-assess and avoid mù
+                            // even when the top-level summary is not in its immediate focus (sub-agents, long loops).
+                            const _compactNote = compacted !== stripped
+                                ? `[context compacted at step ${sn} — older or low-value tool results rewritten to stubs to fit budget. High-value evidence (file reads, bash, your previous responses) is kept verbatim. ${buildCheckpointReminder(sn, true)}]`
+                                : null;
+                            if (_compactNote) {
+                                return { messages: attachReminderToMessages(compacted, _compactNote) };
+                            }
                             return { messages: compacted };
                         },
                         ...(dropParam("temperature") ? {} : { temperature: 0.7 }),
@@ -940,10 +1608,23 @@ export class MessageProcessor {
                             });
                             // Realtime status bar update per step
                             if (stepUsage.inputTokens || stepUsage.outputTokens) {
-                                deps.recordUsage(stepUsage, "message", runtime.modelId);
+                                // O1 — thread THIS turn's providerOptions shape per step so every
+                                // step event records it (not just step 1) and an interleaved task
+                                // can't overwrite it. Mirrors the gate used for the call itself.
+                                deps.recordUsage(stepUsage, "message", runtime.modelId, Object.keys(providerOpts).length > 0 ? extractProviderOptionsShape(providerOpts) : null);
                             }
+                            // Fix #8 — feed the assistant text emitted in this step into
+                            // the self-repetition detector. The slice covers everything
+                            // appended to `assistantText` since the previous step boundary;
+                            // a step with no text (pure tool call) records as empty, which
+                            // recordAssistantBurst treats as a no-op so the current run is
+                            // preserved across tool interludes.
+                            const _stepText = assistantText.slice(_assistantTextAtLastStep);
+                            _assistantTextAtLastStep = assistantText.length;
+                            recordAssistantBurst(_ceilingSessionId, _stepText);
                         },
                         onFinish: ({ finishReason }) => {
+                            _lastFinishReason = finishReason ?? null;
                             // Task 2.6b — emit llm-done (agent-mode only).
                             try {
                                 const _ar = globalThis.__muonroiAgentRuntime;
@@ -955,8 +1636,8 @@ export class MessageProcessor {
                                     finishReason: finishReason ?? "stop",
                                 });
                             }
-                            catch {
-                                /* best-effort */
+                            catch (err) {
+                                console.error("[Agent:onFinish] failed to emit llm-done", err);
                             }
                             deps.setCurrentCallId("");
                         },
@@ -964,6 +1645,7 @@ export class MessageProcessor {
                     let _topTokenIndex = 0;
                     const _wireProviderIdTop = runtime.modelInfo?.provider ?? "unknown";
                     for await (const part of result.fullStream) {
+                        stall.pet(); // chunk arrived — reset the stall watchdog
                         if (signal.aborted) {
                             yield { type: "content", content: "\n\n[Cancelled]" };
                             break;
@@ -1019,6 +1701,73 @@ export class MessageProcessor {
                                 // SAMR: track that Phase 1 produced tool calls → transition to Phase 2
                                 if (stepRouterPhase === "phase1")
                                     phase1HadToolCalls = true;
+                                // Response tool = the terminal final answer (identity execute;
+                                // the payload lives in the call args). Buffer it (longest-wins)
+                                // straight from the args and gate UI/DB/exec spam: cheap models
+                                // sometimes emit the response tool MANY times in ONE generation
+                                // (session 8d8f498268ed: 80× identical respond_general hedge in
+                                // one step). stopWhen only halts BETWEEN steps, so it can't stop
+                                // an in-step spam — this does. Surface only the first indicator;
+                                // if the model spams past the cap, finalize NOW with the
+                                // buffered answer instead of streaming out the degenerate step.
+                                if (isResponseTool(tc.function.name)) {
+                                    _responseToolEmitCount += 1;
+                                    try {
+                                        const _payload = JSON.parse(tc.function.arguments || "{}");
+                                        const _len = JSON.stringify(_payload).length;
+                                        if (_len > _pendingStructuredResponseLen) {
+                                            _pendingStructuredResponseLen = _len;
+                                            _pendingStructuredResponse = {
+                                                taskType: getResponseTaskType(tc.function.name) ?? tc.function.name,
+                                                data: _payload,
+                                            };
+                                        }
+                                    }
+                                    catch {
+                                        /* keep the prior buffered payload */
+                                    }
+                                    responseToolCalled = true;
+                                    // Only the first response-tool call gets a UI indicator.
+                                    if (_responseToolEmitCount === 1) {
+                                        yield { type: "tool_calls", toolCalls: [tc] };
+                                    }
+                                    if (_responseToolEmitCount >= RESPONSE_TOOL_SPAM_CAP && _pendingStructuredResponse) {
+                                        if (deps.session) {
+                                            try {
+                                                logInteraction(deps.session.id, "f6_synthesis", {
+                                                    eventSubtype: "response_tool_spam_abort",
+                                                    data: { emitted: _responseToolEmitCount, keptChars: _pendingStructuredResponseLen },
+                                                });
+                                            }
+                                            catch {
+                                                /* telemetry best-effort */
+                                            }
+                                        }
+                                        // Persist a clean turn (user + the single buffered answer)
+                                        // so history stays usable; the spam is dropped. Mirrors the
+                                        // tool-repetition abort: yield + done + return (do NOT await
+                                        // result.response — the stream is still spewing calls).
+                                        const _data = _pendingStructuredResponse.data;
+                                        const _answerText = typeof _data.response === "string"
+                                            ? _data.response
+                                            : JSON.stringify(_pendingStructuredResponse.data);
+                                        try {
+                                            deps.appendCompletedTurn(userModelMessage, [
+                                                { role: "assistant", content: _answerText },
+                                            ]);
+                                        }
+                                        catch (persistErr) {
+                                            console.error(`[message-processor] response-tool-spam persist failed: ${persistErr?.message}`);
+                                        }
+                                        yield {
+                                            type: "structured_response",
+                                            structuredResponse: _pendingStructuredResponse,
+                                        };
+                                        yield { type: "done" };
+                                        return;
+                                    }
+                                    break; // response tools skip write-ahead/hooks/normal tool_calls yield
+                                }
                                 // EE PreToolUse hook: fire intercept before tool execution.
                                 {
                                     const turnAssistantReasoning = deps.getTurnAssistantReasoning();
@@ -1158,9 +1907,13 @@ export class MessageProcessor {
                                         yield { type: "content", content: `[Vision Bridge: image → text for ${turnModelId}]\n` };
                                     }
                                 }
-                                catch {
-                                    /* fail-open */
+                                catch (err) {
+                                    console.error("[Agent:visionBridge] failed to process image for tool result", err);
                                 }
+                                // Capture into the stall-rescue digest before any further
+                                // processing — if the stream stalls after this, these outputs
+                                // are all we have to synthesize a final answer from.
+                                pushStallToolResult(turnToolResults, part.toolName, typeof tr.output === "string" ? tr.output : JSON.stringify(tr.output));
                                 // Pitfall 9: settle the pending call log entry.
                                 if (deps.pendingCalls) {
                                     const pending = activeToolCalls.find((t) => t.id === part.toolCallId);
@@ -1182,25 +1935,32 @@ export class MessageProcessor {
                                         session_id: deps.session?.id,
                                         cwd: deps.bash.getCwd(),
                                     };
-                                    await deps.fireHook(postInput, signal).catch(() => { });
+                                    await deps.fireHook(postInput, signal).catch((err) => {
+                                        console.error("[Agent:PostToolUse hook] failed", err);
+                                    });
                                 }
                                 // Response tool: yield as structured_response instead of tool_result.
                                 // AI SDK v5 wraps tool outputs as `{type:"json", value:{...}}`; unwrap
                                 // to expose the schema-shaped payload to the UI renderer.
                                 if (isResponseTool(part.toolName)) {
                                     responseToolCalled = true;
+                                    // Payload was already buffered (longest-wins) from the
+                                    // tool-CALL args above; re-buffer from the executed result as
+                                    // a fallback (unwraps the AI-SDK `{type:"json",value}` shape).
+                                    // Counting + the spam cap live in the tool-call branch.
                                     const taskType = getResponseTaskType(part.toolName);
                                     const rawOutput = part.output;
                                     const unwrapped = rawOutput && typeof rawOutput === "object" && rawOutput.type === "json"
                                         ? (rawOutput.value ?? {})
                                         : (rawOutput ?? {});
-                                    yield {
-                                        type: "structured_response",
-                                        structuredResponse: {
+                                    const _len = JSON.stringify(unwrapped ?? {}).length;
+                                    if (_len > _pendingStructuredResponseLen) {
+                                        _pendingStructuredResponseLen = _len;
+                                        _pendingStructuredResponse = {
                                             taskType: taskType ?? part.toolName,
                                             data: unwrapped,
-                                        },
-                                    };
+                                        };
+                                    }
                                     notifyObserver(observer?.onToolFinish, { toolCall: tc, toolResult: tr, timestamp: Date.now() });
                                     break;
                                 }
@@ -1209,13 +1969,38 @@ export class MessageProcessor {
                                     toolResult: tr,
                                     timestamp: Date.now(),
                                 });
-                                // Interaction log: tool result
+                                // Interaction log: tool result.
+                                // Phase 5 BUG-J — for edit/write/update tools, persist the
+                                // structured diff (file_path, +N/-M counts, isNew flag, and
+                                // a bounded patch preview) so forensics queries can audit
+                                // what actually changed in each turn without re-reading
+                                // git history. Earlier the log only had the summary string
+                                // ("Edited X (+1 -1)") — the patch text was lost.
                                 try {
                                     if (deps.session) {
                                         const outputPreview = typeof tr.output === "string" ? tr.output.slice(0, 200) : JSON.stringify(tr.output).slice(0, 200);
+                                        const _trWithDiff = tr;
+                                        const diffMeta = _trWithDiff.diff &&
+                                            (tc.function.name === "edit_file" ||
+                                                tc.function.name === "write_file" ||
+                                                tc.function.name === "update_file")
+                                            ? {
+                                                filePath: _trWithDiff.diff.filePath,
+                                                additions: _trWithDiff.diff.additions,
+                                                removals: _trWithDiff.diff.removals,
+                                                isNew: _trWithDiff.diff.isNew,
+                                                // Cap at 4000 chars — enough to inspect small/medium
+                                                // edits without ballooning the SQLite row. Large
+                                                // refactors get truncated with a tail marker so
+                                                // readers know the patch is partial.
+                                                patchPreview: _trWithDiff.diff.patch.length > 4000
+                                                    ? _trWithDiff.diff.patch.slice(0, 4000) + "\n…[truncated]"
+                                                    : _trWithDiff.diff.patch,
+                                            }
+                                            : undefined;
                                         logInteraction(deps.session.id, "tool_result", {
                                             eventSubtype: tc.function.name,
-                                            data: { success: tr.success, outputPreview },
+                                            data: { success: tr.success, outputPreview, ...(diffMeta ? { diff: diffMeta } : {}) },
                                         });
                                     }
                                 }
@@ -1223,6 +2008,21 @@ export class MessageProcessor {
                                     /* fail-open */
                                 }
                                 yield { type: "tool_result", toolCall: tc, toolResult: tr };
+                                // Reset tool-repetition counter on any non-error result. A
+                                // successful call between two failures of the same shape is
+                                // progress and should not accumulate toward the abort gate.
+                                if (tr.success) {
+                                    recordToolRepetitionSuccess(deps.session?.id ?? null);
+                                }
+                                // todo_write side-effect: surface the task list to the UI via a
+                                // dedicated chunk so the sticky checklist panel can re-render
+                                // without parsing tool args itself. Skipped when the snapshot
+                                // doesn't parse (malformed args) so the UI is never poisoned.
+                                if (tc.function.name === "todo_write" && tr.success) {
+                                    const snap = snapshotFromTodoWriteArgs(tc.function.arguments);
+                                    if (snap)
+                                        yield { type: "task_list_update", taskListSnapshot: snap };
+                                }
                                 break;
                             }
                             case "tool-error": {
@@ -1277,11 +2077,37 @@ export class MessageProcessor {
                                         });
                                     }
                                 }
-                                catch {
-                                    /* fail-open */
+                                catch (logErr) {
+                                    console.error(`[message-processor] interaction-log tool_result failed: ${logErr?.message}`);
                                 }
                                 notifyObserver(observer?.onToolFinish, { toolCall: tc, toolResult: tr, timestamp: Date.now() });
                                 yield { type: "tool_result", toolCall: tc, toolResult: tr };
+                                // Tool-call perseveration guard. After N consecutive identical
+                                // (toolName, args, error) triples, abort the streaming loop
+                                // before TPM rate limits do (session 080fe2fcbf24).
+                                const repetition = recordToolRepetitionError(deps.session?.id ?? null, errPart.toolName, errPart.input, errMsg);
+                                if (repetition.shouldAbort) {
+                                    const abortMsg = buildToolRepetitionAbortMessage(errPart.toolName, repetition.runLength, errMsg);
+                                    try {
+                                        if (deps.session) {
+                                            logInteraction(deps.session.id, "error", {
+                                                eventSubtype: "tool_repetition_abort",
+                                                data: {
+                                                    toolName: errPart.toolName,
+                                                    runLength: repetition.runLength,
+                                                    errorPreview: errMsg.slice(0, 200),
+                                                },
+                                            });
+                                        }
+                                    }
+                                    catch (logErr) {
+                                        console.error(`[message-processor] interaction-log tool_repetition_abort failed: ${logErr?.message}`);
+                                    }
+                                    notifyObserver(observer?.onError, { message: abortMsg, timestamp: Date.now() });
+                                    yield { type: "error", content: abortMsg, isAuthError: false };
+                                    yield { type: "done" };
+                                    return;
+                                }
                                 break;
                             }
                             case "tool-approval-request": {
@@ -1301,9 +2127,25 @@ export class MessageProcessor {
                                 // 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, deps.permissionMode)) {
+                                const input = approvalPart.toolCall?.input ?? {};
+                                const context = toolName === "bash"
+                                    ? { command: String(input.command ?? "") }
+                                    : toolName === "write_file" ||
+                                        toolName === "edit_file" ||
+                                        toolName === "read_file" ||
+                                        toolName === "grep"
+                                        ? { path: String(input.path ?? input.file_path ?? "") }
+                                        : undefined;
+                                if (!toolNeedsApproval(toolName, deps.permissionMode, context)) {
                                     // Auto-approve: respond directly without surfacing to UI.
                                     deps.respondToToolApproval(approvalPart.approvalId, true);
+                                    appendAudit({
+                                        kind: deps.permissionMode === "yolo" ? "yolo-override" : "permission-override",
+                                        tool: toolName,
+                                        mode: deps.permissionMode,
+                                        context,
+                                        ts: Date.now(),
+                                    });
                                     break;
                                 }
                                 yield {
@@ -1316,22 +2158,31 @@ export class MessageProcessor {
                             }
                             case "error": {
                                 const authError = isAuthenticationError(part.error);
-                                const friendly = humanizeApiError(part.error);
+                                const friendly = humanizeApiError(part.error, {
+                                    modelId: runtime.modelId,
+                                    providerId: runtime.modelInfo?.provider,
+                                });
+                                const forensics = summarizeApiErrorForLog(part.error);
                                 notifyObserver(observer?.onError, {
                                     message: friendly,
                                     timestamp: Date.now(),
                                 });
-                                // Interaction log: error
+                                // Interaction log: error + forensics envelope so opaque
+                                // provider 4xx ("parameter is invalid" / unknown 400s) leave
+                                // an actionable wire-level trace without needing a repro.
                                 try {
                                     if (deps.session) {
                                         logInteraction(deps.session.id, "error", {
                                             eventSubtype: authError ? "auth" : "api",
-                                            data: { message: friendly.slice(0, 200) },
+                                            data: {
+                                                message: friendly.slice(0, 200),
+                                                ...(forensics ? { forensics } : {}),
+                                            },
                                         });
                                     }
                                 }
-                                catch {
-                                    /* fail-open */
+                                catch (logErr) {
+                                    console.error(`[message-processor] interaction-log error failed: ${logErr?.message}`);
                                 }
                                 yield {
                                     type: "error",
@@ -1341,17 +2192,144 @@ export class MessageProcessor {
                                 break;
                             }
                             case "abort":
+                                // A stall-watchdog abort arrives here as an "abort" stream part
+                                // (the SDK surfaces it as a part, not a throw). Distinguish it
+                                // from a genuine user cancel — which is caught at the top of the
+                                // loop via `signal.aborted` — and surface it as a visible error
+                                // instead of a benign "[Cancelled]" so a hung provider no longer
+                                // looks like a silent freeze.
+                                if (stallTriggered) {
+                                    stall.dispose();
+                                    // A response tool already produced the terminal structured
+                                    // answer (buffered from its call args) before the provider
+                                    // stalled on a LATER step. Surface it and finish cleanly —
+                                    // never bury the model's actual answer behind a "not
+                                    // responding" error. Root cause of the "respond_* indicator
+                                    // shows but no answer block renders" report: this stall-abort
+                                    // path returned before the post-loop structured_response yield,
+                                    // dropping the captured answer. A response tool is terminal,
+                                    // so there is nothing to rescue — just emit what we have.
+                                    if (_pendingStructuredResponse) {
+                                        if (!streamOk) {
+                                            try {
+                                                const _d = _pendingStructuredResponse.data;
+                                                const _ans = typeof _d.response === "string"
+                                                    ? _d.response
+                                                    : JSON.stringify(_pendingStructuredResponse.data);
+                                                deps.appendCompletedTurn(userModelMessage, [
+                                                    { role: "assistant", content: _ans },
+                                                ]);
+                                                streamOk = true;
+                                            }
+                                            catch (persistErr) {
+                                                console.error(`[message-processor] stall+response-tool persist failed: ${persistErr?.message}`);
+                                            }
+                                        }
+                                        yield {
+                                            type: "structured_response",
+                                            structuredResponse: _pendingStructuredResponse,
+                                        };
+                                        yield { type: "done" };
+                                        return;
+                                    }
+                                    // Best-effort answer rescue: a turn that already ran tools but
+                                    // stalled before the final synthesis would otherwise return
+                                    // ONLY "Model not responding", discarding all that work (live
+                                    // obs 2026-06-04, deepseek session 734e65cffdf6: 67 tool calls
+                                    // → user got nothing). Make ONE guarded forced-finalize call
+                                    // over the gathered tool outputs. forcedFinalize has its own
+                                    // stall timeout, so a still-dead provider just falls through.
+                                    let _rescued = null;
+                                    if (turnToolResults.length > 0) {
+                                        try {
+                                            const _userText = typeof userModelMessage?.content === "string"
+                                                ? userModelMessage.content
+                                                : JSON.stringify(userModelMessage?.content ?? "");
+                                            _rescued = await attemptStallRescue({
+                                                baseMessages: _topMessagesForCall,
+                                                userText: _userText.slice(0, 4000),
+                                                toolResults: turnToolResults,
+                                                system: typeof systemForModel === "string" ? systemForModel : undefined,
+                                                finalize: (a) => forcedFinalize({ model: runtime.model, messages: a.messages, system: a.system }),
+                                            });
+                                        }
+                                        catch {
+                                            _rescued = null;
+                                        }
+                                        try {
+                                            if (deps.session) {
+                                                logInteraction(deps.session.id, "stall_rescue", {
+                                                    data: {
+                                                        outcome: _rescued ? "rescued" : "no_text",
+                                                        toolResultCount: turnToolResults.length,
+                                                        chars: _rescued?.length ?? 0,
+                                                    },
+                                                });
+                                            }
+                                        }
+                                        catch {
+                                            /* telemetry is best-effort */
+                                        }
+                                    }
+                                    if (_rescued) {
+                                        assistantText += (assistantText ? "\n\n" : "") + _rescued;
+                                        yield { type: "content", content: _rescued };
+                                    }
+                                    // Persist a record of the interrupted turn BEFORE returning so
+                                    // the next turn is not amnesiac. Previously this returned with
+                                    // nothing persisted → the next turn saw "no previous turn" and
+                                    // redid the work, orphaning any edits the stalled turn applied
+                                    // (live obs 2026-06-04, deepseek-v4-flash). When rescued, the
+                                    // note now carries the synthesized answer too (assistantText).
+                                    // Best-effort: never let persistence failure block surfacing.
+                                    if (!streamOk) {
+                                        try {
+                                            const _stallNote = buildInterruptedTurnNote(assistantText, activeToolCalls.map((c) => c.function.name));
+                                            deps.appendCompletedTurn(userModelMessage, [
+                                                { role: "assistant", content: _stallNote },
+                                            ]);
+                                            streamOk = true;
+                                        }
+                                        catch {
+                                            /* best-effort — surface the stall regardless */
+                                        }
+                                    }
+                                    if (_rescued) {
+                                        // Recovered a best-effort answer from partial data — surface
+                                        // a soft notice instead of the scary "not responding" error.
+                                        yield {
+                                            type: "content",
+                                            content: "\n\n[Note: the model connection stalled; the answer above is a best-effort synthesis " +
+                                                "from the tool results gathered before the stall and may be incomplete.]",
+                                        };
+                                        yield { type: "done" };
+                                        return;
+                                    }
+                                    notifyObserver(observer?.onError, { message: STALL_ERROR_MESSAGE, timestamp: Date.now() });
+                                    yield { type: "error", content: STALL_ERROR_MESSAGE, isAuthError: false };
+                                    yield { type: "done" };
+                                    return;
+                                }
                                 yield { type: "content", content: "\n\n[Cancelled]" };
                                 break;
                         }
                     }
+                    stall.dispose(); // stream drained normally — stop the stall watchdog
                     // ─── SAMR Phase 1 → Phase 2 transition ─────────────────────────
                     // Phase 1 (premium model) produced tool calls but the SDK stopped
                     // before executing them (stopWhen: stepCountIs(1)). Append the
                     // assistant message to deps.messages and restart the loop with
                     // the fast execution model. Phase 2's streamText call will see
                     // the pending tool calls and execute them automatically.
-                    if (stepRouterPhase === "phase1" && phase1HadToolCalls) {
+                    //
+                    // EXCEPT when Phase 1 emitted a response tool: a `respond_*` call IS
+                    // the terminal structured answer (identity execute), not work to hand
+                    // to Phase 2. Transitioning here would (a) skip the structured_response
+                    // yield below — the answer never reaches the TUI — and (b) append a
+                    // dangling assistant tool-call WITHOUT its tool-result (only assistant
+                    // msgs are pushed), corrupting Phase 2's history. Fall through instead
+                    // so the buffered answer is yielded + persisted on this turn.
+                    if (stepRouterPhase === "phase1" && phase1HadToolCalls && !responseToolCalled) {
                         try {
                             const phase1Response = await result.response;
                             // Append only new messages (assistant message with tool calls)
@@ -1368,6 +2346,28 @@ export class MessageProcessor {
                         stepRouterPhase = "phase2";
                         continue; // Re-enter while loop with Phase 2 (fast) model
                     }
+                    // Surface the single most-complete response-tool answer buffered
+                    // during the stream (see _pendingStructuredResponse). Yielding here —
+                    // once, after the stream drained and after the Phase 1 transition —
+                    // collapses any duplicate response-tool emissions in the turn into a
+                    // single structured_response block for the UI.
+                    if (_pendingStructuredResponse) {
+                        yield {
+                            type: "structured_response",
+                            structuredResponse: _pendingStructuredResponse,
+                        };
+                        if (_responseToolEmitCount > 1 && deps.session) {
+                            try {
+                                logInteraction(deps.session.id, "f6_synthesis", {
+                                    eventSubtype: "response_tool_deduped",
+                                    data: { emitted: _responseToolEmitCount, keptChars: _pendingStructuredResponseLen },
+                                });
+                            }
+                            catch {
+                                /* telemetry best-effort */
+                            }
+                        }
+                    }
                     if (signal.aborted) {
                         deps.discardAbortedTurn(userModelMessage);
                         yield { type: "done" };
@@ -1383,7 +2383,162 @@ export class MessageProcessor {
                             // screenshot, ~1.5MB). Persisting that lets it accumulate and
                             // overflow the model's context on subsequent turns.
                             const scrubbed = scrubImagePayloadsInMessages(response.messages);
-                            deps.appendCompletedTurn(userModelMessage, sanitizeModelMessages(scrubbed));
+                            // Phase 5 F6 — synthesis step when stream ended without a final
+                            // text response. Cheap models (DeepSeek V4 Flash) frequently
+                            // emit only tool-calls in their last step and stop, leaving the
+                            // user staring at "Here's the summary:..." truncation that
+                            // required a manual "tiếp tục" turn-2 to coax out. Detect that
+                            // shape and inject ONE forcedFinalize call (same path as 4B
+                            // ceiling-hit) so the answer arrives on turn 1.
+                            //
+                            // Skip when 4B ceiling already triggered its own forcedFinalize
+                            // below — running both would double-bill and duplicate text.
+                            let _f6SynthesisText = null;
+                            const _f6LastMsg = scrubbed[scrubbed.length - 1];
+                            const _f6LastRole = _f6LastMsg?.role ?? "none";
+                            let _f6Outcome = "skip_ceiling";
+                            let _f6Elapsed = 0;
+                            let _f6ChunkChars = 0;
+                            let _f6Error = null;
+                            // A response tool already produced the final structured answer —
+                            // F6 synthesis would duplicate it as prose. Skip entirely. With
+                            // the stopWhen terminal-halt above, the turn now ends right after
+                            // the response tool (last scrubbed message is the response
+                            // tool-result, role "tool"), which would otherwise trip the
+                            // _needsSynthesis "ended on a tool" branch and double-respond.
+                            if (responseToolCalled) {
+                                _f6Outcome = "skip_response_tool";
+                            }
+                            else if (!_ceilingHit) {
+                                const _needsSynthesis = (() => {
+                                    if (!_f6LastMsg)
+                                        return false;
+                                    if (_f6LastMsg.role === "tool")
+                                        return true;
+                                    if (_f6LastMsg.role !== "assistant")
+                                        return false;
+                                    const _c = _f6LastMsg.content;
+                                    if (typeof _c === "string")
+                                        return !_c.trim();
+                                    if (!Array.isArray(_c))
+                                        return false;
+                                    return !_c.some((p) => p && p.type === "text" && typeof p.text === "string" && p.text.trim().length > 0);
+                                })();
+                                if (!_needsSynthesis) {
+                                    _f6Outcome = "skip_has_text";
+                                }
+                                else {
+                                    const _f6Start = Date.now();
+                                    try {
+                                        const _ff = await forcedFinalize({
+                                            model: runtime.model,
+                                            messages: _topMessagesForCall,
+                                            system: typeof systemForModel === "string" ? systemForModel : undefined,
+                                        });
+                                        _f6Elapsed = Date.now() - _f6Start;
+                                        _f6ChunkChars = (_ff.text ?? "").length;
+                                        if (_ff.text.trim()) {
+                                            _f6SynthesisText = _ff.text;
+                                            assistantText += _ff.text;
+                                            yield { type: "content", content: _ff.text };
+                                            _f6Outcome = "fired_text";
+                                        }
+                                        else {
+                                            _f6Outcome = "fired_empty";
+                                        }
+                                    }
+                                    catch (_err) {
+                                        _f6Elapsed = Date.now() - _f6Start;
+                                        _f6Outcome = "error";
+                                        _f6Error = _err?.message?.slice(0, 200) ?? String(_err).slice(0, 200);
+                                    }
+                                }
+                            }
+                            try {
+                                if (deps.session) {
+                                    logInteraction(deps.session.id, "f6_synthesis", {
+                                        data: {
+                                            outcome: _f6Outcome,
+                                            lastMsgRole: _f6LastRole,
+                                            elapsedMs: _f6Elapsed,
+                                            chars: _f6ChunkChars,
+                                            error: _f6Error,
+                                            ceilingHit: _ceilingHit,
+                                            scrubbedLen: scrubbed.length,
+                                        },
+                                    });
+                                }
+                            }
+                            catch {
+                                /* telemetry is best-effort */
+                            }
+                            // Summary-phase grounding check (Agent Operating Contract, runtime
+                            // half). Soft-flag counts / file:line refs in the final synthesis
+                            // that don't appear in this turn's tool outputs — possible
+                            // hallucination. Never blocks: emits a grounding-flag event + a
+                            // warn toast + an inline advisory footnote. Only runs when the
+                            // turn actually produced tool output (a corpus to ground against)
+                            // and is not chitchat. See grounding-check.ts.
+                            if (process.env.MUONROI_DISABLE_GROUNDING_CHECK !== "1" &&
+                                !isChitchat &&
+                                assistantText.trim().length > 0) {
+                                try {
+                                    const _gParts = [];
+                                    let _gHadTool = false;
+                                    for (const _gm of scrubbed) {
+                                        if (!_gm || _gm.role === "assistant")
+                                            continue;
+                                        if (_gm.role === "tool")
+                                            _gHadTool = true;
+                                        const _gc = _gm.content;
+                                        _gParts.push(typeof _gc === "string" ? _gc : JSON.stringify(_gc));
+                                    }
+                                    if (_gHadTool) {
+                                        const _claims = findUnverifiedClaims(assistantText, _gParts.join("\n"));
+                                        if (_claims.length > 0) {
+                                            const _footnote = buildGroundingFootnote(_claims);
+                                            assistantText += _footnote;
+                                            yield { type: "content", content: _footnote };
+                                            const _gar = globalThis.__muonroiAgentRuntime;
+                                            const _claimTexts = _claims.map((c) => c.text);
+                                            _gar?.emitEvent({
+                                                t: "event",
+                                                kind: "grounding-flag",
+                                                claims: _claimTexts,
+                                                count: _claims.length,
+                                                ts: Date.now(),
+                                            });
+                                            _gar?.emitEvent({
+                                                t: "event",
+                                                kind: "toast",
+                                                level: "warn",
+                                                text: `grounding: ${_claims.length} unverified claim(s) — ${_claimTexts.join(", ")}`,
+                                            });
+                                            if (deps.session) {
+                                                try {
+                                                    logInteraction(deps.session.id, "grounding_flag", {
+                                                        data: { claims: _claimTexts, count: _claims.length },
+                                                    });
+                                                }
+                                                catch {
+                                                    /* telemetry is best-effort */
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                                catch {
+                                    /* grounding check is best-effort — never break finalize */
+                                }
+                            }
+                            const _finalMessages = sanitizeModelMessages(scrubbed);
+                            if (_f6SynthesisText !== null) {
+                                _finalMessages.push({
+                                    role: "assistant",
+                                    content: _f6SynthesisText,
+                                });
+                            }
+                            deps.appendCompletedTurn(userModelMessage, _finalMessages);
                             streamOk = true;
                         }
                     }
@@ -1401,6 +2556,13 @@ export class MessageProcessor {
                         yield { type: "done" };
                         return;
                     }
+                    // Phase 5 Fix 5 — the Phase 4 4B forced-finalize-on-ceiling-hit
+                    // block lived here. With the matrix ceiling no longer halting the
+                    // stream (it's pure telemetry now), _ceilingHit can never be true
+                    // and this branch is dead. F6 synthesis above already covers the
+                    // "stream ended with no final text" case for both natural model
+                    // termination AND maxToolRounds halt. Keeping the comment as a
+                    // breadcrumb for future archaeology.
                     if (!streamOk && assistantText.trim()) {
                         deps.appendCompletedTurn(userModelMessage, [{ role: "assistant", content: assistantText }]);
                     }
@@ -1454,11 +2616,29 @@ export class MessageProcessor {
                             reportRouteOutcome(storeHash, "success", turnDuration);
                         }
                     }
+                    // Detect a tool call emitted as plain TEXT (wrong dialect) in the final
+                    // assistant answer — the action never ran, so the turn would otherwise
+                    // end silently with broken/half-done work (live: deepseek session
+                    // 905d564dbde4 emitted `<read_file>` as text after a destructive edit).
+                    // Detect regardless of how many real tool calls already succeeded: the
+                    // common failure is the model doing a few real tools, then emitting the
+                    // NEXT call as text and stopping (live deepseek-native, full-fix CLI: 2
+                    // real read_file calls, then `<read_file><path>` as text → silent stop).
+                    // An earlier `activeToolCalls.length === 0` guard suppressed exactly
+                    // that case. Detector precision (structural invocation shape, not a bare
+                    // mention) guards against false-firing on a normal final answer.
+                    const _textToolCall = detectTextEmittedToolCall(assistantText);
                     // Interaction log: agent response complete
                     try {
                         if (deps.session) {
                             const sb = statusBarStore.getState();
                             const turnDurationMs = Date.now() - turnStartMs;
+                            // BUG-A telemetry — detect raw DeepSeek native tool-call markup
+                            // leaking into assistant text. Signature is `<｜｜DSML｜｜` (the
+                            // fullwidth vertical bars are NOT pipes, they're U+FF5C).
+                            const _dsmlSig = "｜｜DSML｜｜";
+                            const _dsmlMatches = assistantText.includes(_dsmlSig);
+                            const _codeBlockBash = /```\s*bash\b/i.test(assistantText);
                             logInteraction(deps.session.id, "agent_response", {
                                 model: turnModelId,
                                 inputTokens: sb.in_tokens,
@@ -1468,6 +2648,10 @@ export class MessageProcessor {
                                     textLength: assistantText.length,
                                     toolCallCount: activeToolCalls.length,
                                     compacted: deps.getCompactedThisTurn(),
+                                    dsmlLeak: _dsmlMatches,
+                                    bashCodeBlock: _codeBlockBash,
+                                    textToolXmlLeak: _textToolCall.detected,
+                                    textToolXmlTool: _textToolCall.tool,
                                 },
                             });
                         }
@@ -1475,6 +2659,90 @@ export class MessageProcessor {
                     catch {
                         /* fail-open */
                     }
+                    // Surface the round-cap stop so the user knows why the agent halted
+                    // (session 7dcf8fd7d6a4 hit stepCountIs(100) silently, looked like a
+                    // crash). AI SDK reports finishReason='tool-calls' when the step cap
+                    // fires with tool calls still pending — distinct from 'stop' (model
+                    // chose to end). We only warn when stepNumber ≥ cap so a model that
+                    // legitimately terminates mid-tool-call (rare) doesn't get a false
+                    // warning.
+                    if (_lastFinishReason === "tool-calls" && stepNumber >= deps.maxToolRounds - 1) {
+                        yield {
+                            type: "content",
+                            content: `\n\n[Stopped: hit max-tool-rounds=${deps.maxToolRounds}. ` +
+                                `Re-run with \`--max-tool-rounds ${deps.maxToolRounds * 2}\` to continue, ` +
+                                "or accept the partial result above.]\n",
+                        };
+                    }
+                    // Tool-call-as-text leak: the model wrote a tool invocation as plain
+                    // text (wrong dialect) and made NO real tool call, so the action never
+                    // ran. Auto-recover ONCE: append a corrective message and re-run the
+                    // turn so the model can invoke the tool properly. The just-finished
+                    // (text-only) turn is already persisted above — the model sees its own
+                    // mistake plus the correction. Mirrors the proven phase-switch re-entry
+                    // (it also pushes to deps.messages then `continue`s); bounded by
+                    // MAX_TEXT_TOOL_RESTEER so a persistently-degrading model can't loop.
+                    if (_textToolCall.detected && streamOk && textToolReSteerCount < MAX_TEXT_TOOL_RESTEER) {
+                        textToolReSteerCount++;
+                        // Recover the model's INTENT from the leaked markup (DeepSeek-native
+                        // DSML carries the tool + args) so the corrective restates the exact
+                        // call — far more effective than a generic "use the tool" nudge.
+                        const _parsedCalls = parseDsmlToolCalls(assistantText);
+                        const _intent = _parsedCalls.length > 0
+                            ? ` You appear to have intended: ${_parsedCalls
+                                .map((c) => `${c.name}(${Object.entries(c.args)
+                                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                                .join(", ")})`)
+                                .join("; ")}. Make those exact call(s) via the tool interface now.`
+                            : "";
+                        deps.messages.push({
+                            role: "user",
+                            content: `Your previous reply wrote a \`${_textToolCall.tool}\` tool call as XML/text. That is NOT how tools are invoked here — ` +
+                                "writing tool calls as text does nothing, so the action did not run. " +
+                                "Use the actual tool-calling interface (function/tool calls) to perform the action now. " +
+                                "Do NOT output XML tags like <read_file>, <write_to_file>, <execute_command>, or <tool_call> (or DSML markup) as text." +
+                                _intent,
+                        });
+                        if (deps.session) {
+                            try {
+                                logInteraction(deps.session.id, "text_tool_resteer", {
+                                    model: turnModelId,
+                                    data: { tool: _textToolCall.tool, attempt: textToolReSteerCount },
+                                });
+                            }
+                            catch {
+                                /* telemetry best-effort */
+                            }
+                        }
+                        {
+                            const _gar = globalThis.__muonroiAgentRuntime;
+                            _gar?.emitEvent({
+                                t: "event",
+                                kind: "toast",
+                                level: "info",
+                                text: `model wrote a ${_textToolCall.tool} tool call as text — re-steering to use the tool interface`,
+                            });
+                        }
+                        await closeMcp?.().catch(() => { });
+                        continue;
+                    }
+                    // Re-steer budget exhausted (or no clean finish): surface the leak so
+                    // the turn is not SILENTLY wasted. The "answer" above is unexecuted XML.
+                    if (_textToolCall.detected) {
+                        yield {
+                            type: "content",
+                            content: `\n\n[⚠ The model wrote a \`${_textToolCall.tool}\` tool call as TEXT instead of invoking the tool, ` +
+                                "so that action did NOT run and this turn made no real progress. " +
+                                "Re-run the request (optionally with a more capable model) — the tool interface was not used.]\n",
+                        };
+                        const _gar = globalThis.__muonroiAgentRuntime;
+                        _gar?.emitEvent({
+                            t: "event",
+                            kind: "toast",
+                            level: "warn",
+                            text: `model emitted a ${_textToolCall.tool} tool call as text — action not executed`,
+                        });
+                    }
                     const stopInput = {
                         hook_event_name: "Stop",
                         session_id: deps.session?.id,
@@ -1564,7 +2832,9 @@ export class MessageProcessor {
                     // Transient network/server error retry — up to MAX_STREAM_RETRIES extra attempts.
                     // Only retry when no content has flowed yet (assistantText empty) to avoid
                     // partial-output corruption. Honour the abort signal between retries.
-                    if (!assistantText.trim() && streamRetryCount < MAX_STREAM_RETRIES && !signal.aborted) {
+                    // Skip retry on a stall abort: the provider is unresponsive, so a retry
+                    // just burns another full stall timeout of silence — surface it instead.
+                    if (!assistantText.trim() && streamRetryCount < MAX_STREAM_RETRIES && !signal.aborted && !stallTriggered) {
                         const { transient } = classifyStreamError(err);
                         if (transient) {
                             streamRetryCount++;
@@ -1614,7 +2884,11 @@ export class MessageProcessor {
                         }
                     }
                     const authError = isAuthenticationError(err);
-                    const friendly = humanizeApiError(err);
+                    // Stall aborts carry an opaque DOMException; show the clear stall
+                    // message instead of the raw abort reason.
+                    const friendly = stallTriggered
+                        ? STALL_ERROR_MESSAGE
+                        : humanizeApiError(err, { modelId: runtime.modelId, providerId: runtime.modelInfo?.provider });
                     notifyObserver(observer?.onError, {
                         message: friendly,
                         timestamp: Date.now(),