@cjhyy/code-shell-core 0.7.0 → 0.7.1

package/dist/engine/goal.d.ts

@@ -47,8 +47,10 @@ export interface GoalConfig {
      */
     setAtMs?: number;
 }
-/** A forced terminal outcome for one concrete persisted goal instance. */
-export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exhausted" | "time_budget_exhausted" | "max_turns_exhausted";
+/** A forced stop outcome for a Goal run. Some outcomes intentionally preserve the Goal. */
+export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exhausted" | "time_budget_exhausted" | "max_turns_exhausted" | "judge_prompt_too_large";
+/** Outcomes that permanently close one concrete persisted Goal instance. */
+export type PersistedGoalTerminationReason = Exclude<GoalTerminationReason, "judge_prompt_too_large">;
 /**
  * Persisted terminal marker used to prevent a stale whole-state writer from
  * making an exhausted goal armable again. `objective + setAtMs` is the goal
@@ -57,7 +59,7 @@ export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exha
 export interface GoalTerminal {
     objective: string;
     setAtMs?: number;
-    reason: GoalTerminationReason;
+    reason: PersistedGoalTerminationReason;
     terminatedAtMs?: number;
 }
 /** True only when both values identify the same concrete goal instance. */

package/dist/engine/session-title.d.ts

@@ -5,9 +5,10 @@
  * resolves the aux client and wiring; this only does the LLM call + cleanup.
  */
 import type { LLMClientBase } from "../llm/client-base.js";
+import type { TokenUsage } from "../types.js";
 /**
  * Ask the aux client for a one-line title from the first user message + first
  * assistant reply. Returns the cleaned title, or null on any failure / empty
  * output (caller treats null as "keep existing title").
  */
-export declare function buildSessionTitle(client: LLMClientBase, firstUserText: string, firstAssistantText: string): Promise<string | null>;
+export declare function buildSessionTitle(client: LLMClientBase, firstUserText: string, firstAssistantText: string, recordBilledUsage?: (usage: TokenUsage) => void): Promise<string | null>;

package/dist/engine/session-title.js

@@ -13,7 +13,7 @@ function clean(raw) {
  * assistant reply. Returns the cleaned title, or null on any failure / empty
  * output (caller treats null as "keep existing title").
  */
-export async function buildSessionTitle(client, firstUserText, firstAssistantText) {
+export async function buildSessionTitle(client, firstUserText, firstAssistantText, recordBilledUsage) {
     try {
         const prompt = `User: ${firstUserText.slice(0, 2000)}\n\n` +
             `Assistant: ${firstAssistantText.slice(0, 2000)}\n\n` +
@@ -23,8 +23,11 @@ export async function buildSessionTitle(client, firstUserText, firstAssistantTex
             messages: [{ role: "user", content: prompt }],
             tools: [],
             maxTokens: 64,
+            requestVisible: false,
             reasoning: { mode: "off" },
         });
+        if (resp.usage)
+            recordBilledUsage?.(resp.usage);
         const title = clean(resp.text ?? "");
         return title.length > 0 ? title : null;
     }

package/dist/engine/turn-loop.d.ts

@@ -172,6 +172,10 @@ export declare class TurnLoop {
     private readonly sensitiveToolResultRedactions;
     private readonly pendingImageMessages;
     private readonly volatileContextMessages;
+    /** Last outer-loop turn for which the model returned a complete response. */
+    private lastCompletedModelTurn;
+    /** Last model turn whose transcript/persistence boundary was finalized. */
+    private lastFinalizedTurn;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -204,6 +208,13 @@ export declare class TurnLoop {
         timeBudgetMs?: number;
         maxStopBlocks: number;
     };
+    /**
+     * Private Goal-judge accounting seam. Judge calls bypass ModelFacade, so the
+     * Engine forwards their provider usage here while the run-scoped tracker is
+     * live. The returned reason lets the hook suppress verdict side effects when
+     * this very request crossed a hard token/time budget.
+     */
+    recordGoalJudgeUsage(usage: TokenUsage | undefined): Extract<GoalTerminationReason, "token_budget_exhausted" | "time_budget_exhausted"> | undefined;
     /**
      * Goal mode only: if the run is nearing EITHER stop ceiling (maxTurns or
      * maxStopBlocks) and we haven't announced it yet, emit one approaching_limit
@@ -229,6 +240,13 @@ export declare class TurnLoop {
      * for one Stop still writes a single marker.
      */
     private markStopped;
+    /**
+     * Close one completed model turn exactly once. The transcript boundary must
+     * be durable before the Engine flushes usage, heartbeat, and turnCount via
+     * onTurnBoundary, so crash recovery never folds two assistant responses into
+     * the same transcript turn or observes state ahead of the transcript.
+     */
+    private finalizeModelTurn;
     private prepareMessagesForModel;
     private stripVolatileContextMessages;
     private appendVolatileContextMessages;

package/dist/engine/turn-loop.js

@@ -64,6 +64,10 @@ export class TurnLoop {
     sensitiveToolResultRedactions = new Map();
     pendingImageMessages = new Set();
     volatileContextMessages = new Set();
+    /** Last outer-loop turn for which the model returned a complete response. */
+    lastCompletedModelTurn = 0;
+    /** Last model turn whose transcript/persistence boundary was finalized. */
+    lastFinalizedTurn = 0;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -128,6 +132,20 @@ export class TurnLoop {
         }
         return { ...next, maxStopBlocks: nextCap };
     }
+    /**
+     * Private Goal-judge accounting seam. Judge calls bypass ModelFacade, so the
+     * Engine forwards their provider usage here while the run-scoped tracker is
+     * live. The returned reason lets the hook suppress verdict side effects when
+     * this very request crossed a hard token/time budget.
+     */
+    recordGoalJudgeUsage(usage) {
+        if (!this.goalTracker)
+            return undefined;
+        if (usage) {
+            recordGoalUsage(this.goalTracker, (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0));
+        }
+        return goalBudgetTerminationReason(this.goalTracker, Date.now());
+    }
     /**
      * Goal mode only: if the run is nearing EITHER stop ceiling (maxTurns or
      * maxStopBlocks) and we haven't announced it yet, emit one approaching_limit
@@ -217,6 +235,21 @@ export class TurnLoop {
             return;
         this.deps.transcript.appendTurnStopped();
     }
+    /**
+     * Close one completed model turn exactly once. The transcript boundary must
+     * be durable before the Engine flushes usage, heartbeat, and turnCount via
+     * onTurnBoundary, so crash recovery never folds two assistant responses into
+     * the same transcript turn or observes state ahead of the transcript.
+     */
+    finalizeModelTurn() {
+        if (this.lastCompletedModelTurn !== this.turnCount ||
+            this.lastFinalizedTurn === this.turnCount) {
+            return;
+        }
+        this.lastFinalizedTurn = this.turnCount;
+        this.deps.transcript.appendTurnBoundary();
+        this.config.onTurnBoundary?.(this.turnCount);
+    }
     prepareMessagesForModel(messages) {
         const preserveMessages = this.pendingImageMessages.size > 0 ? this.pendingImageMessages : undefined;
         const result = downgradeImagePayloadsInHistory(messages, { preserveMessages });
@@ -406,13 +439,16 @@ export class TurnLoop {
         // window only after irreversible sensitive-data removal, non-text omission,
         // and per-item truncation at the current-round ToolResult boundary.
         const goalToolResults = [];
+        const sensitiveGoalResultTools = this.config.goal
+            ? new Set(this.deps.tools.filter((tool) => tool.sensitiveResult).map((tool) => tool.name))
+            : undefined;
         // 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.
-        this.goalTracker = this.config.goal
-            ? createGoalBudgetTracker(this.config.goal, Date.now())
-            : null;
+        if (!this.goalTracker && this.config.goal) {
+            this.goalTracker = createGoalBudgetTracker(this.config.goal, Date.now());
+        }
         const goalTracker = this.goalTracker;
         // Fresh run: re-arm the approaching-limit announcement.
         this.approachAnnounced = false;
@@ -425,6 +461,25 @@ export class TurnLoop {
         // hook emits, guards) and surfaces them as a model_error result.
         try {
             while (this.turnCount < this.config.maxTurns) {
+                const preTurnGoalTermination = goalTracker
+                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                    : undefined;
+                if (preTurnGoalTermination) {
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: {
+                            role: "assistant",
+                            content: "（Goal 预算已耗尽，强制停止。）",
+                        },
+                    });
+                    messages = this.redactConsumedSensitiveToolResults(messages);
+                    return {
+                        text: finalText,
+                        reason: "goal_budget_exhausted",
+                        messages,
+                        goalTermination: preTurnGoalTermination,
+                    };
+                }
                 this.turnCount++;
                 this.currentTurnUsage = {
                     promptTokens: 0,
@@ -523,7 +578,7 @@ export class TurnLoop {
                 }
                 else {
                     // Context management (async — may trigger LLM summarization)
-                    messages = await this.deps.contextManager.manageAsync(messages);
+                    messages = await this.deps.contextManager.manageAsync(messages, this.config.signal);
                     // 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
@@ -621,12 +676,22 @@ export class TurnLoop {
                         return { text: finalText, reason: "model_error", messages };
                     }
                 }
+                this.lastCompletedModelTurn = this.turnCount;
                 messages = this.redactConsumedSensitiveToolResults(messages);
                 // Record the response once into current-turn and whole-session counters.
                 if (response.usage?.promptTokens !== undefined) {
                     this.recordResponseUsage(response.usage);
                     this.emitCtxFromUsage(response.usage, messages);
                 }
+                // Charge every provider response to the run-scoped Goal budget before
+                // any truncation path can retry or continue the outer turn loop.
+                if (goalTracker && response.usage) {
+                    const used = (response.usage.promptTokens ?? 0) + (response.usage.completionTokens ?? 0);
+                    recordGoalUsage(goalTracker, used);
+                }
+                let budgetTermination = goalTracker
+                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                    : undefined;
                 // 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.
@@ -637,13 +702,24 @@ export class TurnLoop {
                         this.deps.recordContextUsageAnchor?.(anchor);
                 }
                 messages = this.markPendingImagesConsumed(messages);
+                // stopBlockCount guards only the no-tool final-answer loop evaluated by
+                // on_stop (text -> block -> text -> block). A response that structurally
+                // contains tool_use has left that streak, regardless of whether the call
+                // will execute successfully. Reset here, before truncated-tool and later
+                // queued-steer paths can continue the outer loop. Repeated ineffective
+                // tool_use turns still consume turns and are bounded by maxTurns.
+                if (response.toolCalls.length > 0) {
+                    this.stopBlockCount = 0;
+                }
                 // 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) {
+                if (!budgetTermination &&
+                    isTruncatedStop(response.stopReason) &&
+                    response.toolCalls.length > 0) {
                     tlog.info("turn.truncated_tool_call", {
                         cat: "turn",
                         toolCount: response.toolCalls.length,
@@ -655,13 +731,15 @@ export class TurnLoop {
                         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>",
                     });
+                    this.finalizeModelTurn();
                     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) &&
+                if (!budgetTermination &&
+                    isTruncatedStop(response.stopReason) &&
                     response.toolCalls.length === 0 &&
                     response.text) {
                     let combinedText = response.text;
@@ -672,6 +750,11 @@ export class TurnLoop {
                         // more model calls, emitting text after Stop.
                         if (this.config.signal?.aborted)
                             break;
+                        budgetTermination = goalTracker
+                            ? goalBudgetTerminationReason(goalTracker, Date.now())
+                            : undefined;
+                        if (budgetTermination)
+                            break;
                         tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
                         const contMessages = [
                             ...messages,
@@ -683,18 +766,40 @@ export class TurnLoop {
                         ];
                         try {
                             const contResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(contMessages), this.deps.tools, this.config.onStream, this.config.signal);
+                            // Continuations are separate provider responses, so preserve the
+                            // same structural tool_use invariant before processing this one.
+                            if (contResponse.toolCalls.length > 0) {
+                                this.stopBlockCount = 0;
+                            }
                             if (contResponse.usage?.promptTokens !== undefined) {
                                 this.recordResponseUsage(contResponse.usage);
                                 continuedResponse = true;
                             }
+                            if (goalTracker && contResponse.usage) {
+                                const used = (contResponse.usage.promptTokens ?? 0) +
+                                    (contResponse.usage.completionTokens ?? 0);
+                                recordGoalUsage(goalTracker, used);
+                            }
+                            budgetTermination = goalTracker
+                                ? goalBudgetTerminationReason(goalTracker, Date.now())
+                                : undefined;
                             combinedText += contResponse.text;
-                            if (!isTruncatedStop(contResponse.stopReason) || contResponse.toolCalls.length > 0) {
+                            if (budgetTermination ||
+                                !isTruncatedStop(contResponse.stopReason) ||
+                                contResponse.toolCalls.length > 0) {
                                 response = { ...contResponse, text: combinedText };
                                 break;
                             }
                         }
-                        catch {
-                            break;
+                        catch (err) {
+                            if (isAbortError(err) || this.config.signal?.aborted) {
+                                this.markStopped();
+                                this.finalizeModelTurn();
+                                return { text: finalText, reason: "aborted_streaming", messages };
+                            }
+                            this.config.onStream?.({ type: "error", error: formatFriendlyError(err) });
+                            this.finalizeModelTurn();
+                            return { text: finalText, reason: "model_error", messages };
                         }
                     }
                     response = { ...response, text: combinedText };
@@ -702,16 +807,10 @@ export class TurnLoop {
                         this.emitCtxFromUsage(response.usage, 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) {
                     this.markStopped();
+                    this.finalizeModelTurn();
                     return { text: finalText, reason: "aborted_streaming", messages };
                 }
                 // Accumulate text
@@ -722,8 +821,8 @@ export class TurnLoop {
                 // 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.
-                const budgetTermination = goalTracker
-                    ? goalBudgetTerminationReason(goalTracker, Date.now())
+                budgetTermination = goalTracker
+                    ? (budgetTermination ?? goalBudgetTerminationReason(goalTracker, Date.now()))
                     : undefined;
                 if (goalTracker && budgetTermination) {
                     tlog.info("turn.goal_budget_exhausted", {
@@ -740,6 +839,7 @@ export class TurnLoop {
                             content: "（Goal 预算已耗尽，强制停止。）",
                         },
                     });
+                    this.finalizeModelTurn();
                     return {
                         text: finalText,
                         reason: "goal_budget_exhausted",
@@ -760,6 +860,7 @@ export class TurnLoop {
                         hasToolUse: false,
                     });
                     messages.push({ role: "assistant", content: finalText });
+                    this.finalizeModelTurn();
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
@@ -791,6 +892,57 @@ export class TurnLoop {
                         finalText,
                         turnCount: this.turnCount,
                     });
+                    // The primary-model judge is a real billed request. Its hook forwards
+                    // usage through recordGoalJudgeUsage above; re-check immediately so an
+                    // over-budget verdict cannot authorize another main-model turn.
+                    const hookGoalTermination = stopHook.goalTermination;
+                    const hookBudgetTermination = hookGoalTermination === "token_budget_exhausted" ||
+                        hookGoalTermination === "time_budget_exhausted"
+                        ? hookGoalTermination
+                        : undefined;
+                    const postJudgeBudgetTermination = goalTracker
+                        ? (hookBudgetTermination ?? goalBudgetTerminationReason(goalTracker, Date.now()))
+                        : undefined;
+                    if (goalTracker && postJudgeBudgetTermination) {
+                        tlog.info("turn.goal_budget_exhausted_after_judge", {
+                            cat: "goal",
+                            reason: postJudgeBudgetTermination,
+                            tokensUsed: goalTracker.tokensUsed,
+                            tokenBudget: goalTracker.goal.tokenBudget,
+                            timeBudgetMs: goalTracker.goal.timeBudgetMs,
+                        });
+                        this.config.onStream?.({
+                            type: "assistant_message",
+                            messageId: assistantMessageId,
+                            message: {
+                                role: "assistant",
+                                content: "（Goal 预算已耗尽，强制停止。）",
+                            },
+                        });
+                        return {
+                            text: finalText,
+                            reason: "goal_budget_exhausted",
+                            messages,
+                            goalTermination: postJudgeBudgetTermination,
+                        };
+                    }
+                    if (goalTracker && hookGoalTermination === "judge_prompt_too_large") {
+                        tlog.warn("turn.goal_judge_prompt_too_large", { cat: "goal" });
+                        this.config.onStream?.({
+                            type: "assistant_message",
+                            messageId: assistantMessageId,
+                            message: {
+                                role: "assistant",
+                                content: "（Goal 裁判输入超过安全上限，无法判定；本次已停止，目标已保留。）",
+                            },
+                        });
+                        return {
+                            text: finalText,
+                            reason: "completed",
+                            messages,
+                            goalTermination: hookGoalTermination,
+                        };
+                    }
                     // 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.
@@ -912,11 +1064,14 @@ export class TurnLoop {
                 const resultBlocks = [];
                 for (const result of results) {
                     if (goalTracker) {
-                        goalToolResults.push(projectGoalJudgeToolResult(result, this.turnCount));
-                        // The prompt renderer keeps at most 12, but retaining a few extra
-                        // bounded projections lets its total-char budget choose the newest useful subset.
-                        if (goalToolResults.length > 20)
-                            goalToolResults.splice(0, goalToolResults.length - 20);
+                        goalToolResults.push(projectGoalJudgeToolResult(result, this.turnCount, sensitiveGoalResultTools?.has(result.toolName) === true));
+                        // Never evict the front of one legal batch: the default executor may
+                        // return 25 results in a turn. Keep at least maxToolCallsPerTurn so
+                        // the judge renderer can preserve metadata for the entire newest batch.
+                        const residencyLimit = Math.max(20, this.config.maxToolCallsPerTurn);
+                        if (goalToolResults.length > residencyLimit) {
+                            goalToolResults.splice(0, goalToolResults.length - residencyLimit);
+                        }
                     }
                     resultBlocks.push(toolResultToBlock(result));
                     const streamResult = toolResultForDisplay(result);
@@ -994,6 +1149,7 @@ export class TurnLoop {
                     tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
                     this.stopBlockCount = 0;
                     this.deps.clearPersistedGoal?.();
+                    this.finalizeModelTurn();
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
@@ -1010,6 +1166,7 @@ export class TurnLoop {
                     tlog.info("turn.goal_user_cancelled", { cat: "goal" });
                     this.stopBlockCount = 0;
                     this.deps.clearPersistedGoal?.();
+                    this.finalizeModelTurn();
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
@@ -1030,6 +1187,7 @@ export class TurnLoop {
                         message: { role: "assistant", content: finalText },
                     });
                     messages.push({ role: "assistant", content: finalText });
+                    this.finalizeModelTurn();
                     if (await this.consumeQueuedSteer(messages, "finalize_backfill")) {
                         continue;
                     }
@@ -1072,9 +1230,7 @@ export class TurnLoop {
                     hasToolUse: true,
                     toolCallCount: toolCalls.length,
                 });
-                // Record turn boundary
-                this.deps.transcript.appendTurnBoundary();
-                this.config.onTurnBoundary?.(this.turnCount);
+                this.finalizeModelTurn();
                 tlog.info("turn.end", {
                     cat: "turn",
                     duration_ms: Date.now() - turnStartedAt,
@@ -1089,6 +1245,9 @@ export class TurnLoop {
             // engine's post-run saveState records model_error instead of leaving
             // the session stuck at "active".
             this.patchOrphanedToolUses(messages);
+            // If the model already returned, this is still a completed model turn.
+            // The idempotent helper is a no-op when its normal branch finalized first.
+            this.finalizeModelTurn();
             // A user-initiated Stop also bubbles here (an AbortError thrown from the
             // per-turn scaffolding). Treat it as a clean abort, not a model_error —
             // no error event, so the UI shows only the "你停止了本轮" line.
@@ -1133,12 +1292,28 @@ export class TurnLoop {
         try {
             const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, this.prepareMessagesForModel(messages), [], // No tools available for summary turn
             this.config.onStream, this.config.signal, this.modelCallRecordingOptions());
+            if (summaryResponse.usage?.promptTokens !== undefined) {
+                this.recordResponseUsage(summaryResponse.usage);
+            }
+            if (goalTracker && summaryResponse.usage) {
+                recordGoalUsage(goalTracker, (summaryResponse.usage.promptTokens ?? 0) + (summaryResponse.usage.completionTokens ?? 0));
+            }
+            if (this.config.signal?.aborted) {
+                this.markStopped();
+                messages = this.redactConsumedSensitiveToolResults(messages);
+                return { text: finalText, reason: "aborted_streaming", messages };
+            }
             messages = this.markPendingImagesConsumed(messages);
             if (summaryResponse.text) {
                 finalText = summaryResponse.text;
             }
         }
-        catch {
+        catch (err) {
+            if (isAbortError(err) || this.config.signal?.aborted) {
+                this.markStopped();
+                messages = this.redactConsumedSensitiveToolResults(messages);
+                return { text: finalText, reason: "aborted_streaming", messages };
+            }
             // If even summary fails, just return what we have
             this.currentTurnLog.warn("turn.summary_failed", { cat: "turn" });
         }

package/dist/engine/types.d.ts

@@ -12,8 +12,8 @@
  */
 import type { ClientDefaults, LLMConfig, SessionOrigin, TerminalReason, TokenUsage } from "../types.js";
 import type { AgentPresetName } from "../preset/index.js";
-import type { GoalConfig } from "./goal.js";
-import type { ApprovalBackend } from "../tool-system/permission.js";
+import type { GoalConfig, GoalTerminationReason } from "./goal.js";
+import type { ApprovalBackend, ApprovalRouter } from "../tool-system/permission.js";
 import type { SandboxConfig } from "../tool-system/sandbox/index.js";
 import type { CostStateStore } from "./cost-store.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
@@ -70,6 +70,8 @@ export interface EngineConfig {
     sessionStorageDir?: string;
     maxContextTokens?: number;
     approvalBackend?: ApprovalBackend;
+    /** Connection-scoped permission approval router supplied by an interactive host. */
+    approvalRouter?: ApprovalRouter;
     hooks?: EngineHookConfig[];
     askUser?: AskUserFn;
     /** Browser automation bridge (browser_* tools). Wired by the host (desktop)
@@ -177,6 +179,8 @@ export interface EngineHookConfig {
 export interface EngineResult {
     text: string;
     reason: TerminalReason;
+    /** Goal-specific stop outcome; omitted for ordinary completion/met verdicts. */
+    goalTermination?: GoalTerminationReason;
     sessionId: string;
     turnCount: number;
     usage: TokenUsage;

package/dist/git/worktree/crud.d.ts

@@ -17,7 +17,10 @@ export interface PlatformScripts {
 }
 export interface CreateWorktreeOptions {
     prefix?: string;
+    signal?: AbortSignal;
 }
+/** Best-effort rollback for an aborted `git worktree add`. */
+export declare function cleanupAbortedWorktree(gitRoot: string, worktreePath: string, branchName: string): Promise<void>;
 /**
  * Pick the setup/cleanup script for the running platform, falling back to
  * `default`. Empty/whitespace-only scripts are treated as absent so a project

package/dist/git/worktree/crud.js

@@ -1,10 +1,25 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { safeSpawnShell } from "../../runtime/safe-spawn.js";
 import { buildSandboxEnv, defaultShellBinary, mergeShellEnv } from "../../runtime/spawn-common.js";
 import { execGit, execGitSync, gitErrorMessage } from "./git-exec.js";
 import { assertBranchNotCheckedOut, currentBranch, findGitRoot } from "./query.js";
 import { applyPrefix, isManagedWorktreeBranch, validateWorktreeSlug } from "./slug.js";
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+/** Best-effort rollback for an aborted `git worktree add`. */
+export async function cleanupAbortedWorktree(gitRoot, worktreePath, branchName) {
+    try {
+        await execGit(gitRoot, ["worktree", "remove", worktreePath, "--force"], 30_000);
+    }
+    catch {
+        await rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+        await execGit(gitRoot, ["worktree", "prune"], 10_000).catch(() => { });
+    }
+    await execGit(gitRoot, ["branch", "-D", branchName], 10_000).catch(() => { });
+}
 /**
  * Pick the setup/cleanup script for the running platform, falling back to
  * `default`. Empty/whitespace-only scripts are treated as absent so a project
@@ -27,16 +42,30 @@ export function selectPlatformScript(scripts, platform = process.platform) {
  */
 export async function createWorktree(cwd, slug, sessionId, opts = {}) {
     validateWorktreeSlug(slug);
+    throwIfAborted(opts.signal);
     const gitRoot = await findGitRoot(cwd);
+    throwIfAborted(opts.signal);
     const branchName = applyPrefix(opts.prefix, slug, sessionId);
     const worktreePath = resolve(gitRoot, "..", `.worktrees/${slug}-${sessionId.slice(0, 8)}`);
     await assertBranchNotCheckedOut(gitRoot, branchName);
+    throwIfAborted(opts.signal);
     const originalBranch = await currentBranch(gitRoot);
+    throwIfAborted(opts.signal);
     // The argv form keeps branchName/worktreePath as literal positional
     // arguments even if a future caller bypasses validateWorktreeSlug.
-    await execGit(gitRoot, ["worktree", "add", "-b", branchName, worktreePath], 30000);
-    // Symlink large directories to avoid disk bloat.
-    symlinkLargeDirectories(gitRoot, worktreePath);
+    try {
+        await execGit(gitRoot, ["worktree", "add", "-b", branchName, worktreePath], 30_000, opts.signal);
+        throwIfAborted(opts.signal);
+        // Symlink large directories to avoid disk bloat.
+        symlinkLargeDirectories(gitRoot, worktreePath);
+        throwIfAborted(opts.signal);
+    }
+    catch (error) {
+        if (opts.signal?.aborted) {
+            await cleanupAbortedWorktree(gitRoot, worktreePath, branchName);
+        }
+        throw error;
+    }
     return {
         originalCwd: cwd,
         worktreePath,

package/dist/git/worktree/git-exec.d.ts

@@ -1,7 +1,7 @@
 export declare const GIT_BIN: string;
-export declare function execGit(cwd: string, args: string[], timeout?: number): Promise<string>;
+export declare function execGit(cwd: string, args: string[], timeout?: number, signal?: AbortSignal): Promise<string>;
 export declare function execGitSync(cwd: string, args: string[], timeout?: number): string;
-export declare function gitOutput(cwd: string, args: string[], timeout?: number): Promise<string | undefined>;
+export declare function gitOutput(cwd: string, args: string[], timeout?: number, signal?: AbortSignal): Promise<string | undefined>;
 export declare function gitOutputSync(cwd: string, args: string[], timeout?: number): string | undefined;
 export declare function gitErrorMessage(err: unknown): string;
 export declare function normalizeBranchName(branch: string): string;