@blackbelt-technology/pi-agent-dashboard 0.4.0 → 0.4.2

package/packages/extension/src/__tests__/fork-entryid-timing.test.ts

@@ -1,100 +1,88 @@
 /**
- * Tests for fork entryId timing fix.
+ * Tests for bridge entryId stamping on message_end events.
  *
- * Verifies that the bridge's message_end entryId enrichment captures the
- * correct leaf ID (after pi core persists the entry), not the stale one
- * (before appendMessage runs).
+ * HISTORY: Originally this file modelled pi <0.69's synchronous emit pattern,
+ * where the bridge's `queueMicrotask` deferral ran BEFORE
+ * sessionManager.appendMessage. That design no longer reflects pi 0.70.x:
+ * pi awaits extension handlers inside _emitExtensionEvent, so the microtask
+ * resolves *inside* the awaited dispatcher, before persistence. The fix
+ * (see change: fix-per-message-fork) is `setTimeout(0)` (a macrotask)
+ * combined with reading `event.message.id` (which pi mutates in place
+ * during appendMessage) or a WeakMap populated by the wrapped appendMessage.
  *
- * The bug: pi core emits message_end via _emit() BEFORE calling
- * sessionManager.appendMessage(), so getLeafId() returns the previous leaf.
- * The fix: the bridge defers getLeafId() for message_end using queueMicrotask,
- * allowing appendMessage to run first.
+ * The previous test "message_start should still capture entryId immediately
+ * (no deferral)" codified the off-by-one bug as expected behavior — it has
+ * been REMOVED. The current test suite below models pi 0.70.x semantics
+ * directly. Detailed pi-0.70-specific scenarios live in
+ * `bridge-entry-id-pi-070.test.ts`.
  */
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect } from "vitest";
 
-/**
- * Simulates the pi core + bridge interaction for entryId enrichment.
- *
- * Pi core's _processAgentEvent does:
- *   1. _emit(event)          — bridge handler called (async, not awaited)
- *   2. appendMessage(msg)    — updates leafId synchronously
- *
- * The bridge handler (async) should yield via queueMicrotask before reading
- * getLeafId(), so that appendMessage has already run.
- */
-describe("message_end entryId timing", () => {
-  it("deferred getLeafId() captures the post-persist entry ID", async () => {
-    // Simulate sessionManager with mutable leafId
-    let leafId = "user-entry-100"; // stale leaf before appendMessage
+describe("message_end entryId timing on pi 0.70.x", () => {
+  it("setTimeout(0) deferral captures the post-persist entry ID", async () => {
+    // Simulate pi 0.70.x: bridge handler runs awaited, THEN appendMessage runs.
+    let leafId = "user-entry-100";
     const sessionManager = {
       getLeafId: () => leafId,
+      appendMessage: (msg: any) => {
+        msg.id = "assistant-entry-101";
+        leafId = msg.id;
+        return msg.id;
+      },
     };
 
-    let capturedEntryId: string | undefined;
-
-    // Simulate the bridge handler (with the fix: defers via queueMicrotask)
-    const bridgeHandler = async () => {
-      // This is what the fixed bridge does for message_end:
-      await new Promise<void>(resolve => queueMicrotask(resolve));
-      capturedEntryId = sessionManager.getLeafId();
+    const event = { type: "message_end", message: { role: "assistant" } as any };
+    let captured: string | undefined;
+    let sendDone!: () => void;
+    const sentP = new Promise<void>((r) => { sendDone = r; });
+
+    // Bridge handler: schedules a setTimeout(0) and returns synchronously.
+    // The awaited dispatcher then unwinds, appendMessage runs, AND finally
+    // the timeout fires.
+    const bridgeHandler = (ev: any) => {
+      setTimeout(() => {
+        captured = ev.message.id ?? sessionManager.getLeafId();
+        sendDone();
+      }, 0);
     };
 
-    // Simulate pi core's _processAgentEvent:
-    // 1. _emit calls handler (async, NOT awaited)
-    const handlerPromise = bridgeHandler();
-    // 2. appendMessage runs synchronously, updating leafId
-    leafId = "assistant-entry-101";
-
-    // Wait for the deferred handler to complete
-    await handlerPromise;
+    // Simulate the dispatcher: await handler, then call appendMessage.
+    await bridgeHandler(event);
+    sessionManager.appendMessage(event.message);
+    await sentP;
 
-    expect(capturedEntryId).toBe("assistant-entry-101");
+    expect(captured).toBe("assistant-entry-101");
   });
 
-  it("immediate getLeafId() would capture the stale entry ID (demonstrates the bug)", async () => {
+  it("queueMicrotask deferral would NOT work on pi 0.70.x (regression demonstration)", async () => {
+    // Reproduces why we abandoned queueMicrotask: it resolves inside the
+    // awaited dispatcher, before appendMessage runs.
     let leafId = "user-entry-100";
-    const sessionManager = {
-      getLeafId: () => leafId,
-    };
+    let captured: string | undefined;
 
-    let capturedEntryId: string | undefined;
-
-    // Simulate the OLD (buggy) bridge handler: reads getLeafId() immediately
-    const buggyBridgeHandler = async () => {
-      // No deferral — reads leafId before appendMessage runs
-      capturedEntryId = sessionManager.getLeafId();
+    const buggyBridge = async () => {
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      captured = leafId;
     };
 
-    // Simulate pi core's _processAgentEvent:
-    const handlerPromise = buggyBridgeHandler();
-    leafId = "assistant-entry-101"; // too late — handler already read it
-
-    await handlerPromise;
+    // Pi 0.70.x: await the bridge, THEN persist. Mirroring the real ordering:
+    const handlerP = buggyBridge();
+    await handlerP;
+    leafId = "assistant-entry-101"; // appendMessage runs after await
 
-    // Bug: captures the stale leaf, not the assistant's entry
-    expect(capturedEntryId).toBe("user-entry-100");
+    expect(captured).toBe("user-entry-100");
+    expect(captured).not.toBe("assistant-entry-101");
   });
 
-  it("message_start should still capture entryId immediately (no deferral)", async () => {
-    let leafId = "previous-assistant-entry-99";
-    const sessionManager = {
-      getLeafId: () => leafId,
-    };
-
-    let capturedEntryId: string | undefined;
-
-    // Simulate bridge handler for message_start (immediate, no deferral)
-    const messageStartHandler = async () => {
-      capturedEntryId = sessionManager.getLeafId();
-    };
-
-    const handlerPromise = messageStartHandler();
-    // User entry gets written after message_start
-    leafId = "user-entry-100";
-
-    await handlerPromise;
+  it("entry_persisted is the back-fill mechanism for user message_start (where event.message.id is unavailable)", () => {
+    // Behavioural assertion (pure data shape): when the bridge sends a
+    // user message_start, it stamps a nonce; later when pi persists the
+    // user entry, the bridge sends entry_persisted { nonce, entryId }.
+    // The reducer pairs them by nonce. See change: fix-per-message-fork.
+    const start = { type: "message_start", message: { role: "user" }, nonce: "n-1" };
+    const persisted = { type: "entry_persisted", entryId: "user-200", nonce: "n-1" };
 
-    // message_start should capture the leaf BEFORE the user entry is written
-    expect(capturedEntryId).toBe("previous-assistant-entry-99");
+    expect(start.nonce).toBe(persisted.nonce);
+    expect(persisted.entryId).toBe("user-200");
   });
 });

package/packages/extension/src/__tests__/multiselect-dashboard-routing.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Tests for the bridge's `ctx.ui.multiselect` PromptBus patch and the TUI
+ * adapter's multiselect handling. The patch lives in `bridge.ts` but is
+ * exercised here through a small reproduction harness so we don't pull in
+ * the full session lifecycle.
+ *
+ * See change: fix-multiselect-auto-cancel-on-dashboard.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { decodeMultiselectAnswer } from "../multiselect-decode.js";
+
+// ──────────────────────────────────────────────────────────────────────
+// `decodeMultiselectAnswer` — pure helper used by both the runtime patch
+// and the TUI adapter's response encoding round-trip.
+// ──────────────────────────────────────────────────────────────────────
+
+describe("decodeMultiselectAnswer", () => {
+  it("resolves cancellation as undefined", () => {
+    expect(decodeMultiselectAnswer({ cancelled: true })).toBeUndefined();
+    expect(decodeMultiselectAnswer({ cancelled: true, answer: '["x"]' })).toBeUndefined();
+  });
+
+  it("resolves successful selection from JSON-encoded array", () => {
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: '["a","c"]' })).toEqual(["a", "c"]);
+  });
+
+  it("resolves empty selection as []", () => {
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: "[]" })).toEqual([]);
+  });
+
+  it("resolves null / undefined / empty answer as [] (not undefined)", () => {
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: undefined })).toEqual([]);
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: "" })).toEqual([]);
+  });
+
+  it("resolves unparseable JSON as [] without throwing", () => {
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: "not-json" })).toEqual([]);
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: "{not:array}" })).toEqual([]);
+  });
+
+  it("resolves valid JSON that is not an array as []", () => {
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: '"just-a-string"' })).toEqual([]);
+    expect(decodeMultiselectAnswer({ cancelled: false, answer: '{"k":"v"}' })).toEqual([]);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────────
+// Bridge patch reproduction — emulate the assignment block in
+// `bridge.ts:935-948` plus the new multiselect arm and assert behavior.
+// We cannot import `bridge.ts` directly (it has heavy session-lifecycle
+// imports), so we reproduce the assignment closure here. The closure
+// shape MUST match `bridge.ts` exactly; if `bridge.ts` drifts, the
+// regression guard test (see "ctx.ui.multiselect is assigned by the
+// bridge patch block" below) re-loads the bridge source and asserts
+// the assignment exists.
+// ──────────────────────────────────────────────────────────────────────
+
+interface BusRequestArgs {
+  pipeline: string;
+  type: string;
+  question: string;
+  options?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+interface FakeBus {
+  request: (args: BusRequestArgs) => Promise<{ cancelled?: boolean; answer?: string }>;
+}
+
+function applyMultiselectPatch(
+  ctx: { ui: Record<string, any> },
+  bus: FakeBus,
+): void {
+  const existing = (ctx.ui as any).multiselect;
+  if (typeof existing === "function") {
+    // eslint-disable-next-line no-console
+    console.warn("[bridge] ctx.ui.multiselect already exists — overriding for PromptBus routing");
+  }
+  (ctx.ui as any).multiselect = (title: string, options: string[], opts?: { message?: string }) =>
+    bus.request({
+      pipeline: "command",
+      type: "multiselect",
+      question: title,
+      options,
+      metadata: opts?.message ? { message: opts.message } : undefined,
+    }).then((r) => decodeMultiselectAnswer(r));
+}
+
+describe("bridge ctx.ui.multiselect patch", () => {
+  let ctx: { ui: Record<string, any> };
+  let bus: FakeBus;
+  let requestSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    requestSpy = vi.fn();
+    bus = { request: requestSpy as any };
+    ctx = { ui: {} };
+  });
+
+  it("assigns ctx.ui.multiselect as a function after the patch runs", () => {
+    expect(typeof ctx.ui.multiselect).toBe("undefined");
+    applyMultiselectPatch(ctx, bus);
+    expect(typeof ctx.ui.multiselect).toBe("function");
+  });
+
+  it("dispatches bus.request with the right shape on call", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: false, answer: '["a","c"]' });
+
+    const result = await ctx.ui.multiselect("Pick", ["a", "b", "c"], { message: "ctx" });
+
+    expect(requestSpy).toHaveBeenCalledTimes(1);
+    expect(requestSpy).toHaveBeenCalledWith({
+      pipeline: "command",
+      type: "multiselect",
+      question: "Pick",
+      options: ["a", "b", "c"],
+      metadata: { message: "ctx" },
+    });
+    expect(result).toEqual(["a", "c"]);
+  });
+
+  it("omits metadata when no message is provided", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: false, answer: "[]" });
+
+    await ctx.ui.multiselect("Pick", ["a", "b"]);
+
+    expect(requestSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ metadata: undefined }),
+    );
+  });
+
+  it("resolves successful selection through the decoder", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: false, answer: '["a","c"]' });
+    await expect(ctx.ui.multiselect("t", ["a", "b", "c"])).resolves.toEqual(["a", "c"]);
+  });
+
+  it("resolves empty selection as []", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: false, answer: "[]" });
+    await expect(ctx.ui.multiselect("t", ["a"])).resolves.toEqual([]);
+  });
+
+  it("resolves cancellation as undefined", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: true });
+    await expect(ctx.ui.multiselect("t", ["a"])).resolves.toBeUndefined();
+  });
+
+  it("resolves unparseable answer as [] without throwing", async () => {
+    applyMultiselectPatch(ctx, bus);
+    requestSpy.mockResolvedValue({ cancelled: false, answer: "not-json" });
+    await expect(ctx.ui.multiselect("t", ["a"])).resolves.toEqual([]);
+  });
+
+  it("warns when ctx.ui.multiselect was already a function before the patch", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    ctx.ui.multiselect = () => Promise.resolve(["pre-existing"]);
+
+    applyMultiselectPatch(ctx, bus);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("already exists"),
+    );
+    // The patch still wins — subsequent calls go through bus.request.
+    requestSpy.mockResolvedValue({ cancelled: false, answer: '["winner"]' });
+    return ctx.ui.multiselect("t", ["a"]).then((r: any) => {
+      expect(r).toEqual(["winner"]);
+      expect(requestSpy).toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────────
+// Source regression guard — re-load bridge.ts as text and assert the
+// multiselect patch line exists. Mirrors `no-direct-process-kill.test.ts`
+// pattern: textual scan over a single file, fail with file:line if the
+// expected snippet is missing or moved.
+// ──────────────────────────────────────────────────────────────────────
+
+describe("bridge.ts source regression guard", () => {
+  it("contains the ctx.ui.multiselect PromptBus assignment", async () => {
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+    const url = await import("node:url");
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const bridgePath = path.resolve(here, "../bridge.ts");
+    const src = fs.readFileSync(bridgePath, "utf8");
+
+    // The assignment must mention `multiselect` as a key on ctx.ui AND
+    // dispatch through bus.request with type:"multiselect".
+    expect(src).toMatch(/\(ctx\.ui as any\)\.multiselect\s*=/);
+    expect(src).toMatch(/type:\s*"multiselect"/);
+  });
+
+  // Note: the previous-change assertions about `custom: ctx.ui.custom?.bind(...)`
+  // capture and the TUI `prompt.type === "multiselect"` arm were removed by
+  // change `fix-multiselect-tui-arm-self-cancel`. The inverse-guard for that
+  // removal lives in `no-tui-multiselect-arm-regression.test.ts`.
+});

package/packages/extension/src/__tests__/multiselect-list.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from "vitest";
+import { MultiSelectList } from "../multiselect-list.js";
+
+function make(options: string[] = ["A", "B", "C"], title = "Pick", message?: string) {
+  const list = new MultiSelectList(title, options, message);
+  const onConfirm = vi.fn();
+  const onCancel = vi.fn();
+  list.onConfirm = onConfirm;
+  list.onCancel = onCancel;
+  return { list, onConfirm, onCancel };
+}
+
+describe("MultiSelectList", () => {
+  describe("keybindings", () => {
+    it("space toggles the checked state of the current item and nothing else", () => {
+      const { list, onConfirm } = make();
+      list.handleInput(" "); // toggle index 0 → A checked
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith(["A"]);
+    });
+
+    it("arrow down moves cursor and space toggles the new current item", () => {
+      const { list, onConfirm } = make();
+      list.handleInput("\u001b[B"); // cursor → 1 (B)
+      list.handleInput(" "); // B checked
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith(["B"]);
+    });
+
+    it("j / k navigation works like arrows", () => {
+      const { list, onConfirm } = make();
+      list.handleInput("j"); // cursor → 1
+      list.handleInput("j"); // cursor → 2
+      list.handleInput(" "); // C checked
+      list.handleInput("k"); // cursor → 1
+      list.handleInput(" "); // B checked
+      list.handleInput("\r");
+      // selected values returned in ORIGINAL order
+      expect(onConfirm).toHaveBeenCalledWith(["B", "C"]);
+    });
+
+    it("enter with nothing checked confirms with []", () => {
+      const { list, onConfirm } = make();
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith([]);
+    });
+
+    it("escape cancels; no confirm is fired", () => {
+      const { list, onConfirm, onCancel } = make();
+      list.handleInput(" "); // check A
+      list.handleInput("\u001b");
+      expect(onCancel).toHaveBeenCalledTimes(1);
+      expect(onConfirm).not.toHaveBeenCalled();
+    });
+
+    it("pressing 'a' does NOT bulk-toggle (no select-all in TUI)", () => {
+      const { list, onConfirm } = make();
+      list.handleInput("a");
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith([]);
+    });
+
+    it("cursor does not go below 0", () => {
+      const { list } = make();
+      list.handleInput("k");
+      list.handleInput("k");
+      expect(list.getCursor()).toBe(0);
+    });
+
+    it("cursor does not go past last item", () => {
+      const { list } = make(["A", "B"]);
+      list.handleInput("j");
+      list.handleInput("j");
+      list.handleInput("j");
+      expect(list.getCursor()).toBe(1);
+    });
+
+    it("toggling twice returns item to unchecked", () => {
+      const { list, onConfirm } = make();
+      list.handleInput(" ");
+      list.handleInput(" ");
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith([]);
+    });
+
+    it("selected order follows original option order, not toggle order", () => {
+      const { list, onConfirm } = make(["A", "B", "C", "D"]);
+      // toggle D first, then A, then C
+      list.handleInput("j");
+      list.handleInput("j");
+      list.handleInput("j");
+      list.handleInput(" "); // D
+      list.handleInput("k");
+      list.handleInput("k");
+      list.handleInput("k");
+      list.handleInput(" "); // A
+      list.handleInput("j");
+      list.handleInput("j");
+      list.handleInput(" "); // C
+      list.handleInput("\r");
+      expect(onConfirm).toHaveBeenCalledWith(["A", "C", "D"]);
+    });
+  });
+
+  describe("render", () => {
+    it("includes footer hint", () => {
+      const { list } = make();
+      const lines = list.render(80);
+      expect(lines.some((l) => l.includes("space toggle"))).toBe(true);
+      expect(lines.some((l) => l.includes("enter confirm"))).toBe(true);
+      expect(lines.some((l) => l.includes("esc cancel"))).toBe(true);
+    });
+
+    it("renders [ ] for unchecked and [x] for checked items", () => {
+      const { list } = make();
+      list.handleInput(" "); // check A
+      const lines = list.render(80);
+      expect(lines.some((l) => l.includes("[x] A"))).toBe(true);
+      expect(lines.some((l) => l.includes("[ ] B"))).toBe(true);
+    });
+
+    it("renders cursor marker on current item", () => {
+      const { list } = make();
+      list.handleInput("j"); // cursor → 1
+      const lines = list.render(80);
+      // Cursor line should start with "▸ " somewhere
+      expect(lines.some((l) => l.startsWith("▸ ") && l.includes("B"))).toBe(true);
+    });
+
+    it("includes title and message when provided", () => {
+      const { list } = make(["A", "B"], "Pick one or more", "Some context");
+      const lines = list.render(80);
+      expect(lines.some((l) => l.includes("Pick one or more"))).toBe(true);
+      expect(lines.some((l) => l.includes("Some context"))).toBe(true);
+    });
+  });
+});

package/packages/extension/src/__tests__/multiselect-polyfill.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for `polyfillMultiselect`'s fallback chain. After the
+ * fix-multiselect-auto-cancel-on-dashboard change, the polyfill prefers a
+ * bridge-patched `ctx.ui.multiselect` (the PromptBus path that surfaces in
+ * the dashboard browser) and falls back to the legacy `ctx.ui.custom` +
+ * `MultiSelectList` overlay only when the patch is absent (older pi
+ * versions or non-bridge embeddings).
+ *
+ * See change: fix-multiselect-auto-cancel-on-dashboard.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { polyfillMultiselect } from "../multiselect-polyfill.js";
+
+describe("polyfillMultiselect — fallback chain", () => {
+  it("delegates to ctx.ui.multiselect when present (primary, bus-routed path)", async () => {
+    const multiselectFn = vi.fn().mockResolvedValue(["a"]);
+    const customFn = vi.fn();
+    const ctx = {
+      ui: {
+        multiselect: multiselectFn,
+        custom: customFn,
+      },
+    };
+
+    const result = await polyfillMultiselect(ctx as any, "Pick", ["a", "b"]);
+
+    expect(result).toEqual(["a"]);
+    expect(multiselectFn).toHaveBeenCalledTimes(1);
+    expect(multiselectFn).toHaveBeenCalledWith("Pick", ["a", "b"], undefined);
+    expect(customFn).not.toHaveBeenCalled();
+  });
+
+  it("forwards opts.message to ctx.ui.multiselect when present", async () => {
+    const multiselectFn = vi.fn().mockResolvedValue([]);
+    const ctx = { ui: { multiselect: multiselectFn, custom: vi.fn() } };
+
+    await polyfillMultiselect(ctx as any, "Pick", ["a"], { message: "ctx" });
+
+    expect(multiselectFn).toHaveBeenCalledWith("Pick", ["a"], { message: "ctx" });
+  });
+
+  it("propagates undefined (cancellation) through the primary path", async () => {
+    const multiselectFn = vi.fn().mockResolvedValue(undefined);
+    const ctx = { ui: { multiselect: multiselectFn, custom: vi.fn() } };
+
+    await expect(polyfillMultiselect(ctx as any, "t", ["a"])).resolves.toBeUndefined();
+  });
+
+  it("falls back to ctx.ui.custom when ctx.ui.multiselect is absent (TUI path)", async () => {
+    let capturedDone: ((r: string[] | undefined) => void) | undefined;
+    const customFn = vi.fn().mockImplementation((factory: any) => {
+      return new Promise<string[] | undefined>((resolve) => {
+        const done = (r: string[] | undefined) => resolve(r);
+        capturedDone = done;
+        const component = factory({}, {}, {}, done);
+        // Simulate user confirming after the factory wires the component.
+        component?.onConfirm?.(["b"]);
+      });
+    });
+    const ctx = { ui: { custom: customFn } };
+
+    const result = await polyfillMultiselect(ctx as any, "Pick", ["a", "b"]);
+
+    expect(result).toEqual(["b"]);
+    expect(customFn).toHaveBeenCalledTimes(1);
+    expect(capturedDone).toBeTypeOf("function");
+  });
+
+  it("falls back to ctx.ui.custom and resolves undefined on cancel", async () => {
+    const customFn = vi.fn().mockImplementation((factory: any) => {
+      return new Promise<string[] | undefined>((resolve) => {
+        const component = factory({}, {}, {}, (r: any) => resolve(r));
+        component?.onCancel?.();
+      });
+    });
+    const ctx = { ui: { custom: customFn } };
+
+    await expect(polyfillMultiselect(ctx as any, "Pick", ["a"])).resolves.toBeUndefined();
+  });
+
+  it("does NOT fall back to ctx.ui.custom when ctx.ui.multiselect resolves to []", async () => {
+    // Empty selection is a valid answer — must NOT trigger the legacy fallback.
+    const multiselectFn = vi.fn().mockResolvedValue([]);
+    const customFn = vi.fn();
+    const ctx = { ui: { multiselect: multiselectFn, custom: customFn } };
+
+    const result = await polyfillMultiselect(ctx as any, "t", ["a"]);
+
+    expect(result).toEqual([]);
+    expect(customFn).not.toHaveBeenCalled();
+  });
+});