@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/ui-request-handler-factory.test.ts

@@ -0,0 +1,369 @@
+// src/__tests__/ui-request-handler-factory.test.ts
+//
+// C1 测试：ui-request-handler-factory.ts — createUiRequestHandlerForMode 透传矩阵。
+//
+// 透传矩阵（createUiRequestHandlerForMode 返回的 handler 行为）：
+//   - headless（json/print/undefined）：返回 undefined（不注入 handler）
+//   - TUI：fire-and-forget 回 ack 不透传；dialog 进 dialogQueue 串行
+//   - GUI（rpc）：fire-and-forget 直接调 realHandler；dialog 进 dialogQueue 串行
+// realHandler 路由：channel 命中 → channelHandler（经 coerceUiResponse 形变）；未命中 → defaultDialogForward（dialog 转发结果，fire-and-forget 转发 ctx.ui.* 后回 ack，未知 method warn + ack）。
+// 测接口契约，不测实现细节。
+
+import type { ExtensionContext, ExtensionMode } from "@earendil-works/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+vi.mock("../../core/logger.ts", () => ({
+  getLogger: () => loggerMock,
+}));
+
+import { DialogGlobalQueue, type UiRequest } from "../dialog-queue.ts";
+import { type ChannelHandler,createUiChannelRegistry } from "../ui-channels.ts";
+import { createUiRequestHandlerForMode } from "../ui-request-handler-factory.ts";
+
+// mock ExtensionContext 已补 mode 字段（host-mode.ts 读它分流）。最小形状构造。
+function makeCtx(mode: ExtensionMode): ExtensionContext {
+  return {
+    cwd: "/tmp/test",
+    mode,
+    sessionManager: {
+      getSessionId: () => "s1",
+      getSessionFile: () => undefined,
+      getSessionDir: () => "/tmp/test/sessions",
+    },
+    modelRegistry: undefined,
+    model: undefined,
+  } as ExtensionContext;
+}
+
+/** 带 mock ctx.ui 的 ExtensionContext（GUI fire-and-forget 转发测试用）。
+ *  dialog method（select/confirm/input/editor）返回 undefined/true/"" 兜底，
+ *  fire-and-forget method（notify/setStatus/setWidget/setTitle/setEditorText）是 void spy。 */
+function makeCtxWithUi(mode: ExtensionMode = "rpc"): ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> } {
+  const ui: Record<string, ReturnType<typeof vi.fn>> = {
+    select: vi.fn(async () => undefined),
+    confirm: vi.fn(async () => true),
+    input: vi.fn(async () => ""),
+    editor: vi.fn(async () => ""),
+    notify: vi.fn(),
+    setStatus: vi.fn(),
+    setWidget: vi.fn(),
+    setTitle: vi.fn(),
+    setEditorText: vi.fn(),
+  };
+  return {
+    cwd: "/tmp/test",
+    mode,
+    sessionManager: {
+      getSessionId: () => "s1",
+      getSessionFile: () => undefined,
+      getSessionDir: () => "/tmp/test/sessions",
+    },
+    modelRegistry: undefined,
+    model: undefined,
+    ui,
+  } as unknown as ExtensionContext & { ui: Record<string, ReturnType<typeof vi.fn>> };
+}
+
+function dialogReq(id: string, channel?: string): UiRequest {
+  return { method: "select", id, title: `q-${id}`, ...(channel ? { channel } : {}) };
+}
+
+function fireAndForgetReq(id: string): UiRequest {
+  return { method: "notify", id, message: `n-${id}` };
+}
+
+// dialog 路径用 fake timers 推进 processNext；静默 console.warn/error（stub 故意 warn）。
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  loggerMock.warn.mockClear();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("createUiRequestHandlerForMode — headless 返回 undefined", () => {
+  it("mode='json' → undefined（不注入 handler）", () => {
+    const queue = new DialogGlobalQueue();
+    expect(createUiRequestHandlerForMode(makeCtx("json"), createUiChannelRegistry(), queue))
+      .toBeUndefined();
+  });
+
+  it("mode='print' → undefined", () => {
+    const queue = new DialogGlobalQueue();
+    expect(createUiRequestHandlerForMode(makeCtx("print"), createUiChannelRegistry(), queue))
+      .toBeUndefined();
+  });
+});
+
+describe("createUiRequestHandlerForMode — TUI 模式透传", () => {
+  it("fire-and-forget（notify）→ {ack:true}，不调 realHandler / 不入队", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("tui"), registry, queue)!;
+    const resp = await handler(fireAndForgetReq("f1"));
+
+    expect(resp).toEqual({ ack: true });
+    expect(console.warn).not.toHaveBeenCalled(); // realHandler（defaultDialogForward）未走
+    expect(enqueueSpy).not.toHaveBeenCalled();
+  });
+
+  it("dialog（select 无 channel）→ 进 dialogQueue（enqueue 被调，defaultDialogForward stub cancelled）", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("tui"), registry, queue)!;
+    const pending = handler(dialogReq("d1"));
+
+    expect(enqueueSpy).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(0);
+    await expect(pending).resolves.toEqual({ cancelled: true });
+  });
+});
+
+describe("createUiRequestHandlerForMode — GUI（rpc）模式透传", () => {
+  it("fire-and-forget（notify）→ 直接调 realHandler，不入队", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const ctx = makeCtxWithUi("rpc");
+    const handler = createUiRequestHandlerForMode(ctx, registry, queue)!;
+    // notify 无 channel → realHandler → defaultDialogForward → case "notify" → {ack:true}
+    const resp = await handler(fireAndForgetReq("f1"));
+
+    expect(enqueueSpy).not.toHaveBeenCalled();
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("n-f1", "info");
+  });
+
+  it("dialog（select 无 channel）→ 进 dialogQueue", async () => {
+    const registry = createUiChannelRegistry();
+    const queue = new DialogGlobalQueue();
+    const enqueueSpy = vi.spyOn(queue, "enqueue");
+
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, queue)!;
+    const pending = handler(dialogReq("d1"));
+
+    expect(enqueueSpy).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(0);
+    await expect(pending).resolves.toEqual({ cancelled: true });
+  });
+});
+
+describe("createUiRequestHandlerForMode — channel 业务路由", () => {
+  it("channel 命中 registry → 调注册的 channelHandler（不走 defaultDialogForward）", async () => {
+    const registry = createUiChannelRegistry();
+    const channelHandler: ChannelHandler = vi.fn(async () => ({ value: "from-channel" }));
+    registry.register("ask_user", channelHandler);
+
+    // GUI fire-and-forget 直接调 realHandler，绕过队列；channel 命中立即生效
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, new DialogGlobalQueue())!;
+    const resp = await handler({ method: "notify", id: "f1", message: "m", channel: "ask_user" });
+
+    expect(channelHandler).toHaveBeenCalledTimes(1);
+    expect(resp).toEqual({ value: "from-channel" });
+  });
+
+  it("channel 未命中 → defaultDialogForward（fire-and-forget 走 ack）", async () => {
+    const ctx = makeCtxWithUi("rpc");
+    const handler = createUiRequestHandlerForMode(
+      ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+    const resp = await handler({ method: "notify", id: "f1", message: "m", channel: "unknown" });
+    // notify 是 fire-and-forget，channel miss 后走 defaultDialogForward 的 notify case → ack
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
+  });
+});
+
+// coerceUiResponse 形变（通过 channelHandler 返回不同 shape 间接测）
+describe("createUiRequestHandlerForMode — coerceUiResponse 形变", () => {
+  async function callWithChannel(raw: unknown) {
+    const registry = createUiChannelRegistry();
+    registry.register("ask_user", (async () => raw) as ChannelHandler);
+    const handler = createUiRequestHandlerForMode(makeCtx("rpc"), registry, new DialogGlobalQueue())!;
+    return handler({ method: "notify", id: "f1", message: "m", channel: "ask_user" });
+  }
+
+  it("channelHandler 返回 {value:'x'} → {value:'x'}", async () => {
+    expect(await callWithChannel({ value: "x" })).toEqual({ value: "x" });
+  });
+
+  it("channelHandler 返回 {confirmed:true} → {confirmed:true}", async () => {
+    expect(await callWithChannel({ confirmed: true })).toEqual({ confirmed: true });
+  });
+
+  it("channelHandler 返回 null（非法）→ 降级 {cancelled:true}", async () => {
+    expect(await callWithChannel(null)).toEqual({ cancelled: true });
+  });
+});
+
+// ── P1：GUI fire-and-forget 分类转发（§3.2 映射表 + §3.7 D1/D2） ──
+describe("defaultDialogForward — fire-and-forget 分类转发", () => {
+  function makeHandler(ctx: ExtensionContext) {
+    return createUiRequestHandlerForMode(
+      ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+  }
+
+  // (a) 五个 case 转发调用与 ack 返回
+  it("notify → ctx.ui.notify + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "notify", id: "n1", message: "hello" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.notify).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.notify).toHaveBeenCalledWith("hello", "info");
+  });
+
+  it("setStatus → ctx.ui.setStatus + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "setStatus", id: "s1", statusKey: "progress", statusText: "50%" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setStatus).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setStatus).toHaveBeenCalledWith("progress", "50%");
+  });
+
+  it("setWidget（channel=undefined）→ ctx.ui.setWidget 含 placement + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "my-widget", widgetLines: ["line1", "line2"],
+      widgetPlacement: "belowEditor",
+    });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setWidget).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setWidget).toHaveBeenCalledWith("my-widget", ["line1", "line2"], { placement: "belowEditor" });
+  });
+
+  it("setTitle → ctx.ui.setTitle + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "setTitle", id: "t1", title: "My Title" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setTitle).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setTitle).toHaveBeenCalledWith("My Title");
+  });
+
+  it("set_editor_text → ctx.ui.setEditorText + {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "set_editor_text", id: "e1", text: "some code" });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setEditorText).toHaveBeenCalledTimes(1);
+    expect(ctx.ui.setEditorText).toHaveBeenCalledWith("some code");
+  });
+
+  // (b) notifyType 收窄三档 + 非法值 fallback info
+  it.each([
+    ["info", "info"],
+    ["warning", "warning"],
+    ["error", "error"],
+  ] as const)("notifyType='%s' → 透传 '%s'", async (input, expected) => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m", notifyType: input });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", expected);
+  });
+
+  it("notifyType 非法值 → fallback 'info'", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m", notifyType: "debug" });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
+  });
+
+  it("notifyType undefined → fallback 'info'", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({ method: "notify", id: "n1", message: "m" });
+    expect(ctx.ui.notify).toHaveBeenCalledWith("m", "info");
+  });
+
+  // (c) setWidget 两分支
+  it("setWidget channel='gui_widget' → 不调 ctx.ui.setWidget，回 {ack:true}", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "gui-w", widgetLines: ["\0XYZ_GUI_WIDGET:{...}"],
+      channel: "gui_widget",
+    });
+    expect(resp).toEqual({ ack: true });
+    expect(ctx.ui.setWidget).not.toHaveBeenCalled();
+  });
+
+  it("setWidget channel=undefined → 转发含 placement", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    await handler({
+      method: "setWidget", id: "w1",
+      widgetKey: "k", widgetLines: ["a"],
+      widgetPlacement: "aboveEditor",
+    });
+    expect(ctx.ui.setWidget).toHaveBeenCalledWith("k", ["a"], { placement: "aboveEditor" });
+  });
+
+  // (d) 未知 method warn + ack
+  it("未知 method → logger.warn + {ack:true}（非 cancelled）", async () => {
+    const ctx = makeCtxWithUi();
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "futureMethod", id: "x1" });
+    expect(resp).toEqual({ ack: true });
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("unknown method"),
+      expect.objectContaining({ detail: { method: "futureMethod", id: "x1" } }),
+    );
+  });
+
+  // (e) dialog 既有 case 不回归（select/confirm 代表）
+  it("select 无 channel → 调 ctx.ui.select + 透传 value", async () => {
+    const ctx = makeCtxWithUi();
+    ctx.ui.select.mockResolvedValueOnce("picked");
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "select", id: "d1", title: "Choose", options: ["a", "b"] });
+    expect(resp).toEqual({ value: "picked" });
+    expect(ctx.ui.select).toHaveBeenCalledWith("Choose", ["a", "b"]);
+  });
+
+  it("confirm 无 channel → 调 ctx.ui.confirm + 透传 confirmed", async () => {
+    const ctx = makeCtxWithUi();
+    ctx.ui.confirm.mockResolvedValueOnce(false);
+    const handler = makeHandler(ctx);
+    const resp = await handler({ method: "confirm", id: "d2", title: "Sure?", message: "Go?" });
+    expect(resp).toEqual({ confirmed: false });
+    expect(ctx.ui.confirm).toHaveBeenCalledWith("Sure?", "Go?");
+  });
+});
+
+// ── 确认 createUiRequestHandlerForMode 未改动（TUI 行为零变化） ──
+describe("createUiRequestHandlerForMode — TUI 零回归", () => {
+  it("TUI 下所有 fire-and-forget method 均回 ack 且不调 ctx.ui", async () => {
+    const methods = ["notify", "setStatus", "setWidget", "setTitle", "set_editor_text"];
+    for (const method of methods) {
+      const ctx = makeCtxWithUi("tui");
+      const handler = createUiRequestHandlerForMode(
+        ctx, createUiChannelRegistry(), new DialogGlobalQueue())!;
+      const resp = await handler({ method, id: "t1" });
+      expect(resp).toEqual({ ack: true });
+      // TUI 不透传，ctx.ui 方法不应被调用
+      for (const fn of Object.values(ctx.ui)) {
+        expect(fn).not.toHaveBeenCalled();
+      }
+    }
+  });
+});

package/src/execution/__tests__/ui-request-handler.test.ts

@@ -0,0 +1,204 @@
+// src/__tests__/ui-request-handler.test.ts
+//
+// W2 测试（TC-W2 / SR-2）：UI 请求处理 —— Pi 原生协议格式。
+//
+// 测试对象：session-runner.ts 的 handleUiRequest + spawn-event-adapter.ts 的 parseSpawnLine
+// 契约来源：.fix-plans/00-master-summary.md §二 2.1（ExtensionUiRequest）+ 2.2（UiRequest/channel）
+//          + 2.3（stdin 回写 extension_ui_response 格式）+ §一冲突 2（channel 提取在 session-runner 层）
+//
+// 修复原因（FR-12/SR-2）：
+//   旧测试用错误的 JSON-RPC 2.0 格式 mock（jsonrpc:"2.0" + params.marker:"ASK_USER"
+//   + params.questions），测试绿但生产红（Pi 实际发 {type, method, title, options} 平铺）。
+//   改为 Pi 真实格式 + channel/channelPayload 断言 + extension_ui_response 回写格式。
+//
+// 红灯原因：handleUiRequest 签名仍是旧的 (child, id, params, ctx, signal)
+//   + parseChannel 未接入 session-runner，编译失败。W2 改完签名后转绿。
+
+import { PassThrough } from "node:stream";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { ASK_USER_RPC_PROMPT } from "../session-runner.ts";
+import { parseSpawnLine } from "../spawn-event-adapter.ts";
+import { parseChannel } from "../ui-channels.ts";
+import { createUiRequestQueue, type UiRequest, type UiRequestHandler } from "../ui-request-queue.ts";
+
+// ── Pi 原生协议样本构造 ────────────────────────────────────
+// 真实格式：{type:"extension_ui_request", id, method:"select",
+//           title:"\0XYZ_ASK_USER", options:[JSON.stringify({questions, allowCancel})]}
+// 无 jsonrpc 字段、无 params 包裹、method 在顶层（非 method:"extension_ui_request"）。
+
+const ASK_USER_MARKER = "\0XYZ_ASK_USER";
+const askUserPayload = {
+  questions: [
+    {
+      question: "What is your preference?",
+      options: [{ label: "Option A" }, { label: "Option B" }],
+    },
+  ],
+  allowCancel: true,
+};
+
+function askUserLine(id: string): string {
+  return JSON.stringify({
+    type: "extension_ui_request",
+    id,
+    method: "select",
+    title: ASK_USER_MARKER,
+    options: [JSON.stringify(askUserPayload)],
+  });
+}
+
+// ── 解析：Pi 原生格式 → ExtensionUiRequest（method 平铺，无 params） ─────
+
+describe("parseSpawnLine — ask_user 请求解析（Pi 原生格式）", () => {
+  it("ask_user 行被识别为 extension_ui_request kind", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    expect(result?.kind).toBe("extension_ui_request");
+  });
+
+  it("request.method === 'select'（ask_user 借道 select dialog 通道）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") {
+      expect.fail("expected extension_ui_request kind");
+      return;
+    }
+    expect(result.request.method).toBe("select");
+  });
+
+  it("request.title === ASK_USER_MARKER（NUL 前缀 marker 原样保留，由 parseChannel 提取）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    expect(result.request.title).toBe(ASK_USER_MARKER);
+  });
+
+  it("id 被正确提取（用于 response 关联）", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    expect(result.id).toBe("ui-req-001");
+  });
+});
+
+// ── channel 提取（session-runner 层消费 parseChannel） ──────────────
+// adapter 层只做协议解析（method + 字段平铺），channel 提取在 session-runner 层。
+// 对 select.title 的 NUL 前缀解析出 channel='ask_user' + payload={questions, allowCancel}。
+
+describe("parseChannel — ask_user channel 提取（session-runner 层）", () => {
+  it("select.title 含 ASK_USER_MARKER → channel='ask_user'", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    const channel = parseChannel(result.request);
+    expect(channel.channel).toBe("ask_user");
+  });
+
+  it("channelPayload 已 parse 为 {questions, allowCancel}", () => {
+    const result = parseSpawnLine(askUserLine("ui-req-001"));
+    if (result?.kind !== "extension_ui_request") return;
+    const channel = parseChannel(result.request);
+    expect(channel.channelPayload).toEqual(askUserPayload);
+  });
+});
+
+// ── stdin 回写格式：extension_ui_response（非 JSON-RPC 2.0 result） ─────
+
+describe("handleUiRequest — stdin 回写 extension_ui_response（Pi 原生格式）", () => {
+  it("handler 返回 {value} → stdin 写入 {type:extension_ui_response, id, value}", async () => {
+    const stdin = new PassThrough();
+    const written: string[] = [];
+    stdin.on("data", (chunk: Buffer) => written.push(chunk.toString()));
+
+    const child = { stdin, on: vi.fn(), removeListener: vi.fn() } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[0];
+
+    const handler: UiRequestHandler = vi.fn(
+      async (req: UiRequest) => ({ value: `answer-for-${req.id}` }),
+    );
+    const ctx = { uiRequestHandler: handler } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+
+    const enqueue = createUiRequestQueue(child, ctx);
+    // W2 新签名：enqueue(id, request) —— request 是 ExtensionUiRequest（method 平铺）
+    enqueue("ui-req-002", {
+      method: "select",
+      title: ASK_USER_MARKER,
+      options: [JSON.stringify(askUserPayload)],
+    });
+
+    // 等微任务 + stdin flush
+    await new Promise((r) => setImmediate(r));
+
+    const raw = written.join("");
+    expect(raw).toContain('"type":"extension_ui_response"');
+    expect(raw).toContain('"id":"ui-req-002"');
+    expect(raw).toContain('"value":"answer-for-ui-req-002"');
+    // 旧 JSON-RPC 2.0 格式不应出现
+    expect(raw).not.toContain('"jsonrpc"');
+    expect(raw).not.toContain('"result"');
+  });
+});
+
+// ── handler 抛错兜底（M5）：catch → 回 cancelled → 写 stdin ─────
+// session-runner.ts:489-494 的 catch 分支：handler reject 时兜底写 cancelled。
+
+describe("handleUiRequest — handler 抛错兜底回 cancelled", () => {
+  it("handler reject(new Error('boom')) → stdin 写入 cancelled:true", async () => {
+    const stdin = new PassThrough();
+    const written: string[] = [];
+    stdin.on("data", (chunk: Buffer) => written.push(chunk.toString()));
+
+    const child = { stdin, on: vi.fn(), removeListener: vi.fn() } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[0];
+
+    // handler 抛错（reject）
+    const handler: UiRequestHandler = vi.fn(
+      async () => Promise.reject(new Error("boom")),
+    );
+    const ctx = { uiRequestHandler: handler } as unknown as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+
+    const enqueue = createUiRequestQueue(child, ctx);
+    enqueue("ui-req-err", {
+      method: "select",
+      title: ASK_USER_MARKER,
+      options: [JSON.stringify(askUserPayload)],
+    });
+
+    // 等微任务 + stdin flush
+    await new Promise((r) => setImmediate(r));
+
+    const raw = written.join("");
+    expect(raw).toContain('"type":"extension_ui_response"');
+    expect(raw).toContain('"id":"ui-req-err"');
+    expect(raw).toContain('"cancelled":true');
+  });
+});
+
+// ── W4 提示词（保留，不受格式修复影响） ──────────────────────────
+
+describe("W4: ask_user RPC 系统提示词注入", () => {
+  it("ASK_USER_RPC_PROMPT 常量已导出且非空", () => {
+    expect(ASK_USER_RPC_PROMPT).toBeDefined();
+    expect(typeof ASK_USER_RPC_PROMPT).toBe("string");
+    expect(ASK_USER_RPC_PROMPT.length).toBeGreaterThan(0);
+  });
+
+  it("提示词包含 ask_user 工具说明", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("ask_user");
+    expect(ASK_USER_RPC_PROMPT).toContain("Tool Availability");
+  });
+
+  it("提示词告知 LLM ask_user 走 RPC 转发", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("RPC");
+    expect(ASK_USER_RPC_PROMPT).toContain("main agent");
+    expect(ASK_USER_RPC_PROMPT).toContain("forwarded");
+  });
+
+  it("提示词说明用户在主 agent 界面回答", () => {
+    expect(ASK_USER_RPC_PROMPT).toContain("user");
+    expect(ASK_USER_RPC_PROMPT).toContain("answers");
+  });
+});

package/src/execution/__tests__/ui-request-observability.test.ts

@@ -0,0 +1,113 @@
+// src/__tests__/ui-request-observability.test.ts
+//
+// M4 测试：ui-request-observability.ts — UiRequestObservability 纯逻辑类。
+//
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-request-observability.ts
+// 契约来源：类注释（per-session 去重 + resetMissingHandlerWarnings 清洗 + setMode/getMode 往返）
+//
+// UiRequestObservability 职责：
+//   - setMode/getMode：sessionMode 往返存储
+//   - notifyMissingHandler(sessionId)：per-session 去重，每 session 只 console.warn 一次
+//   - resetMissingHandlerWarnings()：清去重集合，清洗后可重新 warn
+//
+// 纯逻辑无异步，测试最简单。console.warn spy 验证调用次数。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+vi.mock("../../core/logger.ts", () => ({
+  getLogger: () => loggerMock,
+}));
+
+import { UiRequestObservability } from "../ui-request-observability.ts";
+
+// ── 公共 fixture ──────────────────────────────────────────────
+
+beforeEach(() => {
+  loggerMock.warn.mockClear();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("UiRequestObservability — setMode/getMode 往返", () => {
+  it("setMode('tui') → getMode() === 'tui'", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("tui");
+    expect(obs.getMode()).toBe("tui");
+  });
+
+  it("setMode('rpc') → getMode() === 'rpc'", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("rpc");
+    expect(obs.getMode()).toBe("rpc");
+  });
+
+  it("初始 getMode() === undefined（未 set）", () => {
+    const obs = new UiRequestObservability();
+    expect(obs.getMode()).toBeUndefined();
+  });
+
+  it("setMode(undefined) → getMode() === undefined（可重置）", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("json");
+    obs.setMode(undefined);
+    expect(obs.getMode()).toBeUndefined();
+  });
+});
+
+describe("UiRequestObservability — notifyMissingHandler per-session 去重", () => {
+  it("同 sessionId 调两次 → 只 warn 一次", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s1");
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("warn 内容含 sessionId 和 mode（可观测性）", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("tui");
+    obs.notifyMissingHandler("s1");
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("session=s1"),
+    );
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      expect.stringContaining("mode=tui"),
+    );
+  });
+});
+
+describe("UiRequestObservability — resetMissingHandlerWarnings 后可重新 warn", () => {
+  it("notify(s1) → reset → notify(s1) → warn 被调 2 次", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+
+    obs.resetMissingHandlerWarnings();
+
+    obs.notifyMissingHandler("s1");
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("UiRequestObservability — 不同 session 各自首次 warn", () => {
+  it("notify(s1) + notify(s2) → warn 被调 2 次（互不干扰）", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s2");
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+
+    // 再次各自调用，已被去重，不再 warn
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s2");
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+  });
+});