@zhushanwen/pi-ask-user 7.2.3 → 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/README.md

@@ -57,7 +57,7 @@ If you recommend an option, prefix its label with `(Recommended)` and list it fi
 | `questions` | 1-4 entries | schema (`minItems`/`maxItems`) |
 | `options` | 2-4 entries | schema |
 | `question` | ≤1000 chars, no control chars (incl. `\n`), unique within the call | schema description + `validate.ts` |
-| `header` | ≤12 chars; required when `questions.length > 1` | `validate.ts` (length + non-empty) |
+| `header` | ≤12 chars (always); non-empty and unique when `questions.length > 1` | `validate.ts` (length; non-empty + uniqueness in multi-question mode) |
 | `options[].label` | non-empty, unique within the question | `validate.ts` |
 
 Validation failures make the tool `throw` with a message that names the violation and tells you how to fix it — correct the parameters and retry. (Pi converts a thrown error into an `isError: true` tool result; business outcomes like answers and cancellation are returned normally.)
@@ -80,11 +80,12 @@ A question with no answer reports as `(no answer)`.
 | No interactive UI (headless) | `throw`, tool **disabled for the session** | Proceed with a defensible decision stated in text, or wait for the user — **do not retry** |
 | Agent aborted (goal cancelled / context compacted) | `cancelled: true` | The text identifies it as an agent abort, not a user cancel. Do not assume an answer; do not retry ask_user — propagate the abort, or wait for new instructions if the decision is still required. |
 | User cancels (Esc → confirm, or Cancel button) | `cancelled: true` | Wait for new instructions, or re-ask with refined options if the decision is still required |
-| Unexpected error during interaction | `throw` (Pi shows it as `isError: true`) | Retry once with corrected parameters, or proceed with a defensible decision |
+| Unexpected error during interaction (TUI) | `throw` (Pi shows it as `isError: true`) | Tool stays enabled — retry with corrected parameters, or proceed with a defensible decision |
+| Unexpected error during interaction (RPC/GUI) | `throw` + tool **disabled for the session** | Same as the headless row — do not retry |
 
 Business outcomes (answers / cancellation) are returned as normal results; only validation failures and unexpected exceptions `throw` — Pi marks a thrown error `isError: true` with empty `details`.
 
-The headless branch physically removes the tool from the session (`setActiveTools`) — this is deliberate, so a function-calling loop cannot keep retrying `ask_user` in a non-interactive context.
+The headless and RPC-failure branches physically remove the tool from the session (`setActiveTools`) — this is deliberate, so a function-calling loop cannot keep retrying `ask_user` in a non-interactive context. The TUI branch does not disable: an interaction failure there is usually transient, so the tool stays enabled for a retry.
 
 ## Features
 
@@ -92,7 +93,7 @@ The headless branch physically removes the tool from the session (`setActiveTool
 - **Split-pane preview** (≥84 cols): option list left, selected option detail right. The right pane is **plain-text** option detail (label + description), not a Markdown renderer.
 - **Inline free-text editor**: select "Other" → Enter → type a custom answer. Multi-line aware, soft-wrapped. No comment mode — this editor is the only free-form input.
 - **Multi-select**: `multiSelect: true` → toggle checkboxes with Space, Enter to confirm.
-- **Esc confirm-to-cancel**: Esc on the first question opens a confirm overlay (a second Esc cancels; any other key stays).
+- **Esc confirm-to-cancel**: in options mode, Esc on the first question opens a confirm overlay (a second Esc cancels; any other key stays). Elsewhere Esc means back, not cancel: on later question tabs it steps back one tab, on the Submit tab it returns to the last question, and in the Other editor it saves the draft and returns to the option list.
 - **Headless-safe**: disables the tool and throws when no UI is available.
 
 ## File structure
@@ -104,6 +105,7 @@ extensions/universal/ask-user/
 ├── README.md                 # this file — usage contract for LLM callers + overview
 ├── ARCHITECTURE.md           # internals: dependency graph, state machine, defensive flow
 ├── vitest.config.ts
+├── tsconfig.json             # typecheck config (not in the npm files allowlist)
 └── src/
     ├── index.ts              # Tool factory: registerTool + execute (6-step defensive flow) + renderCall/renderResult
     ├── types.ts              # Input schema, Result schema, shared state types (QuestionState/ThemeLike) — dependency leaf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.2.3",
+  "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);