Merge pull request #688 from code-yeongyu/fix/goal-resume-after-provider-error

fix(coding-agent): resume a provider-error-blocked goal on the next user message

Author: code-yeongyu

packages/coding-agent/src/core/extensions/builtin/goal/AGENTS.md

@@ -50,7 +50,9 @@ and a clean accepted user turn arms a visible 10-second grace countdown before t
 resumes; mechanically blocked Goals are reactivated on accepted input, including admitted
 steering. A `length` stop gets exactly one minimal truncation recovery before the goal
 blocks on repetition, terminal provider errors block the goal only when `AgentEndEvent.willRetry`
-is false, and resumed sessions with 8+ trailing historical continuation entries suppress
+is false and count as mechanical (a new user message resumes the goal, and the blocked notice
+says so), while intentional blocks — a user interrupt or a model-declared `update_goal` block —
+stay non-recoverable. Resumed sessions with 8+ trailing historical continuation entries suppress
 session-start auto-resume. `tokenBudget` remains inert compatibility metadata only; this
 policy is budget-free by design.
 

packages/coding-agent/src/core/extensions/builtin/goal/changes.md

@@ -1,5 +1,40 @@
 # goal Extension Changes
 
+## A terminal provider error is a prompt-recoverable block (2026-08-04)
+
+### What changed
+
+- `continuation-recovery.ts` exports `PROVIDER_ERROR_BLOCKED_REASON` and adds it to
+  `MECHANICAL_CONTINUATION_BLOCKS`, so `isMechanicalContinuationBlock` classifies a
+  retries-exhausted provider error alongside the cap, repetition, and length guards.
+- `index.ts` writes that shared constant instead of repeating the literal reason and
+  appends `continuationCapRecoveryHint(...)` to the blocked notice, so the TUI warning
+  now ends with `Send any message to resume.` instead of only naming the failure.
+- `GoalDirectInputLifecycle.onDisposition` needed no change: reactivating a mechanically
+  blocked goal on accepted direct input already existed, and the provider-error reason
+  now flows through it.
+
+### Why
+
+- A terminal provider error is infrastructure, not a decision. The user's next message is
+  exactly the retry signal, so leaving the goal blocked stranded a live run behind a state
+  only `/goal resume` could clear, while the notice never said so.
+- Intentional blocks stay non-recoverable: `user interrupted the turn` and model-declared
+  `update_goal` blocks are still excluded, because those encode a decision to stop.
+- This is the in-session counterpart to the restart resume prompt below: that entry recovers
+  a stopped goal when a new session loads it, this one recovers it mid-session without a
+  restart or a prompt.
+
+### Why an extension couldn't do it
+
+- Both the block-reason writer and the mechanical-block classifier live inside this builtin;
+  the policy has no public extension hook.
+
+### Expected merge-conflict zones
+
+- `continuation-recovery.ts` `MECHANICAL_CONTINUATION_BLOCKS` and its exported reason constants.
+- `index.ts` `agent_end` terminal-provider-error branch and its import block.
+
 ## Restart resume prompt covers every stopped-but-unfinished goal (2026-08-04)
 
 ### What changed

packages/coding-agent/src/core/extensions/builtin/goal/continuation-recovery.ts

@@ -1,11 +1,18 @@
 export const CONTINUATION_CAP_BLOCKED_REASON = "continuation cap reached";
 export const REPETITION_BLOCKED_REASON = "repeated assistant output";
 export const LENGTH_EXHAUSTED_BLOCKED_REASON = "output truncation repeated";
+export const PROVIDER_ERROR_BLOCKED_REASON = "provider error ended the turn (retries exhausted)";
 
+// Mechanical blocks are stops the runtime imposed on itself, not decisions the
+// user or the model made. A terminal provider error belongs here: the provider
+// failing is infrastructure, and the user's next message is exactly the retry
+// signal, so the goal resumes instead of stranding behind a block that only
+// `/goal resume` could clear.
 const MECHANICAL_CONTINUATION_BLOCKS: readonly string[] = [
 	CONTINUATION_CAP_BLOCKED_REASON,
 	REPETITION_BLOCKED_REASON,
 	LENGTH_EXHAUSTED_BLOCKED_REASON,
+	PROVIDER_ERROR_BLOCKED_REASON,
 ];
 
 const RESUME_GUIDANCE = "Send any message to resume.";

packages/coding-agent/src/core/extensions/builtin/goal/index.ts

@@ -5,6 +5,7 @@ import { GOAL_CACHE_WARMUP_ENTRY_TYPE } from "./cache-warm.ts";
 import { renderGoalCacheWarmupEntry } from "./cache-warm-renderer.ts";
 import { registerGoalCommand } from "./command-registration.ts";
 import { GOAL_CONTINUATION_CAP } from "./continuation.ts";
+import { continuationCapRecoveryHint, PROVIDER_ERROR_BLOCKED_REASON } from "./continuation-recovery.ts";
 import { GoalDirectInputLifecycle } from "./direct-input-lifecycle.ts";
 import { GoalElapsedTicker } from "./elapsed-ticker.ts";
 import { formatGoalForTool, goalStatusLabel } from "./format.ts";
@@ -194,10 +195,15 @@ export default function goalExtension(pi: ExtensionAPI): void {
 		} else if (didTerminalProviderErrorEndTurn(event) && goal?.status === "active") {
 			goal = await updateGoal(
 				goalStoreRef(ctx),
-				{ status: "blocked", reason: "provider error ended the turn (retries exhausted)" },
+				{ status: "blocked", reason: PROVIDER_ERROR_BLOCKED_REASON },
 				"model",
 			);
-			if (ctx.hasUI) ctx.ui.notify(`Goal ${goalStatusLabel(goal.status)}\n${formatGoalForTool(goal)}`, "warning");
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					`Goal ${goalStatusLabel(goal.status)}\n${formatGoalForTool(goal)}\n${continuationCapRecoveryHint(PROVIDER_ERROR_BLOCKED_REASON)}`,
+					"warning",
+				);
+			}
 		}
 		if (goal?.status === "active") {
 			beginAgentGoalAccounting(goal);

packages/coding-agent/test/suite/goal-extension.test.ts

@@ -364,6 +364,76 @@ describe("goal extension contract (budget-free)", () => {
 		expect(sent).toHaveLength(0);
 	});
 
+	it("resumes a provider-error-blocked goal when the user sends a new message", async () => {
+		const { tools, handlers } = createGoalHarness();
+		const ctx = await makeCtx("thread-provider-error-resume");
+		await tools
+			.get("create_goal")
+			?.execute("c1", { objective: "Survive a provider outage" }, undefined, undefined, ctx);
+
+		await runHandlers(handlers, "agent_start", { type: "agent_start" }, ctx);
+		await runHandlers(
+			handlers,
+			"agent_end",
+			{ type: "agent_end", messages: [assistantMessageWithStopReason("error")], willRetry: false },
+			ctx,
+		);
+		expect((await readGoal(storeRefFor(ctx)))?.status).toBe("blocked");
+
+		await runHandlers(
+			handlers,
+			"input",
+			{ type: "input", inputId: "provider-error-resume", text: "keep going", source: "interactive" },
+			ctx,
+		);
+		await runHandlers(
+			handlers,
+			"input_disposition",
+			{ type: "input_disposition", inputId: "provider-error-resume", disposition: "started" },
+			ctx,
+		);
+
+		expect(await readGoal(storeRefFor(ctx))).toMatchObject({ status: "active" });
+	});
+
+	it("leaves a user-interrupted goal blocked when the user sends a new message", async () => {
+		const { tools, handlers } = createGoalHarness();
+		const ctx = await makeCtx("thread-user-abort-no-resume");
+		await tools.get("create_goal")?.execute("c1", { objective: "Stay stopped" }, undefined, undefined, ctx);
+
+		await runHandlers(handlers, "agent_start", { type: "agent_start" }, ctx);
+		await runHandlers(
+			handlers,
+			"agent_end",
+			{
+				type: "agent_end",
+				messages: [assistantMessageWithStopReason("aborted")],
+				aborted: true,
+				abortSource: "user",
+				willRetry: false,
+			},
+			ctx,
+		);
+
+		await runHandlers(
+			handlers,
+			"input",
+			{ type: "input", inputId: "user-abort-no-resume", text: "hello", source: "interactive" },
+			ctx,
+		);
+		await runHandlers(
+			handlers,
+			"input_disposition",
+			{ type: "input_disposition", inputId: "user-abort-no-resume", disposition: "started" },
+			ctx,
+		);
+
+		expect(await readGoal(storeRefFor(ctx))).toMatchObject({
+			status: "blocked",
+			blockedReason: "user interrupted the turn",
+		});
+	});
+
 	it("preserves the user-abort block reason", async () => {
 		const { tools, handlers } = createGoalHarness();
 		const ctx = await makeCtx("thread-user-abort-provider-guard");

packages/coding-agent/test/suite/regressions/goal-cap-recovery-guidance.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
 	continuationCapRecoveryHint,
 	isMechanicalContinuationBlock,
+	PROVIDER_ERROR_BLOCKED_REASON,
 } from "../../../src/core/extensions/builtin/goal/continuation-recovery.ts";
 
 // The cap stays as a runaway backstop; tripping it must not strand the user.
@@ -12,9 +13,17 @@ describe("goal continuation cap recovery guidance", () => {
 		expect(isMechanicalContinuationBlock("output truncation repeated")).toBe(true);
 	});
 
+	// A terminal provider error is infrastructure, not a decision: the next user
+	// message is exactly the retry signal, so the goal must resume instead of
+	// stranding the run behind a block only /goal resume could clear.
+	it("classifies a terminal provider error as prompt-recoverable", () => {
+		expect(PROVIDER_ERROR_BLOCKED_REASON).toBe("provider error ended the turn (retries exhausted)");
+		expect(isMechanicalContinuationBlock(PROVIDER_ERROR_BLOCKED_REASON)).toBe(true);
+		expect(continuationCapRecoveryHint(PROVIDER_ERROR_BLOCKED_REASON)).toMatch(/send any message to resume/i);
+	});
+
 	it("does not classify intentional blocks as mechanical", () => {
 		expect(isMechanicalContinuationBlock("user interrupted the turn")).toBe(false);
-		expect(isMechanicalContinuationBlock("provider error ended the turn (retries exhausted)")).toBe(false);
 		expect(isMechanicalContinuationBlock("Waiting on a user decision")).toBe(false);
 		expect(isMechanicalContinuationBlock(undefined)).toBe(false);
 	});