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

package/packages/shared/src/platform/npm.ts

@@ -0,0 +1,162 @@
+/**
+ * npm tool module — Recipe-based API for the npm CLI.
+ *
+ * Covers the subset of npm operations the dashboard actually invokes:
+ *   - `npm root -g`          (resolve the global node_modules path)
+ *   - `npm outdated`         (check for updates, local or global)
+ *   - `npm install`          (install a package, local or global)
+ *   - `npm view <pkg> version` (read upstream version)
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const NPM_TIMEOUT_FAST = 10_000;
+const NPM_TIMEOUT_INSTALL = 120_000;
+
+interface WithCwd {
+  cwd?: string;
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g` — returns the absolute path to the global node_modules.
+ * Cached by callers (it's stable per Node install).
+ */
+export const NPM_ROOT_GLOBAL: Recipe<Record<string, never>, string> = {
+  argv: () => ["npm", "root", "-g"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+/**
+ * `npm outdated <pkg> --json` (or without `<pkg>` for project-wide).
+ * npm exits 1 when updates are available and 0 when up-to-date — we tolerate
+ * exit 1 so callers see the JSON body either way.
+ */
+export const NPM_OUTDATED: Recipe<WithCwd & { pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "--json"]
+    : ["npm", "outdated", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm outdated -g <pkg> --json`. Same exit-1 tolerance.
+ */
+export const NPM_OUTDATED_GLOBAL: Recipe<{ pkg?: string }, unknown | null> = {
+  argv: ({ pkg }) => pkg === undefined
+    ? ["npm", "outdated", "-g", "--json"]
+    : ["npm", "outdated", "-g", pkg, "--json"],
+  parse: (out) => {
+    const trimmed = out.trim();
+    if (!trimmed) return null;
+    try { return JSON.parse(trimmed); } catch { return null; }
+  },
+  timeout: NPM_TIMEOUT_FAST,
+  tolerate: [1],
+};
+
+/**
+ * `npm install <pkg>@<version>` — local install. Long timeout.
+ */
+export const NPM_INSTALL: Recipe<WithCwd & { pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm install -g <pkg>@<version>` — global install.
+ */
+export const NPM_INSTALL_GLOBAL: Recipe<{ pkg: string; version?: string }, string> = {
+  argv: ({ pkg, version }) => ["npm", "install", "-g", version ? `${pkg}@${version}` : pkg],
+  parse: (out) => out,
+  timeout: NPM_TIMEOUT_INSTALL,
+};
+
+/**
+ * `npm view <pkg> version` — the single-value shorthand for "latest version".
+ */
+export const NPM_VIEW_VERSION: Recipe<{ pkg: string }, string> = {
+  argv: ({ pkg }) => ["npm", "view", pkg, "version"],
+  parse: (out) => out.trim(),
+  timeout: NPM_TIMEOUT_FAST,
+};
+
+export const NPM_RECIPES = {
+  NPM_ROOT_GLOBAL,
+  NPM_OUTDATED,
+  NPM_OUTDATED_GLOBAL,
+  NPM_INSTALL,
+  NPM_INSTALL_GLOBAL,
+  NPM_VIEW_VERSION,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * `npm root -g`. Returns a `Result` for explicit error handling; use
+ * `rootGlobalOr` for best-effort semantics.
+ *
+ * Previous versions cached the result in a module-level variable. That
+ * cache is now owned by `ToolRegistry` (the runner consults the
+ * registry for every resolved binary including `npm` itself). Cache
+ * invalidation flows through `registry.rescan()`.
+ *
+ * See change: consolidate-tool-resolution.
+ */
+export function rootGlobal(): Result<string> {
+  return run(NPM_ROOT_GLOBAL, {}, {});
+}
+
+/**
+ * Test-only no-op kept for backward compatibility with existing test
+ * suites. The `cachedGlobalRoot` variable no longer exists.
+ */
+export function _resetNpmRootCache(): void { /* no-op */ }
+
+export function outdated(input: WithCwd & { pkg?: string }): Result<unknown | null> {
+  return run(NPM_OUTDATED, input, { cwd: input.cwd });
+}
+
+export function outdatedGlobal(input: { pkg?: string } = {}): Result<unknown | null> {
+  return run(NPM_OUTDATED_GLOBAL, input, {});
+}
+
+export function install(input: WithCwd & { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL, input, { cwd: input.cwd });
+}
+
+export function installGlobal(input: { pkg: string; version?: string }): Result<string> {
+  return run(NPM_INSTALL_GLOBAL, input, {});
+}
+
+export function viewVersion(input: { pkg: string }): Result<string> {
+  return run(NPM_VIEW_VERSION, input, {});
+}
+
+// ── Best-effort variants ────────────────────────────────────────────────────
+
+export function rootGlobalOr(fallback = ""): string {
+  return unwrap(rootGlobal(), fallback);
+}
+
+export function outdatedOr(input: WithCwd & { pkg?: string }, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdated(input), fallback);
+}
+
+export function outdatedGlobalOr(input: { pkg?: string } = {}, fallback: unknown | null = null): unknown | null {
+  return unwrap(outdatedGlobal(input), fallback);
+}
+
+export function viewVersionOr(input: { pkg: string }, fallback = ""): string {
+  return unwrap(viewVersion(input), fallback);
+}

package/packages/shared/src/platform/openspec.ts

@@ -0,0 +1,91 @@
+/**
+ * OpenSpec tool module — Recipe-based API for the openspec CLI.
+ *
+ * Replaces the ad-hoc spawnSync/execFile calls in `openspec-poller.ts`
+ * with typed Recipes executed through the runner. The higher-level
+ * `pollOpenSpec` / `pollOpenSpecAsync` functions remain in
+ * `openspec-poller.ts` (they aggregate list + per-change status into
+ * the dashboard's OpenSpecData shape) and now use these primitives.
+ *
+ * See change: platform-command-executor.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+const OPENSPEC_TIMEOUT = 10_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+/** Parse JSON from stdout; returns null on parse failure. */
+function parseJsonOrNull(out: string): unknown | null {
+  const trimmed = out.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// ── Recipes ─────────────────────────────────────────────────────────────────
+
+export const OPENSPEC_LIST: Recipe<WithCwd, unknown | null> = {
+  argv: () => ["openspec", "list", "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+export const OPENSPEC_STATUS: Recipe<WithCwd & { change: string }, unknown | null> = {
+  argv: ({ change }) => ["openspec", "status", "--change", change, "--json"],
+  parse: parseJsonOrNull,
+  timeout: OPENSPEC_TIMEOUT,
+};
+
+/**
+ * `openspec archive --completed` — bulk-archives all completed changes.
+ * Stdout is human-readable (not JSON); callers typically don't parse it,
+ * they just await success/failure.
+ */
+export const OPENSPEC_ARCHIVE_COMPLETED: Recipe<WithCwd, string> = {
+  argv: () => ["openspec", "archive", "--completed"],
+  parse: (out) => out,
+  // Archive operations can be slow when many changes are processed.
+  timeout: 30_000,
+};
+
+export const OPENSPEC_RECIPES = {
+  OPENSPEC_LIST,
+  OPENSPEC_STATUS,
+  OPENSPEC_ARCHIVE_COMPLETED,
+} as const;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/** Run `openspec list --json` and return the parsed JSON, or null on failure. */
+export function list(input: WithCwd): Result<unknown | null> {
+  return run(OPENSPEC_LIST, input, { cwd: input.cwd });
+}
+
+/** Run `openspec status --change <name> --json` and return parsed JSON or null. */
+export function status(input: WithCwd & { change: string }): Result<unknown | null> {
+  return run(OPENSPEC_STATUS, input, { cwd: input.cwd });
+}
+
+/** Run `openspec archive --completed`. Returns raw stdout on success. */
+export function archiveCompleted(input: WithCwd): Result<string> {
+  return run(OPENSPEC_ARCHIVE_COMPLETED, input, { cwd: input.cwd });
+}
+
+// ── Best-effort variants (mirror the pattern established in git.ts) ─────────
+
+export function listOr(input: WithCwd, fallback: unknown | null = null): unknown | null {
+  return unwrap(list(input), fallback);
+}
+
+export function statusOr(
+  input: WithCwd & { change: string },
+  fallback: unknown | null = null,
+): unknown | null {
+  return unwrap(status(input), fallback);
+}

package/packages/shared/src/platform/paths.ts

@@ -0,0 +1,276 @@
+/**
+ * OS-aware filesystem path primitives.
+ *
+ * The dashboard uses paths in three places that need OS-correct behaviour:
+ *   1. Pin/unpin directory storage (server-side).
+ *   2. Session grouping — matching a session's `cwd` against pinned entries.
+ *   3. Path picker UI — parsing user-typed input.
+ *
+ * This module is the single source of truth. All exported helpers that
+ * depend on OS conventions take a trailing `platform: NodeJS.Platform`
+ * parameter defaulting to `process.platform` — tests pass it explicitly
+ * to exercise both Windows and Unix branches without mutating
+ * `process.platform`.
+ *
+ * ISOMORPHIC: implemented with string operations only (no `node:path`)
+ * so the module loads in the browser. The client imports `normalizePath`
+ * and `parsePathInput` directly; using `node:path` would have forced
+ * Vite to externalize the import and crash the SPA at load time.
+ *
+ * Windows specifics:
+ *   - Each drive letter (A:, B:, …, Z:) is a distinct filesystem root.
+ *     `samePath` NEVER merges different drives.
+ *   - Drive letters are case-insensitive (`B:\` == `b:\`).
+ *   - Path components are case-insensitive on NTFS (default) and HFS+.
+ *   - UNC paths (`\\server\share`) are distinct from drive-letter paths.
+ *   - Bare drive-relative input (`B:`, `B:Dev`) is defensively treated
+ *     as drive-root-plus-partial, NOT as the B-drive's current directory
+ *     (which is cwd-dependent and useless in a pin dialog).
+ *
+ * See change: platform-path-normalization.
+ */
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** True if input is a Windows drive-letter form (`B:`, `B:Dev`) without separator. */
+function isDriveLetterForm(value: string): boolean {
+  return /^[A-Za-z]:(?![\\/])/.test(value);
+}
+
+/** Extract the `B:` prefix from `B:Dev`, else null. */
+function driveLetterPrefix(value: string): string | null {
+  const m = value.match(/^([A-Za-z]:)(?![\\/])/);
+  return m ? m[1] : null;
+}
+
+/** Detect the root portion of a path. Returns "" when no root. */
+function getRoot(p: string, platform: NodeJS.Platform): string {
+  if (platform === "win32") {
+    // UNC: \\server\share  (captures up to the share name, no trailing sep)
+    const unc = p.match(/^(?:\\\\|\/\/)([^\\/]+)[\\/]([^\\/]+)(?:[\\/]|$)/);
+    if (unc) return `\\\\${unc[1]}\\${unc[2]}\\`;
+    // Drive root: "C:\" or "C:/"
+    const drive = p.match(/^([A-Za-z]:)[\\/]/);
+    if (drive) return `${drive[1]}\\`;
+    return "";
+  }
+  // POSIX
+  return p.startsWith("/") ? "/" : "";
+}
+
+/**
+ * Split a path into segments, collapsing `.` and `..`. Operates on a
+ * rootless remainder; caller is responsible for re-prepending the root.
+ */
+function normalizeSegments(rest: string, sep: string): string[] {
+  const split = rest.split(/[\\/]+/).filter((s) => s.length > 0);
+  const out: string[] = [];
+  for (const seg of split) {
+    if (seg === ".") continue;
+    if (seg === "..") {
+      if (out.length > 0 && out[out.length - 1] !== "..") out.pop();
+      // Rootless `..` that can't be resolved stays (we only call this with
+      // rootful paths via getRoot, so this arm is mostly defensive).
+      continue;
+    }
+    out.push(seg);
+  }
+  return out;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Canonicalize a path to the OS-native form:
+ *   - Separators match the OS (`\\` on win32, `/` elsewhere).
+ *   - Redundant separators collapsed.
+ *   - `.` and `..` segments resolved.
+ *   - Trailing separator removed EXCEPT for roots.
+ *   - Original case preserved (NO lowercasing).
+ *
+ * Windows subtleties:
+ *   - Bare drive-letter input (`B:`, `B:Dev`) is treated defensively as
+ *     drive-rooted (`B:\` / `B:\Dev`), NOT as cwd-relative on that drive
+ *     (which would be useless for a pin dialog — the dashboard's
+ *     `process.cwd()` has no relationship to what the user typed).
+ *   - UNC paths are preserved as-is (with the `\\server\share\` root).
+ */
+export function normalizePath(
+  p: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (!p) return p;
+
+  if (platform === "win32") {
+    // Handle drive-relative forms defensively.
+    if (isDriveLetterForm(p)) {
+      const prefix = driveLetterPrefix(p)!; // "B:"
+      const rest = p.slice(prefix.length);
+      if (!rest) return prefix + "\\"; // bare "B:" → "B:\\"
+      // "B:Dev" → normalize as if it were "B:\\Dev"
+      return normalizePath(prefix + "\\" + rest, "win32");
+    }
+
+    const root = getRoot(p, "win32");
+    if (root) {
+      const rest = p.slice(root.length);
+      const segments = normalizeSegments(rest, "\\");
+      if (segments.length === 0) return root;
+      // Drive root: "C:\" → segments joined with \ after root (no extra sep).
+      // UNC root: "\\server\share\" → same pattern.
+      return root + segments.join("\\");
+    }
+    // No root detected — relative path. Normalize separators + segments,
+    // leave without a leading root.
+    const segments = normalizeSegments(p, "\\");
+    return segments.join("\\");
+  }
+
+  // POSIX
+  const root = getRoot(p, platform);
+  if (root) {
+    const segments = normalizeSegments(p.slice(root.length), "/");
+    if (segments.length === 0) return root;
+    return root + segments.join("/");
+  }
+  const segments = normalizeSegments(p, "/");
+  return segments.join("/");
+}
+
+/**
+ * Filesystem-level equality.
+ *   - win32/darwin: case-insensitive (Windows NTFS + macOS HFS+ defaults).
+ *   - linux: case-sensitive.
+ *
+ * Runs both inputs through `normalizePath` first so separator and
+ * trailing-separator drift is tolerated uniformly. Cross-drive safety
+ * on Windows is automatic — the drive letter is preserved and compared.
+ */
+export function samePath(
+  a: string,
+  b: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (!a || !b) return a === b;
+  const na = normalizePath(a, platform);
+  const nb = normalizePath(b, platform);
+  if (platform === "linux") return na === nb;
+  return na.toLowerCase() === nb.toLowerCase();
+}
+
+/**
+ * Parse user-typed path input into `{ parent, partial }`:
+ *   - `parent` is the directory to browse.
+ *   - `partial` is the in-progress filter / typed segment after `parent`.
+ *
+ * Handles Windows drive-letter roots, UNC roots, Unix roots, mixed
+ * separators, and trailing separators.
+ */
+export function parsePathInput(
+  value: string,
+  platform: NodeJS.Platform = process.platform,
+): { parent: string; partial: string } {
+  if (!value) return { parent: platform === "win32" ? "" : "/", partial: "" };
+
+  if (platform === "win32") {
+    // Bare drive letter "B:" → drive root.
+    if (/^[A-Za-z]:$/.test(value)) {
+      return { parent: value[0] + ":\\", partial: "" };
+    }
+    // Drive-relative "B:Dev" → drive root + partial.
+    if (isDriveLetterForm(value)) {
+      const prefix = driveLetterPrefix(value)!;
+      return { parent: prefix + "\\", partial: value.slice(prefix.length) };
+    }
+
+    const lastBackslash = value.lastIndexOf("\\");
+    const lastForward = value.lastIndexOf("/");
+    const lastSep = Math.max(lastBackslash, lastForward);
+
+    if (lastSep < 0) {
+      // No separator — treat whole input as partial.
+      return { parent: "", partial: value };
+    }
+
+    if (lastSep === value.length - 1) {
+      // Ends with separator.
+      const parent = value.slice(0, lastSep);
+      if (/^[A-Za-z]:$/.test(parent)) return { parent: parent + "\\", partial: "" };
+      return { parent: normalizePath(parent, "win32"), partial: "" };
+    }
+
+    const parent = value.slice(0, lastSep);
+    const partial = value.slice(lastSep + 1);
+    const normalizedParent = /^[A-Za-z]:$/.test(parent)
+      ? parent + "\\"
+      : normalizePath(parent, "win32");
+    return { parent: normalizedParent, partial };
+  }
+
+  // POSIX
+  if (value === "/") return { parent: "/", partial: "" };
+  if (value.endsWith("/")) {
+    const parent = value.slice(0, -1) || "/";
+    return { parent, partial: "" };
+  }
+  const lastSep = value.lastIndexOf("/");
+  if (lastSep < 0) return { parent: "/", partial: value };
+  const parent = value.slice(0, lastSep) || "/";
+  const partial = value.slice(lastSep + 1);
+  return { parent, partial };
+}
+
+/** Append the OS-native separator to a path if not already terminated. */
+export function withTrailingSep(
+  p: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (!p) return p;
+  const sep = platform === "win32" ? "\\" : "/";
+  if (p.endsWith("\\") || p.endsWith("/")) return p;
+  return p + sep;
+}
+
+/** Join two path segments with the OS-native separator. */
+export function joinForDisplay(
+  parent: string,
+  child: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (!parent) return child;
+  if (!child) return parent;
+  const sep = platform === "win32" ? "\\" : "/";
+  const parentTrimmed = parent.replace(/[\\/]+$/, "");
+  const childTrimmed = child.replace(/^[\\/]+/, "");
+  // Preserve root's trailing sep — `C:\` + `Users` → `C:\Users`, not `C:Users`.
+  if (platform === "win32" && /^[A-Za-z]:$/.test(parentTrimmed)) {
+    return parentTrimmed + "\\" + childTrimmed;
+  }
+  if (parentTrimmed === "") return sep + childTrimmed; // POSIX root case
+  return parentTrimmed + sep + childTrimmed;
+}
+
+/**
+ * True iff `resolved` is a filesystem root on `platform`. Used by
+ * server-side `browse.ts` to compute `parent = null` uniformly
+ * (replacing the Unix-only `resolved === "/"` check).
+ */
+export function isFilesystemRoot(
+  resolved: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (!resolved) return false;
+  if (platform === "win32") {
+    // Drive-letter root: "C:\" (also accept forward slash form)
+    if (/^[A-Za-z]:[\\/]$/.test(resolved)) return true;
+    // UNC root: "\\server\share" with optional trailing sep
+    if (/^\\\\[^\\]+\\[^\\]+\\?$/.test(resolved)) return true;
+    // Bare separator as "current drive root" — Node's path.dirname("/")
+    // returns "/" even on Windows, and listDirectories("/") is a valid
+    // call for "root of the current drive". Treat it as a root so the
+    // picker doesn't show a useless `..` entry.
+    if (resolved === "/" || resolved === "\\") return true;
+    return false;
+  }
+  return resolved === "/";
+}

package/packages/shared/src/platform/process-identify.ts

@@ -0,0 +1,126 @@
+/**
+ * Process identification primitives — find PIDs by command-line marker,
+ * check if a PID looks like a pi-related process.
+ *
+ * Every OS-dependent helper accepts injectable `platform` and `exec`
+ * parameters, defaulting to `process.platform` and a safe `execSync`.
+ * Tests exercise both branches without mutating `process.platform`.
+ *
+ * Windows branches are intentional stubs today: there is no cheap,
+ * format-stable cross-command way to inspect a PID's command line
+ * (tasklist /V is slow and locale-dependent). Windows pi-ness is
+ * verified via `headlessPidRegistry` at the server level, which tracks
+ * PID → session identity directly at spawn time. Future work can
+ * extend these Windows branches with WMIC / PowerShell probing in
+ * ONE place (here) instead of the three scattered inline checks in
+ * session-action-handler.ts.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+import { execSync } from "./exec.js";
+
+type ExecFn = (cmd: string, opts: { encoding: "utf-8"; timeout?: number; stdio?: any }) => string;
+
+export interface ProcessIdentifyOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override execSync (for tests). */
+  exec?: ExecFn;
+}
+
+function defaultExec(cmd: string, opts: { encoding: "utf-8"; timeout?: number; stdio?: any }): string {
+  return execSync(cmd, { ...opts, windowsHide: true }) as unknown as string;
+}
+
+// ── Pattern matcher ─────────────────────────────────────────────────────────
+
+/** Returns true iff the given command-line string references pi or node. */
+export function isPiCommandLine(commandLine: string): boolean {
+  return /\bpi\b|\bnode\b/.test(commandLine);
+}
+
+// ── findPidByMarker ─────────────────────────────────────────────────────────
+
+/**
+ * Find PIDs whose command line contains `marker`. Unix uses ps|grep;
+ * Windows returns `[]` (command-line lookup is delegated to
+ * headlessPidRegistry at the server level).
+ *
+ * Never throws. Returns `[]` on any error.
+ */
+export function findPidByMarker(marker: string, opts: ProcessIdentifyOpts = {}): number[] {
+  const platform = opts.platform ?? process.platform;
+  if (platform === "win32") return [];
+
+  const exec = opts.exec ?? defaultExec;
+  // Additional sentinels help distinguish pi headless spawns from other
+  // processes that happen to contain the session ID in an env var or
+  // unrelated argument. The canonical sentinels match the Unix headless
+  // wrapper strings.
+  const sentinels = ["sleep 2147483647", "tail -f /dev/null"];
+
+  try {
+    const out = exec(
+      `ps -eo pid,command | grep ${shellQuote(marker)} | grep -v grep`,
+      { encoding: "utf-8", timeout: 3000 },
+    ).trim();
+    if (!out) return [];
+
+    const pids: number[] = [];
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      // Must also contain one of the pi headless sentinels, else it's
+      // probably a grep/editor/tail-of-log matching the session id.
+      const hasSentinel = sentinels.some((s) => trimmed.includes(s));
+      if (!hasSentinel) continue;
+      const pidStr = trimmed.split(/\s+/, 1)[0];
+      const pid = parseInt(pidStr, 10);
+      if (pid > 0) pids.push(pid);
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
+
+// ── isProcessLikePi ────────────────────────────────────────────────────────
+
+/**
+ * Check if a PID belongs to a pi/node process. Safety check before
+ * SIGKILL on Unix; no-op on Windows where pi-ness is tracked by
+ * the PID registry at spawn time.
+ *
+ * Unix behaviour:
+ *   - macOS: `ps -p <pid> -o command=`
+ *   - Linux: `/proc/<pid>/cmdline` with `ps` fallback via `cat`
+ *
+ * Returns `false` if the process has already exited (command fails).
+ * Returns `true` on Windows unconditionally.
+ */
+export function isProcessLikePi(pid: number, opts: ProcessIdentifyOpts = {}): boolean {
+  const platform = opts.platform ?? process.platform;
+  if (platform === "win32") return true;
+
+  const exec = opts.exec ?? defaultExec;
+  const cmd = platform === "darwin"
+    ? `ps -p ${pid} -o command=`
+    : `cat /proc/${pid}/cmdline 2>/dev/null || ps -p ${pid} -o command=`;
+
+  try {
+    const output = exec(cmd, { encoding: "utf-8", timeout: 2000 }).trim();
+    return isPiCommandLine(output);
+  } catch {
+    return false;
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function shellQuote(s: string): string {
+  // Strict allow-list: if the marker is purely [A-Za-z0-9._-], leave it alone;
+  // otherwise single-quote it safely. Session IDs are UUIDs or similar and
+  // fall into the allow-list in practice, so this is almost always a no-op.
+  if (/^[A-Za-z0-9._-]+$/.test(s)) return `"${s}"`;
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}