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

package/packages/extension/src/__tests__/provider-register-reload.test.ts

@@ -0,0 +1,394 @@
+/**
+ * Tests for the provider-register hot-reload path.
+ *
+ * `reloadProviders(pi)` diffs the current providers.json against a
+ * last-registered snapshot and calls pi.registerProvider / pi.unregisterProvider
+ * as needed. Async model discovery is stubbed via a fetch mock.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// We re-import the module fresh in each test so module-level `lastRegistered`
+// state starts empty.
+async function importFresh() {
+  vi.resetModules();
+  return (await import("../provider-register.js")) as typeof import("../provider-register.js");
+}
+
+function makeMockPi() {
+  const registerProvider = vi.fn();
+  const unregisterProvider = vi.fn();
+  const pi = {
+    registerProvider,
+    unregisterProvider,
+    events: { on: vi.fn(), emit: vi.fn() },
+    on: vi.fn(),
+  } as any;
+  return { pi, registerProvider, unregisterProvider };
+}
+
+function writeProvidersJson(home: string, providers: Record<string, any>) {
+  const dir = join(home, ".pi", "agent");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "providers.json"),
+    JSON.stringify({ providers }, null, 2),
+    "utf-8",
+  );
+}
+
+describe("reloadProviders", () => {
+  let tmpHome: string;
+  const originalHome = process.env.HOME;
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    tmpHome = mkdtempSync(join(tmpdir(), "provider-reload-"));
+    process.env.HOME = tmpHome;
+    // Stub fetch to return 2 models so discovery succeeds cheaply
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ data: [{ id: "m1" }, { id: "m2" }] }), { status: 200 }),
+    ) as any;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    process.env.HOME = originalHome;
+    rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it("adds a new provider when providers.json gains an entry (snapshot was empty)", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider, unregisterProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": {
+        baseUrl: "https://api.example.com/v1",
+        apiKey: "sk-abc",
+        api: "openai-completions",
+      },
+    });
+
+    const diff = await mod.reloadProviders(pi);
+    expect(diff.added).toEqual(["my-llm"]);
+    expect(diff.removed).toEqual([]);
+    expect(diff.changed).toEqual([]);
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+    expect(registerProvider).toHaveBeenCalledWith("my-llm", expect.objectContaining({
+      baseUrl: "https://api.example.com/v1",
+      api: "openai-completions",
+    }));
+    expect(unregisterProvider).not.toHaveBeenCalled();
+  });
+
+  it("removes a provider when its entry disappears from providers.json", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider, unregisterProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "k", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+
+    writeProvidersJson(tmpHome, {});
+    const diff = await mod.reloadProviders(pi);
+
+    expect(diff.removed).toEqual(["my-llm"]);
+    expect(diff.added).toEqual([]);
+    expect(unregisterProvider).toHaveBeenCalledTimes(1);
+    expect(unregisterProvider).toHaveBeenCalledWith("my-llm");
+  });
+
+  it("re-registers (unregister then register) when baseUrl changes", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider, unregisterProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://old.example.com/v1", apiKey: "k", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://new.example.com/v1", apiKey: "k", api: "openai-completions" },
+    });
+    const diff = await mod.reloadProviders(pi);
+
+    expect(diff.changed).toEqual(["my-llm"]);
+    // unregister must be called before the second register
+    const unregOrder = unregisterProvider.mock.invocationCallOrder[0];
+    const reg2Order = registerProvider.mock.invocationCallOrder[1];
+    expect(unregOrder).toBeLessThan(reg2Order);
+    expect(registerProvider).toHaveBeenLastCalledWith(
+      "my-llm",
+      expect.objectContaining({ baseUrl: "https://new.example.com/v1" }),
+    );
+  });
+
+  it("unchanged providers.json produces no register/unregister calls on second reload", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider, unregisterProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "k", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+    registerProvider.mockClear();
+    unregisterProvider.mockClear();
+
+    const diff = await mod.reloadProviders(pi);
+    expect(diff.added).toEqual([]);
+    expect(diff.removed).toEqual([]);
+    expect(diff.changed).toEqual([]);
+    expect(registerProvider).not.toHaveBeenCalled();
+    expect(unregisterProvider).not.toHaveBeenCalled();
+  });
+
+  it("malformed providers.json returns empty diff and does not throw", async () => {
+    const mod = await importFresh();
+    const { pi } = makeMockPi();
+
+    const dir = join(tmpHome, ".pi", "agent");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "providers.json"), "not valid json {", "utf-8");
+
+    await expect(mod.reloadProviders(pi)).resolves.toEqual({
+      added: [],
+      removed: [],
+      changed: [],
+    });
+  });
+
+  it("treats apiKey change as 'changed'", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider, unregisterProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "old", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "new", api: "openai-completions" },
+    });
+    const diff = await mod.reloadProviders(pi);
+    expect(diff.changed).toEqual(["my-llm"]);
+    expect(unregisterProvider).toHaveBeenCalledWith("my-llm");
+  });
+
+  it("treats api type change as 'changed'", async () => {
+    const mod = await importFresh();
+    const { pi } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "k", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://x", apiKey: "k", api: "openai-responses" },
+    });
+    const diff = await mod.reloadProviders(pi);
+    expect(diff.changed).toEqual(["my-llm"]);
+  });
+
+  // ── input capability default (see change: enable-image-input-custom-providers) ─────
+  // Every discovered model must advertise `input: ["text", "image"]` so pi-ai does
+  // not strip pasted images via `downgradeUnsupportedImages` before the request
+  // leaves the bridge. This guards both the initial-registration path and the
+  // reloadProviders() re-register path.
+
+  it("discovered models default to input: [\"text\", \"image\"] on fresh register", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider } = makeMockPi();
+
+    writeProvidersJson(tmpHome, {
+      "my-llm": {
+        baseUrl: "https://api.example.com/v1",
+        apiKey: "sk-abc",
+        api: "openai-completions",
+      },
+    });
+
+    await mod.reloadProviders(pi);
+
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+    const [, config] = registerProvider.mock.calls[0];
+    expect(Array.isArray(config.models)).toBe(true);
+    expect(config.models.length).toBe(2); // two models from the fetch stub
+    for (const m of config.models) {
+      expect(m.input).toEqual(["text", "image"]);
+    }
+  });
+
+  it("re-registered models (after reload diff) retain input: [\"text\", \"image\"]", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider } = makeMockPi();
+
+    // Initial register
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://old.example.com/v1", apiKey: "k", api: "openai-completions" },
+    });
+    await mod.reloadProviders(pi);
+
+    // Change baseUrl → triggers unregister + re-register
+    writeProvidersJson(tmpHome, {
+      "my-llm": { baseUrl: "https://new.example.com/v1", apiKey: "k", api: "openai-completions" },
+    });
+    const diff = await mod.reloadProviders(pi);
+    expect(diff.changed).toEqual(["my-llm"]);
+
+    // Second registerProvider call is the re-register; must carry same input default
+    expect(registerProvider).toHaveBeenCalledTimes(2);
+    const [, secondConfig] = registerProvider.mock.calls[1];
+    for (const m of secondConfig.models) {
+      expect(m.input).toEqual(["text", "image"]);
+    }
+  });
+
+  // ── model metadata enrichment (see change: enrich-custom-provider-model-metadata) ──
+  // registerEntry() resolves per-model metadata via enrichModelMetadata() which
+  // consults pi-ai's bundled catalog. These tests verify the end-to-end path:
+  // discovered id → catalog match → registerProvider receives accurate fields.
+
+  it("captures ctx.modelRegistry from session_start and re-registers providers with enriched metadata", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider } = makeMockPi();
+
+    // Capture the session_start handler registered by activate().
+    const handlers = new Map<string, (event: any, ctx: any) => Promise<void> | void>();
+    pi.on = vi.fn((event: string, handler: any) => {
+      handlers.set(event, handler);
+    });
+
+    // Fake pi's ModelRegistry. `find(provider, id)` returns Opus 4.7's real
+    // metadata for the anthropic entry, simulating what pi passes via
+    // ctx.modelRegistry at session_start.
+    const fakeRegistry = {
+      find: vi.fn((provider: string, id: string) => {
+        if (provider === "anthropic" && id === "claude-opus-4-7") {
+          return {
+            contextWindow: 1_000_000,
+            maxTokens: 128_000,
+            reasoning: true,
+            cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+            input: ["text", "image"],
+          };
+        }
+        return null;
+      }),
+    };
+
+    // Fetch mock advertises the real model id.
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({ data: [{ id: "cc/claude-opus-4-7" }] }),
+        { status: 200 },
+      ),
+    ) as any;
+
+    writeProvidersJson(tmpHome, {
+      proxy: {
+        baseUrl: "https://llmproxy.example.com/v1",
+        apiKey: "sk-test",
+        api: "anthropic-messages",
+      },
+    });
+
+    // 1) activate() registers the provider BEFORE ctx.modelRegistry is
+    //    available — first registration hits the fallback path.
+    mod.activate(pi);
+    // Wait a microtask for the fire-and-forget registerEntry inside activate.
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(registerProvider).toHaveBeenCalledTimes(1);
+    const firstCall = registerProvider.mock.calls[0];
+    expect(firstCall[1].models[0].contextWindow).toBe(200_000); // fallback
+
+    // 2) Fire session_start with ctx.modelRegistry — the handler captures it
+    //    and re-registers all known providers with the enriched metadata.
+    const sessionStartHandler = handlers.get("session_start");
+    expect(sessionStartHandler).toBeDefined();
+    await sessionStartHandler!({ type: "session_start" }, {
+      ui: { notify: vi.fn() },
+      modelRegistry: fakeRegistry,
+      model: undefined,
+    });
+
+    // 3) The re-registration should have issued a second registerProvider
+    //    call, this time with the catalog-enriched metadata.
+    expect(registerProvider).toHaveBeenCalledTimes(2);
+    const secondCall = registerProvider.mock.calls[1];
+    const [name, config] = secondCall;
+    expect(name).toBe("proxy");
+    const [opus] = config.models;
+    expect(opus.id).toBe("cc/claude-opus-4-7");
+    expect(opus.contextWindow).toBe(1_000_000);
+    expect(opus.maxTokens).toBe(128_000);
+    expect(opus.reasoning).toBe(true);
+    expect(opus.cost.input).toBe(5);
+    expect(opus.cost.output).toBe(25);
+    // Probed with prefix-stripped bare id under `anthropic`.
+    expect(fakeRegistry.find).toHaveBeenCalledWith("anthropic", "claude-opus-4-7");
+  });
+
+  it("without modelRegistry (never captured), discovered models fall back to api-appropriate defaults", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider } = makeMockPi();
+
+    // No session_start fires — modelRegistryRef stays null and the probe is
+    // null, so every discovered id hits the fallback table.
+    globalThis.fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({ data: [{ id: "cc/claude-opus-4-7" }] }),
+        { status: 200 },
+      ),
+    ) as any;
+
+    writeProvidersJson(tmpHome, {
+      proxy: {
+        baseUrl: "https://llmproxy.example.com/v1",
+        apiKey: "sk-test",
+        api: "anthropic-messages",
+      },
+    });
+
+    await mod.reloadProviders(pi);
+
+    const [, config] = registerProvider.mock.calls[0];
+    const [opus] = config.models;
+    // anthropic-messages fallback: 200k / 64k / no reasoning / zero cost / text+image.
+    expect(opus.contextWindow).toBe(200_000);
+    expect(opus.maxTokens).toBe(64_000);
+    expect(opus.reasoning).toBe(false);
+    expect(opus.input).toEqual(["text", "image"]);
+  });
+
+  it("discovered unknown model falls back to api-appropriate defaults (openai-completions → 128k)", async () => {
+    const mod = await importFresh();
+    const { pi, registerProvider } = makeMockPi();
+
+    // Default beforeEach fetch stub returns `m1` and `m2` — neither exists in catalog.
+    writeProvidersJson(tmpHome, {
+      "my-llm": {
+        baseUrl: "https://api.example.com/v1",
+        apiKey: "sk-abc",
+        api: "openai-completions",
+      },
+    });
+
+    await mod.reloadProviders(pi);
+
+    const [, config] = registerProvider.mock.calls[0];
+    for (const m of config.models) {
+      expect(m.contextWindow).toBe(128_000);
+      expect(m.maxTokens).toBe(16_384);
+      expect(m.reasoning).toBe(false);
+      expect(m.cost).toEqual({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+      expect(m.input).toEqual(["text", "image"]);
+    }
+  });
+});

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/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";
@@ -216,6 +217,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); }
@@ -951,17 +963,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;