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

package/packages/server/src/routes/recommended-routes.ts

@@ -0,0 +1,227 @@
+/**
+ * REST route for the dashboard's curated "recommended extensions" list.
+ *
+ *   GET /api/packages/recommended
+ *
+ * Returns the static RECOMMENDED_EXTENSIONS manifest enriched with:
+ *   - live description + version from npm or GitHub (falls back to
+ *     fallbackDescription on network failure)
+ *   - installed.scope cross-reference via packageManagerWrapper
+ *   - activeInPi flag from ~/.pi/agent/settings.json packages[]
+ *   - updateAvailable flag
+ *
+ * Results are cached for 60 seconds. The cache is busted when any package
+ * install / remove / update operation completes successfully.
+ */
+import type { FastifyInstance } from "fastify";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { EnrichedRecommendedExtension } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import {
+	RECOMMENDED_EXTENSIONS,
+	type RecommendedExtension,
+} from "@blackbelt-technology/pi-dashboard-shared/recommended-extensions.js";
+import {
+	parseSourceKey,
+	sourcesMatch,
+	type SourceKey,
+} from "@blackbelt-technology/pi-dashboard-shared/source-matching.js";
+export { parseSourceKey, sourcesMatch, type SourceKey };
+import {
+	fetchPackageMeta,
+	fetchGithubPackageJson,
+	type PackageMeta,
+} from "../npm-search-proxy.js";
+import type { PackageManagerWrapper } from "../package-manager-wrapper.js";
+
+const CACHE_TTL_MS = 60 * 1000;
+
+interface CacheEntry {
+	at: number;
+	data: EnrichedRecommendedExtension[];
+}
+
+let cache: CacheEntry | null = null;
+
+/** Invalidate the recommended-extensions cache. */
+export function invalidateRecommendedCache(): void {
+	cache = null;
+}
+
+/**
+ * Parse a pi install source into a lookup key for matching against
+ * listInstalled() results.
+ *
+ * Supported forms (matches pi's DefaultPackageManager.parseSource):
+ *   npm:<name>[@<version>]
+ *   git@<host>:<owner>/<repo>.git
+ *   git:<host>/<owner>/<repo>[#<ref>]
+ *   https://<host>/<owner>/<repo>[.git][#<ref>]
+ *
+ * Returns:
+ *   { kind: "npm", name }                 for npm sources
+ *   { kind: "git", host, owner, repo }    for git sources
+ *   { kind: "raw", source }               for anything else (local paths)
+ *
+ * Source-matching logic lives in
+ * `@blackbelt-technology/pi-dashboard-shared/source-matching.js` so the
+ * Electron wizard's bootstrap enricher can apply the same rules without
+ * depending on the server runtime. We re-export above so existing
+ * imports from this module keep working.
+ */
+
+/** Read pi's project-local `.pi/settings.json` (if any) for the given cwd. */
+function readLocalSources(cwd: string): string[] {
+	const settingsPath = path.join(cwd, ".pi", "settings.json");
+	try {
+		if (!fs.existsSync(settingsPath)) return [];
+		const raw = fs.readFileSync(settingsPath, "utf-8").trim();
+		if (!raw) return [];
+		const data = JSON.parse(raw);
+		const pkgs = Array.isArray(data?.packages) ? (data.packages as unknown[]) : [];
+		return pkgs.filter((p): p is string => typeof p === "string");
+	} catch {
+		return [];
+	}
+}
+
+/** Collect active package sources from both the user's global
+ * `~/.pi/agent/settings.json` and the project's `<cwd>/.pi/settings.json`.
+ * Mirrors pi's SettingsManager behavior: a package is "active" in pi if
+ * it appears in EITHER scope's packages[] list. */
+function readActiveSources(cwd?: string): string[] {
+	const sources: string[] = [];
+
+	const globalPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+	try {
+		if (fs.existsSync(globalPath)) {
+			const raw = fs.readFileSync(globalPath, "utf-8").trim();
+			if (raw) {
+				const data = JSON.parse(raw);
+				const pkgs = Array.isArray(data?.packages) ? (data.packages as unknown[]) : [];
+				for (const p of pkgs) if (typeof p === "string") sources.push(p);
+			}
+		}
+	} catch {
+		/* ignore corrupt global settings */
+	}
+
+	if (cwd) {
+		for (const p of readLocalSources(cwd)) sources.push(p);
+	}
+
+	return sources;
+}
+
+function semverOlder(installed: string | undefined, latest: string | undefined): boolean {
+	if (!installed || !latest) return false;
+	if (installed === latest) return false;
+	// Very conservative comparison: if they differ textually, assume an
+	// update may be available. The Packages tab's check-updates flow can
+	// resolve the definitive answer.
+	return installed !== latest;
+}
+
+async function enrichEntry(
+	entry: RecommendedExtension,
+	installedGlobal: Array<{ source: string; installedPath?: string }>,
+	installedLocal: Array<{ source: string; installedPath?: string }>,
+	activeSources: string[],
+): Promise<EnrichedRecommendedExtension> {
+	const key = parseSourceKey(entry.source);
+	let meta: PackageMeta | null = null;
+
+	if (key.kind === "npm") {
+		meta = await fetchPackageMeta(key.name);
+	} else if (key.kind === "git" && key.host.toLowerCase() === "github.com") {
+		meta = await fetchGithubPackageJson(key.owner, key.repo);
+	}
+
+	const description = meta?.description ?? entry.fallbackDescription;
+	const version = meta?.version;
+
+	const inGlobal = installedGlobal.some((p) => sourcesMatch(p.source, entry.source));
+	const inLocal = installedLocal.some((p) => sourcesMatch(p.source, entry.source));
+	const installedScope: "global" | "local" | null = inGlobal
+		? "global"
+		: inLocal
+			? "local"
+			: null;
+
+	const activeInPi = activeSources.some((s) => sourcesMatch(s, entry.source));
+
+	// Best-effort update indicator: for npm sources, try to read the installed
+	// package.json version and compare to the live registry version. For git
+	// sources we currently don't track ref pins, so updateAvailable defaults
+	// to false (the Packages-tab check-updates action handles this separately).
+	let updateAvailable = false;
+	if (version && key.kind === "npm" && installedScope) {
+		const installed = inGlobal ? installedGlobal : installedLocal;
+		const match = installed.find((p) => sourcesMatch(p.source, entry.source));
+		if (match?.installedPath) {
+			try {
+				const pj = path.join(match.installedPath, "package.json");
+				if (fs.existsSync(pj)) {
+					const parsed = JSON.parse(fs.readFileSync(pj, "utf-8"));
+					updateAvailable = semverOlder(parsed?.version, version);
+				}
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+
+	return {
+		...entry,
+		description,
+		version,
+		installed: { scope: installedScope },
+		activeInPi,
+		updateAvailable,
+	};
+}
+
+export function registerRecommendedRoutes(
+	fastify: FastifyInstance,
+	deps: { packageManagerWrapper: PackageManagerWrapper },
+): void {
+	fastify.get("/api/packages/recommended", async () => {
+		const now = Date.now();
+		if (cache && now - cache.at < CACHE_TTL_MS) {
+			return { success: true, data: { recommended: cache.data } } satisfies ApiResponse<{
+				recommended: EnrichedRecommendedExtension[];
+			}>;
+		}
+
+		let installedGlobal: Array<{ source: string; installedPath?: string }> = [];
+		let installedLocal: Array<{ source: string; installedPath?: string }> = [];
+		try {
+			installedGlobal = (await deps.packageManagerWrapper.listInstalled("global")) as any[];
+		} catch {
+			/* proceed with empty */
+		}
+		try {
+			installedLocal = (await deps.packageManagerWrapper.listInstalled("local")) as any[];
+		} catch {
+			/* proceed with empty */
+		}
+
+		// Include both global + project-local settings.json `packages[]`.
+		// The server's CWD is a reasonable proxy for the active project.
+		const activeSources = readActiveSources(process.cwd());
+
+		const enriched = await Promise.all(
+			RECOMMENDED_EXTENSIONS.map((entry) =>
+				enrichEntry(entry, installedGlobal, installedLocal, activeSources),
+			),
+		);
+
+		cache = { at: now, data: enriched };
+
+		return { success: true, data: { recommended: enriched } } satisfies ApiResponse<{
+			recommended: EnrichedRecommendedExtension[];
+		}>;
+	});
+}

package/packages/server/src/routes/system-routes.ts

@@ -147,7 +147,9 @@ export function registerSystemRoutes(
   });
 
   fastify.post("/api/tunnel-disconnect", async () => {
-    await deleteTunnel();
+    // Pass port so orphan zrok processes bound to this endpoint are also
+    // swept (not just the one we tracked via pid-file).
+    await deleteTunnel(config.port);
     return { ok: true };
   });
 
@@ -186,6 +188,9 @@ export function registerSystemRoutes(
     async () => {
       metaPersistence.flushAll();
       preferencesStore.flush();
+      // Tear down the zrok tunnel (and sweep orphans on our port) so restarts
+      // don't leak reservations that leave stale URLs backed by nothing.
+      try { await deleteTunnel(config.port); } catch { /* best-effort */ }
       setTimeout(() => process.exit(0), 100);
       return { ok: true };
     },
@@ -199,6 +204,10 @@ export function registerSystemRoutes(
       metaPersistence.flushAll();
       preferencesStore.flush();
 
+      // Tear down tunnel before spawning the replacement process so the new
+      // server doesn't race an orphan zrok agent on the same port.
+      try { await deleteTunnel(config.port); } catch { /* best-effort */ }
+
       const cliPath = process.argv[1];
       if (!cliPath) return { ok: false, error: "Cannot determine CLI path" };
 

package/packages/server/src/server.ts

@@ -4,6 +4,7 @@
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
 import cors from "@fastify/cors";
+import compress from "@fastify/compress";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
@@ -29,7 +30,7 @@ import { createIdleTimer } from "./idle-timer.js";
 import { discoverAndBroadcastSessions } from "./session-bootstrap.js";
 import { scanAllSessions } from "./session-scanner.js";
 import { needsMigration, runMigration } from "./migrate-persistence.js";
-import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel } from "./tunnel.js";
+import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel, scavengeOrphanZrokProcesses, getTunnelUrl } from "./tunnel.js";
 import { registerAuthPlugin, validateWsUpgrade } from "./auth-plugin.js";
 import { findBundledExtension, registerBridgeExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import { createNetworkGuard, isLoopback, isBypassedHost } from "./localhost-guard.js";
@@ -42,9 +43,14 @@ import { registerOpenSpecRoutes } from "./routes/openspec-routes.js";
 import { registerSystemRoutes } from "./routes/system-routes.js";
 import { registerProviderAuthRoutes } from "./routes/provider-auth-routes.js";
 import { registerPackageRoutes } from "./routes/package-routes.js";
+import { registerRecommendedRoutes, invalidateRecommendedCache } from "./routes/recommended-routes.js";
+import { registerPiCoreRoutes } from "./routes/pi-core-routes.js";
+import { PiCoreChecker } from "./pi-core-checker.js";
+import { PiCoreUpdater } from "./pi-core-updater.js";
 import { registerProviderRoutes } from "./routes/provider-routes.js";
 import { PackageManagerWrapper } from "./package-manager-wrapper.js";
 import { createEditorManager, type EditorManager } from "./editor-manager.js";
+import { createEditorPidRegistry } from "./editor-pid-registry.js";
 import { registerEditorRoutes } from "./routes/editor-routes.js";
 import { registerKnownServersRoutes } from "./routes/known-servers-routes.js";
 import { registerEditorProxy, handleEditorUpgrade } from "./editor-proxy.js";
@@ -79,6 +85,10 @@ export interface DashboardServer {
   sessionManager: SessionManager;
   eventStore: EventStore;
   browserGateway: BrowserGateway;
+  /** Resolved HTTP port after start() (useful for port:0 in tests). Returns null if not listening. */
+  httpPort(): number | null;
+  /** Resolved pi gateway port after start(). Returns null if not listening. */
+  piPort(): number | null;
 }
 
 export async function createServer(config: ServerConfig): Promise<DashboardServer> {
@@ -190,9 +200,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
 
   // Create editor manager for code-server instances
   const editorDetection = detectCodeServerBinary(config.editor);
+  const editorPidRegistry = createEditorPidRegistry();
   const editorManager = createEditorManager({
     config: config.editor,
     detection: editorDetection,
+    pidRegistry: editorPidRegistry,
     onStatusChange: (cwd, id, status) => {
       browserGateway.broadcastToAll({ type: "editor_status", cwd, id, status });
     },
@@ -243,23 +255,62 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     connectionTimeout: 10_000,
   });
 
-  // CORS: allow localhost by default + configured origins
+  // Compression: gzip/deflate for HTTP responses. Critical for large client
+  // bundles (~3 MB JS) served over tunnels like zrok which abort big transfers.
+  // Brotli is intentionally disabled — zrok's free public proxy has been
+  // observed to truncate/stream-reset `content-encoding: br` responses under
+  // parallel browser load (curl succeeds, Chrome reports ERR_ABORTED 500).
+  // gzip is universally supported and round-trips cleanly through zrok.
+  // threshold=1024 skips tiny responses; global=true compresses all routes.
+  await fastify.register(compress, {
+    global: true,
+    threshold: 1024,
+    encodings: ["gzip", "deflate"],
+  });
+
+  // CORS: allow localhost, the active zrok tunnel URL, any *.share.zrok.io
+  // host (so tunnel URL rotation doesn't break loads), and configured origins.
+  //
+  // Two critical correctness notes:
+  // (1) Vite emits `<script type="module" crossorigin>` tags, which browsers
+  //     always request in CORS mode — even when same-origin. If the server
+  //     doesn't emit `Access-Control-Allow-Origin` for the request's own
+  //     origin, the browser aborts the script with ERR_ABORTED 500. So when
+  //     accessed via a tunnel URL, that URL MUST be in the allow list or all
+  //     asset loads fail in the browser (while curl — which sends no Origin
+  //     header — works fine). This is the exact failure mode that looked
+  //     like a zrok problem for hours of debugging.
+  // (2) On origin mismatch, return `cb(null, false)` (no CORS headers) rather
+  //     than `cb(new Error(…), false)`. The latter causes @fastify/cors to
+  //     surface the error as HTTP 500 on every asset — far worse than
+  //     silently omitting CORS headers and letting the browser enforce its
+  //     own same-origin policy.
   const corsAllowedOrigins = config.corsAllowedOrigins ?? [];
   await fastify.register(cors, {
     origin: (origin, cb) => {
-      // Same-origin (no Origin header) — always allow
+      // Same-origin navigation (no Origin header) — always allow.
       if (!origin) return cb(null, true);
-      // Localhost / 127.0.0.1 / [::1] — any port
       try {
         const u = new URL(origin);
         const host = u.hostname;
+        // Loopback — any port.
         if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1") {
           return cb(null, true);
         }
-      } catch { /* ignore parse errors */ }
-      // Configured origins
+        // Active zrok tunnel URL — checked dynamically so URL rotation is
+        // picked up without a server restart.
+        const tunnelUrl = getTunnelUrl();
+        if (tunnelUrl && origin === tunnelUrl) return cb(null, true);
+        // Any *.share.zrok.io host — covers the brief window between a new
+        // reservation being created and the in-memory `activeTunnelUrl`
+        // being populated, plus any other zrok share the user points at us.
+        if (host.endsWith(".share.zrok.io")) return cb(null, true);
+      } catch { /* ignore URL parse errors */ }
+      // Explicitly configured origins.
       if (corsAllowedOrigins.includes(origin)) return cb(null, true);
-      cb(new Error("CORS origin not allowed"), false);
+      // Unknown cross-origin request — don't emit CORS headers, but don't
+      // 500 either. Browser will block the request for us.
+      cb(null, false);
     },
     credentials: true,
   });
@@ -294,7 +345,16 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   registerSessionRoutes(fastify, { sessionManager, eventStore, networkGuard });
   registerGitRoutes(fastify, { networkGuard });
   registerFileRoutes(fastify, { sessionManager, preferencesStore, networkGuard });
-  registerOpenSpecRoutes(fastify, { sessionManager, preferencesStore, directoryService, networkGuard });
+  registerOpenSpecRoutes(fastify, {
+    sessionManager,
+    preferencesStore,
+    directoryService,
+    networkGuard,
+    onOpenSpecChanged: (cwd) => {
+      const data = directoryService.getOpenSpecData(cwd);
+      if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
+    },
+  });
   registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion });
   // Package management
   const packageManagerWrapper = new PackageManagerWrapper();
@@ -304,7 +364,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     browserGateway.broadcastToAll({ type: "package_progress", operationId, event } as any);
   });
 
-  // On completion: broadcast to browsers
+  // On completion: broadcast to browsers + invalidate the recommended cache
   packageManagerWrapper.setCompleteListener((result) => {
     browserGateway.broadcastToAll({
       type: "package_operation_complete",
@@ -316,6 +376,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       error: result.error,
       sessionsReloaded: (result as any).sessionsReloaded,
     } as any);
+    if (result.success) invalidateRecommendedCache();
   });
 
   // Reload all active sessions after a successful package operation
@@ -337,14 +398,60 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   });
 
   registerPackageRoutes(fastify, { packageManagerWrapper });
+  registerRecommendedRoutes(fastify, { packageManagerWrapper });
+
+  // Pi core version check + update (complements the extension package manager).
+  const piCoreChecker = new PiCoreChecker();
+  const piCoreUpdater = new PiCoreUpdater({
+    packageManagerWrapper,
+    onAllComplete: async () => {
+      const connectedIds = piGateway.getConnectedSessionIds();
+      let count = 0;
+      for (const sid of connectedIds) {
+        const session = sessionManager.get(sid);
+        if (session && session.status !== "ended") {
+          piGateway.sendToSession(sid, {
+            type: "send_prompt",
+            sessionId: sid,
+            text: "/reload",
+          });
+          count++;
+        }
+      }
+      return count;
+    },
+  });
+  piCoreUpdater.setProgressListener((event) => {
+    browserGateway.broadcastToAll({
+      type: "pi_core_update_progress",
+      name: event.name,
+      phase: event.phase,
+      message: event.message,
+    });
+  });
+  registerPiCoreRoutes(fastify, {
+    piCoreChecker,
+    piCoreUpdater,
+    onUpdateComplete: (payload) => {
+      browserGateway.broadcastToAll({
+        type: "pi_core_update_complete",
+        results: payload.results,
+        sessionsReloaded: payload.sessionsReloaded,
+      });
+    },
+  });
 
-  // Editor (code-server) routes and proxy
+  // Editor (code-server) routes and proxy.
+  // NOTE: routes are *registered* here but cannot dispatch until fastify.listen runs
+  // inside server.start(). The orphan sweep in editorPidRegistry.cleanupOrphans()
+  // runs at the top of server.start() BEFORE fastify.listen, so any
+  // POST /api/editor/start call is guaranteed to see a post-sweep clean state.
   registerEditorRoutes(fastify, editorManager, { networkGuard });
   registerEditorProxy(fastify, editorManager);
 
-  registerProviderAuthRoutes(fastify, { piGateway });
+  registerProviderAuthRoutes(fastify, { piGateway, browserGateway });
   registerKnownServersRoutes(fastify, { networkGuard, getPeerServers: () => peerServers });
-  registerProviderRoutes(fastify, { networkGuard });
+  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway });
 
   // Serve static files / SPA fallback
   // Search order: npm package → workspace sibling → legacy dist/client
@@ -371,6 +478,13 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     await fastify.register(fastifyStatic, {
       root: clientDir,
       prefix: "/",
+      // Serve pre-compressed sibling files (assets/foo.js.gz alongside foo.js)
+      // directly when the client accepts gzip. This gives every compressed
+      // response a stable Content-Length header — dynamic compression via
+      // @fastify/compress streams responses without Content-Length, which
+      // some HTTP/2 proxy chains (notably zrok free-tier) occasionally
+      // stream-reset as ERR_ABORTED 500 in browsers.
+      preCompressed: true,
       setHeaders: (res, filePath) => {
         if (filePath.endsWith(".html")) {
           res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
@@ -435,10 +549,23 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     eventStore,
     browserGateway,
 
+    httpPort() {
+      const addr = fastify.server.address();
+      if (addr && typeof addr === "object") return addr.port;
+      return null;
+    },
+    piPort() {
+      return piGateway.address();
+    },
+
     async start() {
       // Clean up orphan headless processes from a previous server instance
       browserGateway.headlessPidRegistry.cleanupOrphans();
 
+      // Clean up orphan code-server processes from a previous server instance.
+      // Runs before fastify.listen, so no editor start request can race with the sweep.
+      await editorPidRegistry.cleanupOrphans();
+
       piGateway.start(config.piPort);
 
       fastify.server.on("upgrade", (request, socket, head) => {
@@ -501,10 +628,19 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
         console.warn(`mDNS browser failed (peer discovery disabled):`, err);
       }
 
+      // Always sweep leftover zrok processes on startup, even when tunnel is
+      // disabled (--no-tunnel). Orphans from a previous run hold reservations
+      // on the zrok edge and keep old URLs "alive but broken" until their
+      // agents are killed. Scavenge runs unconditionally when the binary is
+      // present; the tunnel-creation branch below is gated separately.
+      const hasZrok = detectZrokBinary();
+      if (hasZrok) {
+        cleanupStaleZrok();
+        scavengeOrphanZrokProcesses(config.port);
+      }
+
       if (config.tunnel) {
-        const hasZrok = detectZrokBinary();
         if (hasZrok) {
-          cleanupStaleZrok();
           const tunnelUrl = await createTunnel(config.port, config.tunnelReservedToken);
           if (tunnelUrl) {
             console.log(`🌐 Tunnel: ${tunnelUrl}`);
@@ -534,7 +670,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       preferencesStore.flush();
       preferencesStore.dispose();
 
-      await deleteTunnel();
+      await deleteTunnel(config.port);
       piGateway.stop();
       for (const client of browserGateway.wss.clients) {
         client.terminate();

package/packages/server/src/terminal-manager.ts

@@ -4,6 +4,7 @@
 import * as pty from "node-pty";
 import type { IPty } from "node-pty";
 import { randomBytes } from "node:crypto";
+import { fixPtyPermissions } from "./fix-pty-permissions.js";
 import type { TerminalSession, TerminalControlMessage } from "@blackbelt-technology/pi-dashboard-shared/terminal-types.js";
 import type { WebSocket } from "ws";
 
@@ -99,6 +100,9 @@ function generateId(): string {
 }
 
 export function createTerminalManager(options?: TerminalManagerOptions): TerminalManager {
+  // Fix node-pty spawn-helper permissions at runtime (defense in depth)
+  fixPtyPermissions();
+
   const entries = new Map<string, TerminalEntry>();
   const bufferSize = options?.bufferSize ?? DEFAULT_BUFFER_SIZE;
 

package/packages/server/src/test-env-guard.ts

@@ -0,0 +1,26 @@
+/**
+ * Defense-in-depth guard against destructive PID-registry sweeps during tests.
+ *
+ * Production startup code paths (headlessPidRegistry.cleanupOrphans/killAll,
+ * editorPidRegistry.cleanupOrphans) read PID files and send SIGTERM. If they
+ * ever run under vitest AGAINST the developer's real $HOME, they can kill
+ * live pi sessions.
+ *
+ * This guard returns true when:
+ *   - we appear to be inside a vitest run (VITEST env var), AND
+ *   - HOME still points at the real user home (tripwire missed).
+ *
+ * Callers SHOULD `console.warn` and return without performing destructive work
+ * when this returns true.
+ *
+ * Normal production servers (VITEST not set) always get `false` and behave as
+ * before.
+ */
+import os from "node:os";
+
+export function isUnsafeTestHomeScan(): boolean {
+  if (process.env.VITEST !== "true") return false;
+  const currentHome = process.env.HOME ?? "";
+  const realHome = os.userInfo().homedir;
+  return currentHome === "" || currentHome === realHome;
+}

package/packages/server/src/test-support/test-server.ts

@@ -0,0 +1,63 @@
+/**
+ * createTestServer — boot a real DashboardServer on OS-assigned ports for
+ * integration tests, with safe defaults (no auto-shutdown, no tunnel).
+ *
+ * Use with the `setup-home` vitest setupFile (in @blackbelt-technology/pi-dashboard-shared/test-support)
+ * so that HOME is also isolated.
+ *
+ * Example:
+ *   const { server, httpPort, piPort, stop } = await createTestServer();
+ *   const res = await fetch(`http://localhost:${httpPort}/api/health`);
+ *   ...
+ *   await stop();
+ */
+import { createServer, type DashboardServer, type ServerConfig } from "../server.js";
+
+export interface TestServerHandle {
+  server: DashboardServer;
+  httpPort: number;
+  piPort: number;
+  stop: () => Promise<void>;
+}
+
+export type TestServerOverrides = Partial<ServerConfig>;
+
+const DEFAULTS: ServerConfig = {
+  port: 0,
+  piPort: 0,
+  dev: true,
+  autoShutdown: false,
+  shutdownIdleSeconds: 999,
+  tunnel: false,
+  editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+};
+
+export async function createTestServer(
+  overrides: TestServerOverrides = {},
+): Promise<TestServerHandle> {
+  const config: ServerConfig = { ...DEFAULTS, ...overrides };
+  const server = await createServer(config);
+  await server.start();
+
+  const httpPort = server.httpPort();
+  const piPort = server.piPort();
+  if (httpPort == null || piPort == null) {
+    await server.stop();
+    throw new Error(
+      `createTestServer: failed to resolve ports (httpPort=${httpPort}, piPort=${piPort})`,
+    );
+  }
+
+  return {
+    server,
+    httpPort,
+    piPort,
+    stop: async () => {
+      try {
+        await server.stop();
+      } catch {
+        // best-effort — tests may race on shutdown
+      }
+    },
+  };
+}