@zhushanwen/pi-goal 0.13.0 → 0.14.1

package/README.md

@@ -52,8 +52,8 @@ goal/
     ├── service.ts      # 协调层 — createGoal / finalizeAndPersist / applyEvent
     ├── persistence.ts  # serialize/deserialize + GoalHistoryEntry
     ├── session.ts      # 运行时句柄 + 状态重建（append-only 只读最新一条，无 entry GC）
-    ├── engine/         # 零 Pi 依赖的纯状态机（goal/budget/types）
-    ├── adapters/       # Pi 桥接（goal-control-adapter / command-adapter / event-adapter
-    │                   #   + event-handlers/ + ports / success-criteria）
+    ├── engine/         # 零 Pi 依赖的纯状态机（goal/budget/types/liveness）
+    ├── adapters/       # Pi 桥接（goal-control-adapter / command-adapter / ports /
+    │                   #   success-criteria + event-handlers/）
     └── projection/     # 渲染（widget / prompts / gui）
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token budget, agent-reported blocking, and steering templates.",
   "type": "module",
   "main": "src/index.ts",
@@ -29,10 +29,10 @@
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.6.0"
+    "@zhushanwen/pi-pending-notifications": "0.7.1"
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.8.2"
+    "@xyz-agent/extension-protocol": "0.10.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/src/__tests__/circuit-breaker.test.ts

@@ -11,7 +11,7 @@
  * 另覆盖：停发通知含 /goal resume 恢复指引 + goal 保持 active；/goal resume
  * 恢复通道重置计数；未封顶 active goal 的 resume 语义不变。
  *
- * fake timers + fake pi/ctx（不 import Pi SDK 真实实现，harness 对齐 event-adapter.test.ts）。
+ * fake timers + fake pi/ctx（不 import Pi SDK 真实实现，harness 对齐 __tests__/event-adapter.test.ts）。
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

package/src/__tests__/criteria-array-adapter.test.ts

@@ -38,8 +38,10 @@ function makeFakePorts(): ServicePorts & {
 			hasUI: true,
 			isGui: false,
 			setGuiWidget: () => {},
-			fg: (_color: string, text: string) => text,
-			bold: (text: string) => text,
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
 		} as UiPort,
 		messaging: {
 			sendContextMessage: () => {},
@@ -47,8 +49,6 @@ function makeFakePorts(): ServicePorts & {
 		},
 		session: {
 			getEntries: () => [],
-			getContextUsage: () => null,
-			signal: undefined,
 		},
 	};
 }

package/src/__tests__/criteria-array-migration.test.ts

@@ -24,9 +24,7 @@ function makeLegacyData(successCriteria: unknown): Record<string, unknown> {
 		timeStartedAt: 1000,
 		timeUsedSeconds: 0,
 		budget: {},
-		lastProgressTurn: 0,
 		budgetLimitSteeringSent: false,
-		objectiveUpdatedAt: 1000,
 		lastBlockerReason: null,
 		tokenWarning70Sent: false,
 		tokenWarning90Sent: false,

package/src/__tests__/deserialize-state.test.ts

@@ -1,5 +1,5 @@
 /**
- * FR-5/FR-7.3: deserializeState — 新格式严格解析（字段缺失 throw）
+ * FR-5/FR-7.3: deserializeState — 严格解析（必填缺失 throw；旧格式容忍面见 persistence.ts 各迁移点注释）
  *
  * round-trip property 覆盖全字段 serialize→deserialize 双向一致性，替代手写还原用例。
  * 保留：throw 路径（缺必填）+ 向后兼容（缺 optional）+ 旧 tasks 字段忽略。
@@ -32,9 +32,7 @@ const goalStateArb = fc.record({
 	timeStartedAt: fc.integer({ min: 0 }),
 	timeUsedSeconds: fc.nat(),
 	budget: fc.record({ tokenBudget: fc.option(fc.integer({ min: 0 })) }),
-	lastProgressTurn: fc.nat(),
 	budgetLimitSteeringSent: fc.boolean(),
-	objectiveUpdatedAt: fc.integer({ min: 0 }),
 	lastBlockerReason: fc.option(fc.string(), { nil: null }), // string | null
 	tokenWarning70Sent: fc.boolean(),
 	tokenWarning90Sent: fc.boolean(),
@@ -59,9 +57,7 @@ const FULL_DATA: Record<string, unknown> = {
 	timeStartedAt: 1000,
 	timeUsedSeconds: 0,
 	budget: {},
-	lastProgressTurn: 0,
 	budgetLimitSteeringSent: false,
-	objectiveUpdatedAt: 1000,
 	lastBlockerReason: null,
 	tokenWarning70Sent: false,
 	tokenWarning90Sent: false,
@@ -70,7 +66,7 @@ const FULL_DATA: Record<string, unknown> = {
 };
 
 describe("deserializeState — round-trip", () => {
-	// ⭐ serialize→deserialize 深相等：覆盖全 18 字段双向一致性（含 optional 有/无两态）
+	// ⭐ serialize→deserialize 深相等：覆盖全 21 字段双向一致性（含 optional 有/无两态）
 	it.prop([goalStateArb])("deserializeState(serializeState(s)) 深相等 s", (s) => {
 		const rt = deserializeState(serializeState(s) as unknown as Record<string, unknown>);
 		expect(rt).toEqual(s);
@@ -111,6 +107,32 @@ describe("deserializeState — 严格解析（缺必填 throw）", () => {
 	});
 });
 
+describe("deserializeState — legacy entry 含已删字段（P-m14-1，D2 白名单兼容）", () => {
+	// ext-simplify-03 D2：lastProgressTurn/objectiveUpdatedAt 已从 GoalRuntimeState 一步删除。
+	// 0.13.0 形状 entry 仍携带这两个字段——deserializeState 是白名单模式（只对已知 key 逐个
+	// req()/可选解析，从不遍历 entry 全部 key，与 tasks 字段先例同一机制），entry 多出的
+	// 字段天然被忽略：不 throw、state 完整重建（G3：旧数据加载兼容）。
+	const LEGACY_0_13: Record<string, unknown> = {
+		...FULL_DATA,
+		lastProgressTurn: 3,
+		objectiveUpdatedAt: 2000,
+	};
+
+	it("0.13.0 形状 entry（含已删两字段）→ 不 throw，返回完整 state", () => {
+		const state = deserializeState(LEGACY_0_13);
+		expect(state.goalId).toBe("g1");
+		expect(state.objective).toBe("test");
+		expect(state.status).toBe("active");
+		expect(state.budgetLimitSteeringSent).toBe(false);
+	});
+
+	it("已删字段被白名单忽略：返回对象不含 lastProgressTurn/objectiveUpdatedAt", () => {
+		const state = deserializeState(LEGACY_0_13);
+		expect(state).not.toHaveProperty("lastProgressTurn");
+		expect(state).not.toHaveProperty("objectiveUpdatedAt");
+	});
+});
+
 describe("deserializeState — optional 字段向后兼容（GAP-4 旧数据）", () => {
 	it("缺 completedAtTurnIndex → undefined", () => {
 		expect(deserializeState(FULL_DATA).completedAtTurnIndex).toBeUndefined();

package/src/__tests__/event-adapter.test.ts

@@ -1,5 +1,5 @@
 /**
- * event-adapter.ts 测试 — agent_end / before_agent_start 核心逻辑
+ * event-handlers 行为测试 — agent_end / before_agent_start 核心逻辑
  *
  * 覆盖 agent_end 的 continuation + ESC 守卫（FR-6.7）+
  * before_agent_start 的 AUTO_CLEAR/context wrap-up。

package/src/__tests__/goal-control-adapter.test.ts

@@ -52,9 +52,11 @@ function makeFakePorts(): ServicePorts & {
 				notifications.push({ text, level });
 			},
 			hasUI: true,
-			// widget.asTheme 期望 fg/bold（ports.ts 的 uiPort 同样携带）
-			fg: (_color: string, text: string) => text,
-			bold: (text: string) => text,
+			// widget 渲染读 UiPort.theme（ports.ts 的 uiPort 同样以 theme 嵌套成员提供）
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
 		} as UiPort,
 		messaging: {
 			sendContextMessage: () => {},
@@ -62,8 +64,6 @@ function makeFakePorts(): ServicePorts & {
 		},
 		session: {
 			getEntries: () => [],
-			getContextUsage: () => null,
-			signal: undefined,
 		},
 	};
 }

package/src/__tests__/goal-control-rpc.test.ts

@@ -47,7 +47,7 @@ interface FakeFixture {
  * 构造最小 fake pi / ctx。ctx.mode 由调用方覆盖（默认 "rpc"）。
  *
  * ports.ts 的 buildPorts 读 ctx.ui.theme.fg/bold、ctx.ui.setWidget/setStatus/notify、
- * ctx.sessionManager.getEntries、ctx.getContextUsage、ctx.signal、ctx.hasUI——全部 mock。
+ * ctx.sessionManager.getEntries、ctx.hasUI——全部 mock。
  */
 function makeFixture(mode: "rpc" | "tui" | "json" | "print" = "rpc"): FakeFixture {
 	const notifications: Array<{ text: string; level: string }> = [];

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

@@ -154,7 +154,7 @@ function handleResume(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionCont
 		return;
 	}
 	if (state.status !== "active") {
-		state.status = "active";
+		state.status = transitionStatus(state.status, "active");
 		state.timeStartedAt = Date.now();
 	}
 	// W5：resume = 新激活周期——熔断计数清零。主判据总次数（continuationsSent）只经
@@ -284,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(
@@ -313,9 +313,7 @@ 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;

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

@@ -43,7 +43,6 @@ 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,
@@ -353,3 +352,21 @@ function deliverContinuation(ports: ServicePorts, session: GoalSession): void {
 	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,7 +20,7 @@ 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 { cancelContinuationTimer, clearGoalSession } from "../../session";
 import { buildPorts } from "../ports";
@@ -92,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);
 }

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

@@ -7,27 +7,15 @@
  * 不 persist / updateWidget。
  */
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, MessageEndEvent } from "@earendil-works/pi-coding-agent";
 
 import { applyEvent } from "../../service";
 import type { GoalSession } from "../../session";
 
-export interface MessageEndLikeEvent {
-	message: {
-		role: string;
-		usage?: {
-			input?: number;
-			output?: number;
-			cacheRead?: number;
-			totalTokens?: number;
-		};
-	};
-}
-
 export async function handleMessageEnd(
 	session: GoalSession,
 	ctx: ExtensionContext,
-	event: MessageEndLikeEvent,
+	event: MessageEndEvent,
 ): Promise<void> {
 	if (!session.state) return;
 	// FR-6.7 ESC 守卫

package/src/adapters/goal-control-adapter.ts

@@ -28,7 +28,7 @@
  *
  * executionMode: "sequential"——状态变更 tool，不可与同批其他 tool 并行执行。
  *
- * 错误处理：用 throw new Error（CLAUDE.md Tool 设计规范），不返回错误成功模式。
+ * 错误处理：用 throw new Error（extension-conventions.md Tool 设计规范），不返回错误成功模式。
  */
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";

package/src/adapters/ports.ts

@@ -1,12 +1,15 @@
 /**
  * Ports 桥接 — Pi → ServicePorts 适配（adapters 层）
  *
- * 单一 ports 构造点（DRY）：command-adapter / event-adapter / index 共用。
+ * 单一 ports 构造点（DRY）：command-adapter / goal-control-adapter / event-handlers / index 共用。
  *
  * - persistence: pi.appendEntry 映射到 appendState / appendHistory（type 字符串区分）
- * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + theme 的 fg/bold（满足 ThemeLike 形状）
+ * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + isGui + theme（fg/bold 适配 ThemeLike）
  * - messaging: pi.sendMessage 映射到 sendContextMessage / sendUserMessage
- * - session: ctx.sessionManager.getEntries + ctx.getContextUsage + ctx.signal
+ * - session: ctx.sessionManager.getEntries
+ *
+ * port/ctx 双通道惯例：port 对象仅用于传入 service/session 的实参；
+ * handler 自用的 UI/日志直呼 ctx（如 ctx.ui.notify、ctx.ui.setWidget）。
  */
 
 import type { ExtensionAPI, ExtensionContext, ThemeColor } from "@earendil-works/pi-coding-agent";
@@ -22,10 +25,6 @@ import type { ServicePorts } from "../service";
  *
  * persistence 的 appendState 用 ENTRY_TYPE，appendHistory 用 HISTORY_ENTRY_TYPE，
  * 与 serializeState / makeHistoryEntry 的输出对齐（session.ts reconstructGoalState 据此识别）。
- *
- * UiPort 接口未声明 fg/bold（D-22：只声明机器可检查的能力边界），
- * 构造满足 UiPort & ThemeLike 的对象后整体断言为 UiPort（多出的 fg/bold 运行时存在，
- * projection/widget.ts 的 asTheme 用 `as unknown as ThemeLike` 单步断言取出）。
  */
 export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePorts {
 	const persistence: PersistencePort = {
@@ -40,7 +39,7 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 		},
 	};
 
-	const uiPort = {
+	const uiPort: UiPort = {
 		setWidget(name: string, content: string[] | string | undefined): void {
 			// SDK setWidget 重载只接受 string[] | undefined（或 factory）。本地 UiPort 允许单 string，
 			// 此处归一化：string 包一层成 [string]，再透传。
@@ -50,7 +49,7 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 		setGuiWidget(name: string, result: GuiRenderResult | undefined): void {
 			// GUI 协议 widget：guiSetWidget 在 RPC 模式用 marker 编码 GuiRenderResult JSON
 			// （component + meta 宿主元数据）进 string[]，复用 ctx.ui.setWidget 通道；
-			// host 侧 event-adapter 检测 marker 解码还原。guiSetWidget 无 isGui 守卫
+			// host 侧 EventAdapter（xyz-agent runtime 的 pi 事件适配层）检测 marker 解码还原。guiSetWidget 无 isGui 守卫
 			// （helpers.ts 仅查 ctx.ui?.setWidget 存在性），isGui 判定在 updateWidget
 			// 外层（projection/widget.ts）。
 			//
@@ -74,16 +73,18 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 			// 断言同 setGuiWidget：custom 泛型签名静态不兼容，mode 单字段运行时可靠。
 			return isGuiCapable(ctx as GuiContext);
 		},
-		// ThemeLike 形状：透传 ctx.ui.theme 的 fg/bold。
+		// ThemeLike 适配：透传 ctx.ui.theme 的 fg/bold。
 		// Theme.fg 只接受 ThemeColor 字面量 union（SDK 契约）；projection 层保证传入 union 内字面量，
 		// string → ThemeColor 是宽到窄单步断言（无需 unknown 中转）。
-		fg(color: string, text: string): string {
-			return ctx.ui.theme.fg(color as ThemeColor, text);
-		},
-		bold(text: string): string {
-			return ctx.ui.theme.bold(text);
+		theme: {
+			fg(color: string, text: string): string {
+				return ctx.ui.theme.fg(color as ThemeColor, text);
+			},
+			bold(text: string): string {
+				return ctx.ui.theme.bold(text);
+			},
 		},
-	} as UiPort;
+	};
 
 	const messaging: MessagingPort = {
 		sendContextMessage: (content, deliverAs, customType): void => {
@@ -103,13 +104,6 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 
 	const session: SessionPort = {
 		getEntries: () => ctx.sessionManager.getEntries(),
-		getContextUsage: () => {
-			const usage = ctx.getContextUsage();
-			return usage ? { tokens: usage.tokens, contextWindow: usage.contextWindow } : null;
-		},
-		get signal(): AbortSignal | undefined {
-			return ctx.signal;
-		},
 	};
 
 	return { persistence, ui: uiPort, messaging, session };

package/src/engine/__tests__/budget.test.ts

@@ -71,21 +71,21 @@ describe("checkBudgetOnTurnEnd — token 阈值", () => {
 	it("token < 70% → 无预警", () => {
 		expect(checkBudgetOnTurnEnd(makeState({ tokensUsed: 600, budget: { tokenBudget: 1000 } })).warnings).toEqual([]);
 	});
-	it("token >= 70% 未发 → warning70 token", () => {
+	it("token >= 70% 未发 → warning70", () => {
 		const s = makeState({ tokensUsed: 700, budget: { tokenBudget: 1000 } });
-		expect(checkBudgetOnTurnEnd(s).warnings).toContainEqual({ type: "warning70", dimension: "token" });
+		expect(checkBudgetOnTurnEnd(s).warnings).toContainEqual({ type: "warning70" });
 	});
 	it("token >= 70% 已发 → 不重复", () => {
 		const s = makeState({ tokensUsed: 750, tokenWarning70Sent: true, budget: { tokenBudget: 1000 } });
-		expect(checkBudgetOnTurnEnd(s).warnings).not.toContainEqual({ type: "warning70", dimension: "token" });
+		expect(checkBudgetOnTurnEnd(s).warnings).not.toContainEqual({ type: "warning70" });
 	});
 	it("token >= 90% 未发 steering → shouldSendSteering", () => {
 		const s = makeState({ tokensUsed: 950, budget: { tokenBudget: 1000 } });
 		expect(checkBudgetOnTurnEnd(s).shouldSendSteering).toBe(true);
 	});
-	it("token >= 100% 已发 steering → terminal exceeded token", () => {
+	it("token >= 100% 已发 steering → terminal exceeded", () => {
 		const s = makeState({ tokensUsed: 1000, budgetLimitSteeringSent: true, budget: { tokenBudget: 1000 } });
-		expect(checkBudgetOnTurnEnd(s).terminal).toEqual({ type: "exceeded", dimension: "token" });
+		expect(checkBudgetOnTurnEnd(s).terminal).toEqual({ type: "exceeded" });
 	});
 });
 
@@ -96,9 +96,9 @@ describe("checkBudgetOnResume", () => {
 	it("无预算 → null", () => {
 		expect(checkBudgetOnResume(makeState())).toBeNull();
 	});
-	it("token 超额 → exceeded token", () => {
+	it("token 超额 → exceeded", () => {
 		const s = makeState({ tokensUsed: 1000, budget: { tokenBudget: 1000 } });
-		expect(checkBudgetOnResume(s)).toEqual({ type: "exceeded", dimension: "token" });
+		expect(checkBudgetOnResume(s)).toEqual({ type: "exceeded" });
 	});
 	it("未超额 → null", () => {
 		const s = makeState({ tokensUsed: 500, budget: { tokenBudget: 1000 } });

package/src/engine/__tests__/goal.test.ts

@@ -6,6 +6,9 @@
  */
 import { describe, expect } from "vitest";
 import { it, fc } from "@fast-check/vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { createGoalState, isActiveStatus, isTerminalStatus, transitionStatus } from "../goal";
 import { VALID_TRANSITIONS } from "../types";
@@ -53,7 +56,6 @@ describe("createGoalState", () => {
 			tokensUsed: 0,
 			timeUsedSeconds: 0,
 			currentTurnIndex: 0,
-			lastProgressTurn: 0,
 			lastTurnTokensUsed: 0,
 			budgetLimitSteeringSent: false,
 			tokenWarning70Sent: false,
@@ -84,3 +86,40 @@ describe("createGoalState", () => {
 		});
 	});
 });
+
+// ── E1 守卫：状态变更唯一执行点（.status 裸赋值扫描）──
+
+describe("E1 守卫：src 内禁止 .status 裸赋值（必须走 transitionStatus 查表）", () => {
+	it("扫描 src/**/*.ts（排除 __tests__）：0 命中", () => {
+		// 正则逐字来自设计 docs/design/ext-simplify-03-goal.md §5.4「E1 守卫设计」，不得自行修改：
+		// (?![=>]) 排除 ==/===/=>（比较与箭头函数形态）；(?!\s*transitionStatus\b) 放行白名单查表赋值。
+		// 扫描粒度 = 整文件内容（非逐行）：\s* 必须能跨行吃换行，才能排除
+		// `state.status =\n transitionStatus(...)` 这类跨行白名单赋值形态，逐行实现会误报。
+		const re = /\.status\s*=(?![=>])(?!\s*transitionStatus\b)/g;
+		const srcDir = fileURLToPath(new URL("../../", import.meta.url));
+		const offenders: string[] = [];
+		const walk = (dir: string): void => {
+			for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+				if (dirent.name === "__tests__") continue;
+				const abs = join(dir, dirent.name);
+				if (dirent.isDirectory()) {
+					walk(abs);
+				} else if (dirent.isFile() && dirent.name.endsWith(".ts")) {
+					const content = readFileSync(abs, "utf8");
+					let match: RegExpExecArray | null;
+					while ((match = re.exec(content)) !== null) {
+						// 行号 = 命中起点之前的换行数 + 1
+						const line = content.slice(0, match.index).split("\n").length;
+						offenders.push(`${abs}:${line}`);
+					}
+				}
+			}
+		};
+		walk(srcDir);
+		expect(
+			offenders,
+			`检测到 ${offenders.length} 处 .status 裸赋值（状态变更必须走 transitionStatus 查表，见设计 §5.4 E1 / VALID_TRANSITIONS engine/types.ts）:\n`
+				+ offenders.join("\n"),
+		).toEqual([]);
+	});
+});

package/src/engine/budget.ts

@@ -35,20 +35,14 @@ export interface TickResult {
 	timeStartedAt: number;
 }
 
-/** 预算维度（time budget 已移除，仅 token）。 */
-export type BudgetDimension = "token";
-
-export type BudgetDecision =
-	| { type: "warning70"; dimension: BudgetDimension }
-	| { type: "warning90"; dimension: BudgetDimension };
+export type BudgetDecision = { type: "warning70" } | { type: "warning90" };
 
 export interface BudgetCheckResult {
-	terminal: { type: "exceeded"; dimension: BudgetDimension } | null;
+	terminal: { type: "exceeded" } | null;
 	warnings: BudgetDecision[];
 	shouldSendSteering: boolean;
 }
 
-
 // ── token 累加（FR-8.6）──────────────────────────────
 
 export function accumulateTokens(currentTokensUsed: number, usage: TokenUsage): number {
@@ -130,15 +124,15 @@ export function checkBudgetOnTurnEnd(state: GoalRuntimeState): BudgetCheckResult
 	if (state.budget.tokenBudget) {
 		const tokenPct = state.tokensUsed / state.budget.tokenBudget;
 		if (tokenPct >= 1 && state.budgetLimitSteeringSent) {
-			result.terminal = { type: "exceeded", dimension: "token" };
+			result.terminal = { type: "exceeded" };
 			return result;
 		}
 		if (tokenPct >= BUDGET_RATIO_HIGH && !state.budgetLimitSteeringSent) {
 			result.shouldSendSteering = true;
 		} else if (tokenPct >= BUDGET_RATIO_HIGH && !state.tokenWarning90Sent) {
-			result.warnings.push({ type: "warning90", dimension: "token" });
+			result.warnings.push({ type: "warning90" });
 		} else if (tokenPct >= BUDGET_RATIO_LOW && !state.tokenWarning70Sent) {
-			result.warnings.push({ type: "warning70", dimension: "token" });
+			result.warnings.push({ type: "warning70" });
 		}
 	}
 
@@ -147,9 +141,9 @@ export function checkBudgetOnTurnEnd(state: GoalRuntimeState): BudgetCheckResult
 
 // ── resume 预算重检 ──────────────────────────────────
 
-export function checkBudgetOnResume(state: GoalRuntimeState): { type: "exceeded"; dimension: BudgetDimension } | null {
+export function checkBudgetOnResume(state: GoalRuntimeState): { type: "exceeded" } | null {
 	if (state.budget.tokenBudget && state.tokensUsed >= state.budget.tokenBudget) {
-		return { type: "exceeded", dimension: "token" };
+		return { type: "exceeded" };
 	}
 	return null;
 }

package/src/engine/goal.ts

@@ -50,9 +50,7 @@ export function createGoalState(
 		timeStartedAt: now,
 		timeUsedSeconds: 0,
 		budget: { ...DEFAULT_BUDGET, ...budgetOverrides },
-		lastProgressTurn: 0,
 		budgetLimitSteeringSent: false,
-		objectiveUpdatedAt: now,
 		lastBlockerReason: null,
 		tokenWarning70Sent: false,
 		tokenWarning90Sent: false,

package/src/engine/types.ts

@@ -71,9 +71,7 @@ export interface GoalRuntimeState {
 	timeStartedAt: number;
 	timeUsedSeconds: number;
 	budget: BudgetConfig;
-	lastProgressTurn: number;
 	budgetLimitSteeringSent: boolean;
-	objectiveUpdatedAt: number;
 	lastBlockerReason: string | null;
 	// token 维度预警 flag（time budget 已移除，仅 token 70/90 两个 flag）
 	tokenWarning70Sent: boolean;

package/src/index.ts

@@ -9,69 +9,29 @@
  * - ports.ts：机器可检查的能力边界
  * - adapters/ports.ts：Pi → ServicePorts 桥接（单一构造点）
  * - service.ts：事件入口协调器（applyEvent）
- * - adapters/：Pi 桥接（command-adapter / event-adapter / ports）
+ * - adapters/：Pi 桥接（command-adapter / event-handlers / ports）
  * - projection/：渲染（widget / prompts）
  *
  * FR-4.2/D-16：ctx 必填，移除 lastCtx 模块级可变状态。
  * FR-6.4：移除 hasPendingInjection。
- * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在 event-adapter）。
+ * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在各 event handler）。
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, MessageEndEvent } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
 import { handleGoalCommand } from "./adapters/command-adapter";
-import {
-	handleAgentEnd,
-	handleBeforeAgentStart,
-	handleMessageEnd,
-	handleSessionShutdown,
-	handleSessionStart,
-	handleTurnEnd,
-	type MessageEndLikeEvent,
-} from "./adapters/event-adapter";
+import { handleAgentEnd } from "./adapters/event-handlers/agent-end";
+import { handleBeforeAgentStart } from "./adapters/event-handlers/before-agent-start";
+import { handleMessageEnd } from "./adapters/event-handlers/message-end";
+import { handleSessionShutdown } from "./adapters/event-handlers/session-shutdown";
+import { handleSessionStart } from "./adapters/event-handlers/session-start";
+import { handleTurnEnd } from "./adapters/event-handlers/turn-end";
 import { registerGoalControlTool } from "./adapters/goal-control-adapter";
 import { buildPorts } from "./adapters/ports";
 import { createGoal } from "./service";
 import { createGoalSession, type GoalSession } from "./session";
 
-// ── Local Interfaces (Like*Event — 避免 any on Pi callback/event signatures) ────
-
-interface BeforeAgentStartLikeEvent {
-	type: "before_agent_start";
-	prompt: string;
-	systemPrompt: string;
-}
-
-interface TurnEndLikeEvent {
-	type: "turn_end";
-	turnIndex: number;
-}
-
-interface AgentEndLikeEvent {
-	type: "agent_end";
-	messages: unknown[];
-}
-
-interface SessionStartLikeEvent {
-	type: "session_start";
-	reason: string;
-}
-
-interface SessionShutdownLikeEvent {
-	type: "session_shutdown";
-	reason: "quit" | "reload" | "new" | "resume" | "fork";
-}
-
-interface LikeCustomMessage {
-	customType: string;
-	content: string | unknown;
-}
-
-interface LikeMessageRenderOptions {
-	expanded: boolean;
-}
-
 // ── Extension Factory ─────────────────────────────────
 
 export default function goalExtension(pi: ExtensionAPI) {
@@ -106,32 +66,32 @@ export default function goalExtension(pi: ExtensionAPI) {
 
 	registerGoalControlTool(pi, session);
 
-	// ── Events（全部委托 adapters/event-adapter）────────
+	// ── Events（全部委托 adapters/event-handlers）────────
 
-	pi.on("before_agent_start", async (_event: BeforeAgentStartLikeEvent, ctx: ExtensionContext) => {
+	pi.on("before_agent_start", async (_event, ctx: ExtensionContext) => {
 		return handleBeforeAgentStart(pi, session, ctx);
 	});
 
-	pi.on("turn_end", async (_event: TurnEndLikeEvent, ctx: ExtensionContext) => {
+	pi.on("turn_end", async (_event, ctx: ExtensionContext) => {
 		await handleTurnEnd(pi, session, ctx);
 	});
 
-	pi.on("message_end", async (event: MessageEndLikeEvent, ctx: ExtensionContext) => {
+	pi.on("message_end", async (event: MessageEndEvent, ctx: ExtensionContext) => {
 		await handleMessageEnd(session, ctx, event);
 	});
 
-	pi.on("agent_end", async (_event: AgentEndLikeEvent, ctx: ExtensionContext) => {
+	pi.on("agent_end", async (_event, ctx: ExtensionContext) => {
 		await handleAgentEnd(pi, session, ctx);
 	});
 
-	pi.on("session_start", async (_event: SessionStartLikeEvent, ctx: ExtensionContext) => {
+	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
 		await handleSessionStart(pi, session, ctx);
 	});
 
 	// MF-R2-1 根修：session_shutdown 在 runner invalidate 之前触发（此刻 pi/ctx
 	// 仍可用），取消待发的退避 continuation timer——覆盖 reload / new / resume /
 	// fork / quit 全部失效路径，旧 timer 不再携 stale ctx 闭包存活到到期
-	pi.on("session_shutdown", async (_event: SessionShutdownLikeEvent, _ctx: ExtensionContext) => {
+	pi.on("session_shutdown", async (_event, _ctx: ExtensionContext) => {
 		await handleSessionShutdown(session);
 	});
 
@@ -141,7 +101,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 	for (const customType of goalMessageTypes) {
 		pi.registerMessageRenderer(
 			customType,
-			(message: LikeCustomMessage, _options: LikeMessageRenderOptions, theme: Theme) => {
+			(message, _options, theme) => {
 				const prefix =
 					message.customType === "goal-context-exceeded"
 						? theme.fg("error", "[GOAL Budget] ")

package/src/persistence.ts

@@ -1,8 +1,9 @@
 /**
  * 持久化层 — serialize/deserialize + history entry 构造
  *
- * FR-5: 移除旧格式兼容，字段缺失直接 throw（tasks 字段例外——向后兼容忽略）。
- * 零 Pi 依赖。
+ * FR-5：必填字段缺失直接 throw；旧格式容忍面（time_limited → budget_limited 迁移、
+ * successCriteria 旧格式归一、W5 熔断计数缺省归零、slug/completedAtTurnIndex 可选解析、
+ * tasks 及未知字段白名单忽略）见 deserializeState 各迁移点注释。零 Pi 依赖。
  */
 
 import type { GoalRuntimeState, GoalStatus } from "./engine/types";
@@ -22,7 +23,7 @@ export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
 	};
 }
 
-// ── deserialize（FR-5 严格解析，缺字段 throw）──────────
+// ── deserialize（FR-5 严格解析，缺必填字段 throw）──────────
 
 /**
  * 旧持久化状态归一化（唯一迁移点）。
@@ -95,9 +96,7 @@ export function deserializeState(data: Record<string, unknown>): GoalRuntimeStat
 		timeStartedAt: req("timeStartedAt"),
 		timeUsedSeconds: req("timeUsedSeconds"),
 		budget: req("budget"),
-		lastProgressTurn: req("lastProgressTurn"),
 		budgetLimitSteeringSent: req("budgetLimitSteeringSent"),
-		objectiveUpdatedAt: req("objectiveUpdatedAt"),
 		lastBlockerReason: req("lastBlockerReason"),
 		tokenWarning70Sent: req("tokenWarning70Sent"),
 		tokenWarning90Sent: req("tokenWarning90Sent"),

package/src/ports.ts

@@ -35,6 +35,17 @@ export interface PersistencePort {
 	appendHistory(entry: GoalHistoryEntry): void;
 }
 
+// ── ThemeLike ────────────────────────────────────────
+
+/**
+ * projection 层的 Theme 抽象。不 import Pi 的 ThemeColor。
+ * adapter 层负责把 Pi 的 theme（fg 接收 ThemeColor）适配到此签名（fg 接收 string）。
+ */
+export interface ThemeLike {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+}
+
 // ── UiPort ───────────────────────────────────────────
 
 export interface UiPort {
@@ -54,6 +65,8 @@ export interface UiPort {
 	readonly hasUI: boolean;
 	/** 是否 GUI 渲染模式（RPC → GuiComponent；TUI → 原生文本行） */
 	readonly isGui: boolean;
+	/** 终端主题能力（fg/bold 着色），widget/status 文本行渲染消费（E3 显式声明） */
+	readonly theme: ThemeLike;
 }
 
 // ── MessagingPort ────────────────────────────────────
@@ -75,7 +88,4 @@ export interface SessionEntryLike {
 
 export interface SessionPort {
 	getEntries(): SessionEntryLike[];
-	// tokens 与 Pi SDK 的 ContextUsage.tokens 对齐：number | null（null = 未知，如压缩后未到下次 LLM 响应）。
-	getContextUsage(): { tokens: number | null; contextWindow: number } | null;
-	readonly signal: AbortSignal | undefined;
 }

package/src/projection/__tests__/prompts.test.ts

@@ -1,8 +1,8 @@
 /**
- * projection/prompts.ts 测试 — prompt 生成函数 + formatBudget 2 样式
+ * projection/prompts.test.ts 测试 — prompt 生成函数 + budget 片段格式化
  *
  * 覆盖：
- * - formatBudget 2 种 style（percent/line）
+ * - formatBudgetPercent / formatBudgetLine
  * - escapeXmlText（XML 注入防护）
  * - continuationPrompt / budgetLimitPrompt / objectiveUpdatedPrompt / contextInjectionPrompt
  *
@@ -19,7 +19,8 @@ import {
 	contextInjectionPrompt,
 	continuationPrompt,
 	escapeXmlText,
-	formatBudget,
+	formatBudgetLine,
+	formatBudgetPercent,
 	objectiveUpdatedPrompt,
 } from "../prompts";
 
@@ -32,31 +33,38 @@ function makeState(overrides?: Partial<GoalRuntimeState>): GoalRuntimeState {
 	};
 }
 
-// ── formatBudget 2 样式（FR-3.4 唯一收敛出口）────────
+// ── budget 片段格式化 ────────────────────────────────
 
-describe("formatBudget — 2 styles (FR-3.4)", () => {
-	it("percent: Token 百分比", () => {
+describe("formatBudgetPercent", () => {
+	it("有预算 → Token 百分比", () => {
 		const state = makeState({
 			budget: { tokenBudget: 1000 },
 			tokensUsed: 500,
 		});
-		const out = formatBudget(state, "percent");
+		const out = formatBudgetPercent(state);
 		expect(out).toContain("Token: 50%");
 	});
 
-	it("percent: 无预算 → 空字符串", () => {
+	it("无预算 → 空字符串", () => {
 		const state = makeState();
-		expect(formatBudget(state, "percent")).toBe("");
+		expect(formatBudgetPercent(state)).toBe("");
 	});
+});
 
-	it("line: 剩余/总量格式", () => {
+describe("formatBudgetLine", () => {
+	it("有预算 → 剩余/总量格式", () => {
 		const state = makeState({
 			budget: { tokenBudget: 1000 },
 			tokensUsed: 300,
 		});
-		const out = formatBudget(state, "line");
+		const out = formatBudgetLine(state);
 		expect(out).toContain("Tokens: 700/1000");
 	});
+
+	it("无预算 → 空字符串", () => {
+		const state = makeState();
+		expect(formatBudgetLine(state)).toBe("");
+	});
 });
 
 // ── escapeXmlText（XML 注入防护）──────────────────────

package/src/projection/__tests__/widget.test.ts

@@ -14,14 +14,13 @@ import { describe, expect, it } from "vitest";
 
 import { createGoalState } from "../../engine/goal";
 import type { GoalRuntimeState, GoalStatus } from "../../engine/types";
-import type { UiPort } from "../../ports";
+import type { ThemeLike, UiPort } from "../../ports";
 import { createGoalSession } from "../../session";
 import { OBJECTIVE_DISPLAY_LIMIT, OBJECTIVE_TRUNCATE_KEEP } from "../../constants";
 import {
 	renderStatusLine,
 	renderTerminalStatusLine,
 	renderWidgetLines,
-	type ThemeLike,
 	toSingleLine,
 	updateWidget,
 } from "../widget";
@@ -221,8 +220,10 @@ describe("updateWidget (FR-6.6 hasUI guard)", () => {
 				calls.push({ method: "setStatus", args: [name, text] });
 			},
 			notify() {},
-			fg: (_color: string, text: string) => text,
-			bold: (text: string) => text,
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
 		} as UiPort;
 		return { ui, calls };
 	}
@@ -300,8 +301,10 @@ describe("updateWidget GUI 协议分支（isGui=true）", () => {
 				calls.push({ method: "setStatus", args: [name, text] });
 			},
 			notify() {},
-			fg: (_color: string, text: string) => text,
-			bold: (text: string) => text,
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
 		} as UiPort;
 		return { ui, calls };
 	}

package/src/projection/prompts.ts

@@ -1,7 +1,7 @@
 /**
  * Steering prompt 模板（projection 层）
  *
- * 类型 import 自 engine/types.ts。FR-3.4：formatBudget 单一出口。
+ * 类型 import 自 engine/types.ts。
  *
  * 设计原则（来自 Codex 调研）：
  * - Completion audit: 逐项证据验证，intent/partial progress 不是 evidence
@@ -42,31 +42,10 @@ function successCriteriaBlock(state: GoalRuntimeState): string {
 	return `<successCriteria>\n${items}\n</successCriteria>\n`;
 }
 
-// ── FR-3.4：唯一 budget 格式化收敛出口 ─────────────────
+// ── budget 片段格式化 ────────────────────────────────
 
-export type BudgetFormatStyle = "percent" | "line";
-
-/**
- * FR-3.4 唯一 budget 格式化收敛出口。
- *
- * 2 种输出样式：
- * - "percent"  → ` (Token: N%)`（contextInjectionPrompt 用）
- * - "line"     → ` | Tokens: remaining/total`（continuationPrompt 用）
- *
- * @param state runtime state（读 budget / tokensUsed）
- * @param style 输出形式
- */
-export function formatBudget(
-	state: GoalRuntimeState,
-	style: BudgetFormatStyle,
-): string {
-	if (style === "percent") {
-		return formatBudgetPercent(state);
-	}
-	return formatBudgetLine(state);
-}
-
-function formatBudgetPercent(state: GoalRuntimeState): string {
+/** ` (Token: N%)`（contextInjectionPrompt 用）。无预算返回空串。 */
+export function formatBudgetPercent(state: GoalRuntimeState): string {
 	if (state.budget.tokenBudget) {
 		const pct = Math.round((state.tokensUsed / state.budget.tokenBudget) * PERCENT_FACTOR);
 		return ` (Token: ${pct}%)`;
@@ -74,7 +53,8 @@ function formatBudgetPercent(state: GoalRuntimeState): string {
 	return "";
 }
 
-function formatBudgetLine(state: GoalRuntimeState): string {
+/** ` | Tokens: remaining/total`（continuationPrompt 用）。无预算返回空串。 */
+export function formatBudgetLine(state: GoalRuntimeState): string {
 	if (state.budget.tokenBudget) {
 		const remaining = Math.max(state.budget.tokenBudget - state.tokensUsed, 0);
 		return ` | Tokens: ${remaining}/${state.budget.tokenBudget}`;
@@ -86,7 +66,7 @@ function formatBudgetLine(state: GoalRuntimeState): string {
 
 export function continuationPrompt(state: GoalRuntimeState): string {
 	const objective = escapeXmlText(state.objective);
-	const budgetLine = formatBudget(state, "line");
+	const budgetLine = formatBudgetLine(state);
 	const criteria = successCriteriaBlock(state);
 
 	return (
@@ -190,7 +170,7 @@ export function objectiveUpdatedPrompt(
  */
 export function contextInjectionPrompt(state: GoalRuntimeState): string {
 	const objective = escapeXmlText(state.objective);
-	const budgetInfo = formatBudget(state, "percent");
+	const budgetInfo = formatBudgetPercent(state);
 	const criteria = successCriteriaBlock(state);
 
 	return (

package/src/projection/widget.ts

@@ -2,8 +2,8 @@
  * Widget 渲染逻辑（projection 层）— 状态栏和侧边栏面板
  *
  * 设计要点：
- * - 不 import Pi 类型（ThemeColor → ThemeLike，fg 接收 string）
- * - 类型 import 自 engine/types.ts
+ * - 不 import Pi 类型（theme 能力经 ports.ts 的 ThemeLike 抽象，fg 接收 string）
+ * - 类型 import 自 engine/types.ts 与 ports.ts（ThemeLike 上移至接口层）
  * - 工具函数 import 自 engine/budget.ts
  * - 时间计算基于 state.timeUsedSeconds（不含 Date.now() 副作用段）
  * - updateWidget(session, uiPort) 含 FR-6.6 hasUI 守卫
@@ -26,19 +26,10 @@ import {
 import { getBudgetColor, getTokenUsagePercent } from "../engine/budget";
 import { isTerminalStatus } from "../engine/goal";
 import type { GoalRuntimeState } from "../engine/types";
-import type { UiPort } from "../ports";
+import type { ThemeLike, UiPort } from "../ports";
 import type { GoalSession } from "../session";
 import { buildGoalGui } from "./gui";
 
-/**
- * projection 层的 Theme 抽象。不 import Pi 的 ThemeColor。
- * adapter 层负责把 Pi 的 theme（fg 接收 ThemeColor）适配到此签名（fg 接收 string）。
- */
-export interface ThemeLike {
-	fg: (color: string, text: string) => string;
-	bold: (text: string) => string;
-}
-
 /**
  * 将多行文本压缩为单行，用于 widget 渲染。
  * 多行 content 泄漏到 widget 会导致 markdown 表格/标题等破坏布局。
@@ -195,29 +186,6 @@ export function renderWidgetLines(state: GoalRuntimeState, th: ThemeLike): strin
 
 // ── updateWidget（FR-6.6 hasUI 守卫）──
 
-/**
- * 从 UiPort 取出 ThemeLike。
- *
- * ports.ts 的 UiPort 故意不暴露 theme（保持抽象最小）。adapter 层在
- * 构造 UiPort 实现时，把 Pi 的 ctx.ui.theme 的 fg/bold 方法挂到对象上，
- * 使该实现同时满足 UiPort 与 ThemeLike 形状。projection 层通过此单步断言取出。
- */
-function asTheme(uiPort: UiPort): ThemeLike {
-	// UiPort 刻意不声明 fg/bold（D-22：只声明机器可检查的能力边界），与 ThemeLike 无类型重叠，
-	// 必须 unknown 中转——这是架构契约断言：ports.ts 构造 UiPort 实现时已把 ctx.ui.theme 的
-	// fg/bold 挂到对象上（buildPorts 的 uiPort 对象含全部字段），运行时必然存在。
-	// eslint-disable-next-line taste/no-unsafe-cast
-	return uiPort as unknown as ThemeLike;
-}
-
-/**
- * 导出 asTheme：单一 theme 提取断言点（TS-1）。
- *
- * adapter 层（event-adapter handleTerminalStateBeforeAgent）复用本函数，
- * 避免重复 `ctx.ui.theme as unknown as ThemeLike` 断言。
- */
-export { asTheme };
-
 /**
  * 刷新 widget + status bar。
  *
@@ -243,7 +211,7 @@ export function updateWidget(session: GoalSession, uiPort: UiPort): void {
 
 	// 终态折叠为单行 status bar
 	if (isTerminalStatus(session.state.status)) {
-		const statusText = renderTerminalStatusLine(session.state, asTheme(uiPort));
+		const statusText = renderTerminalStatusLine(session.state, uiPort.theme);
 		if (statusText) {
 			uiPort.setStatus("goal", statusText);
 		}
@@ -252,11 +220,11 @@ export function updateWidget(session: GoalSession, uiPort: UiPort): void {
 		return;
 	}
 
-	uiPort.setStatus("goal", renderStatusLine(session.state, asTheme(uiPort)));
+	uiPort.setStatus("goal", renderStatusLine(session.state, uiPort.theme));
 	if (isGui) {
 	// 复用 projection/gui.ts 的 buildGoalGui（整个 GuiRenderResult：component + meta 宿主元数据）
 		uiPort.setGuiWidget("goal", buildGoalGui(session.state));
 	} else {
-		uiPort.setWidget("goal", renderWidgetLines(session.state, asTheme(uiPort)));
+		uiPort.setWidget("goal", renderWidgetLines(session.state, uiPort.theme));
 	}
 }

package/src/service.ts

@@ -60,7 +60,7 @@ export function tickState(state: GoalRuntimeState): void {
  * 这类「active → 非活跃」的转换，调用方必须在改 status **之前**先调本函数
  * （或先调 {@link tickState} 捕获最后运行段）。
  *
- * 导出供 command-adapter / event-adapter 复用（DRY：所有路径共用同一持久化语义）。
+ * 导出供 command-adapter / goal-control-adapter 复用（DRY：所有路径共用同一持久化语义）。
  */
 export function persistState(session: GoalSession, ports: ServicePorts): void {
 	if (!session.state) return;
@@ -154,9 +154,9 @@ export function createGoal(
 /**
  * 唯一终态序列入口（FR-3.3 / AC-3）。
  *
- * 收口所有 active→terminal 转换的完整副作用序列，消除此前散在 service /
- * command-adapter / event-adapter 的重复 `transitionStatus + completedAtTurnIndex +
- * writeHistory + appendState` 序列。
+ * 收口所有 active→terminal 转换的完整副作用序列——service（budget 终态）与
+ * command-adapter（clear / resume 超预算）、goal-control-adapter（complete）共用
+ * 同一 `transitionStatus + completedAtTurnIndex + writeHistory + appendState` 序列。
  *
  * 序列（严格顺序）：
  * 1. tickState(state)（FR-6.5：转 terminal 前累加当前运行段——此时 status 仍为 active）
@@ -237,10 +237,10 @@ function toMessageEndData(eventData: unknown): MessageEndEventData | null {
 
 /**
  * 路径 B 入口。异步事件，无返回值（副作用直接 mutate session.state）。
- * 并发保护（isProcessing / stale-check）在 event-adapter，不在此层。
+ * 并发保护（isProcessing / stale-check）在 event-handlers（agent-end.ts），不在此层。
  *
  * 本函数作为简单事件的统一入口（message_end / turn_end）。
- * 复杂事件（before_agent_start / agent_end / session_start）由 event-adapter
+ * 复杂事件（before_agent_start / agent_end / session_start）由 event-handlers
  * 直接实现，调 engine 纯函数 + service 辅助函数。
  *
  * H3：不再返回 effect 数组。turn_end 的 updateWidget 副作用由调用方

package/src/adapters/event-adapter.ts

@@ -1,17 +0,0 @@
-/**
- * Event adapter — 薄路由（#4 拆分后）。
- *
- * 6 个事件 handler + 1 个共享辅助拆在 event-handlers/，本文件只做 re-export。
- * handler 逻辑见各自文件。pi.on 注册在 index.ts（保持不变）。
- *
- * 行为等价（#4 验收）：handler 逻辑原样搬迁，仅 persistAndUpdate 签名 ports 化
- * （见 service.ts）+ turn_end 的 buildPorts 调用从两次收敛为一次。
- */
-
-export { handleAgentEnd } from "./event-handlers/agent-end";
-export { handleBeforeAgentStart } from "./event-handlers/before-agent-start";
-export type { MessageEndLikeEvent } from "./event-handlers/message-end";
-export { handleMessageEnd } from "./event-handlers/message-end";
-export { handleSessionShutdown } from "./event-handlers/session-shutdown";
-export { handleSessionStart } from "./event-handlers/session-start";
-export { handleTurnEnd } from "./event-handlers/turn-end";

package/src/adapters/event-handlers/shared.ts

@@ -1,27 +0,0 @@
-/**
- * event-handlers 共享辅助（adapters/event-handlers 层）。
- *
- * - makeStaleChecker：FR-8.2 G-020 goalId snapshot，agent_end 入口构造、每个副作用前 checkStale
- *
- * handleAgentEnd 直接操纵 session.isProcessing（历史实现），无需 acquire/release 封装。
- */
-
-import type { GoalSession } from "../../session";
-
-/**
- * 构造 stale-check 闭包：入口快照 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;
-}