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

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;
@@ -186,6 +188,61 @@ function initBridge(pi: ExtensionAPI) {
   let lastThinkingLevel: string | undefined;
   let promptBus: PromptBus | undefined;
 
+  // ── Per-message entry id tracking (for fix-per-message-fork) ──
+  // Pi 0.69+ awaits extension handlers BEFORE sessionManager.appendMessage runs,
+  // which means getLeafId() at emit time returns the previous leaf, not the
+  // entry id of the message currently being emitted. We solve this by:
+  //  1. Wrapping ctx.sessionManager.appendMessage at session_start to stamp
+  //     the just-generated entry id onto the message object reference.
+  //  2. Deferring the message_end enrichment-and-send via setTimeout(0) so
+  //     the awaited dispatcher unwinds and appendMessage runs in between.
+  //  3. Stamping a nonce on message_start/message_end events; emitting an
+  //     entry_persisted event after appendMessage so the client reducer can
+  //     back-fill user-message ChatMessage.entryId.
+  // See change: fix-per-message-fork.
+  const idByMessage = new WeakMap<object, string>();
+  const pendingNonces = new WeakMap<object, string>();
+  let nonceCounter = 0;
+  const nextNonce = (): string => `n-${++nonceCounter}-${Date.now()}`;
+  let appendMessageWrapped = false;
+  let lastWrappedSm: any = null;
+
+  /**
+   * Wrap ctx.sessionManager.appendMessage once per session so that when pi
+   * generates an entry id we capture it in the WeakMap and emit
+   * entry_persisted to the server.
+   */
+  function wrapAppendMessageForCtx(ctx: any): void {
+    const sm = ctx?.sessionManager;
+    if (!sm || typeof sm.appendMessage !== "function") return;
+    // Re-wrap when sessionManager identity changes (session replacement).
+    if (sm === lastWrappedSm && appendMessageWrapped) return;
+    const original = sm.appendMessage.bind(sm);
+    sm.appendMessage = (msg: any, ...rest: any[]) => {
+      const result = original(msg, ...rest);
+      try {
+        if (msg && typeof msg === "object" && typeof msg.id === "string") {
+          idByMessage.set(msg as object, msg.id);
+          const nonce = pendingNonces.get(msg as object);
+          if (nonce && sessionReady && isActive()) {
+            const ev = {
+              type: "entry_persisted",
+              entryId: msg.id,
+              nonce,
+            };
+            connection.send(mapEventToProtocol(sessionId, ev));
+            pendingNonces.delete(msg as object);
+          }
+        }
+      } catch (err) {
+        console.error("[dashboard] entry_persisted emit failed:", err);
+      }
+      return result;
+    };
+    lastWrappedSm = sm;
+    appendMessageWrapped = true;
+  }
+
   /** Wrap a callback so errors log instead of crashing the host pi agent. */
   function safe<T extends (...args: any[]) => any>(fn: T): T {
     return ((...args: any[]) => {
@@ -208,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") {
@@ -408,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);
     }),
   });
 
@@ -612,30 +692,53 @@ function initBridge(pi: ExtensionAPI) {
         }
       }
 
-      // For message_start, enrich with entryId immediately (current leaf)
+      // For message_start: stamp a nonce on the event so the client reducer
+      // can correlate a later entry_persisted back-fill with this bubble.
+      // We do NOT attach entryId here — the message has no id yet on pi
+      // 0.69+ (persistence is deferred to message_end). See change:
+      // fix-per-message-fork.
       if (eventType === "message_start") {
-        const entryId = ctx.sessionManager?.getLeafId?.();
-        if (entryId) {
-          const enriched = { ...event, entryId };
+        wrapAppendMessageForCtx(ctx);
+        const messageRef = (event as any).message;
+        if (messageRef && typeof messageRef === "object") {
+          const nonce = nextNonce();
+          pendingNonces.set(messageRef as object, nonce);
+          const enriched = { ...event, nonce };
           const msg = mapEventToProtocol(sessionId, enriched);
           connection.send(msg);
           return;
         }
       }
 
-      // For message_end, defer getLeafId() so it runs after pi core persists the entry.
-      // Pi core calls _emit (which invokes this handler) BEFORE appendMessage (which updates leafId).
-      // Since _emit doesn't await async handlers, yielding via queueMicrotask lets appendMessage
-      // run first, so getLeafId() returns the correct entry ID for the just-persisted message.
+      // For message_end: defer the SEND via setTimeout(0). Pi 0.69+ runs
+      // sessionManager.appendMessage AFTER the awaited extension dispatcher
+      // returns, so a queueMicrotask deferral is no longer enough. By the
+      // time the macrotask fires, appendMessage has run, pi has mutated
+      // event.message.id in place, and the wrapped appendMessage above has
+      // populated idByMessage. We also stamp a nonce so a downstream
+      // entry_persisted can correlate (covers user message_end where the
+      // earlier message_start nonce is what the reducer is waiting on).
+      // See change: fix-per-message-fork.
       if (eventType === "message_end") {
-        await new Promise<void>(resolve => queueMicrotask(resolve));
-        const entryId = ctx.sessionManager?.getLeafId?.();
-        if (entryId) {
-          const enriched = { ...event, entryId };
-          const msg = mapEventToProtocol(sessionId, enriched);
-          connection.send(msg);
-          return;
+        wrapAppendMessageForCtx(ctx);
+        const messageRef = (event as any).message;
+        const nonce = messageRef && typeof messageRef === "object"
+          ? (pendingNonces.get(messageRef as object) ?? nextNonce())
+          : nextNonce();
+        if (messageRef && typeof messageRef === "object" && !pendingNonces.has(messageRef as object)) {
+          pendingNonces.set(messageRef as object, nonce);
         }
+        setTimeout(() => {
+          if (!isActive() || !sessionReady) return;
+          const entryId =
+            (messageRef && typeof messageRef === "object" && typeof messageRef.id === "string" ? messageRef.id : undefined)
+            ?? (messageRef ? idByMessage.get(messageRef as object) : undefined)
+            ?? ctx.sessionManager?.getLeafId?.();
+          const enriched = { ...event, entryId, nonce };
+          const protoMsg = mapEventToProtocol(sessionId, enriched);
+          connection.send(protoMsg);
+        }, 0);
+        return;
       }
 
       const msg = mapEventToProtocol(sessionId, event);
@@ -694,6 +797,15 @@ function initBridge(pi: ExtensionAPI) {
     cachedCtx = ctx;
     sessionId = newSessionId;
 
+    // Wrap sessionManager.appendMessage so that future message_end events can
+    // recover the just-generated entry id, even when their setTimeout(0)
+    // fires before pi has finished mutating event.message in place. The
+    // helper is idempotent and re-wraps on session replacement.
+    // See change: fix-per-message-fork.
+    appendMessageWrapped = false;
+    lastWrappedSm = null;
+    wrapAppendMessageForCtx(ctx);
+
     // Register ask_user at runtime (not at load time) to avoid static
     // tool-name conflicts with other extensions like pi-flows.
     registerAskUserTool(pi);
@@ -743,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
@@ -771,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;
               }
 
@@ -821,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);
@@ -1073,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-list.ts

@@ -0,0 +1,146 @@
+/**
+ * MultiSelectList — a TUI multi-select component implementing pi-tui's
+ * `Component` interface. Used by `polyfillMultiselect` to emulate the
+ * `ctx.ui.multiselect(...)` call that `pi-coding-agent`'s `ExtensionUIContext`
+ * does not expose natively.
+ *
+ * Keyboard contract (intentional — no "select all" binding in TUI):
+ *   ↑ / k        move cursor up
+ *   ↓ / j        move cursor down
+ *   space        toggle the checked state of the current item
+ *   enter        confirm → onConfirm(selected[])
+ *   esc          cancel  → onCancel()
+ *
+ * The selected array preserves the original option order, not toggle order.
+ */
+
+interface Item {
+  value: string;
+  label: string;
+  description?: string;
+  checked: boolean;
+}
+
+/**
+ * Minimal shape of pi-tui's `Component` interface — we avoid importing from
+ * `@mariozechner/pi-tui` directly so this module stays compile-friendly when
+ * that peer dep isn't present (e.g. in unit tests running via vitest without
+ * the full pi runtime).
+ */
+export interface ComponentLike {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+}
+
+const CURSOR = "▸ ";
+const NO_CURSOR = "  ";
+const CHECKED = "[x]";
+const UNCHECKED = "[ ]";
+const FOOTER_HINT = "space toggle · enter confirm · esc cancel";
+
+const MAX_VISIBLE = 10;
+
+function truncate(text: string, maxWidth: number): string {
+  if (maxWidth <= 1) return "";
+  if (text.length <= maxWidth) return text;
+  if (maxWidth <= 1) return "…";
+  return text.slice(0, Math.max(0, maxWidth - 1)) + "…";
+}
+
+export class MultiSelectList implements ComponentLike {
+  private items: Item[];
+  private cursor = 0;
+  private scrollOffset = 0;
+
+  onConfirm?: (selectedValues: string[]) => void;
+  onCancel?: () => void;
+
+  constructor(
+    private title: string,
+    options: string[],
+    private message?: string,
+  ) {
+    this.items = options.map((opt) => ({
+      value: opt,
+      label: opt,
+      checked: false,
+    }));
+  }
+
+  /** Expose current state for testing / adapters. */
+  getItems(): readonly Item[] {
+    return this.items;
+  }
+  getCursor(): number {
+    return this.cursor;
+  }
+
+  /** Return values of currently checked items in original option order. */
+  private selectedValues(): string[] {
+    return this.items.filter((it) => it.checked).map((it) => it.value);
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    if (this.title) lines.push(truncate(this.title, width));
+    if (this.message) lines.push(truncate(this.message, width));
+    if (lines.length > 0) lines.push("");
+
+    // Scroll window around cursor.
+    const visible = Math.min(MAX_VISIBLE, this.items.length);
+    if (this.cursor < this.scrollOffset) {
+      this.scrollOffset = this.cursor;
+    } else if (this.cursor >= this.scrollOffset + visible) {
+      this.scrollOffset = this.cursor - visible + 1;
+    }
+
+    for (let i = 0; i < visible; i++) {
+      const idx = this.scrollOffset + i;
+      const item = this.items[idx];
+      if (!item) break;
+      const marker = idx === this.cursor ? CURSOR : NO_CURSOR;
+      const box = item.checked ? CHECKED : UNCHECKED;
+      let line = `${marker}${box} ${item.label}`;
+      if (item.description) line += ` — ${item.description}`;
+      lines.push(truncate(line, width));
+    }
+
+    if (this.items.length > visible) {
+      lines.push(`  (${this.cursor + 1}/${this.items.length})`);
+    }
+
+    lines.push("");
+    lines.push(truncate(FOOTER_HINT, width));
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    // Escape
+    if (data === "\u001b" || data === "\x1b") {
+      this.onCancel?.();
+      return;
+    }
+    // Enter (CR or LF)
+    if (data === "\r" || data === "\n") {
+      this.onConfirm?.(this.selectedValues());
+      return;
+    }
+    // Space — toggle current
+    if (data === " ") {
+      const item = this.items[this.cursor];
+      if (item) item.checked = !item.checked;
+      return;
+    }
+    // Arrow up / k
+    if (data === "\u001b[A" || data === "k") {
+      if (this.cursor > 0) this.cursor--;
+      return;
+    }
+    // Arrow down / j
+    if (data === "\u001b[B" || data === "j") {
+      if (this.cursor < this.items.length - 1) this.cursor++;
+      return;
+    }
+    // Everything else (including "a", "A", bulk-toggle attempts) is a no-op.
+  }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Polyfill for `ctx.ui.multiselect(...)` — a method the dashboard bridge's
+ * `ask_user` tool advertises but which `pi-coding-agent`'s
+ * `ExtensionUIContext` does not expose. Without this, any TUI dispatch of
+ * `method: "multiselect"` crashes with `"ctx.ui.multiselect is not a function"`.
+ *
+ * Fallback chain (introduced by change fix-multiselect-auto-cancel-on-dashboard):
+ *
+ *   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 / 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.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,
+    ): Promise<T>;
+  };
+}
+
+export function polyfillMultiselect(
+  ctx: PolyfillCtx,
+  title: string,
+  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);
+    list.onCancel = () => done(undefined);
+    return list as unknown;
+  });
+}

package/packages/extension/src/server-launcher.ts

@@ -11,6 +11,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import type { DashboardConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { resolveJitiImport } from "@blackbelt-technology/pi-dashboard-shared/resolve-jiti.js";
+import { toFileUrl, shouldUrlWrapEntry } from "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";
 import { isDashboardRunning } from "@blackbelt-technology/pi-dashboard-shared/server-identity.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -77,11 +78,22 @@ export async function launchServer(config: DashboardConfig): Promise<LaunchResul
       );
     } catch { /* if we can't open the log, spawn still works */ }
 
-    // Spawn server via the detached-spawn primitive. resolveJitiImport()
-    // returns a file:// URL (required on Windows for node --import).
+    // Spawn server via the detached-spawn primitive. The loader is always
+    // URL-wrapped (Node needs file:// for --import on Windows drive letters).
+    // The entry is URL-wrapped only on Windows + non-tsx loader (Node parses
+    // drive letters as URL schemes in argv); on POSIX the entry MUST be raw
+    // because jiti's resolver misbehaves on file:// URL entries. See
+    // openspec/changes/archive/2026-04-24-fix-windows-entry-script-url.
+    const loader = resolveJitiImport();
+    const wrapEntry = shouldUrlWrapEntry(loader);
+    // entry is gated by shouldUrlWrapEntry(loader): returns true only on
+    // Windows + non-tsx (where URL wrap is required); false on POSIX
+    // where jiti needs the raw path (file:// URL entries trigger jiti's
+    // `<cwd>/file:/...` misresolution bug).
+    const entry = wrapEntry ? toFileUrl(cliPath) : cliPath;
     const r = await spawnDetached({
       cmd: process.execPath,
-      args: ["--import", resolveJitiImport(), cliPath, ...args],
+      args: ["--import", loader, entry, ...args], // ban:raw-node-import-ok: entry gated by shouldUrlWrapEntry
       env: { ...process.env },
       logFd,
     });