@zhushanwen/pi-ask-user 7.2.4 → 7.3.0

package/ARCHITECTURE.md

@@ -4,7 +4,7 @@
 
 Internals reference for maintainers. For the usage contract (what the tool does, when an agent should call it), see [README.md](./README.md). This document covers how the code is structured, the state machine, the defensive execute flow, and where each design invariant is enforced — so a change does not silently break an invariant.
 
-Source: 10 files in `src/`, ~2085 lines total.
+Source: 11 files in `src/`, ~2265 lines total.
 
 ## File dependency graph
 
@@ -32,21 +32,21 @@ Source: 10 files in `src/`, ~2085 lines total.
        │  race guards        │    │  cursor/paste)     │                 │
        └──────────▲──────────┘    └────────────────────┘                 │
                   │                                                      │
-                  │                 ┌────────────────────┐               │
-                  ├────────────────▶│ channel-handler.ts │◀──────────────┘
-                  │  (AskUserComp.) │ subagent passthru  │
-                  │                 └─────────▲──────────┘
-                  │                           │
-                  │                 ┌─────────┴──────────┐
-                  │                 │channel-registry-   │
-                  │                 │register.ts         │
-                  │                 │globalThis Symbol   │
-                  │                 │handshake           │
-                  │                 └────────────────────┘
-           ┌──────┴───────────┐
-           │     index.ts     │  ← Tool factory + execute (6-step flow) + renderCall/renderResult
+                  │                 ┌────────────────────┐  ┌────────────────┐
+                  ├────────────────▶│ channel-handler.ts │◀─│ form-adapter   │
+                  │  (AskUserComp.) │ subagent passthru  │  │ AskUserQuestion│
+                  │                 └─────────▲──────────┘  │ ↔ FormQuestion │
+                  │                           │             │ normalize (D3)  │
+                  │                 ┌─────────┴──────────┐  └───────▲────────┘
+                  │                 │channel-registry-   │          │
+                  │                 │register.ts         │          │
+                  │                 │globalThis Symbol   │          │
+                  │                 │handshake           │          │
+                  │                 └────────────────────┘          │
+           ┌──────┴───────────┐                                     │
+           │     index.ts     │◀────────────────────────────────────┘
            └──────────────────┘     imports component + validate + types + submit-view +
-                                    channel-handler + channel-registry-register
+                                    channel-handler + channel-registry-register + form-adapter
 ```
 
 **No cycles.** All imports flow one direction; `types.ts` is the single leaf depended on by everyone.
@@ -67,11 +67,11 @@ Encoding is **one-way** — the old `parseAnswerParts` text reverse-parsing was
 
 ## Channel registry handshake (subagent passthrough)
 
-`channel-handler.ts` + `channel-registry-register.ts` implement the subagent passthrough: the host-process ask-user extension registers an `"ask_user"` channel handler through a versioned `globalThis[Symbol.for]` slot handshake (`CHANNEL_HANDSHAKE_KEY`). The skeleton (versioned slot + pending/flush; this side never creates the registry instance) is deliberate and must not be simplified away — the M4 incident (a simplified self-made registry hijacking the canonical slot) is the anchor, see the header comment of `channel-registry-register.ts`. A second consumer of the same handshake *pattern* exists: `extensions/universal/permission/src/footer-provider.ts` (own slot key `FOOTER_HANDSHAKE_KEY`, same versioned-slot shape).
+`channel-handler.ts` + `channel-registry-register.ts` implement the subagent passthrough: the host-process ask-user extension registers one handler under **both channel names** — `ASK_USER_CHANNELS = ["ask_user", "ui_form"]` (`channel-registry-register.ts`; D9 dual-name: new subagents send `ui_form`, legacy npm subagents still send `ask_user`) — through a versioned `globalThis[Symbol.for]` slot handshake (`CHANNEL_HANDSHAKE_KEY`). The skeleton (versioned slot + pending/flush; this side never creates the registry instance) is deliberate and must not be simplified away — the M4 incident (a simplified self-made registry hijacking the canonical slot) is the anchor, see the header comment of `channel-registry-register.ts`. A second consumer of the same handshake *pattern* exists: `extensions/universal/permission/src/footer-provider.ts` (own slot key `FOOTER_HANDSHAKE_KEY`, same versioned-slot shape).
 
 Registry outreach facts (ext-simplify-11, D4):
 
-- **Single registrant on this slot.** The `CHANNEL_HANDSHAKE_KEY` slot currently has exactly one registrant: ask-user (`"ask_user"`). The permission footer-provider handshake above uses its own separate slot — same pattern, different slot, not a registrant here.
+- **Single registrant on this slot.** The `CHANNEL_HANDSHAKE_KEY` slot currently has exactly one registrant: ask-user, registering the same handler on both `"ask_user"` and `"ui_form"` (one handler, two channel names). The permission footer-provider handshake above uses its own separate slot — same pattern, different slot, not a registrant here.
 - **`"gui_widget"` route reserved but vacant.** The engine-sdk ui-channels parsing (`parseChannel`, re-exported via `packages/subagent-core/src/execution/ui-channels.ts`) reserves a `"gui_widget"` channel name, but no package registers a handler for it; the core-side `ui-request-handler-factory` special-cases the unregistered `"gui_widget"` request to `{ack:true}` without forwarding. A future registrant needs no ask-user change — registration is keyed by channel name and orthogonal per extension.
 - **Known gap, accepted (version-mismatch slot overwrite).** On `slot.version !== 1`, `readSlot` discards the slot and `registerAskUserChannelHandler` rebuilds it via `ensureSlot` — if a hypothetical v2 registry ever held the slot, this would drop its reference. Ruled not-worth-fixing (ext-simplify-11 finding 6): both sides pin `HANDSHAKE_VERSION = 1`, so the mismatch path is unreachable today; fixing it would be defensive code for an imagined v2. Re-review trigger: any PR that bumps either side's handshake version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.2.4",
+  "version": "7.3.0",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and an inline free-text editor.",
   "type": "module",
   "main": "index.ts",
@@ -29,7 +29,7 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/extension-protocol": "0.13.0",
     "@zhushanwen/pi-ext-guards": "0.4.1",
     "@zhushanwen/pi-extension-logger": "0.6.1"
   },

package/src/__tests__/channel-handler.test.ts

@@ -2,22 +2,29 @@
 //
 // Tests createAskUserChannelHandler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
 //
+// D9 双 payload mock 轨：孙进程 npm 版本不可控——新孙进程发 {formQuestions: FormQuestion[]}
+// （ui_form channel），旧孙进程发 {questions: AskUserQuestion[]}（ask_user channel）。
+// 核心行为用例全部在两种 payload 形态下各跑一遍（payloadShapes 参数化），断言输出逐字一致。
+//
 // 覆盖：
-//   - RPC 路径（ctx.mode === 'rpc'）：转发器——handler 内部调 askUserInteract（select 通道），
-//     把 proto answers JSON.stringify 成 {value} 返回，子进程 JSON.parse(value) 正确 decode。
+//   - RPC 路径（ctx.mode === 'rpc'）：转发器——handler 内部调 uiFormInteract（select 通道 +
+//     UI_FORM_MARKER），把 proto answers JSON.stringify 成 {value} 返回，子进程 JSON.parse(value)
+//     正确 decode（回包 isFormAnswers 校验通过）。
 //   - TUI 路径（ctx.mode === 'tui'）：handler 走 ctx.ui.custom（mock 成返回预设 Result），
-//     验证内部结构化 Result.answers（AnswerValue）→ proto AskUserAnswers 重新编码
-//     （single/multi/Other 三种答案形态，经 encodeAnswer 序列化）。
-//   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
-//   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
-import type { AskUserQuestion } from "@zhushanwen/extension-protocol";
+//     验证内部结构化 Result.answers（AnswerValue）→ proto answers 重新编码
+//     （single/multi/Other/text 四种答案形态，经 encodeAnswer 序列化）。
+//   - 取消（uiFormInteract 不 ok / custom 返回 null 或 cancelled）→ {cancelled: true}
+//   - 输入校验（channelPayload 缺失 / 双读两键皆空 / formQuestions 全不合法）→ {cancelled: true}
+import type { AskUserQuestion, FormQuestion } from "@zhushanwen/extension-protocol";
 import { describe, expect, it } from "vitest";
 
 import { createAskUserChannelHandler } from "../channel-handler";
 import type { Result } from "../types";
 
 // ── Mock ctx ───────────────────────────────────────────
-// RPC：ctx.ui.select 模拟前端回传的 proto answers（JSON.stringify(AskUserAnswers)）。
+// RPC：ctx.ui.select 模拟前端回传的 proto answers（JSON.stringify(FormAnswers)）。
+// selectEcho = true 时 select 原样回显 options[0]（模拟旧宿主不识别 UI_FORM_MARKER 的
+// band 单选项回显——uiFormInteract echo 检测命中 → channel-error → handler 折叠 cancelled）。
 // TUI：ctx.ui.custom 模拟 AskUserComponent 产出的内部 Result。
 type CtxMode = "tui" | "rpc";
 
@@ -25,6 +32,8 @@ interface MockCtxOpts {
 	mode: CtxMode;
 	/** RPC：select 返回的 value（JSON.stringify 后的 proto answers）；undefined = 取消 */
 	selectResult?: string | undefined;
+	/** RPC：select 原样回显收到的 options[0]（echo 场景） */
+	selectEcho?: boolean;
 	/** TUI：custom 返回的内部 Result；null = 用户取消 */
 	customResult?: Result | null;
 }
@@ -37,14 +46,15 @@ function makeCtx(opts: MockCtxOpts): {
 		custom: <T = void>(factory: unknown) => Promise<T>;
 	};
 } {
-	const { mode, selectResult, customResult } = opts;
+	const { mode, selectResult, selectEcho, customResult } = opts;
 	const hasUI = true;
 	if (mode === "rpc") {
 		return {
 			mode,
 			hasUI,
 			ui: {
-				select: async (): Promise<string | undefined> => selectResult,
+				select: async (_title: string, options: string[]): Promise<string | undefined> =>
+					selectEcho ? options[0] : selectResult,
 				custom: async <T = void>(): Promise<T> => undefined as T,
 			},
 		};
@@ -59,42 +69,75 @@ function makeCtx(opts: MockCtxOpts): {
 	};
 }
 
-// ── 样例 proto questions（handler 收到的格式） ──────────
-const singleProto: AskUserQuestion = {
+// ── 样例问题（legacy AskUserQuestion 与等价 FormQuestion 双形态）──
+const legacySingle: AskUserQuestion = {
+	question: "Which DB?",
+	options: [{ label: "Postgres" }, { label: "SQLite" }],
+};
+const formSingle: FormQuestion = {
+	type: "choice",
 	question: "Which DB?",
 	options: [{ label: "Postgres" }, { label: "SQLite" }],
 };
 
-const multiProto: AskUserQuestion = {
+const legacyMulti: AskUserQuestion = {
 	question: "Which tools?",
 	header: "Tools",
 	multiSelect: true,
 	options: [{ label: "A" }, { label: "B" }, { label: "C" }],
 };
+const formMulti: FormQuestion = {
+	type: "choice",
+	question: "Which tools?",
+	header: "Tools",
+	multi: true,
+	options: [{ label: "A" }, { label: "B" }, { label: "C" }],
+};
+
+/** D9 双 payload 轨：同一问题集的两种 wire 形态（旧 questions / 新 formQuestions） */
+function payloadShapes(
+	legacy: AskUserQuestion[],
+	form: FormQuestion[],
+	allowCancel?: boolean,
+): { label: string; req: unknown }[] {
+	return [
+		{
+			label: "legacy payload {questions}",
+			req: { channelPayload: { questions: legacy, ...(allowCancel !== undefined ? { allowCancel } : {}) } },
+		},
+		{
+			label: "new payload {formQuestions}",
+			req: { channelPayload: { formQuestions: form, ...(allowCancel !== undefined ? { allowCancel } : {}) } },
+		},
+	];
+}
+
+const singleShapes = payloadShapes([legacySingle], [formSingle]);
+const multiShapes = payloadShapes([legacyMulti], [formMulti]);
 
 // ── Tests ───────────────────────────────────────────────
 
-describe("createAskUserChannelHandler", () => {
-	it("RPC: single-select proto answers → {value: JSON.stringify(answers)}", async () => {
+describe("createAskUserChannelHandler — D9 双 payload 轨（两种形态行为逐字一致）", () => {
+	it.each(singleShapes)("RPC single-select: $label → {value: JSON.stringify(answers)}", async ({ req }) => {
 		// 前端回传 proto answers：{[key]: value}，key = question 全文（无 header）
 		const protoAnswers = { "Which DB?": "Postgres" };
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler(req);
 		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
 	});
 
-	it("RPC: multi-select proto answers (JSON array value) → 透传", async () => {
+	it.each(multiShapes)("RPC multi-select: $label → JSON array value 透传", async ({ req }) => {
 		const protoAnswers = { Tools: JSON.stringify(["A", "C"]) };
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		const resp = await handler(req);
 		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
 	});
 
-	it("RPC: Other proto answers → 透传", async () => {
+	it.each(singleShapes)("RPC Other: $label → __other 键透传", async ({ req }) => {
 		const protoAnswers = {
 			"Which DB?": "Postgres",
 			"Which DB?__other": "Custom DB",
@@ -102,19 +145,32 @@ describe("createAskUserChannelHandler", () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler(req);
 		expect(resp).toEqual({ value: JSON.stringify(protoAnswers) });
 	});
 
-	it("RPC: user cancel (select undefined) → {cancelled: true}", async () => {
+	it.each(singleShapes)("RPC user cancel: $label → {cancelled: true}", async ({ req }) => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler(req);
 		expect(resp).toEqual({ cancelled: true });
 	});
 
-	it("TUI: internal Result single-select AnswerValue → 重新编码为 proto answers", async () => {
+	it.each(singleShapes)(
+		"RPC echo（旧宿主回显 payload）: $label → channel-error 折叠 {cancelled: true}",
+		async ({ req }) => {
+			// uiFormInteract echo 检测命中（value === payload）→ channel-error；
+			// 间接链回包形状只有 {value}|{cancelled}，throw 会被 dialog-queue 兜底成同一结果
+			const handler = createAskUserChannelHandler(
+				makeCtx({ mode: "rpc", selectEcho: true }) as never,
+			);
+			const resp = await handler(req);
+			expect(resp).toEqual({ cancelled: true });
+		},
+	);
+
+	it.each(singleShapes)("TUI single-select: $label → 重新编码为 proto answers", async ({ req }) => {
 		// 内部 Result.answers：key = question 全文，value = 结构化 AnswerValue
 		const internalResult: Result = {
 			questions: [],
@@ -124,12 +180,12 @@ describe("createAskUserChannelHandler", () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "tui", customResult: internalResult }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler(req);
 		// 期望：proto answers { "Which DB?": "Postgres" }
 		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
 	});
 
-	it("TUI: multi-select internal Result → proto JSON array value", async () => {
+	it.each(multiShapes)("TUI multi-select: $label → proto JSON array value", async ({ req }) => {
 		const internalResult: Result = {
 			questions: [],
 			answers: { "Which tools?": { selected: ["A", "C"], other: null } },
@@ -138,12 +194,12 @@ describe("createAskUserChannelHandler", () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "tui", customResult: internalResult }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		const resp = await handler(req);
 		// 期望：key=header "Tools"，value = JSON.stringify(["A","C"])
 		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
 	});
 
-	it("TUI: Other free text → ${key}__other", async () => {
+	it.each(singleShapes)("TUI Other free text: $label → ${key}__other", async ({ req }) => {
 		// 内部 Result：selected label + Other 文本分离存储（AnswerValue.other）
 		const internalResult: Result = {
 			questions: [],
@@ -153,13 +209,23 @@ describe("createAskUserChannelHandler", () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "tui", customResult: internalResult }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler(req);
 		expect(resp).toEqual({
 			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__other": "Custom DB" }),
 		});
 	});
 
-	it("TUI: Other-only answer（selected 空）→ 只写 ${key}__other 不写主 key", async () => {
+	it.each(singleShapes)("TUI user cancel: $label → {cancelled: true}", async ({ req }) => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: null }) as never,
+		);
+		const resp = await handler(req);
+		expect(resp).toEqual({ cancelled: true });
+	});
+});
+
+describe("createAskUserChannelHandler — 形态特有用例", () => {
+	it("TUI Other-only answer（selected 空）→ 只写 ${key}__other 不写主 key", async () => {
 		const internalResult: Result = {
 			questions: [],
 			answers: { "Which DB?": { selected: [], other: "custom text" } },
@@ -168,61 +234,101 @@ describe("createAskUserChannelHandler", () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "tui", customResult: internalResult }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler({ channelPayload: { questions: [legacySingle] } });
 		expect(resp).toEqual({
 			value: JSON.stringify({ "Which DB?__other": "custom text" }),
 		});
 	});
 
-	it("TUI: user cancel (custom returns null) → {cancelled: true}", async () => {
+	it("TUI custom returns cancelled Result → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(
-			makeCtx({ mode: "tui", customResult: null }) as never,
+			makeCtx({
+				mode: "tui",
+				customResult: { questions: [], answers: {}, cancelled: true },
+			}) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler({ channelPayload: { questions: [legacySingle] } });
 		expect(resp).toEqual({ cancelled: true });
 	});
 
-	it("TUI: custom returns cancelled Result → {cancelled: true}", async () => {
+	it("TUI text question（新形态）：自由文本答案只写 ${key}__other", async () => {
+		// 旧 payload 无 options 问题 → text；组件渲染为空 options 自由输入，
+		// 答案经 AnswerValue.other 编码为 __other 键（与 FormOverlay text 题键位一致）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Describe the issue": { selected: [], other: "typed free text" } },
+			cancelled: false,
+		};
 		const handler = createAskUserChannelHandler(
-			makeCtx({
-				mode: "tui",
-				customResult: { questions: [], answers: {}, cancelled: true },
-			}) as never,
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({
+			channelPayload: { formQuestions: [{ type: "text", question: "Describe the issue" }] },
+		});
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Describe the issue__other": "typed free text" }),
+		});
+	});
+
+	it("新 payload 逐项守卫：不合法项过滤，合法项照常服务", async () => {
+		const protoAnswers = { "Which DB?": "Postgres" };
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler({
+			channelPayload: {
+				formQuestions: [{ type: "choice", question: 123 }, formSingle, "garbage"],
+			},
+		});
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("新 payload formQuestions 空数组 → ?? 语义生效 → {cancelled: true}（不回落旧键）", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({
+			channelPayload: { formQuestions: [], questions: [legacySingle] },
+		});
 		expect(resp).toEqual({ cancelled: true });
 	});
+});
 
-	it("input: channelPayload missing → {cancelled: true}", async () => {
+describe("createAskUserChannelHandler — input 校验", () => {
+	it("channelPayload missing → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
 		const resp = await handler({});
 		expect(resp).toEqual({ cancelled: true });
 	});
 
-	it("input: questions empty array → {cancelled: true}", async () => {
+	it("questions empty array → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
 		const resp = await handler({ channelPayload: { questions: [] } });
 		expect(resp).toEqual({ cancelled: true });
 	});
 
-	it("input: questions not an array → {cancelled: true}", async () => {
+	it("questions not an array → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
 		const resp = await handler({ channelPayload: { questions: "not-array" } });
 		expect(resp).toEqual({ cancelled: true });
 	});
 
-	it("input: req is null/undefined → {cancelled: true}", async () => {
+	it("formQuestions 全不合法 → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({ channelPayload: { formQuestions: ["nope", 42] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("req is null/undefined → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
 		expect(await handler(null)).toEqual({ cancelled: true });
 		expect(await handler(undefined)).toEqual({ cancelled: true });
 	});
 
-	it("RPC: allowCancel passed through to askUserInteract (default true)", async () => {
+	it("RPC: allowCancel passed through to uiFormInteract (default true)", async () => {
 		// allowCancel 默认 true：验证不抛错（select mock 返回 undefined=取消）
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
 		);
-		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		const resp = await handler({ channelPayload: { questions: [legacySingle] } });
 		expect(resp).toEqual({ cancelled: true });
 	});
 });

package/src/__tests__/channel-registry-register.test.ts

@@ -2,13 +2,15 @@
 //
 // Tests registerAskUserChannelHandler：ask-user 侧的 globalThis Symbol 握手注册纯函数。
 //
-// 覆盖（PR #85 #M4 + #M5）：
-//   - 空 globalThis → 建 slot（仅 pending），handler 入 pending；**slot.registry === undefined**
+// 覆盖（PR #85 #M4 + #M5 + D9 双名注册）：
+//   - 空 globalThis → 建 slot（仅 pending），handler 逐名入 pending；**slot.registry === undefined**
 //     （M4 核心断言：ask-user 永不创建 registry 实例）
 //   - slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）
-//   - slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)，pending 不增长
+//   - slot 存在且 registry 就绪 → 对每个 channel 名调 registry.register(name, handler)，pending 不增长
 //   - 重复调用：registry 就绪时 register 多次（同名覆盖幂等）；未就绪时 pending.length 增长
 //   - version !== 1 → warn + 重建为新 slot，旧 pending 丢弃
+//   - D9：同一 handler 注册两代 channel 名——"ask_user"（旧孙进程 marker 派生）+
+//     "ui_form"（新孙进程 UI_FORM_MARKER 派生），顺序 = ASK_USER_CHANNELS 声明序
 //
 // 隔离：每个用例前 Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY)。
 // Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
@@ -73,8 +75,11 @@ describe("registerAskUserChannelHandler", () => {
 		expect(slot!.version).toBe(1);
 		// M4 核心断言：ask-user 永不创建 registry 实例
 		expect(slot!.registry).toBeUndefined();
-		expect(slot!.pending).toHaveLength(1);
-		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+		// D9 双名：ask_user + ui_form 各一条 pending
+		expect(slot!.pending).toEqual([
+			{ channel: "ask_user", handler: noopHandler },
+			{ channel: "ui_form", handler: noopHandler },
+		]);
 	});
 
 	it("slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）", () => {
@@ -87,11 +92,13 @@ describe("registerAskUserChannelHandler", () => {
 		const slot = readSlot();
 		expect(slot).toBe(preSlot); // 同一对象，未重建
 		expect(slot!.registry).toBeUndefined();
-		expect(slot!.pending).toHaveLength(1);
-		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+		expect(slot!.pending).toEqual([
+			{ channel: "ask_user", handler: noopHandler },
+			{ channel: "ui_form", handler: noopHandler },
+		]);
 	});
 
-	it("slot 存在且 registry 就绪 → 调 registry.register，pending 不增长", () => {
+	it("slot 存在且 registry 就绪 → 逐名调 registry.register，pending 不增长", () => {
 		const mockRegistry = makeMockRegistry();
 		const preSlot: ChannelRegistryHandshake = {
 			version: 1,
@@ -102,8 +109,9 @@ describe("registerAskUserChannelHandler", () => {
 
 		registerAskUserChannelHandler(noopHandler);
 
-		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
-		expect(mockRegistry.register).toHaveBeenCalledWith("ask_user", noopHandler);
+		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(1, "ask_user", noopHandler);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ui_form", noopHandler);
 		// pending 不增长（直接 register，不进队列）
 		expect(preSlot.pending).toHaveLength(0);
 	});
@@ -122,25 +130,30 @@ describe("registerAskUserChannelHandler", () => {
 		registerAskUserChannelHandler(h1);
 		registerAskUserChannelHandler(h2);
 
-		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
+		expect(mockRegistry.register).toHaveBeenCalledTimes(4);
 		expect(mockRegistry.register).toHaveBeenNthCalledWith(1, "ask_user", h1);
-		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ask_user", h2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ui_form", h1);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(3, "ask_user", h2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(4, "ui_form", h2);
 		expect(preSlot.pending).toHaveLength(0); // 幂等：不进 pending
 	});
 
 	it("registry 未就绪时多次 register → pending.length 增长（顺序保留）", () => {
-		// 第 1 次：空 globalThis → 建 slot + pending[0]
+		// 第 1 次：空 globalThis → 建 slot + 双名 pending
 		const h1: ChannelHandler = async () => "a";
 		registerAskUserChannelHandler(h1);
-		// 第 2 次：slot 已存在、registry 仍 undefined → pending[1]
+		// 第 2 次：slot 已存在、registry 仍 undefined → 双名 pending 追加
 		const h2: ChannelHandler = async () => "b";
 		registerAskUserChannelHandler(h2);
 
 		const slot = readSlot();
 		expect(slot!.registry).toBeUndefined();
-		expect(slot!.pending).toHaveLength(2);
-		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: h1 });
-		expect(slot!.pending[1]).toEqual({ channel: "ask_user", handler: h2 });
+		expect(slot!.pending).toEqual([
+			{ channel: "ask_user", handler: h1 },
+			{ channel: "ui_form", handler: h1 },
+			{ channel: "ask_user", handler: h2 },
+			{ channel: "ui_form", handler: h2 },
+		]);
 	});
 
 	it("version !== 1 → warn + 重建为新 slot，旧 pending 丢弃", () => {
@@ -157,10 +170,13 @@ describe("registerAskUserChannelHandler", () => {
 		registerAskUserChannelHandler(noopHandler);
 
 		const slot = readSlot();
-		// 旧 slot 被替换（version 退回 1，pending 重置为仅含本次注册）
+		// 旧 slot 被替换（version 退回 1，pending 重置为仅含本次双名注册）
 		expect(slot).not.toBe(legacySlot);
 		expect(slot!.version).toBe(1);
-		expect(slot!.pending).toEqual([{ channel: "ask_user", handler: noopHandler }]);
+		expect(slot!.pending).toEqual([
+			{ channel: "ask_user", handler: noopHandler },
+			{ channel: "ui_form", handler: noopHandler },
+		]);
 		// warn 被调用（包含 version mismatch 提示）
 		expect(loggerMock.warn).toHaveBeenCalledTimes(1);
 		expect(loggerMock.warn.mock.calls[0]![0]).toContain("version mismatch");
@@ -180,7 +196,7 @@ describe("registerAskUserChannelHandler", () => {
 
 		registerAskUserChannelHandler(noopHandler);
 
-		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
 		// 遗留 pending 未被消费（长度不变）
 		expect(preSlot.pending).toHaveLength(1);
 		expect(preSlot.pending).toBe(preExistingPending);