@zhushanwen/pi-goal 0.15.0 → 0.16.1

package/README.md

@@ -26,15 +26,9 @@ ln -s /path/to/taiji/extensions/universal/goal \
 pi install npm:@zhushanwen/pi-goal
 ```
 
-## 工具激活（deferred）
+## 工具激活
 
-`goal_control` 工具为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）开启：
-
-```json
-{ "defaultTools": ["+tool_search"] }
-```
-
-`+` 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 `tool_search` 时该工具对模型不可见。
+`goal_control` 工具为 direct 常驻——注册不声明 `exposure` 字段（pi SDK 缺省 `direct`），工具声明随会话常驻、对模型默认可见，无需经 `tool_search` 检索激活，独立 pi 开箱即用。
 
 ## 使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.15.0",
+  "version": "0.16.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,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", () => ({
@@ -36,6 +36,8 @@ type ExecuteResult = {
 
 interface CapturedTool {
 	name: string;
+	/** pi SDK 的 exposure 缺省值 "direct"（常驻）——不写字段时 SDK 侧默认（pi-semantics PS-91），本视图可缺省。 */
+	exposure?: string;
 	execute: (
 		toolCallId: string,
 		params: Record<string, unknown>,
@@ -123,6 +125,18 @@ function createViaHandler(
 
 // ── 测试场景 ─────────────────────────────────────────
 
+// exposure 重划终态锚（C-ext-05，2026-10-23 ADR-0136）：goal_control 保持 direct 常驻 =
+// 注册时不写 exposure 字段（SDK 缺省 direct，pi-semantics PS-91）——误写 "deferred" 会把
+// 目标管理入口从模型默认可见集收走（tool_search 才可激活），此处红。
+describe("goal_control SDK 契约 — exposure 注册终态（C-ext-05）", () => {
+	it("direct 常驻：不写 exposure 字段（SDK 缺省 direct）", () => {
+		const { pi } = makeFixture("rpc");
+		const tool = captureTool(pi);
+		expect(tool.name).toBe("goal_control");
+		expect(tool.exposure).toBeUndefined();
+	});
+});
+
 describe("goal_control execute — RPC 模式 tool result 无 __gui__", () => {
 	it("RPC + 有 budget 的 create → details 无 __gui__ 字段（content 仍正常）", async () => {
 		const { pi, ctx } = makeFixture("rpc");
@@ -150,9 +164,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 +177,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__/goal-control-summary.test.ts

@@ -53,6 +53,32 @@ describe("buildGoalControlSummary", () => {
 		);
 	});
 
+	it("report_blocked reason 含换行 → summary 归一单行（S-1）", () => {
+		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
+		const summary = buildGoalControlSummary(
+			{ action: "report_blocked", reason: "第一行\n第二段\n\n尾行" } as never,
+			details,
+		);
+		expect(summary).toBe("Blocked: 第一行 第二段 尾行");
+	});
+
+	it("report_blocked reason 含 emoji 超长 → 截断不劈代理对（S-3）", () => {
+		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
+		// "x🎉" = 3 个 UTF-16 码元；UTF-16 slice(0,40) 会在第 40 码元处劈开 🎉 的代理对。
+		// 码点口径：50 码点 > 40 → 保留前 40 码点 = 20 组完整 "x🎉"
+		const summary = buildGoalControlSummary(
+			{ action: "report_blocked", reason: "x🎉".repeat(25) } as never,
+			details,
+		);
+		expect(summary).not.toContain("\n");
+		// Array.from 按码点切分后，孤立代理项表现为单码元的代理字符
+		const loneSurrogates = Array.from(summary).filter(
+			(ch) => ch.length === 1 && /[\uD800-\uDFFF]/.test(ch),
+		);
+		expect(loneSurrogates).toHaveLength(0);
+		expect(summary).toBe(`Blocked: ${"x🎉".repeat(20)}…`);
+	});
+
 	it("report_blocked 无 reason → 省略后缀", () => {
 		const details = { action: "report_blocked", goalId: "g1", status: "blocked" } as GoalControlDetails;
 		expect(buildGoalControlSummary({ action: "report_blocked" } as never, details)).toBe("Blocked");

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);