@zhushanwen/pi-goal 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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,12 +29,13 @@
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-pending-notifications": "0.9.0"
+    "@zhushanwen/pi-pending-notifications": "0.10.1"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.23.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-session-path": "0.1.0"
+    "@zhushanwen/pi-session-path": "0.1.0",
+    "@zhushanwen/state-machine": "0.2.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/src/__tests__/active-path.test.ts

@@ -127,7 +127,7 @@ interface HandlerFixture {
 	appendEntry: ReturnType<typeof vi.fn>;
 }
 
-/** 实例化 goal 工厂并捕获事件 handler（最小 pi：注册面 vi.fn + 副作用面 vi.fn） */
+/** 实例化 goal 工厂并捕获事件 handler（最小 pi：注册点 vi.fn + 副作用侧 vi.fn） */
 function makeHandlerFixture(): HandlerFixture {
 	const handlers = new Map<string, (event: unknown, ctx: ExtensionContext) => Promise<unknown>>();
 	const pi = {
@@ -145,7 +145,7 @@ function makeHandlerFixture(): HandlerFixture {
 	return { handlers, sendMessage: pi.sendMessage, appendEntry: pi.appendEntry };
 }
 
-/** 最小 ctx：sessionManager（分支树）+ ui 记录面 + getContextUsage（before_agent_start 用） */
+/** 最小 ctx：sessionManager（分支树）+ ui 记录侧 + getContextUsage（before_agent_start 用） */
 function makeCtx(entries: SessionEntryLike[], leafId: string | null) {
 	const setWidget = vi.fn();
 	const setStatus = vi.fn();

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

@@ -1,5 +1,5 @@
 /**
- * 轮次活性熔断行为测试（chat-domain-v1x 设计 §3.2 D4 / W5，验收 §4 A10 的单测面）
+ * 轮次活性熔断行为测试（chat-domain-v1x 设计 §3.2 D4 / W5，验收 §4 A10 的单测）
  *
  * 四断言（对齐 impl-plan W5 验收条款②）：
  * a. 主判据 50 次封顶必停发——含「每轮调一次工具」序列同样被封顶（正交性：
@@ -43,7 +43,7 @@ interface FakeHarness {
 	entries: unknown[];
 	piCalls: RecordedCall[];
 	ctxCalls: RecordedCall[];
-	/** 可控 isIdle（MF-6① 守卫断言用：延迟窗内有活动 turn 时置 false） */
+	/** 可控 isIdle（MF-6① 检查断言用：延迟窗内有活动 turn 时置 false） */
 	isIdle: { value: boolean };
 	/**
 	 * 可控 appendEntry 抛错（MF-R2-1 测试前提修正）：pi.appendEntry 与 ctx 同生命周期
@@ -336,11 +336,11 @@ async function enterBackoff(): Promise<{ h: FakeHarness; session: GoalSession }>
 	return { h, session };
 }
 
-describe("MF-6① idle 守卫：ctx.signal 实时求值失效场景由 isIdle 拦截", () => {
+describe("MF-6① idle 检查：ctx.signal 实时求值失效场景由 isIdle 拦截", () => {
 	it("延迟窗内有活动 turn（isIdle=false、signal=undefined）→ 到期不误发", async () => {
 		const { h, session } = await enterBackoff();
 
-		// agent idle 后 SDK get signal 实时求值为 undefined（旧 signal?.aborted 守卫恒放行）；
+		// agent idle 后 SDK get signal 实时求值为 undefined（旧 signal?.aborted 检查恒放行）；
 		// 用户在延迟窗内发新消息 → 活动 turn 占用 → isIdle=false
 		h.ctx.signal = undefined;
 		h.isIdle.value = false;
@@ -350,7 +350,7 @@ describe("MF-6① idle 守卫：ctx.signal 实时求值失效场景由 isIdle
 		expect(session.state!.continuationsSent).toBe(4);
 	});
 
-	it("延迟窗内 idle（isIdle=true、signal=undefined）→ 正常发出（守卫不误伤退避路径）", async () => {
+	it("延迟窗内 idle（isIdle=true、signal=undefined）→ 正常发出（检查不误伤退避路径）", async () => {
 		const { h, session } = await enterBackoff();
 
 		h.ctx.signal = undefined;
@@ -403,7 +403,7 @@ describe("MF-6② stale 保护：timer 回调内异常不冒泡（catch 块自
 	});
 });
 
-describe("MF-R2-1 根修：session_shutdown 取消旧退避 timer", () => {
+describe("MF-R2-1 从根源修复：session_shutdown 取消旧退避 timer", () => {
 	it("session_shutdown（invalidate 前触发）后旧 timer 到期不发；全量 stale 下不崩、不冒泡", async () => {
 		const { h, session } = await enterBackoff();
 
@@ -430,7 +430,7 @@ describe("MF-R2-1 根修：session_shutdown 取消旧退避 timer", () => {
 	});
 });
 
-describe("MF-6③ timer 清理面：session_start / before_agent_start 取消旧 timer", () => {
+describe("MF-6③ timer 清理侧：session_start / before_agent_start 取消旧 timer", () => {
 	it("session_start 重建 → 旧退避 timer 被取消，到期不发", async () => {
 		const { h, session } = await enterBackoff();
 
@@ -459,13 +459,13 @@ describe("MF-6③ timer 清理面：session_start / before_agent_start 取消旧
 // 端口改造前 backoff timer 到期伪装用户消息投递；改造后
 // deliverContinuation 经端口发 custom message 且 options 含 triggerTurn: true——
 // 非 streaming idle 场景真实开轮（改造前 append 不开轮 = 死消息）。
-// isIdle=false 拦截见 MF-6①；封顶记账守卫见「主判据」describe；此处锁定到期
+// isIdle=false 拦截见 MF-6①；封顶记账检查见「主判据」describe；此处锁定到期
 // 发出路径的 options 契约与记账恰好 +1。
 describe("A8：退避 timer 到期 → triggerTurn: true 开轮发出", () => {
-	it("isIdle 守卫通过后发出：custom message 四要素齐备，记账恰好 +1", async () => {
+	it("isIdle 检查通过后发出：custom message 四要素齐备，记账恰好 +1", async () => {
 		const { h, session } = await enterBackoff();
 
-		vi.advanceTimersByTime(20_000); // 2×base 到期，isIdle 默认 true → 守卫放行
+		vi.advanceTimersByTime(20_000); // 2×base 到期，isIdle 默认 true → 检查放行
 
 		const sends = followUpSends(h);
 		expect(sends).toHaveLength(5); // 4 立即 + 1 到期发出

package/src/__tests__/criteria-array-prompt-guidance.test.ts

@@ -48,12 +48,12 @@ const successCriteriaSchema = GoalControlParams.properties.successCriteria;
 const PARAM_DESCRIPTION =
 	typeof successCriteriaSchema.description === "string" ? successCriteriaSchema.description : "";
 
-// ── 第 2 层切片：工具 description 模板字面量（"description: `" 到闭合反引号）──
+// ── 第 2 层切片：工具 description 模板字面量（"description: `" 到结束反引号）──
 
 const TOOL_DESCRIPTION = sliceBetween(ADAPTER_SRC, "description: `", "`");
 
 // ── 第 3 层切片：promptGuidelines 赋值块 ─────────────────────
-// 闭合 "]" 不能用 indexOf 找——块内 guideline 文本自身含 "string[]" 的 "]"，
+// 结束 "]" 不能用 indexOf 找——块内 guideline 文本自身含 "string[]" 的 "]"，
 // 故按行扫描 trim() === "]," 的行作块尾（缩进无关）。
 
 function extractPromptGuidelinesBlock(src: string): string {

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

@@ -181,9 +181,9 @@ describe("deserializeState — 旧数据迁移（time_limited → budget_limited
 		expect((state as unknown as { timeWarning90Sent?: unknown }).timeWarning90Sent).toBeUndefined();
 	});
 
-	it("归一化后是合法终态：/goal clear 守卫（!isTerminalStatus）跳过 transitionStatus，不 throw", () => {
+	it("归一化后是合法终态：/goal clear 检查（!isTerminalStatus）跳过 transitionStatus，不 throw", () => {
 		const state = deserializeState(LEGACY_DATA);
-		// handleClear（command-adapter.ts）的守卫：!isTerminalStatus 为 false → 直接 clearSession，
+		// handleClear（command-adapter.ts）的检查：!isTerminalStatus 为 false → 直接 clearSession，
 		// 不再走 finalizeAndPersist("cancelled") 的 transitionStatus 查表（旧值会 throw）。
 		expect(isTerminalStatus(state.status)).toBe(true);
 	});

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

@@ -1,7 +1,7 @@
 /**
  * event-handlers 行为测试 — agent_end / before_agent_start 核心逻辑
  *
- * 覆盖 agent_end 的 continuation + ESC 守卫（FR-6.7）+
+ * 覆盖 agent_end 的 continuation + ESC 检查（FR-6.7）+
  * before_agent_start 的 AUTO_CLEAR/context wrap-up。
  *
  * 全解耦后不再测 allTasksDone followUp（原依赖 pi.__todoGetList，已删）。
@@ -100,9 +100,9 @@ function makeRunningState(overrides?: Partial<GoalRuntimeState>): GoalRuntimeSta
 	};
 }
 
-// ── handleAgentEnd：ESC 守卫 ──────────────────────────
+// ── handleAgentEnd：ESC 检查 ──────────────────────────
 
-describe("handleAgentEnd — FR-6.7 ESC 守卫", () => {
+describe("handleAgentEnd — FR-6.7 ESC 检查", () => {
 	it("aborted=true：不发 continuation、不做 budget 检查、goal 保持 active", async () => {
 		const { pi, calls: piCalls, states } = makeFakePi();
 		const { ctx, calls: ctxCalls } = makeFakeCtx({ aborted: true });
@@ -174,9 +174,9 @@ describe("handleAgentEnd — continuation", () => {
 		expect(sendContext[0]!.content).toContain("[GOAL]");
 	});
 
-	// ── pending 守卫：background subagent/workflow 运行时不死循环 ──
+	// ── pending 检查：background subagent/workflow 运行时不死循环 ──
 
-	it("有活跃 pending → 不发 continuation（pending 守卫生效）", async () => {
+	it("有活跃 pending → 不发 continuation（pending 检查生效）", async () => {
 		const { pi, calls: piCalls } = makeFakePi();
 		const { ctx, calls: ctxCalls } = makeFakeCtx({
 			entries: [
@@ -258,7 +258,7 @@ describe("handleAgentEnd — continuation", () => {
 		expect(data?.ids).toEqual(["bg-1", "bg-2"]); // ids 透出
 	});
 
-	it("重复 register 同 id → 去重计为 1（seen.has 守卫）", async () => {
+	it("重复 register 同 id → 去重计为 1（seen.has 检查）", async () => {
 		const { pi, calls: piCalls, states } = makeFakePi();
 		const { ctx, calls: ctxCalls } = makeFakeCtx({
 			entries: [
@@ -272,7 +272,7 @@ describe("handleAgentEnd — continuation", () => {
 		await handleAgentEnd(pi, session, ctx);
 		const all = allCalls(piCalls, ctxCalls);
 
-		// 守卫触发：count>0 不发 continuation
+		// 检查触发：count>0 不发 continuation
 		const followUp = all.filter(
 			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
 		);
@@ -298,7 +298,7 @@ describe("handleAgentEnd — continuation", () => {
 		await handleAgentEnd(pi, session, ctx);
 		const all = allCalls(piCalls, ctxCalls);
 
-		// count=0，守卫不触发，走正常 continuation
+		// count=0，检查不触发，走正常 continuation
 		const followUp = all.filter(
 			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
 		);

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

@@ -2,8 +2,8 @@
  * goal_control adapter 测试 — handler 用 fake ports
  *
  * 覆盖 #3 验收：
- * - complete: active 守卫 + evidence 必填 + finalizeAndPersist（status→complete + history）
- * - report_blocked: active 守卫 + reason 必填 + tickState + transitionStatus(active→blocked) + persistState
+ * - complete: active 检查 + evidence 必填 + finalizeAndPersist（status→complete + history）
+ * - report_blocked: active 检查 + reason 必填 + tickState + transitionStatus(active→blocked) + persistState
  *
  * 全解耦后不再测 todo 前置检查（checkCompletePrerequisites / buildProgressInput / findIncompleteTodos 已删）。
  * complete 不做 todo 完成硬检查——AI 自行判断（prompt 软建议）。
@@ -74,7 +74,7 @@ const activeState = (overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeStat
 
 // ── handleComplete ───────────────────────────────────
 
-describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", () => {
+describe("handleComplete — active 检查 + evidence + finalizeAndPersist", () => {
 	it("active + evidence → status complete + 写 history", () => {
 		const session = createGoalSession();
 		session.state = activeState();
@@ -117,7 +117,7 @@ describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", ()
 
 // ── handleCreate ─────────────────────────────────────
 
-describe("handleCreate — objective/successCriteria 必填（handler 运行时校验）+ slug 真 optional + 非终态守卫 + createGoal", () => {
+describe("handleCreate — objective/successCriteria 必填（handler 运行时校验）+ slug 真 optional + 非终态检查 + createGoal", () => {
 	it("无旧 goal + slug + objective → status active + slug 写入 + 持久化 + notify", () => {
 		const session = createGoalSession();
 		const ports = makeFakePorts();
@@ -175,7 +175,7 @@ describe("handleCreate — objective/successCriteria 必填（handler 运行时
 	});
 
 	const NON_TERMINAL_STATUSES: GoalRuntimeState["status"][] = ["active", "paused", "blocked"];
-	it.each(NON_TERMINAL_STATUSES)("已有 %s goal → throw（D25 非终态守卫）", (status) => {
+	it.each(NON_TERMINAL_STATUSES)("已有 %s goal → throw（D25 非终态检查）", (status) => {
 		const session = createGoalSession();
 		session.state = activeState({ status });
 		expect(() =>
@@ -232,7 +232,7 @@ describe("handleCreate — objective/successCriteria 必填（handler 运行时
 
 // ── handleReportBlocked ──────────────────────────────
 
-describe("handleReportBlocked — active 守卫 + tick + transition + persist", () => {
+describe("handleReportBlocked — active 检查 + tick + transition + persist", () => {
 	it("active + reason → status blocked + reason 记录 + tick 累加", () => {
 		const session = createGoalSession();
 		const past = Date.now() - 4000;

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

@@ -17,7 +17,7 @@ import { describe, expect, it, vi, beforeEach } from "vitest";
 import { registerGoalControlTool, type GoalControlDetails } from "../adapters/goal-control-adapter";
 import { createGoalSession } from "../session";
 
-// ── mock：logger + updateWidget（UI 通道降级用例断言面；其余用例下两者为 no-op，
+// ── mock：logger + updateWidget（UI 通道降级用例断言范围；其余用例下两者为 no-op，
 //    与真实路径行为等价——fixture 的 setWidget/notify 本就是 no-op）──
 const loggerWarnSpy = vi.hoisted(() => vi.fn());
 vi.mock("@zhushanwen/pi-extension-logger", () => ({
@@ -150,9 +150,9 @@ describe("goal_control execute — RPC 模式 tool result 无 __gui__", () => {
 	});
 
 	it("RPC + session.state = null → 前置 handler throw（分支不可达）", async () => {
-		// execute 路径上，create 总会 set session.state；complete/report_blocked 前置守卫
+		// execute 路径上，create 总会 set session.state；complete/report_blocked 前置检查
 		// 要求 session.state 非 null 否则 throw——所以 session.state=null 时不会走到返回路径。
-		// 验证：全新 session（state=null）下，complete 前置守卫先 throw。
+		// 验证：全新 session（state=null）下，complete 前置检查先 throw。
 		const { pi, ctx } = makeFixture("rpc");
 		let captured: CapturedTool | undefined;
 		const capturePi = {
@@ -163,7 +163,7 @@ describe("goal_control execute — RPC 模式 tool result 无 __gui__", () => {
 		} as unknown as ExtensionAPI;
 		registerGoalControlTool(capturePi, createGoalSession());
 		const tool2 = captured!;
-		// complete 在 state=null 时 throw（handleComplete 前置守卫）
+		// complete 在 state=null 时 throw（handleComplete 前置检查）
 		await expect(
 			tool2.execute(
 				"id",

package/src/__tests__/index.test.ts

@@ -2,7 +2,7 @@
  * index.ts 测试 — 工厂入口 + 跨扩展 API（goalInit slot）
  *
  * 覆盖 T1.8 (NFR-AC-8)：goalInit 签名 (objective, budget, ctx, slug?, successCriteria?)，
- * 结构上无法接收 tasks（task CRUD 已删除，D-16/FR-4 双轨消除）。active 守卫由 service.test.ts 覆盖。
+ * 结构上无法接收 tasks（task CRUD 已删除，D-16/FR-4 双轨消除）。active 检查由 service.test.ts 覆盖。
  *
  * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再从 globalThis slot 读取 goalInit——
  * mock 形态与真实通道同构（goal-bridge-cross-extension.md §3.4：桥的元教训是 mock 世界

package/src/__tests__/liveness.test.ts

@@ -2,7 +2,7 @@
  * engine/liveness.ts 纯函数测试 — 轮次活性熔断判定单元（chat-domain-v1x D4 / W5）
  *
  * 覆盖：env 配置解析（合法/非法/缺省）、退避等级数学（第 N 轮起 ×2、指数天花板）、
- * 进展信号边界、toolCall 块计数（duck-typed 守卫）、pending 集合变化判定。
+ * 进展信号边界、toolCall 块计数（duck-typed 检查）、pending 集合变化判定。
  * 行为级四断言（封顶/退避/恢复/defer 去重经 handleAgentEnd）见 circuit-breaker.test.ts。
  */
 import { describe, expect, it } from "vitest";

package/src/__tests__/message-end.test.ts

@@ -1,7 +1,7 @@
 /**
- * message_end handler 测试（D13① role 过滤 + FR-6.7 ESC 守卫）。
+ * message_end handler 测试（D13① role 过滤 + FR-6.7 ESC 检查）。
  *
- * 断言面：仅 user/assistant 的 message_end 进入 service 消费；system（pi 1.0
+ * 断言范围：仅 user/assistant 的 message_end 进入 service 消费；system（pi 1.0
  * 新形态）/ toolResult / 缺 role 在 handler 层显式拒绝；assistant 正常透传。
  */
 
@@ -73,7 +73,7 @@ describe("handleMessageEnd（D13① role 过滤）", () => {
 		expect(spy).not.toHaveBeenCalled();
 	});
 
-	it("ESC 守卫先于 role 过滤（aborted 直接返回）", async () => {
+	it("ESC 检查先于 role 过滤（aborted 直接返回）", async () => {
 		const session = makeSession();
 		const spy = vi.mocked(applyEvent);
 		await handleMessageEnd(session, ctx(true), messageEndEvent("assistant"));

package/src/__tests__/ports.test.ts

@@ -6,7 +6,7 @@
  * - tui 模式：text 臂透传（pi 原生文本行，无 marker）
  * - undefined：清除语义（模式无关）
  *
- * 模式分派守卫单点在 protocol helpers.ts（守卫单点化），本测试只验证委托接线。
+ * 模式分派检查单点在 protocol helpers.ts（检查单点化），本测试只验证委托接线。
  *
  * 运行：cd extensions/universal/goal && npx vitest run src/__tests__/ports.test.ts
  */

package/src/__tests__/service.test.ts

@@ -123,7 +123,7 @@ describe("finalizeGoal — history 写入矩阵", () => {
 		const ports = makeFakePorts();
 		const state = makeState();
 		state.status = "complete";
-		// transitionStatus 查表：终态不可转，调用方须先 isTerminalStatus 守卫
+		// transitionStatus 查表：终态不可转，调用方须先 isTerminalStatus 检查
 		expect(() => finalizeGoal(state, "cancelled", ports)).toThrow();
 		expect(state.status).toBe("complete");
 	});
@@ -175,7 +175,7 @@ describe("applyEvent — 简单事件", () => {
 				usage: { input: 100, output: 50, cacheRead: 20 },
 			},
 		});
-		// 回归修复：blocked 状态不累加 token（原 bug：缺 isActiveStatus 守卫）
+		// 回归修复：blocked 状态不累加 token（原 bug：缺 isActiveStatus 检查）
 		expect(session.state.tokensUsed).toBe(before);
 	});
 

package/src/adapters/command-adapter.ts

@@ -353,7 +353,7 @@ function handleUpdate(
  * 这样 goal 创建的唯一路径是 goal_control toolcall（统一入口），
  * slug/objective/budget 都由 AI 在 toolcall 时决定。
  *
- * D25 守卫仍在此处预检：非终态旧 goal（active/paused/blocked）→ 拒绝，
+ * D25 检查仍在此处预检：非终态旧 goal（active/paused/blocked）→ 拒绝，
  * 提示 /goal resume 或 /goal clear（避免 AI 在已有未完成 goal 时重复创建）。
  *
  * budget flag（--tokens）写入消息体，让 AI 原样传给 create。

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

@@ -1,10 +1,10 @@
 /**
- * 事件 6: agent_end（FR-8.7 + ESC 守卫 + 并发保护）。
+ * 事件 6: agent_end（FR-8.7 + ESC 检查 + 并发保护）。
  *
  * 关键约定：
  * - FR-8.2 G-021 防重入：session.isProcessing 入口加锁，finally 释放
  * - FR-8.2 G-020 stale 快照：入口 makeStaleChecker snapshot goalId，每个副作用前 checkStale
- * - FR-6.7 ESC 守卫（最关键）：ctx.signal?.aborted → 不发 continuation、不做 budget 检查、
+ * - FR-6.7 ESC 检查（最关键）：ctx.signal?.aborted → 不发 continuation、不做 budget 检查、
  *   不做任何状态变更，goal 保持 active，等用户下次输入恢复
  *
  * #8 后流程：budget 预警/steering → continuation 去抖 + 轮次活性熔断（W5：
@@ -15,7 +15,7 @@
  * 全解耦：不再做 allTasksDone followUp（原依赖 pi.__todoGetList，跨 ext 失效）。
  * todo 是否全完成由 AI 自行判断（prompt 软建议）。
  *
- * ESC 路径：aborted 时直接 return（goal 保持 active）。注意 ESC 守卫在终态/非 active
+ * ESC 路径：aborted 时直接 return（goal 保持 active）。注意 ESC 检查在终态/非 active
  * 检查之后——终态 goal 仍走终态 notify（不被 ESC 影响），非 active 状态直接返回。
  */
 
@@ -63,7 +63,7 @@ export async function handleAgentEnd(
 		}
 		if (!isActiveStatus(session.state.status)) return;
 
-		// FR-6.7 ESC 守卫（最关键）：aborted 时 goal 保持 active，不做任何副作用
+		// FR-6.7 ESC 检查（最关键）：aborted 时 goal 保持 active，不做任何副作用
 		if (ctx.signal?.aborted) {
 			return;
 		}
@@ -152,7 +152,7 @@ async function handleBudgetChecks(
  * - W5 主判据：continuation 连发总次数封顶（默认 50，PI_GOAL_CONTINUATION_CAP）——
  *   封顶必停发 + notify 用户 + goal 保持 active（不擅自终态）。与「是否调工具」
  *   正交：计数只在 deliverContinuation 实发时 +1，绝不被工具调用清零
- *   （2026-09-08 事故：pending 守卫击穿后 64 分钟 ~320 turn 空转，无任何熔断）。
+ *   （2026-09-08 事故：pending 检查击穿后 64 分钟 ~320 turn 空转，无任何熔断）。
  * - W5 辅判据：连续 N 轮（默认 5）无工具调用且 tokenDelta 低于阈值 → continuation
  *   延迟 base×2^level 发出（间隔 ×2 递增）；真实进展清零退避计数（不动总次数）。
  * - W5 defer 通知去重：pending 集合不变的连续 defer 轮不重复 notify。
@@ -188,7 +188,7 @@ async function handleContinuation(
 		isProgressSignal(toolDelta, tokenDelta, cfg),
 	);
 
-	// pending 守卫：有活跃 background subagent/workflow 时不发 continuation。
+	// pending 检查：有活跃 background subagent/workflow 时不发 continuation。
 	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true}，缺省 deliverAs 即 steer) 自然唤醒主 agent；
 	// goal 抢先催会与异步任务完成通知叠加，形成“停不下来”的死循环——continuation 排入
 	// _followUpMessages 队列 → _handlePostAgentRun 的 hasQueuedMessages() 返回 true → agent.continue()
@@ -196,8 +196,8 @@ async function handleContinuation(
 	// 刻意不校验 expiresAt：长任务 subagent（>1h TTL）完成时仍 triggerTurn 唤醒主 agent，
 	// 按 TTL 判非活跃会让死循环在长任务场景复现。
 	// [W4 读侧过滤①消费口] 传当前 session 基准：fork 继承的父级注册残留不进差集
-	// （守卫不幻 defer）；设计 D4「读侧过滤一刀」在本消费口的落地（W6 探针实测
-	// registry-fork-filter.test.ts 证不传则虚增，A9② 验收口径）。
+	// （检查不幻 defer）；设计 D4「读侧过滤一刀」在本消费口的落地（W6 探针实测
+	// registry-fork-filter.test.ts 证不传则虚增，A9② 验收标准）。
 	const pendingOps = countActiveFromEntries(entries, {
 		currentSessionId: ctx.sessionManager.getSessionId(),
 	});
@@ -239,7 +239,7 @@ async function handleContinuation(
 		// 空 turn：已 persist，不发 continuation
 		return;
 	}
-	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited 终态。
+	// 终态检查：persistAndUpdate 可能把 goal 转为 budget_limited 终态。
 	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
 	if (isTerminalStatus(state.status)) return;
 
@@ -319,11 +319,11 @@ async function handleContinuation(
 }
 
 /**
- * 退避 timer 到期后的发射前守卫 + 实发（延迟期间状态可能已变）：
+ * 退避 timer 到期后的发射前检查 + 实发（延迟期间状态可能已变）：
  * - goal 未被覆盖/清除（goalId 比对）、仍 active
- * - MF-6① idle 守卫：ctx.signal 为实时求值（pi-agent-core agent.js get signal 返回
+ * - 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）——延迟窗内有活动
+ *   恒放行、不可作检查；改用 ctx.isIdle()（SDK types.d.ts L232）——延迟窗内有活动
  *   turn 时不发，该轮 agent_end 会按最新状态重新决策
  * - 未封顶、无活跃 pending（等待期新出现的后台任务由其完成通知唤醒，goal 不抢先催）
  */

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

@@ -8,7 +8,7 @@
  * 2. ADR-002：Context 使用率 > 85% → 保持 active + 注入 wrap-up 指令
  * 3. 正常：注入 contextInjectionPrompt
  *
- * 无 ESC 守卫（before_agent_start 是 agent 开始前的信号，此时无 aborted 可能）。
+ * 无 ESC 检查（before_agent_start 是 agent 开始前的信号，此时无 aborted 可能）。
  *
  * 全解耦：不再做 staleness 检测（原依赖 pi.__todoGetList，跨 ext 失效），
  * 不再探测 plan extension（原 typeof pi.__planStart，跨 ext 失效）。

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

@@ -1,7 +1,7 @@
 /**
- * 事件 3: message_end（FR-6.7 ESC 守卫 + token 累加）。
+ * 事件 3: message_end（FR-6.7 ESC 检查 + token 累加）。
  *
- * FR-6.7 ESC 守卫：ctx.signal.aborted 时跳过 token 累加。
+ * FR-6.7 ESC 检查：ctx.signal.aborted 时跳过 token 累加。
  * FR-8.6: token 累加算法（委托 service.applyEvent("message_end")）。
  *
  * role 过滤（D13①，rename-session 先例同形态）：仅 user/assistant 的 message_end
@@ -37,7 +37,7 @@ export async function handleMessageEnd(
 	event: MessageEndEvent,
 ): Promise<void> {
 	if (!session.state) return;
-	// FR-6.7 ESC 守卫
+	// FR-6.7 ESC 检查
 	if (ctx.signal?.aborted) return;
 
 	// D13① role 过滤：仅对话轴两形态（AgentMessage role 域为开放联合，宽比较）

package/src/adapters/event-handlers/session-shutdown.ts

@@ -1,5 +1,5 @@
 /**
- * 事件 7: session_shutdown（MF-R2-1 根修：invalidate 前取消旧退避 timer）。
+ * 事件 7: session_shutdown（MF-R2-1 从根源修复：invalidate 前取消旧退避 timer）。
  *
  * SDK 触发序（@earendil-works/pi-coding-agent 0.84.4 实装核对）——所有使旧
  * runner 失效的路径都先 emit session_shutdown 再 invalidate，此刻 pi/ctx 仍可用：

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

@@ -1,7 +1,7 @@
 /**
- * 事件 2: turn_end（FR-6.7 ESC 守卫 + 递增）。
+ * 事件 2: turn_end（FR-6.7 ESC 检查 + 递增）。
  *
- * FR-6.7 ESC 守卫：ctx.signal.aborted 时跳过递增（ESC 不算 goal turn）。
+ * FR-6.7 ESC 检查：ctx.signal.aborted 时跳过递增（ESC 不算 goal turn）。
  * 正常路径：currentTurnIndex++ + updateWidget。
  *
  * 委托 service.applyEvent("turn_end") 递增 currentTurnIndex（H3：applyEvent 改 void，
@@ -23,7 +23,7 @@ export async function handleTurnEnd(
 	ctx: ExtensionContext,
 ): Promise<void> {
 	if (!session.state) return;
-	// FR-6.7 ESC 守卫
+	// FR-6.7 ESC 检查
 	if (ctx.signal?.aborted) return;
 
 	const ports = buildPorts(pi, ctx);

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

@@ -4,9 +4,9 @@
  * #3：替代已删除的 goal_manager tool。
  *
  * 职责分层：
- * - execute 层（adapter 职责）：signal 守卫
+ * - execute 层（adapter 职责）：signal 检查
  * - handler 层（goal 业务，契约对齐 code-architecture §3 handleCreate/handleComplete/handleReportBlocked）：
- *   active 守卫 + evidence/reason 空串校验 + 状态转换
+ *   active 检查 + evidence/reason 空串校验 + 状态转换
  *
  * 全解耦：goal 不再读 todo/plan 状态。complete 不做 todo 完成前置硬检查——
  * todo 是否全完成由 AI 自行判断，goal 仅通过 prompt 软建议（见 prompts.ts）。
@@ -176,7 +176,7 @@ export function buildGoalControlSummary(
 
 /**
  * create 业务逻辑：objective + successCriteria 必填（schema 层已强制，此处仅校验空串）
- * + 非终态旧 goal 守卫 + service.createGoal。
+ * + 非终态旧 goal 检查 + service.createGoal。
  *
  * slug：AI 生成的短标识，仅 widget 标题 + history 用，不注入 prompt。真 optional。
  * objective：完整描述，注入每轮 context prompt（保证方向感）。
@@ -184,9 +184,9 @@ export function buildGoalControlSummary(
  * 全解耦：不读 todo/plan。toolcall 时 AI 已在 turn 中，**不**发消息注入
  * （AI 返回后自行续跑，对齐 Codex create_goal）。
  *
- * 守卫用 D25 严格语义：非终态 active/paused/blocked 全挡，提示用 /goal resume 或
+ * 检查用 D25 严格语义：非终态 active/paused/blocked 全挡，提示用 /goal resume 或
  * /goal clear——防 AI 静默覆盖含未完成工作的 goal。
- * 终态旧 goal 走 createGoal 快速路径覆盖（createGoal 内部 active 守卫，终态可覆盖）。
+ * 终态旧 goal 走 createGoal 快速路径覆盖（createGoal 内部 active 检查，终态可覆盖）。
  *
  * 参数校验拆分至 requireCreateObjective / requireCreateSuccessCriteria /
  * resolveCreateBudget（圈复杂度拆分），校验顺序与错误消息不变。
@@ -247,7 +247,7 @@ export function handleCreate(
 	const slugInput = params.slug?.trim();
 	const successCriteria = requireCreateSuccessCriteria(params);
 
-	// D25 严格守卫：非终态旧 goal（active/paused/blocked）→ 拒绝创建（防静默覆盖未完成工作）
+	// D25 严格检查：非终态旧 goal（active/paused/blocked）→ 拒绝创建（防静默覆盖未完成工作）
 	if (session.state && !isTerminalStatus(session.state.status)) {
 		throw new Error(
 			`Goal already active (status: ${session.state.status}). Use /goal resume to continue or /goal clear to reset before creating a new one.`,
@@ -260,7 +260,7 @@ export function handleCreate(
 	// FR-3.1: 唯一创建入口。终态旧 goal 走覆盖快速路径。
 	const created = createGoal(session, objective, budget, ports, slugInput, successCriteria);
 	if (!created) {
-		// createGoal 内部 active 守卫兜底（理论上上面守卫已挡；防御性）
+		// createGoal 内部 active 检查兜底（理论上上面检查已挡；防御性）
 		throw new Error("Goal already active. Cannot create a new one.");
 	}
 
@@ -278,7 +278,7 @@ export function handleCreate(
 }
 
 /**
- * complete 业务逻辑：active 守卫 + evidence 空串校验 + finalizeAndPersist。
+ * complete 业务逻辑：active 检查 + evidence 空串校验 + finalizeAndPersist。
  *
  * 全解耦后不再做 todo 完成前置检查——todo 是否全完成由 AI 自行判断（prompt 软建议）。
  */
@@ -313,7 +313,7 @@ export function handleComplete(
 }
 
 /**
- * report_blocked 业务逻辑：active 守卫 + reason 空串校验 + tickState + transitionStatus + persistState。
+ * report_blocked 业务逻辑：active 检查 + reason 空串校验 + tickState + transitionStatus + persistState。
  *
  * 必须在 transitionStatus **之前** tickState，使 tick 看到 active 状态并累加当前运行段；
  * 否则转 blocked 后 persistState 内部的 tick 因 status≠active 不累加，丢失最后一段运行时间。
@@ -352,7 +352,7 @@ export function handleReportBlocked(
 	return { action: "report_blocked", goalId: state.goalId, status: state.status };
 }
 
-/** renderResult 的 result 是否含 details 字段（类型守卫，替代全可选结构断言 as {details?}）。
+/** renderResult 的 result 是否含 details 字段（类型检查，替代全可选结构断言 as {details?}）。
  * 收紧：除检查 "details" in r 外，还验证其值为 object 或 undefined（防 details 是 string/number
  * 时下游读 d.status 得到 undefined 却被类型系统当作 GoalControlDetails）。 */
 function hasGoalDetails(r: unknown): r is { details?: GoalControlDetails } {
@@ -435,7 +435,7 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 
 		renderCall(args: Record<string, unknown>, theme: Theme): Text {
 			// TUI 渲染先于 schema 校验（args 是未经 schema 收窄的原始形态）：非对象整体
-			// 走安全占位（不抛错）；action/slug 逐个 typeof 守卫替代裸断言——非法 action
+			// 走安全占位（不抛错）；action/slug 逐个 typeof 检查替代裸断言——非法 action
 			// 落 report_blocked 回落分支（与原行为一致）
 			if (typeof args !== "object" || args === null) {
 				return new Text(

package/src/adapters/ports.ts

@@ -42,8 +42,8 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 	const uiPort: UiPort = {
 		setWidget(name, content): void {
 			// 双模 payload 委托 protocol setWidgetDual：推送/清屏 × GUI/TUI 的模式分派
-			// 由 helper 单点内化（守卫单点化说明见 extension-protocol helpers.ts），
-			// 本 adapter 不再自持 isGui 判定/守卫注释。
+			// 由 helper 单点内化（检查单点化说明见 extension-protocol helpers.ts），
+			// 本 adapter 不再自持 isGui 判定/检查注释。
 			//
 			// 断言根因：pi ExtensionUIContext.custom 是泛型方法（返回 Promise<T>），
 			// 与 GuiContext.ui.custom 的具体返回类型静态不兼容，但 mode/hasUI/ui 其余

package/src/constants.ts

@@ -38,7 +38,7 @@ export const MAX_HISTORY_ENTRIES = 20;			// goal-history entry GC 上限
 
 // ── 轮次活性熔断（chat-domain-v1x D4 / W5）─────────────
 //
-// 事故背景（2026-09-08，64 分钟 ~320 turn 空转烧 2.93M token）：pending 守卫被
+// 事故背景（2026-09-08，64 分钟 ~320 turn 空转烧 2.93M token）：pending 检查被
 // 「等待已注销的后台任务」击穿后，goal 每轮注入 continuation、主 agent 每轮回一句
 // 等待，无任何无进展熔断。双维度封顶：主判据总量上限（与是否调工具正交，不可被
 // 任何目标行为绕过）+ 辅判据无进展退避（间隔 ×2 递增）。全部可经 PI_GOAL_* env 覆盖。

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

@@ -125,7 +125,7 @@ describe("getBudgetSeverity", () => {
 		const [r1, r2] = a <= b ? [a, b] : [b, a];
 		return RANK[getBudgetSeverity(r1)] <= RANK[getBudgetSeverity(r2)];
 	});
-	// 三分区 property 钉死阈值边界（捕捉 0.9/0.7 被改）
+	// 三分区 property 固定阈值边界（捕捉 0.9/0.7 被改）
 	it.prop([f64(0.9, 1)])("r ≥ 0.9 → danger", (r) => getBudgetSeverity(r) === "danger");
 	it.prop([f64(0.7, 0.9).filter((r) => r < 0.9)])("0.7 ≤ r < 0.9 → warn", (r) => getBudgetSeverity(r) === "warn");
 	it.prop([f64(0, 0.7).filter((r) => r < 0.7)])("r < 0.7 → ok", (r) => getBudgetSeverity(r) === "ok");

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

@@ -1,8 +1,11 @@
 /**
  * engine/goal.ts 测试 — Goal 状态机 + createGoalState
  *
- * transitionStatus 完备性用 fast-check 覆盖 GoalStatus×GoalStatus 全 36 组合
- * （不 throw ⟺ to ∈ VALID_TRANSITIONS[from]），替代手写合法 9 + 非法 25 = 34 条枚举。
+ * transitionStatus 完备性两层：fast-check 抽样（不 throw ⟺ (from,to) ∈ 期望合法边表）
+ * + (from,target) 6×6 穷举基线（M3 迁移对账矩阵，36 组合全跑）。期望边表硬编码自
+ * 领域语义、独立于实现（不 import 实现侧转移表——M3 迁移前后同一期望表对账）。
+ * 机器表级另设 generateTableTests 穷举生成组（D5/D6 每步判据第二款）——直测
+ * GOAL_MACHINE 全状态×全事件，与包装层基线互为独立防线。
  */
 import { describe, expect } from "vitest";
 import { it, fc } from "@fast-check/vitest";
@@ -10,8 +13,8 @@ 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";
+import { generateTableTests } from "@zhushanwen/state-machine/testing";
+import { GOAL_MACHINE, createGoalState, isActiveStatus, isTerminalStatus, transitionStatus } from "../goal";
 import type { GoalStatus } from "../types";
 
 const STATUS_VALUES: GoalStatus[] = ["active", "paused", "blocked", "complete", "budget_limited", "cancelled"];
@@ -20,6 +23,21 @@ const statusArb = fc.constantFrom(...STATUS_VALUES);
 const TERMINAL: ReadonlySet<GoalStatus> = new Set(["complete", "budget_limited", "cancelled"]);
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+// 期望合法边表（M3 迁移基线 oracle）：9 条合法边硬编码自领域语义——
+// 用户 pause/resume/cancel、agent report_blocked/complete、token 预算耗尽。
+const EXPECTED_LEGAL_EDGES: ReadonlyArray<readonly [GoalStatus, GoalStatus]> = [
+	["active", "paused"],
+	["active", "blocked"],
+	["active", "complete"],
+	["active", "budget_limited"],
+	["active", "cancelled"],
+	["paused", "active"],
+	["paused", "cancelled"],
+	["blocked", "active"],
+	["blocked", "cancelled"],
+];
+const expectedLegalEdge = new Set(EXPECTED_LEGAL_EDGES.map(([from, to]) => `${from}→${to}`));
+
 describe("isTerminalStatus", () => {
 	it.prop([statusArb])("⟺ 在 {complete, budget_limited, cancelled} 内", (s) => isTerminalStatus(s) === TERMINAL.has(s));
 });
@@ -29,9 +47,9 @@ describe("isActiveStatus", () => {
 });
 
 describe("transitionStatus", () => {
-	// ⭐ 完备性：自动枚举全 36 组合，不 throw ⟺ to ∈ VALID_TRANSITIONS[from]
-	it.prop([statusArb, statusArb])("完备性：不 throw ⟺ to ∈ VALID_TRANSITIONS[from]", (from, to) => {
-		const inTable = VALID_TRANSITIONS[from].includes(to);
+	// ⭐ 完备性（抽样）：不 throw ⟺ (from, to) ∈ 期望合法边表（独立 oracle，非循环）
+	it.prop([statusArb, statusArb])("完备性：不 throw ⟺ (from,to) ∈ 期望合法边表", (from, to) => {
+		const inTable = expectedLegalEdge.has(`${from}→${to}`);
 		let threw = false;
 		try {
 			transitionStatus(from, to);
@@ -49,6 +67,42 @@ describe("transitionStatus", () => {
 	});
 });
 
+// ── M3 迁移基线（V7 对账矩阵）：(from,target) 6×6 穷举 ──────────────
+// 迁移前测存量邻接表实现（基线），迁移后测机器包装（to 等价 + throw 形态）；
+// 期望合法边表（expectedLegalEdge，文件顶部）迁移前后同一份。
+
+describe("transitionStatus (from,target) 6×6 穷举基线（V7 对账矩阵）", () => {
+	for (const from of STATUS_VALUES) {
+		for (const target of STATUS_VALUES) {
+			const legal = expectedLegalEdge.has(`${from}→${target}`);
+			it(`${from} → ${target}：${legal ? `合法，返回 ${target}` : "非法，throw"}`, () => {
+				if (legal) {
+					expect(transitionStatus(from, target)).toBe(target);
+				} else {
+					expect(() => transitionStatus(from, target)).toThrow();
+				}
+			});
+		}
+	}
+});
+
+// ── 机器级穷举生成组（D5/D6 每步判据第二款）：全状态 × 全事件 ──────────
+// generateTableTests(GOAL_MACHINE) 直测机器表（词表/表行误改、terminal
+// 拒绝语义），与上方包装层 6×6（transitionStatus 行为对账）互为独立防线。
+// 必须在收集阶段（模块顶层）调用——describe/it 不能在测试回调内注册。
+const generatedCases = generateTableTests(GOAL_MACHINE);
+
+describe("GOAL_MACHINE 穷举覆盖对账", () => {
+	it("全组合 36（6 态 × 6 事件）= 合法 9 + 表外 27 + 不变量破坏 0", () => {
+		// 合法 9 ⟺ 上方 EXPECTED_LEGAL_EDGES 的 9 条 (from,to) 边（本表
+		// from×event→to 单射，两维度同源对账）；覆盖数对账防生成器静默漏覆盖。
+		expect(generatedCases).toHaveLength(36);
+		expect(generatedCases.filter((c) => c.expectation === "transition")).toHaveLength(9);
+		expect(generatedCases.filter((c) => c.expectation === "rejected")).toHaveLength(27);
+		expect(generatedCases.filter((c) => c.expectation === "invariant-broken")).toHaveLength(0);
+	});
+});
+
 describe("createGoalState", () => {
 	it("默认值：status active + 计数器清零 + 预警 flag false", () => {
 		expect(createGoalState("my obj")).toMatchObject({
@@ -87,9 +141,9 @@ describe("createGoalState", () => {
 	});
 });
 
-// ── E1 守卫：状态变更唯一执行点（.status 裸赋值扫描）──
+// ── E1 检查：状态变更唯一执行点（.status 裸赋值扫描）──
 
-describe("E1 守卫：src 内禁止 .status 裸赋值（必须走 transitionStatus 查表）", () => {
+describe("E1 检查：src 内禁止 .status 裸赋值（必须走 transitionStatus 查表）", () => {
 	it("扫描 src/**/*.ts（排除 __tests__）：0 命中", () => {
 		// 正则逐字来自设计定稿，不得自行修改：
 		// (?![=>]) 排除 ==/===/=>（比较与箭头函数形态）；(?!\s*transitionStatus\b) 放行白名单查表赋值。
@@ -118,7 +172,7 @@ describe("E1 守卫：src 内禁止 .status 裸赋值（必须走 transitionStat
 		walk(srcDir);
 		expect(
 			offenders,
-			`检测到 ${offenders.length} 处 .status 裸赋值（状态变更必须走 transitionStatus 查表，见设计 §5.4 E1 / VALID_TRANSITIONS engine/types.ts）:\n`
+			`检测到 ${offenders.length} 处 .status 裸赋值（状态变更必须走 transitionStatus 查表，见设计 §5.4 E1 / goal 状态机声明 engine/goal.ts）:\n`
 				+ offenders.join("\n"),
 		).toEqual([]);
 	});

package/src/engine/goal.ts

@@ -4,8 +4,76 @@
  * 零 Pi 依赖。import from "./types"。
  */
 
+import { defineStateMachine } from "@zhushanwen/state-machine";
+
 import type { BudgetConfig, GoalRuntimeState, GoalStatus } from "./types";
-import { DEFAULT_BUDGET, TERMINAL_GOAL_STATUSES, VALID_TRANSITIONS } from "./types";
+import { DEFAULT_BUDGET, TERMINAL_GOAL_STATUSES } from "./types";
+
+// ── Goal 状态机声明（@zhushanwen/state-machine 行式表，M3 迁移）────────
+// 事件词表从 transitionStatus 调用点目标态语义派生（D6 M3）：
+// - pause / report_blocked / hit_budget_limit / complete / cancel = 用户或 agent
+//   的领域动作（/goal pause、goal_control report_blocked、token 预算耗尽、
+//   goal_control complete、/goal clear）；
+// - cancel 与 resume 各覆盖多源态（clear/resume 对 paused、blocked 对称）。
+// 终态标志与 TERMINAL_GOAL_STATUSES（types.ts，域查询用）是同一事实的两处
+// 声明。表行为由两层穷举锁定（__tests__/goal.test.ts）：机器级
+// generateTableTests 全状态×全事件生成组（D5/D6）+ 包装层 (from,target)
+// 6×6 基线（V7 对账矩阵）。新增状态或转移时必须同步更新此表与两层基线
+// （forcing function）。
+
+/** Goal 机器事件词表（类型层与下方 events 声明键集互为对账）。 */
+type GoalEvent =
+	| "pause"
+	| "report_blocked"
+	| "complete"
+	| "hit_budget_limit"
+	| "cancel"
+	| "resume";
+
+export const GOAL_MACHINE = defineStateMachine<GoalStatus, GoalEvent>({
+	name: "goal",
+	states: {
+		active: {},
+		paused: {},
+		blocked: {},
+		complete: { terminal: true },
+		budget_limited: { terminal: true },
+		cancelled: { terminal: true },
+	},
+	initial: "active",
+	events: {
+		pause: {},
+		report_blocked: {},
+		complete: {},
+		hit_budget_limit: {},
+		cancel: {},
+		resume: {},
+	},
+	transitions: [
+		{ from: "active", on: "pause", to: "paused" },
+		{ from: "active", on: "report_blocked", to: "blocked" },
+		{ from: "active", on: "complete", to: "complete" },
+		{ from: "active", on: "hit_budget_limit", to: "budget_limited" },
+		{ from: ["active", "paused", "blocked"], on: "cancel", to: "cancelled" },
+		{ from: ["paused", "blocked"], on: "resume", to: "active" },
+	],
+	errorPolicy: "throw",
+});
+
+/** (from, target) → 事件名索引：从机器行式表派生，transitionStatus 据此查边。 */
+const edgeEventIndex = new Map<GoalStatus, Map<GoalStatus, GoalEvent>>();
+for (const row of GOAL_MACHINE.definition.transitions) {
+	if (row.to === null) continue; // goal 域无实体消亡行（to: null）
+	const froms = Array.isArray(row.from) ? row.from : [row.from];
+	for (const from of froms) {
+		let byTarget = edgeEventIndex.get(from);
+		if (!byTarget) {
+			byTarget = new Map<GoalStatus, GoalEvent>();
+			edgeEventIndex.set(from, byTarget);
+		}
+		byTarget.set(row.to, row.on);
+	}
+}
 
 export function isTerminalStatus(status: GoalStatus): boolean {
 	return TERMINAL_GOAL_STATUSES.has(status);
@@ -16,18 +84,26 @@ export function isActiveStatus(status: GoalStatus): boolean {
 }
 
 /**
- * 安全的状态转换。查 VALID_TRANSITIONS 表，非法转换 throw。
+ * 安全的状态转换（M3 迁移后形态：机器保形包装）。
  *
+ * 签名与语义不变：查 (current, next) 边的事件名喂机器 transition 并断言
+ * to === next；表外 (current, next) throw（消息与迁移前一致）。
  * 调用方必须在终态转换前自行检查 isTerminalStatus（如 finalizeAndPersist），
  * 因为终态→终态不是合法转换（表为空）。对 active→终态、active→paused/blocked、
  * paused/blocked→active/cancelled 这些合法路径直接返回 next。
  */
 export function transitionStatus(current: GoalStatus, next: GoalStatus): GoalStatus {
-	const allowed = VALID_TRANSITIONS[current];
-	if (allowed && allowed.includes(next)) {
-		return next;
+	const event = edgeEventIndex.get(current)?.get(next);
+	if (event === undefined) {
+		throw new Error(`Invalid goal state transition: ${current} → ${next}`);
+	}
+	const result = GOAL_MACHINE.transition(current, event);
+	if (result.state !== next) {
+		throw new Error(
+			`Goal state machine invariant broken: transition(${current}, ${event}) returned ${String(result.state)}, expected ${next}.`,
+		);
 	}
-	throw new Error(`Invalid goal state transition: ${current} → ${next}`);
+	return next;
 }
 
 /**

package/src/engine/liveness.ts

@@ -78,14 +78,14 @@ const BACKOFF_MULTIPLIER = 2;
  * message.toolCalls 顶层字段从未存在）。这里只数块个数——调用方以「相邻两次
  * agent_end 的差分」判定本 turn 是否有真实工具活动，不需要 name/arguments。
  *
- * duck-typed 逐层守卫（对齐 pending-notifications state.ts 的 EntryLike 风格），
+ * duck-typed 逐层检查（对齐 pending-notifications state.ts 的 EntryLike 风格），
  * 不依赖 SDK 具体类型；畸形 entry 跳过不计。
  */
 export function countToolCallBlocks(entries: unknown[]): number {
 	let count = 0;
 	for (const raw of entries) {
 		if (!raw || typeof raw !== "object") continue;
-		// 断言目标带必填 unknown 字段（typeof object 已守卫），非全可选形状
+		// 断言目标带必填 unknown 字段（typeof object 已检查），非全可选形状
 		const entry = raw as { type: unknown; message: unknown };
 		if (entry.type !== "message") continue;
 		if (!entry.message || typeof entry.message !== "object") continue;

package/src/engine/types.ts

@@ -22,19 +22,6 @@ export const TERMINAL_GOAL_STATUSES: ReadonlySet<GoalStatus> = new Set([
 	"cancelled",
 ]);
 
-/**
- * 显式状态转换表（system-architecture §5）。终态映射空数组——不可逆。
- * transitionStatus 据此查表，非法转换 throw。新增状态时必须更新此表（forcing function）。
- */
-export const VALID_TRANSITIONS: Record<GoalStatus, GoalStatus[]> = {
-	active: ["paused", "blocked", "complete", "budget_limited", "cancelled"],
-	paused: ["active", "cancelled"],
-	blocked: ["active", "cancelled"],
-	complete: [],
-	budget_limited: [],
-	cancelled: [],
-};
-
 // ── 预算配置 ────────────────────────────────────────
 
 export interface BudgetConfig {

package/src/index.ts

@@ -14,7 +14,7 @@
  *
  * FR-4.2/D-16：ctx 必填，移除 lastCtx 模块级可变状态。
  * FR-6.4：移除 hasPendingInjection。
- * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 守卫，在各 event handler）。
+ * FR-6.7：移除 pendingPause（ESC 改用 ctx.signal.aborted 检查，在各 event handler）。
  */
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, MessageEndEvent } from "@earendil-works/pi-coding-agent";
@@ -104,7 +104,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 		updateWidget(session, ports.ui);
 	});
 
-	// MF-R2-1 根修：session_shutdown 在 runner invalidate 之前触发（此刻 pi/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, _ctx: ExtensionContext) => {
@@ -138,7 +138,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 	 * FR-4.2/D-16: ctx 必填（消除 lastCtx 模块级可变状态）。
 	 * ports 构造复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）。
 	 *
-	 * 通道形态（C-ext-06 globalThis slot 惯例）：裸函数直挂——plan 侧使用点以 typeof 守卫
+	 * 通道形态（C-ext-06 globalThis slot 惯例）：裸函数直挂——plan 侧使用点以 typeof 检查
 	 * 读取 `globalThis[Symbol.for("@zhushanwen/pi-goal.goalInit")]`（plan/src/compact.ts）。
 	 * 不挂 pi API 对象：pi 为每个扩展创建独立 ExtensionAPI（1.0.0 复核同构），挂 pi 对象的字段
 	 * 跨扩展不可见。

package/src/persistence.ts

@@ -31,7 +31,7 @@ export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
  * npm pi-goal 0.7.x（base 968b9d76）经 finalizeAndPersist 真实写入过 `time_limited`（时间预算
  * 维度，新状态机已删除该状态）。若不归一化，升级用户持有该状态的 goal 会功能死锁：
  * /goal clear 的 transitionStatus 查表 throw、goal_control create 误报 already active、
- * resume/update 被 isActiveStatus 守卫拒绝——唯一出口是手动删 session 文件。
+ * resume/update 被 isActiveStatus 检查拒绝——唯一出口是手动删 session 文件。
  * 归一化为语义最接近的 `budget_limited`（预算耗尽终态），clear 走 isTerminalStatus 快速路径。
  * 其余值原样透传（不做值域校验，保持现状）。
  */

package/src/ports.ts

@@ -53,8 +53,8 @@ export interface UiPort {
 	/**
 	 * 设置 widget（双模单调用）。content = { gui, text } 双模 payload / undefined 清除；
 	 * 模式分派（RPC→gui 经 marker 通道 / TUI→text 原生文本行）由 protocol setWidgetDual
-	 * 单点内化（守卫单点化说明见 extension-protocol core/helpers.ts，adapter 委托 helper）。
-	 * hasUI 守卫留在调用方（FR-6.6）。
+	 * 单点内化（检查单点化说明见 extension-protocol core/helpers.ts，adapter 委托 helper）。
+	 * hasUI 检查留在调用方（FR-6.6）。
 	 */
 	setWidget(name: string, content: DualWidgetContent | undefined): void;
 	/** 设置 status bar */

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

@@ -6,7 +6,7 @@
  * - renderStatusLine: slug 标题（fallback objective 截断）+ 状态后缀 + cancelled 短路 + token/耗时显示
  * - renderWidgetLines: cancelled 短路 + 标题行 + criteria 摘要单行 + 预算进度条（Objective 全文行已移除，GAP-8）
  * - renderTerminalStatusLine: 终态单行 + cancelled 短路
- * - updateWidget: FR-6.6 hasUI 守卫 + 终态折叠 + cancelled 清除
+ * - updateWidget: FR-6.6 hasUI 检查 + 终态折叠 + cancelled 清除
  *
  * 用 passthrough ThemeLike（fg/bold 返回原文），断言渲染逻辑而非颜色。
  */
@@ -197,7 +197,7 @@ describe("renderWidgetLines", () => {
 	});
 });
 
-// ── updateWidget（FR-6.6 hasUI 守卫 + dual payload）──
+// ── updateWidget（FR-6.6 hasUI 检查 + dual payload）──
 
 interface RecordedCall {
 	method: "setWidget" | "setStatus";
@@ -225,7 +225,7 @@ function makeUiPort(hasUI: boolean): { ui: UiPort; calls: RecordedCall[] } {
 }
 
 describe("updateWidget (FR-6.6 hasUI guard)", () => {
-	it("hasUI=false → 不调 setWidget/setStatus（headless 守卫）", () => {
+	it("hasUI=false → 不调 setWidget/setStatus（headless 检查）", () => {
 		const { ui, calls } = makeUiPort(false);
 		const session = createGoalSession();
 		session.state = makeState({ status: "active" });

package/src/projection/widget.ts

@@ -6,7 +6,7 @@
  * - 类型 import 自 engine/types.ts 与 ports.ts（ThemeLike 上移至接口层）
  * - 工具函数 import 自 engine/budget.ts
  * - 时间计算基于 state.timeUsedSeconds（不含 Date.now() 副作用段）
- * - updateWidget(session, uiPort) 含 FR-6.6 hasUI 守卫
+ * - updateWidget(session, uiPort) 含 FR-6.6 hasUI 检查
  * - 仅 token 维度预算（time budget 已移除）；耗时仅作记账显示
  *
  * slug 精简（widget 显示优化）：
@@ -184,7 +184,7 @@ export function renderWidgetLines(state: GoalRuntimeState, th: ThemeLike): strin
 	return lines;
 }
 
-// ── updateWidget（FR-6.6 hasUI 守卫）──
+// ── updateWidget（FR-6.6 hasUI 检查）──
 
 /**
  * 刷新 widget + status bar。

package/src/service.ts

@@ -154,14 +154,14 @@ export function createGoal(
 /**
  * 唯一终态序列入口（FR-3.3 / AC-3）。
  *
- * 收口所有 active→terminal 转换的完整副作用序列——service（budget 终态）与
+ * 收尾所有 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）
  * 2. finalizeGoal(state, terminalStatus, ports)
- *    — transitionStatus(终态守卫) + completedAtTurnIndex= + appendHistory（FR-8.7 矩阵）
+ *    — transitionStatus(终态检查) + completedAtTurnIndex= + appendHistory（FR-8.7 矩阵）
  * 3. ports.persistence.appendState(serializeState(state))（持久化终态 state）
  *
  * @param state runtime state（mutate）
@@ -255,10 +255,10 @@ export function applyEvent(
 
 	switch (eventType) {
 		case "message_end": {
-			// token 累加（FR-8.6 G-R2-001）—— 仅 active 时累加（回归修复：原缺 isActiveStatus 守卫，
+			// token 累加（FR-8.6 G-R2-001）—— 仅 active 时累加（回归修复：原缺 isActiveStatus 检查，
 			// blocked 等 non-active 状态会错误累加 token）。复用 engine 纯函数。
 			if (!isActiveStatus(session.state.status)) break;
-			// 运行时守卫解析事件数据（未知形状 → 可选字段），替代全可选结构断言
+			// 运行时检查解析事件数据（未知形状 → 可选字段），替代全可选结构断言
 			const data = toMessageEndData(eventData);
 			if (data?.message?.role !== "assistant") break;
 			const usage = data.message.usage;

package/src/session.ts

@@ -6,7 +6,7 @@
  * U6c：重建输入接活跃路径裁剪——被撤子树的 goal-state 不进重建态）。
  *
  * FR-6.4: 删除 hasPendingInjection（僵尸字段）
- * FR-6.7: 删除 pendingPause（ESC 改用 aborted 守卫）
+ * FR-6.7: 删除 pendingPause（ESC 改用 aborted 检查）
  * FR-8.1 G-006: session append-only——entry GC 不生效（生产），history 显示侧截断
  * FR-3: 崩溃后保持原状态（active 重启计时；paused/blocked 保持；终态保持）
  */
@@ -26,7 +26,7 @@ export interface GoalSession {
 	/**
 	 * W5 退避延迟发送的 continuation 定时器（无进展退避时 continuation 不立即发出，
 	 * 按间隔 ×2 递增延迟）。非 null 表示有一个待发的退避 continuation——调度前必须
-	 * 先清（防双发）。清理面（cancelContinuationTimer 统一入口）：clearGoalSession、
+	 * 先清（防双发）。清理侧（cancelContinuationTimer 统一入口）：clearGoalSession、
 	 * session_start（新 session 生命周期旧 timer 作废）、before_agent_start（新用户
 	 * 活动使旧退避作废）、下一轮 agent_end 调度前。
 	 */
@@ -71,7 +71,7 @@ export interface ActivePathSessionView {
 // ── reconstructGoalState（session_start / session_tree 时调）──────────
 
 /**
- * 从 session entries 恢复 goal state（U6c：重建输入 = 活跃路径投影，非全文件）。
+ * 从 session entries 恢复 goal state（U6c：重建输入 = 活跃路径派生视图，非全文件）。
  *
  * Pi SDK 的 session 是 append-only，getEntries() 返回 filter-copy——splice
  * 无法修改真实 entries。Entry GC（goal-state 留 1、goal-history 留 20）在生产
@@ -127,7 +127,7 @@ function isGoalStateEntry(entry: SessionEntryLike): boolean {
 // ── clearGoalSession ──────────────────────────────────
 
 /**
- * 取消待发的退避 continuation timer（全部清理点走本函数，防止清理面遗漏）：
+ * 取消待发的退避 continuation timer（全部清理点走本函数，防止清理侧遗漏）：
  * - clearGoalSession：goal 已终态/清除，发出即僵尸 turn
  * - session_start：session 句柄跨 session 复用，新 session 生命周期旧 timer 作废
  * - before_agent_start：新用户活动使旧退避作废，该轮 agent_end 按最新状态重新决策
@@ -145,7 +145,7 @@ export function clearGoalSession(session: GoalSession, uiPort: UiPort): void {
 	cancelContinuationTimer(session);
 	session.state = null;
 	session.isProcessing = false;
-	// FR-6.6: hasUI 守卫
+	// FR-6.6: hasUI 检查
 	if (uiPort.hasUI) {
 		uiPort.setWidget("goal", undefined);
 		uiPort.setStatus("goal", undefined);