@zhushanwen/pi-goal 0.14.4 → 0.14.6

package/README.md

@@ -46,7 +46,7 @@ goal/
 ├── index.ts            # 入口 — re-export src/index.ts
 └── src/
     ├── index.ts        # 工厂入口（注册 command/tool/events + goalInit slot，全部委托 adapters）
-    ├── commands.ts     # /goal 命令参数解析（仅识别 --tokens flag）
+    ├── commands.ts     # /goal 命令参数解析（识别 --tokens / --criteria flag）
     ├── constants.ts    # 语义常量
     ├── ports.ts        # Pi 能力抽象（Persistence/Ui/Messaging/Session）
     ├── service.ts      # 协调层 — createGoal / finalizeAndPersist / applyEvent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "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,11 @@
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.4"
+    "@zhushanwen/pi-pending-notifications": "0.7.6"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.11.0"
+    "@zhushanwen/extension-protocol": "0.13.0",
+    "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

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

@@ -28,11 +28,13 @@ import { createGoalSession, type GoalSession } from "../session";
 // ── Fake pi / ctx（entries 数组可变，模拟 append-only 会话流）──
 
 interface RecordedCall {
-	kind: "appendState" | "appendHistory" | "notify" | "sendContext" | "sendUser";
+	kind: "appendState" | "appendHistory" | "notify" | "sendContext";
 	payload?: unknown;
 	text?: string;
 	level?: string;
 	content?: unknown;
+	customType?: unknown;
+	display?: unknown;
 }
 
 interface FakeHarness {
@@ -69,11 +71,8 @@ function makeHarness(): FakeHarness {
 			piCalls.push({ kind: customType === "goal-history" ? "appendHistory" : "appendState", payload: data });
 		},
 		sendMessage(message: unknown, options?: unknown): void {
-			const msg = message as { content?: unknown };
-			piCalls.push({ kind: "sendContext", content: msg.content, payload: options });
-		},
-		sendUserMessage(content: string | unknown[], _options?: unknown): void {
-			piCalls.push({ kind: "sendUser", content });
+			const msg = message as { content?: unknown; customType?: unknown; display?: unknown };
+			piCalls.push({ kind: "sendContext", content: msg.content, customType: msg.customType, display: msg.display, payload: options });
 		},
 	} as unknown as ExtensionAPI;
 
@@ -299,12 +298,17 @@ describe("/goal resume 恢复通道", () => {
 		expect(session.state!.continuationsSent).toBe(0); // 新激活周期
 		expect(session.state!.continuationCapNotified).toBe(false);
 		expect(session.state!.status).toBe("active");
-		const userSends = h.piCalls.filter((c) => c.kind === "sendUser");
-		expect(userSends).toHaveLength(1); // FR-8.12 触发 AI
-
-		// 恢复后：下一次 agent_end 正常发 continuation（新周期额度）
+		// FR-8.12 触发 AI（custom message，非 user message）
+		const resumeSends = h.piCalls.filter((c) => c.kind === "sendContext");
+		expect(resumeSends).toHaveLength(1);
+		expect(resumeSends[0]?.customType).toBe("goal-context");
+
+		// 恢复后：下一次 agent_end 正常发 continuation（新周期额度）。
+		// resume 触发消息同为 followUp custom message（改造后形态），按 [GOAL] 前缀
+		// 区分 continuation 本体（continuationPrompt 专属前缀）
 		await runTurn(h, session, { tokenDelta: 200 });
-		expect(followUpSends(h)).toHaveLength(1);
+		const continuations = followUpSends(h).filter((c) => String(c.content).includes("[GOAL]"));
+		expect(continuations).toHaveLength(1);
 	});
 
 	it("未封顶的普通 active goal → resume 提示无需恢复（原语义不变）", async () => {
@@ -315,7 +319,7 @@ describe("/goal resume 恢复通道", () => {
 		await handleGoalCommand(h.pi, session, "resume", h.ctx);
 
 		expect(notifyTexts(h).some((t) => t.includes("no need to resume"))).toBe(true);
-		expect(h.piCalls.filter((c) => c.kind === "sendUser")).toHaveLength(0);
+		expect(h.piCalls.filter((c) => c.kind === "sendContext")).toHaveLength(0);
 	});
 });
 
@@ -447,3 +451,34 @@ describe("MF-6③ timer 清理面：session_start / before_agent_start 取消旧
 		expect(followUpSends(h)).toHaveLength(4);
 	});
 });
+
+// ── A8：退避通道激活（sendContextMessage 端口 triggerTurn 改造）──
+//
+// 设计 docs/design/send-user-message-to-custom-message.md（已删除，git 可追溯；决策见 ADR-0068）
+// §2.2 端口改造 + §3.1 A8：
+// 端口改造前 backoff timer 到期伪装用户消息投递；改造后
+// deliverContinuation 经端口发 custom message 且 options 含 triggerTurn: true——
+// 非 streaming idle 场景真实开轮（改造前 append 不开轮 = 死消息）。
+// isIdle=false 拦截见 MF-6①；封顶记账守卫见「主判据」describe；此处锁定到期
+// 发出路径的 options 契约与记账恰好 +1。
+describe("A8：退避 timer 到期 → triggerTurn: true 开轮发出", () => {
+	it("isIdle 守卫通过后发出：custom message 四要素齐备，记账恰好 +1", async () => {
+		const { h, session } = await enterBackoff();
+
+		vi.advanceTimersByTime(20_000); // 2×base 到期，isIdle 默认 true → 守卫放行
+
+		const sends = followUpSends(h);
+		expect(sends).toHaveLength(5); // 4 立即 + 1 到期发出
+		const fired = sends[4]!;
+		// message 形态：customType + display:false（custom message，非用户气泡）
+		expect(fired.customType).toBe("goal-context");
+		expect(fired.display).toBe(false);
+		// options：deliverAs + triggerTurn（A8 核心断言——退避通道真实开轮）
+		const opts = fired.payload as { deliverAs?: string; triggerTurn?: boolean };
+		expect(opts.deliverAs).toBe("followUp");
+		expect(opts.triggerTurn).toBe(true);
+		// budget 记账不重复触发：主判据只在实发时 +1，本次到期恰好一次
+		expect(session.state!.continuationsSent).toBe(5);
+		expect(session.continuationTimer).toBeNull(); // 无残留待发 timer
+	});
+});

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

@@ -27,12 +27,14 @@ import { createGoalSession } from "../session";
 // ── Fake pi / ctx ────────────────────────────────────
 
 interface RecordedCall {
-	kind: "appendState" | "appendHistory" | "notify" | "sendContext" | "sendUser";
+	kind: "appendState" | "appendHistory" | "notify" | "sendContext";
 	text?: string;
 	level?: string;
 	content?: string;
-	deliverAs?: string;
 	customType?: string;
+	display?: boolean;
+	deliverAs?: string;
+	triggerTurn?: boolean;
 	payload?: unknown;
 }
 
@@ -60,12 +62,17 @@ function makeHarness(entries: SessionEntryLike[] = []): FakeHarness {
 				payload: data,
 			});
 		},
-		sendMessage(message: unknown, _options?: unknown): void {
-			const msg = message as { customType?: string; content?: string };
-			piCalls.push({ kind: "sendContext", content: msg.content, customType: msg.customType });
-		},
-		sendUserMessage(content: string | unknown[], _options?: unknown): void {
-			piCalls.push({ kind: "sendUser", content: typeof content === "string" ? content : undefined });
+		sendMessage(message: unknown, options?: unknown): void {
+			const msg = message as { customType?: string; content?: string; display?: boolean };
+			const opts = (options ?? {}) as { deliverAs?: string; triggerTurn?: boolean };
+			piCalls.push({
+				kind: "sendContext",
+				content: msg.content,
+				customType: msg.customType,
+				display: msg.display,
+				deliverAs: opts.deliverAs,
+				triggerTurn: opts.triggerTurn,
+			});
 		},
 	} as unknown as ExtensionAPI;
 
@@ -121,6 +128,11 @@ function notifyText(h: FakeHarness): string[] {
 		.map((c) => c.text ?? "");
 }
 
+/** 发出的 custom message 调用（经 ports.messaging.sendContextMessage → pi.sendMessage） */
+function sendContextCalls(h: FakeHarness): RecordedCall[] {
+	return h.piCalls.filter((c) => c.kind === "sendContext");
+}
+
 // ── /goal status ─────────────────────────────────────
 
 describe("handleGoalCommand — status", () => {
@@ -200,8 +212,14 @@ describe("handleGoalCommand — resume (FR-3 paused/blocked→active + G-014)",
 		await handleGoalCommand(h.pi, session, "resume", h.ctx);
 		expect(session.state!.status).toBe("active");
 		expect(h.states).toHaveLength(1); // persist 恰好 1 次
-		// FR-8.12: resume 后触发 AI
-		expect(h.piCalls.filter((c) => c.kind === "sendUser")).toHaveLength(1);
+		// FR-8.12: resume 后触发 AI（custom message 四要素：customType/display/deliverAs/triggerTurn）
+		const sends = sendContextCalls(h);
+		expect(sends).toHaveLength(1);
+		expect(sends[0]?.customType).toBe("goal-context");
+		expect(sends[0]?.display).toBe(false);
+		expect(sends[0]?.deliverAs).toBe("followUp");
+		expect(sends[0]?.triggerTurn).toBe(true);
+		expect(sends[0]?.content).toContain("Goal resumed");
 	});
 
 	it("resume 重置 timeStartedAt=now（FR-3.2 重启计时器）", async () => {
@@ -482,7 +500,7 @@ describe("parseGoalArgs — 子命令路由", () => {
 	});
 });
 
-// ── /goal set（提示词触发器：sendUserMessage 让 AI 调 goal_control create）──
+// ── /goal set（提示词触发器：custom message 让 AI 调 goal_control create）──
 
 describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终态)", () => {
 	it("无旧 goal → 发触发消息（不直接创建 state）", async () => {
@@ -492,11 +510,15 @@ describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终
 		// 提示词触发器：不直接 createGoal，state 仍为 null（由 AI 后续 toolcall 创建）
 		expect(session.state).toBeNull();
 		expect(h.states).toHaveLength(0); // 不写 state
-		// 发送 sendUserMessage 引导 AI 调 create
-		const sendUserCalls = h.piCalls.filter((c) => c.kind === "sendUser");
-		expect(sendUserCalls).toHaveLength(1);
-		expect(sendUserCalls[0]?.content).toContain("my objective");
-		expect(sendUserCalls[0]?.content).toContain("goal_control");
+		// 发 custom message 引导 AI 调 create（四要素 + content 含 objective 与工具名）
+		const sends = sendContextCalls(h);
+		expect(sends).toHaveLength(1);
+		expect(sends[0]?.customType).toBe("goal-context");
+		expect(sends[0]?.display).toBe(false);
+		expect(sends[0]?.deliverAs).toBe("followUp");
+		expect(sends[0]?.triggerTurn).toBe(true);
+		expect(sends[0]?.content).toContain("my objective");
+		expect(sends[0]?.content).toContain("goal_control");
 	});
 
 	const SET_REJECT_STATUSES: GoalRuntimeState["status"][] = ["active", "paused"];
@@ -515,7 +537,7 @@ describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终
 			expect(notifyText(h).join("\n")).toContain("clear");
 			expect(session.state!.status).toBe(status); // 状态不变
 			expect(session.state!.objective).toBe(`old ${status} goal`); // 旧 goal 保留
-			expect(h.piCalls.filter((c) => c.kind === "sendUser")).toHaveLength(0); // 不触发 AI
+			expect(sendContextCalls(h)).toHaveLength(0); // 不触发 AI
 		},
 	);
 
@@ -527,7 +549,7 @@ describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终
 		await handleGoalCommand(h.pi, session, "new objective", h.ctx);
 		expect(h.history.length).toBe(historyBefore); // 不写 history（触发器不直接创建）
 		// 终态旧 goal 不挡触发器，发消息让 AI 创建
-		expect(h.piCalls.filter((c) => c.kind === "sendUser")).toHaveLength(1);
+		expect(sendContextCalls(h)).toHaveLength(1);
 	});
 
 	it("空 objective → usage 提示", async () => {
@@ -547,18 +569,18 @@ describe("handleGoalCommand — set (提示词触发器 + #11/D25 拒绝非终
 		await handleGoalCommand(h.pi, session, "obj --tokens 0", h.ctx);
 		// 提示词触发器不直接创建 state
 		expect(session.state).toBeNull();
-		const sendUserCalls = h.piCalls.filter((c) => c.kind === "sendUser");
-		expect(sendUserCalls).toHaveLength(1);
-		expect(sendUserCalls[0]?.content).toContain("obj");
+		const sends = sendContextCalls(h);
+		expect(sends).toHaveLength(1);
+		expect(sends[0]?.content).toContain("obj");
 	});
 
 	it("--tokens N → 触发消息含 budget 值", async () => {
 		const h = makeHarness();
 		const session = createGoalSession();
 		await handleGoalCommand(h.pi, session, "obj --tokens 5000", h.ctx);
-		const sendUserCalls = h.piCalls.filter((c) => c.kind === "sendUser");
-		expect(sendUserCalls).toHaveLength(1);
-		expect(sendUserCalls[0]?.content).toContain("5000");
+		const sends = sendContextCalls(h);
+		expect(sends).toHaveLength(1);
+		expect(sends[0]?.content).toContain("5000");
 	});
 });
 

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

@@ -43,7 +43,6 @@ function makeFakePorts(): ServicePorts & {
 		} as UiPort,
 		messaging: {
 			sendContextMessage: () => {},
-			sendUserMessage: () => {},
 		},
 		session: {
 			getEntries: () => [],

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

@@ -21,7 +21,7 @@ import { createGoalSession } from "../session";
 // ── Fake pi / ctx ────────────────────────────────────
 
 interface RecordedCall {
-	kind: "appendState" | "appendHistory" | "notify" | "sendContext" | "sendUser" | "setStatus" | "setWidget";
+	kind: "appendState" | "appendHistory" | "notify" | "sendContext" | "setStatus" | "setWidget";
 	payload?: unknown;
 	text?: string;
 	level?: string;
@@ -50,13 +50,6 @@ function makeFakePi(): { pi: ExtensionAPI; calls: RecordedCall[]; states: unknow
 				payload: _options,
 			});
 		},
-		sendUserMessage(content: string | unknown[], options?: unknown): void {
-			calls.push({
-				kind: "sendUser",
-				content: typeof content === "string" ? content : undefined,
-				payload: options,
-			});
-		},
 	} as unknown as ExtensionAPI;
 	return { pi, calls, states, history };
 }
@@ -119,8 +112,8 @@ describe("handleAgentEnd — FR-6.7 ESC 守卫", () => {
 		await handleAgentEnd(pi, session, ctx);
 		const all = allCalls(piCalls, ctxCalls);
 
-		// 不发 continuation（无 sendContext/sendUser）
-		expect(all.filter((c) => c.kind === "sendContext" || c.kind === "sendUser")).toHaveLength(0);
+		// 不发 continuation（无 sendContext custom message）
+		expect(all.filter((c) => c.kind === "sendContext")).toHaveLength(0);
 		// 不做 budget 检查（无 notify 关于 budget）
 		expect(all.filter((c) => c.kind === "notify")).toHaveLength(0);
 		// goal 保持 active（status 不变）

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

@@ -60,7 +60,6 @@ function makeFakePorts(): ServicePorts & {
 		} as UiPort,
 		messaging: {
 			sendContextMessage: () => {},
-			sendUserMessage: () => {},
 		},
 		session: {
 			getEntries: () => [],

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

@@ -3,7 +3,7 @@
  *
  * 覆盖场景：
  * - RPC 模式 create/complete/report_blocked → details 无 __gui__ 字段（状态展示改由
- *   handle* 内 updateWidget 经 guiSetWidget 推送 M17 对话流 widget 面板）
+ *   handle* 内 updateWidget 经 guiSetWidget 推送 composer 任务托盘的协议 widget 区）
  * - RPC 模式 + session.state = null → 前置 handler throw（分支不可达）
  * - 非 RPC 模式（tui/json/print）→ details 同样无 __gui__，content 文本正常
  *
@@ -11,12 +11,22 @@
  * 不 mock handleCreate：走真实 createGoal 让 session.state 含完整字段（slug/objective/budget），
  * 避免 hand-rolled state 与生产路径不一致。pi/ctx 用最小 fake（对齐 index.test.ts makeFactoryFixture）。
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+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，
+//    与真实路径行为等价——fixture 的 setWidget/notify 本就是 no-op）──
+const loggerWarnSpy = vi.hoisted(() => vi.fn());
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => ({ warn: loggerWarnSpy, debug: vi.fn(), error: vi.fn() }),
+}));
+vi.mock("../projection/widget", () => ({ updateWidget: vi.fn() }));
+
+import { updateWidget } from "../projection/widget";
+
 // ── Types ─────────────────────────────────────────────
 
 type ExecuteResult = {
@@ -33,6 +43,7 @@ interface CapturedTool {
 		onUpdate: unknown,
 		ctx: ExtensionContext,
 	) => Promise<ExecuteResult>;
+	renderCall: (args: Record<string, unknown>, theme: Theme) => unknown;
 }
 
 // ── Fake pi + ctx（最小化，对齐 index.test.ts 的 makeFactoryFixture）──
@@ -58,7 +69,6 @@ function makeFixture(mode: "rpc" | "tui" | "json" | "print" = "rpc"): FakeFixtur
 		registerMessageRenderer: () => {},
 		appendEntry: () => {},
 		sendMessage: () => {},
-		sendUserMessage: () => {},
 	} as unknown as ExtensionAPI;
 
 	const ctx = {
@@ -215,3 +225,105 @@ describe("goal_control execute — 非 RPC 模式无 __gui__", () => {
 		expect(result.content[0].text).toContain("Goal created");
 	});
 });
+
+// ── 辅助 UI 通道降级（create/complete/blocked 的 updateWidget/notify 在核心副作用
+//    之后调用，UI 故障不得翻转工具结果）──────────────────
+
+describe("goal_control execute — 辅助 UI 通道失败降级", () => {
+	beforeEach(() => {
+		vi.mocked(updateWidget).mockReset();
+		loggerWarnSpy.mockClear();
+	});
+
+	/** 注册 tool 并同时持有 session 引用（断言持久化后的内存 state）。 */
+	function captureToolWithSession(pi: ExtensionAPI): { tool: CapturedTool; session: ReturnType<typeof createGoalSession> } {
+		let captured: CapturedTool | undefined;
+		const capturePi = {
+			...pi,
+			registerTool(tool: CapturedTool): void {
+				captured = tool;
+			},
+		} as unknown as ExtensionAPI;
+		const session = createGoalSession();
+		registerGoalControlTool(capturePi, session);
+		if (!captured) throw new Error("registerGoalControlTool did not register a tool");
+		return { tool: captured, session };
+	}
+
+	it("create + updateWidget 抛错 → 工具调用仍成功返回、状态已创建（warn 留痕非静默）", async () => {
+		vi.mocked(updateWidget).mockImplementation(() => {
+			throw new Error("widget channel broken");
+		});
+		const { pi, ctx } = makeFixture("rpc");
+		const { tool, session } = captureToolWithSession(pi);
+		const result = await tool.execute(
+			"call-ui-fail",
+			{ action: "create", slug: "ui-fail", objective: "survive ui failure", successCriteria: ["tests pass"] },
+			undefined,
+			undefined,
+			ctx,
+		);
+		// 工具成功返回（UI 异常未上抛翻转结果）
+		expect(result.details.action).toBe("create");
+		expect(result.details.status).toBe("active");
+		expect(result.content[0].text).toContain("Goal created");
+		// 核心副作用不受影响：state 已落盘到 session（内存态可见，persist 已在 createGoal 内完成）
+		expect(session.state?.status).toBe("active");
+		expect(session.state?.objective).toBe("survive ui failure");
+		// 降级留痕：warn 而非静默
+		expect(loggerWarnSpy).toHaveBeenCalledTimes(1);
+		expect(loggerWarnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("goal_control create"),
+			expect.objectContaining({ detail: expect.objectContaining({ err: "widget channel broken" }) }),
+		);
+	});
+
+	it("complete + updateWidget 抛错 → 工具调用仍成功返回（终态已持久化）", async () => {
+		const { pi, ctx } = makeFixture("rpc");
+		const { tool, session } = captureToolWithSession(pi);
+		await createViaHandler(tool, pi, ctx, { slug: "ui-comp", objective: "to complete" });
+		vi.mocked(updateWidget).mockImplementation(() => {
+			throw new Error("widget channel broken");
+		});
+		const result = await tool.execute(
+			"call-ui-comp",
+			{ action: "complete", evidence: "tests green" },
+			undefined,
+			undefined,
+			ctx,
+		);
+		expect(result.details.status).toBe("complete");
+		expect(session.state?.status).toBe("complete");
+		expect(loggerWarnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("goal_control complete"),
+			expect.objectContaining({ detail: expect.objectContaining({ err: "widget channel broken" }) }),
+		);
+	});
+});
+
+// ── renderCall 非法 args 安全渲染（TUI 渲染先于 schema 校验）──
+
+const stubTheme = {
+	fg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+} as unknown as Theme;
+
+/** 注册 → 捕获 tool → 以给定 args 调 renderCall，返回渲染文本（width 足够宽避免 wrap）。 */
+function renderedCallText(args: unknown): string {
+	const { pi } = makeFixture("rpc");
+	const tool = captureTool(pi);
+	const node = tool.renderCall(args as Record<string, unknown>, stubTheme) as {
+		render: (width: number) => string[];
+	};
+	return node.render(400).join("\n");
+}
+
+describe("renderCall — 非法 args 安全渲染", () => {
+	it("args 为 null → 占位文本，不抛错", () => {
+		expect(renderedCallText(null)).toContain("(invalid args)");
+	});
+
+	it("action 非字符串 → 不抛错，落 report_blocked 回落分支（与原行为一致）", () => {
+		expect(renderedCallText({ action: 42 })).toContain("report_blocked");
+	});
+});

package/src/__tests__/gui.test.ts

@@ -3,7 +3,8 @@
  *
  * 覆盖：
  * - 内容根 = group（透明组合容器）：stats-line（status/turn[+tokens]）+ list-tree（criteria）
- * - meta：title=slug、状态点语义（done/failed/idle/running）、token 进度（取整 + 百分比 + 阈值 severity）
+ * - meta：title=slug、状态点语义（done/failed/idle/running）、token 进度（取整 + 百分比 + 阈值 severity）、
+ *   托盘 icon（显式 'target' key）
  * - successCriteria 逐行 list-tree（不压扁/不截断/无 icon/不编号）
  * - token 展示走 formatTokens（无 budget 分支）
  */
@@ -60,12 +61,23 @@ describe("buildGoalGui（v1.1 meta head 架构）", () => {
 			}),
 		);
 		expect(gui.meta).toEqual({
+			icon: "target",
 			title: "fix-auth",
 			status: "running",
 			progress: { current: 4200, total: 10000, label: "42%", severity: "ok" },
 		});
 	});
 
+	it("meta.icon 推显式 'target' key（协议形状 string；badge 不推，宿主从 progress.label 派生）", () => {
+		const gui = buildGoalGui(makeState({ slug: "fix-auth", budget: { tokenBudget: 10000 } }));
+		// 协议形状：string（宿主按 lucide 名解析）或 { paths }（自定义形状）。
+		// goal 只用 key 形态——与宿主内置 widgetKey 映射（'goal'→Target）同款，
+		// 宿主改映射表也不会换掉 goal 图标。
+		expect(gui.meta!.icon).toBe("target");
+		// badge 留空：托盘缺省从 progress.label 派生同值百分比，推一份会变成双真相源
+		expect(gui.meta!.badge).toBeUndefined();
+	});
+
 	it("tokensUsed 浮点 → meta.progress.current 取整（1454.84…1 不进 UI）", () => {
 		const gui = buildGoalGui(
 			makeState({ tokensUsed: 1454.8400000000001, budget: { tokenBudget: 5000 } }),
@@ -104,7 +116,7 @@ describe("buildGoalGui（v1.1 meta head 架构）", () => {
 				tokensUsed: 3000,
 			}),
 		);
-		expect(gui.meta).toEqual({ title: expect.any(String), status: "running" });
+		expect(gui.meta).toEqual({ icon: "target", title: expect.any(String), status: "running" });
 		const stats = findChildComp(gui, "stats-line");
 		const items = stats.props.items as { label?: string; value?: string }[];
 		expect(items.find((i) => i.label === "tokens")).toMatchObject({ value: "3k" });

package/src/__tests__/index.test.ts

@@ -38,15 +38,13 @@ interface FactoryFixture {
 	ctx: ExtensionContext;
 	states: unknown[];
 	history: unknown[];
-	sendUser: unknown[];
 	commands: Record<string, { description?: string }>;
 }
 
-/** 工厂所需的最小 pi：registerCommand/registerTool/on/registerMessageRenderer + appendEntry/sendMessage/sendUserMessage */
+/** 工厂所需的最小 pi：registerCommand/registerTool/on/registerMessageRenderer + appendEntry/sendMessage */
 function makeFactoryFixture(): FactoryFixture {
 	const states: unknown[] = [];
 	const history: unknown[] = [];
-	const sendUser: unknown[] = [];
 	const commands: Record<string, { description?: string }> = {};
 	const pi = {
 		registerCommand: (name: string, opts: { description?: string }) => {
@@ -60,9 +58,6 @@ function makeFactoryFixture(): FactoryFixture {
 			else states.push(data);
 		},
 		sendMessage: () => {},
-		sendUserMessage(content: unknown): void {
-			sendUser.push(content);
-		},
 	} as unknown as ExtensionAPI;
 
 	const ctx = {
@@ -78,7 +73,7 @@ function makeFactoryFixture(): FactoryFixture {
 		sessionManager: { getEntries: () => [], getBranch: () => undefined },
 	} as unknown as ExtensionContext;
 
-	return { pi, ctx, states, history, sendUser, commands };
+	return { pi, ctx, states, history, commands };
 }
 
 // ── goalInit slot（NFR-AC-8 / T1.8）──────────────────
@@ -181,7 +176,6 @@ function makeE1Fixture(
 			appendFileSync(sessionFile, `${JSON.stringify({ type: "custom", customType, data })}\n`, "utf-8");
 		},
 		sendMessage: () => {},
-		sendUserMessage: () => {},
 	} as unknown as ExtensionAPI;
 
 	const ctx = {

package/src/__tests__/service.test.ts

@@ -42,7 +42,6 @@ function makeFakePorts(): ServicePorts & {
 		},
 		messaging: {
 			sendContextMessage: () => {},
-			sendUserMessage: () => {},
 		},
 		session: {
 			getEntries: () => [],

package/src/__tests__/stubs/pi-sdk.ts

@@ -7,9 +7,17 @@ export function StringEnum<T extends readonly string[]>(values: T, _options?: Re
 	return values[0] as T[number];
 }
 
-// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）
+// Text: pi-tui 的渲染节点 stub（goal-control-adapter renderCall/renderResult 返回值）。
+// 承载 content 并提供最小 render（原样单行返回）——renderCall 的非法 args 安全渲染
+// 测试经它断言渲染文本。
 export class Text {
-	constructor(_content: unknown, _x: number, _y: number) {}
+	content: unknown;
+	constructor(content: unknown, _x: number, _y: number) {
+		this.content = content;
+	}
+	render(_width: number): string[] {
+		return [String(this.content)];
+	}
 }
 
 // Pi SDK types used in import chains — re-export as empty

package/src/adapters/command-adapter.ts

@@ -9,7 +9,7 @@
  *
  * 状态变更调 service（createGoal / finalizeAndPersist）；
  * ports 桥接复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）；
- * FR-8.12: set/resume 后 sendUserMessage 触发 AI。
+ * FR-8.12: set/resume 后经 messaging.sendContextMessage（followUp）触发 AI。
  *
  * adapters 层可 import Pi 类型（桥接 Pi 和 service）。
  */
@@ -184,16 +184,17 @@ function handleResume(pi: ExtensionAPI, session: GoalSession, ctx: ExtensionCont
 	persistState(session, ports);
 	updateWidget(session, ports.ui);
 
-	// FR-8.12 并行模式：resume 后触发 AI 继续
+	// FR-8.12 并行模式：resume 后触发 AI 继续（custom message + followUp，
+	// 非 streaming 时经端口 triggerTurn 开轮）
 	const blockerNote = state.lastBlockerReason
 		? `\n\nPrevious blocker: ${state.lastBlockerReason}. Try a different approach.`
 		: "";
 	const capNote = cappedActive
 		? "\n\nContinuation circuit breaker was reached — pursue the objective with concrete tool-backed progress."
 		: "";
-	pi.sendUserMessage(
+	ports.messaging.sendContextMessage(
 		`Goal resumed. Continuing toward the objective.${blockerNote}${capNote}\n\nObjective: ${state.objective}`,
-		{ deliverAs: "followUp" },
+		"followUp",
 	);
 }
 
@@ -347,7 +348,7 @@ function handleUpdate(
 
 /**
  * /goal <objective> 改为「提示词触发器」：不直接 createGoal，
- * 而是 sendUserMessage 引导 AI 调 goal_control create（slug 由 AI 生成）。
+ * 而是发 custom message（followUp）引导 AI 调 goal_control create（slug 由 AI 生成）。
  *
  * 这样 goal 创建的唯一路径是 goal_control toolcall（统一入口），
  * slug/objective/budget 都由 AI 在 toolcall 时决定。
@@ -400,6 +401,7 @@ function handleSet(
 		`\nRaw objective from user: ${objective.trim()}${budgetLine}`;
 
 	ctx.ui.notify(`Requesting goal start: ${objective.trim()}`, "info");
-	// FR-8.12: 触发 AI（followUp）—— AI 消化后调 goal_control create
-	pi.sendUserMessage(message, { deliverAs: "followUp" });
+	// FR-8.12: 触发 AI（custom message + followUp，非 streaming 时开轮）—— AI 消化后调 goal_control create
+	const ports = buildPorts(pi, ctx);
+	ports.messaging.sendContextMessage(message, "followUp");
 }

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

@@ -189,7 +189,7 @@ async function handleContinuation(
 	);
 
 	// pending 守卫：有活跃 background subagent/workflow 时不发 continuation。
-	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true,deliverAs:"steer"}) 自然唤醒主 agent；
+	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true}，缺省 deliverAs 即 steer) 自然唤醒主 agent；
 	// goal 抢先催会与异步任务完成通知叠加，形成“停不下来”的死循环——continuation 排入
 	// _followUpMessages 队列 → _handlePostAgentRun 的 hasQueuedMessages() 返回 true → agent.continue()
 	// 新 turn → 又 agent_end → 又 continuation。

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

@@ -16,7 +16,7 @@
  * - complete: finalizeAndPersist(state, "complete", ...)（内部已含 tickState → finalizeGoal → persist）
  * - report_blocked: 手动 tickState（status 仍 active 才累加当前运行段）→ transitionStatus(active→blocked) → persistState
  *
- * create 不调 sendUserMessage：toolcall 时 AI 已在 turn 中，返回结果后自行续跑
+ * create 不发消息注入：toolcall 时 AI 已在 turn 中，返回结果后自行续跑
  * （与 /goal set 的 followUp 触发区分；对齐 Codex create_goal 不自动续跑）。
  *
  * schema：扁平 Type.Object（OpenAI 兼容，C3）——parameters 顶层必须是 type:"object"，
@@ -33,6 +33,7 @@
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { type Static, Type } from "typebox";
 
 import { SHORT_ID_LENGTH } from "../constants";
@@ -112,6 +113,26 @@ export const GoalControlParams = Type.Object(
 
 export type GoalControlParamsT = Static<typeof GoalControlParams>;
 
+const logger = getLogger("goal");
+
+/**
+ * 辅助 UI 通道降级包装：updateWidget / notify 失败只 warn 留痕不上抛。
+ *
+ * 调用点全部位于核心副作用（createGoal / finalizeAndPersist / persistState）之后——
+ * 状态已落盘，UI 通道故障不能翻转工具结果（与 base-tool-enhance notify.ts 的接入点
+ * 降级同构）。错误串格式化内联（Error message / String）而非复用
+ * @zhushanwen/pi-ext-guards 的 toErrorMessage——不为一个一行 helper 引入运行时依赖。
+ */
+function runUiChannelSafe(action: GoalControlDetails["action"], goalId: string, fn: () => void): void {
+	try {
+		fn();
+	} catch (err) {
+		logger.warn(`goal_control ${action}: ui channel failed; persisted state unaffected`, {
+			detail: { goalId, err: err instanceof Error ? err.message : String(err) },
+		});
+	}
+}
+
 // ── Details（renderResult 数据来源）──────────────────
 
 export interface GoalControlDetails {
@@ -130,7 +151,7 @@ export interface GoalControlDetails {
  * slug：AI 生成的短标识，仅 widget 标题 + history 用，不注入 prompt。真 optional。
  * objective：完整描述，注入每轮 context prompt（保证方向感）。
  *
- * 全解耦：不读 todo/plan。toolcall 时 AI 已在 turn 中，**不**调 sendUserMessage
+ * 全解耦：不读 todo/plan。toolcall 时 AI 已在 turn 中，**不**发消息注入
  * （AI 返回后自行续跑，对齐 Codex create_goal）。
  *
  * 守卫用 D25 严格语义：非终态 active/paused/blocked 全挡，提示用 /goal resume 或
@@ -212,14 +233,16 @@ export function handleCreate(
 		// createGoal 内部 active 守卫兜底（理论上上面守卫已挡；防御性）
 		throw new Error("Goal already active. Cannot create a new one.");
 	}
-	updateWidget(session, ports.ui);
 
 	const state = session.state!;
 	// slug fallback：未提供时用 goalId 截断作标题（与 buildGoalGui 一致，避免 [undefined]）
 	const slug = state.slug ?? state.goalId.slice(0, SHORT_ID_LENGTH);
 	const budgetNotice: string[] = [];
 	if (budget.tokenBudget) budgetNotice.push(`Token budget: ${budget.tokenBudget}`);
-	ports.ui.notify([`Goal created [${slug}]: ${objective}`, ...budgetNotice].join("\n"), "info");
+	runUiChannelSafe("create", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify([`Goal created [${slug}]: ${objective}`, ...budgetNotice].join("\n"), "info");
+	});
 
 	return { action: "create", goalId: state.goalId, status: state.status, slug };
 }
@@ -251,8 +274,10 @@ export function handleComplete(
 
 	// FR-3.3: 唯一终态序列入口（内部：tickState → finalizeGoal(transition+history) → persist）
 	finalizeAndPersist(state, "complete", ports);
-	updateWidget(session, ports.ui);
-	ports.ui.notify(`Goal completed: ${state.objective}`, "info");
+	runUiChannelSafe("complete", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify(`Goal completed: ${state.objective}`, "info");
+	});
 
 	return { action: "complete", goalId: state.goalId, status: state.status };
 }
@@ -289,8 +314,10 @@ export function handleReportBlocked(
 	state.status = transitionStatus(state.status, "blocked");
 
 	persistState(session, ports);
-	updateWidget(session, ports.ui);
-	ports.ui.notify(`Goal blocked: ${reason}`, "warning");
+	runUiChannelSafe("report_blocked", state.goalId, () => {
+		updateWidget(session, ports.ui);
+		ports.ui.notify(`Goal blocked: ${reason}`, "warning");
+	});
 
 	return { action: "report_blocked", goalId: state.goalId, status: state.status };
 }
@@ -376,12 +403,23 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
 
 			// 状态展示不再进 tool result（GUI 渲染字段已移除）：GUI 由 handle* 内的 updateWidget
-			// 经 guiSetWidget 推送（M17 对话流 widget 面板）。
+			// 经 setWidgetDual 推送（GUI 臂 = guiSetWidget/marker 通道，低层原语不单独调用；
+			// 渲染终点 = composer 任务托盘的协议 widget 区）。
 			return { content: [{ type: "text", text }], details };
 		},
 
 		renderCall(args: Record<string, unknown>, theme: Theme): Text {
-			const action = args.action as string;
+			// TUI 渲染先于 schema 校验（args 是未经 schema 收窄的原始形态）：非对象整体
+			// 走安全占位（不抛错）；action/slug 逐个 typeof 守卫替代裸断言——非法 action
+			// 落 report_blocked 回落分支（与原行为一致）
+			if (typeof args !== "object" || args === null) {
+				return new Text(
+					theme.fg("toolTitle", theme.bold("goal_control ")) + theme.fg("muted", "(invalid args)"),
+					0,
+					0,
+				);
+			}
+			const action = typeof args.action === "string" ? args.action : "";
 			const slug = typeof args.slug === "string" ? args.slug : "";
 			const actionLabel =
 				action === "create"

package/src/adapters/ports.ts

@@ -5,7 +5,7 @@
  *
  * - persistence: pi.appendEntry 映射到 appendState / appendHistory（type 字符串区分）
  * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + theme（fg/bold 适配 ThemeLike）
- * - messaging: pi.sendMessage 映射到 sendContextMessage / sendUserMessage
+ * - messaging: pi.sendMessage（custom message 形态）映射到 sendContextMessage
  * - session: ctx.sessionManager.getEntries
  *
  * port/ctx 双通道惯例：port 对象仅用于传入 service/session 的实参；
@@ -74,6 +74,8 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 	};
 
 	const messaging: MessagingPort = {
+		// triggerTurn: true——非 streaming 时真实开轮（不设则 pi 只 append entry 不开轮，
+		// 消息成死文）；streaming 时走 deliverAs 队列（steer/followUp），triggerTurn 不额外生效。
 		sendContextMessage: (content, deliverAs, customType): void => {
 			pi.sendMessage(
 				{
@@ -81,12 +83,9 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 					content,
 					display: false,
 				},
-				{ deliverAs },
+				{ deliverAs, triggerTurn: true },
 			);
 		},
-		sendUserMessage: (content, deliverAs): void => {
-			pi.sendUserMessage(content, { deliverAs });
-		},
 	};
 
 	const session: SessionPort = {

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

@@ -91,7 +91,7 @@ describe("createGoalState", () => {
 
 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(...)` 这类跨行白名单赋值形态，逐行实现会误报。

package/src/index.ts

@@ -125,7 +125,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 	 * 通道形态（C-ext-06 globalThis slot 惯例）：裸函数直挂——plan 侧使用点以 typeof 守卫
 	 * 读取 `globalThis[Symbol.for("@zhushanwen/pi-goal.goalInit")]`（plan/src/compact.ts）。
 	 * 不挂 pi API 对象：pi 0.84.4 为每个扩展创建独立 ExtensionAPI，挂 pi 对象的字段
-	 * 跨扩展不可见（设计 docs/design/goal-bridge-cross-extension.md §2.3）。
+	 * 跨扩展不可见。
 	 *
 	 * @param objective 目标描述
 	 * @param budget 预算配置，传 undefined 用默认值

package/src/ports.ts

@@ -70,10 +70,11 @@ export interface UiPort {
 // ── MessagingPort ────────────────────────────────────
 
 export interface MessagingPort {
-	/** 发送 custom message（goal-context 等） */
+	/**
+	 * 发送 custom message（goal-context 等）。实现侧固定 display:false +
+	 * triggerTurn:true（非 streaming 真实开轮，streaming 走 deliverAs 队列）。
+	 */
 	sendContextMessage(content: string, deliverAs: "steer" | "followUp", customType?: string): void;
-	/** 发送 user message（触发 AI 开始工作，FR-8.12） */
-	sendUserMessage(content: string, deliverAs: "steer" | "followUp"): void;
 }
 
 // ── SessionPort ──────────────────────────────────────

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

@@ -284,12 +284,17 @@ describe("updateWidget dual payload（gui 臂）", () => {
 		updateWidget(session, ui);
 		const widgetCall = calls.find((c) => c.method === "setWidget" && c.args[0] === "goal");
 		const payload = widgetCall!.args[1] as {
-			gui: { component: { type: string }; meta: { title: string; progress?: { total: number } } };
+			gui: {
+				component: { type: string };
+				meta: { title: string; progress?: { total: number }; icon?: string | { paths: string[] } };
+			};
 			text: string[];
 		};
 		// v1.1：gui 臂整个 GuiRenderResult（group 组合根 + meta 宿主元数据，head 由壳层渲染）
 		expect(payload.gui.component.type).toBe("group");
 		expect(payload.gui.meta.progress).toMatchObject({ total: 10000 });
+		// 托盘 icon 随 dual payload 的 gui 臂到达宿主（协议形状 = string key）
+		expect(payload.gui.meta.icon).toBe("target");
 		// text 臂同步构造（TUI 渲染行）
 		expect(payload.text.length).toBeGreaterThan(0);
 	});
@@ -301,9 +306,11 @@ describe("updateWidget dual payload（gui 臂）", () => {
 		updateWidget(session, ui);
 		const widgetCall = calls.find((c) => c.method === "setWidget" && c.args[0] === "goal");
 		const payload = widgetCall!.args[1] as {
-			gui: { component: { type: string }; meta: { title: string; progress?: unknown } };
+			gui: { component: { type: string }; meta: { title: string; progress?: unknown; icon?: unknown } };
 		};
 		expect(payload.gui.component.type).toBe("group");
 		expect(payload.gui.meta.progress).toBeUndefined();
+		// icon 与预算无关，两种形态都推（托盘不依赖宿主 widgetKey 映射兜底）
+		expect(payload.gui.meta.icon).toBe("target");
 	});
 });

package/src/projection/gui.ts

@@ -6,7 +6,8 @@
  *
  * 与 projection/widget.ts 的分工：
  * - widget.ts：TUI 模式渲染（ANSI 字符串，经 ctx.ui.setWidget）
- * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，经 guiSetWidget 推送给 M17 对话流 widget 面板）
+ * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，经 setWidgetDual 推送——GUI 臂 =
+ *   guiSetWidget/marker 通道，低层原语不单独调用；渲染终点 = composer 任务托盘的协议 widget 区）
  *
  * 预算阈值经 engine/budget.ts 的 getBudgetSeverity 单源化（H4）：
  * buildGoalGui（percent→severity）与 widget.getBudgetColor（percent→color）共用阈值。
@@ -70,7 +71,7 @@ function metaStatus(status: GoalStatus): WidgetMeta["status"] {
 /**
  * 构造 goal 的 GUI 渲染描述符（v1.1 meta head 架构）。
  *
- * - meta（标题=slug / 状态点 / token 进度）由宿主壳层渲染成唯一 head；
+ * - meta（托盘 icon / 标题=slug / 状态点 / token 进度）由宿主壳层渲染成唯一 head；
  *   有预算时进度计数用百分比 + 预算阈值 severity（70/90 warn/danger 单源）。
  * - 内容根 = group（透明组合容器）：stats-line（status/turn，无预算时补 token
  *   绝对值）+ list-tree（criteria 逐行，无 icon——所有行同 icon 是无信息量装饰，
@@ -114,6 +115,11 @@ export function buildGoalGui(state: GoalRuntimeState): GuiRenderResult {
 	}
 
 	const meta: WidgetMeta = {
+		// 点名 lucide key "target"（与宿主内置 widgetKey 映射 "goal"→Target 同图标）：
+		// 宿主映射只是兜底，extension 显式声明后，宿主调整自己的映射表也不会换掉 goal 的图标。
+		// 不推 badge：托盘 badge 缺省由 progress.label 派生（"42%"），推一份同值字符串会把
+		// 百分比格式变成两个真相源。
+		icon: "target",
 		title: slug,
 		status: metaStatus(state.status),
 		...(hasBudget

package/src/service.ts

@@ -124,7 +124,7 @@ export function persistAndUpdate(
  * - goalInit slot（index.ts，跨扩展编程式入口）
  *
  * 注：/goal <objective> 命令路径已改为提示词触发器——不直接调本函数，
- * 而是 sendUserMessage 让 AI 调 goal_control create（slug + successCriteria 由 AI 生成）。
+ * 而是发 custom message 让 AI 调 goal_control create（slug + successCriteria 由 AI 生成）。
  *
  * @param slug AI 生成的短标识（optional，仅 widget 标题 + history 用）
  * @param successCriteria 成功标准（optional，由 AI 推导或外部传入；注入 prompt 指导完成验证）