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

package/packages/extension/src/__tests__/server-auto-start.test.ts

@@ -112,10 +112,13 @@ describe("autoStartServer", () => {
 
     const result = await autoStartServer(baseConfig, deps);
 
-    expect(deps.notify).toHaveBeenCalledWith(
-      "Dashboard server failed to start: exited",
-      "warning",
-    );
+    expect(deps.notify).toHaveBeenCalledTimes(1);
+    const [msg, level] = (deps.notify as any).mock.calls[0];
+    expect(msg).toMatch(/Dashboard server failed to start: exited/);
+    // Spec requirement (fix-windows-server-parity): failure notification
+    // MUST include the absolute path to ~/.pi/dashboard/server.log.
+    expect(msg).toMatch(/server\.log/);
+    expect(level).toBe("warning");
     expect(result.server).toBeUndefined();
   });
 
@@ -164,4 +167,92 @@ describe("autoStartServer", () => {
 
     expect(result.server).toEqual({ host: "myhost.local", port: 8000, piPort: 9999 });
   });
+
+  describe("onLaunchStart / onLaunchEnd callbacks", () => {
+    it("fires onLaunchStart then onLaunchEnd(true) when launch succeeds", async () => {
+      const onLaunchStart = vi.fn();
+      const onLaunchEnd = vi.fn();
+      const deps = makeDeps({
+        launchServer: vi.fn().mockResolvedValue({ success: true, message: "ok" }),
+        onLaunchStart,
+        onLaunchEnd,
+      });
+
+      await autoStartServer(baseConfig, deps);
+
+      expect(onLaunchStart).toHaveBeenCalledTimes(1);
+      expect(onLaunchEnd).toHaveBeenCalledTimes(1);
+      expect(onLaunchEnd).toHaveBeenCalledWith(true);
+    });
+
+    it("fires onLaunchStart then onLaunchEnd(false) when launch fails", async () => {
+      const onLaunchStart = vi.fn();
+      const onLaunchEnd = vi.fn();
+      const deps = makeDeps({
+        launchServer: vi.fn().mockResolvedValue({ success: false, message: "boom" }),
+        isDashboardRunning: vi.fn().mockResolvedValue({ running: false }),
+        onLaunchStart,
+        onLaunchEnd,
+      });
+
+      await autoStartServer(baseConfig, deps);
+
+      expect(onLaunchStart).toHaveBeenCalledTimes(1);
+      expect(onLaunchEnd).toHaveBeenCalledTimes(1);
+      expect(onLaunchEnd).toHaveBeenCalledWith(false);
+    });
+
+    it("fires onLaunchEnd(true) when launch fails but recheck finds running server", async () => {
+      // Race scenario: another agent started the server during our launch attempt.
+      const onLaunchStart = vi.fn();
+      const onLaunchEnd = vi.fn();
+      const deps = makeDeps({
+        launchServer: vi.fn().mockResolvedValue({ success: false, message: "EADDRINUSE" }),
+        isDashboardRunning: vi.fn()
+          .mockResolvedValueOnce({ running: false })   // before launch
+          .mockResolvedValueOnce({ running: true }),   // after launch (recheck)
+        onLaunchStart,
+        onLaunchEnd,
+      });
+
+      await autoStartServer(baseConfig, deps);
+
+      expect(onLaunchStart).toHaveBeenCalledTimes(1);
+      expect(onLaunchEnd).toHaveBeenCalledWith(true);
+    });
+
+    it("does NOT fire onLaunchStart when mDNS finds a local server (no launch happens)", async () => {
+      const onLaunchStart = vi.fn();
+      const onLaunchEnd = vi.fn();
+      const local: DiscoveredServer = {
+        host: "localhost", port: 8000, piPort: 9999,
+        isLocal: true, source: "mdns",
+      };
+      const deps = makeDeps({
+        discoverDashboard: vi.fn().mockResolvedValue([local]),
+        onLaunchStart,
+        onLaunchEnd,
+      });
+
+      await autoStartServer(baseConfig, deps);
+
+      expect(onLaunchStart).not.toHaveBeenCalled();
+      expect(onLaunchEnd).not.toHaveBeenCalled();
+    });
+
+    it("does NOT fire onLaunchStart when health check finds an already-running server", async () => {
+      const onLaunchStart = vi.fn();
+      const onLaunchEnd = vi.fn();
+      const deps = makeDeps({
+        isDashboardRunning: vi.fn().mockResolvedValue({ running: true }),
+        onLaunchStart,
+        onLaunchEnd,
+      });
+
+      await autoStartServer(baseConfig, deps);
+
+      expect(onLaunchStart).not.toHaveBeenCalled();
+      expect(onLaunchEnd).not.toHaveBeenCalled();
+    });
+  });
 });

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

@@ -17,6 +17,22 @@ describe("server-launcher", () => {
     it("should point to a file that actually exists on disk", () => {
       expect(existsSync(resolveServerCliPath())).toBe(true);
     });
+
+    it("uses require.resolve so it adapts to installed layout", () => {
+      // Regression: the monorepo-relative path math
+      // (`<extension>/../../server/src/cli.ts`) produced
+      // `<scope>/server/src/cli.ts` instead of
+      // `<scope>/pi-dashboard-server/src/cli.ts` when the extension
+      // was installed into `node_modules/@blackbelt-technology/`. The
+      // resolver must locate the server via package name, not sibling
+      // path arithmetic.
+      const cliPath = resolveServerCliPath();
+      // Either layout is fine; we just must NOT produce the broken
+      // `@blackbelt-technology/server/src/cli.ts` shape.
+      expect(cliPath).not.toMatch(/@blackbelt-technology[\\/]+server[\\/]+src[\\/]+cli\.ts$/);
+      // And must land on pi-dashboard-server (installed) or packages/server (dev).
+      expect(cliPath).toMatch(/(pi-dashboard-server|packages[\\/]+server)[\\/]+src[\\/]+cli\.ts$/);
+    });
   });
 
   describe("buildSpawnArgs", () => {

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

@@ -6,7 +6,8 @@
  * register ask_user. Runtime registration bypasses detectExtensionConflicts.
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
+import { polyfillMultiselect } from "./multiselect-polyfill.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Single-question schema arms (reused inside the batch arm's questions array)
@@ -121,7 +122,7 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
     name: "ask_user",
     label: "Ask User",
     description:
-      "Ask the user a question interactively. Use this when you need clarification, confirmation, or a choice from the user before proceeding.",
+      "Ask the user a question interactively. Use this when you need clarification, confirmation, or a choice from the user before proceeding. UI provides a Select all toggle; do not add one.",
     promptSnippet:
       "Ask the user interactive questions (confirm, select, multiselect, input, or batch — multiple related questions at once)",
     promptGuidelines: [
@@ -254,7 +255,7 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
                     `ask_user batch: sub-question method "multiselect" requires a non-empty "options" array.`,
                   );
                 }
-                answer = await (ctx.ui as any).multiselect(subTitle, opts, subMsg);
+                answer = await polyfillMultiselect(ctx, subTitle, opts, subMsg);
                 break;
               }
               case "input":
@@ -336,7 +337,7 @@ export function registerAskUserTool(pi: ExtensionAPI): void {
           result = await ctx.ui.select(title, options, msgOpts);
           break;
         case "multiselect":
-          result = await (ctx.ui as any).multiselect(title, options, msgOpts);
+          result = await polyfillMultiselect(ctx, title, options, msgOpts);
           break;
         case "input":
           result = await ctx.ui.input(title, params.placeholder, msgOpts);

package/packages/extension/src/bridge.ts

@@ -5,6 +5,7 @@
  * forwards all pi events, and relays commands back.
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Loader } from "@mariozechner/pi-tui";
 import { ConnectionManager } from "./connection.js";
 import { detectSessionSource } from "./source-detector.js";
 import { mapEventToProtocol } from "./event-forwarder.js";
@@ -25,7 +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 { activate as activateProviderRegister, onProviderChanged } from "./provider-register.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";
 import { scanChildProcesses } from "./process-scanner.js";
@@ -185,6 +186,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[]) => {
@@ -216,6 +272,17 @@ function initBridge(pi: ExtensionAPI) {
       // Reload auth credentials when dashboard notifies of changes
       if (msg.type === "credentials_updated") {
         try {
+          // Hot-reload providers.json diff BEFORE refreshing the registry,
+          // so any newly added providers are registered before getAvailable() runs.
+          const diff = await reloadProviders(pi).catch((err) => {
+            console.error("[dashboard] reloadProviders failed:", err);
+            return { added: [], removed: [], changed: [] };
+          });
+          if (diff.added.length || diff.removed.length || diff.changed.length) {
+            console.log(
+              `[dashboard] hot-reloaded providers: added=${JSON.stringify(diff.added)} removed=${JSON.stringify(diff.removed)} changed=${JSON.stringify(diff.changed)}`,
+            );
+          }
           cachedModelRegistry?.authStorage?.reload?.();
           cachedModelRegistry?.refresh?.();
         } catch (err) { console.error("[dashboard] credentials reload failed:", err); }
@@ -600,30 +667,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);
@@ -682,6 +772,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);
@@ -951,17 +1050,72 @@ function initBridge(pi: ExtensionAPI) {
     }
 
     // Discover or auto-start server (non-blocking — connection will reconnect)
+    //
+    // When a real launchServer() is about to run (not on mDNS/health-check
+    // paths), mount an animated TUI widget above the editor using pi-tui's
+    // Loader (a real Component, self-animating at 80ms, like pi-flows'
+    // architect-widget). The previous implementation used
+    // ctx.ui.setStatus(...) which only writes a footer string and relies on
+    // the TUI render loop being ticked elsewhere — on the cold-start path
+    // nothing else requests renders, so the spinner never animated and often
+    // never appeared. setWidget(key, factory, {placement:"aboveEditor"}) gives
+    // us a managed component that owns its own render loop and is always
+    // visible while the launch is in flight.
+    let spinnerTimer: NodeJS.Timeout | null = null;
+    let spinnerStart = 0;
+    let activeLoader: Loader | null = null;
+    const stopSpinner = () => {
+      if (spinnerTimer) {
+        clearInterval(spinnerTimer);
+        spinnerTimer = null;
+      }
+      activeLoader = null;
+      ctx.ui.setWidget("pi-dashboard-launch", undefined);
+    };
     autoStartServer(config, {
       discoverDashboard,
       isDashboardRunning,
       launchServer,
       notify: (msg, level) => ctx.ui.notify(msg, level),
+      onLaunchStart: () => {
+        spinnerStart = Date.now();
+        const buildMessage = () => {
+          const elapsed = Math.floor((Date.now() - spinnerStart) / 1000);
+          return `starting dashboard server … (${elapsed}s)`;
+        };
+        ctx.ui.setWidget(
+          "pi-dashboard-launch",
+          (tui: unknown, theme: { fg: (role: string, s: string) => string }) => {
+            const loader = new Loader(
+              tui as ConstructorParameters<typeof Loader>[0],
+              (s: string) => theme.fg("accent", s),
+              (s: string) => theme.fg("muted", s),
+              buildMessage(),
+            );
+            activeLoader = loader;
+            // Loader has stop() but no dispose(); wire dispose so that
+            // setExtensionWidget's teardown stops the 80ms animation interval.
+            (loader as Loader & { dispose?: () => void }).dispose = () => loader.stop();
+            return loader;
+          },
+          { placement: "aboveEditor" },
+        );
+        // Refresh the elapsed-seconds label every second. Frame animation is
+        // driven by the Loader's own 80ms interval.
+        spinnerTimer = setInterval(() => {
+          activeLoader?.setMessage(buildMessage());
+        }, 1000);
+      },
+      onLaunchEnd: () => {
+        stopSpinner();
+      },
     }).then((result) => {
+      stopSpinner(); // safety net — covers onLaunchEnd not firing
       if (result.server && result.server.piPort !== config.piPort) {
         // Server found on a different piPort than configured — update connection URL
         connection.updateUrl(`ws://${result.server.host === 'localhost' ? 'localhost' : result.server.host}:${result.server.piPort}`);
       }
-    }).catch(() => {});
+    }).catch(() => { stopSpinner(); });
 
     // Send initial git info
     sendGitInfoIfChanged(ctx.cwd);

package/packages/extension/src/dev-build.ts

@@ -2,7 +2,7 @@
  * Dev build-on-reload helper.
  * Builds the Vite client and requests server shutdown.
  */
-import { execSync as defaultExecSync } from "node:child_process";
+import { execSync as defaultExecSync } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 
 export interface DevBuildOptions {
   packageRoot: string;

package/packages/extension/src/git-info.ts

@@ -1,7 +1,11 @@
 /**
  * Git info gathering — detects branch, remote URL, and PR number.
+ * Delegates to the shared git tool module so there's no inline execSync
+ * and every call benefits from the runner's safety defaults (windowsHide,
+ * timeout, tolerated exit codes).
+ * See change: platform-command-executor.
  */
-import { execSync } from "node:child_process";
+import * as git from "@blackbelt-technology/pi-dashboard-shared/platform/git.js";
 import { buildGitLinks, type GitLinks } from "./git-link-builder.js";
 
 export interface GitInfo {
@@ -11,39 +15,25 @@ export interface GitInfo {
   gitPrUrl?: string;
 }
 
-/** Run a shell command and return trimmed stdout, or undefined on failure. */
-function runGit(command: string, cwd: string): string | undefined {
-  try {
-    return execSync(command, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 }).trim();
-  } catch {
-    return undefined;
-  }
-}
-
 /** Detect the current git branch. Returns short SHA for detached HEAD. */
 export function detectBranch(cwd: string): string | undefined {
-  const ref = runGit("git rev-parse --abbrev-ref HEAD", cwd);
+  const ref = git.currentBranchOr({ cwd });
   if (!ref) return undefined;
   if (ref === "HEAD") {
     // Detached HEAD — return short commit SHA
-    return runGit("git rev-parse --short HEAD", cwd) ?? "HEAD";
+    return git.headShaOr({ cwd, short: true }) ?? "HEAD";
   }
   return ref;
 }
 
 /** Detect the remote origin URL. */
 export function detectRemoteUrl(cwd: string): string | undefined {
-  return runGit("git remote get-url origin", cwd);
+  return git.remoteUrlOr({ cwd });
 }
 
 /** Detect the PR number via gh CLI (best effort). */
 export function detectPrNumber(cwd: string): number | undefined {
-  const result = runGit("gh pr view --json number -q .number", cwd);
-  if (result) {
-    const num = parseInt(result, 10);
-    if (!isNaN(num)) return num;
-  }
-  return undefined;
+  return git.prNumberOr({ cwd });
 }
 
 /** Gather all git info for a directory. Returns undefined if not a git repo. */

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.
+  }
+}