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

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

@@ -22,6 +22,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { fetchPackageMeta } from "./npm-search-proxy.js";
+import { invalidateChangelogCache } from "./changelog-parser.js";
+import { getLatestPiRelease, type PiDevReleaseInfo } from "./pi-dev-version-check.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -34,16 +36,16 @@ const MANAGED_NODE_MODULES = path.join(MANAGED_DIR, "node_modules");
 
 /** Known core packages (not extensions). Order matters for display. */
 export const CORE_PACKAGE_NAMES: readonly string[] = [
+	"@earendil-works/pi-coding-agent",
 	"@mariozechner/pi-coding-agent",
-	"@oh-my-pi/pi-coding-agent",
 	"@blackbelt-technology/pi-agent-dashboard",
 	"@blackbelt-technology/pi-model-proxy",
 ];
 
 /** Display name mapping for known packages. Falls back to package name. */
 const DISPLAY_NAMES: Readonly<Record<string, string>> = {
-	"@mariozechner/pi-coding-agent": "pi (core agent)",
-	"@oh-my-pi/pi-coding-agent": "pi (core agent — fork)",
+	"@earendil-works/pi-coding-agent": "pi (core agent)",
+	"@mariozechner/pi-coding-agent": "pi (core agent — legacy fork)",
 	"@blackbelt-technology/pi-agent-dashboard": "pi-dashboard",
 	"@blackbelt-technology/pi-model-proxy": "pi-model-proxy",
 };
@@ -68,20 +70,40 @@ function resolveDisplayName(name: string): string {
 	return DISPLAY_NAMES[name] ?? name;
 }
 
+/**
+ * Dynamically-discovered package-name aliases for `@mariozechner/pi-coding-agent`.
+ * Populated from pi.dev's `latest-version` response, which returns the
+ * authoritative package name for fresh installs (used for the upcoming
+ * `@mariozechner` → `@earendil-works` scope migration). The dashboard
+ * accepts whatever name pi.dev declares as a trusted alias — this avoids
+ * having to ship a release every time the canonical scope changes.
+ *
+ * See change: improve-pi-update-detection.
+ */
+let dynamicPiAliases: Set<string> = new Set();
+
+/** Test seam: clear runtime aliases between tests. */
+export function _resetDynamicPiAliases(): void {
+	dynamicPiAliases = new Set();
+}
+
 /**
  * Strict whitelist check: a package is part of the pi-ecosystem CORE
- * tooling if and only if its name is in `CORE_PACKAGE_NAMES`. The
- * previous `pi-*` name-prefix heuristic was removed because it caused
- * recommended-extension packages (e.g. `pi-agent-browser`,
- * `@tintinweb/pi-subagents`) to appear in BOTH the Core ecosystem panel
- * and the Installed Packages panel. Recommended extensions are now
- * surfaced exclusively through `/api/packages/installed`. See change:
- * consolidate-packages-settings-ui.
+ * tooling if and only if its name is in `CORE_PACKAGE_NAMES` OR a
+ * pi.dev-declared alias. The previous `pi-*` name-prefix heuristic was
+ * removed because it caused recommended-extension packages (e.g.
+ * `pi-agent-browser`, `@tintinweb/pi-subagents`) to appear in BOTH the
+ * Core ecosystem panel and the Installed Packages panel. Recommended
+ * extensions are now surfaced exclusively through
+ * `/api/packages/installed`. See change: consolidate-packages-settings-ui.
  */
 function looksLikePiEcosystem(name: string): boolean {
-	return CORE_PACKAGE_NAMES.includes(name);
+	return CORE_PACKAGE_NAMES.includes(name) || dynamicPiAliases.has(name);
 }
 
+/** Pi packages whose latestVersion comes from pi.dev (not npm registry). */
+const PI_DEV_PACKAGE = "@mariozechner/pi-coding-agent";
+
 export interface NpmListRunner {
 	/** Run `npm list -g --depth=0 --json` and return stdout. */
 	(): Promise<string>;
@@ -92,6 +114,13 @@ export interface PiCoreCheckerOptions {
 	npmList?: NpmListRunner;
 	/** Inject version fetcher (for tests). */
 	fetchLatest?: (packageName: string) => Promise<string | null>;
+	/**
+	 * Inject pi.dev release fetcher (for tests). Production uses
+	 * `getLatestPiRelease` which honours PI_OFFLINE / PI_SKIP_VERSION_CHECK
+	 * envs and falls back to `undefined` on any failure. See change:
+	 * improve-pi-update-detection.
+	 */
+	fetchPiDevRelease?: (currentVersion: string) => Promise<PiDevReleaseInfo | undefined>;
 	/** Override managed directory (for tests). */
 	managedDir?: string;
 }
@@ -114,19 +143,28 @@ export class PiCoreChecker {
 	private cache: { at: number; data: PiCoreStatus } | null = null;
 	private readonly npmList: NpmListRunner;
 	private readonly fetchLatest: (packageName: string) => Promise<string | null>;
+	private readonly fetchPiDevRelease: (currentVersion: string) => Promise<PiDevReleaseInfo | undefined>;
 	private readonly managedNodeModules: string;
 
 	constructor(opts: PiCoreCheckerOptions = {}) {
 		this.npmList = opts.npmList ?? defaultNpmList;
 		this.fetchLatest = opts.fetchLatest ?? defaultFetchLatest;
+		this.fetchPiDevRelease = opts.fetchPiDevRelease ?? getLatestPiRelease;
 		this.managedNodeModules = opts.managedDir
 			? path.join(opts.managedDir, "node_modules")
 			: MANAGED_NODE_MODULES;
 	}
 
-	/** Invalidate the cache (e.g. after an update completes). */
+	/**
+	 * Invalidate the cache (e.g. after an update completes).
+	 *
+	 * Also clears the changelog parser cache so the next
+	 * `GET /api/pi-core/changelog` request reads the freshly-installed
+	 * file from disk. See change: pi-update-whats-new-panel.
+	 */
 	invalidate(): void {
 		this.cache = null;
+		invalidateChangelogCache();
 	}
 
 	/** Get version status. Returns cached data within 5 min unless `refresh`. */
@@ -144,15 +182,37 @@ export class PiCoreChecker {
 		for (const entry of global) byName.set(entry.name, { version: entry.version, source: "global" });
 		for (const entry of managed) byName.set(entry.name, { version: entry.version, source: "managed" });
 
-		// Fetch latest versions in parallel.
+		// Fetch latest versions in parallel. For pi-coding-agent (and its
+		// declared scope-rename aliases), prefer pi.dev's authoritative
+		// version-check endpoint over the npm registry; fall back to npm
+		// registry on any failure so the dashboard never reports "unknown
+		// version" just because pi.dev had a hiccup. See change:
+		// improve-pi-update-detection.
 		const entries = Array.from(byName.entries());
 		const withLatest = await Promise.all(
 			entries.map(async ([name, info]) => {
 				let latest: string | null = null;
-				try {
-					latest = await this.fetchLatest(name);
-				} catch {
-					latest = null;
+				const isPi = name === PI_DEV_PACKAGE || dynamicPiAliases.has(name);
+				if (isPi) {
+					try {
+						const piDev = await this.fetchPiDevRelease(info.version);
+						if (piDev) {
+							latest = piDev.version;
+							// Record any new alias for next-time discovery.
+							if (piDev.packageName && !CORE_PACKAGE_NAMES.includes(piDev.packageName)) {
+								dynamicPiAliases.add(piDev.packageName);
+							}
+						}
+					} catch {
+						/* fall through to npm registry */
+					}
+				}
+				if (latest === null) {
+					try {
+						latest = await this.fetchLatest(name);
+					} catch {
+						latest = null;
+					}
 				}
 				const updateAvailable = latest !== null && latest !== info.version;
 				const pkg: PiCorePackage = {

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

@@ -1,10 +1,16 @@
 /**
  * Pi core package updater.
  *
- * Runs `npm update -g <pkg>` for globally-installed packages or
- * `npm update <pkg>` in `~/.pi-dashboard/` for managed installs.
+ * Runs `npm install -g <pkg>@latest` for globally-installed packages or
+ * `npm install <pkg>@latest` in `~/.pi-dashboard/` for managed installs.
+ * The `@latest` suffix is required because the consuming `package.json`
+ * dependency range (e.g. `^0.70.0`) would otherwise pin updates to the
+ * same minor — breaking cross-minor upgrades that pi now ships routinely
+ * (0.71+ minors carry breaking changes per its CHANGELOG).
  * Coordinates with PackageManagerWrapper's busy-lock so extension
  * operations and core updates can't run concurrently.
+ *
+ * See change: fix-pi-core-update-cross-minor.
  */
 import { spawn } from "node:child_process"; // ban:child_process-ok npm-update streams stdout/stderr via pipe for progress events; refactor to platform/spawn Recipe is tracked tech debt
 import path from "node:path";
@@ -75,10 +81,14 @@ export function defaultRunNpmUpdate(
 	seams: DefaultRunNpmUpdateSeams = {},
 ): Promise<void> {
 	return new Promise((resolve, reject) => {
+		// Always target the npm `latest` dist-tag — bypasses the
+		// consuming package.json range so cross-minor jumps work. See
+		// change: fix-pi-core-update-cross-minor.
+		const spec = `${pkg.name}@latest`;
 		const args =
 			pkg.installSource === "global"
-				? ["update", "-g", pkg.name]
-				: ["update", pkg.name];
+				? ["install", "-g", spec]
+				: ["install", spec];
 		const cwd = pkg.installSource === "managed" ? MANAGED_DIR : process.cwd();
 
 		if (pkg.installSource === "managed" && !existsSync(MANAGED_DIR)) {
@@ -149,9 +159,9 @@ export function defaultRunNpmUpdate(
 			} else {
 				const hint =
 					pkg.installSource === "global" && /permission|EACCES|EPERM|EROFS/i.test(stderrBuf)
-						? ` (permission error — try: sudo npm update -g ${pkg.name})`
+						? ` (permission error — try: sudo npm install -g ${pkg.name}@latest)`
 						: "";
-				reject(new Error(`npm update exited with code ${code}${hint}`));
+				reject(new Error(`npm install exited with code ${code}${hint}`));
 			}
 		});
 	});

package/packages/server/src/pi-dev-version-check.ts

@@ -0,0 +1,145 @@
+/**
+ * pi.dev version-check client. Mirrors the implementation pi itself
+ * uses for self-update checks (see `@mariozechner/pi-coding-agent/dist/
+ * utils/version-check.js`). Returns `{ version, packageName? }` so the
+ * dashboard can:
+ *   1. Detect the genuinely-newest pi without npm-registry lag.
+ *   2. Pick up pi's npm-scope migration dynamically (the response's
+ *      `packageName` field is the upstream's authoritative answer to
+ *      "which package should be installed for the latest pi?").
+ *
+ * Falls back to `undefined` on any error so callers can degrade to
+ * the npm-registry path. Honours `PI_OFFLINE` and `PI_SKIP_VERSION_CHECK`
+ * envs identically to pi.
+ *
+ * See change: improve-pi-update-detection.
+ */
+
+const LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export interface PiDevReleaseInfo {
+  /** Latest version string as published by pi.dev (e.g. `"0.74.0"`). */
+  version: string;
+  /**
+   * Authoritative package name for fresh installs. Pi 0.73.1+ returns
+   * this so consumers can follow npm-scope migrations without code
+   * changes. Absent for older pi.dev responses.
+   */
+  packageName?: string;
+}
+
+export interface PiDevVersionCheckOptions {
+  /** Override fetch timeout. Default 10 s, matching pi. */
+  timeoutMs?: number;
+  /** Test seam: override fetch implementation. */
+  fetchImpl?: typeof fetch;
+}
+
+interface ParsedSemver {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string;
+}
+
+/**
+ * Parse a semver-ish version string. Mirrors pi's `parsePackageVersion`.
+ * Returns `undefined` for unparseable input so callers fall back to a
+ * conservative comparison.
+ */
+export function parsePackageVersion(version: string): ParsedSemver | undefined {
+  const match = version
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+  if (!match) return undefined;
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prerelease: match[4],
+  };
+}
+
+/**
+ * Compare two semver strings: -ve when left < right, 0 when equal,
+ * +ve when left > right. Returns `undefined` when either side is
+ * unparseable.
+ */
+export function comparePackageVersions(
+  leftVersion: string,
+  rightVersion: string,
+): number | undefined {
+  const left = parsePackageVersion(leftVersion);
+  const right = parsePackageVersion(rightVersion);
+  if (!left || !right) return undefined;
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  if (left.patch !== right.patch) return left.patch - right.patch;
+  if (left.prerelease === right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  return left.prerelease.localeCompare(right.prerelease);
+}
+
+/** True when `candidateVersion` is strictly newer than `currentVersion`. */
+export function isNewerPackageVersion(
+  candidateVersion: string,
+  currentVersion: string,
+): boolean {
+  const cmp = comparePackageVersions(candidateVersion, currentVersion);
+  if (cmp !== undefined) return cmp > 0;
+  return candidateVersion.trim() !== currentVersion.trim();
+}
+
+/**
+ * Build the User-Agent string pi sends on its self-update calls.
+ * Format: `pi/<version> (<platform>; <runtime>; <arch>)`.
+ *
+ * `<runtime>` is `bun/<version>` when running under Bun, otherwise
+ * `node/<process.version>`. We don't identify the dashboard separately
+ * so pi.dev treats the request the same way as a self-update from pi.
+ */
+export function getPiUserAgent(version: string, runtime?: string): string {
+  const rt =
+    runtime ??
+    ((globalThis as { Bun?: { version: string } }).Bun?.version
+      ? `bun/${(globalThis as { Bun?: { version: string } }).Bun!.version}`
+      : `node/${process.version}`);
+  return `pi/${version} (${process.platform}; ${rt}; ${process.arch})`;
+}
+
+/**
+ * Query pi.dev for the latest release info. Returns `undefined` on
+ * any of: env-skipped, network error, non-2xx response, malformed
+ * JSON, missing `version` field, timeout.
+ */
+export async function getLatestPiRelease(
+  currentVersion: string,
+  opts: PiDevVersionCheckOptions = {},
+): Promise<PiDevReleaseInfo | undefined> {
+  if (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) {
+    return undefined;
+  }
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  try {
+    const response = await fetchFn(LATEST_VERSION_URL, {
+      headers: {
+        "User-Agent": getPiUserAgent(currentVersion),
+        accept: "application/json",
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return undefined;
+    const data = (await response.json()) as { version?: unknown; packageName?: unknown };
+    if (typeof data.version !== "string" || !data.version.trim()) return undefined;
+    const packageName =
+      typeof data.packageName === "string" && data.packageName.trim()
+        ? data.packageName.trim()
+        : undefined;
+    return { version: data.version.trim(), packageName };
+  } catch {
+    return undefined;
+  }
+}

package/packages/server/src/pi-gateway.ts

@@ -275,7 +275,11 @@ export function createPiGateway(
 
             if (msg.type === "session_register") {
               // Clear spawn-register watchdog BEFORE any throwing logic. See change: spawn-failure-diagnostics.
+              // Priority: token > pid > cwd. Token is the strongest identity
+              // (spawn-correlation-token); pid catches headless without token;
+              // cwd is the legacy fallback for tmux/wt with neither.
               const watchdog = getSpawnRegisterWatchdog();
+              if (msg.spawnToken) watchdog.clearByToken(msg.spawnToken);
               if (msg.pid !== undefined) watchdog.clearByPid(msg.pid);
               watchdog.clearByCwd(msg.cwd);
 

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

@@ -98,10 +98,18 @@ export function readPiCompatibility(serverPkgJsonPath: string): Pick<
 export function readCurrentPiVersion(registry: ToolRegistry = getDefaultRegistry()): string | undefined {
   try {
     const req = createRequire(import.meta.url);
-    const pkgJson = req.resolve("@mariozechner/pi-coding-agent/package.json");
-    const raw = fs.readFileSync(pkgJson, "utf8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    if (typeof parsed.version === "string") return parsed.version;
+    let pkgJson: string | undefined;
+    for (const name of ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"]) {
+      try {
+        pkgJson = req.resolve(`${name}/package.json`);
+        break;
+      } catch { /* try next alias */ }
+    }
+    if (pkgJson) {
+      const raw = fs.readFileSync(pkgJson, "utf8");
+      const parsed = JSON.parse(raw) as { version?: string };
+      if (typeof parsed.version === "string") return parsed.version;
+    }
   } catch {
     /* not resolvable yet */
   }

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

@@ -23,6 +23,13 @@ import type { SpawnStrategy } from "@blackbelt-technology/pi-dashboard-shared/co
 import { MANAGED_BIN } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
 import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
 import { prependManagedNodeToPath } from "@blackbelt-technology/pi-dashboard-shared/platform/managed-node-path.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { mintSpawnToken } from "./spawn-token.js";
+import {
+  createKeeperManager,
+  type KeeperManager,
+} from "./rpc-keeper/keeper-manager.js";
+import { randomUUID } from "node:crypto";
 import { execSync, spawnSync, buildSafeArgv } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import {
   spawnDetached,
@@ -51,12 +58,56 @@ export function resetResolver(): void {
   resolver = new ToolResolver({ processExecPath: process.execPath });
 }
 
+// ── KeeperManager seam (injectable for tests) ──────────────────────────
+
+let keeperManager: KeeperManager | null = null;
+
+/** Inject a KeeperManager — used by tests. Production code lazy-inits below. */
+export function setKeeperManager(km: KeeperManager | null): void {
+  keeperManager = km;
+}
+
+/**
+ * Public lazy accessor for the singleton `KeeperManager`. Exposed so the
+ * server-side dispatch handler (`rpc-keeper/dispatch-router.ts`) and
+ * `headlessPidRegistry.setKeeperWriter` can share the same instance the
+ * spawn path uses. Tests still inject via `setKeeperManager`.
+ * See change: add-rpc-stdin-dispatch-with-keeper-sidecar (Phase 6 + 8).
+ */
+export function getKeeperManager(): KeeperManager {
+  if (!keeperManager) keeperManager = createKeeperManager();
+  return keeperManager;
+}
+
+/**
+ * Hook used by tests to override the `useRpcKeeper` flag read from config
+ * without mutating `~/.pi/dashboard/config.json`. Returns `null` to defer
+ * to the real config.
+ */
+let useRpcKeeperOverride: boolean | null = null;
+export function _setUseRpcKeeperOverrideForTests(v: boolean | null): void {
+  useRpcKeeperOverride = v;
+}
+function shouldUseRpcKeeper(): boolean {
+  if (useRpcKeeperOverride !== null) return useRpcKeeperOverride;
+  try { return loadConfig().useRpcKeeper === true; } catch { return false; }
+}
+
 // ── Public API ─────────────────────────────────────────────────────────────
 
 export interface SessionOptions {
   sessionFile?: string;
   mode?: "continue" | "fork";
   strategy?: SpawnStrategy;
+  /**
+   * Server-minted spawn correlation token. When provided, injected into
+   * the spawned process env as `PI_DASHBOARD_SPAWN_TOKEN`. The bridge
+   * echoes it back in the first `session_register` so the server can
+   * resolve identity precisely (linkByToken). When omitted, callers
+   * fall through to pid-link or cwd-FIFO matching.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
 }
 
 export interface SpawnResult {
@@ -72,6 +123,22 @@ export interface SpawnResult {
   stderr?: string;
   /** Path to the per-session stderr log (Windows headless). Forwarded to watchdog. See change: spawn-failure-diagnostics. */
   logPath?: string;
+  /**
+   * Token minted by `spawnPiSession` and injected into the spawned process's
+   * env as `PI_DASHBOARD_SPAWN_TOKEN`. Returned so callers can register it
+   * with the headless-pid registry, watchdog, and pending-* registries.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
+  /**
+   * RPC keeper UDS / named-pipe path. Set ONLY when the keeper-mediated
+   * spawn path was taken (`useRpcKeeper: true`). Callers pass this to
+   * `headlessPidRegistry.register(..., { keeperPid, keeperSockPath })` so
+   * later `writeRpc` / `killBySessionId` calls can locate the keeper.
+   * In keeper mode `pid` IS the keeper PID, so `keeperPid` is implicit.
+   * See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+   */
+  keeperSockPath?: string;
 }
 
 /**
@@ -87,8 +154,18 @@ export interface SpawnResult {
  * lands at the very head of `PATH` — spawned children invoking plain
  * `node` / `npm` resolve to the managed runtime first.
  */
-export function buildSpawnEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  return prependManagedNodeToPath(resolver.buildSpawnEnv(baseEnv));
+export function buildSpawnEnv(
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  opts?: { spawnToken?: string },
+): NodeJS.ProcessEnv {
+  const env = prependManagedNodeToPath(resolver.buildSpawnEnv(baseEnv));
+  if (opts?.spawnToken) {
+    // Inject the correlation token so the bridge inside the spawned pi
+    // process can read it and echo back in `session_register`.
+    // See change: spawn-correlation-token.
+    return { ...env, PI_DASHBOARD_SPAWN_TOKEN: opts.spawnToken };
+  }
+  return env;
 }
 
 /**
@@ -279,14 +356,25 @@ export async function spawnPiSession(
     return { success: false, code: "DIR_MISSING", message: `Directory does not exist: ${cwd}` };
   }
 
-  const mechanism = chooseMechanism(options, options?.electronMode ?? false);
+  // Mint a spawn token if the caller didn't provide one. Token is injected
+  // into the spawned process's env (via buildSpawnEnv) and surfaced on
+  // SpawnResult so callers can register it with the registries.
+  // See change: spawn-correlation-token.
+  const spawnToken = options?.spawnToken ?? mintSpawnToken();
+  const opts: SessionOptions & { electronMode?: boolean } = { ...(options ?? {}), spawnToken };
 
+  const mechanism = chooseMechanism(opts, opts?.electronMode ?? false);
+
+  let result: SpawnResult;
   switch (mechanism) {
-    case "tmux":     return spawnTmux(cwd, options);
-    case "wt":       return spawnWt(cwd, options);
-    case "wsl-tmux": return spawnWslTmux(cwd, options);
-    case "headless": return spawnHeadless(cwd, options);
+    case "tmux":     result = spawnTmux(cwd, opts); break;
+    case "wt":       result = await spawnWt(cwd, opts); break;
+    case "wsl-tmux": result = spawnWslTmux(cwd, opts); break;
+    case "headless": result = await spawnHeadless(cwd, opts); break;
   }
+  // Surface the token on every result (success or failure) so callers
+  // can clean up registries deterministically.
+  return { ...result, spawnToken };
 }
 
 // ── Per-mechanism spawn ────────────────────────────────────────────────────
@@ -294,8 +382,12 @@ export async function spawnPiSession(
 function spawnTmux(cwd: string, options?: SessionOptions): SpawnResult {
   const exists = dashboardSessionExists();
   const cmd = buildTmuxCommand(cwd, exists, options);
+  // Pass env explicitly so PI_DASHBOARD_SPAWN_TOKEN reaches the tmux pane's
+  // pi process (tmux inherits the caller's env into new windows/sessions).
+  // See change: spawn-correlation-token.
+  const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
   try {
-    execSync(cmd, { stdio: "ignore" });
+    execSync(cmd, { stdio: "ignore", env });
     return {
       success: true,
       dashboardSpawned: true,
@@ -309,7 +401,8 @@ function spawnTmux(cwd: string, options?: SessionOptions): SpawnResult {
 function spawnWslTmux(cwd: string, options?: SessionOptions): SpawnResult {
   try {
     const cmd = `wsl ${buildTmuxCommand(cwd, false, options)}`;
-    execSync(cmd, { stdio: "ignore" });
+    const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
+    execSync(cmd, { stdio: "ignore", env });
     return { success: true, dashboardSpawned: true, message: "Pi session spawned via WSL tmux" };
   } catch (err: any) {
     return { success: false, code: "TMUX_MISSING", message: `Failed to spawn via WSL tmux (wsl-tmux mechanism): ${err.message}` };
@@ -333,7 +426,7 @@ async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResu
     cmd: wt,
     args,
     cwd,
-    env: buildSpawnEnv(),
+    env: buildSpawnEnv(process.env, { spawnToken: options?.spawnToken }),
   });
 
   if (!r.ok) {
@@ -351,7 +444,16 @@ async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResu
 
 async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<SpawnResult> {
   const args = buildHeadlessArgs(options);
-  const env = buildSpawnEnv();
+  const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
+
+  // RPC keeper sidecar path (feature-flagged). When enabled, both Unix and
+  // Windows go through the keeper (uniform durability across OSes). The
+  // keeper spawns pi internally via its own PATH lookup, so we do NOT need
+  // to resolve pi here. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+  if (shouldUseRpcKeeper()) {
+    return spawnHeadlessViaKeeper(cwd, env, args);
+  }
+
   const piCmd = resolvePiCommand();
   if (!piCmd) {
     return { success: false, code: "PI_NOT_FOUND", message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
@@ -387,6 +489,75 @@ async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<Spa
   };
 }
 
+/**
+ * RPC keeper sidecar headless spawn. Uniform across Unix + Windows.
+ *
+ * The keeper itself is a CJS-pure Node script (`rpc-keeper/keeper.cjs`).
+ * It binds a per-session UDS / named pipe BEFORE spawning pi, then owns
+ * pi's stdin pipe so it survives dashboard server restarts.
+ *
+ * Returned `pid` is the KEEPER PID (not pi's). Pi's PID is linked later
+ * via the existing `session_register` token correlation path.
+ *
+ * Crash-detection window applies to KEEPER spawn only — the keeper itself
+ * runs a separate 300 ms window on its pi child internally (and surfaces
+ * the failure by exiting non-zero, which will be picked up by
+ * `headless-pid-registry`'s PID-death tracking).
+ *
+ * See change: add-rpc-stdin-dispatch-with-keeper-sidecar (Phase 5).
+ */
+async function spawnHeadlessViaKeeper(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  piArgs: string[],
+): Promise<SpawnResult> {
+  // sessionId is what the keeper uses to derive its UDS / named-pipe path.
+  // This is a TRANSPORT-side identifier, distinct from pi's session UUID
+  // (which only exists once pi's RPC mode boots). We mint a fresh one per
+  // spawn so the keeper's socket path is unique.
+  const transportId = randomUUID();
+
+  // piArgs already includes `--mode rpc` plus any per-spawn flags from
+  // `buildHeadlessArgs(options)` (e.g. `--session-file <path>` for resume,
+  // `--fork` for fork). Forwarding them through the keeper preserves the
+  // existing resume / fork contract. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+  const km = getKeeperManager();
+  const result = await km.spawnKeeperFor(transportId, cwd, env, piArgs);
+  if (!result.success || !result.pid || !result.process) {
+    return {
+      success: false,
+      code: "SPAWN_ERRNO",
+      message: `Failed to spawn RPC keeper: ${result.error ?? "unknown error"}`,
+    };
+  }
+
+  // Crash-detection window on the keeper process itself. Keeper applies
+  // its own 300 ms window to pi internally; this catches keeper-side
+  // failures (bind failure, pi-spawn-error, etc.) that exit the keeper
+  // within the window.
+  const gate = await waitForNoCrash({ child: result.process, windowMs: 300 });
+  if (!gate.ok) {
+    return {
+      success: false,
+      code: "PI_CRASHED",
+      message:
+        `RPC keeper exited within crash window (code ${gate.exitCode}). ` +
+        `Check ~/.pi/dashboard/sessions/keeper-${transportId}.log for details.`,
+    };
+  }
+
+  return {
+    success: true,
+    dashboardSpawned: true,
+    message: `Pi session spawned via RPC keeper (keeper pid ${result.pid}, transport ${transportId.slice(0, 8)})`,
+    pid: result.pid,
+    process: result.process,
+    keeperSockPath: result.sockPath,
+    // spawnToken propagated by the outer wrapper; keeper-spawn doesn't
+    // mint its own. The token already lives in `env.PI_DASHBOARD_SPAWN_TOKEN`.
+  };
+}
+
 /**
  * Windows headless spawn using the detached-spawn primitive.
  *