@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/engine/turn-loop.js

@@ -11,6 +11,28 @@ import { logger } from "../logging/logger.js";
 import { checkTokenBudget, createBudgetTracker } from "./token-budget.js";
 import { StreamingToolQueue } from "./streaming-tool-queue.js";
 import { estimateTokens } from "../context/compaction.js";
+import { isTruncatedStop } from "../llm/stop-reason.js";
+import { isAbortError } from "../llm/client-base.js";
+import { crossedReactiveThreshold } from "./reactive-threshold.js";
+import { COMPLETE_GOAL_TOOL_NAME } from "../tool-system/builtin/complete-goal.js";
+import { createGoalBudgetTracker, recordGoalUsage, goalBudgetExceeded, } from "./goal.js";
+/**
+ * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
+ * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
+ * 用文本(成功用 result,失败用 "Error: ...")。抽成纯函数以便单测。
+ */
+export function toolResultToBlock(result) {
+    const block = {
+        type: "tool_result",
+        tool_use_id: result.id,
+        content: result.error
+            ? `Error: ${result.error}`
+            : result.contentBlocks ?? (result.result ?? "(no output)"),
+    };
+    if (result.isError || result.error)
+        block.is_error = true;
+    return block;
+}
 export class TurnLoop {
     deps;
     config;
@@ -26,6 +48,12 @@ export class TurnLoop {
     currentTurnLog = logger;
     /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
     lastCtxEmit = -1;
+    /**
+     * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
+     * on any unblocked completion. When it reaches config.maxStopBlocks the
+     * loop forces a stop so a stuck goal can't loop forever.
+     */
+    stopBlockCount = 0;
     constructor(deps, config) {
         this.deps = deps;
         this.config = config;
@@ -131,298 +159,486 @@ export class TurnLoop {
         let messages = [...initialMessages];
         let finalText = "";
         const budgetTracker = createBudgetTracker();
-        while (this.turnCount < this.config.maxTurns) {
-            this.turnCount++;
-            const state = initialTurnState(this.turnCount);
-            // Per-turn correlation ID. Every log written through `tlog` (or any
-            // child derived from it) is stamped with `turn` + `turnId`, so
-            // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
-            // Span is *not* used for the loop itself because there are 6+ early
-            // returns; instead, each return-causing branch logs its own terminal
-            // event (model_error, completed, etc.).
-            const turnId = newTurnId();
-            const tlog = logger.child({ turn: this.turnCount, turnId });
-            this.currentTurnLog = tlog;
-            const turnStartedAt = Date.now();
-            tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
-            // Tag downstream tool-exec / permission lines with this turn's IDs.
-            this.deps.toolExecutor.setLogger(tlog);
-            this.config.onStream?.({ type: "stream_request_start", turnNumber: this.turnCount });
-            const turnStartHook = await this.emitHook("on_turn_start", {
-                turnNumber: this.turnCount,
-            });
-            const turnStartInjection = wrapHookMessages(turnStartHook.messages);
-            if (turnStartInjection) {
-                messages.push(turnStartInjection);
-            }
-            // Approaching max turns: inject a warning so the model can wrap up
-            const turnsRemaining = this.config.maxTurns - this.turnCount;
-            if (turnsRemaining === 2) {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>Warning: you have only 2 turns remaining before the turn limit is reached. " +
-                        "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
-                });
-            }
-            else if (turnsRemaining === 0) {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>This is your LAST turn. You MUST respond with a final text summary now. " +
-                        "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
-                });
-            }
-            // Pre-check: context management (async — may trigger LLM summarization)
-            messages = await this.deps.contextManager.manageAsync(messages);
-            // No pre-llm ctx emit here: the messages-only estimate would be ~16k
-            // smaller than the real prompt (system + tools not included), making
-            // the bar visibly drop on every submit. Post-llm/post-tool-result
-            // events carry an accurate value; if compaction shrank the array, the
-            // dedicated context_compact event has already informed the UI.
-            // post_compact hook: ContextManager just finished a manage() pass.
-            // If any non-micro tier fired, give handlers a chance to inject a
-            // <system-reminder> ("context was compacted — recall earlier
-            // decisions from the transcript") into THIS turn before the model
-            // call. Microcompact is lossless (just clearing redundant
-            // tool_results) so we suppress hook emits for it to keep token
-            // overhead down.
-            const pending = this.deps.consumePendingCompactInfo?.();
-            if (pending && pending.strategy !== "micro") {
-                const compactHook = await this.emitHook("post_compact", {
-                    strategy: pending.strategy,
-                    beforeTokens: pending.before,
-                    afterTokens: pending.after,
+        // Goal-mode run-scoped budget tracker (P0). Null when no goal. Stamps a
+        // wall-clock start now and accumulates prompt+completion tokens across
+        // every turn; the guardrail below force-stops the run once any configured
+        // budget is blown — the unattended-safety backstop.
+        const goalTracker = this.config.goal
+            ? createGoalBudgetTracker(this.config.goal, Date.now())
+            : null;
+        // run() must never reject: the engine's post-run bookkeeping (saveState
+        // with the terminal reason, on_session_end hook) runs AFTER this call and
+        // outside the engine's try, so a throw here would leave the session
+        // frozen at status "active" on disk. Per-turn errors are already turned
+        // into return-reasons by callModelWithFallback; this outer guard catches
+        // throws from the surrounding scaffolding (contextManager.manageAsync,
+        // hook emits, guards) and surfaces them as a model_error result.
+        try {
+            while (this.turnCount < this.config.maxTurns) {
+                this.turnCount++;
+                // Abort fast-path: bail at the loop TOP before doing any per-turn work.
+                // Without this, an aborted child (parent abort, or the 30min per-call
+                // registry timeout) would run a full contextManager.manageAsync (itself
+                // an LLM summarization call) + model call + tool batch before the
+                // post-model check at the bottom of the loop noticed — exactly the
+                // sub-agent leak where a synchronous child kept burning turns/tokens for
+                // minutes after the parent Agent call already returned. The model call's
+                // own signal check only fires AFTER the call resolves; this guards the
+                // boundary between turns. (Mirrors Claude Code's query.ts, where the
+                // aborted check short-circuits before re-entering the streaming loop.)
+                if (this.config.signal?.aborted) {
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                const state = initialTurnState(this.turnCount);
+                // Per-turn correlation ID. Every log written through `tlog` (or any
+                // child derived from it) is stamped with `turn` + `turnId`, so
+                // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
+                // Span is *not* used for the loop itself because there are 6+ early
+                // returns; instead, each return-causing branch logs its own terminal
+                // event (model_error, completed, etc.).
+                const turnId = newTurnId();
+                const tlog = logger.child({ turn: this.turnCount, turnId });
+                this.currentTurnLog = tlog;
+                const turnStartedAt = Date.now();
+                tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
+                // Tag downstream tool-exec / permission lines with this turn's IDs.
+                this.deps.toolExecutor.setLogger(tlog);
+                this.config.onStream?.({ type: "stream_request_start", turnNumber: this.turnCount });
+                const turnStartHook = await this.emitHook("on_turn_start", {
+                    turnNumber: this.turnCount,
                 });
-                const compactInjection = wrapHookMessages(compactHook.messages);
-                if (compactInjection) {
-                    messages.push(compactInjection);
+                const turnStartInjection = wrapHookMessages(turnStartHook.messages);
+                if (turnStartInjection) {
+                    messages.push(turnStartInjection);
                 }
-            }
-            // Model call (with streaming fallback and max_output_tokens continuation)
-            // Track tool IDs streamed during this turn to avoid duplicate UI events
-            this.streamedToolIds.clear();
-            // Streaming tool queue: start concurrency-safe tools during streaming
-            const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
-            let response;
-            try {
-                response = await this.callModelWithFallback(messages);
-            }
-            catch (err) {
-                if (err instanceof ContextLimitError) {
-                    // Progressive recovery: drop oldest API rounds, up to 3 retries
-                    const { dropOldestRounds } = await import("../context/compaction.js");
-                    let recovered = false;
-                    for (let retry = 1; retry <= 3; retry++) {
-                        tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
-                        messages = dropOldestRounds(messages, retry);
+                // Approaching max turns: inject a warning so the model can wrap up
+                const turnsRemaining = this.config.maxTurns - this.turnCount;
+                if (turnsRemaining === 2) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Warning: you have only 2 turns remaining before the turn limit is reached. " +
+                            "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
+                    });
+                }
+                else if (turnsRemaining === 0) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>This is your LAST turn. You MUST respond with a final text summary now. " +
+                            "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
+                    });
+                }
+                // Pre-check: context management (async — may trigger LLM summarization)
+                messages = await this.deps.contextManager.manageAsync(messages);
+                // manageAsync can itself issue an LLM summarization call lasting several
+                // seconds; if the signal aborted during it, stop here rather than
+                // proceeding into the (expensive) main model call. Belt to the loop-top
+                // brace: this catches an abort that landed *inside* context management.
+                if (this.config.signal?.aborted) {
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                // No pre-llm ctx emit here: the messages-only estimate would be ~16k
+                // smaller than the real prompt (system + tools not included), making
+                // the bar visibly drop on every submit. Post-llm/post-tool-result
+                // events carry an accurate value; if compaction shrank the array, the
+                // dedicated context_compact event has already informed the UI.
+                // post_compact hook: ContextManager just finished a manage() pass.
+                // If any non-micro tier fired, give handlers a chance to inject a
+                // <system-reminder> ("context was compacted — recall earlier
+                // decisions from the transcript") into THIS turn before the model
+                // call. Microcompact is lossless (just clearing redundant
+                // tool_results) so we suppress hook emits for it to keep token
+                // overhead down.
+                const pending = this.deps.consumePendingCompactInfo?.();
+                if (pending && pending.strategy !== "micro") {
+                    const compactHook = await this.emitHook("post_compact", {
+                        strategy: pending.strategy,
+                        beforeTokens: pending.before,
+                        afterTokens: pending.after,
+                    });
+                    const compactInjection = wrapHookMessages(compactHook.messages);
+                    if (compactInjection) {
+                        messages.push(compactInjection);
+                    }
+                }
+                // Model call (with streaming fallback and max_output_tokens continuation)
+                // Track tool IDs streamed during this turn to avoid duplicate UI events
+                this.streamedToolIds.clear();
+                // Streaming tool queue: start concurrency-safe tools during streaming
+                const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
+                let response;
+                try {
+                    response = await this.callModelWithFallback(messages);
+                }
+                catch (err) {
+                    if (err instanceof ContextLimitError) {
+                        // Progressive recovery: drop oldest API rounds, up to 3 retries
+                        const { dropOldestRounds } = await import("../context/compaction.js");
+                        let recovered = false;
+                        for (let retry = 1; retry <= 3; retry++) {
+                            tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
+                            messages = dropOldestRounds(messages, retry);
+                            try {
+                                response = await this.callModelWithFallback(messages);
+                                recovered = true;
+                                break;
+                            }
+                            catch (retryErr) {
+                                if (!(retryErr instanceof ContextLimitError)) {
+                                    this.config.onStream?.({ type: "error", error: retryErr.message });
+                                    return { text: finalText, reason: "model_error", messages };
+                                }
+                            }
+                        }
+                        if (!recovered) {
+                            this.patchOrphanedToolUses(messages);
+                            this.config.onStream?.({
+                                type: "error",
+                                error: "Context limit exceeded after 3 recovery attempts",
+                            });
+                            return { text: finalText, reason: "prompt_too_long", messages };
+                        }
+                    }
+                    else {
+                        this.patchOrphanedToolUses(messages);
+                        this.config.onStream?.({ type: "error", error: err.message });
+                        return { text: finalText, reason: "model_error", messages };
+                    }
+                }
+                // UI ctx bar: prefer the provider's authoritative promptTokens.
+                if (response.usage?.promptTokens !== undefined) {
+                    this.emitCtxFromUsage(response.usage.promptTokens, messages);
+                }
+                // Feed actual token usage back to the context manager so subsequent
+                // compaction decisions use hybrid (actual + delta) estimation rather than
+                // pure heuristics. Without this the manager falls back to char/4 estimates.
+                if (response.usage?.promptTokens !== undefined) {
+                    this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
+                }
+                // Truncation that cut off a TOOL CALL: the model overflowed
+                // max_output_tokens mid tool-call, so the arg JSON is incomplete (e.g. a
+                // Write whose `content` was clipped, leaving file_path unset). Executing
+                // it raised a misleading "Missing required parameter: file_path". Instead,
+                // tell the model its output was truncated and let the next turn retry —
+                // bounded by the outer maxTurns loop.
+                if (isTruncatedStop(response.stopReason) && response.toolCalls.length > 0) {
+                    tlog.info("turn.truncated_tool_call", {
+                        cat: "turn",
+                        toolCount: response.toolCalls.length,
+                    });
+                    if (response.text) {
+                        messages.push({ role: "assistant", content: response.text });
+                    }
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Your previous response was truncated by the max output token limit before the tool call finished, so its arguments are incomplete. Do not assume it ran. Either retry with a smaller/more focused tool call (e.g. write the file in sections via Edit), or raise this model's maxOutputTokens.</system-reminder>",
+                    });
+                    continue;
+                }
+                // Handle max_output_tokens: if response was truncated, do continuation
+                // (up to 3 times). Truncation is reported as finish_reason "length"
+                // (OpenAI) or stop_reason "max_tokens" (Anthropic) — isTruncatedStop
+                // accepts both, so the OpenAI streaming path triggers continuation too.
+                if (isTruncatedStop(response.stopReason) &&
+                    response.toolCalls.length === 0 &&
+                    response.text) {
+                    let combinedText = response.text;
+                    for (let retry = 0; retry < 3; retry++) {
+                        // Don't fire another continuation call if the user cancelled — without
+                        // this an abort during a truncated response could still issue up to 3
+                        // more model calls, emitting text after Stop.
+                        if (this.config.signal?.aborted)
+                            break;
+                        tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
+                        const contMessages = [
+                            ...messages,
+                            { role: "assistant", content: combinedText },
+                            {
+                                role: "user",
+                                content: "<system-reminder>Your previous response was truncated due to length. Please continue from where you left off.</system-reminder>",
+                            },
+                        ];
                         try {
-                            response = await this.callModelWithFallback(messages);
-                            recovered = true;
+                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
+                            combinedText += contResponse.text;
+                            if (!isTruncatedStop(contResponse.stopReason) || contResponse.toolCalls.length > 0) {
+                                response = { ...contResponse, text: combinedText };
+                                break;
+                            }
+                        }
+                        catch {
                             break;
                         }
-                        catch (retryErr) {
-                            if (!(retryErr instanceof ContextLimitError)) {
-                                this.config.onStream?.({ type: "error", error: retryErr.message });
-                                return { text: finalText, reason: "model_error", messages };
-                            }
+                    }
+                    response = { ...response, text: combinedText };
+                }
+                // After any continuation, send latest usage so ctx bar reflects real context
+                if (response.usage?.promptTokens !== undefined) {
+                    this.emitCtxFromUsage(response.usage.promptTokens, messages);
+                }
+                // Goal-mode run-scoped accounting: add this turn's total token usage
+                // (prompt + completion) to the running total. Done after continuation so
+                // continued output is counted against the budget.
+                if (goalTracker && response.usage) {
+                    const used = (response.usage.promptTokens ?? 0) + (response.usage.completionTokens ?? 0);
+                    recordGoalUsage(goalTracker, used);
+                }
+                // Aborted?
+                if (this.config.signal?.aborted) {
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                // Accumulate text
+                if (response.text) {
+                    finalText = response.text;
+                }
+                // Goal budget guardrail (P0): a run that has blown its token/time budget
+                // is force-stopped regardless of what the model wants to do next (stop OR
+                // continue with tool calls). This is the unattended-safety backstop, so
+                // it sits BEFORE the "tool calls?" branch — both paths pass the gate.
+                if (goalTracker && goalBudgetExceeded(goalTracker, Date.now())) {
+                    tlog.info("turn.goal_budget_exhausted", {
+                        cat: "goal",
+                        tokensUsed: goalTracker.tokensUsed,
+                        tokenBudget: this.config.goal?.tokenBudget,
+                        timeBudgetMs: this.config.goal?.timeBudgetMs,
+                    });
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: {
+                            role: "assistant",
+                            content: "（Goal 预算已耗尽，强制停止。）",
+                        },
+                    });
+                    return { text: finalText, reason: "goal_budget_exhausted", messages };
+                }
+                // Post-check: tool calls?
+                if (response.toolCalls.length === 0) {
+                    // No tool use — final answer
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: { role: "assistant", content: finalText },
+                    });
+                    await this.emitHook("on_turn_end", {
+                        turnNumber: this.turnCount,
+                        hasToolUse: false,
+                    });
+                    messages.push({ role: "assistant", content: finalText });
+                    // on_stop seam: the model wants to stop. Give handlers (Goal mode)
+                    // a chance to BLOCK termination and keep the agent working. A
+                    // handler returning continueSession=true injects its messages and
+                    // we run another turn instead of returning. Bounded by
+                    // maxStopBlocks (consecutive) and the outer maxTurns ceiling.
+                    const maxStopBlocks = this.config.maxStopBlocks ?? 8;
+                    const stopHook = await this.emitHook("on_stop", {
+                        goal: this.config.goal,
+                        finalText,
+                        turnCount: this.turnCount,
+                    });
+                    // The judge's structured verdict (set by GoalStopHook in result.data)
+                    // rides back here so we can show goal progress WITHOUT a second LLM
+                    // call — `gaps` is whatever the judge already computed.
+                    const goalVerdict = stopHook.data?.goalVerdict;
+                    if (stopHook.continueSession && this.stopBlockCount < maxStopBlocks) {
+                        this.stopBlockCount++;
+                        // Goal visibility: one not_met marker per re-prompt. round counts
+                        // up with stopBlockCount so the UI can show "第 N 轮".
+                        this.config.onStream?.({
+                            type: "goal_progress",
+                            status: "not_met",
+                            round: this.stopBlockCount,
+                            gaps: goalVerdict?.gaps || undefined,
+                        });
+                        const injection = wrapHookMessages(stopHook.messages);
+                        if (injection) {
+                            messages.push(injection);
+                        }
+                        else {
+                            // No guidance from the handler — inject a generic nudge so the
+                            // model knows it must keep going rather than re-emitting the
+                            // same final answer.
+                            messages.push({
+                                role: "user",
+                                content: "<system-reminder>The goal is not yet complete. Continue working toward it.</system-reminder>",
+                            });
                         }
+                        tlog.info("turn.stop_blocked", {
+                            cat: "turn",
+                            stopBlockCount: this.stopBlockCount,
+                            maxStopBlocks,
+                            hasGuidance: !!injection,
+                        });
+                        continue;
                     }
-                    if (!recovered) {
-                        this.patchOrphanedToolUses(messages);
+                    if (stopHook.continueSession && this.stopBlockCount >= maxStopBlocks) {
+                        // Cap hit: stop anyway, but tell the user why we're not looping
+                        // forever on an unsatisfiable goal.
+                        tlog.info("turn.stop_block_cap", {
+                            cat: "turn",
+                            stopBlockCount: this.stopBlockCount,
+                            maxStopBlocks,
+                        });
                         this.config.onStream?.({
-                            type: "error",
-                            error: "Context limit exceeded after 3 recovery attempts",
+                            type: "goal_progress",
+                            status: "exhausted",
+                            round: this.stopBlockCount,
+                        });
+                        this.config.onStream?.({
+                            type: "assistant_message",
+                            message: {
+                                role: "assistant",
+                                content: `（Goal 续跑已达 ${maxStopBlocks} 次上限，先停下。）`,
+                            },
                         });
-                        return { text: finalText, reason: "prompt_too_long", messages };
                     }
+                    else if (this.config.goal && goalVerdict?.met) {
+                        // Goal run completed cleanly: the judge says met. round = total
+                        // rounds = prior blocks + this accepted final round.
+                        this.config.onStream?.({
+                            type: "goal_progress",
+                            status: "met",
+                            round: this.stopBlockCount + 1,
+                        });
+                    }
+                    this.stopBlockCount = 0;
+                    return { text: finalText, reason: "completed", messages };
                 }
-                else {
-                    this.patchOrphanedToolUses(messages);
-                    this.config.onStream?.({ type: "error", error: err.message });
-                    return { text: finalText, reason: "model_error", messages };
+                // Tool execution phase
+                tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
+                const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
+                // Add assistant message with tool_use blocks to messages
+                const assistantBlocks = [];
+                if (response.text) {
+                    assistantBlocks.push({ type: "text", text: response.text });
                 }
-            }
-            // UI ctx bar: prefer the provider's authoritative promptTokens.
-            if (response.usage?.promptTokens !== undefined) {
-                this.emitCtxFromUsage(response.usage.promptTokens, messages);
-            }
-            // Feed actual token usage back to the context manager so subsequent
-            // compaction decisions use hybrid (actual + delta) estimation rather than
-            // pure heuristics. Without this the manager falls back to char/4 estimates.
-            if (response.usage?.promptTokens !== undefined) {
-                this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
-            }
-            // Handle max_output_tokens: if response was truncated, do continuation (up to 3 times)
-            if (response.stopReason === "max_tokens" &&
-                response.toolCalls.length === 0 &&
-                response.text) {
-                let combinedText = response.text;
-                for (let retry = 0; retry < 3; retry++) {
-                    tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
-                    const contMessages = [
-                        ...messages,
-                        { role: "assistant", content: combinedText },
-                        {
-                            role: "user",
-                            content: "<system-reminder>Your previous response was truncated due to length. Please continue from where you left off.</system-reminder>",
-                        },
-                    ];
-                    try {
-                        const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
-                        combinedText += contResponse.text;
-                        if (contResponse.stopReason !== "max_tokens" || contResponse.toolCalls.length > 0) {
-                            response = { ...contResponse, text: combinedText };
-                            break;
-                        }
+                for (const tc of toolCalls) {
+                    assistantBlocks.push({
+                        type: "tool_use",
+                        id: tc.id,
+                        name: tc.toolName,
+                        input: tc.args,
+                    });
+                    // Only emit tool_use_start if not already emitted during streaming
+                    if (!this.streamedToolIds.has(tc.id)) {
+                        this.config.onStream?.({ type: "tool_use_start", toolCall: tc });
                     }
-                    catch {
-                        break;
+                    // Record in transcript
+                    this.deps.transcript.appendToolUse(tc.toolName, tc.id, tc.args);
+                }
+                messages.push({ role: "assistant", content: assistantBlocks });
+                // Execute tools — enqueue concurrency-safe tools for early start,
+                // drain remaining (unsafe) tools sequentially.
+                for (const tc of toolCalls) {
+                    streamingQueue.enqueue(tc);
+                }
+                const results = await streamingQueue.drain();
+                // Record results in transcript and stream
+                const resultBlocks = [];
+                for (const result of results) {
+                    resultBlocks.push(toolResultToBlock(result));
+                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
+                    this.config.onStream?.({ type: "tool_result", result });
+                }
+                // Fire-and-forget tool use summary (non-blocking)
+                if (this.config.onStream) {
+                    import("./tool-summary.js").then(({ generateToolUseSummary }) => {
+                        if (!this.deps.model.summarize)
+                            return;
+                        generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
+                            if (summary) {
+                                this.config.onStream?.({ type: "tool_summary", summary });
+                            }
+                        });
+                    });
+                }
+                messages.push({ role: "user", content: resultBlocks });
+                // Tool results just pushed; recompute ctx so the bar updates *before*
+                // the next model round-trip — large tool outputs can move it sharply.
+                this.emitCtxFromMessages(messages);
+                // Goal mode P0: explicit completion. If the model called complete_goal,
+                // it has DECLARED the goal done — short-circuit to "completed" WITHOUT
+                // running the judge hook. The tool's result is already in `messages`
+                // above so the summary lands in the transcript. Reset the stop-block
+                // counter so a prior judge-driven block streak doesn't leak out.
+                if (goalTracker && toolCalls.some((tc) => tc.toolName === COMPLETE_GOAL_TOOL_NAME)) {
+                    tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
+                    this.stopBlockCount = 0;
+                    return { text: finalText, reason: "completed", messages };
+                }
+                // Token budget check
+                const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
+                const budgetDecision = checkTokenBudget(totalOutputTokens, this.config.tokenBudget ?? Infinity, budgetTracker);
+                if (budgetDecision === "stop") {
+                    tlog.info("turn.budget_stop", {
+                        cat: "turn",
+                        outputTokens: totalOutputTokens,
+                        budget: this.config.tokenBudget,
+                    });
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: { role: "assistant", content: finalText },
+                    });
+                    messages.push({ role: "assistant", content: finalText });
+                    return { text: finalText, reason: "completed", messages };
+                }
+                if (budgetDecision === "nudge") {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>You are approaching the token budget limit. Please start wrapping up your work and provide a summary.</system-reminder>",
+                    });
+                }
+                // Investigation guard: end-of-turn check. If too many consecutive
+                // read-only turns went by without any user-visible text or side-effecting
+                // tool, inject a reminder that will land at the top of the next turn.
+                const guard = this.deps.toolExecutor.getInvestigationGuard();
+                if (guard) {
+                    guard.noteText(response.text);
+                    const turnReminder = guard.turnEnded(this.turnCount);
+                    if (turnReminder) {
+                        messages.push({ role: "user", content: turnReminder });
+                        tlog.info("guard.silent_turn", { cat: "guard", turn: this.turnCount });
                     }
                 }
-                response = { ...response, text: combinedText };
-            }
-            // After any continuation, send latest usage so ctx bar reflects real context
-            if (response.usage?.promptTokens !== undefined) {
-                this.emitCtxFromUsage(response.usage.promptTokens, messages);
-            }
-            // Aborted?
-            if (this.config.signal?.aborted) {
-                return { text: finalText, reason: "aborted_streaming", messages };
-            }
-            // Accumulate text
-            if (response.text) {
-                finalText = response.text;
-            }
-            // Post-check: tool calls?
-            if (response.toolCalls.length === 0) {
-                // No tool use — final answer
-                this.config.onStream?.({
-                    type: "assistant_message",
-                    message: { role: "assistant", content: finalText },
-                });
+                // Task guard: nudge the model if it has an in_progress task that
+                // hasn't moved in several turns. TaskCreate is sticky in working
+                // memory for the first few turns only; without this, the spinner
+                // runs forever on tasks the model has mentally finished.
+                const taskGuard = this.deps.toolExecutor.getTaskGuard();
+                if (taskGuard) {
+                    const taskReminder = taskGuard.turnEnded(this.turnCount);
+                    if (taskReminder) {
+                        messages.push({ role: "user", content: taskReminder });
+                        tlog.info("guard.stale_task", { cat: "guard", turn: this.turnCount });
+                    }
+                }
+                // Hook: turn end
                 await this.emitHook("on_turn_end", {
                     turnNumber: this.turnCount,
-                    hasToolUse: false,
+                    hasToolUse: true,
+                    toolCallCount: toolCalls.length,
                 });
-                messages.push({ role: "assistant", content: finalText });
-                return { text: finalText, reason: "completed", messages };
-            }
-            // Tool execution phase
-            tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
-            const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
-            // Add assistant message with tool_use blocks to messages
-            const assistantBlocks = [];
-            if (response.text) {
-                assistantBlocks.push({ type: "text", text: response.text });
-            }
-            for (const tc of toolCalls) {
-                assistantBlocks.push({
-                    type: "tool_use",
-                    id: tc.id,
-                    name: tc.toolName,
-                    input: tc.args,
-                });
-                // Only emit tool_use_start if not already emitted during streaming
-                if (!this.streamedToolIds.has(tc.id)) {
-                    this.config.onStream?.({ type: "tool_use_start", toolCall: tc });
-                }
-                // Record in transcript
-                this.deps.transcript.appendToolUse(tc.toolName, tc.id, tc.args);
-            }
-            messages.push({ role: "assistant", content: assistantBlocks });
-            // Execute tools — enqueue concurrency-safe tools for early start,
-            // drain remaining (unsafe) tools sequentially.
-            for (const tc of toolCalls) {
-                streamingQueue.enqueue(tc);
-            }
-            const results = await streamingQueue.drain();
-            // Record results in transcript and stream
-            const resultBlocks = [];
-            for (const result of results) {
-                const content = result.error ? `Error: ${result.error}` : (result.result ?? "(no output)");
-                resultBlocks.push({
-                    type: "tool_result",
-                    tool_use_id: result.id,
-                    content,
-                });
-                this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
-                this.config.onStream?.({ type: "tool_result", result });
-            }
-            // Fire-and-forget tool use summary (non-blocking)
-            if (this.config.onStream) {
-                import("./tool-summary.js").then(({ generateToolUseSummary }) => {
-                    if (!this.deps.model.summarize)
-                        return;
-                    generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
-                        if (summary) {
-                            this.config.onStream?.({ type: "tool_summary", summary });
-                        }
-                    });
-                });
-            }
-            messages.push({ role: "user", content: resultBlocks });
-            // Tool results just pushed; recompute ctx so the bar updates *before*
-            // the next model round-trip — large tool outputs can move it sharply.
-            this.emitCtxFromMessages(messages);
-            // Token budget check
-            const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
-            const budgetDecision = checkTokenBudget(totalOutputTokens, this.config.tokenBudget ?? Infinity, budgetTracker);
-            if (budgetDecision === "stop") {
-                tlog.info("turn.budget_stop", {
+                // Record turn boundary
+                this.deps.transcript.appendTurnBoundary();
+                this.config.onTurnBoundary?.(this.turnCount);
+                tlog.info("turn.end", {
                     cat: "turn",
-                    outputTokens: totalOutputTokens,
-                    budget: this.config.tokenBudget,
-                });
-                this.config.onStream?.({
-                    type: "assistant_message",
-                    message: { role: "assistant", content: finalText },
+                    duration_ms: Date.now() - turnStartedAt,
+                    outcome: "continue",
                 });
-                messages.push({ role: "assistant", content: finalText });
-                return { text: finalText, reason: "completed", messages };
-            }
-            if (budgetDecision === "nudge") {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>You are approaching the token budget limit. Please start wrapping up your work and provide a summary.</system-reminder>",
-                });
-            }
-            // Investigation guard: end-of-turn check. If too many consecutive
-            // read-only turns went by without any user-visible text or side-effecting
-            // tool, inject a reminder that will land at the top of the next turn.
-            const guard = this.deps.toolExecutor.getInvestigationGuard();
-            if (guard) {
-                guard.noteText(response.text);
-                const turnReminder = guard.turnEnded(this.turnCount);
-                if (turnReminder) {
-                    messages.push({ role: "user", content: turnReminder });
-                    tlog.info("guard.silent_turn", { cat: "guard", turn: this.turnCount });
-                }
             }
-            // Task guard: nudge the model if it has an in_progress task that
-            // hasn't moved in several turns. TaskCreate is sticky in working
-            // memory for the first few turns only; without this, the spinner
-            // runs forever on tasks the model has mentally finished.
-            const taskGuard = this.deps.toolExecutor.getTaskGuard();
-            if (taskGuard) {
-                const taskReminder = taskGuard.turnEnded(this.turnCount);
-                if (taskReminder) {
-                    messages.push({ role: "user", content: taskReminder });
-                    tlog.info("guard.stale_task", { cat: "guard", turn: this.turnCount });
-                }
-            }
-            // Hook: turn end
-            await this.emitHook("on_turn_end", {
-                turnNumber: this.turnCount,
-                hasToolUse: true,
-                toolCallCount: toolCalls.length,
-            });
-            // Record turn boundary
-            this.deps.transcript.appendTurnBoundary();
-            this.config.onTurnBoundary?.(this.turnCount);
-            tlog.info("turn.end", {
+        }
+        catch (err) {
+            // Unexpected throw from the per-turn scaffolding (manageAsync, hooks,
+            // guards). Patch any dangling tool_use so a later resume isn't poisoned,
+            // surface the error to the UI, and return a terminal reason so the
+            // engine's post-run saveState records model_error instead of leaving
+            // the session stuck at "active".
+            this.patchOrphanedToolUses(messages);
+            this.currentTurnLog.error("turn.unhandled_error", {
                 cat: "turn",
-                duration_ms: Date.now() - turnStartedAt,
-                outcome: "continue",
+                error: err.message,
+                stack: err.stack?.split("\n").slice(0, 4).join("\n"),
             });
+            this.config.onStream?.({ type: "error", error: err.message });
+            return { text: finalText, reason: "model_error", messages };
         }
         // Max turns reached — do one final summarization call (no tools)
         logger.warn("turn.max_turns_reached", {
@@ -464,6 +680,7 @@ export class TurnLoop {
     async callModelWithFallback(messages) {
         // Wrap stream callback to track tool_use_start events and reactive compaction
         let streamingResponseTokens = 0;
+        let reactiveBucket = -1;
         const wrappedStream = this.config.onStream
             ? (event) => {
                 if (event.type === "tool_use_start" && event.toolCall?.id) {
@@ -474,8 +691,12 @@ export class TurnLoop {
                     streamingResponseTokens += Math.ceil(event.text.length / 4);
                 }
                 // Reactive compaction warning: if nearing context limit mid-stream,
-                // log a warning (actual compaction happens between turns)
-                if (streamingResponseTokens > 0 && streamingResponseTokens % 2000 === 0) {
+                // log a warning (actual compaction happens between turns). Gated to
+                // fire once per 2000-token bucket crossed — the old `% 2000 === 0`
+                // check essentially never matched the running accumulator.
+                const probe = crossedReactiveThreshold(streamingResponseTokens, reactiveBucket);
+                if (probe.crossed) {
+                    reactiveBucket = probe.bucket;
                     if (this.deps.contextManager.shouldReactiveCompact(messages, streamingResponseTokens)) {
                         this.currentTurnLog.warn("turn.reactive_compact_warning", {
                             cat: "turn",
@@ -494,6 +715,12 @@ export class TurnLoop {
             // If it's a context or rate limit error, don't fallback — propagate
             if (err instanceof ContextLimitError)
                 throw err;
+            // User cancelled (ESC / Stop / run signal). Falling back to a
+            // non-streaming call here re-sends the whole request the user just
+            // aborted. Propagate so the run unwinds cleanly instead of doing
+            // more work after cancellation.
+            if (isAbortError(err))
+                throw err;
             // Streaming might have partially emitted — send tombstone to revoke
             this.config.onStream?.({ type: "tombstone", messageId: `turn_${this.turnCount}` });
             this.currentTurnLog.warn("turn.streaming_fallback", {
@@ -504,51 +731,6 @@ export class TurnLoop {
             return await this.deps.model.callWithoutStreaming(this.deps.systemPrompt, messages, this.deps.tools, this.config.signal);
         }
     }
-    /**
-     * Execute tools with overlap: start concurrent-safe (read-only) tools
-     * immediately in parallel while sequential (write) tools run one-by-one.
-     * Both groups run simultaneously — we don't wait for safe tools to finish
-     * before starting unsafe ones.
-     */
-    async executeToolsOverlapped(calls) {
-        if (calls.length <= 1) {
-            // Single tool — no overlap needed
-            return this.deps.toolExecutor.executeAll(calls);
-        }
-        const safe = [];
-        const unsafe = [];
-        for (const call of calls) {
-            if (this.deps.toolExecutor.isConcurrencySafe(call.toolName)) {
-                safe.push(call);
-            }
-            else {
-                unsafe.push(call);
-            }
-        }
-        // If all same type, delegate directly
-        if (safe.length === 0 || unsafe.length === 0) {
-            return this.deps.toolExecutor.executeAll(calls);
-        }
-        // Run both groups simultaneously:
-        // - safe tools all in parallel
-        // - unsafe tools sequentially (but started at the same time as safe group)
-        const resultMap = new Map();
-        const safePromise = Promise.all(safe.map((c) => this.deps.toolExecutor.executeSingle(c)));
-        const unsafePromise = (async () => {
-            const results = [];
-            for (const call of unsafe) {
-                results.push(await this.deps.toolExecutor.executeSingle(call));
-            }
-            return results;
-        })();
-        const [safeResults, unsafeResults] = await Promise.all([safePromise, unsafePromise]);
-        for (const r of safeResults)
-            resultMap.set(r.id, r);
-        for (const r of unsafeResults)
-            resultMap.set(r.id, r);
-        // Return results in original call order for deterministic transcript
-        return calls.map((c) => resultMap.get(c.id));
-    }
     get currentTurn() {
         return this.turnCount;
     }