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

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,43 @@
+/**
+ * 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"`.
+ *
+ * Implementation strategy: always delegate to the already-exposed
+ * `ctx.ui.custom<T>()` primitive, which takes a factory that returns a
+ * focused pi-tui `Component`. We instantiate a `MultiSelectList`, wire
+ * `onConfirm` → `done(selected)` and `onCancel` → `done(undefined)`, and
+ * return the component.
+ *
+ * The result contract matches what the current (broken) call expects:
+ *   - resolves to `string[]` when the user confirms a selection
+ *     (possibly empty if nothing is checked)
+ *   - resolves to `undefined` when the user cancels (Escape)
+ */
+import { MultiSelectList } from "./multiselect-list.js";
+
+// Intentionally loose: `ctx` shape varies slightly across pi versions; the
+// polyfill only needs `ctx.ui.custom`.
+export interface PolyfillCtx {
+  ui: {
+    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> {
+  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,
     });

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "publishConfig": {
@@ -10,8 +10,8 @@
     "node": ">=22.18.0"
   },
   "piCompatibility": {
-    "minimum": "0.6.7",
-    "recommended": "0.6.7",
+    "minimum": "0.70.0",
+    "recommended": "0.70.0",
     "maximum": null
   },
   "main": "src/cli.ts",
@@ -26,8 +26,8 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-extension": "^0.4.0",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.4.0",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.4.1",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.4.1",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",

package/packages/server/src/__tests__/fixtures/fork-jsonl-roundtrip.jsonl

@@ -0,0 +1,8 @@
+{"type":"session","version":"1","id":"019dcdd5-0000-0000-0000-000000000000","timestamp":"2026-04-27T07:26:23.927Z","cwd":"/tmp/fork-test"}
+{"type":"model_change","id":"m1","timestamp":"2026-04-27T07:26:24.000Z","provider":"anthropic","modelId":"claude-sonnet-4"}
+{"type":"message","id":"u1","parentId":"m1","timestamp":"2026-04-27T07:26:25.000Z","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}
+{"type":"message","id":"a1","parentId":"u1","timestamp":"2026-04-27T07:26:30.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi there!"}]}}
+{"type":"message","id":"u2","parentId":"a1","timestamp":"2026-04-27T07:26:40.000Z","message":{"role":"user","content":[{"type":"text","text":"How are you?"}]}}
+{"type":"message","id":"a2","parentId":"u2","timestamp":"2026-04-27T07:26:45.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Doing well."}]}}
+{"type":"message","id":"u3","parentId":"a2","timestamp":"2026-04-27T07:26:55.000Z","message":{"role":"user","content":[{"type":"text","text":"Goodbye"}]}}
+{"type":"message","id":"a3","parentId":"u3","timestamp":"2026-04-27T07:27:00.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Bye!"}]}}

package/packages/server/src/__tests__/fork-jsonl-roundtrip.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Round-trip test: createBranchedSessionFile MUST end the new JSONL at the
+ * given entry id. Catches the fork-bubble off-by-one bug from the upstream
+ * angle: if the bridge ever stamps a correct entry id on a bubble, this
+ * function must produce a file whose tail entry equals that id.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createBranchedSessionFile } from "../session-file-reader.js";
+
+const FIXTURE = join(__dirname, "fixtures", "fork-jsonl-roundtrip.jsonl");
+
+function readEntries(path: string): any[] {
+  return readFileSync(path, "utf-8").trim().split("\n").map(l => JSON.parse(l));
+}
+
+describe("createBranchedSessionFile round-trip", () => {
+  it("for every non-header entry id, the forked JSONL ends at that id", () => {
+    // Copy fixture to a tmp dir so the function can write its sibling output there.
+    const tmp = mkdtempSync(join(tmpdir(), "fork-roundtrip-"));
+    const tmpFixture = join(tmp, "src.jsonl");
+    require("node:fs").copyFileSync(FIXTURE, tmpFixture);
+
+    try {
+      const allEntries = readEntries(tmpFixture);
+      const candidates = allEntries.filter(e => e.type === "message" || e.type === "model_change").map(e => e.id);
+      expect(candidates.length).toBeGreaterThan(0);
+
+      for (const targetId of candidates) {
+        const newPath = createBranchedSessionFile(tmpFixture, targetId);
+        const newEntries = readEntries(newPath);
+
+        const header = newEntries[0];
+        expect(header.type).toBe("session");
+
+        const lastEntry = newEntries[newEntries.length - 1];
+        expect(lastEntry.id).toBe(targetId);
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("throws on unknown entry id", () => {
+    expect(() => createBranchedSessionFile(FIXTURE, "does-not-exist")).toThrow(/not found/i);
+  });
+});

package/packages/server/src/__tests__/pi-version-skew.test.ts

@@ -13,9 +13,11 @@ import {
   isBelow,
   isAbove,
   readPiCompatibility,
+  readCurrentPiVersion,
   computeCompatibility,
   _resetVersionSkewCache,
 } from "../pi-version-skew.js";
+import type { ToolRegistry, Resolution } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
 
 describe("pi-version-skew", () => {
   beforeEach(() => {
@@ -162,4 +164,74 @@ describe("pi-version-skew", () => {
       expect(out.upgradeDashboard).toBe(true);
     });
   });
+
+  // See change: warn-pi-version-skew-in-cli.
+  describe("readCurrentPiVersion (realpath symlinks)", () => {
+    let tmpDir: string;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-skew-realpath-"));
+    });
+
+    function stubRegistry(resolvedPath: string): ToolRegistry {
+      return {
+        resolve: (name: string): Resolution => ({
+          ok: true,
+          name,
+          path: resolvedPath,
+          source: "system",
+          tried: [],
+          resolvedAt: Date.now(),
+        }),
+      } as unknown as ToolRegistry;
+    }
+
+    it("npm-global symlinked bin launcher resolves to the real package.json", () => {
+      // Simulate ~/.nvm/.../bin/pi → ../lib/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+      const nodeRoot = path.join(tmpDir, "node-install");
+      const binDir = path.join(nodeRoot, "bin");
+      const pkgDir = path.join(nodeRoot, "lib", "node_modules", "@mariozechner", "pi-coding-agent");
+      const distDir = path.join(pkgDir, "dist");
+      fs.mkdirSync(binDir, { recursive: true });
+      fs.mkdirSync(distDir, { recursive: true });
+      fs.writeFileSync(path.join(distDir, "cli.js"), "// stub");
+      fs.writeFileSync(
+        path.join(pkgDir, "package.json"),
+        JSON.stringify({ name: "@mariozechner/pi-coding-agent", version: "0.70.0" }),
+      );
+      // The bad path (what old code computed) must NOT exist.
+      // That is: nodeRoot/package.json. We leave it absent.
+
+      const binLink = path.join(binDir, "pi");
+      // relative symlink matches npm's install layout.
+      fs.symlinkSync(
+        path.relative(binDir, path.join(distDir, "cli.js")),
+        binLink,
+      );
+
+      const registry = stubRegistry(binLink);
+      expect(readCurrentPiVersion(registry)).toBe("0.70.0");
+    });
+
+    it("non-symlinked path is a no-op under realpath", () => {
+      const pkgDir = path.join(tmpDir, "pkg");
+      const distDir = path.join(pkgDir, "dist");
+      fs.mkdirSync(distDir, { recursive: true });
+      const cli = path.join(distDir, "cli.js");
+      fs.writeFileSync(cli, "// stub");
+      fs.writeFileSync(
+        path.join(pkgDir, "package.json"),
+        JSON.stringify({ name: "@mariozechner/pi-coding-agent", version: "0.69.0" }),
+      );
+      const registry = stubRegistry(cli);
+      expect(readCurrentPiVersion(registry)).toBe("0.69.0");
+    });
+
+    it("dangling symlink returns undefined", () => {
+      const link = path.join(tmpDir, "dangling-pi");
+      fs.symlinkSync(path.join(tmpDir, "does-not-exist", "cli.js"), link);
+      const registry = stubRegistry(link);
+      expect(readCurrentPiVersion(registry)).toBeUndefined();
+    });
+  });
 });

package/packages/server/src/__tests__/restart-helper.test.ts

@@ -34,14 +34,18 @@ describe("buildOrchestratorScript", () => {
     const script = buildOrchestratorScript(baseParams);
     // ARGS should be a JSON array containing --import and the loader
     expect(script).toMatch(/const ARGS = \[.*"--import".*"file:\/\/\/tmp\/jiti-register\.mjs"/);
+    // On POSIX, cliPath stays RAW — jiti's resolver misbehaves on file:// URL entries.
     expect(script).toMatch(/"\/tmp\/cli\.ts"/);
+    expect(script).not.toContain(JSON.stringify("file:///tmp/cli.ts"));
     expect(script).toMatch(/"start"/);
   });
 
   it("omits --import when loader is empty", () => {
     const script = buildOrchestratorScript({ ...baseParams, loader: "" });
     expect(script).not.toMatch(/"--import"/);
+    // No loader + POSIX host → raw entry.
     expect(script).toMatch(/"\/tmp\/cli\.ts"/);
+    expect(script).not.toContain(JSON.stringify("file:///tmp/cli.ts"));
     expect(script).toMatch(/"start"/);
   });
 
@@ -51,7 +55,12 @@ describe("buildOrchestratorScript", () => {
     expect(script).toMatch(/"start","--dev"/);
   });
 
-  it("safely embeds Windows paths with backslashes and drive letters", () => {
+  it("wraps Windows cliPath as file:// URL when loader is jiti AND host is Windows (Node parses drive letters as URL schemes)", () => {
+    // NOTE: shouldUrlWrapEntry consults process.platform. This test runs on
+    // Linux CI, so the wrap branch isn't directly exercised here — but the
+    // UNIT test for shouldUrlWrapEntry itself covers the win32 contract.
+    // Here we verify the tree of what buildOrchestratorScript emits on the
+    // host platform (Linux): raw entry even with a Windows-styled path.
     const winParams = {
       ...baseParams,
       cliPath: "B:\\Dev\\BB\\pi-agent-dashboard\\packages\\server\\src\\cli.ts",
@@ -59,13 +68,32 @@ describe("buildOrchestratorScript", () => {
       execPath: "C:\\Program Files\\nodejs\\node.exe",
     };
     const script = buildOrchestratorScript(winParams);
-    // Must be embedded via JSON.stringify (backslashes escaped, quotes preserved)
     expect(script).toContain(JSON.stringify(winParams.execPath));
-    expect(script).toContain(JSON.stringify(winParams.cliPath));
     expect(script).toContain(JSON.stringify(winParams.loader));
-    // Should not contain raw unescaped backslashes that would break the JS
-    // (we embed via JSON.stringify which escapes them to \\)
-    expect(script).toMatch(/B:\\\\Dev\\\\BB/);
+    // Host is Linux → entry stays raw (tested branch here).
+    expect(script).toContain(JSON.stringify(winParams.cliPath));
+  });
+
+  it("keeps cliPath as RAW path when loader is tsx (tsx rejects file:// URL entries)", () => {
+    // Regression: tsx's ESM hook treats the entry as a user-typed specifier
+    // and attempts bare/relative resolution. A file:// URL becomes "<cwd>/file:/..."
+    // and crashes with ERR_MODULE_NOT_FOUND. This is the Linux dev-loop case
+    // (jiti not in repo node_modules, tsx fallback picked up).
+    const tsxParams = {
+      cliPath: "/home/u/repo/packages/server/src/cli.ts",
+      loader: "file:///home/u/repo/node_modules/tsx/dist/esm/index.mjs",
+      port: 8000,
+      extraArgs: [] as string[],
+      execPath: "/usr/bin/node",
+    };
+    const script = buildOrchestratorScript(tsxParams);
+    // Loader is still URL-wrapped (Node's --import requires file://)
+    expect(script).toContain(JSON.stringify(tsxParams.loader));
+    // Entry is the RAW path, NOT a file:// URL
+    expect(script).toContain(JSON.stringify(tsxParams.cliPath));
+    // Negative: must NOT contain the file:// URL form of the entry
+    const urlForm = "file://" + tsxParams.cliPath;
+    expect(script).not.toContain(JSON.stringify(urlForm));
   });
 
   it("references ~/.pi/dashboard/restart.log for failure logging", () => {

package/packages/server/src/cli.ts

@@ -18,6 +18,7 @@
 import { createServer, type ServerConfig } from "./server.js";
 import { loadConfig, ensureConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import { spawnNodeScript } from "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import fs from "node:fs";
@@ -51,6 +52,37 @@ import {
 } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import type { DashboardServer } from "./server.js";
 import { updateBootstrapCompatibility } from "./pi-version-skew.js";
+import type { BootstrapStateStore } from "./bootstrap-state.js";
+
+/**
+ * Emit a stderr warning at CLI startup when the resolved pi version is
+ * below `piCompatibility.minimum` (blocking) or below `.recommended`
+ * (advisory). Reads from the already-populated `bootstrapState` so no
+ * additional I/O happens here. See change: warn-pi-version-skew-in-cli.
+ */
+function logCompatibilityWarning(store: BootstrapStateStore): void {
+  const s = store.get();
+  const c = s.compatibility;
+  if (!c || !c.current) return;
+  // Below minimum: `updateBootstrapCompatibility` sets `error.message`.
+  // We treat the presence of a blocking error + upgradeRecommended as the
+  // below-minimum signal; `upgradeRecommended` alone means below-recommended.
+  if (s.error?.message && c.upgradeRecommended) {
+    console.error(
+      `[bootstrap] ⚠ pi ${c.current} is below the required minimum ${c.minimum}.`,
+    );
+    console.error(
+      `[bootstrap]   All pi-dependent features (sessions, resources, openspec) will return 503.`,
+    );
+    console.error(`[bootstrap]   Run: pi-dashboard upgrade-pi`);
+    return;
+  }
+  if (c.upgradeRecommended) {
+    console.warn(
+      `[bootstrap] pi ${c.current} is below the recommended ${c.recommended} — consider running \`pi-dashboard upgrade-pi\``,
+    );
+  }
+}
 
 const SUBCOMMANDS = ["start", "stop", "restart", "status", "upgrade-pi"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
@@ -191,6 +223,7 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
         "package.json",
       );
       updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
     } catch (err) {
       console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
     }
@@ -260,6 +293,7 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
         "package.json",
       );
       updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
     } catch (err) {
       console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
     }
@@ -339,21 +373,31 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     `\n[${new Date().toISOString()}] pi-dashboard start (parent pid ${process.pid}, port ${config.port})\n`,
   );
 
-  // tsLoader is a file:// URL (required on Windows for node --import).
-  // See change: fix-windows-server-parity.
-  const child = spawn(process.execPath, ["--import", tsLoader, cliPath, ...args], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: { ...process.env },
+  // Both tsLoader and cliPath are wrapped as file:// URLs by spawnNodeScript.
+  // Required on Windows for node --import (see change: fix-windows-entry-script-url).
+  const child = spawnNodeScript({
+    loader: tsLoader,
+    entry: cliPath,
+    args,
+    spawnOptions: {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env },
+    },
   });
   child.unref();
   // Close the parent's copy of the fd — child has its own via stdio inheritance.
   try { fs.closeSync(logFd); } catch { /* ignore */ }
 
-  // Wait for dashboard to become available (up to 5 seconds)
-  const deadline = Date.now() + 5000;
+  // Wait for dashboard to become available. Windows + jiti cold-start can
+  // take 10s+ (TS compile on first boot, native module loads). 30s is the
+  // outer bound — if the server isn't up by then, something's genuinely wrong.
+  const READINESS_TIMEOUT_MS = 30_000;
+  const deadline = Date.now() + READINESS_TIMEOUT_MS;
   let started = false;
   while (Date.now() < deadline) {
+    // Also bail if the child has already exited (fast-path crash detection).
+    if (child.exitCode !== null) break;
     await new Promise((r) => setTimeout(r, 300));
     const status = await isDashboardRunning(config.port);
     if (status.running) {
@@ -366,7 +410,10 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     const pid = readPid();
     console.log(`Dashboard server started (pid ${pid ?? child.pid}) at http://localhost:${config.port}`);
   } else {
-    console.error("Failed to start dashboard server (timed out after 5s)");
+    const reason = child.exitCode !== null
+      ? `child process exited with code ${child.exitCode}`
+      : `timed out after ${READINESS_TIMEOUT_MS / 1000}s`;
+    console.error(`Failed to start dashboard server (${reason})`);
     console.error(`Check logs at ${path.join(logDir, "server.log")}`);
     process.exit(1);
   }

package/packages/server/src/pi-version-skew.ts

@@ -106,10 +106,21 @@ export function readCurrentPiVersion(registry: ToolRegistry = getDefaultRegistry
     /* not resolvable yet */
   }
   // Fall back to the registry's resolved path + ../package.json.
+  // `where` / `which` strategies typically return a symlinked npm bin
+  // launcher (e.g. ~/.nvm/.../bin/pi → ../lib/node_modules/@mariozechner/
+  // pi-coding-agent/dist/cli.js). Realpath the result first so the
+  // dirname math lands on the real pi module directory, not the
+  // bin-containing Node install prefix. See change: warn-pi-version-skew-in-cli.
   try {
     const res = registry.resolve("pi");
     if (res.ok && res.path) {
-      const candidate = path.join(path.dirname(path.dirname(res.path)), "package.json");
+      let resolvedPath: string;
+      try {
+        resolvedPath = fs.realpathSync(res.path);
+      } catch {
+        return undefined;
+      }
+      const candidate = path.join(path.dirname(path.dirname(resolvedPath)), "package.json");
       if (fs.existsSync(candidate)) {
         const raw = fs.readFileSync(candidate, "utf8");
         const parsed = JSON.parse(raw) as { version?: string };

package/packages/server/src/restart-helper.ts

@@ -12,6 +12,7 @@
  * See change: fix-windows-server-parity.
  */
 import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import { toFileUrl, shouldUrlWrapEntry } from "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";
 import os from "node:os";
 import path from "node:path";
 
@@ -35,11 +36,21 @@ export interface RestartParams {
 export function buildOrchestratorScript(params: RestartParams): string {
   const execPath = params.execPath ?? process.execPath;
   const logPath = path.join(os.homedir(), ".pi", "dashboard", "restart.log");
+  // Loader is always URL-wrapped (required on Windows for non-C: drives).
+  // Entry is URL-wrapped only on Windows + non-tsx loader. POSIX + jiti MUST
+  // pass raw path because jiti's resolver treats file:// URL entries as
+  // relative specifiers (normalises to file:/... then prepends cwd).
+  // See openspec/changes/archive/2026-04-24-fix-windows-entry-script-url.
+  const wrapEntry = shouldUrlWrapEntry(params.loader);
   const spawnArgs: string[] = [];
   if (params.loader) {
-    spawnArgs.push("--import", params.loader);
+    spawnArgs.push("--import", toFileUrl(params.loader));
   }
-  spawnArgs.push(params.cliPath, "start", ...params.extraArgs);
+  spawnArgs.push(
+    wrapEntry ? toFileUrl(params.cliPath) : params.cliPath,
+    "start",
+    ...params.extraArgs,
+  );
 
   // The script runs in a fresh Node process. Keep it self-contained and use
   // only built-ins (net, http, fs, child_process). JSON.stringify is used to

package/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-shared",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared types and utilities for pi-dashboard",
   "type": "module",
   "publishConfig": {