@zhushanwen/pi-goal 0.12.2 → 0.14.0

package/src/__tests__/liveness.test.ts

@@ -0,0 +1,162 @@
+/**
+ * engine/liveness.ts 纯函数测试 — 轮次活性熔断判定单元（chat-domain-v1x D4 / W5）
+ *
+ * 覆盖：env 配置解析（合法/非法/缺省）、退避等级数学（第 N 轮起 ×2、指数天花板）、
+ * 进展信号边界、toolCall 块计数（duck-typed 守卫）、pending 集合变化判定。
+ * 行为级四断言（封顶/退避/恢复/defer 去重经 handleAgentEnd）见 circuit-breaker.test.ts。
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	continuationBackoffDelayMs,
+	countToolCallBlocks,
+	isProgressSignal,
+	nextNoProgressTurns,
+	pendingSetChanged,
+	resolveLivenessConfig,
+	type LivenessConfig,
+} from "../engine/liveness";
+import { createGoalState } from "../engine/goal";
+
+const CFG: LivenessConfig = resolveLivenessConfig({});
+
+// ── resolveLivenessConfig（env 覆盖）──────────────────
+
+describe("resolveLivenessConfig", () => {
+	it("缺省 env → 全默认值（50 / 5 / 1000 / 10s / 10min）", () => {
+		const cfg = resolveLivenessConfig({});
+		expect(cfg.continuationCap).toBe(50);
+		expect(cfg.noProgressTurnsThreshold).toBe(5);
+		expect(cfg.noProgressTokenThreshold).toBe(1000);
+		expect(cfg.backoffBaseMs).toBe(10_000);
+		expect(cfg.backoffMaxMs).toBe(600_000);
+	});
+
+	it("PI_GOAL_* 合法正整数 → 覆盖默认值", () => {
+		const cfg = resolveLivenessConfig({
+			PI_GOAL_CONTINUATION_CAP: "10",
+			PI_GOAL_NO_PROGRESS_TURNS: "3",
+			PI_GOAL_NO_PROGRESS_TOKEN_THRESHOLD: "500",
+			PI_GOAL_BACKOFF_BASE_MS: "1000",
+			PI_GOAL_BACKOFF_MAX_MS: "30000",
+		});
+		expect(cfg.continuationCap).toBe(10);
+		expect(cfg.noProgressTurnsThreshold).toBe(3);
+		expect(cfg.noProgressTokenThreshold).toBe(500);
+		expect(cfg.backoffBaseMs).toBe(1000);
+		expect(cfg.backoffMaxMs).toBe(30000);
+	});
+
+	it.each([
+		["非数字", "abc"],
+		["零", "0"],
+		["负数", "-5"],
+		["小数", "2.7"],
+	])("非法值（%s）→ 回退默认（安全网不因坏配置挂掉）", (_label, raw) => {
+		const cfg = resolveLivenessConfig({ PI_GOAL_CONTINUATION_CAP: raw });
+		expect(cfg.continuationCap).toBe(50);
+	});
+});
+
+// ── 进展信号 + 无进展计数 ────────────────────────────
+
+describe("isProgressSignal / nextNoProgressTurns", () => {
+	it("有工具调用（toolDelta>0）即进展，即使 tokenDelta 低", () => {
+		expect(isProgressSignal(1, 100, CFG)).toBe(true);
+	});
+
+	it("tokenDelta 越阈值即进展，即使无工具调用（纯文本迭代型任务豁免退避）", () => {
+		expect(isProgressSignal(0, 1000, CFG)).toBe(true);
+		expect(isProgressSignal(0, 999, CFG)).toBe(false);
+	});
+
+	it("无进展 → 计数 +1；进展 → 清零", () => {
+		expect(nextNoProgressTurns(4, false)).toBe(5);
+		expect(nextNoProgressTurns(4, true)).toBe(0);
+	});
+});
+
+// ── 退避等级数学 ─────────────────────────────────────
+
+describe("continuationBackoffDelayMs", () => {
+	it("未达阈值（1~4 轮）→ 0（立即发）", () => {
+		expect(continuationBackoffDelayMs(0, CFG)).toBe(0);
+		expect(continuationBackoffDelayMs(4, CFG)).toBe(0);
+	});
+
+	it("第 5 轮起 ×2 递增：5 轮 → 2×base，6 轮 → 4×base，7 轮 → 8×base", () => {
+		expect(continuationBackoffDelayMs(5, CFG)).toBe(20_000);
+		expect(continuationBackoffDelayMs(6, CFG)).toBe(40_000);
+		expect(continuationBackoffDelayMs(7, CFG)).toBe(80_000);
+	});
+
+	it("指数封顶：delay 永不超过 backoffMaxMs", () => {
+		expect(continuationBackoffDelayMs(50, CFG)).toBe(600_000);
+		expect(continuationBackoffDelayMs(1000, CFG)).toBe(600_000);
+	});
+});
+
+// ── toolCall 块计数 ──────────────────────────────────
+
+describe("countToolCallBlocks", () => {
+	it("assistant content 内 toolCall 块计数（多个 entry 累计）", () => {
+		const entries = [
+			{ type: "message", message: { role: "user", content: "hi" } },
+			{
+				type: "message",
+				message: {
+					role: "assistant",
+					content: [
+						{ type: "text", text: "thinking..." },
+						{ type: "toolCall", id: "tc-1", name: "bash" },
+						{ type: "toolCall", id: "tc-2", name: "read" },
+					],
+				},
+			},
+			{
+				type: "message",
+				message: { role: "assistant", content: [{ type: "toolCall", id: "tc-3", name: "bash" }] },
+			},
+			{ type: "message", message: { role: "toolResult", content: [], toolName: "bash", toolCallId: "tc-1" } },
+			{ type: "custom", customType: "goal-state", data: {} },
+		];
+		expect(countToolCallBlocks(entries)).toBe(3);
+	});
+
+	it("畸形 entry（null/非对象/缺 message/content 非数组）→ 跳过不计数", () => {
+		expect(
+			countToolCallBlocks([null, 42, "x", { type: "message" }, { type: "message", message: null }, {
+				type: "message",
+				message: { role: "assistant", content: "plain-string" },
+			}]),
+		).toBe(0);
+	});
+});
+
+// ── pending 集合变化 ─────────────────────────────────
+
+describe("pendingSetChanged", () => {
+	it("集合相同（含顺序不同）→ 无变化", () => {
+		expect(pendingSetChanged(["a", "b"], ["b", "a"])).toBe(false);
+		expect(pendingSetChanged([], [])).toBe(false);
+	});
+
+	it("首次进入 defer（last 为空）或有增删 → 变化", () => {
+		expect(pendingSetChanged(["a"], [])).toBe(true);
+		expect(pendingSetChanged(["a"], ["a", "b"])).toBe(true);
+		expect(pendingSetChanged(["a", "c"], ["a", "b"])).toBe(true);
+	});
+});
+
+// ── createGoalState 初始化 ───────────────────────────
+
+describe("createGoalState — W5 计数初始化", () => {
+	it("新 goal 熔断计数全部从零开始", () => {
+		const state = createGoalState("obj");
+		expect(state.continuationsSent).toBe(0);
+		expect(state.noProgressTurns).toBe(0);
+		expect(state.continuationCapNotified).toBe(false);
+		expect(state.lastDeferredPendingIds).toEqual([]);
+		expect(state.toolCallsSeen).toBe(0);
+	});
+});

package/src/__tests__/ports.test.ts

@@ -46,7 +46,7 @@ describe("buildPorts UiPort.setGuiWidget（marker 编码集成）", () => {
 		const captured = getCaptured();
 		expect(captured).toBeDefined();
 		expect(captured).toHaveLength(1);
-		// marker 前缀（host 侧 event-adapter 据此解码成 extension:widgetGui）
+		// marker 前缀（host 侧 EventAdapter 据此解码成 extension:widgetGui）
 		expect(captured![0].startsWith(GUI_WIDGET_MARKER)).toBe(true);
 		// 解码还原 GuiComponent
 		const json = captured![0].slice(GUI_WIDGET_MARKER.length);

package/src/__tests__/schema.test.ts

@@ -16,6 +16,8 @@ import { describe, expect, it } from "vitest";
 import { Value } from "typebox/value";
 
 import { GoalControlParams } from "../adapters/goal-control-adapter";
+import { createGoalState } from "../engine/goal";
+import { serializeState } from "../persistence";
 
 describe("GoalControlParams — 扁平 Object（OpenAI 兼容）", () => {
 	// 顶层合规：序列化形态顶层必须有 type:"object"，不得有 anyOf（否则被严格网关 400 拒绝）
@@ -52,3 +54,16 @@ describe("GoalControlParams — 扁平 Object（OpenAI 兼容）", () => {
 		expect(Value.Check(GoalControlParams, params)).toBe(false);
 	});
 });
+
+// ── 持久化 schema：serializeState 输出（P-m14-2，ext-simplify-03 D2）──
+
+describe("persisted goal-state schema — serializeState 输出（P-m14-2）", () => {
+	// D2 一步删除 lastProgressTurn/objectiveUpdatedAt 后，新写入的 goal-state entry
+	// 不得再携带这两个 write-only 字段。serializeState 是浅拷贝透传（{ ...state, budget: {...} }），
+	// 字段从 GoalRuntimeState 删除后输出自动少两键——此处断言删除完整（fixture 残留即红）。
+	it("新写入 entry（serializeState(createGoalState)）不含已删两字段", () => {
+		const serialized = serializeState(createGoalState("obj"));
+		expect(serialized).not.toHaveProperty("lastProgressTurn");
+		expect(serialized).not.toHaveProperty("objectiveUpdatedAt");
+	});
+});

package/src/__tests__/service.test.ts

@@ -34,9 +34,11 @@ function makeFakePorts(): ServicePorts & {
 			setStatus: () => {},
 			notify: () => {},
 			hasUI: true,
-			// ThemeLike 直接成员（widget 经 asTheme 取出，见 projection/widget.ts）
-			fg: (_color: string, text: string) => text,
-			bold: (text: string) => text,
+			// ThemeLike 嵌套成员（UiPort.theme 显式声明，updateWidget 直读 uiPort.theme）
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
 		},
 		messaging: {
 			sendContextMessage: () => {},
@@ -44,8 +46,6 @@ function makeFakePorts(): ServicePorts & {
 		},
 		session: {
 			getEntries: () => [],
-			getContextUsage: () => null,
-			signal: undefined,
 		},
 	};
 }

package/src/__tests__/session.test.ts

@@ -31,8 +31,6 @@ function makeFakeSessionPort(entries: SessionEntryLike[]): SessionPort {
 	return {
 		// 模拟 Pi SDK filter-copy 语义：返回新数组，避免测试掩盖 splice GC 失效
 		getEntries: () => entries.slice(),
-		getContextUsage: () => null,
-		signal: undefined,
 	};
 }
 

package/src/__tests__/stale-checker.test.ts

@@ -1,5 +1,5 @@
 /**
- * event-adapter 并发保护辅助函数测试（TC-3）
+ * agent-end stale-check 辅助函数测试（TC-3）
  *
  * 直接测试 makeStaleChecker 的快照语义，
  * 非间接覆盖。重点：makeStaleChecker 在 state=null 时 snapshot=undefined，
@@ -7,7 +7,7 @@
  */
 import { describe, expect, it } from "vitest";
 
-import { makeStaleChecker } from "../adapters/event-handlers/shared";
+import { makeStaleChecker } from "../adapters/event-handlers/agent-end";
 import { createGoalState } from "../engine/goal";
 import type { GoalRuntimeState } from "../engine/types";
 import { createGoalSession } from "../session";

package/src/adapters/command-adapter.ts

@@ -31,7 +31,7 @@ import { updateWidget } from "../projection/widget";
 import { finalizeAndPersist, persistState, tickState } from "../service";
 import type { GoalHistoryEntry } from "../ports";
 import type { GoalSession } from "../session";
-import { clearGoalSession } from "../session";
+import { clearGoalSession, cancelContinuationTimer } from "../session";
 import { buildPorts } from "./ports";
 import { CRITERIA_HINTS_SLASH, validateSuccessCriteriaItems } from "./success-criteria";
 
@@ -122,6 +122,9 @@ function handlePause(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionConte
 	// 先 tickState 累加当前运行段（此时 status 仍为 active）
 	tickState(state);
 	state.status = transitionStatus(state.status, "paused");
+	// W5：用户主动叫停 → 取消待发的退避 continuation（paused 期间不自动续跑；
+	// resume 后由其触发的 user message 重新驱动循环）
+	cancelContinuationTimer(session);
 
 	const ports = buildPorts(pi, ctx);
 	persistState(session, ports);
@@ -141,13 +144,27 @@ function handleResume(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionCont
 		ctx.ui.notify(`Goal is in terminal state (${state.status}), cannot resume.`, "warning");
 		return;
 	}
+	// W5 恢复通道②：active 且 continuation 已封顶停发 → resume 重置熔断计数续跑
+	// （goal 封顶时刻意保持 active 不转终态，续跑决策权在用户）。
+	// 未封顶的普通 active goal 无需 resume（保持原语义）。
+	const cappedActive = state.status === "active" && state.continuationCapNotified;
 	// FR-3: resume 支持 paused→active 和 blocked→active（两者对称，都做 budget 重检 + 触发 AI）
-	if (state.status !== "paused" && state.status !== "blocked") {
+	if (state.status !== "paused" && state.status !== "blocked" && !cappedActive) {
 		ctx.ui.notify("Goal is not paused or blocked, no need to resume.", "info");
 		return;
 	}
-	state.status = "active";
-	state.timeStartedAt = Date.now();
+	if (state.status !== "active") {
+		state.status = transitionStatus(state.status, "active");
+		state.timeStartedAt = Date.now();
+	}
+	// W5：resume = 新激活周期——熔断计数清零。主判据总次数（continuationsSent）只经
+	// 用户显式 resume 重置，agent 侧任何行为（含每轮调工具）都不可清零（正交性）。
+	state.continuationsSent = 0;
+	state.noProgressTurns = 0;
+	state.continuationCapNotified = false;
+	state.lastDeferredPendingIds = [];
+	// toolCallsSeen 不清零：entries 差分口径跨周期连续（清零会让首轮差分把历史
+	// 调用全算成本轮进展，虚高一次无害但无意义）
 
 	const ports = buildPorts(pi, ctx);
 
@@ -171,8 +188,11 @@ function handleResume(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionCont
 	const blockerNote = state.lastBlockerReason
 		? `\n\nPrevious blocker: ${state.lastBlockerReason}. Try a different approach.`
 		: "";
+	const capNote = cappedActive
+		? "\n\nContinuation circuit breaker was reached — pursue the objective with concrete tool-backed progress."
+		: "";
 	pi.sendUserMessage(
-		`Goal resumed. Continuing toward the objective.${blockerNote}\n\nObjective: ${state.objective}`,
+		`Goal resumed. Continuing toward the objective.${blockerNote}${capNote}\n\nObjective: ${state.objective}`,
 		{ deliverAs: "followUp" },
 	);
 }
@@ -264,7 +284,7 @@ function handleClear(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionConte
 
 /**
  * FR-8.4 G-002：重塑（reset）。重置 objective/budget flags/
- * currentTurnIndex/lastProgressTurn，保留 goalId。
+ * currentTurnIndex，保留 goalId。
  * active 状态下向 AI 注入 objective-updated steering。
  */
 function handleUpdate(
@@ -293,12 +313,15 @@ function handleUpdate(
 	const oldObjective = state.objective;
 	// FR-8.4 G-002: 重塑（重置，保留 goalId）
 	state.objective = newObjective;
-	state.objectiveUpdatedAt = Date.now();
 	state.currentTurnIndex = 0;
-	state.lastProgressTurn = 0;
 	state.budgetLimitSteeringSent = false;
 	state.tokenWarning70Sent = false;
 	state.tokenWarning90Sent = false;
+	// W5：重塑 = 新激活周期，熔断计数与 budget flag 同类（cycle-scoped 记账）一并重置
+	state.continuationsSent = 0;
+	state.noProgressTurns = 0;
+	state.continuationCapNotified = false;
+	state.lastDeferredPendingIds = [];
 	// GAP-6: update 是重塑，旧 slug 已不匹配新 objective → 置空（widget fallback objective 截断）
 	state.slug = undefined;
 	// update 重塑后旧 successCriteria 可能不再完全匹配新 objective，但语义内容仍可部分适用。

package/src/adapters/event-handlers/agent-end.ts

@@ -7,7 +7,8 @@
  * - FR-6.7 ESC 守卫（最关键）：ctx.signal?.aborted → 不发 continuation、不做 budget 检查、
  *   不做任何状态变更，goal 保持 active，等用户下次输入恢复
  *
- * #8 后流程：budget 预警/steering → continuation 去抖。
+ * #8 后流程：budget 预警/steering → continuation 去抖 + 轮次活性熔断（W5：
+ * 连发总次数封顶 + 无进展退避 + defer 通知去重，见 handleContinuation 头注）。
  * agent_end 只做提醒（warning + steering），不做终态转换。
  * 终态转换不在 agent_end——由 persistAndUpdate 兜底（#5 范围，单一检查点）。
  *
@@ -23,15 +24,25 @@ import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
 
 import { checkBudgetOnTurnEnd } from "../../engine/budget";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
+import {
+	type LivenessConfig,
+	continuationBackoffDelayMs,
+	countToolCallBlocks,
+	isContinuationCapped,
+	isProgressSignal,
+	nextNoProgressTurns,
+	pendingSetChanged,
+	resolveLivenessConfig,
+} from "../../engine/liveness";
 import {
 	budgetLimitPrompt,
 	continuationPrompt,
 } from "../../projection/prompts";
 import { persistAndUpdate, tickState } from "../../service";
-import type { GoalSession } from "../../session";
+import { serializeState } from "../../persistence";
+import { cancelContinuationTimer, type GoalSession } from "../../session";
 import type { ServicePorts } from "../../service";
 import { buildPorts } from "../ports";
-import { makeStaleChecker } from "./shared";
 
 export async function handleAgentEnd(
 	pi: ExtensionAPI,
@@ -135,13 +146,19 @@ async function handleBudgetChecks(
 }
 
 /**
- * continuation 去抖（budget 预警未拦截时的尾部逻辑）。
+ * continuation 去抖 + 轮次活性熔断（budget 预警未拦截时的尾部逻辑）。
  *
  * - continuation 去抖：tokenDelta=0（空 turn）不发，只 persist
- * - 否则 persist + 发 continuationPrompt
+ * - W5 主判据：continuation 连发总次数封顶（默认 50，PI_GOAL_CONTINUATION_CAP）——
+ *   封顶必停发 + notify 用户 + goal 保持 active（不擅自终态）。与「是否调工具」
+ *   正交：计数只在 deliverContinuation 实发时 +1，绝不被工具调用清零
+ *   （2026-09-08 事故：pending 守卫击穿后 64 分钟 ~320 turn 空转，无任何熔断）。
+ * - W5 辅判据：连续 N 轮（默认 5）无工具调用且 tokenDelta 低于阈值 → continuation
+ *   延迟 base×2^level 发出（间隔 ×2 递增）；真实进展清零退避计数（不动总次数）。
+ * - W5 defer 通知去重：pending 集合不变的连续 defer 轮不重复 notify。
  *
  * 注：maxTurnsReached / stall 自动终态分支随 #6 删除；budget terminal 分支随 #8 删除。
- * 终态转换由 persistAndUpdate 兑底（#5 范围，单一检查点）。
+ * 终态转换由 persistAndUpdate 兜底（#5 范围，单一检查点）。
  */
 async function handleContinuation(
 	pi: ExtensionAPI,
@@ -153,20 +170,24 @@ async function handleContinuation(
 	const state = session.state!;
 	if (checkStale()) return;
 
+	const cfg = resolveLivenessConfig();
+	const entries = ctx.sessionManager.getEntries();
+
 	// FR-8.6: continuation 去抖（空 turn 不发）
 	const tokenDelta = state.tokensUsed - state.lastTurnTokensUsed;
 	state.lastTurnTokensUsed = state.tokensUsed;
-	// 单次 persist（H2 合并：原空 turn/非空 turn 两处重复 persistAndUpdate 提到 if 前统一调用）。
-	// budget 终态检查点在 persistAndUpdate 内部（#5 单一检查点），与调用位置无关——
-	// 合并不影响预算终态触发时机（explorer 论证）。
-	persistAndUpdate(session, ports);
-	if (tokenDelta <= 0) {
-		// 空 turn：已 persist，不发 continuation
-		return;
-	}
-	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited 终态。
-	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
-	if (isTerminalStatus(state.status)) return;
+
+	// W5 辅判据记账：本 turn（自上次 agent_end 以来）真实工具活动 = toolCall 块差分。
+	// 无进展 → 计数 +1；有进展（工具调用或 tokenDelta 越阈值）→ 清零退避计数
+	// （主判据 continuationsSent 不在此处触碰——正交性）。
+	const toolCallsTotal = countToolCallBlocks(entries);
+	const toolDelta = toolCallsTotal - state.toolCallsSeen;
+	state.toolCallsSeen = toolCallsTotal;
+	state.noProgressTurns = nextNoProgressTurns(
+		state.noProgressTurns,
+		isProgressSignal(toolDelta, tokenDelta, cfg),
+	);
+
 	// pending 守卫：有活跃 background subagent/workflow 时不发 continuation。
 	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true,deliverAs:"steer"}) 自然唤醒主 agent；
 	// goal 抢先催会与异步任务完成通知叠加，形成“停不下来”的死循环——continuation 排入
@@ -174,8 +195,15 @@ async function handleContinuation(
 	// 新 turn → 又 agent_end → 又 continuation。
 	// 刻意不校验 expiresAt：长任务 subagent（>1h TTL）完成时仍 triggerTurn 唤醒主 agent，
 	// 按 TTL 判非活跃会让死循环在长任务场景复现。
-	const pendingOps = countActiveFromEntries(ctx.sessionManager.getEntries());
+	// [W4 读侧过滤①消费口] 传当前 session 基准：fork 继承的父级注册残留不进差集
+	// （守卫不幻 defer）；设计 D4「读侧过滤一刀」在本消费口的落地（W6 探针实测
+	// registry-fork-filter.test.ts 证不传则虚增，A9② 验收口径）。
+	const pendingOps = countActiveFromEntries(entries, {
+		currentSessionId: ctx.sessionManager.getSessionId(),
+	});
+	let deferred = false;
 	if (pendingOps.count > 0) {
+		deferred = true;
 		pi.appendEntry("goal:log", {
 			timestamp: Date.now(),
 			level: "debug",
@@ -183,17 +211,162 @@ async function handleContinuation(
 			message: `continuation deferred: ${pendingOps.count} active pending operation(s)`,
 			data: { activePending: pendingOps.count, ids: pendingOps.ids },
 		});
-		// 用户可见反馈：goal 在等待后台任务完成而非卡死（deferred 无反馈时用户只看到
-		// goal active 但无产出，无法区分等待 vs 死循环）。
-		ctx.ui.notify(
-			`Goal waiting for ${pendingOps.count} background task(s) to complete.`,
-			"info",
-		);
+		// W5 defer 通知去重：状态变化（pending 集合变化或首次进入 defer）才 notify——
+		// 事故中每轮 agent_end 都发「Goal waiting for N…」，集合不变时是纯噪音。
+		// 用户可见反馈保留：deferred 无反馈时用户只看到 goal active 但无产出，
+		// 无法区分等待 vs 死循环。
+		if (pendingSetChanged(pendingOps.ids, state.lastDeferredPendingIds)) {
+			ctx.ui.notify(
+				`Goal waiting for ${pendingOps.count} background task(s) to complete.`,
+				"info",
+			);
+			state.lastDeferredPendingIds = [...pendingOps.ids].sort();
+		}
+	} else {
+		// 非 defer 轮清空去重锚：每个等待 episode 的首次 defer 都会通知一次
+		state.lastDeferredPendingIds = [];
+	}
+
+	// 单次 persist（H2 合并）：熔断计数（noProgressTurns / toolCallsSeen /
+	// lastDeferredPendingIds）随同一快照落盘。budget 终态检查点在 persistAndUpdate
+	// 内部（#5 单一检查点），与调用位置无关——合并不影响预算终态触发时机（explorer 论证）。
+	persistAndUpdate(session, ports);
+	if (deferred) {
+		// defer 轮：已 persist + 已去重通知，不发 continuation
 		return;
 	}
-	// 发 continuation（FR-8.7: 去 debounce 后才发）
-	ports.messaging.sendContextMessage(
-		continuationPrompt(state),
-		"followUp",
-	);
+	if (tokenDelta <= 0) {
+		// 空 turn：已 persist，不发 continuation
+		return;
+	}
+	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited 终态。
+	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
+	if (isTerminalStatus(state.status)) return;
+
+	// W5 主判据：连发总次数封顶（与是否调工具正交——toolDelta 只影响辅判据退避）。
+	// 封顶必停发 + 通知一次（含恢复指引）+ goal 保持 active（不擅自终态）。
+	if (isContinuationCapped(state, cfg)) {
+		if (!state.continuationCapNotified) {
+			state.continuationCapNotified = true;
+			ports.ui.notify(
+				`Goal continuation stopped: ${cfg.continuationCap} continuations sent this cycle without completing (no-progress circuit breaker). The goal stays active. Use /goal resume to continue with a fresh allowance, or /goal clear to stop.`,
+				"warning",
+			);
+			pi.appendEntry("goal:log", {
+				timestamp: Date.now(),
+				level: "info",
+				component: "goal:agent-end",
+				message: `continuation capped: ${state.continuationsSent}/${cfg.continuationCap} sent, stopping (goal stays active; /goal resume resets)`,
+				data: { continuationsSent: state.continuationsSent, cap: cfg.continuationCap },
+			});
+			// 停发标志单独落盘（罕见路径——每激活周期至多一次）：否则下次 persist 前
+			// 进程重启会让停发通知重发一次
+			ports.persistence.appendState(serializeState(state));
+		}
+		return;
+	}
+
+	// W5 辅判据：无进展退避。到决策点先取消旧的待发退避 continuation——等待期内若
+	// 有外部驱动的 turn（用户输入 / 后台任务通知唤醒）到达这里，按最新状态重算：
+	// 有进展 → 立即发；仍无进展 → 按当前等级重排。保证任意时刻至多一个待发。
+	cancelContinuationTimer(session);
+
+	const delayMs = continuationBackoffDelayMs(state.noProgressTurns, cfg);
+	if (delayMs <= 0) {
+		deliverContinuation(ports, session);
+		return;
+	}
+	pi.appendEntry("goal:log", {
+		timestamp: Date.now(),
+		level: "debug",
+		component: "goal:agent-end",
+		message: `continuation delayed by backoff: ${delayMs}ms (no-progress turns: ${state.noProgressTurns})`,
+		data: { delayMs, noProgressTurns: state.noProgressTurns },
+	});
+	const goalId = state.goalId;
+	session.continuationTimer = setTimeout(() => {
+		session.continuationTimer = null;
+		// MF-6②：timer 回调跨生命周期持有本次 agent_end 的 ctx/ports 闭包，且不在
+		// pi runner 的 handler 错误隔离范围内——回调内同步异常 = uncaughtException，
+		// 可能带崩 pi 进程。整体 try/catch：stale ctx（session 关闭/替换后 ctx 的
+		// isIdle / sessionManager getter 走 assertActive 抛错，development-guide
+		// §11.1）等异常降级为一条 goal:log 记录后放弃，goal 状态仍在盘上，后续任意
+		// agent_end 会重新决策。（正常运行时路径的兜底：session_shutdown 已在
+		// invalidate 前取消旧 timer，stale 到期属极端残留场景。）
+		try {
+			fireBackoffContinuation(session, ports, ctx, cfg, goalId);
+		} catch (err) {
+			// MF-R2-1 兜底：pi.appendEntry 与 ctx 同生命周期（loader.js appendEntry
+			// 首行 assertActive，0.84.4 实装核对）——stale 场景此调用同样必抛，
+			// 故降级日志自包 try/catch，保证 catch 块自身零抛出。放弃日志无害：
+			// goal 状态在盘上，后续任意 agent_end 会重新决策。
+			try {
+				pi.appendEntry("goal:log", {
+					timestamp: Date.now(),
+					level: "warn",
+					component: "goal:agent-end",
+					message: `backoff continuation dropped after error: ${String(err)}`,
+				});
+			} catch (logErr) {
+				// 刻意放弃：appendEntry（goal:log 落盘通道）自身失效的场景（stale /
+				// runtime 失效）下再调任何 runtime 方法都会二次抛出——本 catch 存在的
+				// 意义即阻断该 uncaughtException 路径。void 显式忽略，对齐
+				// extension-logger 内部 appendEntry 失败兜底的既定惯例。
+				void logErr;
+			}
+		}
+	}, delayMs);
+}
+
+/**
+ * 退避 timer 到期后的发射前守卫 + 实发（延迟期间状态可能已变）：
+ * - goal 未被覆盖/清除（goalId 比对）、仍 active
+ * - MF-6① idle 守卫：ctx.signal 为实时求值（pi-agent-core agent.js get signal 返回
+ *   activeRun?.abortController.signal），agent idle 后恒 undefined，`signal?.aborted`
+ *   恒放行、不可作守卫；改用 ctx.isIdle()（SDK types.d.ts L232）——延迟窗内有活动
+ *   turn 时不发，该轮 agent_end 会按最新状态重新决策
+ * - 未封顶、无活跃 pending（等待期新出现的后台任务由其完成通知唤醒，goal 不抢先催）
+ */
+function fireBackoffContinuation(
+	session: GoalSession,
+	ports: ServicePorts,
+	ctx: ExtensionContext,
+	cfg: LivenessConfig,
+	goalId: string,
+): void {
+	if (!session.state || session.state.goalId !== goalId) return;
+	if (!isActiveStatus(session.state.status)) return;
+	if (!ctx.isIdle()) return;
+	if (isContinuationCapped(session.state, cfg)) return;
+	if (countActiveFromEntries(ctx.sessionManager.getEntries(), { currentSessionId: ctx.sessionManager.getSessionId() }).count > 0) return;
+	deliverContinuation(ports, session);
+}
+
+/**
+ * 发出一次 continuation 并立即落盘计数（主判据只在实发时 +1，发出即持久化——
+ * 崩溃后封顶计数不从零开始）。
+ */
+function deliverContinuation(ports: ServicePorts, session: GoalSession): void {
+	const state = session.state!;
+	state.continuationsSent += 1;
+	ports.messaging.sendContextMessage(continuationPrompt(state), "followUp");
+	ports.persistence.appendState(serializeState(state));
+}
+
+/**
+ * 构造 stale-check 闭包（FR-8.2 G-020）：入口快照 goalId，后续判断是否被新 goal 覆盖。
+ *
+ * 用法（agent_end）：
+ * ```ts
+ * const checkStale = makeStaleChecker(session);
+ * // ... 长流程 ...
+ * if (checkStale()) return; // goal 被覆盖，本次 agent_end 作废
+ * ```
+ *
+ * 语义：snapshot 时 session.state 可能为 null（首次启动），此时 snapshotGoalId
+ * 为 undefined；后续若有新 goal（goalId !== undefined）即视为 stale。
+ */
+export function makeStaleChecker(session: GoalSession): () => boolean {
+	const snapshotGoalId = session.state?.goalId;
+	return () => !session.state || session.state.goalId !== snapshotGoalId;
 }

package/src/adapters/event-handlers/before-agent-start.ts

@@ -20,9 +20,9 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { AUTO_CLEAR_TURNS, CONTEXT_USAGE_RATIO_LIMIT } from "../../constants";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
 import { contextInjectionPrompt } from "../../projection/prompts";
-import { asTheme, renderTerminalStatusLine } from "../../projection/widget";
+import { renderTerminalStatusLine } from "../../projection/widget";
 import type { GoalSession } from "../../session";
-import { clearGoalSession } from "../../session";
+import { cancelContinuationTimer, clearGoalSession } from "../../session";
 import { buildPorts } from "../ports";
 
 interface BeforeAgentStartResult {
@@ -38,6 +38,10 @@ export async function handleBeforeAgentStart(
 	session: GoalSession,
 	ctx: ExtensionContext,
 ): Promise<BeforeAgentStartResult | undefined> {
+	// MF-6③：新用户活动（新 turn 开始）使旧的退避 continuation 作废——该轮
+	// agent_end 会按最新状态重新决策。放在 state 检查之前：即使 goal 已清，
+	// 旧 timer 也不该在新 turn 开始后仍存活
+	cancelContinuationTimer(session);
 	if (!session.state) return;
 
 	pi.appendEntry("goal:log", {
@@ -88,7 +92,7 @@ function handleTerminalStateBeforeAgent(
 		return;
 	}
 	// 折叠 status bar（终态显示）
-	const statusText = renderTerminalStatusLine(state, asTheme(buildPorts(pi, ctx).ui));
+	const statusText = renderTerminalStatusLine(state, buildPorts(pi, ctx).ui.theme);
 	if (statusText && ctx.hasUI) ctx.ui.setStatus("goal", statusText);
 	if (ctx.hasUI) ctx.ui.setWidget("goal", undefined);
 }