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

package/packages/server/src/routes/pi-core-routes.ts

@@ -0,0 +1,140 @@
+/**
+ * REST routes for pi core version check and update.
+ *
+ *   GET  /api/pi-core/versions[?refresh=true]
+ *   POST /api/pi-core/update                 { packages?: string[] }
+ *
+ * Complements /api/packages/* (extension management): this endpoint covers
+ * globally-installed pi CLI packages like @mariozechner/pi-coding-agent,
+ * pi-dashboard itself, pi-model-proxy, etc.
+ */
+import type { FastifyInstance } from "fastify";
+import type {
+	ApiResponse,
+	PiCoreStatus,
+	PiCoreUpdateRequest,
+	PiCoreUpdateResponse,
+} from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import type { PiCoreChecker } from "../pi-core-checker.js";
+import type { PiCoreUpdater } from "../pi-core-updater.js";
+import { PackageOperationBusyError } from "../package-manager-wrapper.js";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
+
+export interface PiCoreRouteDeps {
+	piCoreChecker: PiCoreChecker;
+	piCoreUpdater: PiCoreUpdater;
+	/**
+	 * When provided, pi-core endpoints return 503 unless bootstrap
+	 * status is "ready". See change: unified-bootstrap-install §5.5.
+	 */
+	bootstrapState?: BootstrapStateStore;
+	/**
+	 * Called after the updater finishes a batch (success or per-package failure).
+	 * The server wires this to broadcast a `pi_core_update_complete` WS message
+	 * so listeners (PiUpdateBadge, PiCoreVersionsSection, usePiCoreVersions
+	 * hook instances in other open tabs) refetch their state.
+	 */
+	onUpdateComplete?: (payload: {
+		results: Array<{ name: string; success: boolean; error?: string }>;
+		sessionsReloaded: number;
+	}) => void;
+}
+
+export function registerPiCoreRoutes(
+	fastify: FastifyInstance,
+	deps: PiCoreRouteDeps,
+): void {
+	const { piCoreChecker, piCoreUpdater, bootstrapState } = deps;
+
+	/** Gate: 503 unless bootstrap is ready. Returns undefined when OK to proceed. */
+	const bootstrapGate = async (
+		_req: unknown,
+		reply: { code: (n: number) => { send: (body: unknown) => unknown } },
+	): Promise<unknown> => {
+		if (!bootstrapState) return undefined;
+		const status = bootstrapState.get().status;
+		if (status === "ready") return undefined;
+		return reply.code(503).send({
+			success: false,
+			error: `pi not yet installed (bootstrap status: ${status})`,
+			bootstrap: status,
+		});
+	};
+
+	// ── GET /api/pi-core/versions ──────────────────────────────────
+
+	fastify.get<{ Querystring: { refresh?: string } }>(
+		"/api/pi-core/versions",
+		{ preHandler: bootstrapGate as any },
+		async (request) => {
+			const refresh = request.query.refresh === "true";
+			try {
+				const status = await piCoreChecker.getStatus(refresh);
+				return { success: true, data: status } satisfies ApiResponse<PiCoreStatus>;
+			} catch (err: any) {
+				return { success: false, error: err?.message ?? String(err) } satisfies ApiResponse;
+			}
+		},
+	);
+
+	// ── POST /api/pi-core/update ───────────────────────────────────
+
+	fastify.post<{ Body: PiCoreUpdateRequest }>(
+		"/api/pi-core/update",
+		{ preHandler: bootstrapGate as any },
+		async (request, reply) => {
+			const requested = request.body?.packages ?? [];
+
+			// Load current status to determine install source and eligibility.
+			const status = await piCoreChecker.getStatus();
+			const allByName = new Map(status.packages.map((p) => [p.name, p]));
+
+			const targetNames =
+				requested.length > 0
+					? requested
+					: status.packages.filter((p) => p.updateAvailable).map((p) => p.name);
+
+			const resolved = [];
+			const unknown: string[] = [];
+			for (const name of targetNames) {
+				const pkg = allByName.get(name);
+				if (!pkg) {
+					unknown.push(name);
+					continue;
+				}
+				resolved.push(pkg);
+			}
+
+			if (unknown.length > 0) {
+				reply.code(400);
+				return {
+					success: false,
+					error: `Unknown package(s): ${unknown.join(", ")}`,
+				} satisfies ApiResponse;
+			}
+
+			if (resolved.length === 0) {
+				return {
+					success: true,
+					data: { results: [], sessionsReloaded: 0 },
+				} satisfies ApiResponse<PiCoreUpdateResponse>;
+			}
+
+			try {
+				const out = await piCoreUpdater.update(resolved);
+				// Invalidate cache so next version check reflects new versions.
+				piCoreChecker.invalidate();
+				// Notify other browser tabs / the header badge hook instance so
+				// their independent usePiCoreVersions state refetches.
+				deps.onUpdateComplete?.(out);
+				return { success: true, data: out } satisfies ApiResponse<PiCoreUpdateResponse>;
+			} catch (err: any) {
+				if (err instanceof PackageOperationBusyError) {
+					reply.code(409);
+					return { success: false, error: err.message } satisfies ApiResponse;
+				}
+				return { success: false, error: err?.message ?? String(err) } satisfies ApiResponse;
+			}
+		},
+	);
+}

package/packages/server/src/routes/provider-auth-routes.ts

@@ -1,7 +1,6 @@
 /**
  * REST routes for browser-based pi provider authentication.
  */
-import { exec } from "node:child_process";
 import type { FastifyInstance } from "fastify";
 import {
   getProviderHandler,
@@ -21,6 +20,7 @@ import {
 } from "../provider-auth-storage.js";
 import { startCallbackServer } from "../oauth-callback-server.js";
 import type { PiGateway } from "../pi-gateway.js";
+import type { BrowserGateway } from "../browser-gateway.js";
 
 // ── In-memory flow store (short-lived PKCE + device code state) ──────────────
 
@@ -65,15 +65,16 @@ function makeFlowId(): string {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
+// Delegate to the shared platform primitive. The cross-OS dispatch
+// (open/start/xdg-open) and URL escaping live in
+// `packages/shared/src/platform/commands.ts`.
+// See change: consolidate-platform-handlers.
+import { openBrowser as platformOpenBrowser } from "@blackbelt-technology/pi-dashboard-shared/platform/commands.js";
+
 /** Open a URL in the system's default browser */
 function openInBrowser(url: string): void {
-  const cmd = process.platform === "darwin"
-    ? `open ${JSON.stringify(url)}`
-    : process.platform === "win32"
-      ? `start "" ${JSON.stringify(url)}`
-      : `xdg-open ${JSON.stringify(url)}`;
-  exec(cmd, (err) => {
-    if (err) console.error("[provider-auth] Failed to open browser:", err.message);
+  platformOpenBrowser(url, {
+    onError: (err) => console.error("[provider-auth] Failed to open browser:", err.message),
   });
 }
 
@@ -81,12 +82,13 @@ function openInBrowser(url: string): void {
 
 export function registerProviderAuthRoutes(
   fastify: FastifyInstance,
-  deps: { piGateway: PiGateway },
+  deps: { piGateway: PiGateway; browserGateway: BrowserGateway },
 ) {
-  const { piGateway } = deps;
+  const { piGateway, browserGateway } = deps;
 
   function notifyBridges() {
     piGateway.broadcast({ type: "credentials_updated" });
+    browserGateway.broadcastToAll({ type: "models_refreshed" });
   }
 
   // List OAuth providers

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

@@ -6,6 +6,9 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import type { NetworkGuard } from "./route-deps.js";
+import type { PiGateway } from "../pi-gateway.js";
+import type { BrowserGateway } from "../browser-gateway.js";
+import { probeProvider, resolveProbeApiKey, type ProbeApi } from "../provider-probe.js";
 
 const REDACTED = "***";
 const CONFIG_PATH = join(homedir(), ".pi", "agent", "providers.json");
@@ -44,8 +47,8 @@ function redactProviders(
   return redacted;
 }
 
-export function registerProviderRoutes(fastify: FastifyInstance, deps: { networkGuard: NetworkGuard }): void {
-  const { networkGuard } = deps;
+export function registerProviderRoutes(fastify: FastifyInstance, deps: { networkGuard: NetworkGuard; piGateway?: PiGateway; browserGateway?: BrowserGateway }): void {
+  const { networkGuard, piGateway } = deps;
   fastify.get(
     "/api/providers",
     { preHandler: networkGuard },
@@ -95,7 +98,57 @@ export function registerProviderRoutes(fastify: FastifyInstance, deps: { network
       mkdirSync(dir, { recursive: true });
       writeFileSync(CONFIG_PATH, JSON.stringify(fileData, null, 2) + "\n", "utf-8");
 
+      // Broadcast credentials_updated so all sessions refresh their model registries
+      if (piGateway) {
+        piGateway.broadcast({ type: "credentials_updated" });
+      }
+      if (deps.browserGateway) {
+        deps.browserGateway.broadcastToAll({ type: "models_refreshed" });
+      }
+
       return { success: true };
     },
   );
+
+  // Test a provider configuration without saving it. Accepts literal api keys,
+  // $ENV_VAR references, or the REDACTED sentinel (***) for already-saved entries.
+  fastify.post(
+    "/api/providers/test",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const body = request.body as Record<string, any> | null;
+      if (!body || typeof body !== "object") {
+        return reply.code(400).send({ ok: false, error: "Invalid body" });
+      }
+      const name = typeof body.name === "string" ? body.name : undefined;
+      const baseUrl = typeof body.baseUrl === "string" ? body.baseUrl.trim() : "";
+      const apiKey = typeof body.apiKey === "string" ? body.apiKey : "";
+      const api = typeof body.api === "string" ? (body.api as ProbeApi) : undefined;
+      if (!baseUrl) {
+        return reply.code(400).send({ ok: false, error: "baseUrl is required" });
+      }
+      if (!apiKey) {
+        return reply.code(400).send({ ok: false, error: "apiKey is required" });
+      }
+      if (!api) {
+        return reply.code(400).send({ ok: false, error: "api type is required" });
+      }
+
+      const resolved = resolveProbeApiKey({
+        apiKey,
+        name,
+        readProviders: readProvidersRaw,
+      });
+      if (!resolved.ok) {
+        return { ok: false, error: resolved.error };
+      }
+
+      const result = await probeProvider({
+        baseUrl,
+        apiKey: resolved.key,
+        api,
+      });
+      return result;
+    },
+  );
 }

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

@@ -0,0 +1,225 @@
+/**
+ * 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[];
+			}>;
+		}
+
+		// Run global + local listInstalled in parallel to halve cold-start
+		// latency. On Windows where each call instantiates pi's
+		// DefaultPackageManager (1-3s cold), sequential awaits were making
+		// the "Loading recommended extensions" spinner stick for ~15s.
+		const [installedGlobalRes, installedLocalRes] = await Promise.allSettled([
+			deps.packageManagerWrapper.listInstalled("global"),
+			deps.packageManagerWrapper.listInstalled("local"),
+		]);
+		const installedGlobal = (installedGlobalRes.status === "fulfilled" ? installedGlobalRes.value : []) as Array<{ source: string; installedPath?: string }>;
+		const installedLocal = (installedLocalRes.status === "fulfilled" ? installedLocalRes.value : []) as Array<{ source: string; installedPath?: string }>;
+
+		// 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

@@ -5,6 +5,7 @@ import type { FastifyInstance } from "fastify";
 import type { SessionManager } from "../memory-session-manager.js";
 import type { PreferencesStore } from "../preferences-store.js";
 import type { MetaPersistence } from "../meta-persistence.js";
+import type { DirectoryService } from "../directory-service.js";
 import type { ServerConfig } from "../server.js";
 import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { NetworkGuard } from "./route-deps.js";
@@ -12,7 +13,8 @@ import { detectEditors, EDITORS } from "../editor-registry.js";
 import { detectCodeServerBinary, resetDetectionCache } from "../editor-detection.js";
 import { readConfigRedacted, writeConfigPartial } from "../config-api.js";
 import { createTunnel, deleteTunnel, getTunnelStatus } from "../tunnel.js";
-import { spawn } from "node:child_process";
+import { spawnRestart } from "../restart-helper.js";
+import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import path from "node:path";
 import os from "node:os";
 import { localhostGuard, netmaskToCidrBits, networkAddress } from "../localhost-guard.js";
@@ -27,9 +29,10 @@ export function registerSystemRoutes(
     config: ServerConfig;
     networkGuard: NetworkGuard;
     version?: string;
+    directoryService?: DirectoryService;
   },
 ) {
-  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version } = deps;
+  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService } = deps;
   const serverStartTime = Date.now();
 
   // Editor detection endpoint
@@ -127,6 +130,9 @@ export function registerSystemRoutes(
           await (fastify as any)._reloadAuth(reloaded.auth);
         }
       }
+      if (partial.openspec !== undefined && directoryService) {
+        directoryService.reconfigurePolling(reloaded.openspec);
+      }
 
       return { success: true, restartRequired: result.restartRequired };
     },
@@ -147,7 +153,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 +194,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,47 +210,32 @@ 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" };
 
       // Find the TypeScript loader from process.execArgv (--import <loader>)
       const importIdx = process.execArgv.indexOf("--import");
-      const loaderArgs = importIdx >= 0 ? ["--import", process.execArgv[importIdx + 1]] : [];
+      const loader = importIdx >= 0 ? (process.execArgv[importIdx + 1] ?? "") : "";
 
       // Allow overriding dev mode via request body
       const useDev = request.body?.dev ?? config.dev;
-      const args = ["start"];
-      if (useDev) args.push("--dev");
-
-      // Spawn a shell script that:
-      // 1. Waits for the old server's port to be free (up to 10s)
-      // 2. Starts the new server
-      // 3. Verifies health (up to 10s)
-      // 4. If health check fails, logs error
-      const port = config.port;
-      const nodeCmd = `${JSON.stringify(process.execPath)} ${loaderArgs.map(a => JSON.stringify(a)).join(" ")} ${JSON.stringify(cliPath)} ${args.join(" ")}`;
-      const script = [
-        // Wait for port to be free
-        `for i in $(seq 1 20); do`,
-        `  lsof -i :${port} -sTCP:LISTEN >/dev/null 2>&1 || break`,
-        `  sleep 0.5`,
-        `done`,
-        // Start new server
-        nodeCmd,
-        // Verify health
-        `for i in $(seq 1 20); do`,
-        `  curl -sf http://localhost:${port}/api/health >/dev/null 2>&1 && exit 0`,
-        `  sleep 0.5`,
-        `done`,
-        `echo "[dashboard] Restart health check failed" >&2`,
-      ].join("\n");
+      const extraArgs: string[] = [];
+      if (useDev) extraArgs.push("--dev");
 
-      const child = spawn("sh", ["-c", script], {
-        detached: true,
-        stdio: "ignore",
-        env: { ...process.env },
+      // Cross-platform restart: spawns a detached Node orchestrator that
+      // polls the port via net, spawns the new server, polls /api/health
+      // via http. No dependency on sh/lsof/curl — works on Windows too.
+      // See change: fix-windows-server-parity.
+      spawnRestart({
+        cliPath,
+        loader,
+        port: config.port,
+        extraArgs,
       });
-      child.unref();
 
       setTimeout(() => process.exit(0), 200);
       return { ok: true };