@zhushanwen/pi-goal 0.14.0 → 0.14.2

package/README.md

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

package/package.json

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

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

@@ -36,8 +36,6 @@ function makeFakePorts(): ServicePorts & {
 			setStatus: () => {},
 			notify: (text, level) => { notifications.push({ text, level }); },
 			hasUI: true,
-			isGui: false,
-			setGuiWidget: () => {},
 			theme: {
 				fg: (_color: string, text: string) => text,
 				bold: (text: string) => text,

package/src/__tests__/index.test.ts

@@ -1,27 +1,40 @@
 /**
- * index.ts 测试 — 工厂入口 + 跨扩展 API（pi.__goalInit）
+ * index.ts 测试 — 工厂入口 + 跨扩展 API（goalInit slot）
  *
- * 覆盖 T1.8 (NFR-AC-8)：__goalInit 签名 (objective, budget, ctx, slug?, successCriteria?)，
+ * 覆盖 T1.8 (NFR-AC-8)：goalInit 签名 (objective, budget, ctx, slug?, successCriteria?)，
  * 结构上无法接收 tasks（task CRUD 已删除，D-16/FR-4 双轨消除）。active 守卫由 service.test.ts 覆盖。
  *
- * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再调 pi.__goalInit。
+ * 用最小 fake pi + fake ctx 实例化 goalExtension 工厂，再从 globalThis slot 读取 goalInit——
+ * mock 形态与真实通道同构（goal-bridge-cross-extension.md §3.4：桥的元教训是 mock 世界
+ * 构造「共享 pi 对象」掩盖了真实世界的 per-extension 隔离，两侧测试一律走 slot）。
  */
 import { appendFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
 import { handleSessionStart } from "../adapters/event-handlers/session-start";
-import goalExtension from "../index";
+import goalExtension, { GOAL_INIT_SLOT_KEY, type GoalInitFn } from "../index";
 import { contextInjectionPrompt } from "../projection/prompts";
 import { createGoalSession } from "../session";
 
+/** 每用例后清 slot，防跨用例 globalThis 泄漏（设计 §3.4：teardown 两侧通用） */
+afterEach(() => {
+	Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, undefined);
+});
+
+/** 从 globalThis slot 读取 goalInit（与 plan 侧 compact.ts 的消费形态一致） */
+function readGoalInit(): GoalInitFn | undefined {
+	const fn = Reflect.get(globalThis, GOAL_INIT_SLOT_KEY);
+	return typeof fn === "function" ? (fn as GoalInitFn) : undefined;
+}
+
 // ── Minimal fake pi / ctx ─────────────────────────────
 
 interface FactoryFixture {
-	pi: ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+	pi: ExtensionAPI;
 	ctx: ExtensionContext;
 	states: unknown[];
 	history: unknown[];
@@ -50,7 +63,7 @@ function makeFactoryFixture(): FactoryFixture {
 		sendUserMessage(content: unknown): void {
 			sendUser.push(content);
 		},
-	} as unknown as ExtensionAPI & { __goalInit?: (...args: never[]) => unknown };
+	} as unknown as ExtensionAPI;
 
 	const ctx = {
 		hasUI: true,
@@ -68,18 +81,15 @@ function makeFactoryFixture(): FactoryFixture {
 	return { pi, ctx, states, history, sendUser, commands };
 }
 
-// ── pi.__goalInit（NFR-AC-8 / T1.8）──────────────────
+// ── goalInit slot（NFR-AC-8 / T1.8）──────────────────
 
-describe("pi.__goalInit（NFR-AC-8 / T1.8）", () => {
-	it("工厂实例化后 __goalInit 存在；正常调用 → 创建 goal（返回 true + 持久化 state）", () => {
+describe("goalInit slot（NFR-AC-8 / T1.8）", () => {
+	it("工厂实例化后 slot 内 goalInit 存在；正常调用 → 创建 goal（返回 true + 持久化 state）", () => {
 		const { pi, ctx, states } = makeFactoryFixture();
 		goalExtension(pi);
-		expect(typeof pi.__goalInit).toBe("function");
-		const ok = (pi.__goalInit as (o: string, b: unknown, c: ExtensionContext) => boolean)(
-			"build feature X",
-			undefined,
-			ctx,
-		);
+		const goalInit = readGoalInit();
+		expect(typeof goalInit).toBe("function");
+		const ok = goalInit!("build feature X", undefined, ctx);
 		expect(ok).toBe(true);
 		expect(states).toHaveLength(1); // appendState 调用
 		const persisted = states[0] as { objective?: string };
@@ -90,14 +100,7 @@ describe("pi.__goalInit（NFR-AC-8 / T1.8）", () => {
 		const { pi, ctx, states } = makeFactoryFixture();
 		goalExtension(pi);
 		// GoalInitFn 签名防漂移：successCriteria 为 string[]（数组入参，非旧 string）
-		const init = pi.__goalInit as (
-			o: string,
-			b: unknown,
-			c: ExtensionContext,
-			slug: string,
-			sc: string[],
-		) => boolean;
-		const ok = init("objective", undefined, ctx, "slug", ["cond A", "cond B"]);
+		const ok = readGoalInit()!("objective", undefined, ctx, "slug", ["cond A", "cond B"]);
 		expect(ok).toBe(true);
 		// appendState 持久化的 state 深透传 successCriteria 数组
 		const persisted = states[0] as { slug?: string; successCriteria?: string[] };
@@ -109,7 +112,7 @@ describe("pi.__goalInit（NFR-AC-8 / T1.8）", () => {
 		// FR-4.2/D-16: ctx 必填
 		const { pi } = makeFactoryFixture();
 		goalExtension(pi);
-		const init = pi.__goalInit as (o: string, b: unknown, c: unknown) => boolean;
+		const init = readGoalInit()!;
 		expect(() => init("obj", undefined, undefined)).not.toThrow();
 		expect(init("obj", undefined, undefined)).toBe(false);
 	});

package/src/__tests__/ports.test.ts

@@ -1,14 +1,22 @@
 /**
- * adapters/ports.ts 测试 — UiPort GUI 协议接线（marker 编码集成）。
+ * adapters/ports.ts 测试 — UiPort 双模 widget 接线（setWidgetDual 委托集成）。
  *
- * 验证 buildPorts 构造的 uiPort：
- * - setGuiWidget 经 guiSetWidget 编码 marker 进 ctx.ui.setWidget（RPC 模式）
- * - isGui 反映 ctx.mode（rpc → GUI 渲染通道；tui → 原生文本）
+ * 验证 buildPorts 构造的 uiPort.setWidget（dual payload 签名）：
+ * - rpc 模式：gui 臂经 guiSetWidget 编码 marker 进 ctx.ui.setWidget
+ * - tui 模式：text 臂透传（pi 原生文本行，无 marker）
+ * - undefined：清除语义（模式无关）
+ *
+ * 模式分派守卫单点在 protocol helpers.ts（守卫单点化），本测试只验证委托接线。
  *
  * 运行：cd extensions/universal/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 {
+	GUI_WIDGET_MARKER,
+	guiComponent,
+	guiResult,
+	type DualWidgetContent,
+} from "@xyz-agent/extension-protocol";
 
 import { buildPorts } from "../adapters/ports";
 
@@ -17,7 +25,7 @@ function makePi(): Parameters<typeof buildPorts>[0] {
 	return { appendEntry: () => {} } as unknown as Parameters<typeof buildPorts>[0];
 }
 
-/** mock ctx，捕获 ui.setWidget 收到的 lines（验证 marker 编码）。 */
+/** mock ctx，捕获 ui.setWidget 收到的 lines（验证 marker 编码 / text 透传）。 */
 function makeCtx(opts: { mode?: string; hasUI?: boolean } = {}) {
 	let captured: string[] | undefined = undefined;
 	const ctx = {
@@ -35,43 +43,51 @@ function makeCtx(opts: { mode?: string; hasUI?: boolean } = {}) {
 	return { ctx, getCaptured: () => captured };
 }
 
-describe("buildPorts UiPort.setGuiWidget（marker 编码集成）", () => {
-	it("RPC 模式 setGuiWidget → ctx.ui.setWidget 收到 marker 编码的 string[]", () => {
+function makeDualContent(): DualWidgetContent {
+	return {
+		gui: guiResult(guiComponent("stats-line", { items: [{ value: "x" }] })),
+		text: ["tui line"],
+	};
+}
+
+describe("buildPorts UiPort.setWidget（setWidgetDual 委托）", () => {
+	it("rpc 模式 → ctx.ui.setWidget 收到 gui 臂 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);
+		ports.ui.setWidget("goal", makeDualContent());
 
 		const captured = getCaptured();
 		expect(captured).toBeDefined();
 		expect(captured).toHaveLength(1);
 		// marker 前缀（host 侧 EventAdapter 据此解码成 extension:widgetGui）
 		expect(captured![0].startsWith(GUI_WIDGET_MARKER)).toBe(true);
-		// 解码还原 GuiComponent
+		// 解码还原 GuiRenderResult 信封（TUI text 臂不出现）
 		const json = captured![0].slice(GUI_WIDGET_MARKER.length);
 		const parsed = JSON.parse(json);
-		expect(parsed.type).toBe("stats-line");
+		expect(parsed.v).toBe(1);
+		expect(parsed.component.type).toBe("stats-line");
 	});
 
-	it("setGuiWidget(undefined) → ctx.ui.setWidget 收到 undefined（清除语义）", () => {
-		const { ctx, getCaptured } = makeCtx({ mode: "rpc" });
+	it("tui 模式 → ctx.ui.setWidget 收到 text 臂原生文本行（无 marker 前缀）", () => {
+		const { ctx, getCaptured } = makeCtx({ mode: "tui" });
 		const ports = buildPorts(makePi(), ctx);
 
-		ports.ui.setGuiWidget("goal", undefined);
+		ports.ui.setWidget("goal", makeDualContent());
 
-		expect(getCaptured()).toBeUndefined();
+		const captured = getCaptured();
+		expect(captured).toEqual(["tui line"]);
+		for (const line of captured!) {
+			expect(line.startsWith(GUI_WIDGET_MARKER)).toBe(false);
+		}
 	});
-});
 
-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("setWidget(undefined) → ctx.ui.setWidget 收到 undefined（清除语义，模式无关）", () => {
+		const { ctx, getCaptured } = makeCtx({ mode: "rpc" });
+		const ports = buildPorts(makePi(), ctx);
+
+		ports.ui.setWidget("goal", undefined);
 
-	it("tui 模式 → isGui=false（走原生文本行）", () => {
-		const { ctx } = makeCtx({ mode: "tui" });
-		expect(buildPorts(makePi(), ctx).ui.isGui).toBe(false);
+		expect(getCaptured()).toBeUndefined();
 	});
 });

package/src/adapters/ports.ts

@@ -4,7 +4,7 @@
  * 单一 ports 构造点（DRY）：command-adapter / goal-control-adapter / event-handlers / index 共用。
  *
  * - persistence: pi.appendEntry 映射到 appendState / appendHistory（type 字符串区分）
- * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + isGui + theme（fg/bold 适配 ThemeLike）
+ * - ui: ctx.ui 的 setWidget/setStatus/notify + hasUI + theme（fg/bold 适配 ThemeLike）
  * - messaging: pi.sendMessage 映射到 sendContextMessage / sendUserMessage
  * - session: ctx.sessionManager.getEntries
  *
@@ -13,8 +13,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 { setWidgetDual } from "@xyz-agent/extension-protocol";
+import type { GuiContext } from "@xyz-agent/extension-protocol";
 
 import { ENTRY_TYPE, HISTORY_ENTRY_TYPE } from "../persistence";
 import type { MessagingPort, PersistencePort, SessionPort, UiPort } from "../ports";
@@ -40,24 +40,16 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 	};
 
 	const uiPort: UiPort = {
-		setWidget(name: string, content: string[] | string | undefined): void {
-			// SDK setWidget 重载只接受 string[] | undefined（或 factory）。本地 UiPort 允许单 string，
-			// 此处归一化：string 包一层成 [string]，再透传。
-			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 侧 EventAdapter（xyz-agent runtime 的 pi 事件适配层）检测 marker 解码还原。guiSetWidget 无 isGui 守卫
-			// （helpers.ts 仅查 ctx.ui?.setWidget 存在性），isGui 判定在 updateWidget
-			// 外层（projection/widget.ts）。
+		setWidget(name, content): void {
+			// 双模 payload 委托 protocol setWidgetDual：推送/清屏 × GUI/TUI 的模式分派
+			// 由 helper 单点内化（守卫单点化说明见 extension-protocol helpers.ts），
+			// 本 adapter 不再自持 isGui 判定/守卫注释。
 			//
 			// 断言根因：pi ExtensionUIContext.custom 是泛型方法（返回 Promise<T>），
 			// 与 GuiContext.ui.custom 的具体返回类型静态不兼容，但 mode/hasUI/ui 其余
 			// 成员形状一致（ExtensionMode 与 GuiContext.mode union 完全相同）——
-			// 单层直接断言可过 tsc（guiSetWidget 仅读 ui.setWidget，custom 不参与）。
-			guiSetWidget(ctx as GuiContext, name, result);
+			// 单层直接断言可过 tsc（setWidgetDual 只读 mode 与 ui.setWidget，custom 不参与）。
+			setWidgetDual(ctx as GuiContext, name, content);
 		},
 		setStatus(name: string, text: string | undefined): void {
 			ctx.ui.setStatus(name, text);
@@ -68,11 +60,6 @@ export function buildPorts(pi: ExtensionAPI, ctx: ExtensionContext): ServicePort
 		get hasUI(): boolean {
 			return Boolean(ctx.hasUI);
 		},
-		get isGui(): boolean {
-			// RPC 模式 = GUI 渲染通道有效；TUI/json/print 走 pi 原生渲染。
-			// 断言同 setGuiWidget：custom 泛型签名静态不兼容，mode 单字段运行时可靠。
-			return isGuiCapable(ctx as GuiContext);
-		},
 		// ThemeLike 适配：透传 ctx.ui.theme 的 fg/bold。
 		// Theme.fg 只接受 ThemeColor 字面量 union（SDK 契约）；projection 层保证传入 union 内字面量，
 		// string → ThemeColor 是宽到窄单步断言（无需 unknown 中转）。

package/src/index.ts

@@ -2,7 +2,7 @@
  * Pi /goal Extension — 工厂入口（重构后架构）
  *
  * 注册 command / events，全部委托 adapters 层。
- * __goalInit 内部调 service.createGoal（FR-4.1）。
+ * goalInit slot 内部调 service.createGoal（FR-4.1）。
  *
  * 架构（D-21 双路径 + Ports/Adapters）：
  * - engine/：零 Pi 依赖的纯状态机（goal/budget/types）
@@ -113,25 +113,27 @@ export default function goalExtension(pi: ExtensionAPI) {
 		);
 	}
 
-	// ── External API: __goalInit（FR-4 双轨消除）──────────
+	// ── External API: goalInit slot（FR-4 双轨消除）──────────
 
 	/**
-	 * 允许其他扩展（coding-workflow / plan）通过 pi.__goalInit 编程式初始化 goal。
+	 * 允许其他扩展（plan）通过 goalInit slot 编程式初始化 goal。
 	 * 内部调 service.createGoal（FR-4.1——与 goal_control create 走同一创建逻辑）。
 	 *
 	 * FR-4.2/D-16: ctx 必填（消除 lastCtx 模块级可变状态）。
 	 * ports 构造复用 adapters/ports.buildPorts（DRY：单一 ports 构造点）。
 	 *
+	 * 通道形态（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 用默认值
 	 * @param ctx **必填**——调用方的 ExtensionContext。省略会返回 false（创建失败）。
 	 * @param slug 可选短标识（仅 widget 标题 + history 用，不注入 prompt）
 	 * @returns true 创建成功；false 已有 active goal 或 ctx 缺失
 	 */
-	// 交叉类型单步断言（ExtensionAPI 可赋给 ExtensionAPI & { __goalInit? }，无需 unknown 中转）：
-	// __goalInit 字段获得 GoalInitFn 类型（见下方导出），挂载与消费两侧签名强一致。
-	const api = pi as ExtensionAPI & { __goalInit?: GoalInitFn };
-	api.__goalInit = (
+	const goalInitFn: GoalInitFn = (
 		objective: string,
 		budget: GoalInitBudget | undefined,
 		ctx: ExtensionContext,
@@ -141,14 +143,24 @@ export default function goalExtension(pi: ExtensionAPI) {
 		if (!ctx) return false;
 		return createGoal(session, objective, budget ?? {}, buildPorts(pi, ctx), slug, successCriteria);
 	};
+	Reflect.set(globalThis, GOAL_INIT_SLOT_KEY, goalInitFn);
 }
 
 // ── Cross-extension API 类型（单一 source of truth，API-1）──────────
 
 /**
- * `pi.__goalInit` 的预算配置形状。
+ * goalInit 跨扩展通道的 globalThis slot key（C-ext-06「包名.角色」全限定命名）。
+ *
+ * ⚠️ 必须与 `extensions/universal/plan/src/compact.ts` 的字符串字面量完全一致——
+ * 两侧不共享运行时模块（plan 对 goal 是 optional peer），靠同一字符串拿到同一 slot。
+ * 改名必须两侧同步。
+ */
+export const GOAL_INIT_SLOT_KEY = Symbol.for("@zhushanwen/pi-goal.goalInit");
+
+/**
+ * goalInit slot 的预算配置形状。
  *
- * 跨扩展（coding-workflow / plan）通过 `pi.__goalInit` 编程式初始化 goal 时使用。
+ * 跨扩展（plan）通过 goalInit slot 编程式初始化 goal 时使用。
  * 与 `BudgetConfig` 的差异：本类型只暴露外部可设的可选字段，且全部 optional。
  */
 export interface GoalInitBudget {
@@ -156,12 +168,13 @@ export interface GoalInitBudget {
 }
 
 /**
- * `pi.__goalInit` 的规范函数签名（API-1：单一 source of truth）。
+ * goalInit slot 的规范函数签名（API-1：单一 source of truth）。
  *
  * 跨扩展消费者应 import 本类型而非重复声明 inline alias，避免签名 drift：
  * ```ts
  * import type { GoalInitFn } from "@zhushanwen/pi-goal";
- * const goalInit = (pi as unknown as { __goalInit?: GoalInitFn }).__goalInit;
+ * const fn = Reflect.get(globalThis, Symbol.for("@zhushanwen/pi-goal.goalInit"));
+ * const goalInit = typeof fn === "function" ? (fn as GoalInitFn) : undefined;
  * ```
  *
  * @param objective 目标描述

package/src/ports.ts

@@ -6,8 +6,9 @@
  * adapter 层提供实现（包装 ctx / pi）。
  */
 
+import type { DualWidgetContent } from "@xyz-agent/extension-protocol";
+
 import type { GoalRuntimeState } from "./engine/types";
-import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
 
 // ── GoalHistoryEntry（DTO，非 aggregate，D-09）─────────
 
@@ -49,22 +50,19 @@ export interface ThemeLike {
 // ── UiPort ───────────────────────────────────────────
 
 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 = 清除。
+	 * 设置 widget（双模单调用）。content = { gui, text } 双模 payload / undefined 清除；
+	 * 模式分派（RPC→gui 经 marker 通道 / TUI→text 原生文本行）由 protocol setWidgetDual
+	 * 单点内化（守卫单点化说明见 extension-protocol core/helpers.ts，adapter 委托 helper）。
+	 * hasUI 守卫留在调用方（FR-6.6）。
 	 */
-	setGuiWidget(name: string, result: GuiRenderResult | undefined): void;
+	setWidget(name: string, content: DualWidgetContent | undefined): void;
 	/** 设置 status bar */
 	setStatus(name: string, text: string | undefined): void;
 	/** 弹通知 */
 	notify(text: string, level: "info" | "warning" | "error"): void;
 	/** 是否有 UI（headless 为 false） */
 	readonly hasUI: boolean;
-	/** 是否 GUI 渲染模式（RPC → GuiComponent；TUI → 原生文本行） */
-	readonly isGui: boolean;
 	/** 终端主题能力（fg/bold 着色），widget/status 文本行渲染消费（E3 显式声明） */
 	readonly theme: ThemeLike;
 }

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

@@ -197,37 +197,34 @@ describe("renderWidgetLines", () => {
 	});
 });
 
-// ── updateWidget（FR-6.6 hasUI 守卫）─────────────────
+// ── updateWidget（FR-6.6 hasUI 守卫 + dual payload）──
 
-describe("updateWidget (FR-6.6 hasUI guard)", () => {
-	interface RecordedCall {
-		method: "setWidget" | "setGuiWidget" | "setStatus";
-		args: unknown[];
-	}
-
-	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] });
-			},
-			notify() {},
-			theme: {
-				fg: (_color: string, text: string) => text,
-				bold: (text: string) => text,
-			},
-		} as UiPort;
-		return { ui, calls };
-	}
+interface RecordedCall {
+	method: "setWidget" | "setStatus";
+	args: unknown[];
+}
 
+/** UiPort fake：记录 setWidget/setStatus 调用（setWidget 现为 dual payload 单签名）。 */
+function makeUiPort(hasUI: boolean): { ui: UiPort; calls: RecordedCall[] } {
+	const calls: RecordedCall[] = [];
+	const ui = {
+		hasUI,
+		setWidget(name: string, content: unknown) {
+			calls.push({ method: "setWidget", args: [name, content] });
+		},
+		setStatus(name: string, text: unknown) {
+			calls.push({ method: "setStatus", args: [name, text] });
+		},
+		notify() {},
+		theme: {
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		},
+	} as UiPort;
+	return { ui, calls };
+}
+
+describe("updateWidget (FR-6.6 hasUI guard)", () => {
 	it("hasUI=false → 不调 setWidget/setStatus（headless 守卫）", () => {
 		const { ui, calls } = makeUiPort(false);
 		const session = createGoalSession();
@@ -263,7 +260,7 @@ describe("updateWidget (FR-6.6 hasUI guard)", () => {
 		expect(calls.some((c) => c.method === "setWidget" && c.args[1] === undefined)).toBe(true);
 	});
 
-	it("active → setStatus + setWidget（正常渲染）", () => {
+	it("active → setStatus + setWidget dual payload（text 臂正常渲染）", () => {
 		const { ui, calls } = makeUiPort(true);
 		const session = createGoalSession();
 		session.state = makeState({ status: "active" });
@@ -272,90 +269,41 @@ describe("updateWidget (FR-6.6 hasUI guard)", () => {
 		expect(statusCall!.args[1]).toEqual(expect.stringContaining("◆"));
 		expect(statusCall!.args[1]).toEqual(expect.stringContaining("Turn"));
 		const widgetCall = calls.find((c) => c.method === "setWidget");
-		expect(widgetCall!.args[1]).toEqual(
-			expect.arrayContaining([expect.stringContaining("Token:")]),
-		);
+		const payload = widgetCall!.args[1] as { gui: unknown; text: string[] };
+		expect(payload.text).toEqual(expect.arrayContaining([expect.stringContaining("Token:")]));
 	});
 });
 
-// ── 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() {},
-			theme: {
-				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);
+// ── updateWidget dual payload（gui 臂 = projection/gui.ts buildGoalGui 信封）──
+
+describe("updateWidget dual payload（gui 臂）", () => {
+	it("active + 有预算 → gui 臂 v1.1 信封（group + meta.progress）", () => {
+		const { ui, calls } = makeUiPort(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 } };
+		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 } } };
+			text: string[];
 		};
-		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);
+		// v1.1：gui 臂整个 GuiRenderResult（group 组合根 + meta 宿主元数据，head 由壳层渲染）
+		expect(payload.gui.component.type).toBe("group");
+		expect(payload.gui.meta.progress).toMatchObject({ total: 10000 });
+		// text 臂同步构造（TUI 渲染行）
+		expect(payload.text.length).toBeGreaterThan(0);
 	});
 
-	it("active + isGui 无预算 → setGuiWidget(group，meta 无 progress)", () => {
-		const { ui, calls } = makeGuiUiPort(true, true);
+	it("active 无预算 → gui 臂 meta 无 progress", () => {
+		const { ui, calls } = makeUiPort(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 };
+		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 } };
 		};
-		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);
+		expect(payload.gui.component.type).toBe("group");
+		expect(payload.gui.meta.progress).toBeUndefined();
 	});
 });

package/src/projection/widget.ts

@@ -191,20 +191,16 @@ export function renderWidgetLines(state: GoalRuntimeState, th: ThemeLike): strin
  *
  * FR-6.6：`uiPort.hasUI === false`（headless）时直接 return。
  *
- * GUI 模式（RPC，uiPort.isGui）：推送 buildGoalGui 的 GuiComponent（guiSetWidget marker
- * 编码，host 侧解码 → GuiComponentRenderer 渲染）。
- * TUI 模式：推送 renderWidgetLines 文本行（向后兼容）。
+ * widget 推送为双模单调用：setWidget 收 dual payload（{ gui, text }），
+ * GUI/TUI 模式分派由 adapter 层委托的 protocol setWidgetDual 单点承担。
  *
  * 终态折叠为单行 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") {
-		if (isGui) uiPort.setGuiWidget("goal", undefined);
-		else uiPort.setWidget("goal", undefined);
+		uiPort.setWidget("goal", undefined);
 		uiPort.setStatus("goal", undefined);
 		return;
 	}
@@ -215,16 +211,15 @@ export function updateWidget(session: GoalSession, uiPort: UiPort): void {
 		if (statusText) {
 			uiPort.setStatus("goal", statusText);
 		}
-		if (isGui) uiPort.setGuiWidget("goal", undefined);
-		else uiPort.setWidget("goal", undefined);
+		uiPort.setWidget("goal", undefined);
 		return;
 	}
 
 	uiPort.setStatus("goal", renderStatusLine(session.state, uiPort.theme));
-	if (isGui) {
-	// 复用 projection/gui.ts 的 buildGoalGui（整个 GuiRenderResult：component + meta 宿主元数据）
-		uiPort.setGuiWidget("goal", buildGoalGui(session.state));
-	} else {
-		uiPort.setWidget("goal", renderWidgetLines(session.state, uiPort.theme));
-	}
+	// 双模 payload 按值立即构造（buildGoalGui/renderWidgetLines 均为廉价纯函数）：
+	// gui 臂复用 projection/gui.ts 的 buildGoalGui（GuiRenderResult：component + meta 宿主元数据）
+	uiPort.setWidget("goal", {
+		gui: buildGoalGui(session.state),
+		text: renderWidgetLines(session.state, uiPort.theme),
+	});
 }

package/src/service.ts

@@ -6,7 +6,7 @@
  *
  * D-16: service 不持有 ctx，通过 ports 参数接收能力。
  *
- * FR-3.1: createGoal 唯一创建入口（/goal set 与 __goalInit 都走它）
+ * FR-3.1: createGoal 唯一创建入口（/goal set 与 goalInit slot 都走它）
  * FR-3.3: finalizeAndPersist 唯一终态序列入口（tick → finalizeGoal → persist）
  *         finalizeGoal 只做 transitionStatus + writeHistory（纯）
  * FR-6.5: persist 前调 tick 累计时间
@@ -121,7 +121,7 @@ export function persistAndUpdate(
 /**
  * 唯一创建入口。两个调用源都走它：
  * - goal_control create（toolcall，AI 提供 slug + objective + successCriteria）
- * - __goalInit（index.ts）
+ * - goalInit slot（index.ts，跨扩展编程式入口）
  *
  * 注：/goal <objective> 命令路径已改为提示词触发器——不直接调本函数，
  * 而是 sendUserMessage 让 AI 调 goal_control create（slug + successCriteria 由 AI 生成）。