@zhushanwen/pi-ask-user 0.1.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor, and optional comments.",
   "type": "module",
   "main": "index.ts",
@@ -25,6 +25,9 @@
     "README.md",
     "ARCHITECTURE.md"
   ],
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-tui": "*",
     "@sinclair/typebox": "*",
@@ -34,11 +37,15 @@
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@sinclair/typebox": "*",
+    "@zhushanwen/pi-subagent-workflow": "*"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-tui": {
       "optional": true
+    },
+    "@zhushanwen/pi-subagent-workflow": {
+      "optional": true
     }
   },
   "scripts": {

package/src/__tests__/answer-format.test.ts

@@ -0,0 +1,107 @@
+// src/__tests__/answer-format.test.ts
+//
+// answer-format.ts 独立单元测试。
+// 覆盖审查 S5 发现的覆盖盲区：
+//   - parseAnswerParts 子串误匹配（"A" 不应命中 "AB"）
+//   - formatAnswer 空 parts → null
+//   - comment 分隔符边界
+
+import { describe, expect, it } from "vitest";
+
+import { formatAnswer, parseAnswerParts } from "../answer-format.js";
+import { ANSWER_COMMENT_SEPARATOR } from "../types.js";
+
+describe("formatAnswer", () => {
+	it("returns null for empty parts (unanswered)", () => {
+		expect(formatAnswer([])).toBeNull();
+	});
+
+	it("returns null for empty parts even with comment", () => {
+		// parts 空 = 没有选中选项，即使有 comment 也不应产出有效答案行
+		expect(formatAnswer([], "some comment")).toBeNull();
+	});
+
+	it("joins single part without separator", () => {
+		expect(formatAnswer(["yes"])).toBe("yes");
+	});
+
+	it("joins multiple parts with ', '", () => {
+		expect(formatAnswer(["A", "B", "C"])).toBe("A, B, C");
+	});
+
+	it("appends comment with ANSWER_COMMENT_SEPARATOR", () => {
+		const result = formatAnswer(["A", "B"], "my comment");
+		expect(result).toBe(`A, B${ANSWER_COMMENT_SEPARATOR}my comment`);
+	});
+
+	it("handles null comment (no separator appended)", () => {
+		expect(formatAnswer(["A"], null)).toBe("A");
+	});
+});
+
+describe("parseAnswerParts", () => {
+	it("extracts selected labels by exact match", () => {
+		const labels = ["yes", "no", "maybe"];
+		const result = parseAnswerParts("yes, no", labels);
+		expect(result.selected).toEqual(["yes", "no"]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	// S5 核心：防子串误匹配——"A" 不应命中 label "AB"
+	it("does NOT match substring labels (A vs AB)", () => {
+		const labels = ["A", "AB", "ABC"];
+		// 答案 "A, AB" 应精确匹配两个 label，而非 "A" 匹配三次
+		const result = parseAnswerParts("A, AB", labels);
+		expect(result.selected).toEqual(["A", "AB"]);
+	});
+
+	it("does NOT match 'A' when only 'AB' is in answer", () => {
+		const labels = ["A", "AB"];
+		// 答案 "AB" 只应命中 "AB"，不应命中 "A"
+		const result = parseAnswerParts("AB", labels);
+		expect(result.selected).toEqual(["AB"]);
+	});
+
+	it("preserves order of appearance in answer (not label order)", () => {
+		const labels = ["A", "B", "C"];
+		// 用户选择顺序可能与 options 定义顺序不同
+		const result = parseAnswerParts("C, A", labels);
+		expect(result.selected).toEqual(["C", "A"]);
+	});
+
+	it("extracts comment after ANSWER_COMMENT_SEPARATOR", () => {
+		const labels = ["yes"];
+		const answer = `yes${ANSWER_COMMENT_SEPARATOR}because reasons`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual(["yes"]);
+		expect(result.comment).toBe("because reasons");
+	});
+
+	it("handles full-width comma (，) as separator", () => {
+		const labels = ["A", "B"];
+		const result = parseAnswerParts("A，B", labels);
+		expect(result.selected).toEqual(["A", "B"]);
+	});
+
+	it("returns non-matching tokens as neither selected nor comment (Other free text)", () => {
+		const labels = ["yes", "no"];
+		// "custom text" 不匹配任何 label → 是 Other 自由文本
+		const result = parseAnswerParts("custom text", labels);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	it("handles empty answer string", () => {
+		const result = parseAnswerParts("", ["A", "B"]);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	it("handles answer with only comment (no selected labels)", () => {
+		const labels = ["A"];
+		const answer = `${ANSWER_COMMENT_SEPARATOR}just a comment`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBe("just a comment");
+	});
+});

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

@@ -0,0 +1,286 @@
+// src/__tests__/channel-handler.test.ts
+//
+// Tests createAskUserChannelHandler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
+//
+// 覆盖：
+//   - RPC 路径（ctx.mode === 'rpc'）：转发器——handler 内部调 askUserInteract（select 通道），
+//     把 proto answers JSON.stringify 成 {value} 返回，子进程 JSON.parse(value) 正确 decode。
+//   - TUI 路径（ctx.mode === 'tui'）：handler 走 ctx.ui.custom（mock 成返回预设 Result），
+//     验证内部 Result → proto AskUserAnswers 重新编码（single/multi/Other/comment 四种答案形态）。
+//   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
+//   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
+import type { AskUserQuestion } from "@xyz-agent/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)）。
+// TUI：ctx.ui.custom 模拟 AskUserComponent 产出的内部 Result。
+type CtxMode = "tui" | "rpc";
+
+interface MockCtxOpts {
+	mode: CtxMode;
+	/** RPC：select 返回的 value（JSON.stringify 后的 proto answers）；undefined = 取消 */
+	selectResult?: string | undefined;
+	/** TUI：custom 返回的内部 Result；null = 用户取消 */
+	customResult?: Result | null;
+}
+
+function makeCtx(opts: MockCtxOpts): {
+	mode: CtxMode;
+	hasUI: boolean;
+	ui: {
+		select?: (title: string, options: string[], o?: { signal?: AbortSignal }) => Promise<string | undefined>;
+		custom: <T = void>(factory: unknown) => Promise<T>;
+	};
+} {
+	const { mode, selectResult, customResult } = opts;
+	const hasUI = true;
+	if (mode === "rpc") {
+		return {
+			mode,
+			hasUI,
+			ui: {
+				select: async (): Promise<string | undefined> => selectResult,
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+	}
+	// TUI
+	return {
+		mode,
+		hasUI,
+		ui: {
+			custom: async <T = void>(): Promise<T> => customResult as T,
+		},
+	};
+}
+
+// ── 样例 proto questions（handler 收到的格式） ──────────
+const singleProto: AskUserQuestion = {
+	question: "Which DB?",
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+const multiProto: AskUserQuestion = {
+	question: "Which tools?",
+	header: "Tools",
+	multiSelect: true,
+	options: [
+		{ label: "A", value: "A" },
+		{ label: "B", value: "B" },
+		{ label: "C", value: "C" },
+	],
+};
+
+const commentProto: AskUserQuestion = {
+	question: "Which DB?",
+	allowComment: true,
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+// ── Tests ───────────────────────────────────────────────
+
+describe("createAskUserChannelHandler", () => {
+	it("RPC: single-select proto answers → {value: JSON.stringify(answers)}", async () => {
+		// 前端回传 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] } });
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("RPC: multi-select proto answers (JSON array value) → 透传", async () => {
+		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] } });
+		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
+	});
+
+	it("RPC: Other + comment proto answers → 透传", async () => {
+		const protoAnswers = {
+			"Which DB?": "Postgres",
+			"Which DB?__other": "Custom DB",
+			"Which DB?__comment": "prod constraint",
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({ value: JSON.stringify(protoAnswers) });
+	});
+
+	it("RPC: user cancel (select undefined) → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: internal Result single-select → 重新编码为 proto answers", async () => {
+		// 内部 Result.answers：key = question 全文，value = 选中 label
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		// 期望：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 () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which tools?": "A, C" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		// 期望：key=header "Tools"，value = JSON.stringify(["A","C"])
+		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
+	});
+
+	it("TUI: value≠label single-select → encodeTuiResultToProto 回查 proto option value（PR #85 #8 回归守护）", async () => {
+		// value≠label 是 #8 修复的核心场景：TUI 渲染用 label，但 proto 期望回传 option.value。
+		// 若 #8 修复回归（直接 push label），此测试会失败：返回 "显示名A" 而非 "val_a"。
+		const valueNeqLabelProto: AskUserQuestion = {
+			question: "选哪个?",
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		// 内部 Result.answers：用户在 TUI 选了"显示名A"（label）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪个?": "显示名A" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelProto] } });
+		// 期望：proto answers 回查 value，返回 "val_a"（不是 label "显示名A"）
+		expect(resp).toEqual({ value: JSON.stringify({ "选哪个?": "val_a" }) });
+	});
+
+	it("TUI: value≠label multi-select → proto JSON 数组元素回查 value（PR #85 #8 回归守护）", async () => {
+		// 多选路径同样依赖 #8 修复：selected.push(opt?.value ?? t)，多选会 JSON.stringify 数组。
+		const valueNeqLabelMultiProto: AskUserQuestion = {
+			question: "选哪些?",
+			header: "Opts",
+			multiSelect: true,
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪些?": "显示名A, 显示名B" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelMultiProto] } });
+		// 期望：多选 JSON 数组，每个元素回查 value（["val_a","val_b"]，不是 label）
+		expect(resp).toEqual({ value: JSON.stringify({ Opts: JSON.stringify(["val_a", "val_b"]) }) });
+	});
+
+	it("TUI: Other free text → ${key}__other", async () => {
+		// 内部 Result：selected label + Other 文本逗号拼接（与 getAnswerText 语义一致）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres, Custom DB" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__other": "Custom DB" }),
+		});
+	});
+
+	it("TUI: comment → ${key}__comment", async () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres — prod constraint" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__comment": "prod constraint" }),
+		});
+	});
+
+	it("TUI: user cancel (custom returns null) → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: null }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: custom returns cancelled Result → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({
+				mode: "tui",
+				customResult: { questions: [], answers: {}, cancelled: true },
+			}) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: 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 () => {
+		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 () => {
+		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 () => {
+		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 () => {
+		// allowCancel 默认 true：验证不抛错（select mock 返回 undefined=取消）
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+});

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

@@ -0,0 +1,180 @@
+// src/__tests__/channel-registry-register.test.ts
+//
+// Tests registerAskUserChannelHandler：ask-user 侧的 globalThis Symbol 握手注册纯函数。
+//
+// 覆盖（PR #85 #M4 + #M5）：
+//   - 空 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 不增长
+//   - 重复调用：registry 就绪时 register 多次（同名覆盖幂等）；未就绪时 pending.length 增长
+//   - version !== 1 → warn + 重建为新 slot，旧 pending 丢弃
+//
+// 隔离：每个用例前 Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY)。
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+import type { ChannelHandler } from "../channel-handler";
+import {
+	CHANNEL_HANDSHAKE_KEY,
+	type ChannelRegistryHandshake,
+	registerAskUserChannelHandler,
+} from "../channel-registry-register";
+
+// 拿到当前 slot（cast any 安全：测试控制 slot 写入，结构已知）
+function readSlot(): ChannelRegistryHandshake | undefined {
+	return Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as
+		| ChannelRegistryHandshake
+		| undefined;
+}
+
+/** 塞一个指定 version 的 slot（手动构造，绕过 registerAskUserChannelHandler）。 */
+function writeSlot(slot: ChannelRegistryHandshake): void {
+	Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+}
+
+/** 用 spy 构造 mock registry：register 是 vi.fn，pending flush 时可断言调用。 */
+function makeMockRegistry(): {
+	register: ReturnType<typeof vi.fn>;
+	resolve: ReturnType<typeof vi.fn>;
+	list: ReturnType<typeof vi.fn>;
+} {
+	return {
+		register: vi.fn(),
+		resolve: vi.fn().mockReturnValue(undefined),
+		list: vi.fn().mockReturnValue([]),
+	};
+}
+
+// 占位 handler——测试只关心调用计数和参数，handler 实体不重要
+const noopHandler: ChannelHandler = async () => undefined;
+
+describe("registerAskUserChannelHandler", () => {
+	beforeEach(() => {
+		Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY);
+	});
+
+	it("空 globalThis → 建 slot，handler 入 pending，slot.registry === undefined（M4 核心）", () => {
+		expect(readSlot()).toBeUndefined();
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		expect(slot).toBeDefined();
+		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 });
+	});
+
+	it("slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）", () => {
+		// 预置 slot：version=1，pending=[]，registry 缺失（模拟 subagent-workflow 尚未 session_start）
+		const preSlot: ChannelRegistryHandshake = { version: 1, pending: [] };
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		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 });
+	});
+
+	it("slot 存在且 registry 就绪 → 调 registry.register，pending 不增长", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		expect(mockRegistry.register).toHaveBeenCalledWith("ask_user", noopHandler);
+		// pending 不增长（直接 register，不进队列）
+		expect(preSlot.pending).toHaveLength(0);
+	});
+
+	it("registry 就绪时重复 register → register 被调多次（同名覆盖幂等，pending 始终 0）", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		const h1: ChannelHandler = async () => "a";
+		const h2: ChannelHandler = async () => "b";
+		registerAskUserChannelHandler(h1);
+		registerAskUserChannelHandler(h2);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(1, "ask_user", h1);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ask_user", h2);
+		expect(preSlot.pending).toHaveLength(0); // 幂等：不进 pending
+	});
+
+	it("registry 未就绪时多次 register → pending.length 增长（顺序保留）", () => {
+		// 第 1 次：空 globalThis → 建 slot + pending[0]
+		const h1: ChannelHandler = async () => "a";
+		registerAskUserChannelHandler(h1);
+		// 第 2 次：slot 已存在、registry 仍 undefined → pending[1]
+		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 });
+	});
+
+	it("version !== 1 → warn + 重建为新 slot，旧 pending 丢弃", () => {
+		// 塞一个 version=2 的旧 slot（模拟未来协议升级 / 脏数据）
+		const spyWarn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		const legacyPending = [{ channel: "stale", handler: noopHandler }];
+		const legacySlot = {
+			version: 2 as const,
+			registry: makeMockRegistry() as unknown as ChannelRegistryHandshake["registry"],
+			pending: legacyPending,
+		};
+		writeSlot(legacySlot as unknown as ChannelRegistryHandshake);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		// 旧 slot 被替换（version 退回 1，pending 重置为仅含本次注册）
+		expect(slot).not.toBe(legacySlot);
+		expect(slot!.version).toBe(1);
+		expect(slot!.pending).toEqual([{ channel: "ask_user", handler: noopHandler }]);
+		// warn 被调用（包含 version mismatch 提示）
+		expect(spyWarn).toHaveBeenCalledTimes(1);
+		expect(spyWarn.mock.calls[0]![0]).toContain("version mismatch");
+
+		spyWarn.mockRestore();
+	});
+
+	it("registry 就绪但 slot 已预置 pending → 仍走 register 路径（pending 不被本函数消费）", () => {
+		// 边界：subagent-workflow flush 后理论上 pending 应为空，但若 flush 漏了，
+		// 新 handler 来时仍应直接 register（不消费遗留 pending——那是 subagent-workflow 的职责）。
+		const mockRegistry = makeMockRegistry();
+		const preExistingPending = [{ channel: "ask_user", handler: noopHandler }];
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: preExistingPending,
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		// 遗留 pending 未被消费（长度不变）
+		expect(preSlot.pending).toHaveLength(1);
+		expect(preSlot.pending).toBe(preExistingPending);
+	});
+});

package/src/__tests__/component-keymap.test.ts

@@ -473,37 +473,6 @@ describe("AskUserComponent — unknown control sequence leak fix (C-CSI)", () =>
 		expect(editorLine).toContain("hello");
 		expect(editorLine).not.toContain("[200~");
 	});
-
-	it("C-CSI-R5: arrow keys still no-op", () => {
-		const c = openFreeform([singleQ]);
-		c.handleInput(RIGHT);
-		c.handleInput(RIGHT);
-		c.handleInput(RIGHT);
-		c.handleInput("a");
-		c.handleInput("b");
-		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
-		expect(editorLine).toContain("ab");
-		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
-	});
-
-	it("C-CSI-R6: backspace still works", () => {
-		const c = openFreeform([singleQ]);
-		c.handleInput("abc");
-		c.handleInput(BKSP);
-		const lines = c.render(60);
-		const editorLine = lines.find((l) => l.includes("\x1b[7m"));
-		expect(editorLine).toContain("ab");
-		expect(editorLine).not.toContain("abc");
-	});
-
-	it("C-CSI-R7: Esc still exits editor", () => {
-		const c = openFreeform([singleQ]);
-		c.handleInput("abc");
-		c.handleInput(ESC);
-		const lines = c.render(60);
-		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
-	});
 });
 
 // 🐛 = U+1F41B，UTF-16 surrogate pair（占 2 个 code unit，index 1=高代理 / 2=低代理）。

package/src/__tests__/e2e-harness.ts

@@ -16,6 +16,8 @@ interface PiShape {
 	registerTool(t: unknown): void;
 	getAllTools(): { name: string }[];
 	setActiveTools(names: string[]): void;
+	// session_start handler（factory 注册透传 channel 用）；测试不覆盖透传，空实现。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 export interface E2EApi {
@@ -48,6 +50,9 @@ export function makeE2E(questions: Question[], opts: E2EOptions = {}): E2EApi {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler（透传 channel 注册），测试不覆盖
+		},
 	};
 
 	factory(pi as never);
@@ -72,6 +77,7 @@ export function makeE2E(questions: Question[], opts: E2EOptions = {}): E2EApi {
 		controller.signal,
 		undefined,
 		{
+			mode: hasUI ? "tui" : "print",
 			hasUI,
 			signal: controller.signal,
 			ui: {

package/src/__tests__/e2e.test.ts

@@ -75,9 +75,9 @@ describe("E2E-3: single question + allowComment — Enter in comment skips", ()
 		expect(details.cancelled).toBe(false);
 		// 不含 " — " 分隔符
 		expect(details.answers["Which DB?"]).toBe("Postgres");
-			expect(details.answers["Which DB?"]).not.toContain("—");
-		});
+		expect(details.answers["Which DB?"]).not.toContain("—");
 	});
+});
 
 // ── E2E-4: 多问题提交 — 逐题选择后 Submit tab 提交（S-11）──────
 describe("E2E-4: multi-question submit — answer each then Submit tab", () => {