@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.3

package/packages/extension/src/ask-user-tool.ts

@@ -10,58 +10,89 @@ import { Type } from "typebox";
 import { polyfillMultiselect } from "./multiselect-polyfill.js";
 
 // ──────────────────────────────────────────────────────────────────────────
-// Single-question schema arms (reused inside the batch arm's questions array)
+// Schema definition
+//
+// IMPORTANT: We use a single flat `Type.Object` at the root (rather than a
+// `Type.Union` of per-method object arms) so the generated JSON Schema has
+// `"type": "object"` at the root.
+//
+// Rationale: OpenAI's function-calling validator (and especially the strict
+// mode used by GPT-4.1+/GPT-5.x/Codex/Responses API) REQUIRES the parameters
+// schema to be an object at the root. A `Type.Union` produces `anyOf` at the
+// root with no `type` field, which Anthropic accepts but OpenAI rejects with:
+//   "Invalid schema for function 'ask_user': schema must be a JSON Schema
+//    of 'type: \"object\"', got 'type: \"None\"'."
+//
+// Per-method validation (which fields are required for which `method`) is
+// enforced at runtime by `prepareArguments` (rescue/normalization) and the
+// `execute` switch below — the JSON Schema only needs to describe the union
+// of allowed fields.
 // ──────────────────────────────────────────────────────────────────────────
 
-const ConfirmSchema = Type.Object({
-  method: Type.Literal("confirm", { description: "Yes/no question" }),
-  title: Type.String({ description: "The question to confirm" }),
-  message: Type.Optional(Type.String({ description: "Additional context or detailed question body" })),
-});
-
-const SelectSchema = Type.Object({
-  method: Type.Literal("select", { description: "Pick one option from a list" }),
-  title: Type.String({ description: "Short title for the question" }),
-  options: Type.Array(Type.String(), {
-    minItems: 2,
-    description: "Options the user chooses between (at least 2; use 'confirm' for yes/no)",
-  }),
-  message: Type.Optional(Type.String({ description: "Additional context" })),
-});
-
-const MultiselectSchema = Type.Object({
-  method: Type.Literal("multiselect", { description: "Pick multiple options from a list" }),
-  title: Type.String({ description: "Short title for the question" }),
-  options: Type.Array(Type.String(), {
-    minItems: 1,
-    description: "Options the user can multi-select",
-  }),
-  message: Type.Optional(Type.String({ description: "Additional context" })),
-});
-
-const InputSchema = Type.Object({
-  method: Type.Literal("input", { description: "Free-text input" }),
-  title: Type.String({ description: "Short title for the question" }),
-  placeholder: Type.Optional(Type.String({ description: "Placeholder text for the input field" })),
-  message: Type.Optional(Type.String({ description: "Additional context" })),
-});
-
-// Sub-question union deliberately omits the batch arm (no nesting).
-const SubQuestionSchema = Type.Union([ConfirmSchema, SelectSchema, MultiselectSchema, InputSchema], {
-  description: "A single question inside a batch. Must not itself be a batch.",
-});
-
-const BatchSchema = Type.Object({
-  method: Type.Literal("batch", {
-    description: "Ask multiple related questions in one call; answers are returned as an ordered array.",
-  }),
-  title: Type.String({ description: "Header shown above the sequence of dialogs" }),
-  questions: Type.Array(SubQuestionSchema, {
-    minItems: 1,
-    description: "One or more sub-questions (confirm/select/multiselect/input). Cannot nest batch.",
-  }),
-  message: Type.Optional(Type.String({ description: "Additional context for the whole batch" })),
-});
+const MethodEnum = Type.Union(
+  [
+    Type.Literal("confirm"),
+    Type.Literal("select"),
+    Type.Literal("multiselect"),
+    Type.Literal("input"),
+    Type.Literal("batch"),
+  ],
+  {
+    description:
+      "Question kind. 'confirm' = yes/no, 'select' = pick one of options[], 'multiselect' = pick many of options[], 'input' = free text, 'batch' = ask several questions in one call (provide questions[]).",
+  },
+);
+
+// Sub-question schema for batch.method — flat object (root: type=object) so
+// the emitted JSON Schema stays OpenAI-compatible at every level.
+//
+// IMPORTANT: this object MUST NOT carry a root-level `oneOf` / `anyOf` /
+// `allOf` / `enum` / `not`. OpenAI strict mode (GPT-4.1+, GPT-5.x, Codex,
+// Responses API) explicitly rejects those at *any* schema's top level
+// with: "schema must have type 'object' and not have 'oneOf' / 'anyOf' /
+// 'allOf' / 'enum' / 'not' at the top level." An earlier draft of
+// fix-multiselect-auto-cancel-on-dashboard tried to add a body-level
+// `oneOf` discriminator to restore Anthropic's per-arm strictness, but
+// real-world OpenAI gpt-5 rejected it; the fallback path documented in
+// tasks.md §9.7 was taken — Layer 2 dropped, Layer 1 ships alone.
+//
+// Per-method requirements (select/multiselect need `options`, batch
+// needs `questions[]`, etc.) are enforced exclusively by
+// `prepareArguments` rescue + the `execute` switch's runtime guards.
+// Sub-questions cannot themselves be a batch (no nesting); enforced at
+// runtime in `execute`.
+//
+// See change: fix-multiselect-auto-cancel-on-dashboard.
+const SubQuestionSchema = Type.Object(
+  {
+    method: Type.Union(
+      [
+        Type.Literal("confirm"),
+        Type.Literal("select"),
+        Type.Literal("multiselect"),
+        Type.Literal("input"),
+      ],
+      { description: "Sub-question kind. Cannot be 'batch' (no nesting)." },
+    ),
+    title: Type.String({ description: "Short title / question text for this sub-question" }),
+    options: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "Required for 'select' (>=2) and 'multiselect' (>=1). Plain string[] — not [{label,value}].",
+      }),
+    ),
+    placeholder: Type.Optional(
+      Type.String({ description: "Placeholder for 'input' method" }),
+    ),
+    message: Type.Optional(
+      Type.String({ description: "Additional context for this sub-question" }),
+    ),
+  },
+  {
+    description:
+      "A single question inside a batch. Must not itself be a batch.",
+  },
+);
 
 // ──────────────────────────────────────────────────────────────────────────
 // Argument rescue helpers
@@ -132,9 +163,67 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
       "Do not nest batches. Send `options` as a plain string[] — not [{label, value}].",
       "This applies to all workflows including OpenSpec, planning, and any situation where you need user input before proceeding.",
     ],
-    parameters: Type.Union(
-      [ConfirmSchema, SelectSchema, MultiselectSchema, InputSchema, BatchSchema],
-      { description: "Parameters for ask_user, discriminated by method." },
+    // Flat object schema (root: type=object) for OpenAI strict-mode
+    // compatibility.
+    //
+    // IMPORTANT: this object MUST NOT carry a root-level `oneOf` / `anyOf`
+    // / `allOf` / `enum` / `not`. OpenAI strict mode (GPT-4.1+, GPT-5.x,
+    // Codex, Responses API) explicitly rejects those at the top level with:
+    // "schema must have type 'object' and not have 'oneOf' / 'anyOf' /
+    // 'allOf' / 'enum' / 'not' at the top level."
+    //
+    // An earlier iteration of fix-multiselect-auto-cancel-on-dashboard
+    // ("Layer 2: defense in depth") tried adding a body-level `oneOf`
+    // discriminator over `method` so Anthropic would regain per-arm
+    // `required` + `minItems` enforcement. That worked for Anthropic
+    // models but real-world OpenAI gpt-5 rejected the schema (verified by
+    // the user 2026-04-30). The fallback documented in tasks.md §9.7 was
+    // taken: Layer 2 was dropped; Layer 1 (multiselect dashboard routing)
+    // ships alone, which is what actually fixes the user-reported bug.
+    //
+    // Per-method shape requirements (select/multiselect need `options`,
+    // batch needs `questions[]`, etc.) are enforced exclusively at runtime
+    // by `prepareArguments` (rescue/normalization) and the `execute` switch.
+    //
+    // The `no-root-oneof-in-ask-user-schema` guard test at
+    // packages/extension/src/__tests__/ask-user-schema-discriminator.test.ts
+    // pins this constraint so a future refactor cannot reintroduce it.
+    //
+    // See change: fix-multiselect-auto-cancel-on-dashboard.
+    parameters: Type.Object(
+      {
+        method: MethodEnum,
+        title: Type.Optional(
+          Type.String({
+            description:
+              "Short title / question text. Required for all methods except when 'questions' carry it (batch may omit and inherit from first sub-question).",
+          }),
+        ),
+        message: Type.Optional(
+          Type.String({ description: "Additional context shown alongside the question(s)." }),
+        ),
+        options: Type.Optional(
+          Type.Array(Type.String(), {
+            description:
+              "Required for method 'select' (>=2 items) and 'multiselect' (>=1 item). Plain string[] — not [{label,value}]. Ignored for other methods.",
+          }),
+        ),
+        placeholder: Type.Optional(
+          Type.String({
+            description: "Placeholder for method 'input'. Ignored for other methods.",
+          }),
+        ),
+        questions: Type.Optional(
+          Type.Array(SubQuestionSchema, {
+            description:
+              "Required for method 'batch' (>=1 sub-question). Each sub-question is its own confirm/select/multiselect/input — cannot nest 'batch'.",
+          }),
+        ),
+      },
+      {
+        description:
+          "Parameters for ask_user. The required fields depend on `method`: confirm→title; select→title+options(>=2); multiselect→title+options(>=1); input→title (placeholder optional); batch→questions[] (title auto-derived from first question if omitted). Validation is enforced at runtime by prepareArguments + execute (no schema-level discriminator — OpenAI strict mode forbids root-level oneOf).",
+      },
     ),
     prepareArguments(args: unknown) {
       let obj = (args && typeof args === "object" ? { ...(args as Record<string, unknown>) } : {}) as Record<string, unknown>;
@@ -223,6 +312,21 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
       return obj as any;
     },
     async execute(_toolCallId: any, params: any, _signal: any, _onUpdate: any, ctx: any) {
+      // Capture the originating toolCallId so the resulting prompt_request
+      // metadata carries it; the client reducer pairs the interactiveUi
+      // row with its parent toolResult row using this id.
+      // See change: fix-interactive-ui-reorder.
+      const toolCallId: string | undefined =
+        typeof _toolCallId === "string" && _toolCallId.length > 0
+          ? _toolCallId
+          : undefined;
+      const withTcid = (
+        opts: Record<string, unknown> | undefined,
+      ): Record<string, unknown> | undefined => {
+        if (!toolCallId) return opts;
+        return { ...(opts ?? {}), toolCallId };
+      };
+
       // ── Batch branch ─────────────────────────────────────────────────
       if (params.method === "batch" && Array.isArray(params.questions)) {
         const results: Array<unknown> = [];
@@ -230,13 +334,17 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
 
         for (const sq of params.questions) {
           const subTitle = `${params.title} — ${sq.title ?? "Question"}`;
-          const subMsg = params.message ? { message: params.message } : undefined;
+          const subMsg = withTcid(params.message ? { message: params.message } : undefined);
 
           let answer: unknown;
           try {
             switch (sq.method) {
               case "confirm":
-                answer = await ctx.ui.confirm(subTitle, sq.message ?? params.message ?? "");
+                answer = await ctx.ui.confirm(
+                  subTitle,
+                  sq.message ?? params.message ?? "",
+                  withTcid(undefined),
+                );
                 break;
               case "select": {
                 const opts = Array.isArray(sq.options) ? sq.options : [];
@@ -312,7 +420,7 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
 
       // ── Single-question branches (unchanged behavior) ────────────────
       let result: unknown;
-      const msgOpts = params.message ? { message: params.message } : undefined;
+      const msgOpts = withTcid(params.message ? { message: params.message } : undefined);
       const title = params.title || params.message || "Question";
 
       const options: string[] = Array.isArray(params.options)
@@ -331,7 +439,7 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
 
       switch (params.method) {
         case "confirm":
-          result = await ctx.ui.confirm(title, params.message ?? "");
+          result = await ctx.ui.confirm(title, params.message ?? "", withTcid(undefined));
           break;
         case "select":
           result = await ctx.ui.select(title, options, msgOpts);

package/packages/extension/src/bridge.ts

@@ -26,6 +26,7 @@ import { expandPromptTemplateFromDisk } from "./prompt-expander.js";
 import { PromptBus } from "./prompt-bus.js";
 import { DashboardDefaultAdapter } from "./dashboard-default-adapter.js";
 import { registerAskUserTool } from "./ask-user-tool.js";
+import { decodeMultiselectAnswer } from "./multiselect-decode.js";
 import { activate as activateProviderRegister, onProviderChanged, reloadProviders } from "./provider-register.js";
 import type { FlowInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { startMetricsMonitor, stopMetricsMonitor, collectMetrics } from "./process-metrics.js";
@@ -35,6 +36,7 @@ import { filterHiddenCommands, extractFirstMessage, getCurrentModelString } from
 import { sendStateSync as _sendStateSync, replaySessionEntries as _replaySessionEntries, handleSessionChange as _handleSessionChange } from "./session-sync.js";
 import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged } from "./model-tracker.js";
 import { registerFlowEventListeners, FLOW_EVENT_MAP, SUBAGENT_EVENT_MAP } from "./flow-event-wiring.js";
+import { refreshUiModules, subscribeUiInvalidate, handleUiManagement, type UiModulesBridgeCtx } from "./ui-modules.js";
 
 const HEARTBEAT_INTERVAL = 15_000;
 const GIT_POLL_INTERVAL = 30_000;
@@ -263,11 +265,29 @@ function initBridge(pi: ExtensionAPI) {
   const config = loadConfig();
   const dashboardUrl = process.env.PI_DASHBOARD_URL ?? `ws://localhost:${config.piPort}`;
 
+  // Long-lived ctx wrapper for the Extension UI System (Phase 1) — see
+  // change: add-extension-ui-modal. `getSessionId` reads the closed-over
+  // `sessionId` so the helper always uses the current value (which is
+  // mutated when `event.reason ∈ {"new","fork","resume"}` fires).
+  const uiModulesBridgeCtx: UiModulesBridgeCtx = {
+    pi: pi as any,
+    connection: { send: (msg: unknown) => connection.send(msg) },
+    getSessionId: () => sessionId,
+  };
+
   const connection = new ConnectionManager({
     url: dashboardUrl,
     onMessage: safe(async (data: unknown) => {
       if (!isActive()) return; // Stale listener guard
       const msg = data as ServerToExtensionMessage;
+      // Extension UI System (Phase 1): browser-originated action / data
+      // request. Re-emit on pi.events; the listener either populates
+      // data.items synchronously or calls _reply asynchronously.
+      // See change: add-extension-ui-modal.
+      if ((msg as any).type === "ui_management") {
+        handleUiManagement(uiModulesBridgeCtx, msg as any);
+        return;
+      }
       // Legacy extension_ui_response removed — now handled by prompt_response → promptBus.respond()
       // Reload auth credentials when dashboard notifies of changes
       if (msg.type === "credentials_updated") {
@@ -463,6 +483,11 @@ function initBridge(pi: ExtensionAPI) {
       if (getBridgeState().isAgentStreaming) {
         connection.send(mapEventToProtocol(sessionId, { type: "agent_start" }));
       }
+      // Extension UI System (Phase 1): re-probe modules after every
+      // reconnect so the server-side cache stays accurate. The probe is
+      // synchronous and re-runs the listener stack each call.
+      // See change: add-extension-ui-modal.
+      refreshUiModules(uiModulesBridgeCtx);
     }),
   });
 
@@ -830,6 +855,16 @@ function initBridge(pi: ExtensionAPI) {
       input: ctx.ui.input?.bind(ctx.ui) as ((q: string, placeholder?: string, extra?: any) => Promise<string | undefined>) | undefined,
       confirm: ctx.ui.confirm?.bind(ctx.ui) as ((q: string, msg: string, extra?: any) => Promise<boolean>) | undefined,
       editor: ctx.ui.editor?.bind(ctx.ui) as ((q: string, prefill?: string, extra?: any) => Promise<string | undefined>) | undefined,
+      // NOTE: the `custom` field is intentionally NOT captured here. A
+      // previous change (fix-multiselect-auto-cancel-on-dashboard) added a
+      // TUI multiselect arm that awaited the original ctx.ui.custom binding,
+      // but pi 0.70's RPC mode defines that primitive as a no-op (returns
+      // undefined synchronously), causing the TUI adapter to auto-cancel the
+      // dashboard-rendered dialog within one event-loop tick. The arm has
+      // been removed; see change fix-multiselect-tui-arm-self-cancel for full
+      // rationale. A repo lint (no-tui-multiselect-arm-regression.test.ts)
+      // prevents reintroduction by banning the co-occurrence of two
+      // substrings (the captured original binding and the TUI arm match).
     };
 
     // Register TUI adapter — presents prompts in the terminal using original
@@ -858,6 +893,13 @@ function initBridge(pi: ExtensionAPI) {
               } else if (prompt.type === "editor" && originals.editor) {
                 answer = await originals.editor(prompt.question, prompt.defaultValue || "", { signal: ac.signal });
               } else {
+                // NOTE: there is intentionally no `else if` arm for the
+                // multiselect prompt type here. See change
+                // fix-multiselect-tui-arm-self-cancel — pi 0.70 RPC mode's
+                // ctx.ui.custom primitive is a no-op, so any TUI arm that
+                // awaits it auto-cancels the dashboard-rendered dialog. The
+                // bus-routed ctx.ui.multiselect patch below + the
+                // DashboardDefaultAdapter handle multiselect end-to-end.
                 return;
               }
 
@@ -908,22 +950,66 @@ function initBridge(pi: ExtensionAPI) {
     // now route through the bus, which distributes to all registered adapters.
     {
       const bus = promptBus;
+      // Build a `metadata` envelope for bus.request that includes both
+      // `message` (existing) and `toolCallId` (new — added by change
+      // `fix-interactive-ui-reorder` so the client reducer can pair the
+      // resulting interactiveUi row with its parent toolResult row).
+      // Free-floating callers (slash commands, architect prompts) omit
+      // `opts.toolCallId` and the metadata field stays undefined.
+      const buildMeta = (
+        opts: any,
+        explicitMessage?: string,
+      ): Record<string, unknown> | undefined => {
+        const message = explicitMessage ?? opts?.message;
+        const toolCallId = opts?.toolCallId;
+        if (!message && !toolCallId) return undefined;
+        const meta: Record<string, unknown> = {};
+        if (message) meta.message = message;
+        if (toolCallId) meta.toolCallId = toolCallId;
+        return meta;
+      };
+
       (ctx.ui as any).select = (title: string, options: string[], opts?: any) =>
-        bus.request({ pipeline: "command", type: "select", question: title, options, metadata: opts?.message ? { message: opts.message } : undefined })
+        bus.request({ pipeline: "command", type: "select", question: title, options, metadata: buildMeta(opts) })
           .then(r => r.cancelled ? undefined : r.answer);
 
       (ctx.ui as any).input = (title: string, placeholder?: string, opts?: any) =>
-        bus.request({ pipeline: "command", type: "input", question: title, defaultValue: placeholder, metadata: opts?.message ? { message: opts.message } : undefined })
+        bus.request({ pipeline: "command", type: "input", question: title, defaultValue: placeholder, metadata: buildMeta(opts) })
           .then(r => r.cancelled ? undefined : r.answer);
 
       (ctx.ui as any).confirm = (title: string, message?: string, opts?: any) =>
-        bus.request({ pipeline: "command", type: "confirm", question: title, metadata: (message || opts?.message) ? { message: message || opts?.message } : undefined })
+        bus.request({ pipeline: "command", type: "confirm", question: title, metadata: buildMeta(opts, message) })
           .then(r => !r.cancelled && r.answer === "true");
 
       (ctx.ui as any).editor = (title: string, prefill?: string, opts?: any) =>
-        bus.request({ pipeline: "command", type: "editor", question: title, defaultValue: prefill, metadata: opts?.message ? { message: opts.message } : undefined })
+        bus.request({ pipeline: "command", type: "editor", question: title, defaultValue: prefill, metadata: buildMeta(opts) })
           .then(r => r.cancelled ? undefined : r.answer);
 
+      // ── Multiselect ──────────────────────────────────────────────
+      // ctx.ui.multiselect is NOT a built-in pi method — we attach it here
+      // so that polyfillMultiselect (and any other consumer) routes through
+      // PromptBus. The dashboard adapter renders a real browser dialog via
+      // MultiselectRenderer; there is intentionally no TUI adapter arm for
+      // multiselect (pi 0.70 RPC mode's ctx.ui.custom is a no-op, so any TUI
+      // arm would auto-cancel the dashboard render in <1s). See changes
+      // fix-multiselect-auto-cancel-on-dashboard (initial bus routing) and
+      // fix-multiselect-tui-arm-self-cancel (TUI arm removal).
+      if (typeof (ctx.ui as any).multiselect === "function") {
+        // Defensive: future upstream pi may add a built-in multiselect.
+        // Override is intentional — the bus-routed version is what
+        // participates in PromptBus first-response-wins semantics.
+        // 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?: any) =>
+        bus.request({
+          pipeline: "command",
+          type: "multiselect",
+          question: title,
+          options,
+          metadata: opts?.message ? { message: opts.message } : undefined,
+        }).then(decodeMultiselectAnswer);
+
       // Notify is fire-and-forget: call original + forward to dashboard
       (ctx.ui as any).notify = (message: string, level?: string) => {
         originalNotify?.(message, level);
@@ -1160,6 +1246,13 @@ function initBridge(pi: ExtensionAPI) {
 
     // Register flow event listeners (pi-flows emits these via pi.events)
     registerFlowEventListeners(syncBc(), () => sessionReady, getFlowsList);
+
+    // Extension UI System (Phase 1): subscribe to invalidate once per
+    // session, then run the discovery probe. The probe is synchronous
+    // and re-runs on every reconnect (see `onReconnect` callback above).
+    // See change: add-extension-ui-modal.
+    subscribeUiInvalidate(uiModulesBridgeCtx);
+    refreshUiModules(uiModulesBridgeCtx);
   }));
 
   // Shared handler for session changes (new/fork/resume)

package/packages/extension/src/multiselect-decode.ts

@@ -0,0 +1,40 @@
+/**
+ * decodeMultiselectAnswer — pure helper that turns a `PromptResponse`
+ * (from PromptBus) into the `string[] | undefined` shape expected by
+ * `polyfillMultiselect` and other multiselect callers.
+ *
+ * Contract:
+ *   • cancelled: true                                  → undefined
+ *   • cancelled: false, answer: undefined / null / ""  → []  (empty selection
+ *                                                            is a real answer,
+ *                                                            distinct from
+ *                                                            cancellation)
+ *   • cancelled: false, answer: '["a","b"]'            → ["a","b"]
+ *   • cancelled: false, answer: <unparseable>          → []  (graceful
+ *                                                            degradation,
+ *                                                            never throw)
+ *
+ * Kept separate from `bridge.ts` so unit tests can exercise it without
+ * instantiating a live PromptBus or session context.
+ *
+ * See change: fix-multiselect-auto-cancel-on-dashboard.
+ */
+
+export interface DecodableResponse {
+  cancelled?: boolean;
+  answer?: string | undefined;
+}
+
+export function decodeMultiselectAnswer(
+  response: DecodableResponse,
+): string[] | undefined {
+  if (response.cancelled) return undefined;
+  const answer = response.answer;
+  if (answer == null || answer === "") return [];
+  try {
+    const parsed = JSON.parse(answer);
+    return Array.isArray(parsed) ? (parsed as string[]) : [];
+  } catch {
+    return [];
+  }
+}

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

@@ -4,23 +4,38 @@
  * `ExtensionUIContext` does not expose. Without this, any TUI dispatch of
  * `method: "multiselect"` crashes with `"ctx.ui.multiselect is not a function"`.
  *
- * Implementation strategy: always delegate to the already-exposed
- * `ctx.ui.custom<T>()` primitive, which takes a factory that returns a
- * focused pi-tui `Component`. We instantiate a `MultiSelectList`, wire
- * `onConfirm` → `done(selected)` and `onCancel` → `done(undefined)`, and
- * return the component.
+ * Fallback chain (introduced by change fix-multiselect-auto-cancel-on-dashboard):
  *
- * The result contract matches what the current (broken) call expects:
+ *   1. PRIMARY  — bridge-patched `ctx.ui.multiselect` (PromptBus path).
+ *      The bridge attaches this method on session_start so the dashboard
+ *      browser renders a real `MultiselectRenderer` dialog and the TUI
+ *      adapter renders a `MultiSelectList` overlay in the terminal.
+ *
+ *   2. FALLBACK — legacy `ctx.ui.custom` + `MultiSelectList` overlay.
+ *      Reached when (a) running against an older pi without the bridge
+ *      patch, (b) running outside the bridge entirely, or (c) the bridge
+ *      patch was removed for some reason. TUI-only — does NOT render a
+ *      browser dialog in dashboard / RPC mode (which is exactly the bug
+ *      that motivated the primary path).
+ *
+ * The result contract is unchanged in either branch:
  *   - resolves to `string[]` when the user confirms a selection
  *     (possibly empty if nothing is checked)
- *   - resolves to `undefined` when the user cancels (Escape)
+ *   - resolves to `undefined` when the user cancels (Escape / Cancel)
+ *
+ * See change: fix-multiselect-auto-cancel-on-dashboard.
  */
 import { MultiSelectList } from "./multiselect-list.js";
 
 // Intentionally loose: `ctx` shape varies slightly across pi versions; the
-// polyfill only needs `ctx.ui.custom`.
+// polyfill only needs `ctx.ui.multiselect` (primary) or `ctx.ui.custom` (fallback).
 export interface PolyfillCtx {
   ui: {
+    multiselect?: (
+      title: string,
+      options: string[],
+      opts?: { message?: string },
+    ) => Promise<string[] | undefined>;
     custom<T>(
       factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (result: T) => void) => unknown,
       options?: unknown,
@@ -34,6 +49,21 @@ export function polyfillMultiselect(
   options: string[],
   opts?: { message?: string },
 ): Promise<string[] | undefined> {
+  // Primary path: delegate to the bridge-patched ctx.ui.multiselect (which
+  // routes through PromptBus → DashboardDefaultAdapter → client
+  // MultiselectRenderer). This is the only working path on pi 0.70 RPC mode
+  // (dashboard headless sessions).
+  const ui = ctx.ui as PolyfillCtx["ui"] & { multiselect?: Function };
+  if (typeof ui.multiselect === "function") {
+    return Promise.resolve(ui.multiselect(title, options, opts));
+  }
+
+  // Legacy fallback: TUI overlay via ctx.ui.custom. Used when the bridge
+  // patch is absent (older pi / non-bridge embedding) OR a future pi version
+  // restores ctx.ui.custom in RPC mode. NOTE: in pi 0.70 RPC mode
+  // ctx.ui.custom is a no-op that resolves to undefined synchronously, so
+  // this branch returns undefined immediately on dashboard headless
+  // sessions — the primary path above is the only effective route there.
   return ctx.ui.custom<string[] | undefined>((_tui, _theme, _keybindings, done) => {
     const list = new MultiSelectList(title, options, opts?.message);
     list.onConfirm = (selected) => done(selected);