@zhushanwen/pi-goal 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.1"
+    "@zhushanwen/pi-pending-notifications": "0.3.2"
   },
   "dependencies": {
     "@xyz-agent/extension-protocol": "^0.4.0"

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

@@ -1,15 +1,11 @@
 /**
- * goal_control tool — execute handler RPC 分支 handler 级测试（W3 Wave __gui__ 协议）
- *
- * PR review 补测：registerGoalControlTool execute handler 中
- *   `if (ctx.mode === "rpc" && session.state)` 分支和 __gui__ 注入。
+ * goal_control tool — execute handler 级测试（M17 后：tool result 无 __gui__）
  *
  * 覆盖场景：
- * - RPC 模式 + session.state 非 null → details.__gui__ 存在（card 或 stats-line）
- * - RPC 模式 + session.state = null → 跳过路径守卫生效（前置 handler throw，验证分支不可达）
- * - TUI 模式 → __gui__ 不附加
- * - RPC 模式 + 有 budget → __gui__ 为 card 类型（progress-bar + stats-line）
- * - RPC 模式 + 无 budget → __gui__ 为 stats-line 类型
+ * - RPC 模式 create/complete/report_blocked → details 无 __gui__ 字段（状态展示改由
+ *   handle* 内 updateWidget 经 guiSetWidget 推送 M17 对话流 widget 面板）
+ * - RPC 模式 + session.state = null → 前置 handler throw（分支不可达）
+ * - 非 RPC 模式（tui/json/print）→ details 同样无 __gui__，content 文本正常
  *
  * 范式参考 ask-user/src/__tests__/index.test.ts R-1~R-7（handler 级：注册 → 捕获 → 直接调 execute）。
  * 不 mock handleCreate：走真实 createGoal 让 session.state 含完整字段（slug/objective/budget），
@@ -117,47 +113,36 @@ function createViaHandler(
 
 // ── 测试场景 ─────────────────────────────────────────
 
-describe("goal_control execute — RPC __gui__ 注入分支", () => {
-	it("RPC + 有 state（有 budget）→ details.__gui__ 存在且为 card 类型", async () => {
+describe("goal_control execute — RPC 模式 tool result 无 __gui__", () => {
+	it("RPC + 有 budget 的 create → details 无 __gui__ 字段（content 仍正常）", async () => {
 		const { pi, ctx } = makeFixture("rpc");
 		const tool = captureTool(pi);
-		// create 后 session.state 有 tokenBudget → buildGoalGui 走 card 分支
 		const result = await createViaHandler(tool, pi, ctx, {
 			slug: "rpc-card",
 			objective: "rpc card goal",
 			tokenBudget: 10000,
 		});
-		const gui = result.details.__gui__!;
-		expect(gui.component.type).toBe("card");
-		// card body 含 progress-bar（tokenBudget）+ stats-line
-		const body = gui.component.props.body as Array<{ type: string }>;
-		const types = body.map((c) => c.type);
-		expect(types).toContain("progress-bar");
-		expect(types).toContain("stats-line");
+		expect("__gui__" in result.details).toBe(false);
+		expect(result.details.action).toBe("create");
+		expect(result.details.status).toBe("active");
+		expect(result.content[0].text).toContain("Goal created");
 	});
 
-	it("RPC + 有 state（无 budget）→ details.__gui__ 存在且为 stats-line 类型", async () => {
+	it("RPC + 无 budget 的 create → details 无 __gui__ 字段", async () => {
 		const { pi, ctx } = makeFixture("rpc");
 		const tool = captureTool(pi);
-		// create 不传 budget → buildGoalGui 走 stats-line 分支
 		const result = await createViaHandler(tool, pi, ctx, {
 			slug: "rpc-stats",
 			objective: "rpc stats goal",
 		});
-		const gui = result.details.__gui__!;
-		expect(gui.component.type).toBe("stats-line");
-		// stats-line items 含 goal/status/turn/tokens
-		const items = gui.component.props.items as Array<{ label: string }>;
-		const labels = items.map((i) => i.label);
-		expect(labels).toContain("goal");
-		expect(labels).toContain("status");
+		expect("__gui__" in result.details).toBe(false);
+		expect(result.details.action).toBe("create");
 	});
 
-	it("RPC + session.state = null → 跳过路径守卫生效（前置 handler throw，分支不可达）", async () => {
-		// 源码 line 380: `if (ctx.mode === "rpc" && session.state)` 的 session.state 守卫。
+	it("RPC + session.state = null → 前置 handler throw（分支不可达）", async () => {
 		// execute 路径上，create 总会 set session.state；complete/report_blocked 前置守卫
-		// 要求 session.state 非 null 否则 throw——所以 session.state=null 时分支条件恒不成立。
-		// 验证：全新 session（state=null）下，complete 前置守卫先 throw，不进 __gui__ 注入逻辑。
+		// 要求 session.state 非 null 否则 throw——所以 session.state=null 时不会走到返回路径。
+		// 验证：全新 session（state=null）下，complete 前置守卫先 throw。
 		const { pi, ctx } = makeFixture("rpc");
 		let captured: CapturedTool | undefined;
 		const capturePi = {
@@ -168,7 +153,7 @@ describe("goal_control execute — RPC __gui__ 注入分支", () => {
 		} as unknown as ExtensionAPI;
 		registerGoalControlTool(capturePi, createGoalSession());
 		const tool2 = captured!;
-		// complete 在 state=null 时 throw（handleComplete 前置守卫）—— 不会走到 __gui__ 分支
+		// complete 在 state=null 时 throw（handleComplete 前置守卫）
 		await expect(
 			tool2.execute(
 				"id",
@@ -180,13 +165,12 @@ describe("goal_control execute — RPC __gui__ 注入分支", () => {
 		).rejects.toThrow(/not active/i);
 	});
 
-	it("RPC + complete 动作 → __gui__ 也附加（用终态 state 渲染）", async () => {
-		// 验证 __gui__ 注入不限于 create：complete 后 session.state 仍非 null（status=complete）
+	it("RPC + complete 动作 → details 无 __gui__ 字段（终态 status 正确）", async () => {
 		const { pi, ctx } = makeFixture("rpc");
 		const tool = captureTool(pi);
 		// 先 create（建 active state）
 		await createViaHandler(tool, pi, ctx, { slug: "comp", objective: "to complete" });
-		// 再 complete —— session.state.status=complete，buildGoalGui 走 card variant=success
+		// 再 complete —— session.state.status=complete
 		const result = await tool.execute(
 			"call-2",
 			{ action: "complete", evidence: "tests green" },
@@ -195,15 +179,10 @@ describe("goal_control execute — RPC __gui__ 注入分支", () => {
 			ctx,
 		);
 		expect(result.details.status).toBe("complete");
-		const gui = result.details.__gui__!;
-		// 无 budget → stats-line
-		expect(gui.component.type).toBe("stats-line");
-		const items = gui.component.props.items as Array<{ label: string; value: string }>;
-		const statusItem = items.find((i) => i.label === "status");
-		expect(statusItem!.value).toBe("complete");
+		expect("__gui__" in result.details).toBe(false);
 	});
 
-	it("RPC + report_blocked 动作 → __gui__ 附加，status severity danger", async () => {
+	it("RPC + report_blocked 动作 → details 无 __gui__ 字段（blocked status 正确）", async () => {
 		const { pi, ctx } = makeFixture("rpc");
 		const tool = captureTool(pi);
 		await createViaHandler(tool, pi, ctx, { slug: "blk", objective: "to block" });
@@ -215,21 +194,16 @@ describe("goal_control execute — RPC __gui__ 注入分支", () => {
 			ctx,
 		);
 		expect(result.details.status).toBe("blocked");
-		// 无 budget → stats-line；blocked status severity=danger
-		const gui = result.details.__gui__!;
-		expect(gui.component.type).toBe("stats-line");
-		const items = gui.component.props.items as Array<{ label: string; severity?: string }>;
-		const statusItem = items.find((i) => i.label === "status");
-		expect(statusItem!.severity).toBe("danger");
+		expect("__gui__" in result.details).toBe(false);
 	});
 
 });
 
-// ── 边界：非 RPC 模式（tui/json/print）也不注入 __gui__ ──
+// ── 边界：非 RPC 模式（tui/json/print）同样无 __gui__ ──
 
-describe("goal_control execute — 非 RPC 模式不注入 __gui__", () => {
+describe("goal_control execute — 非 RPC 模式无 __gui__", () => {
 	const NON_RPC_MODES: Array<"tui" | "json" | "print"> = ["tui", "json", "print"];
-	it.each(NON_RPC_MODES)("%s 模式 → __gui__ 不附加（content 仍正常）", async (mode) => {
+	it.each(NON_RPC_MODES)("%s 模式 → details 无 __gui__ 字段（content 仍正常）", async (mode) => {
 		const { pi, ctx } = makeFixture(mode);
 		const tool = captureTool(pi);
 		const result = await createViaHandler(tool, pi, ctx, {
@@ -237,7 +211,7 @@ describe("goal_control execute — 非 RPC 模式不注入 __gui__", () => {
 			objective: `${mode} goal`,
 			tokenBudget: 1000,
 		});
-		expect(result.details.__gui__).toBeUndefined();
-		expect(result.content[0]!.text).toContain("Goal created");
+		expect("__gui__" in result.details).toBe(false);
+		expect(result.content[0].text).toContain("Goal created");
 	});
 });

package/src/__tests__/gui.test.ts

@@ -1,11 +1,11 @@
 /**
- * buildGoalGui 测试 — goal 的 GUI 渲染描述符构造（W3 Wave __gui__ 协议）
+ * buildGoalGui 测试 — v1.1 meta head 架构。
  *
  * 覆盖：
- * - 有 tokenBudget/timeBudget → card(progress-bar + stats-line)
- * - 预算消耗阈值（≥70% warn, ≥90% danger）
- * - 状态→severity/variant 映射
- * - 无 budget → stats-line 摘要
+ * - 内容根 = group（透明组合容器）：stats-line（status/turn[+tokens]）+ list-tree（criteria）
+ * - meta：title=slug、状态点语义（done/failed/idle/running）、token 进度（取整 + 百分比 + 阈值 severity）
+ * - successCriteria 逐行 list-tree（不压扁/不截断/无 icon/不编号）
+ * - token 展示走 formatTokens（无 budget 分支）
  */
 import { describe, expect, it } from "vitest";
 
@@ -20,30 +20,58 @@ function makeState(overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState
 	};
 }
 
-/** 从 card 分支的 body 中按 type 取组件（hasBudget 分支只有一个 progress-bar / 一个 stats-line 组合）。 */
-function findBodyComp(
+/** 从 group children 中按 type 取组件（每个类型至多一个）。 */
+function findChildComp(
 	gui: ReturnType<typeof buildGoalGui>,
 	type: string,
 ): { type: string; props: Record<string, unknown> } {
-	const body = gui.component.props.body as { type: string; props: Record<string, unknown> }[];
-	return body.find((c) => c.type === type)!;
+	if (gui.component.type !== "group") throw new Error(`root 应为 group，实际 ${gui.component.type}`);
+	const children = gui.component.props.children as { type: string; props: Record<string, unknown> }[];
+	const found = children.find((c) => c.type === type);
+	if (!found) throw new Error(`children 中无 ${type} 组件`);
+	return found;
 }
 
-describe("buildGoalGui", () => {
-	it("有 tokenBudget → card 含 progress-bar + stats-line", () => {
+describe("buildGoalGui（v1.1 meta head 架构）", () => {
+	it("内容根 = group(stats-line + list-tree)，无 card（卡壳/head 归宿主壳层）", () => {
 		const gui = buildGoalGui(
 			makeState({
 				tokensUsed: 4200,
 				budget: { tokenBudget: 10000 },
 				currentTurnIndex: 3,
+				successCriteria: "all tests green",
 			}),
 		);
 		expect(gui.v).toBe(1);
-		expect(gui.component.type).toBe("card");
-		const tokenBar = findBodyComp(gui, "progress-bar");
-		expect(tokenBar.props).toMatchObject({ current: 4200, total: 10000, severity: "ok" });
-		const stats = findBodyComp(gui, "stats-line");
+		expect(gui.component.type).toBe("group");
+		const stats = findChildComp(gui, "stats-line");
 		expect(stats.props.items).toContainEqual(expect.objectContaining({ label: "status", value: "active" }));
+		expect(findChildComp(gui, "list-tree")).toBeDefined();
+		// 无 progress-bar（token 进度移入 head meta）
+		expect(() => findChildComp(gui, "progress-bar")).toThrow();
+	});
+
+	it("meta：title=slug、status=running、progress=取整 current + 百分比 label + 阈值 severity", () => {
+		const gui = buildGoalGui(
+			makeState({
+				slug: "fix-auth",
+				tokensUsed: 4200,
+				budget: { tokenBudget: 10000 },
+			}),
+		);
+		expect(gui.meta).toEqual({
+			title: "fix-auth",
+			status: "running",
+			progress: { current: 4200, total: 10000, label: "42%", severity: "ok" },
+		});
+	});
+
+	it("tokensUsed 浮点 → meta.progress.current 取整（1454.84…1 不进 UI）", () => {
+		const gui = buildGoalGui(
+			makeState({ tokensUsed: 1454.8400000000001, budget: { tokenBudget: 5000 } }),
+		);
+		expect(gui.meta!.progress!.current).toBe(1455);
+		expect(gui.meta!.progress!.label).toBe("29%");
 	});
 
 	it.each([
@@ -51,111 +79,96 @@ describe("buildGoalGui", () => {
 		["9000/10000 =90%", 9000, "danger"],
 		["7500/10000 ≥70%", 7500, "warn"],
 		["7000/10000 =70%", 7000, "warn"],
-	])("token 消耗 %s → severity %s（S#14 边界 ≥）", (_label, used, severity) => {
+	])("token 消耗 %s → meta.progress.severity %s（S#14 边界 ≥）", (_label, used, severity) => {
 		const gui = buildGoalGui(makeState({ tokensUsed: used, budget: { tokenBudget: 10000 } }));
-		const tokenBar = findBodyComp(gui, "progress-bar");
-		expect(tokenBar.props.severity).toBe(severity);
+		expect(gui.meta!.progress!.severity).toBe(severity);
 	});
 
-	it("无 budget → stats-line 摘要", () => {
+	it.each([
+		["complete", "done"],
+		["blocked", "failed"],
+		["budget_limited", "failed"],
+		["cancelled", "failed"],
+		["paused", "idle"],
+	])("status %s → meta.status %s", (status, metaStatus) => {
 		const gui = buildGoalGui(
-			makeState({
-				currentTurnIndex: 5,
-				tokensUsed: 3000,
-			}),
+			makeState({ status: status as GoalStatus, budget: { tokenBudget: 10000 } }),
 		);
-		expect(gui.component.type).toBe("stats-line");
-		const items = gui.component.props.items as { label?: string }[];
-		const labels = items.map((i) => i.label);
-		expect(labels).toContain("goal");
-		expect(labels).toContain("status");
-		expect(labels).toContain("turn");
-		expect(labels).toContain("tokens");
+		expect(gui.meta!.status).toBe(metaStatus);
 	});
 
-	it("blocked 状态 → card variant danger", () => {
+	it("无 budget → stats-line 含 tokens（formatTokens，3k），meta 无 progress", () => {
 		const gui = buildGoalGui(
 			makeState({
-				status: "blocked",
-				budget: { tokenBudget: 10000 },
+				currentTurnIndex: 5,
+				tokensUsed: 3000,
 			}),
 		);
-		expect(gui.component.type).toBe("card");
-		expect(gui.component.props.variant).toBe("danger");
+		expect(gui.meta).toEqual({ 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" });
 	});
 
-	it("complete 状态 → card variant success", () => {
-		const gui = buildGoalGui(
-			makeState({
-				status: "complete",
-				budget: { tokenBudget: 10000 },
-			}),
-		);
-		expect(gui.component.type).toBe("card");
-		expect(gui.component.props.variant).toBe("success");
+	it("有 budget 时 stats-line 不重复 tokens（head 进度已表达）", () => {
+		const gui = buildGoalGui(makeState({ tokensUsed: 3000, budget: { tokenBudget: 10000 } }));
+		const stats = findChildComp(gui, "stats-line");
+		const labels = (stats.props.items as { label?: string }[]).map((i) => i.label);
+		expect(labels).not.toContain("tokens");
 	});
 
-	it("slug 缺省 → header 用 goalId 前 8 字符", () => {
+	it("slug 缺省 → meta.title 用 goalId 前 8 字符", () => {
 		const state = makeState({ slug: undefined, budget: { tokenBudget: 10000 } });
-		const gui = buildGoalGui(state);
-		expect(gui.component.props.header).toBe(state.goalId.slice(0, 8));
+		expect(buildGoalGui(state).meta!.title).toBe(state.goalId.slice(0, 8));
 	});
 
-	// ── S#2: statusSeverity 完整覆盖 ──
-
 	it.each([
 		["budget_limited", "danger"],
 		["cancelled", "danger"],
 		["paused", "warn"],
 	])("status %s → stats-line status severity %s（S#2）", (status, severity) => {
 		const gui = buildGoalGui(makeState({ status: status as GoalStatus, budget: { tokenBudget: 10000 } }));
-		const stats = findBodyComp(gui, "stats-line");
+		const stats = findChildComp(gui, "stats-line");
 		const items = stats.props.items as Array<{ label: string; severity?: string }>;
 		const statusItem = items.find((i) => i.label === "status")!;
 		expect(statusItem.severity).toBe(severity);
 	});
 
-	// ── I#1: tokenBudget=0 口径统一 ──
-
-	it("tokenBudget=0 → 无 progress-bar（口径 >0，I#1）", () => {
+	it("tokenBudget=0 → 无预算形态（meta 无 progress，stats-line 含 tokens）（I#1 口径 >0）", () => {
 		const gui = buildGoalGui(makeState({ tokensUsed: 0, budget: { tokenBudget: 0 } }));
-		// tokenBudget=0 → hasBudget=false → 走无 budget 分支的 stats-line
-		expect(gui.component.type).toBe("stats-line");
-	});
-
-	// ── 无 budget 分支的 status severity ──
-
-	it("无 budget 时 status severity 正确（S#14）", () => {
-		const gui = buildGoalGui(makeState({ status: "active" }));
-		const items = gui.component.props.items as Array<{ label: string; severity?: string }>;
-		const statusItem = items.find((i) => i.label === "status");
-		expect(statusItem!.severity).toBe("ok");
+		expect(gui.meta!.progress).toBeUndefined();
+		const stats = findChildComp(gui, "stats-line");
+		const labels = (stats.props.items as { label?: string }[]).map((i) => i.label);
+		expect(labels).toContain("tokens");
 	});
 
-	// ── successCriteria 渲染（与 objective 成对，让用户看到「怎么算完成」）──
+	// ── successCriteria 逐行 list-tree ──
 
-	it("card 分支（有 budget）+ successCriteria → body 含 stats-line {label:'done'}", () => {
+	it("多行 successCriteria → list-tree 每行一条纯文本 item（用户报障场景）", () => {
 		const gui = buildGoalGui(
 			makeState({
-				successCriteria: "all tests green",
+				successCriteria: "1. 输出 Node.js 版本号；\n2. 输出 extensions 目录下的子目录列表",
 				budget: { tokenBudget: 10000 },
 			}),
 		);
-		expect(gui.component.type).toBe("card");
-		const body = gui.component.props.body as {
-			type: string;
-			props: { items: Array<{ label: string; value: string }> };
-		}[];
-		const doneStats = body.find(
-			(c) => c.type === "stats-line" && c.props.items.some((i) => i.label === "done"),
-		)!;
-		expect(doneStats.props.items).toContainEqual({ label: "done", value: "all tests green" });
+		const tree = findChildComp(gui, "list-tree");
+		// 无 icon（所有行同 icon 是无信息量装饰）、不编号（criteria 文本常自带编号）
+		expect(tree.props.numbered).toBeUndefined();
+		expect(tree.props.items).toEqual([
+			{ label: "1. 输出 Node.js 版本号；", depth: 0 },
+			{ label: "2. 输出 extensions 目录下的子目录列表", depth: 0 },
+		]);
 	});
 
-	it("无 budget 分支 + successCriteria → items 含 {label:'done'}", () => {
-		const gui = buildGoalGui(makeState({ successCriteria: "all tests green" }));
-		expect(gui.component.type).toBe("stats-line");
-		const items = gui.component.props.items as Array<{ label: string; value: string }>;
-		expect(items).toContainEqual({ label: "done", value: "all tests green" });
+	it("超 80 字符的 criteria 行不截断；空行过滤；无 criteria → 无 list-tree", () => {
+		const longLine = "x".repeat(120);
+		const longGui = buildGoalGui(makeState({ successCriteria: longLine }));
+		expect(findChildComp(longGui, "list-tree").props.items).toEqual([{ label: longLine, depth: 0 }]);
+
+		const gapGui = buildGoalGui(makeState({ successCriteria: "a\n\n  \nb" }));
+		expect(findChildComp(gapGui, "list-tree").props.items).toHaveLength(2);
+
+		const noneGui = buildGoalGui(makeState({ successCriteria: undefined, budget: { tokenBudget: 10000 } }));
+		expect(() => findChildComp(noneGui, "list-tree")).toThrow();
 	});
 });

package/src/__tests__/ports.test.ts

@@ -0,0 +1,77 @@
+/**
+ * adapters/ports.ts 测试 — UiPort GUI 协议接线（marker 编码集成）。
+ *
+ * 验证 buildPorts 构造的 uiPort：
+ * - setGuiWidget 经 guiSetWidget 编码 marker 进 ctx.ui.setWidget（RPC 模式）
+ * - isGui 反映 ctx.mode（rpc → GUI 渲染通道；tui → 原生文本）
+ *
+ * 运行：cd extensions/goal && npx vitest run src/__tests__/ports.test.ts
+ */
+import { describe, expect, it } from "vitest";
+import { GUI_WIDGET_MARKER, guiComponent } from "@xyz-agent/extension-protocol";
+
+import { buildPorts } from "../adapters/ports";
+
+/** mock pi（buildPorts 仅用 pi.appendEntry，此处不测 persistence）。 */
+function makePi(): Parameters<typeof buildPorts>[0] {
+	return { appendEntry: () => {} } as unknown as Parameters<typeof buildPorts>[0];
+}
+
+/** mock ctx，捕获 ui.setWidget 收到的 lines（验证 marker 编码）。 */
+function makeCtx(opts: { mode?: string; hasUI?: boolean } = {}) {
+	let captured: string[] | undefined = undefined;
+	const ctx = {
+		mode: opts.mode ?? "rpc",
+		hasUI: opts.hasUI ?? true,
+		ui: {
+			setWidget: (_key: string, lines: string[] | undefined) => {
+				captured = lines;
+			},
+			setStatus: () => {},
+			notify: () => {},
+			theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
+		},
+	} as unknown as Parameters<typeof buildPorts>[1];
+	return { ctx, getCaptured: () => captured };
+}
+
+describe("buildPorts UiPort.setGuiWidget（marker 编码集成）", () => {
+	it("RPC 模式 setGuiWidget → ctx.ui.setWidget 收到 marker 编码的 string[]", () => {
+		const { ctx, getCaptured } = makeCtx({ mode: "rpc" });
+		const ports = buildPorts(makePi(), ctx);
+		const comp = guiComponent("stats-line", { items: [{ value: "x" }] });
+
+		ports.ui.setGuiWidget("goal", comp);
+
+		const captured = getCaptured();
+		expect(captured).toBeDefined();
+		expect(captured).toHaveLength(1);
+		// marker 前缀（host 侧 event-adapter 据此解码成 extension:widgetGui）
+		expect(captured![0].startsWith(GUI_WIDGET_MARKER)).toBe(true);
+		// 解码还原 GuiComponent
+		const json = captured![0].slice(GUI_WIDGET_MARKER.length);
+		const parsed = JSON.parse(json);
+		expect(parsed.type).toBe("stats-line");
+	});
+
+	it("setGuiWidget(undefined) → ctx.ui.setWidget 收到 undefined（清除语义）", () => {
+		const { ctx, getCaptured } = makeCtx({ mode: "rpc" });
+		const ports = buildPorts(makePi(), ctx);
+
+		ports.ui.setGuiWidget("goal", undefined);
+
+		expect(getCaptured()).toBeUndefined();
+	});
+});
+
+describe("buildPorts UiPort.isGui（ctx.mode 反映）", () => {
+	it("rpc 模式 → isGui=true（GUI 渲染通道有效）", () => {
+		const { ctx } = makeCtx({ mode: "rpc" });
+		expect(buildPorts(makePi(), ctx).ui.isGui).toBe(true);
+	});
+
+	it("tui 模式 → isGui=false（走原生文本行）", () => {
+		const { ctx } = makeCtx({ mode: "tui" });
+		expect(buildPorts(makePi(), ctx).ui.isGui).toBe(false);
+	});
+});

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

@@ -33,13 +33,11 @@
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { type GuiRenderResult } from "@xyz-agent/extension-protocol";
 import { type Static, Type } from "typebox";
 
 import { SHORT_ID_LENGTH } from "../constants";
 import { isActiveStatus, isTerminalStatus, transitionStatus } from "../engine/goal";
 import type { BudgetConfig, GoalStatus } from "../engine/types";
-import { buildGoalGui } from "../projection/gui";
 import { updateWidget } from "../projection/widget";
 import { createGoal, finalizeAndPersist, persistState, type ServicePorts, tickState } from "../service";
 import type { GoalSession } from "../session";
@@ -111,8 +109,6 @@ export interface GoalControlDetails {
 	goalId: string;
 	status: GoalStatus;
 	slug?: string;
-	/** RPC 模式下的 GUI 渲染描述符（progress-bar 预算进度）。TUI 模式无此字段。 */
-	__gui__?: GuiRenderResult;
 }
 
 // ── 业务 handler（契约对齐 §3，可测：fake ports）──────
@@ -344,10 +340,8 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 						? `Goal completed.\nGoal ID: ${details.goalId}`
 						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
 
-			// RPC 模式下附加 __gui__（用展开避免 details 来自 frozen 对象时加字段失败）
-			if (ctx.mode === "rpc" && session.state) {
-				return { content: [{ type: "text", text }], details: { ...details, __gui__: buildGoalGui(session.state) } };
-			}
+			// 状态展示不再进 tool result（GUI 渲染字段已移除）：GUI 由 handle* 内的 updateWidget
+			// 经 guiSetWidget 推送（M17 对话流 widget 面板）。
 			return { content: [{ type: "text", text }], details };
 		},
 

package/src/adapters/ports.ts

@@ -10,6 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { guiSetWidget, isGuiCapable } from "@xyz-agent/extension-protocol";
+import type { GuiContext, GuiRenderResult } from "@xyz-agent/extension-protocol";
 
 import { ENTRY_TYPE, HISTORY_ENTRY_TYPE } from "../persistence";
 import type { MessagingPort, PersistencePort, SessionPort, UiPort } from "../ports";
@@ -45,6 +47,14 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 			const lines = typeof content === "string" ? [content] : content;
 			ctx.ui.setWidget(name, lines);
 		},
+		setGuiWidget(name: string, result: GuiRenderResult | undefined): void {
+			// GUI 协议 widget：guiSetWidget 在 RPC 模式用 marker 编码 GuiRenderResult JSON
+			// （component + meta 宿主元数据）进 string[]，复用 ctx.ui.setWidget 通道；
+			// host 侧 event-adapter 检测 marker 解码还原。guiSetWidget 无 isGui 守卫
+			// （helpers.ts 仅查 ctx.ui?.setWidget 存在性），isGui 判定在 updateWidget
+			// 外层（projection/widget.ts）。
+			guiSetWidget(ctx as unknown as GuiContext, name, result);
+		},
 		setStatus(name: string, text: string | undefined): void {
 			ctx.ui.setStatus(name, text);
 		},
@@ -54,6 +64,10 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 		get hasUI(): boolean {
 			return Boolean(ctx.hasUI);
 		},
+		get isGui(): boolean {
+			// RPC 模式 = GUI 渲染通道有效；TUI/json/print 走 pi 原生渲染
+			return isGuiCapable(ctx as unknown as GuiContext);
+		},
 		// ThemeLike 形状：透传 ctx.ui.theme 的 fg/bold。
 		// Theme.fg 只接受 ThemeColor 字面量 union（SDK 契约）；projection 层保证传入 union 内字面量，
 		// string → ThemeColor 是宽到窄单步断言（无需 unknown 中转）。

package/src/ports.ts

@@ -7,6 +7,7 @@
  */
 
 import type { GoalRuntimeState } from "./engine/types";
+import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
 
 // ── GoalHistoryEntry（DTO，非 aggregate，D-09）─────────
 
@@ -36,12 +37,20 @@ export interface PersistencePort {
 export interface UiPort {
 	/** 设置 widget（undefined = 清除）。hasUI=false 时 adapter 跳过（FR-6.6） */
 	setWidget(name: string, content: string[] | string | undefined): void;
+	/**
+	 * 设置 GUI 协议 widget（GuiRenderResult：component + meta 宿主元数据，
+	 * RPC 模式经 guiSetWidget marker 编码）。TUI 模式 adapter 内部 no-op
+	 * （走 setWidget 文本行）。undefined = 清除。
+	 */
+	setGuiWidget(name: string, result: GuiRenderResult | undefined): void;
 	/** 设置 status bar */
 	setStatus(name: string, text: string | undefined): void;
 	/** 弹通知 */
 	notify(text: string, level: "info" | "warning" | "error"): void;
-	/** 是否有 UI（headless/RPC mode 为 false） */
+	/** 是否有 UI（headless 为 false） */
 	readonly hasUI: boolean;
+	/** 是否 GUI 渲染模式（RPC → GuiComponent；TUI → 原生文本行） */
+	readonly isGui: boolean;
 }
 
 // ── MessagingPort ────────────────────────────────────

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

@@ -194,17 +194,21 @@ describe("renderWidgetLines", () => {
 
 describe("updateWidget (FR-6.6 hasUI guard)", () => {
 	interface RecordedCall {
-		method: "setWidget" | "setStatus";
+		method: "setWidget" | "setGuiWidget" | "setStatus";
 		args: unknown[];
 	}
 
-	function makeUiPort(hasUI: boolean): { ui: UiPort; calls: RecordedCall[] } {
+	function makeUiPort(hasUI: boolean, isGui = false): { ui: UiPort; calls: RecordedCall[] } {
 		const calls: RecordedCall[] = [];
 		const ui = {
 			hasUI,
+			isGui,
 			setWidget(name: string, content: unknown) {
 				calls.push({ method: "setWidget", args: [name, content] });
 			},
+			setGuiWidget(name: string, component: unknown) {
+				calls.push({ method: "setGuiWidget", args: [name, component] });
+			},
 			setStatus(name: string, text: unknown) {
 				calls.push({ method: "setStatus", args: [name, text] });
 			},
@@ -264,3 +268,83 @@ describe("updateWidget (FR-6.6 hasUI guard)", () => {
 		);
 	});
 });
+
+// ── updateWidget GUI 协议分支（isGui=true，复用 projection/gui.ts buildGoalGui）──
+
+describe("updateWidget GUI 协议分支（isGui=true）", () => {
+	interface RecordedCall {
+		method: "setWidget" | "setGuiWidget" | "setStatus";
+		args: unknown[];
+	}
+
+	function makeGuiUiPort(hasUI: boolean, isGui = false): { ui: UiPort; calls: RecordedCall[] } {
+		const calls: RecordedCall[] = [];
+		const ui = {
+			hasUI,
+			isGui,
+			setWidget(name: string, content: unknown) {
+				calls.push({ method: "setWidget", args: [name, content] });
+			},
+			setGuiWidget(name: string, component: unknown) {
+				calls.push({ method: "setGuiWidget", args: [name, component] });
+			},
+			setStatus(name: string, text: unknown) {
+				calls.push({ method: "setStatus", args: [name, text] });
+			},
+			notify() {},
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		} as UiPort;
+		return { ui, calls };
+	}
+
+	it("active + isGui + 有预算 → setGuiWidget(v1.1 result: group + meta) + 不调 setWidget TUI lines", () => {
+		const { ui, calls } = makeGuiUiPort(true, true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "active", budget: { tokenBudget: 10000 } });
+		updateWidget(session, ui);
+		const guiCall = calls.find((c) => c.method === "setGuiWidget" && c.args[0] === "goal");
+		expect(guiCall).toBeDefined();
+		// v1.1：整个 GuiRenderResult（group 组合根 + meta 宿主元数据，head 由壳层渲染）
+		const result = guiCall!.args[1] as {
+			component: { type: string };
+			meta: { title: string; progress?: { total: number } };
+		};
+		expect(result.component.type).toBe("group");
+		expect(result.meta.progress).toMatchObject({ total: 10000 });
+		// GUI 模式不走 TUI 文本行
+		expect(calls.some((c) => c.method === "setWidget" && c.args[0] === "goal")).toBe(false);
+	});
+
+	it("active + isGui 无预算 → setGuiWidget(group，meta 无 progress)", () => {
+		const { ui, calls } = makeGuiUiPort(true, true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "active" });
+		updateWidget(session, ui);
+		const guiCall = calls.find((c) => c.method === "setGuiWidget" && c.args[0] === "goal");
+		expect(guiCall).toBeDefined();
+		const result = guiCall!.args[1] as {
+			component: { type: string };
+			meta: { title: string; progress?: unknown };
+		};
+		expect(result.component.type).toBe("group");
+		expect(result.meta.progress).toBeUndefined();
+	});
+
+	it("cancelled + isGui → setGuiWidget(undefined)", () => {
+		const { ui, calls } = makeGuiUiPort(true, true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "cancelled" });
+		updateWidget(session, ui);
+		expect(calls.some((c) => c.method === "setGuiWidget" && c.args[1] === undefined)).toBe(true);
+	});
+
+	it("isGui=false → 走 TUI setWidget（不调 setGuiWidget）", () => {
+		const { ui, calls } = makeGuiUiPort(true, false);
+		const session = createGoalSession();
+		session.state = makeState({ status: "active" });
+		updateWidget(session, ui);
+		expect(calls.some((c) => c.method === "setWidget" && c.args[0] === "goal")).toBe(true);
+		expect(calls.some((c) => c.method === "setGuiWidget")).toBe(false);
+	});
+});

package/src/projection/gui.ts

@@ -2,22 +2,29 @@
  * GUI 渲染描述符构造（projection 层）— buildGoalGui + goalStatusSeverity
  *
  * H4 拆层：从 adapters/goal-control-adapter.ts 抽出。GUI 渲染描述符归 projection 层，
- * goal-control-adapter 回归 tool 注册 + RPC 模式调用本模块。
+ * goal-control-adapter 回归纯 tool 注册（M17 后不再调用本模块）。
  *
  * 与 projection/widget.ts 的分工：
  * - widget.ts：TUI 模式渲染（ANSI 字符串，经 ctx.ui.setWidget）
- * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，放进 details.__gui__）
+ * - gui.ts：RPC 模式渲染（结构化 GuiComponent 描述符，经 guiSetWidget 推送给 M17 对话流 widget 面板）
  *
  * 预算阈值经 engine/budget.ts 的 getBudgetSeverity 单源化（H4）：
  * buildGoalGui（percent→severity）与 widget.getBudgetColor（percent→color）共用阈值。
  */
 
-import { type GuiComponent, guiComponent, type GuiRenderResult, guiResult } from "@xyz-agent/extension-protocol";
+import {
+	type GuiComponent,
+	guiComponent,
+	type GuiRenderResult,
+	guiResult,
+	type TreeItem,
+	type WidgetMeta,
+} from "@xyz-agent/extension-protocol";
 
-import { OBJECTIVE_DISPLAY_LIMIT, SHORT_ID_LENGTH } from "../constants";
+import { PERCENT_FACTOR, SHORT_ID_LENGTH } from "../constants";
 import { getBudgetSeverity } from "../engine/budget";
 import type { GoalRuntimeState, GoalStatus } from "../engine/types";
-import { toSingleLine } from "./widget";
+import { formatTokens } from "./widget";
 
 /**
  * 按 GoalStatus 映射 stats-line severity（S#2）。
@@ -44,83 +51,93 @@ export function goalStatusSeverity(status: GoalStatus): "ok" | "warn" | "danger"
 	}
 }
 
+/** GoalStatus → head 状态点语义（WidgetMeta.status）。 */
+function metaStatus(status: GoalStatus): WidgetMeta["status"] {
+	switch (status) {
+		case "complete":
+			return "done";
+		case "blocked":
+		case "budget_limited":
+		case "cancelled":
+			return "failed";
+		case "paused":
+			return "idle";
+		case "active":
+			return "running";
+	}
+}
+
 /**
- * 构造 goal 的 GUI 渲染描述符（RPC 模式下放进 details.__gui__）。
- *
- * 逻辑参考 projection/widget.ts 的 renderWidgetLines 预算计算，但此处只构造
- * 结构化数据（GuiComponent），不做 ANSI 渲染。
+ * successCriteria 按行拆分为非空 trim 行。
+ * 原实现用 toSingleLine 压扁 + 截断后塞进 stats-line 单行 value，多行验收标准
+ * 变成一坨长串，是 goal widget 可读性问题的根因——多行数据应改用 list-tree 多行呈现。
+ */
+function splitCriteriaLines(criteria: string | undefined): string[] {
+	return criteria
+		? criteria
+				.split(/\r?\n/)
+				.map((line) => line.trim())
+				.filter((line) => line.length > 0)
+		: [];
+}
+
+/**
+ * 构造 goal 的 GUI 渲染描述符（v1.1 meta head 架构）。
  *
- * - 有 tokenBudget → card(progress-bar + stats-line) 展示预算消耗
- * - 无 budget → stats-line 展示状态摘要
+ * - meta（标题=slug / 状态点 / token 进度）由宿主壳层渲染成唯一 head；
+ *   有预算时进度计数用百分比 + 预算阈值 severity（70/90 warn/danger 单源）。
+ * - 内容根 = group（透明组合容器）：stats-line（status/turn，无预算时补 token
+ *   绝对值）+ list-tree（criteria 逐行，无 icon——所有行同 icon 是无信息量装饰，
+ *   不编号——criteria 文本常自带 "1. 2." 编号）。
  */
 export function buildGoalGui(state: GoalRuntimeState): GuiRenderResult {
 	const slug = state.slug ?? state.goalId.slice(0, SHORT_ID_LENGTH);
-	// successCriteria 摘要（截断后进 stats-line；与 objective 成对展示）
-	const criteriaSnippet = state.successCriteria
-		? toSingleLine(state.successCriteria).slice(0, OBJECTIVE_DISPLAY_LIMIT)
-		: undefined;
-	// statusSeverity 按 GoalStatus 完整覆盖（S#2）：
-	//   active/complete → ok；blocked → danger；paused → warn；
-	//   budget_limited/cancelled → danger（预算耗尽/取消是错误终态）
+	// statusSeverity 按 GoalStatus 完整覆盖（S#2），stats-line status item 消费
 	const statusSeverity = goalStatusSeverity(state.status);
 
-	// hasBudget 与进度条判定统一口径：用 > 0 而非 truthy（I#1：tokenBudget=0 不应触发 card 容器）
-	const hasBudget = (state.budget.tokenBudget ?? 0) > 0;
+	// hasBudget 与进度判定统一口径：用 > 0 而非 truthy（I#1：tokenBudget=0 不应触发预算展示）
+	const tokenBudget = state.budget.tokenBudget;
+	const hasBudget = (tokenBudget ?? 0) > 0;
 
-	if (hasBudget) {
-		const body: GuiComponent[] = [];
-		// token 进度条（>0 判定，与 hasBudget 口径一致）
-		const tokenBudget = state.budget.tokenBudget;
-		if ((tokenBudget ?? 0) > 0) {
-			const tb = tokenBudget!;
-			const tokenPct = state.tokensUsed / tb;
-			body.push(
-				guiComponent("progress-bar", {
-					label: "tokens",
-					current: state.tokensUsed,
-					total: tb,
-					unit: "tok",
-					// H4：阈值经 getBudgetSeverity 单源化（原内联 percent→severity 三元）
-					severity: getBudgetSeverity(tokenPct),
-				}),
-			);
-		}
-		// 状态 + turn 统计行
-		body.push(
-			guiComponent("stats-line", {
-				items: [
-					{ label: "status", value: state.status, severity: statusSeverity },
-					{ label: "turn", value: String(state.currentTurnIndex) },
-				],
-			}),
-		);
-		// successCriteria 摘要（与 objective 成对，让用户看到「怎么算完成」）
-		if (criteriaSnippet) {
-			body.push(
-				guiComponent("stats-line", {
-					items: [{ label: "done", value: criteriaSnippet }],
-				}),
-			);
-		}
-		return guiResult(
-			guiComponent("card", {
-				variant: state.status === "blocked" ? "danger" : state.status === "complete" ? "success" : "default",
-				header: slug,
-				body,
-			}),
-		);
-	}
+	const children: GuiComponent[] = [];
 
-	// 无 budget：stats-line 摘要
-	return guiResult(
+	// 状态 + turn 统计行；无预算时补 token 绝对值（有预算时 head 进度已表达，不重复）。
+	// token 走 formatTokens（12000 → "12k"），避免浮点原样泄漏到 UI
+	children.push(
 		guiComponent("stats-line", {
 			items: [
-				{ label: "goal", value: slug },
 				{ label: "status", value: state.status, severity: statusSeverity },
 				{ label: "turn", value: String(state.currentTurnIndex) },
-				{ label: "tokens", value: String(state.tokensUsed) },
-				...(criteriaSnippet ? [{ label: "done", value: criteriaSnippet }] : []),
+				...(hasBudget ? [] : [{ label: "tokens", value: formatTokens(state.tokensUsed) }]),
 			],
 		}),
 	);
+
+	// successCriteria 逐行呈现（用户看「怎么算完成」）
+	const criteriaLines = splitCriteriaLines(state.successCriteria);
+	if (criteriaLines.length > 0) {
+		children.push(
+			guiComponent("list-tree", {
+				items: criteriaLines.map((line): TreeItem => ({ label: line, depth: 0 })),
+			}),
+		);
+	}
+
+	const meta: WidgetMeta = {
+		title: slug,
+		status: metaStatus(state.status),
+		...(hasBudget
+			? {
+					progress: {
+						// tokensUsed 是累计加权浮点（如 1454.8400…1），取整后再进 UI
+						current: Math.round(state.tokensUsed),
+						total: tokenBudget!,
+						label: `${Math.round((state.tokensUsed / tokenBudget!) * PERCENT_FACTOR)}%`,
+						severity: getBudgetSeverity(state.tokensUsed / tokenBudget!),
+					},
+				}
+			: {}),
+	};
+
+	return guiResult(guiComponent("group", { children }), meta);
 }

package/src/projection/widget.ts

@@ -28,6 +28,7 @@ import { isTerminalStatus } from "../engine/goal";
 import type { GoalRuntimeState } from "../engine/types";
 import type { UiPort } from "../ports";
 import type { GoalSession } from "../session";
+import { buildGoalGui } from "./gui";
 
 /**
  * projection 层的 Theme 抽象。不 import Pi 的 ThemeColor。
@@ -220,16 +221,22 @@ export { asTheme };
 /**
  * 刷新 widget + status bar。
  *
- * FR-6.6：`uiPort.hasUI === false`（headless / RPC mode）时直接 return，
- * 不调 setWidget / setStatus，避免无 UI 环境崩溃或无意义写入。
+ * FR-6.6：`uiPort.hasUI === false`（headless）时直接 return。
  *
- * 终态折叠为单行 status bar；cancelled / 无 state 时清除 widget + status。
+ * GUI 模式（RPC，uiPort.isGui）：推送 buildGoalGui 的 GuiComponent（guiSetWidget marker
+ * 编码，host 侧解码 → GuiComponentRenderer 渲染）。
+ * TUI 模式：推送 renderWidgetLines 文本行（向后兼容）。
+ *
+ * 终态折叠为单行 status bar（widget 清除）；cancelled/无 state 清除 widget + status。
  */
 export function updateWidget(session: GoalSession, uiPort: UiPort): void {
 	if (!uiPort.hasUI) return;
 
+	const isGui = uiPort.isGui;
+
 	if (!session.state || session.state.status === "cancelled") {
-		uiPort.setWidget("goal", undefined);
+		if (isGui) uiPort.setGuiWidget("goal", undefined);
+		else uiPort.setWidget("goal", undefined);
 		uiPort.setStatus("goal", undefined);
 		return;
 	}
@@ -240,10 +247,16 @@ export function updateWidget(session: GoalSession, uiPort: UiPort): void {
 		if (statusText) {
 			uiPort.setStatus("goal", statusText);
 		}
-		uiPort.setWidget("goal", undefined);
+		if (isGui) uiPort.setGuiWidget("goal", undefined);
+		else uiPort.setWidget("goal", undefined);
 		return;
 	}
 
 	uiPort.setStatus("goal", renderStatusLine(session.state, asTheme(uiPort)));
-	uiPort.setWidget("goal", renderWidgetLines(session.state, asTheme(uiPort)));
+	if (isGui) {
+	// 复用 projection/gui.ts 的 buildGoalGui（整个 GuiRenderResult：component + meta 宿主元数据）
+		uiPort.setGuiWidget("goal", buildGoalGui(session.state));
+	} else {
+		uiPort.setWidget("goal", renderWidgetLines(session.state, asTheme(uiPort)));
+	}
 }