@zhushanwen/pi-ask-user 7.0.16 → 7.1.1

package/ARCHITECTURE.md

@@ -69,14 +69,14 @@ Encoding is **one-way** — the old `parseAnswerParts` text reverse-parsing was
 
 | Step | Check | Returns | Why this order |
 |------|-------|---------|----------------|
-| 1 | `validateInput(questions)` | `isError:true` + fix hint | Pure function, no side effects — cheapest gate. Reject before any UI/state work. |
-| 2 | `!ctx.hasUI` (headless) | `isError:true` + **`setActiveTools` removes ask_user** | Must run before the agent can retry. Physically removing the tool breaks a function-calling retry loop that plain `isError` cannot. |
+| 1 | `validateInput(questions)` | `throw` (Pi marks `isError:true`, empty `details`) + fix hint | Pure function, no side effects — cheapest gate. Reject before any UI/state work. |
+| 2 | `ctx.mode !== "tui" && ctx.mode !== "rpc"` (headless) | `throw` + **`setActiveTools` removes ask_user** | Must run before the agent can retry. Physically removing the tool breaks a function-calling retry loop that a thrown error cannot. |
 | 3 | `signal?.aborted` | `cancelled:true` | O(1) short-circuit before the expensive blocking `ctx.ui.custom` call. |
-| 4 | `try { ctx.ui.custom(...) } catch` | `isError:true` + `{ error }` | `ctx.ui.custom` is the only call that runs user interaction / editor construction / theme reads — the largest blast radius, so it is the only thing wrapped. |
+| 4 | `try { ctx.ui.custom(...) } catch` | `throw` (Pi marks `isError:true`, empty `details`) | `ctx.ui.custom` is the only call that runs user interaction / editor construction / theme reads — the largest blast radius, so it is the only thing wrapped. |
 | 5 | `result === null \|\| result.cancelled` | `cancelled:true` | Component resolved to cancel. |
 | 6 | normal | `{ answers }` | Compose the summary. |
 
-**The order is load-bearing**: swapping 1↔2 wastes a UI check on invalid params; swapping 2↔3 lets an aborted agent enter a blocking UI; moving 4's try/catch wider catches nothing extra. The headless branch's `setActiveTools` is the key insight — returning `isError` alone does not stop an LLM from calling the tool again in the same turn, so the tool is removed from the session's active set and the error text says "do not retry".
+**The order is load-bearing**: swapping 1↔2 wastes a UI check on invalid params; swapping 2↔3 lets an aborted agent enter a blocking UI; moving 4's try/catch wider catches nothing extra. Business outcomes (answers / cancellation) are returned as normal results — only validation failures and unexpected exceptions `throw` (Pi converts a throw into an `isError:true` tool result with empty `details`). The headless branch's `setActiveTools` is the key insight — even an `isError` tool result does not stop an LLM from calling the tool again in the same turn, so the tool is removed from the session's active set and the error text says "do not retry".
 
 ## `QuestionState` machine
 
@@ -122,7 +122,7 @@ If you add a new path that changes the answer set, audit both directions of this
 
 ### `autoConfirmIfAnswered` trigger
 
-Called only from `gotoTab()` — when the user navigates between tabs via Tab/Shift+Tab without pressing Enter. It promotes an implicitly-answered tab (toggled but not confirmed) to `confirmed`. A Tab navigation intent should not force a confirm prompt — only the Enter path confirms via `afterConfirm`.
+Called only from `gotoTab()` — when the user navigates between tabs via `←/→` (Tab is not a tab-navigation key: on the Submit tab it toggles Submit/Cancel focus, and `Shift+Tab` is deliberately unused because Pi's global `app.thinking.cycle` intercepts it). It promotes an implicitly-answered tab (toggled but not confirmed) to `confirmed`. A navigation intent should not force a confirm prompt — only the Enter path confirms via `afterConfirm`.
 
 ## Race guards
 
@@ -132,7 +132,7 @@ Three independent guards protect against three different races. They are dimensi
 |-------|------|----------|----------|-----------|
 | `_resolved` | `boolean` field | `component.ts` | **Double `done()`**: user already submitted/cancelled, then a signal-abort listener or a late keypress fires `done` again → Pi receives two resolves. | `submit()`/`cancel()` set `_resolved = true` before `done(...)`; **both `handleInput` and `cancel()` itself early-return if already set** — so a signal-abort firing after resolution (the listener calls `comp.cancel()`) is a no-op (see `execute` step 4). |
 | `pendingCancel` | `boolean` field | `component.ts` | **Accidental cancel losing answers**: Esc on the first question (or single question) cancelling outright would discard everything. | Two-step confirm: first Esc sets `pendingCancel = true` and shows an overlay; a second Esc truly cancels; any other key exits the overlay and keeps the form. The Submit-tab Cancel button bypasses this (already at the terminus). |
-| `autoConfirmIfAnswered` | **method** (not a field) | `component.ts` | **Zombie unanswered tab**: in multi-question mode, toggling an option then Tab-ing away leaves a tab "answered but not confirmed", so the Submit gate (`allConfirmed()`) stays false and the user cannot tell why Submit is blocked. | `gotoTab()` calls it before switching; if the current state has an answer but `!confirmed`, it sets `confirmed = true`. |
+| `autoConfirmIfAnswered` | **method** (not a field) | `component.ts` | **Zombie unanswered tab**: in multi-question mode, toggling an option then navigating away (`←/→`) leaves a tab "answered but not confirmed", so the Submit gate (`allConfirmed()`) stays false and the user cannot tell why Submit is blocked. | `gotoTab()` calls it before switching; if the current state has an answer but `!confirmed`, it sets `confirmed = true`. |
 
 ## Three-layer rendering
 
@@ -164,7 +164,7 @@ Constants: `SPLIT_PANE_MIN_WIDTH = 84`, `SPLIT_PANE_LEFT_MIN = 32`, `SPLIT_PANE_
 
 ## Spec cross-reference
 
-Design spec: `.xyz-harness/2026-06-15-ask-user/spec.md` (FR = functional requirement, AC = acceptance criterion). Implementation anchors:
+The original spec files (`.xyz-harness/2026-06-15-ask-user/`) are no longer in the repo — this table is self-contained (FR = functional requirement from the original spec). Implementation anchors:
 
 | Spec | Implemented in |
 |------|----------------|

package/README.md

@@ -1,6 +1,6 @@
 # @zhushanwen/pi-ask-user
 
-Inline adaptive `ask_user` tool for the Pi coding agent. Resolves ambiguity the agent cannot resolve itself — a single question (no tab bar) or 1-4 questions (tabbed view + submit), with split-pane option preview on wide terminals, an inline free-text editor, and optional comments.
+Inline adaptive `ask_user` tool for the Pi coding agent. Resolves ambiguity the agent cannot resolve itself — a single question (no tab bar) or 1-4 questions (tabbed view + submit), with split-pane option preview on wide terminals and an inline free-text editor. There is no comment feature: the free-text "Other" editor is the only free-form input.
 
 The tool's primary caller is the LLM. This README covers both **how an agent should use it** (top sections) and **how a maintainer reads the code** (File structure → Design notes).
 
@@ -46,7 +46,6 @@ If you recommend an option, prefix its label with `(Recommended)` and list it fi
       description?: string;  // short rationale shown under the label and in the preview pane
     }>;
     multiSelect?: boolean;   // default false; true only when several options can validly apply
-    allowComment?: boolean;  // default false; lets the user append a free-text note after selecting
   }>
 }  // questions: 1-4 entries
 ```
@@ -61,7 +60,7 @@ If you recommend an option, prefix its label with `(Recommended)` and list it fi
 | `header` | ≤12 chars; required when `questions.length > 1` | `validate.ts` (length + non-empty) |
 | `options[].label` | non-empty, unique within the question | `validate.ts` |
 
-Validation errors are returned as `isError: true` with a message that names the violation and tells you how to fix it — correct the parameters and retry.
+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.)
 
 ## Result format
 
@@ -69,8 +68,7 @@ On success the tool returns the answers joined as `"question" = "answer"` lines.
 
 - **Single-select**: the chosen `label`.
 - **Multi-select**: selected labels joined with `, ` (e.g. `A, B`).
-- **Free-text (Other)**: whatever the user typed.
-- **Comment**: if `allowComment` was set, the user's note is appended after ` — ` (e.g. `Postgres — needs TLS`).
+- **Free-text (Other)**: whatever the user typed (appended to the selection with `, ` when both exist).
 
 A question with no answer reports as `(no answer)`.
 
@@ -78,11 +76,13 @@ A question with no answer reports as `(no answer)`.
 
 | Situation | Return | What the agent should do |
 |-----------|--------|--------------------------|
-| Parameter validation fails | `isError: true` + fix hint | Correct params and retry |
-| No interactive UI (headless) | `isError: true`, tool **disabled for the session** | Proceed with a defensible decision stated in text, or wait for the user — **do not retry** |
+| Parameter validation fails | `throw` (Pi shows it as `isError: true`) + fix hint | Correct params and retry |
+| 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 | `isError: true` + `{ error }` | Retry once with corrected parameters, or proceed with a defensible decision |
+| Unexpected error during interaction | `throw` (Pi shows it as `isError: true`) | Retry once with corrected parameters, or proceed with a defensible decision |
+
+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.
 
@@ -90,11 +90,10 @@ The headless branch physically removes the tool from the session (`setActiveTool
 
 - **Adaptive layout**: single question → no tab bar; 1-4 questions → tabbed view + Submit tab.
 - **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.
-- **Optional comments**: `allowComment: true` → after selecting, the user may append a short note.
+- **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).
-- **Headless-safe**: disables the tool and returns `isError` when no UI is available.
+- **Headless-safe**: disables the tool and throws when no UI is available.
 
 ## File structure
 
@@ -111,7 +110,11 @@ extensions/universal/ask-user/
     ├── validate.ts           # pure parameter validation; error messages aimed at LLM fixability
     ├── component.ts          # AskUserComponent: state machine, input routing, race guards
     ├── question-view.ts      # pure render: option list, split-pane, inline editor
-    └── submit-view.ts        # pure render: Submit tab, answer summary, buildResult
+    ├── submit-view.ts        # pure render: Submit tab, answer summary, buildResult
+    ├── answer-codec.ts       # pure encode: AnswerValue → proto answers entries (protocol boundary)
+    ├── channel-handler.ts    # subagent channel passthru: RPC forward / TUI re-render → proto answers
+    ├── channel-registry-register.ts  # globalThis Symbol slot handshake (handler registration)
+    └── editor-ops.ts         # pure editor ops: insert/delete/cursor/paste (UTF-16 surrogate aware)
 ```
 
 `types.ts` is intentionally the shared dependency leaf — it holds `QuestionState`/`ThemeLike` (not `component.ts`) so the two pure-render views depend only on the leaf, breaking a would-be `component → view → component` cycle. See ARCHITECTURE.md for the full graph.
@@ -130,18 +133,12 @@ All three are consistent and point the same direction. If you tune behavior, edi
 
 - **Why inline, not overlay** (`execute` → `ctx.ui.custom` without `options`): the question belongs in the conversation flow, not a modal that obscures context.
 - **Why `Other` is auto-appended, not in the schema**: free-text input is the user's escape hatch and must not be something the LLM can omit or mislabel. Keeping it out of `options` guarantees it is always present and always last.
-- **Why `←/→` does not switch tabs**: left/right is reserved for the Submit tab's Submit/Cancel focus toggle, so it does not yank focus away while navigating an option list.
+- **Why `←/→` switches tabs but `Tab` does not**: arrow keys move between question tabs (and wrap on the Submit tab), so tab navigation never conflicts with the option-list cursor (`↑/↓`) or text editing. On the Submit tab, `Tab` alone toggles focus between Submit and Cancel — a deliberate single-key bidirectional toggle; `Shift+Tab` is intentionally unused because Pi's global `app.thinking.cycle` intercepts it.
 - **Why validation messages are verbose**: every message names the violation and gives a fix path, because the reader is an LLM that will retry.
 
 ## Spec reference
 
-The original design spec, acceptance criteria (FR-x / AC-x), and E2E test cases live under `.xyz-harness/2026-06-15-ask-user/`:
-
-- `spec.md` — requirements + functional/acceptance criteria
-- `e2e-test-cases.md` — end-to-end scenarios
-- `clarification.md` / `plan.md` — design rationale
-
-Cross-references between these and the implementation are in ARCHITECTURE.md.
+The original design spec (requirements, functional requirements FR-x, acceptance criteria AC-x, E2E test cases) predates this repository — the original spec files are no longer in the repo. The FR cross-reference table in ARCHITECTURE.md is self-contained: each entry names the behavior and where it is implemented in this codebase.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.0.16",
-  "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor and optional comments.",
+  "version": "7.1.1",
+  "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",
   "xyz-agent": {
@@ -29,8 +29,8 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.7.0",
-    "@zhushanwen/pi-extension-logger": "0.3.1"
+    "@xyz-agent/extension-protocol": "0.8.1",
+    "@zhushanwen/pi-extension-logger": "0.4.1"
   },
   "devDependencies": {
     "@earendil-works/pi-tui": "^0.84.4",

package/src/__tests__/component.test.ts

@@ -820,3 +820,35 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 		expect(lines.some((l: string) => l.includes("B"))).toBe(true);
 	});
 });
+
+// ── options 输入路由 no-op 落空语义（←/→ 与 Space 的守卫分支）──
+describe("AskUserComponent — options input no-op edges", () => {
+	it("C-NAV-1: single question ignores LEFT/RIGHT in options mode (no tab nav, no cancel overlay)", () => {
+		const { c, result } = make([singleQ]);
+		// 单问题无 tab：←/→ 应为 no-op（isSingle 短路），既不切 tab 也不进入确认取消覆盖层
+		c.handleInput(LEFT);
+		c.handleInput(RIGHT);
+		expect(result.val).toBeUndefined();
+		// 未进入 Esc 确认取消覆盖层（覆盖层特征文案不出现）
+		expect(c.render(60).some((l) => l.includes("Cancel all"))).toBe(false);
+		// 光标仍在第一项，表单完好
+		const lines = c.render(60);
+		expect(lines.some((l) => l.includes(">") && l.includes("Postgres"))).toBe(true);
+	});
+
+	it("C-NAV-2: multi-select Space on Other row is a no-op (does not toggle, does not enter editor)", () => {
+		const { c, result } = make([singleQMulti]);
+		// 下移到 Other 行（Auth, Search, Other → 光标 index 2）
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		// Other 行上 Space：multiSelect && !onOther 为 false → 落空
+		c.handleInput(" ");
+		// 未确认、未提交
+		expect(result.val).toBeUndefined();
+		const lines = c.render(60);
+		// Other 行未被 toggle（无任何 [✓] 勾选框出现）
+		expect(lines.some((l) => l.includes("[✓]"))).toBe(false);
+		// 仍在 options 模式（未进 freeform 编辑器——反色光标不出现）
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
+	});
+});

package/src/__tests__/e2e.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/e2e.test.ts
 // E2E test cases for ask_user. Drives tool.execute() → real AskUserComponent
 // → simulated keypresses → asserts on final execute() result contract.
-// Spec: .xyz-harness/2026-06-15-ask-user/e2e-test-cases.md
+// （原始 spec 文件已不在仓内——用例自包含，编号 E2E-x 沿用原始 spec 命名）
 
 import { describe, expect, it } from "vitest";
 

package/src/__tests__/index.test.ts

@@ -453,17 +453,8 @@ describe("renderCall / renderResult (FR-9)", () => {
 		expect(renderText(node)).toContain("Cancelled");
 	});
 
-	it("I-19: renderResult error shows ✗ <error>", () => {
-		const tool = getTool();
-		const node = tool.renderResult(
-			{ details: { error: "something broke" } },
-			{ expanded: false },
-			stubTheme,
-		) as unknown as { render(width: number): string[] };
-		const text = renderText(node);
-		expect(text).toContain("✗");
-		expect(text).toContain("something broke");
-	});
+	// （I-19 已随 ErrorDetails 死类型删除：错误路径全部 throw（W4），pi 置 isError 后
+	// details 为空对象，renderResult 不存在 {error} details 分支可渲染）
 
 	// S-3: options.expanded 展开 —— 显示全部选项 + ●/○ 选中标记（spec FR-9）
 	it("I-20: renderResult expanded shows all options with ●/○ marks", () => {

package/src/channel-handler.ts

@@ -13,7 +13,8 @@
 //     （key=header/question，单选=string，多选=JSON 数组，Other→__other），让子进程 decode 一致。
 //
 // handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
-// 由子进程 askUserInteract 编码、subagent-workflow parseChannel 解析 options[0] JSON 得到）。
+// 由子进程 askUserInteract 编码、packages/subagent-core 的 parseChannel（execution/ui-channels.ts）
+// 解析 options[0] JSON 得到）。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -27,20 +28,20 @@ import { encodeAnswer } from "./answer-codec";
 import { type AnswerValue, type Option, type Question, type Result, type ThemeLike } from "./types";
 
 /**
- * channel handler 签名——与 subagent-workflow 的 UiChannelRegistry.ChannelHandler 一致
- *（(req: unknown) => Promise<unknown>）。本文件不静态 import subagent-workflow（它是可选
- * peerDep，未安装时静态 import 会导致整个 ask-user 加载失败）；注册时通过动态 import 拿
- * registry，handler 签名用本地等价类型，运行时结构兼容。
+ * channel handler 签名——与 packages/subagent-core 的 UiChannelRegistry.ChannelHandler 一致
+ *（execution/ui-channels.ts 定义，(req: unknown) => Promise<unknown>）。本文件不静态 import
+ * packages/subagent-core（host 侧包，非本包依赖——两侧扩展经 globalThis slot 握手协作，
+ * 见 index.ts 工厂注释）；handler 签名用本地等价类型，运行时结构兼容。
  */
 export type ChannelHandler = (req: unknown) => Promise<unknown>;
 
-/** handler 返回给 subagent-workflow 的 UiResponse 形状（dialog-queue.ts 定义）。
+/** handler 返回给 packages/subagent-core 的 UiResponse 形状（execution/dialog-queue.ts 定义）。
  *  - {value}: select 的回传值（子进程 JSON.parse(value) 得 answers）
  *  - {cancelled}: 用户取消 / 子进程 close / handler 抛错 */
 type ChannelResponse = { value: string } | { cancelled: true };
 
 /** handler 收到的 req 形状收窄（ChannelHandler 签名是 unknown，按形状 as 收窄）。
- *  channelPayload 由 subagent-workflow parseChannel 填充。 */
+ *  channelPayload 由 packages/subagent-core 的 parseChannel 填充。 */
 interface ChannelRequest {
 	channelPayload?: { questions?: AskUserQuestion[]; allowCancel?: boolean };
 }
@@ -138,7 +139,7 @@ async function runTuiProtoInteraction(
  */
 export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandler {
 	return async (req: unknown): Promise<unknown> => {
-		// req 正常是 subagent-workflow 构造的 UiRequest 对象；防御性收窄 null/undefined/
+		// req 正常是 packages/subagent-core 构造的 UiRequest 对象；防御性收窄 null/undefined/
 		// 非 object（handler 抛错会被 dialog-queue 兜底为 {cancelled:true}，但这里直接返回更干净）
 		if (req === null || typeof req !== "object") {
 			return { cancelled: true } satisfies ChannelResponse;

package/src/channel-registry-register.ts

@@ -3,14 +3,16 @@
 // ask-user 侧的 channel handler 握手注册纯函数。
 //
 // 设计动机（PR #85 #M4 修复）：原实现 ask-user 先 session_start 时会自建简化 Map-based
-// registry 占据 canonical 槽位，劫持 subagent-workflow 后续 getOrCreateChannelRegistry 拿到的
-// 实例（subagent-workflow 的 createUiChannelRegistry 才是 canonical——它带排队、dialog 队列
-// 等完整能力）。修复后的握手协议改为「带 version 的 slot」：
-//   - subagent-workflow session_start 时往 slot 写 {version, registry, pending:[]}
+// registry 占据 canonical 槽位，劫持后续 getOrCreateChannelRegistry 拿到的实例
+// （packages/subagent-core 的 createUiChannelRegistry（execution/ui-channels.ts）才是
+// canonical——它带排队、dialog 队列等完整能力）。修复后的握手协议改为「带 version 的 slot」：
+//   - 承载 subagent-core 的 subagent-workflow 扩展 session_start 时往 slot 写
+//     {version, registry, pending:[]}（registry 由 subagent-core 创建）
 //   - ask-user session_start 时只读 slot，registry 就绪则调 registry.register，未就绪则 push pending
 //   - ask-user **永不**创建 registry 实例，**永不**写 slot.registry
 //
-// 这是 ask-user 侧的注册入口；canonical registry 由 subagent-workflow 创建。本模块永不创建
+// 这是 ask-user 侧的注册入口；canonical registry 由 packages/subagent-core 创建（经
+// channel-registry-access.ts 的 getOrCreateChannelRegistry + flush）。本模块永不创建
 // registry 实例——仅往 slot 写 pending 或调 slot.registry.register。
 
 import type { ChannelHandler } from "./channel-handler";
@@ -21,7 +23,7 @@ const logger = getLogger("ask-user");
 /**
  * 进程级 channel registry 握手的 globalThis key（Symbol.for 跨模块共享）。
  *
- * ⚠️ 必须与 extensions/universal/subagent-workflow/src/execution/channel-registry-access.ts 的字面量
+ * ⚠️ 必须与 packages/subagent-core/src/execution/channel-registry-access.ts 的字面量
  * 完全一致——两边用同一字符串确保拿到同一 slot 实例。改名必须两侧同步。
  */
 export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
@@ -35,9 +37,9 @@ const HANDSHAKE_VERSION = 1;
 const ASK_USER_CHANNEL = "ask_user";
 
 /**
- * channel registry 的本地等价接口（与 subagent-workflow UiChannelRegistry 形状一致）。
- * 本模块不静态 import subagent-workflow（它是可选 peerDep，未安装时静态 import 会致整个
- * ask-user 加载失败）；运行时结构兼容即可。
+ * channel registry 的本地等价接口（与 packages/subagent-core 的 UiChannelRegistry 形状一致，
+ * execution/ui-channels.ts 定义）。本模块不静态 import packages/subagent-core（host 侧包，
+ * 非本包依赖——两侧经 globalThis slot 握手协作）；运行时结构兼容即可。
  */
 interface ChannelRegistry {
 	register(channel: string, handler: ChannelHandler): void;
@@ -45,7 +47,7 @@ interface ChannelRegistry {
 	list(): string[];
 }
 
-/** pending 队列元素：channel + handler。subagent-workflow flush 时遍历调用 registry.register。 */
+/** pending 队列元素：channel + handler。packages/subagent-core flush（channel-registry-access.ts）时遍历调用 registry.register。 */
 interface PendingEntry {
 	channel: string;
 	handler: ChannelHandler;
@@ -55,9 +57,9 @@ interface PendingEntry {
  * globalThis slot 的形状。
  *
  * - `version`：握手协议版本（运行时校验，不兼容则丢弃重建）
- * - `registry`：canonical 实例，**仅 subagent-workflow 创建**；缺失表示 registry 未就绪，
+ * - `registry`：canonical 实例，**仅 packages/subagent-core 创建**；缺失表示 registry 未就绪，
  *   ask-user 把 handler 入 pending 队列等待 flush
- * - `pending`：未消费的注册请求（registry 就绪后由 subagent-workflow 一次性 flush）
+ * - `pending`：未消费的注册请求（registry 就绪后由 packages/subagent-core 一次性 flush）
  */
 export interface ChannelRegistryHandshake {
 	version: 1;
@@ -98,7 +100,7 @@ function ensureSlot(): ChannelRegistryHandshake {
  *   3. slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)
  *
  * 多次调用幂等：registry 就绪时 register 同名覆盖；未就绪时 pending.length 增长
- * （subagent-workflow flush 时一次性消费所有 pending）。
+ * （packages/subagent-core flush 时一次性消费所有 pending）。
  *
  * @param handler ask_user channel handler（createAskUserChannelHandler 产出）
  */

package/src/component.ts

@@ -214,6 +214,7 @@ export class AskUserComponent implements Component {
 	/**
 	 * options 模式的输入处理（从 handleInput 拆出）。
 	 * 含：Esc 回退/确认取消、←/→ 切 tab、↑/↓ 移光标、Enter 确认、Space toggle。
+	 * 主函数只留编排：Esc → tab 导航 → 光标导航 → 确认键，各阶段命中即终止。
 	 */
 	private handleOptionsInput(data: string, state: QuestionState, q: Question): void {
 		// Esc → 回退到上一个问题；在首个问题时进入确认取消覆盖层
@@ -221,59 +222,87 @@ export class AskUserComponent implements Component {
 			this.escBackOrConfirm();
 			return;
 		}
+		if (this.handleTabNavKeys(data)) return;
+		if (this.handleCursorNavKeys(data, state, q)) return;
+		this.handleOptionConfirmKeys(data, state, q);
+	}
 
-		// ← / → 切换问题 tab（多问题，options 模式）
+	/** ← / → 切换问题 tab（多问题，options 模式）。返回 true 表示已消费该按键。 */
+	private handleTabNavKeys(data: string): boolean {
 		if (!this.isSingle && matchesKey(data, "right")) {
 			this.gotoTab(Math.min(this.activeTab + 1, this.questions.length));
-			return;
+			return true;
 		}
 		if (!this.isSingle && matchesKey(data, "left")) {
 			this.gotoTab(Math.max(this.activeTab - 1, 0));
-			return;
+			return true;
 		}
+		return false;
+	}
 
+	/** ↑/↓ 移动选项光标（↓ 受 Other 行下界约束）。返回 true 表示已消费该按键。 */
+	private handleCursorNavKeys(data: string, state: QuestionState, q: Question): boolean {
 		if (matchesKey(data, "up")) {
 			state.cursorIndex = Math.max(0, state.cursorIndex - 1);
 			this.rerender();
-			return;
+			return true;
 		}
 		if (matchesKey(data, "down")) {
 			const max = allOptions(q).length - 1;
 			state.cursorIndex = Math.min(max, state.cursorIndex + 1);
 			this.rerender();
-			return;
+			return true;
 		}
+		return false;
+	}
 
+	/** Other 行 Enter 进编辑器 / 多选 Space toggle + Enter 确认 / 单选 Enter 确认。 */
+	private handleOptionConfirmKeys(data: string, state: QuestionState, q: Question): void {
 		const opts = allOptions(q);
 		const onOther = state.cursorIndex === opts.length - 1;
 
 		// Other row → Enter opens freeform editor
 		if (onOther && matchesKey(data, "enter")) {
-			state.savedOptionsCursorIndex = state.cursorIndex;
-			state.mode = "freeform";
-			state.draftText = state.freeTextValue ?? state.freeDraft ?? "";
-			state.cursorIndex = state.draftText.length;
-			this.rerender();
+			this.openOtherEditor(state);
 			return;
 		}
 
 		if (q.multiSelect && !onOther) {
-			if (matchesKey(data, "space")) {
-				this.toggleIndex(state, state.cursorIndex);
-				return;
-			}
-			if (matchesKey(data, "enter")) {
-				state.selectedIndices.add(state.cursorIndex);
-				this.afterConfirm(state);
-				return;
-			}
+			this.handleMultiSelectConfirmKeys(data, state);
 		} else if (!q.multiSelect && !onOther) {
-			if (matchesKey(data, "enter")) {
-				state.selectedIndex = state.cursorIndex;
-				state.freeTextValue = null;
-				this.afterConfirm(state);
-				return;
-			}
+			this.handleSingleSelectConfirmKeys(data, state);
+		}
+	}
+
+	/** Other 行 Enter：进 freeform 编辑器，预填已提交文本或上一次草稿。 */
+	private openOtherEditor(state: QuestionState): void {
+		state.savedOptionsCursorIndex = state.cursorIndex;
+		state.mode = "freeform";
+		state.draftText = state.freeTextValue ?? state.freeDraft ?? "";
+		state.cursorIndex = state.draftText.length;
+		this.rerender();
+	}
+
+	/** 多选（非 Other 行）：Space toggle；Enter 选中光标项并确认前进。 */
+	private handleMultiSelectConfirmKeys(data: string, state: QuestionState): void {
+		if (matchesKey(data, "space")) {
+			this.toggleIndex(state, state.cursorIndex);
+			return;
+		}
+		if (matchesKey(data, "enter")) {
+			state.selectedIndices.add(state.cursorIndex);
+			this.afterConfirm(state);
+			return;
+		}
+	}
+
+	/** 单选（非 Other 行）：Enter 选中光标项（清 Other 文本）并确认前进。 */
+	private handleSingleSelectConfirmKeys(data: string, state: QuestionState): void {
+		if (matchesKey(data, "enter")) {
+			state.selectedIndex = state.cursorIndex;
+			state.freeTextValue = null;
+			this.afterConfirm(state);
+			return;
 		}
 	}
 

package/src/editor-ops.ts

@@ -10,8 +10,6 @@ import { isHighSurrogate, SURROGATE_PAIR_LEN, type QuestionState } from "./types
 
 // ── 编辑器纯操作 ──
 
-// ── 编辑器纯操作 ──
-
 /** 在光标处插入文本，光标前移 text.length。 */
 export function insertAtCursor(state: QuestionState, text: string): void {
 	state.draftText = state.draftText.slice(0, state.cursorIndex) + text + state.draftText.slice(state.cursorIndex);

package/src/index.ts

@@ -211,15 +211,16 @@ export default function (pi: ExtensionAPI): void {
 	// 注册 ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
 	//
 	// 跨扩展握手协议（PR #85 #M4）：通过 globalThis Symbol.for 约定 slot 形状
-	//（CHANNEL_HANDSHAKE_KEY，与 subagent-workflow/src/execution/channel-registry-access.ts
+	//（CHANNEL_HANDSHAKE_KEY，与 packages/subagent-core/src/execution/channel-registry-access.ts
 	// 用同一字符串 key），不依赖 dynamic import npm 包名（两个扩展都通过
 	// ~/.pi/agent/extensions/ symlink 加载，互相之间无法用 npm 包名 import）。
 	//
 	// 握手流程（registerAskUserChannelHandler 内部完成）：
 	//   1. 读 slot；不存在或 version 不兼容 → 建 slot（仅 pending，**永不建 registry**）
-	//   2. slot.registry 就绪（subagent-workflow 先到）→ 直接调 registry.register
-	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-workflow flush
-	// ask-user 永不创建 registry 实例——canonical registry 仅 subagent-workflow 创建。
+	//   2. slot.registry 就绪（承载 packages/subagent-core 的 subagent-workflow 扩展先到）→ 直接调 registry.register
+	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-core flush
+	// ask-user 永不创建 registry 实例——canonical registry 仅 packages/subagent-core 创建
+	//（execution/ui-channels.ts 的 createUiChannelRegistry）。
 	pi.on("session_start", (_event, ctx) => {
 		registerAskUserChannelHandler(createAskUserChannelHandler(ctx));
 	});
@@ -351,10 +352,8 @@ Don't:
 			theme: ThemeLike,
 		) {
 			const details = result.details;
-			if (details && "error" in details && details.error) {
-				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
-			}
-			// details 现已排除 ErrorDetails 分支，收窄为 Result | undefined
+			// 错误路径已全部改 throw（W4）：pi 置 isError:true 后 details 为空对象，
+			// 不存在 ErrorDetails 形态——这里 details 要么 undefined 要么 Result
 			const d = details as Result | undefined;
 			if (!d || d.cancelled) {
 				return new Text(theme.fg("warning", "Cancelled"), 0, 0);

package/src/question-view.ts

@@ -124,6 +124,7 @@ const EDITOR_HINT = " ←/→ Home/End move · Backspace deletes · Enter submit
 /**
  * 构建选项列表行（不含分屏预览）。hideDescriptions 用于分屏模式左列。
  *  freeform 模式下，Other 行**原地**变 [ ] <input> 反色光标（多选）/ <input> 反色光标（单选）。
+ * 主函数只留逐行编排：Other / 多选 / 单选三类行各自提取为独立 append helper。
  */
 function buildOptionLines(
 	ctx: RenderContext,
@@ -141,68 +142,108 @@ function buildOptionLines(
 		// 编辑器模式下用 savedOptionsCursorIndex 判断选项高亮，cursorIndex 此时是文本光标
 		const activeOptionCursor = state.mode === "freeform" ? state.savedOptionsCursorIndex : state.cursorIndex;
 		const isSelected = i === activeOptionCursor;
-		const isOther = opt.isOther === true;
 		const prefix = isSelected ? t.fg("accent", ">") : " ";
 
-		if (isOther) {
-			// 标记位宽度必须与普通选项一致，否则编号列错位：
-			//   单选 check = 1 列，多选 box = 3 列。
-			//   此前单选 freeform 占位用 "  "(2列)、多选非 freeform 用 check(1列)，
-			//   两种情况下 Other 编号都与普通选项错位。
-			if (state.mode === "freeform") {
-				const marker = q.multiSelect ? t.fg("dim", "[ ]") : " ";
-				const num = i + 1;
-				const lead = `${prefix} ${marker} `;
-				const avail = Math.max(1, width - visibleWidth(lead));
-				// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
-				const cursorText = renderCursorText(state.draftText, state.cursorIndex);
-				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
-				addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
-			} else {
-				const hasFreeText = state.freeTextValue !== null;
-				const marker = q.multiSelect
-					? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
-					: (hasFreeText ? t.fg("success", "✓") : " ");
-				const labelColor = isSelected ? "accent" : "text";
-				const num = i + 1;
-				add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-				if (hasFreeText) {
-					// 预览缩进对齐到 label 起始列：prefix + sp + marker + sp + "N." + sp。
-					// 随 num 位数与单/多选 marker 宽度动态变化，硬编码会错位。
-					const numStr = `${num}.`;
-					const lead = " ".repeat(
-						visibleWidth(prefix) + 1 + visibleWidth(marker) + 1 + numStr.length + 1,
-					);
-					const avail = Math.max(1, width - visibleWidth(lead));
-					const styled = t.fg("dim", `"${state.freeTextValue ?? ""}"`);
-					addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
-				}
-			}
+		if (opt.isOther === true) {
+			appendOtherRow(ctx, opt, i, isSelected, prefix, add);
 		} else if (q.multiSelect) {
-			const checked = state.selectedIndices.has(i);
-			const box = checked ? t.fg("accent", "[✓]") : t.fg("dim", "[ ]");
-			const labelColor = isSelected ? "accent" : "text";
-			const num = i + 1;
-			add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
-				for (const line of wrapped) add(`          ${line}`);
-			}
+			appendMultiSelectRow(ctx, opt, i, isSelected, prefix, hideDescriptions, add);
 		} else {
-			const isConfirmed = state.selectedIndex === i;
-			const check = isConfirmed ? t.fg("success", "✓") : " ";
-			const labelColor = isSelected ? "accent" : "text";
-			const num = i + 1;
-			add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
-				for (const line of wrapped) add(`        ${line}`);
-			}
+			appendSingleSelectRow(ctx, opt, i, isSelected, prefix, hideDescriptions, add);
 		}
 	}
 	return lines;
 }
 
+/** Other 行：freeform 原地编辑器（反色光标）/ 非 freeform 的 ✓ 标记 + 已保存文本预览。 */
+function appendOtherRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	add: (s: string) => void,
+): void {
+	const { question: q, state, theme: t, width } = ctx;
+	const num = index + 1;
+
+	if (state.mode === "freeform") {
+		// 标记位宽度必须与普通选项一致，否则编号列错位：
+		//   单选 check = 1 列，多选 box = 3 列。
+		//   此前单选 freeform 占位用 "  "(2列)、多选非 freeform 用 check(1列)，
+		//   两种情况下 Other 编号都与普通选项错位。
+		const marker = q.multiSelect ? t.fg("dim", "[ ]") : " ";
+		const lead = `${prefix} ${marker} `;
+		const avail = Math.max(1, width - visibleWidth(lead));
+		// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
+		const cursorText = renderCursorText(state.draftText, state.cursorIndex);
+		const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
+		addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+	} else {
+		const hasFreeText = state.freeTextValue !== null;
+		const marker = q.multiSelect
+			? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
+			: (hasFreeText ? t.fg("success", "✓") : " ");
+		const labelColor = isSelected ? "accent" : "text";
+		add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+		if (hasFreeText) {
+			// 预览缩进对齐到 label 起始列：prefix + sp + marker + sp + "N." + sp。
+			// 随 num 位数与单/多选 marker 宽度动态变化，硬编码会错位。
+			const numStr = `${num}.`;
+			const lead = " ".repeat(
+				visibleWidth(prefix) + 1 + visibleWidth(marker) + 1 + numStr.length + 1,
+			);
+			const avail = Math.max(1, width - visibleWidth(lead));
+			const styled = t.fg("dim", `"${state.freeTextValue ?? ""}"`);
+			addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+		}
+	}
+}
+
+/** 多选普通选项行：勾选框 + 编号 label + 缩进描述（hideDescriptions 时省略描述）。 */
+function appendMultiSelectRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	hideDescriptions: boolean,
+	add: (s: string) => void,
+): void {
+	const { state, theme: t, width } = ctx;
+	const checked = state.selectedIndices.has(index);
+	const box = checked ? t.fg("accent", "[✓]") : t.fg("dim", "[ ]");
+	const labelColor = isSelected ? "accent" : "text";
+	const num = index + 1;
+	add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+	if (opt.description && !hideDescriptions) {
+		const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
+		for (const line of wrapped) add(`          ${line}`);
+	}
+}
+
+/** 单选普通选项行：✓ 确认标记 + 编号 label + 缩进描述（hideDescriptions 时省略描述）。 */
+function appendSingleSelectRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	hideDescriptions: boolean,
+	add: (s: string) => void,
+): void {
+	const { state, theme: t, width } = ctx;
+	const isConfirmed = state.selectedIndex === index;
+	const check = isConfirmed ? t.fg("success", "✓") : " ";
+	const labelColor = isSelected ? "accent" : "text";
+	const num = index + 1;
+	add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+	if (opt.description && !hideDescriptions) {
+		const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
+		for (const line of wrapped) add(`        ${line}`);
+	}
+}
+
 /** 构建分屏右侧 Markdown 详情预览。 */
 function buildPreviewLines(
 	ctx: RenderContext,

package/src/types.ts

@@ -109,13 +109,12 @@ export const ResultSchema = Type.Object({
 
 export type Result = Static<typeof ResultSchema>;
 
-/** execute 意外异常时返回的错误 details（区别于 Result.cancelled 的业务取消） */
-export interface ErrorDetails {
-	error: string;
-}
-
-/** execute 返回的 details 联合：正常/取消/校验失败走 Result，意外异常走 ErrorDetails */
-export type AskUserDetails = Result | ErrorDetails;
+/**
+ * execute 返回的 details 形状：正常/取消/校验失败都复用 Result。
+ * 错误路径已全部改为 throw（W4）——pi 对 throw 生成 isError:true 且 details 为空对象，
+ * 不存在「错误 details」形态；曾有的 ErrorDetails 死类型随不可达分支一并删除。
+ */
+export type AskUserDetails = Result;
 
 // ── 跨模块共享的交互状态类型 ─────────────────────────
 // 放这里（而非 component.ts）是为了让 question-view.ts / submit-view.ts

package/src/validate.ts

@@ -22,48 +22,74 @@ const ERROR_PREVIEW_CHARS = 20;
  * - 多问题（questions.length > 1）时每个 question 必须有非空 header
  *
  * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改），对结构误用附 Correct 正例。
+ *
+ * 主函数只留编排：逐 question 依序跑「文本 → 唯一性 → option labels」，再跑
+ * 多问题 header 校验与 header 长度校验。各阶段提取为独立 helper（?? 链按序短路求值，
+ * 与原 early-return 顺序一致）。校验顺序即错误优先级，不可调换。
  */
 export function validateInput(questions: InputQuestion[]): string | null {
 	const seenQuestions = new Set<string>();
 
 	for (const q of questions) {
 		const qt = q.question;
+		const perQuestionError =
+			checkQuestionText(qt) ??
+			checkDuplicateQuestion(qt, seenQuestions) ??
+			checkOptionLabels(qt, q.options);
+		if (perQuestionError) return perQuestionError;
+	}
 
-		// 1a. question 文本长度上限（key 有界）
-		if (qt.length > QUESTION_MAX_CHARS) {
-			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
-		}
-		// 1b. question 文本无控制字符（key 可预测，不影响下游渲染/解析）
-		if (CONTROL_CHAR_RE.test(qt)) {
-			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
-		}
+	return checkMultiQuestionHeaders(questions) ?? checkHeaderLengths(questions);
+}
 
-		// 1c. question 文本唯一
-		if (seenQuestions.has(qt)) {
-			return `Duplicate question: "${qt}". Each question text must be unique; merge duplicates or rephrase one to differ.`;
-		}
-		seenQuestions.add(qt);
+/** 1a. question 文本长度上限（key 有界）；1b. 无控制字符（key 可预测，不影响下游渲染/解析）。 */
+function checkQuestionText(qt: string): string | null {
+	if (qt.length > QUESTION_MAX_CHARS) {
+		return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
+	}
+	if (CONTROL_CHAR_RE.test(qt)) {
+		return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
+	}
+	return null;
+}
 
-		// 2. option 元素必须是 {label, description} 对象，不能是 string。
-		//    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
-		//    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
-		const seenLabels = new Set<string>();
-		for (const opt of q.options) {
-			if (typeof opt === "string") {
-				return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
-			}
-			// opt 已收窄为 Option
-			if (opt.label.trim() === "") {
-				return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
-			}
-			if (seenLabels.has(opt.label)) {
-				return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
-			}
-			seenLabels.add(opt.label);
+/** 1c. question 文本唯一。未重复时登记到 seenQuestions（调用方依赖此副作用）。 */
+function checkDuplicateQuestion(qt: string, seenQuestions: Set<string>): string | null {
+	if (seenQuestions.has(qt)) {
+		return `Duplicate question: "${qt}". Each question text must be unique; merge duplicates or rephrase one to differ.`;
+	}
+	seenQuestions.add(qt);
+	return null;
+}
+
+/**
+ * 2. option 元素必须是 {label, description} 对象，不能是 string。
+ *    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
+ *    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
+ */
+function checkOptionLabels(qt: string, options: InputQuestion["options"]): string | null {
+	const seenLabels = new Set<string>();
+	for (const opt of options) {
+		if (typeof opt === "string") {
+			return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
 		}
+		// opt 已收窄为 Option
+		if (opt.label.trim() === "") {
+			return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
+		}
+		if (seenLabels.has(opt.label)) {
+			return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
+		}
+		seenLabels.add(opt.label);
 	}
+	return null;
+}
 
-	// 3. 多问题时 header 必填且非空
+/**
+ * 3. 多问题时 header 必填且非空；S3: header 唯一——重复 header 会导致 askUserKey 碰撞，
+ * 后一个 question 的 __other 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
+ */
+function checkMultiQuestionHeaders(questions: InputQuestion[]): string | null {
 	if (questions.length > 1) {
 		for (const q of questions) {
 			if (!q.header || q.header.trim() === "") {
@@ -71,8 +97,6 @@ export function validateInput(questions: InputQuestion[]): string | null {
 			}
 		}
 
-		// S3: 多问题时 header 唯一——重复 header 会导致 askUserKey 碰撞，
-		// 后一个 question 的 __other 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
 		const seenHeaders = new Set<string>();
 		for (const q of questions) {
 			const h = q.header!.trim();
@@ -82,14 +106,18 @@ export function validateInput(questions: InputQuestion[]): string | null {
 			seenHeaders.add(h);
 		}
 	}
+	return null;
+}
 
-	// 4. header 长度上限（若提供）。单/多问题均校验：超出会在 tab 栏被静默截断，
-	//    这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
+/**
+ * 4. header 长度上限（若提供）。单/多问题均校验：超出会在 tab 栏被静默截断，
+ * 这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
+ */
+function checkHeaderLengths(questions: InputQuestion[]): string | null {
 	for (const q of questions) {
 		if (q.header !== undefined && q.header.length > HEADER_MAX_CHARS) {
 			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, ERROR_PREVIEW_CHARS)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
 		}
 	}
-
 	return null;
 }