@blackbelt-technology/pi-agent-dashboard 0.5.1 → 0.5.2

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

@@ -0,0 +1,78 @@
+/**
+ * Pins the Bridge → `launchDashboardServer` forwarding contract: the
+ * extension's `launchServer` must always pass `starter: "Bridge"`,
+ * `stdio: "ignore"`, and `healthTimeoutMs: 2_000`. The shared
+ * launcher is mocked so this test never spawns a real server.
+ *
+ * See change: unify-server-launch-ts-loader (§3.1.2).
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { launchDashboardServer } from "@blackbelt-technology/pi-dashboard-shared/server-launcher.js";
+
+const { launchSpy } = vi.hoisted(() => ({
+  launchSpy: vi.fn<typeof launchDashboardServer>(async () => ({ childPid: 1, reportedPid: 1, healthOk: true as const })),
+}));
+
+vi.mock("@blackbelt-technology/pi-dashboard-shared/server-launcher.js", () => ({
+  launchDashboardServer: launchSpy,
+  JitiNotFoundError: class JitiNotFoundError extends Error {},
+  PortConflictError: class PortConflictError extends Error {},
+  EarlyExitError: class EarlyExitError extends Error { code: number | null = null; },
+}));
+
+import { launchServer } from "../server-launcher.js";
+
+const cfg = {
+  port: 3000,
+  piPort: 4000,
+  autoStart: true,
+  autoShutdown: true,
+  shutdownIdleSeconds: 300,
+  spawnStrategy: "tmux" as const,
+  tunnel: { enabled: true },
+  devBuildOnReload: false,
+  memoryLimits: { maxEventsPerSession: 5000, maxStringFieldSize: 0, maxWsBufferBytes: 4194304 },
+  editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+  defaultModel: "",
+  trustedNetworks: [],
+  resolvedTrustedNetworks: [],
+  cors: { allowedOrigins: [] },
+  electronMode: false,
+} as any;
+
+beforeEach(() => {
+  launchSpy.mockClear();
+  launchSpy.mockResolvedValue({ childPid: 1, reportedPid: 1, healthOk: true } as any);
+});
+
+describe("Bridge launchServer → launchDashboardServer forwarding", () => {
+  it("passes starter:Bridge + stdio:ignore + 2s health timeout + port", async () => {
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(true);
+    expect(launchSpy).toHaveBeenCalledOnce();
+    const opts = launchSpy.mock.calls[0]![0]!;
+    expect(opts.starter).toBe("Bridge");
+    expect(opts.stdio).toBe("ignore");
+    expect(opts.healthTimeoutMs).toBe(2000);
+    expect(opts.port).toBe(3000);
+    expect(opts.extraArgs).toEqual(["--port", "3000", "--pi-port", "4000"]);
+  });
+
+  it("maps JitiNotFoundError to a failed LaunchResult (no throw)", async () => {
+    const { JitiNotFoundError } = await import("@blackbelt-technology/pi-dashboard-shared/server-launcher.js");
+    launchSpy.mockRejectedValueOnce(new JitiNotFoundError("loader missing"));
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(false);
+    expect(r.message).toContain("loader missing");
+  });
+
+  it("maps EarlyExitError to a failed LaunchResult mentioning the exit code", async () => {
+    const { EarlyExitError } = await import("@blackbelt-technology/pi-dashboard-shared/server-launcher.js");
+    const err = new (EarlyExitError as unknown as new (...args: unknown[]) => Error & { code: number })();
+    err.code = 17;
+    launchSpy.mockRejectedValueOnce(err);
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/code=17/);
+  });
+});

package/packages/extension/src/bridge-context.ts

@@ -40,9 +40,11 @@ export interface BridgeContext {
   hasRegisteredOnce: boolean;
 }
 
-// Commands that the dashboard handles natively with superior UX.
-// These are filtered from the command list sent to dashboard clients.
-const DASHBOARD_NATIVE_COMMANDS = new Set(["roles"]);
+// Commands that the dashboard handles natively with superior UX, filtered from
+// the command list sent to dashboard clients AND from extension-slash detection.
+// Current set: { "roles" }. Bridge-registered `__dashboard_reload` is filtered
+// separately by the `__`-prefix rule. See change: fix-extension-slash-commands-in-dashboard.
+export const DASHBOARD_NATIVE_COMMANDS = new Set(["roles"]);
 
 /** Filter out hidden commands (names starting with __) and dashboard-native commands from commands list */
 export function filterHiddenCommands(commands: any[]): any[] {
@@ -52,6 +54,68 @@ export function filterHiddenCommands(commands: any[]): any[] {
   );
 }
 
+/**
+ * Pure predicate: does `text` name an extension-registered slash command?
+ *
+ * Returns true iff:
+ *   - `text` starts with `/` and contains no embedded newline
+ *   - the token after `/` (up to first space or end) appears in `commandList`
+ *     with `source === "extension"`
+ *   - that token is NOT in `DASHBOARD_NATIVE_COMMANDS` (and not `__`-prefixed)
+ *
+ * Pure: no pi calls, no mutation. See change: fix-extension-slash-commands-in-dashboard.
+ */
+export function isExtensionSlashCommand(
+  text: string,
+  commandList: ReadonlyArray<{ name: string; source?: string }>,
+): boolean {
+  if (typeof text !== "string" || !text.startsWith("/")) return false;
+  if (text.includes("\n")) return false;
+  const rest = text.slice(1);
+  const spaceIdx = rest.indexOf(" ");
+  const cmdName = spaceIdx === -1 ? rest : rest.slice(0, spaceIdx);
+  if (!cmdName) return false;
+  if (cmdName.startsWith("__")) return false;
+  if (DASHBOARD_NATIVE_COMMANDS.has(cmdName)) return false;
+  return commandList.some((c) => c?.name === cmdName && c?.source === "extension");
+}
+
+/**
+ * Feature-detect upstream `pi.dispatchCommand(text, opts)` (pi 0.71+).
+ * Returns true iff the field is a function on the supplied object.
+ * See change: fix-extension-slash-commands-in-dashboard.
+ */
+export function hasDispatchCommand(pi: unknown): boolean {
+  return typeof (pi as any)?.dispatchCommand === "function";
+}
+
+/**
+ * Pure predicate: is this bridge running inside a dashboard-spawned
+ * headless `pi --mode rpc` session?
+ *
+ * Both probes MUST be true:
+ *  1. `process.env.PI_DASHBOARD_SPAWNED === "1"` (set by
+ *     `process-manager.ts::buildSpawnEnv` for every dashboard-spawned session).
+ *  2. `process.argv` contains `--mode` adjacent to `rpc`.
+ *
+ * Either alone is insufficient: env-only matches dashboard-spawned tmux
+ * sessions; argv-only matches non-dashboard RPC invocations.
+ *
+ * Optional `env` / `argv` parameters exist purely for unit testing
+ * (defaulting to the live process state). See change:
+ * add-rpc-stdin-dispatch-with-keeper-sidecar (task 7.1).
+ */
+export function isHeadlessRpcSession(
+  env: NodeJS.ProcessEnv = process.env,
+  argv: ReadonlyArray<string> = process.argv,
+): boolean {
+  if (env.PI_DASHBOARD_SPAWNED !== "1") return false;
+  for (let i = 0; i < argv.length - 1; i++) {
+    if (argv[i] === "--mode" && argv[i + 1] === "rpc") return true;
+  }
+  return false;
+}
+
 /** Extract first user message text from session entries */
 export function extractFirstMessage(ctx: any): string | undefined {
   try {

package/packages/extension/src/bridge.ts

@@ -35,6 +35,7 @@ import { startMetricsMonitor, stopMetricsMonitor, collectMetrics } from "./proce
 import { scanChildProcesses } from "./process-scanner.js";
 import type { BridgeContext } from "./bridge-context.js";
 import { filterHiddenCommands, extractFirstMessage, getCurrentModelString } from "./bridge-context.js";
+import { tryDispatchExtensionCommand } from "./slash-dispatch.js";
 import { sendStateSync as _sendStateSync, replaySessionEntries as _replaySessionEntries, handleSessionChange as _handleSessionChange } from "./session-sync.js";
 import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged, sendJjStateIfChanged as _sendJjStateIfChanged, resetReconnectCaches as _resetReconnectCaches } from "./model-tracker.js";
 import { registerFlowEventListeners, FLOW_EVENT_MAP, SUBAGENT_EVENT_MAP } from "./flow-event-wiring.js";
@@ -694,26 +695,37 @@ function initBridge(pi: ExtensionAPI) {
     spawnNew: () => {
       connection.send({ type: "spawn_new_session", sessionId, cwd: process.cwd() });
     },
-    sessionPrompt: (text) => {
-      // Route slash commands: management events, flow:run, then fallback
+    sessionPrompt: async (text) => {
+      // Route slash commands: management events, flow:run, extension dispatch, then fallback.
+      // See change: fix-extension-slash-commands-in-dashboard.
       if (text.startsWith("/") && pi.events) {
         const cmdText = text.slice(1);
         const spaceIdx = cmdText.indexOf(" ");
         const cmdName = spaceIdx === -1 ? cmdText : cmdText.slice(0, spaceIdx);
         const cmdArgs = spaceIdx === -1 ? "" : cmdText.slice(spaceIdx + 1);
 
-        // Flow management commands from buttons use flow_management message type.
-        // Typed /flows:new, /flows:edit, /flows:delete in chat input fall through
-        // to the slash command handler below, which invokes pi's command system
-        // via pi.sendUserMessage (with ui-proxy handling ctx.ui calls).
-
-        // Check if it's a user-defined flow via flow:list-flows
+        // Flow fast-path: typed /<user-defined-flow-name> wins over extension dispatch.
         const flowsList = getFlowsList();
         if (flowsList.some(f => f.name === cmdName)) {
           pi.events.emit("flow:run", { flowName: cmdName, task: cmdArgs.trim() || undefined });
           return;
         }
       }
+
+      // Extension-command dispatch (routing step 9). When matched, the helper
+      // emits its own command_feedback events and we MUST NOT fall through.
+      // The `connection` arg enables Path C (headless RPC → server-routed
+      // dispatch via the keeper UDS); see change:
+      // add-rpc-stdin-dispatch-with-keeper-sidecar.
+      const handled = await tryDispatchExtensionCommand(
+        pi,
+        text,
+        sessionId,
+        (msg) => connection.send(msg),
+        connection,
+      );
+      if (handled) return;
+
       // Fallback: send as user message (template-expanded).
       // Uses deliverAs:followUp so it queues properly when agent is streaming.
       // expandPromptTemplateFromDisk handles skill commands (/skill:xxx) and

package/packages/extension/src/command-handler.ts

@@ -12,6 +12,7 @@ import { killProcessByPgid } from "./process-scanner.js";
 import type { FileEntry, PiSessionInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { filterHiddenCommands } from "./bridge-context.js";
 import { expandPromptTemplateFromDisk } from "./prompt-expander.js";
+import { tryDispatchExtensionCommand } from "./slash-dispatch.js";
 import { buildProviderCatalogue } from "./provider-register.js";
 
 const IGNORE_DIRS = new Set([".git", "node_modules", ".next", "dist", "build", ".cache", "__pycache__", ".venv"]);
@@ -161,8 +162,14 @@ export function createCommandHandler(
     spawnNew?: () => void;
     /** Switch model via pi.setModel() */
     setModel?: (provider: string, modelId: string) => Promise<void>;
-    /** Route slash commands through session.prompt() */
-    sessionPrompt?: (text: string) => void;
+    /**
+     * Route slash commands through pi's command system. May be sync or async.
+     * In bridge wiring this also runs the extension-command dispatch branch
+     * (see slash-dispatch.ts). The handler awaits the result so command_feedback
+     * events emitted by the dispatch path arrive before this turn returns.
+     * See change: fix-extension-slash-commands-in-dashboard.
+     */
+    sessionPrompt?: (text: string) => void | Promise<void>;
   },
 ): CommandHandler {
   const getSessionId = typeof sessionIdOrGetter === "function" ? sessionIdOrGetter : () => sessionIdOrGetter;
@@ -292,19 +299,29 @@ export function createCommandHandler(
 
           if (parsed.type === "slash") {
             if (options?.sessionPrompt) {
-              options.sessionPrompt(parsed.text);
+              // sessionPrompt (bridge) owns slash-dispatch + flow fast-path +
+              // template expansion. It also owns command_feedback emission for
+              // extension-command dispatch. Do NOT emit completed here — would
+              // duplicate the dispatch path's terminal event.
+              // See change: fix-extension-slash-commands-in-dashboard.
+              await options.sessionPrompt(parsed.text);
             } else {
-              pi.sendUserMessage(parsed.text);
+              // Test / non-bridge callers: apply the extension-command dispatch
+              // branch inline before falling through to sendUserMessage. Keeps
+              // both call sites in lockstep per spec routing-step 9.
+              const handled = await tryDispatchExtensionCommand(
+                pi,
+                parsed.text,
+                sessionId,
+                options?.eventSink,
+              );
+              if (!handled) {
+                // sendUserMessage exempt from gating: only typed single-line
+                // slashes that are NOT extension commands reach this — i.e.
+                // skills, prompt templates, unrecognized slashes.
+                pi.sendUserMessage(parsed.text);
+              }
             }
-            options?.eventSink?.({
-              type: "event_forward",
-              sessionId,
-              event: {
-                eventType: "command_feedback",
-                timestamp: Date.now(),
-                data: { command: parsed.text, status: "completed" },
-              },
-            });
             return undefined;
           }
 
@@ -312,6 +329,12 @@ export function createCommandHandler(
           // Multi-line slash commands (e.g. "/skill:foo\nuser text") are classified as
           // passthrough by parseSendPrompt to preserve images (the slash route strips them),
           // so we expand prompt templates / skills here before sending.
+          //
+          // sendUserMessage exempt from extension-dispatch gating: this path handles
+          // multi-line slashes and image-bearing messages. Per spec, only typed
+          // single-line slash text gates through extension dispatch — multi-line and
+          // image-bearing messages go raw to the LLM as before.
+          // See change: fix-extension-slash-commands-in-dashboard.
           let outgoing = msg.text;
           if (outgoing.startsWith("/")) {
             outgoing = expandPromptTemplateFromDisk(outgoing, process.cwd(), pi);

package/packages/extension/src/prompt-expander.ts

@@ -6,7 +6,7 @@
  * by reading template/skill files directly and expanding them.
  */
 import { readFileSync, existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { readdirSync, statSync } from "node:fs";
 import { buildSkillBlock } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
@@ -54,6 +54,69 @@ function readTemplate(filePath: string): string {
   return match ? match[1].trim() : content.trim();
 }
 
+/**
+ * Build the deduped, ordered list of candidate names for `:` ↔ `-` alias resolution.
+ * Original form always comes first, preserving the user's typed punctuation as
+ * authoritative intent (see design Decision 4: original-form-first precedence).
+ */
+function candidateNames(name: string): string[] {
+  const variants = new Set<string>();
+  variants.add(name);
+  if (name.includes(":")) variants.add(name.replace(/:/g, "-"));
+  if (name.includes("-")) variants.add(name.replace(/-/g, ":"));
+  return [...variants];
+}
+
+type Resolution = {
+  filePath: string;
+  source: "prompt" | "skill";
+  resolvedName: string;
+};
+
+/**
+ * Resolve `templateName` against (a) local prompt/skill scan and (b) pi.getCommands().
+ *
+ * Probe order is OUTER-loop over candidate-name variants, INNER probe over the
+ * three stores. This guarantees original-form-first precedence: every store is
+ * consulted on the typed form before any remapped variant is consulted on any
+ * store. See design Decision 4.
+ */
+function resolveTemplate(
+  templateName: string,
+  templates: Map<string, string>,
+  pi: any | undefined,
+): Resolution | null {
+  for (const cand of candidateNames(templateName)) {
+    // Step 1: local-scan prompt/skill key (may be `skill:<dir>` for SKILL.md dirs).
+    const local = templates.get(cand);
+    if (local) {
+      return {
+        filePath: local,
+        source: cand.startsWith("skill:") ? "skill" : "prompt",
+        resolvedName: cand,
+      };
+    }
+    // Step 2: local SKILL.md directory keyed as `skill:<cand>`.
+    const localSkill = templates.get(`skill:${cand}`);
+    if (localSkill) {
+      return { filePath: localSkill, source: "skill", resolvedName: cand };
+    }
+    // Step 3: pi.getCommands() registry skill.
+    if (pi?.getCommands) {
+      try {
+        const commands = pi.getCommands();
+        const skill = commands.find(
+          (c: any) => c.name === cand && c.source === "skill" && c.path,
+        );
+        if (skill?.path && existsSync(skill.path)) {
+          return { filePath: skill.path, source: "skill", resolvedName: cand };
+        }
+      } catch { /* ignore */ }
+    }
+  }
+  return null;
+}
+
 /**
  * Expand a slash command by finding and reading the prompt template from disk.
  * Returns the expanded text, or the original text if no template found.
@@ -73,45 +136,21 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
   const argsString = m?.[2] ?? "";
 
   const templates = findPromptTemplates(cwd);
-  let filePath = templates.get(templateName);
-
-  // Support colon as alias for hyphen (e.g. /opsx:continue → opsx-continue)
-  if (!filePath && templateName.includes(":")) {
-    filePath = templates.get(templateName.replace(/:/g, "-"));
-  }
-
-  // Fallback: check pi.getCommands() for globally installed skills and package skills
-  // that aren't in the local .pi/skills/ directory.
-  if (!filePath && pi?.getCommands) {
-    try {
-      const commands = pi.getCommands();
-      const skill = commands.find(
-        (c: any) => c.name === templateName && c.source === "skill" && c.path,
-      );
-      if (skill?.path && existsSync(skill.path)) {
-        filePath = skill.path;
-      }
-    } catch { /* ignore */ }
-  }
-
-  if (!filePath) return text;
+  const resolution = resolveTemplate(templateName, templates, pi);
+  if (!resolution) return text;
 
   try {
-    const content = readTemplate(filePath);
+    const content = readTemplate(resolution.filePath);
 
-    // Skill detection: either the local-scan key starts with `skill:` or the
-    // pi.getCommands() fallback resolved a command whose `source === "skill"`
-    // (we re-check below). Skill expansions wrap in pi's `<skill>` envelope so
-    // the dashboard ingress path is byte-identical to pi's own _expandSkillCommand,
-    // which lets the client and server recover the slash-command form.
-    // See change: render-skill-invocations-collapsibly.
-    const isSkill = isSkillResolution(templateName, filePath, pi);
-    if (isSkill) {
-      const bareName = templateName.replace(/^skill:/, "");
+    if (resolution.source === "skill") {
+      // Strip leading `skill:` prefix (only present for local-scan step-1 hits
+      // whose key was `skill:<dir>`); registry hits and step-2 hits already
+      // hold the bare name.
+      const bareName = resolution.resolvedName.replace(/^skill:/, "");
       return buildSkillBlock({
         name: bareName,
-        filePath,
-        baseDir: dirname(filePath),
+        filePath: resolution.filePath,
+        baseDir: dirname(resolution.filePath),
         body: content,
         userArgs: argsString || undefined,
       });
@@ -126,31 +165,3 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
     return text;
   }
 }
-
-/**
- * Detect whether the resolved `filePath` came from a skill source.
- *
- * The local-scan key tells us directly when it starts with `skill:`. For the
- * pi.getCommands() fallback we re-query and check `source === "skill"` against
- * the same templateName.
- */
-function isSkillResolution(
-  templateName: string,
-  filePath: string,
-  pi: any | undefined,
-): boolean {
-  if (templateName.startsWith("skill:")) return true;
-  // The colon-alias path (e.g. /opsx:continue) maps to a hyphen filename and is
-  // a prompt template, not a skill. Skills always use the `skill:` prefix in
-  // both the local scan and pi.getCommands().
-  if (!pi?.getCommands) return false;
-  try {
-    const commands = pi.getCommands();
-    const match = commands.find(
-      (c: any) => c.name === templateName && c.source === "skill" && c.path === filePath,
-    );
-    return !!match;
-  } catch {
-    return false;
-  }
-}

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

@@ -3,16 +3,16 @@
  * The spawned server runs in foreground mode (no subcommand) and writes
  * its own PID file at ~/.pi/dashboard/server.pid.
  */
-import { spawnDetached, waitForReady } from "@blackbelt-technology/pi-dashboard-shared/platform/detached-spawn.js";
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 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";
+import {
+  launchDashboardServer,
+  JitiNotFoundError,
+  PortConflictError,
+  EarlyExitError,
+} from "@blackbelt-technology/pi-dashboard-shared/server-launcher.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -74,82 +74,43 @@ export function buildSpawnArgs(config: DashboardConfig): string[] {
 
 /**
  * Launch the dashboard server as a detached background process.
- * Returns success/failure after a brief wait to detect early crashes.
+ * Delegates to the shared `launchDashboardServer` primitive which owns
+ * loader resolution, argv shape, env merge, log-file policy, and
+ * readiness polling (see `packages/shared/src/server-launcher.ts`).
+ *
+ * Bridge-specific contract preserved: `DASHBOARD_STARTER=Bridge`,
+ * `stdio: "ignore"` (Bridge auto-spawn never owns the log file),
+ * 2 s health timeout (Bridge expects a fast cold-start when the
+ * server is already on the same machine).
  */
 export async function launchServer(config: DashboardConfig): Promise<LaunchResult> {
   const cliPath = resolveServerCliPath();
   const args = buildSpawnArgs(config);
 
   try {
-    // Open the server.log in append mode so any startup error is visible.
-    // Matches the log location used by `pi-dashboard start`.
-    let logFd: number | undefined;
-    try {
-      const logDir = path.join(os.homedir(), ".pi", "dashboard");
-      fs.mkdirSync(logDir, { recursive: true });
-      const logPath = path.join(logDir, "server.log");
-      logFd = fs.openSync(logPath, "a");
-      fs.writeSync(
-        logFd,
-        `\n[${new Date().toISOString()}] bridge auto-start (parent pid ${process.pid}, port ${config.port})\n`,
-      );
-    } catch { /* if we can't open the log, spawn still works */ }
-
-    // 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", loader, entry, ...args], // ban:raw-node-import-ok: entry gated by shouldUrlWrapEntry
-      env: { ...process.env, DASHBOARD_STARTER: "Bridge" },
-      logFd,
+    await launchDashboardServer({
+      cliPath,
+      extraArgs: args,
+      stdio: "ignore",
+      healthTimeoutMs: 2_000,
+      port: config.port,
+      starter: "Bridge",
     });
-
-    // Close the parent's copy of the log fd — the child has its own.
-    if (logFd !== undefined) {
-      try { fs.closeSync(logFd); } catch { /* ignore */ }
+    return { success: true, message: "Server started" };
+  } catch (err: unknown) {
+    if (err instanceof JitiNotFoundError) {
+      return { success: false, message: err.message };
     }
-
-    if (!r.ok || !r.process) {
-      return { success: false, message: `Server process failed to spawn: ${r.error ?? "unknown"}` };
+    if (err instanceof PortConflictError) {
+      return { success: false, message: err.message };
     }
-
-    // Wait for the server to actually become available via positive
-    // HTTP probe. NO deadline — we rely on child-exit for failure
-    // detection. A timeout here only catches the pathological case
-    // "process alive but never ready", which is rarer than the
-    // false-positive case "slow cold-start mistakenly flagged as
-    // failure" (Fastify + jiti compile + session scan can take 15–30s
-    // on Windows). If the child crashes, `waitForReady` returns
-    // { ok: false, error: "child exited with code N" } via its
-    // `child` listener. If the child hangs alive-but-broken, the user
-    // can kill it manually — timers don't help that case anyway.
-    const ready = await waitForReady({
-      probe: async () => (await isDashboardRunning(config.port)).running,
-      pollIntervalMs: 300,
-      child: r.process,
-      // deadlineMs intentionally omitted — wait indefinitely.
-    });
-
-    if (!ready.ok) {
+    if (err instanceof EarlyExitError) {
       return {
         success: false,
-        message: `Server process failed: ${ready.error ?? "unknown"}. See ~/.pi/dashboard/server.log`,
+        message: `Server process exited (code=${err.code}) before health check. See ~/.pi/dashboard/server.log`,
       };
     }
-
-    return { success: true, message: "Server started" };
-  } catch (err: any) {
-    return { success: false, message: err.message };
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, message };
   }
 }