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

package/packages/extension/src/provider-register.ts

@@ -11,7 +11,7 @@
  *   flow:resolve-model / flow:get-available-models
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -373,7 +373,7 @@ async function loadPiAi(): Promise<PiAiHelpers> {
   if (_piAiLoadAttempted) return {};
   _piAiLoadAttempted = true;
   try {
-    const mod: any = await import("@mariozechner/pi-ai");
+    const mod: any = await import("@earendil-works/pi-ai");
     _piAiModule = { findEnvKeys: mod.findEnvKeys, getEnvApiKey: mod.getEnvApiKey };
     return _piAiModule;
   } catch {
@@ -436,6 +436,20 @@ function getModelRegistry(): any {
 // -- Provider registration (with auto-discovery) --------------------------
 
 async function registerEntry(pi: ExtensionAPI, name: string, entry: ProviderEntry): Promise<number> {
+  // Record snapshot SYNCHRONOUSLY before awaiting discovery so the very
+  // first providers_list push (typically fired from `session_start`
+  // shortly after `activate()` kicked off async registerEntry calls) carries
+  // the correct `custom: true` flags. Otherwise a slow / unreachable
+  // /v1/models endpoint causes custom providers from
+  // `~/.pi/agent/providers.json` to leak into Settings → Provider
+  // Authentication → API Keys until the discovery probe resolves.
+  // See change: fix-custom-provider-flag-race.
+  lastRegistered.set(name, {
+    baseUrl: entry.baseUrl,
+    apiKey: entry.apiKey,
+    api: entry.api ?? "openai-completions",
+  });
+
   const discovered = await discoverModels(entry.baseUrl, entry.apiKey);
 
   // Metadata (contextWindow, maxTokens, reasoning, cost, input) is resolved
@@ -464,13 +478,6 @@ async function registerEntry(pi: ExtensionAPI, name: string, entry: ProviderEntr
     models,
   });
 
-  // Record snapshot so reloadProviders can detect subsequent changes.
-  lastRegistered.set(name, {
-    baseUrl: entry.baseUrl,
-    apiKey: entry.apiKey,
-    api: entry.api ?? "openai-completions",
-  });
-
   // Notify bridge directly (same package — no cross-package event needed)
   onProvidersChanged?.();
 

package/packages/extension/src/retry-tracker.ts

@@ -0,0 +1,123 @@
+/**
+ * RetryTracker — synthesizes `auto_retry_start` / `auto_retry_end` events from
+ * observed pi events.
+ *
+ * Background: pi's ExtensionAPI does NOT expose `auto_retry_*` events to
+ * extensions (verified against pi 0.70/0.73 — see
+ * https://github.com/badlogic/pi-mono/discussions/2073). They fire only via
+ * `AgentSession._emit → _eventListeners` which only the embedded SDK can
+ * subscribe to.
+ *
+ * Workaround: pi-coding-agent's `_handleRetryableError` fires `message_end`
+ * for the failed assistant message BEFORE entering its retry sleep. The
+ * bridge sees that `message_end` via `pi.on("message_end")`. By matching
+ * the same regex pi-coding-agent uses internally, we can detect that a
+ * retry is about to happen and emit our own `auto_retry_start` to the
+ * dashboard. When the next non-error `message_end` or `agent_end` arrives,
+ * we emit `auto_retry_end`.
+ *
+ * `delayMs` and `maxAttempts` are unknowable from observed events (pi's
+ * settings are not exposed); we send sentinel `-1` for both. The
+ * RetryBanner renders an indeterminate "retrying…" UI in that case.
+ *
+ * See change: fix-provider-retry-infinite-loop.
+ */
+
+/**
+ * Regex copied verbatim from pi-coding-agent `agent-session.js`
+ * `_isRetryableError`. If pi adds new retryable categories, this regex
+ * goes stale — but the failure mode is "tracker silently misses some
+ * retries", never "tracker breaks". Sync at major pi version bumps.
+ */
+export const RETRYABLE_PATTERN =
+  /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
+
+export interface SyntheticRetryEvent {
+  eventType: "auto_retry_start" | "auto_retry_end";
+  data: Record<string, unknown>;
+}
+
+/** Minimal shape we pluck from a `message_end` event. */
+export interface ObservedAssistantMessage {
+  role?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+export class RetryTracker {
+  /** sessionId → 1-based attempt counter for the current retry chain. */
+  private attempt = new Map<string, number>();
+
+  /**
+   * Process a `message_end` event. Returns a synthetic event the bridge
+   * should ALSO forward (after the original message_end), or null.
+   */
+  observeMessageEnd(
+    sessionId: string,
+    message: ObservedAssistantMessage | undefined | null,
+  ): SyntheticRetryEvent | null {
+    if (!message || message.role !== "assistant") return null;
+
+    if (message.stopReason === "error") {
+      const err = typeof message.errorMessage === "string" ? message.errorMessage : "";
+      if (!err || !RETRYABLE_PATTERN.test(err)) return null;
+      const next = (this.attempt.get(sessionId) ?? 0) + 1;
+      this.attempt.set(sessionId, next);
+      return {
+        eventType: "auto_retry_start",
+        data: { attempt: next, maxAttempts: -1, delayMs: -1, errorMessage: err },
+      };
+    }
+
+    // Non-error assistant message — clears any in-flight retry chain.
+    if (this.attempt.has(sessionId)) {
+      const last = this.attempt.get(sessionId) ?? 0;
+      this.attempt.delete(sessionId);
+      return { eventType: "auto_retry_end", data: { success: true, attempt: last } };
+    }
+    return null;
+  }
+
+  /**
+   * Process an `agent_end` event. Returns a synthetic event the bridge
+   * should forward BEFORE the original agent_end, or null.
+   *
+   * Always clears any in-flight retry tracking (terminal turn boundary).
+   */
+  observeAgentEnd(
+    sessionId: string,
+    agentEndData: { messages?: unknown } | undefined | null,
+  ): SyntheticRetryEvent | null {
+    const wasRetrying = this.attempt.has(sessionId);
+    const last = this.attempt.get(sessionId) ?? -1;
+    this.attempt.delete(sessionId);
+    if (!wasRetrying) return null;
+
+    // Inspect terminal message for error context.
+    const messages = agentEndData?.messages;
+    const lastMsg =
+      Array.isArray(messages) && messages.length > 0
+        ? (messages[messages.length - 1] as ObservedAssistantMessage)
+        : undefined;
+    if (lastMsg?.stopReason === "error" && typeof lastMsg.errorMessage === "string") {
+      return {
+        eventType: "auto_retry_end",
+        data: { success: false, attempt: last, finalError: lastMsg.errorMessage },
+      };
+    }
+    return { eventType: "auto_retry_end", data: { success: true, attempt: last } };
+  }
+
+  /**
+   * Notify the tracker of a user abort. Clears in-flight tracking so a
+   * subsequent agent_end does not double-emit auto_retry_end.
+   */
+  noteAbort(sessionId: string): void {
+    this.attempt.delete(sessionId);
+  }
+
+  /** Test-only / bridge-coordination: is a retry currently in flight? */
+  isRetrying(sessionId: string): boolean {
+    return this.attempt.has(sessionId);
+  }
+}

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 };
   }
 }

package/packages/extension/src/session-sync.ts

@@ -39,7 +39,15 @@ export function sendStateSync(
   // dashboard restart) is a "reattach". Server applies the configured
   // `reattachPlacement` policy on "reattach".
   // See change: reattach-move-to-front.
-  const registerReason: "spawn" | "reattach" = bc.hasRegisteredOnce ? "reattach" : "spawn";
+  const isFirstRegister = !bc.hasRegisteredOnce;
+  const registerReason: "spawn" | "reattach" = isFirstRegister ? "spawn" : "reattach";
+
+  // Include the spawn correlation token (server-minted UUID injected via
+  // env var at spawn time) ONLY on the first register. Subsequent
+  // registers (reattach after dashboard restart, in-process Ctrl+F fork)
+  // omit it because the sessionId is already known to the server.
+  // See change: spawn-correlation-token (Decision 3).
+  const spawnToken = isFirstRegister ? process.env.PI_DASHBOARD_SPAWN_TOKEN : undefined;
 
   bc.connection.send({
     type: "session_register",
@@ -55,6 +63,7 @@ export function sendStateSync(
     eventCount,
     pid: process.pid,
     registerReason,
+    ...(spawnToken ? { spawnToken } : {}),
   });
 
   bc.hasRegisteredOnce = true;

package/packages/extension/src/slash-dispatch.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared extension-slash-command dispatch branch used by both bridge.ts
+ * (sessionPrompt callback) and command-handler.ts (slash else-arm fallback).
+ *
+ * Routing-step 9 from `command-routing` spec — three-way decision:
+ *   - Path B: when `pi.dispatchCommand` is a function → call it directly.
+ *   - Path C: when `pi.dispatchCommand` is absent AND the bridge runs inside a
+ *     dashboard-spawned headless `pi --mode rpc` AND a `connection` is wired
+ *     → emit `dispatch_extension_command` to the server (server forwards to
+ *     the per-session RPC keeper UDS and emits the terminal command_feedback).
+ *   - Path D (stopgap, last resort): `pi.dispatchCommand` absent AND the bridge
+ *     is NOT headless (tmux / wt / unrecognized spawn shape) OR no `connection`
+ *     was supplied → emit `command_feedback {status:"error"}` with a pi-version
+ *     reminder.
+ *
+ * If `text` is NOT an extension command, return `false` so the caller can
+ * fall through to its existing template-expansion / sendUserMessage path.
+ *
+ * Guarantees: EXACTLY ONE `started` event AND EXACTLY ONE terminal event
+ * (`completed` xor `error`) per dispatch, across all three paths combined.
+ * Path C does NOT emit a terminal event — the server emits it.
+ *
+ * See change: fix-extension-slash-commands-in-dashboard,
+ *             add-rpc-stdin-dispatch-with-keeper-sidecar.
+ */
+import crypto from "node:crypto";
+import type { ExtensionToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+import { hasDispatchCommand, isExtensionSlashCommand, isHeadlessRpcSession } from "./bridge-context.js";
+
+export type FeedbackSink = (msg: ExtensionToServerMessage) => void;
+
+/**
+ * Minimal connection surface used by Path C. Concrete implementation is
+ * `ConnectionManager` (`connection.ts`) but a structural type keeps this
+ * helper unit-testable without a real WebSocket.
+ */
+export interface DispatchConnection {
+  send(msg: ExtensionToServerMessage): void;
+}
+
+const PI_071_REQUIRED =
+  "Extension slash commands cannot be dispatched from the dashboard yet — requires pi 0.71+ (`pi.dispatchCommand`). Invoke from the pi TUI, or use the extension's tools directly.";
+
+function emitFeedback(
+  sink: FeedbackSink | undefined,
+  sessionId: string,
+  command: string,
+  status: "started" | "completed" | "error",
+  message?: string,
+): void {
+  if (!sink) return;
+  sink({
+    type: "event_forward",
+    sessionId,
+    event: {
+      eventType: "command_feedback",
+      timestamp: Date.now(),
+      data: message === undefined ? { command, status } : { command, status, message },
+    },
+  });
+}
+
+/**
+ * Try to dispatch a slash command as an extension command.
+ *
+ * @returns `true` if the helper handled the text (extension command detected;
+ *          dispatch attempted or stopgap emitted). The caller MUST NOT fall
+ *          through to template expansion or `sendUserMessage`.
+ * @returns `false` if `text` is not an extension slash command. The caller
+ *          SHOULD continue with its existing fallback path.
+ */
+export async function tryDispatchExtensionCommand(
+  pi: unknown,
+  text: string,
+  sessionId: string,
+  sink: FeedbackSink | undefined,
+  connection?: DispatchConnection,
+): Promise<boolean> {
+  // Defensive: pi.getCommands() can throw on a stale ctx during dispose.
+  let commands: Array<{ name: string; source?: string }> = [];
+  try {
+    const got = (pi as any)?.getCommands?.();
+    if (Array.isArray(got)) commands = got;
+  } catch (err) {
+    console.warn("[dashboard] getCommands stale on slash-dispatch", err);
+    return false; // fall through to existing path; preserve today's behavior
+  }
+
+  if (!isExtensionSlashCommand(text, commands)) return false;
+
+  emitFeedback(sink, sessionId, text, "started");
+
+  // Path B (preferred when available): pi 0.71+ exposes dispatchCommand.
+  if (hasDispatchCommand(pi)) {
+    try {
+      await (pi as any).dispatchCommand(text, { streamingBehavior: "followUp" });
+      emitFeedback(sink, sessionId, text, "completed");
+    } catch (err: any) {
+      const message = err instanceof Error ? err.message : String(err);
+      emitFeedback(sink, sessionId, text, "error", message);
+    }
+    return true;
+  }
+
+  // Path C: headless RPC session, dispatchCommand absent. Hand off to the
+  // server, which writes the line to the session's RPC keeper UDS and
+  // emits the terminal command_feedback. The bridge does NOT emit a
+  // terminal event for this path — that would duplicate the reducer's
+  // started→terminal upsert. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+  if (connection && isHeadlessRpcSession()) {
+    connection.send({
+      type: "dispatch_extension_command",
+      sessionId,
+      command: text,
+      requestId: crypto.randomUUID(),
+    });
+    return true;
+  }
+
+  // Path D (stopgap): no dispatchCommand and not headless (tmux / wt / unrecognized).
+  emitFeedback(sink, sessionId, text, "error", PI_071_REQUIRED);
+  return true;
+}

package/packages/extension/src/usage-limit-orderer.ts

@@ -0,0 +1,76 @@
+/**
+ * Usage-limit event orderer.
+ *
+ * Tracks per-session whether an `auto_retry_start` was forwarded without a
+ * matching `auto_retry_end`, and — when an `agent_end` arrives whose terminal
+ * assistant message has a usage-limit / quota errorMessage — synthesizes an
+ * `auto_retry_end { success: false }` to emit BEFORE the `agent_end`.
+ *
+ * Pure logic (no I/O). The bridge wires this into its forwarding pipeline.
+ *
+ * See change: fix-provider-retry-infinite-loop.
+ */
+
+export const USAGE_LIMIT_PATTERN =
+  /usage[_ ]limit[_ ]reached|usage_not_included|quota[_ ]exceeded|monthly limit|hourly limit|reset after \d+[hms]/i;
+
+export interface SyntheticEventEnvelope {
+  eventType: "auto_retry_end";
+  data: { success: false; attempt: -1; finalError: string };
+}
+
+export class UsageLimitOrderer {
+  /** sessionId → true while a retry is in flight (no auto_retry_end seen yet). */
+  private pending = new Set<string>();
+
+  /**
+   * Notify the orderer of an outbound `auto_retry_start` for sessionId.
+   */
+  noteRetryStart(sessionId: string): void {
+    this.pending.add(sessionId);
+  }
+
+  /**
+   * Notify the orderer of an outbound `auto_retry_end` for sessionId.
+   * Subsequent `agent_end` events will not synthesize unless a new retry
+   * has been started.
+   */
+  noteRetryEnd(sessionId: string): void {
+    this.pending.delete(sessionId);
+  }
+
+  /**
+   * Inspect an `agent_end` payload. If the terminal message has a
+   * usage-limit error AND we have an unmatched retry-start for this session,
+   * return the synthetic event the bridge should forward BEFORE the agent_end.
+   *
+   * Returns null when no synthesis is needed. Always clears the pending flag
+   * after a terminal agent_end (errored or not) so we don't double-synthesize.
+   */
+  maybeSynthesize(
+    sessionId: string,
+    agentEndData: Record<string, unknown> | undefined,
+  ): SyntheticEventEnvelope | null {
+    const wasPending = this.pending.has(sessionId);
+    // Always clear on agent_end: a terminal turn ends any retry tracking.
+    this.pending.delete(sessionId);
+
+    if (!wasPending || !agentEndData) return null;
+    const messages = agentEndData.messages;
+    if (!Array.isArray(messages) || messages.length === 0) return null;
+    const last = messages[messages.length - 1] as Record<string, unknown> | undefined;
+    if (!last || last.stopReason !== "error") return null;
+    const errorMessage = typeof last.errorMessage === "string" ? last.errorMessage : "";
+    if (!errorMessage || !USAGE_LIMIT_PATTERN.test(errorMessage)) return null;
+
+    return {
+      eventType: "auto_retry_end",
+      data: { success: false, attempt: -1, finalError: errorMessage },
+    };
+  }
+
+  /** Test-only: inspect pending state. */
+  hasPending(sessionId: string): boolean {
+    return this.pending.has(sessionId);
+  }
+}

package/packages/server/bin/pi-dashboard.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * pi-dashboard CLI entry point.
+ *
+ * The actual CLI is `../src/cli.ts`. This wrapper exists because a
+ * `#!/usr/bin/env` shebang cannot interpolate a dynamic `--import`
+ * loader path. The wrapper resolves jiti from pi's tree at runtime
+ * and re-execs Node with `--import <jiti-url> cli.ts <args>`.
+ *
+ * No tsx fallback: if jiti cannot be resolved, the wrapper exits 1
+ * with an install-hint pointing at pi. Mirrors the resolution shape
+ * in `packages/shared/src/resolve-jiti.ts` (cannot import the .ts
+ * module before a TS loader is registered, so the lookup is inlined).
+ *
+ * See change: replace-tsx-with-jiti.
+ */
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(here, "..", "src", "cli.ts");
+
+// Mirrors packages/shared/src/resolve-jiti.ts JITI_PACKAGES.
+const JITI_PACKAGES = ["jiti", "@mariozechner/jiti"];
+
+/** Resolve pi's jiti register hook as a file:// URL. Returns null on miss. */
+function resolveJitiUrl() {
+  const anchor = process.argv[1];
+  if (!anchor) return null;
+  let resolved;
+  try {
+    resolved = realpathSync(anchor);
+  } catch {
+    return null;
+  }
+  const req = createRequire(resolved);
+  for (const pkg of JITI_PACKAGES) {
+    try {
+      const pkgJson = req.resolve(`${pkg}/package.json`);
+      const registerPath = join(dirname(pkgJson), "lib", "jiti-register.mjs");
+      return pathToFileURL(registerPath).href;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+const loader = resolveJitiUrl();
+if (!loader) {
+  process.stderr.write(
+    "pi-dashboard: cannot find jiti. " +
+      "Install pi: 'npm install -g @earendil-works/pi-coding-agent'\n",
+  );
+  process.exit(1);
+}
+
+// Mirrors shouldUrlWrapEntry() in packages/shared/src/platform/node-spawn.ts:
+// jiti needs the entry URL-wrapped on Windows (Node rejects raw drive-letter
+// paths for --import). POSIX takes the raw path.
+const entry = process.platform === "win32" ? pathToFileURL(cliPath).href : cliPath;
+
+const child = spawn(
+  process.execPath,
+  ["--import", loader, entry, ...process.argv.slice(2)],
+  { stdio: "inherit", windowsHide: true },
+);
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent shell sees the same exit reason.
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+child.on("error", (err) => {
+  process.stderr.write(`pi-dashboard: failed to spawn Node: ${err.message}\n`);
+  process.exit(1);
+});

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "repository": {
@@ -15,15 +15,16 @@
     "node": ">=22.18.0"
   },
   "piCompatibility": {
-    "minimum": "0.70.0",
-    "recommended": "0.70.0",
+    "minimum": "0.74.0",
+    "recommended": "0.74.0",
     "maximum": null
   },
   "main": "src/cli.ts",
   "bin": {
-    "pi-dashboard": "src/cli.ts"
+    "pi-dashboard": "bin/pi-dashboard.mjs"
   },
   "files": [
+    "bin/",
     "src/",
     "scripts/"
   ],
@@ -31,9 +32,9 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.0",
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.0",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.5.0",
+    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.2",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",