@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

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,16 +1,24 @@
 /**
  * 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";
 import os from "node:os";
 import { existsSync } from "node:fs";
 import type { PiCorePackage, PiCoreUpdateResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { prependManagedNodeToPath } from "@blackbelt-technology/pi-dashboard-shared/platform/managed-node-path.js";
 import type { PackageManagerWrapper } from "./package-manager-wrapper.js";
 
 const UPDATE_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per package
@@ -33,16 +41,54 @@ export interface PiCoreUpdaterOptions {
 	onAllComplete?: () => Promise<number>;
 }
 
-/** Default npm-update runner. */
-function defaultRunNpmUpdate(
+/**
+ * Test seams for `defaultRunNpmUpdate`. Production callers omit
+ * `_seams`; tests inject fakes to avoid real spawns.
+ *
+ * `_resolveNpm` defaults to `getDefaultRegistry().resolveExecutor("npm")`.
+ * `_spawn` defaults to `node:child_process` `spawn`.
+ * `_envBuilder` defaults to `prependManagedNodeToPath(process.env)`.
+ */
+export interface DefaultRunNpmUpdateSeams {
+	_resolveNpm?: () =>
+		| { ok: true; argv: string[] }
+		| { ok: false; reason: string };
+	_spawn?: typeof spawn;
+	_envBuilder?: () => NodeJS.ProcessEnv;
+}
+
+/**
+ * Default npm-update runner.
+ *
+ * After change `embed-managed-node-runtime`:
+ *   - Resolves the `npm` binary via `ToolRegistry.resolve("npm")` so
+ *     the managed-Node runtime (when installed) is preferred over the
+ *     system PATH — the user-visible regression class this change
+ *     exists to prevent (`npm update exited with code 1` on a fresh
+ *     Windows install with no system Node).
+ *   - Refuses to spawn a bare `"npm"` if the registry can't resolve
+ *     it. Surfaces a clear `npm` unresolved error per the spec
+ *     scenario "ToolRegistry resolution failure surfaces a clear
+ *     error".
+ *   - Prepends the managed Node directory to the spawned child's
+ *     `PATH` via `prependManagedNodeToPath`, so any nested `node` /
+ *     `npm` invocation inside the npm subprocess also resolves to the
+ *     managed runtime.
+ */
+export function defaultRunNpmUpdate(
 	pkg: PiCorePackage,
 	onOutput: (line: string) => void,
+	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)) {
@@ -50,15 +96,35 @@ function defaultRunNpmUpdate(
 			return;
 		}
 
-		// On Windows, system npm is npm.cmd (batch wrapper) — spawn("npm")
-		// without the .cmd extension fails with ENOENT. shell:true routes
-		// the invocation through cmd.exe which resolves via PATHEXT.
-		// See change: route-kill-paths-through-platform (same class of bug).
-		const child = spawn("npm", args, {
+		// Resolve npm via ToolRegistry: managed runtime > override > PATH.
+		// On unresolved, refuse — do not fall back to bare spawn("npm").
+		const resolveNpm =
+			seams._resolveNpm ??
+			(() => {
+				const r = getDefaultRegistry().resolveExecutor("npm");
+				return r.ok && r.path
+					? { ok: true as const, argv: r.argv }
+					: { ok: false as const, reason: "no override, no managed runtime, no npm on PATH" };
+			});
+		const npmRes = resolveNpm();
+		if (!npmRes.ok) {
+			reject(new Error(
+				`npm could not be resolved (${npmRes.reason}). ` +
+				"Install Node.js or run `pi-dashboard repair` to restore the managed Node runtime.",
+			));
+			return;
+		}
+
+		// `argv` is ready-to-spawn: on Windows + an npm-cli.js resolution
+		// it is `[node.exe, npm-cli.js]` (bypasses the .cmd shim and the
+		// cmd.exe console flash); elsewhere it is `[npm]`.
+		const [cmd, ...argvPrefix] = npmRes.argv;
+		const spawnFn = seams._spawn ?? spawn;
+		const envFn = seams._envBuilder ?? (() => prependManagedNodeToPath(process.env));
+		const child = spawnFn(cmd, [...argvPrefix, ...args], {
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
-			env: process.env,
-			shell: process.platform === "win32", // platform-branch-ok: shell:true required on Windows so PATHEXT resolves npm.cmd (spawn('npm') without .cmd ENOENTs)
+			env: envFn(),
 			windowsHide: true,
 		});
 
@@ -93,9 +159,9 @@ 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

@@ -5,6 +5,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import type { ExtensionToServerMessage, ServerToExtensionMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
 import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { SessionManager } from "./memory-session-manager.js";
+import { getSpawnRegisterWatchdog } from "./spawn-register-watchdog.js";
 
 export const HEARTBEAT_TIMEOUT = 180_000;
 export const WS_PING_INTERVAL = 60_000;
@@ -273,6 +274,15 @@ 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);
+
               // If session ID changed (e.g., after /reload), clean up the old placeholder
               if (currentSessionId && currentSessionId !== msg.sessionId) {
                 const oldSession = sessionManager.get(currentSessionId);

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 */
   }