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

package/packages/server/src/editor-pid-registry.ts

@@ -0,0 +1,199 @@
+/**
+ * Persistent registry of spawned `code-server` editor instances.
+ *
+ * Persists PIDs to ~/.pi/dashboard/editor-pids.json so that, after a non-graceful
+ * dashboard shutdown (SIGKILL, crash, OOM, force-quit), the next server boot can
+ * sweep and SIGTERM/SIGKILL orphan code-server processes that were reparented to
+ * init/launchd.
+ *
+ * Mirrors the persistence + boot-sweep pattern of `headless-pid-registry.ts` but
+ * KILLS live orphans (not reclaim) — editor instances are dashboard-internal,
+ * unreachable after restart, and the user expects a clean state.
+ */
+import os from "node:os";
+import path from "node:path";
+import { execSync } from "node:child_process"; // ban:child_process-ok editor orphan sweep uses `ps`/`taskkill` probe for bounded wait; tracked tech debt for migration to platform/process Recipe
+import { readFileSync, existsSync } from "node:fs";
+import { readJsonFile, writeJsonFile } from "./json-store.js";
+import { isUnsafeTestHomeScan } from "./test-env-guard.js";
+import {
+	isProcessAlive as platformIsProcessAlive,
+	killPidWithGroup,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+
+const DEFAULT_PID_FILE = path.join(os.homedir(), ".pi", "dashboard", "editor-pids.json");
+
+/** Grace period between SIGTERM and SIGKILL escalation. */
+const SIGKILL_GRACE_MS = 1000;
+
+/** Marker that uniquely identifies a dashboard-spawned code-server cmdline. */
+const DASHBOARD_DATA_DIR_MARKER = path.join(os.homedir(), ".pi", "dashboard", "editors") + path.sep;
+
+export interface PersistedEditorEntry {
+  id: string;
+  pid: number;
+  port: number;
+  cwd: string;
+  dataDir: string;
+  /** ISO 8601 timestamp */
+  spawnedAt: string;
+}
+
+interface EditorPidFileData {
+  entries: PersistedEditorEntry[];
+}
+
+export interface EditorPidRegistry {
+  /** Record a newly-ready editor instance. */
+  register(entry: Omit<PersistedEditorEntry, "spawnedAt"> & { spawnedAt?: number | string }): void;
+  /** Remove an entry by editor id. */
+  remove(id: string): void;
+  /** Number of in-memory tracked entries (testing aid). */
+  size(): number;
+  /** Sweep persisted entries on server boot, killing verified orphans. */
+  cleanupOrphans(): Promise<void>;
+}
+
+export interface EditorPidRegistryOptions {
+  pidFilePath?: string;
+  /** Override cmdline lookup (testing). */
+  getCmdline?: (pid: number) => string | null;
+  /** Override process-alive check (testing). */
+  isProcessAlive?: (pid: number) => boolean;
+  /** Override kill (testing). Returns true if signal was delivered. */
+  kill?: (pid: number, signal: NodeJS.Signals) => boolean;
+  /** Override grace ms between SIGTERM and SIGKILL (testing). */
+  graceMs?: number;
+}
+
+/** Default cross-platform process command-line lookup. */
+function defaultGetCmdline(pid: number): string | null {
+  try {
+    if (process.platform === "linux") {
+      const file = `/proc/${pid}/cmdline`;
+      if (!existsSync(file)) return null;
+      // /proc cmdline is NUL-separated
+      return readFileSync(file, "utf-8").replace(/\0/g, " ").trim();
+    }
+    if (process.platform === "darwin") {
+      const out = execSync(`ps -p ${pid} -o command=`, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+      return out.trim() || null;
+    }
+    if (process.platform === "win32") {
+      const out = execSync(`wmic process where ProcessId=${pid} get CommandLine /value`, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+      const m = out.match(/CommandLine=(.*)/);
+      return m ? m[1].trim() : null;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/** Route through platform/process.ts so lint enforcement and cross-platform
+ * semantics (libuv signal 0 check, POSIX group kill) stay in one place. */
+function defaultIsProcessAlive(pid: number): boolean {
+  return platformIsProcessAlive(pid);
+}
+
+function defaultKill(pid: number, signal: NodeJS.Signals): boolean {
+  try {
+    killPidWithGroup(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Verify that `cmdline` looks like a dashboard-spawned code-server. */
+export function isDashboardOwnedCodeServer(cmdline: string | null): boolean {
+  if (!cmdline) return false;
+  // Must reference --user-data-dir under ~/.pi/dashboard/editors/
+  return cmdline.includes("--user-data-dir") && cmdline.includes(DASHBOARD_DATA_DIR_MARKER);
+}
+
+export function createEditorPidRegistry(options: EditorPidRegistryOptions = {}): EditorPidRegistry {
+  const pidFilePath = options.pidFilePath ?? DEFAULT_PID_FILE;
+  const getCmdline = options.getCmdline ?? defaultGetCmdline;
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  const kill = options.kill ?? defaultKill;
+  const graceMs = options.graceMs ?? SIGKILL_GRACE_MS;
+
+  // In-memory mirror of the file (id → entry).
+  const entries = new Map<string, PersistedEditorEntry>();
+
+  function persist(): void {
+    try {
+      const data: EditorPidFileData = { entries: [...entries.values()] };
+      writeJsonFile(pidFilePath, data);
+    } catch {
+      // Best-effort: persistence failures must not break editor lifecycle.
+    }
+  }
+
+  return {
+    register(entry) {
+      const spawnedAt =
+        typeof entry.spawnedAt === "string"
+          ? entry.spawnedAt
+          : new Date(entry.spawnedAt ?? Date.now()).toISOString();
+      entries.set(entry.id, {
+        id: entry.id,
+        pid: entry.pid,
+        port: entry.port,
+        cwd: entry.cwd,
+        dataDir: entry.dataDir,
+        spawnedAt,
+      });
+      persist();
+    },
+
+    remove(id) {
+      if (entries.delete(id)) persist();
+    },
+
+    size() {
+      return entries.size;
+    },
+
+    async cleanupOrphans() {
+      if (isUnsafeTestHomeScan()) {
+        console.warn("[editor-pid-registry] cleanupOrphans() blocked: running under vitest with real HOME");
+        return;
+      }
+      const data = readJsonFile<EditorPidFileData>(pidFilePath, { entries: [] });
+      const persisted = Array.isArray(data?.entries) ? data.entries : [];
+
+      let killed = 0;
+      const toKill: PersistedEditorEntry[] = [];
+
+      for (const entry of persisted) {
+        if (!isAlive(entry.pid)) continue;
+        const cmdline = getCmdline(entry.pid);
+        if (!isDashboardOwnedCodeServer(cmdline)) continue;
+        toKill.push(entry);
+      }
+
+      for (const entry of toKill) {
+        kill(entry.pid, "SIGTERM");
+      }
+
+      if (toKill.length > 0) {
+        await new Promise((r) => setTimeout(r, graceMs));
+        for (const entry of toKill) {
+          if (isAlive(entry.pid)) {
+            kill(entry.pid, "SIGKILL");
+          }
+          killed++;
+        }
+      }
+
+      // Reset to whatever the new server has registered so far (initially nothing).
+      persist();
+
+      if (killed > 0) {
+        console.log(`[editor-pid-registry] cleaned ${killed} orphan${killed === 1 ? "" : "s"}`);
+      }
+    },
+  };
+}

package/packages/server/src/editor-registry.ts

@@ -1,8 +1,11 @@
 /**
  * Static editor registry and detection logic.
  * Detects available editors by checking for running processes + CLI on PATH.
+ * Uses shared platform primitives so the win32 / unix split is owned in one
+ * place. See change: consolidate-platform-handlers.
  */
-import { execSync } from "node:child_process";
+import { isProcessRunning as platformIsProcessRunning } from "@blackbelt-technology/pi-dashboard-shared/platform/process-scan.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
 
 export interface EditorEntry {
   id: string;
@@ -50,32 +53,28 @@ export const EDITORS: EditorEntry[] = [
   },
 ];
 
+// Cached resolver for binary-availability checks (reads PATH via `where`/`which`).
+const resolver = new ToolResolver({ processExecPath: process.execPath });
+
+/**
+ * Platform-unified process-running check. Re-exported for callers (and tests)
+ * that previously imported it from this module.
+ */
 export function isProcessRunning(pattern: string): boolean {
-  try {
-    execSync(`pgrep -f "${pattern}"`, { stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
-  }
+  return platformIsProcessRunning(pattern);
 }
 
-function isCliAvailable(cli: string): boolean {
-  const cmd = process.platform === "win32" ? `where ${cli}` : `which ${cli}`;
-  try {
-    execSync(cmd, { stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
-  }
+/**
+ * @deprecated Use `isProcessRunning(pattern)` — the shared primitive now
+ * handles the Windows (tasklist) vs Unix (pgrep) split internally. Kept as
+ * a thin alias for tests that still call it directly.
+ */
+export function isProcessRunningWin32(pattern: string): boolean {
+  return platformIsProcessRunning(pattern, { platform: "win32" });
 }
 
-export function isProcessRunningWin32(pattern: string): boolean {
-  try {
-    const result = execSync(`tasklist /FI "IMAGENAME eq ${pattern}" /NH`, { encoding: "utf-8", stdio: "pipe" });
-    return result.includes(pattern);
-  } catch {
-    return false;
-  }
+function isCliAvailable(cli: string): boolean {
+  return resolver.which(cli) !== null;
 }
 
 export function detectEditors(_cwd: string): DetectedEditor[] {
@@ -96,9 +95,7 @@ export function detectEditors(_cwd: string): DetectedEditor[] {
       cli = editor.cli;
     }
 
-    const running = platform === "win32"
-      ? isProcessRunningWin32(pattern)
-      : isProcessRunning(pattern);
+    const running = isProcessRunning(pattern);
 
     if (running && isCliAvailable(cli)) {
       results.push({ id: editor.id, name: editor.name });

package/packages/server/src/fix-pty-permissions.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime fix for node-pty spawn-helper permissions.
+ *
+ * On macOS/Linux, the prebuilt spawn-helper binary may lack the execute bit
+ * (especially in Electron bundles where npm hoisting skips the postinstall fix).
+ * This module finds and fixes all spawn-helper binaries at runtime.
+ *
+ * Called once when the terminal manager is created.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+let fixed = false;
+
+export function fixPtyPermissions(): void {
+  if (fixed || process.platform === "win32") return;
+  fixed = true;
+
+  try {
+    // Resolve node-pty's actual location (works with hoisting)
+    const require_ = createRequire(import.meta.url);
+    const ptyMain = require_.resolve("node-pty");
+    const ptyDir = path.dirname(ptyMain);
+    const prebuildsDir = path.join(ptyDir, "..", "prebuilds");
+
+    if (!fs.existsSync(prebuildsDir)) return;
+
+    for (const dir of fs.readdirSync(prebuildsDir)) {
+      const helper = path.join(prebuildsDir, dir, "spawn-helper");
+      try {
+        const stat = fs.statSync(helper);
+        if (!(stat.mode & 0o111)) {
+          fs.chmodSync(helper, 0o755);
+          console.log(`[pty] Fixed spawn-helper permissions: ${helper}`);
+        }
+      } catch {
+        // spawn-helper doesn't exist for this platform, skip
+      }
+    }
+  } catch {
+    // node-pty not installed or not resolvable, skip silently
+  }
+}

package/packages/server/src/git-operations.ts

@@ -1,7 +1,7 @@
 /**
  * Server-side git operations — branch listing, checkout, init, stash.
  */
-import { execSync } from "node:child_process";
+import { execSync } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 
 const GIT_TIMEOUT = 15_000;
 

package/packages/server/src/headless-pid-registry.ts

@@ -3,11 +3,13 @@
  * Tracks PID + cwd at spawn time, links to sessionId when the bridge connects.
  * Persists entries to disk so a restarted server can clean up orphans.
  */
-import type { ChildProcess } from "node:child_process";
+import type { ChildProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import { EventEmitter } from "node:events";
 import { readJsonFile, writeJsonFile } from "./json-store.js";
+import { killPidWithGroup, isProcessAlive } from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
 import path from "node:path";
 import os from "node:os";
+import { isUnsafeTestHomeScan } from "./test-env-guard.js";
 
 /** Default PID file path */
 const DEFAULT_PID_FILE = path.join(os.homedir(), ".pi", "dashboard", "headless-pids.json");
@@ -81,15 +83,6 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
     return data.entries ?? [];
   }
 
-  function isProcessAlive(pid: number): boolean {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
   return {
     register(pid: number, cwd: string, proc: ChildProcess) {
       entries.set(pid, { pid, cwd, process: proc, spawnedAt: Date.now() });
@@ -123,12 +116,9 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
       for (const entry of entries.values()) {
         if (entry.sessionId === sessionId) {
           try {
-            // On Unix, kill the entire process group (negative PID) so the
-            // wrapper shell, sleep, and pi processes are all terminated.
-            // On Windows, process groups aren't supported — kill directly.
-            const signal = "SIGTERM";
-            const pid = process.platform === "win32" ? entry.pid : -entry.pid;
-            process.kill(pid, signal);
+            // Delegate platform-specific pid-vs-group-pid handling to the
+            // shared primitive. See change: consolidate-platform-handlers.
+            killPidWithGroup(entry.pid, "SIGTERM");
             entries.delete(entry.pid);
             persist();
             return true;
@@ -148,10 +138,13 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
     },
 
     killAll() {
-      const useGroup = process.platform !== "win32";
+      if (isUnsafeTestHomeScan()) {
+        console.warn("[headless-pid-registry] killAll() blocked: running under vitest with real HOME");
+        return;
+      }
       for (const [pid] of entries) {
         try {
-          process.kill(useGroup ? -pid : pid, "SIGTERM");
+          killPidWithGroup(pid, "SIGTERM");
         } catch {
           // Process may have already exited
         }
@@ -166,6 +159,10 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
     },
 
     cleanupOrphans() {
+      if (isUnsafeTestHomeScan()) {
+        console.warn("[headless-pid-registry] cleanupOrphans() blocked: running under vitest with real HOME");
+        return;
+      }
       const persisted = loadFromDisk();
       const now = Date.now();
 
@@ -181,8 +178,7 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
         if (age > MAX_ORPHAN_AGE_MS) {
           // Very old orphan — kill (process group on Unix, direct on Windows)
           try {
-            const pid = process.platform === "win32" ? entry.pid : -entry.pid;
-            process.kill(pid, "SIGTERM");
+            killPidWithGroup(entry.pid, "SIGTERM");
           } catch {
             // Already dead
           }

package/packages/server/src/home-lock-release.ts

@@ -0,0 +1,72 @@
+/**
+ * Install signal + exit handlers that release the per-HOME dashboard lock.
+ *
+ * Separate from `home-lock.ts` so the pure lock-acquisition logic stays
+ * trivially testable. See change: single-dashboard-per-home.
+ */
+
+export type ReleaseFn = () => Promise<void>;
+
+export interface InstallReleaseHandlersOptions {
+  /** Inject a fake `process`-like object for tests. */
+  proc?: NodeJS.Process;
+  /** Inject a logger (defaults to `console`). */
+  log?: (msg: string) => void;
+}
+
+/**
+ * Register SIGINT / SIGTERM / SIGHUP / SIGBREAK handlers and an `exit`
+ * fallback that call `release()` exactly once. The handler is idempotent;
+ * multiple signals will not double-release.
+ *
+ * Windows:
+ *   - SIGINT + SIGBREAK are emitted by Node. SIGBREAK fires on Ctrl+Break.
+ *   - SIGHUP does not exist on Windows; the registration is a no-op there.
+ *   - `taskkill /F` bypasses all signals — the stale-detection path in
+ *     `proper-lockfile` (staleDuration 10s) handles this case on next boot.
+ *
+ * Returns a function that removes the handlers (useful for tests).
+ */
+export function installReleaseHandlers(
+  release: ReleaseFn,
+  options: InstallReleaseHandlersOptions = {},
+): () => void {
+  const proc = options.proc ?? process;
+  const log = options.log ?? ((m: string) => console.log(m));
+
+  let releasing = false;
+  const doRelease = async (signal: string) => {
+    if (releasing) return;
+    releasing = true;
+    try {
+      await release();
+    } catch (err) {
+      log(`[home-lock] release on ${signal} failed: ${(err as Error).message ?? err}`);
+    }
+  };
+
+  const sigintHandler = () => { void doRelease("SIGINT").then(() => proc.exit(0)); };
+  const sigtermHandler = () => { void doRelease("SIGTERM").then(() => proc.exit(0)); };
+  const sighupHandler = () => { void doRelease("SIGHUP").then(() => proc.exit(0)); };
+  const sigbreakHandler = () => { void doRelease("SIGBREAK").then(() => proc.exit(0)); };
+  // `exit` is synchronous — we can't await. Best effort: fire and move on;
+  // the async release will race the exit. `proper-lockfile` also removes its
+  // own lockfile on exit via its own exit hook as a safety net.
+  const exitHandler = () => { void release().catch(() => { /* ignore */ }); };
+
+  proc.on("SIGINT", sigintHandler);
+  proc.on("SIGTERM", sigtermHandler);
+  // SIGHUP + SIGBREAK may be undefined on Windows / some environments —
+  // registering still works (Node just never fires them there).
+  proc.on("SIGHUP", sighupHandler);
+  proc.on("SIGBREAK" as NodeJS.Signals, sigbreakHandler);
+  proc.on("exit", exitHandler);
+
+  return () => {
+    proc.off("SIGINT", sigintHandler);
+    proc.off("SIGTERM", sigtermHandler);
+    proc.off("SIGHUP", sighupHandler);
+    proc.off("SIGBREAK" as NodeJS.Signals, sigbreakHandler);
+    proc.off("exit", exitHandler);
+  };
+}