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

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, "'\\''")}'`;
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Cross-platform process enumeration primitives: is-process-running,
+ * ps/tasklist pattern-matching, elapsed-time parsing.
+ *
+ * Every OS-dependent helper accepts injectable `platform` and `exec`
+ * parameters (defaulting to `process.platform` and `execSync`), so tests
+ * can exercise both branches without mutating the global `process.platform`.
+ * See change: consolidate-platform-handlers.
+ */
+
+import { execSync } from "./exec.js";
+
+type ExecFn = (cmd: string, opts: { encoding: "utf-8"; stdio?: any }) => string;
+
+export interface ProcessScanOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override execSync (for tests). */
+  exec?: ExecFn;
+}
+
+function defaultExec(cmd: string, opts: { encoding: "utf-8"; stdio?: any }): string {
+  return execSync(cmd, { ...opts, windowsHide: true }) as unknown as string;
+}
+
+// ── Elapsed-time parsing (pure, platform-agnostic) ──────────────────────────
+
+/**
+ * Parse `ps -o etime=` format into milliseconds. Handles:
+ *   - `mm:ss`          (e.g. "02:15" → 135000)
+ *   - `hh:mm:ss`       (e.g. "01:30:00" → 5400000)
+ *   - `dd-hh:mm:ss`    (e.g. "2-03:00:00" → 183600000)
+ *
+ * Returns 0 for empty or unparseable input.
+ */
+export function parseEtime(etime: string): number {
+  const trimmed = etime.trim();
+  if (!trimmed) return 0;
+
+  let days = 0;
+  let rest = trimmed;
+
+  const dashIdx = rest.indexOf("-");
+  if (dashIdx !== -1) {
+    days = parseInt(rest.slice(0, dashIdx), 10);
+    if (isNaN(days)) return 0;
+    rest = rest.slice(dashIdx + 1);
+  }
+
+  const parts = rest.split(":").map((p) => parseInt(p, 10));
+  if (parts.some(isNaN)) return 0;
+
+  let hours = 0, minutes = 0, seconds = 0;
+  if (parts.length === 3) {
+    [hours, minutes, seconds] = parts;
+  } else if (parts.length === 2) {
+    [minutes, seconds] = parts;
+  } else {
+    return 0;
+  }
+
+  return ((days * 86400) + (hours * 3600) + (minutes * 60) + seconds) * 1000;
+}
+
+// ── Process-running check ───────────────────────────────────────────────────
+
+/**
+ * Check whether a process matching `pattern` is currently running.
+ *   - win32: `tasklist /FI "IMAGENAME eq <pattern>" /NH` — pattern is the
+ *            executable image name (e.g. "Code.exe"). Returns true if the
+ *            output contains the pattern.
+ *   - unix:  `pgrep -f "<pattern>"` — pattern is any substring of the
+ *            command-line (e.g. "/Applications/Zed.app"). Returns true if
+ *            pgrep exits with code 0 (at least one match).
+ *
+ * Best-effort: any failure returns `false`.
+ */
+export function isProcessRunning(pattern: string, opts: ProcessScanOpts = {}): boolean {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  try {
+    if (platform === "win32") {
+      const result = exec(`tasklist /FI "IMAGENAME eq ${pattern}" /NH`, {
+        encoding: "utf-8",
+        stdio: "pipe",
+      });
+      return String(result).includes(pattern);
+    }
+    exec(`pgrep -f "${pattern}"`, { encoding: "utf-8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,168 @@
+/**
+ * Cross-platform process primitives: port cleanup, kill, liveness, group-kill.
+ *
+ * Every OS-dependent helper takes an optional `platform` parameter
+ * (defaulting to `process.platform`) so tests can exercise both branches
+ * without mutating the global `process.platform`. See change:
+ * consolidate-platform-handlers.
+ */
+
+import { execSync } from "./exec.js";
+
+export type ExecFn = (cmd: string, opts: { encoding: "utf-8" }) => string;
+export type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
+
+export interface ProcessOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override execSync (for tests). */
+  exec?: ExecFn;
+  /** Override process.kill (for tests). */
+  kill?: KillFn;
+}
+
+function defaultExec(cmd: string, opts: { encoding: "utf-8" }): string {
+  // Always suppress the cmd.exe window flash on Windows. The primitives that
+  // use this (findPortHolders via netstat, killProcess via taskkill) don't
+  // need user visibility.
+  return execSync(cmd, { ...opts, windowsHide: true }) as unknown as string;
+}
+
+function defaultKill(pid: number, signal: NodeJS.Signals | number): void {
+  process.kill(pid, signal);
+}
+
+// ── Port-holder detection ────────────────────────────────────────────────────
+
+/**
+ * Parse `netstat -ano -p tcp` output for PIDs listening on a port (Windows).
+ * Pure function, exported for testing.
+ *
+ * Example input line:
+ *   "  TCP    0.0.0.0:8000   0.0.0.0:0   LISTENING   12345"
+ */
+export function parseNetstatListeners(output: string, port: number, selfPid: number): number[] {
+  const pids: number[] = [];
+  const portSuffix = `:${port}`;
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !/^\s*TCP/i.test(line)) continue;
+    if (!/LISTENING/i.test(line)) continue;
+    const cols = trimmed.split(/\s+/);
+    if (cols.length < 5) continue;
+    const local = cols[1];
+    if (!local.endsWith(portSuffix)) continue;
+    const pid = Number.parseInt(cols[cols.length - 1], 10);
+    if (Number.isFinite(pid) && pid > 0 && pid !== selfPid) pids.push(pid);
+  }
+  return pids;
+}
+
+/**
+ * Find PIDs holding a TCP port. Cross-platform:
+ *   - win32: `netstat -ano -p tcp` → parse LISTENING rows
+ *   - unix:  `lsof -t -i :<port> -sTCP:LISTEN`
+ *
+ * Best-effort: any failure returns []. Excludes the current process PID.
+ */
+export function findPortHolders(port: number, opts: ProcessOpts = {}): number[] {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  try {
+    if (platform === "win32") {
+      const output = exec("netstat -ano -p tcp", { encoding: "utf-8" });
+      return parseNetstatListeners(String(output), port, process.pid);
+    }
+    const output = exec(`lsof -t -i :${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" });
+    return String(output).trim().split("\n").map(Number).filter((n) => n > 0 && n !== process.pid);
+  } catch {
+    return [];
+  }
+}
+
+// ── Liveness ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a PID is alive. Cross-platform via `process.kill(pid, 0)`.
+ */
+export function isProcessAlive(pid: number, opts: { kill?: KillFn } = {}): boolean {
+  const kill = opts.kill ?? defaultKill;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Termination ──────────────────────────────────────────────────────────────
+
+export interface KillProcessResult {
+  ok: boolean;
+  forced: boolean;
+}
+
+/**
+ * Terminate a process, cross-platform:
+ *   - win32: `taskkill /F /T /PID <pid>` (tree kill, immediate)
+ *   - unix:  SIGTERM → wait up to `timeoutMs` → SIGKILL if still alive
+ *
+ * Returns `{ ok, forced }`. `ok` is true if the process was terminated (or
+ * was already dead); `forced` is true if SIGKILL was needed on Unix.
+ */
+export async function killProcess(
+  pid: number,
+  opts: ProcessOpts & { timeoutMs?: number } = {},
+): Promise<KillProcessResult> {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  const kill = opts.kill ?? defaultKill;
+  const timeoutMs = opts.timeoutMs ?? 5000;
+
+  if (!isProcessAlive(pid, { kill })) return { ok: false, forced: false };
+
+  if (platform === "win32") {
+    try {
+      exec(`taskkill /F /T /PID ${pid}`, { encoding: "utf-8" });
+      return { ok: true, forced: false };
+    } catch {
+      return { ok: false, forced: false };
+    }
+  }
+
+  try {
+    kill(pid, "SIGTERM");
+  } catch {
+    return { ok: false, forced: false };
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (!isProcessAlive(pid, { kill })) return { ok: true, forced: false };
+  }
+  try {
+    kill(pid, "SIGKILL");
+  } catch {
+    /* already dead */
+  }
+  return { ok: true, forced: true };
+}
+
+// ── Process-group kill (for detached children) ───────────────────────────────
+
+/**
+ * Signal a process, targeting the process group on Unix (negative PID) and
+ * the PID directly on Windows. Used for detached children spawned with their
+ * own process group.
+ */
+export function killPidWithGroup(
+  pid: number,
+  signal: NodeJS.Signals,
+  opts: ProcessOpts = {},
+): void {
+  const platform = opts.platform ?? process.platform;
+  const kill = opts.kill ?? defaultKill;
+  const target = platform === "win32" ? pid : -pid;
+  kill(target, signal);
+}