viewable-one 0.0.0-stage → 0.12.1

package/lib/procs.mjs

@@ -0,0 +1,428 @@
+// KILLING WHAT A SESSION LEFT RUNNING, and nothing about git.
+//
+// Split out of worktree.mjs on 2026-09-02, verbatim. Both halves answer one
+// question - "is this process mine to kill?" - and both learned the same
+// lesson the same way, which is why they belong beside each other rather than
+// in the middle of a file about worktrees:
+//
+//   the reaper matched a bare substring of argv against the worktrees path,
+//     so an editor opened on a deleted worktree, a `grep -r` naming one, a
+//     `tail -f` on its log or a shell whose prompt carried the path all got
+//     SIGTERM'd on a poll tick;
+//   killProcessesIn killed every pid `lsof +D` returned, which is every
+//     process with a file open under the tree - and Merge and Delete are
+//     ordinary buttons on his board.
+//
+// So both now ask the same two things: is it one of OUR binaries, and does
+// its parent chain lead back to this runner. Everything else is somebody's
+// own process. `exists` is passed in rather than imported, so this file
+// depends on nothing but node.
+
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join, win32 } from "node:path";
+
+import { killTree } from "./kill.mjs";
+
+/** argv[0]'s basename, on either slash style. `win32.basename` treats BOTH
+ * "/" and "\" as separators (Windows accepts a forward-slash path too), so
+ * it is a strict superset of the old `argv0.slice(argv0.lastIndexOf("/") +
+ * 1)`: identical output for every POSIX path (no "\" ever appears in one),
+ * and correct for a Windows one ("C:\Users\...\node.exe" -> "node.exe"),
+ * without checking `process.platform` or needing a different code path on
+ * the machine this actually runs on. */
+const basenameOf = (argv0) => win32.basename(argv0);
+
+/** The prefix every board-spawned tree and branch carries.
+ *
+ * The ask, 2026-08-28: "let the branch name + worktrees of coding sessions run
+ * on the board start with glytch, then the name of the actual prompt on the
+ * board.. that way we are able to corrolate things". One word in `git branch`
+ * or `git worktree list` says which of those trees came off the canvas, and
+ * the words after it say WHICH circle asked - which `spawn/spawn-mtahtd9d-e1552c`
+ * could not, because a base36 timestamp correlates with nothing a person
+ * holds in their head. */
+export const GLYTCH = "glytch";
+
+/** The prefix a CHAT worktree carries instead (brief 25, ruling 1,
+ *  2026-09-07): `<root>/.claude/worktrees/chat-<agentId>`, one per agent per
+ *  folder, made once on the agent's first chat turn there and kept.
+ *
+ * It lives beside GLYTCH because this file is where a worktree name is
+ * MATCHED, and the two rules are read together: `glytch-` is a session's
+ * tree, made and thrown away per run, and `chat-` is an agent's, which
+ * outlives every turn that runs in it. */
+export const CHAT_PREFIX = "chat-";
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Every process on the machine as `pid -> { ppid, args, binary }`.
+ *
+ * `binary` is argv[0]'s basename, so an absolute path to the binary
+ * (/opt/homebrew/bin/claude) counts the same as a bare `claude` - the same
+ * comparison reapableWorktreeName makes. Split out from the `ps` call so the
+ * parsing can be pinned without spawning anything. */
+export function parseProcessTable(psOutput) {
+  const table = new Map();
+  for (const line of String(psOutput ?? "").trim().split("\n").slice(1)) {
+    const match = line.trim().match(/^([0-9]+)[ \t]+([0-9]+)[ \t]+(.*)$/);
+    if (!match) continue;
+    const args = match[3];
+    const argv0 = args.trim().split(/\s+/)[0] ?? "";
+    table.set(Number(match[1]), {
+      ppid: Number(match[2]),
+      args,
+      binary: basenameOf(argv0),
+    });
+  }
+  return table;
+}
+
+// ---------- the same table, on a machine with no `ps` ----------
+//
+// Brief 21 session 3 (2026-09-07). The brief left this a choice: a Windows
+// process table, or an honest refusal that logs one line and spares
+// everything. IT IS THE TABLE, because the guard this file exists for CAN be
+// reproduced faithfully on Windows - `Get-CimInstance Win32_Process` hands
+// back ProcessId, ParentProcessId, Name and CommandLine, which is pid, ppid,
+// binary and argv, exactly what `ps -eo pid,ppid,args` gives and exactly what
+// isOursToKill's two tests need. Nothing about the decision changes; only
+// where the rows come from.
+//
+// THE ONE HONEST REFUSAL IS killProcessesIn, below: `lsof +D <dir>` has no
+// Windows counterpart that ships with the OS (Sysinternals handle.exe is a
+// download, not a given), so on Windows there is no way to learn WHICH pids
+// hold a file open under a worktree. Ruling 4A says never kill on a bare pid,
+// and a list of candidates we cannot produce is not a licence to kill the
+// table instead: it logs one line and spares everything.
+
+/** The PowerShell one-liner that stands in for `ps -eo pid,ppid,args`. */
+export const CIM_TABLE_ARGS = [
+  "-NoProfile",
+  "-NonInteractive",
+  "-Command",
+  "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress",
+];
+
+/** argv[0]'s basename, on either separator, lowercased and with the Windows
+ * executable suffix removed.
+ *
+ * A command line on Windows quotes a path with spaces
+ * (`"C:\Program Files\nodejs\node.exe" foo.js`), so a leading quoted token is
+ * read whole. The suffix is stripped so `node.exe` and `claude.cmd` match the
+ * AGENT_BINARIES set the POSIX side already uses - the guard asks "is this one
+ * of our binaries", and `.exe` is spelling, not identity. */
+export function windowsBinaryOf(commandLine, fallbackName = "") {
+  const line = String(commandLine ?? "").trim();
+  let argv0 = "";
+  if (line.startsWith('"')) {
+    const close = line.indexOf('"', 1);
+    argv0 = close > 0 ? line.slice(1, close) : line.slice(1);
+  } else {
+    argv0 = line.split(/\s+/)[0] ?? "";
+  }
+  const raw = argv0 || String(fallbackName ?? "");
+  const base = raw.slice(Math.max(raw.lastIndexOf("/"), raw.lastIndexOf("\\")) + 1);
+  return base.toLowerCase().replace(/\.(exe|cmd|bat|com)$/, "");
+}
+
+/** `Get-CimInstance Win32_Process | ConvertTo-Json` as the same
+ * `pid -> { ppid, args, binary }` Map `parseProcessTable` builds, so
+ * isOursToKill and the reaper never learn which platform they are on.
+ *
+ * `CommandLine` is null for a process this user may not read; `Name` carries
+ * the binary in that case and the argv is that name alone, which is honest -
+ * a process we cannot see the arguments of is one we should not match on
+ * arguments. Bad JSON is an empty Map, the same "we could not see" the POSIX
+ * path returns when `ps` fails. */
+export function parseWin32ProcessTable(json) {
+  const table = new Map();
+  const text = String(json ?? "").trim();
+  if (text === "" || text === "null") return table;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return table;
+  }
+  for (const row of Array.isArray(parsed) ? parsed : [parsed]) {
+    const pid = Number(row?.ProcessId);
+    if (!Number.isFinite(pid)) continue;
+    const args = String(row?.CommandLine ?? row?.Name ?? "").trim();
+    table.set(pid, {
+      ppid: Number(row?.ParentProcessId ?? 0) || 0,
+      args,
+      binary: windowsBinaryOf(row?.CommandLine, row?.Name),
+    });
+  }
+  return table;
+}
+
+const runOut = (bin, args, timeout = 15_000) =>
+  new Promise((done) => {
+    execFile(bin, args, { timeout, maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (error, stdout) =>
+      done(error ? "" : String(stdout ?? "")),
+    );
+  });
+
+async function processTable(platform = process.platform) {
+  if (platform === "win32") return parseWin32ProcessTable(await runOut("powershell.exe", CIM_TABLE_ARGS));
+  return new Promise((done) => {
+    execFile("ps", ["-eo", "pid,ppid,args"], { timeout: 10_000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
+      done(error ? new Map() : parseProcessTable(stdout));
+    });
+  });
+}
+
+/** May this daemon kill `pid`? Only if it is a session this daemon left
+ * behind, by one of two tests:
+ *
+ *   1. the process IS one of the agent binaries (claude, opencode, node) -
+ *      the same guard reapableWorktreeName applies below;
+ *   2. its parent chain leads back to THIS runner, so we started it however
+ *      it has since renamed itself.
+ *
+ * Anything else with a file open under the worktree is somebody's own
+ * process, and killing it is the bug this exists to stop. Exported because
+ * it is a pure decision over a ps snapshot and deserves to be pinned without
+ * spawning anything. */
+export function isOursToKill(pid, table, runnerPid, agentBinaries = AGENT_BINARIES) {
+  const entry = table.get(pid);
+  if (!entry) return false; // gone, or ps could not see it: leave it alone
+  if (agentBinaries.has(entry.binary)) return true;
+  let cur = entry.ppid;
+  // Bounded: a cycle in a ps snapshot should be impossible and is free to
+  // guard against here.
+  for (let hops = 0; hops < 64 && cur > 1; hops += 1) {
+    if (cur === runnerPid) return true;
+    const parent = table.get(cur);
+    if (!parent) return false;
+    cur = parent.ppid;
+  }
+  return false;
+}
+
+/** Kill processes whose cwd is inside a worktree, so removing the directory
+ * does not fail on open files and dev servers do not outlive their session.
+ *
+ * Best-effort: a failure here does not prevent the worktree operation from
+ * proceeding. The most common case is a Vite/webpack dev server the session
+ * started and never stopped.
+ *
+ * Uses lsof on macOS and fuser on Linux. Neither is guaranteed to exist on
+ * every system, so a missing binary is handled the same as an empty result.
+ *
+ * IT USED TO KILL EVERY PID lsof RETURNED, and lsof +D returns every process
+ * with a file open under the tree: the user's editor with one of its files in
+ * a tab, a `tail -f` on its log, a shell sitting in the directory, a `grep -r`
+ * passing through. Merge and Delete are ordinary buttons on his board, and
+ * pressing one SIGTERM'd whatever he happened to have open.
+ *
+ * The reaper below already learned this class of bug and grew a binary guard -
+ * see reapableWorktreeName for what a bare substring match did to an editor -
+ * so this applies the same one, plus a parent-chain test, because a process
+ * THIS runner started is ours to clean up whatever it renamed itself to. */
+export async function killProcessesIn(dirPath, log = () => {}, platform = process.platform) {
+  if (!dirPath) return;
+  // THE HONEST REFUSAL (brief 21, 2026-09-07). `lsof +D` is how this function
+  // learns which pids to consider, and Windows ships nothing equivalent. With
+  // no candidate list there is no way to honour ruling 4A's "never kill on a
+  // bare pid", and killing the whole process table instead is the bug this
+  // file exists to prevent. So it spares everything and says so once; the
+  // worktree rm that follows may then fail EBUSY, which is a visible failure
+  // rather than a silent wrong kill.
+  if (platform === "win32") {
+    log(`not looking for processes with files open in ${dirPath}: Windows has no lsof, so nothing here is safe to kill`);
+    return;
+  }
+  // lsof +D is slow on large trees; instead find PIDs whose cwd is exactly
+  // this directory or a child. lsof -t +d (non-recursive) gives PIDs with
+  // open files in the directory.
+  const pids = await new Promise((resolve) => {
+    // On macOS, `lsof +D <dir> -t` gives all PIDs with open files under dir.
+    // On failure or empty, resolve with an empty list.
+    execFile("lsof", ["+D", dirPath, "-t"], { timeout: 10_000 }, (error, stdout) => {
+      if (error || !stdout.trim()) return resolve([]);
+      resolve(
+        stdout
+          .trim()
+          .split("\n")
+          .map((p) => parseInt(p, 10))
+          .filter((p) => Number.isFinite(p) && p > 1),
+      );
+    });
+  });
+  if (pids.length === 0) return;
+  const own = process.pid;
+  const candidates = pids.filter((p) => p !== own);
+  if (candidates.length === 0) return;
+  const table = await processTable();
+  const toKill = candidates.filter((p) => isOursToKill(p, table, own));
+  const spared = candidates.length - toKill.length;
+  if (spared > 0) {
+    log(`leaving ${spared} process(es) with files open in ${dirPath} alone: not this runner's to kill`);
+  }
+  if (toKill.length === 0) return;
+  log(`killing ${toKill.length} process(es) in ${dirPath}: ${toKill.join(", ")}`);
+  for (const pid of toKill) {
+    try { await killTree(pid); } catch { /* already gone */ }
+  }
+  // Give them a moment to exit before we rm the directory.
+  await new Promise((r) => setTimeout(r, 1000));
+}
+
+// ---------- orphaned process reaper ----------
+//
+// killProcessesIn uses `lsof +D <dir>`, which returns nothing once the
+// directory has been deleted. On 2026-08-30 five vite servers were alive
+// pointing at deleted worktrees. This sweep finds processes whose command
+// line names a path under .claude/worktrees/ that no longer exists.
+//
+// Called at spawn time or teardown time, never as a daemon (ruling
+// q-mt9as5a0: no reaper daemon, no heartbeat, no third state).
+
+/** Kill processes whose argv references a .claude/worktrees/<name> path
+ * that no longer exists on disk.
+ *
+ * Uses `ps -eo pid,args` to find processes, matches their command line
+ * against the worktrees directory, checks whether the named directory
+ * still exists, and kills those pointing at gone trees. */
+/** The agent binaries this runner ever spawns (agents.mjs). Anything else in a
+ *  worktree is somebody's own process, not a session this daemon left behind. */
+const AGENT_BINARIES = new Set(["claude", "opencode", "node"]);
+
+/** The spawn-worktree name this command line is a REAPABLE session for, or null.
+ *
+ * Two guards, both learned from how badly a bare substring match behaves. It
+ * used to be `args.indexOf("<wtRoot>/")` and nothing else, run on every poll
+ * against every process on the machine - so an editor opened on a since-deleted
+ * worktree, a `grep -r` whose arguments named one, a `tail -f` on its log, or a
+ * shell whose prompt string carried the path all got SIGTERM'd. The user's own
+ * editor was one SIGTERM away from a poll tick.
+ *
+ *  1. the directory must be one makeWorktree could have created (`glytch-`),
+ *     which the old comment claimed was checked and never was;
+ *  2. the process must BE one of the agent binaries, so a tool that merely
+ *     mentions the path is never a candidate.
+ *
+ * Exported for the test: this is a pure string decision and deserves to be
+ * pinned without spawning anything. */
+export function reapableWorktreeName(args, wtRoot) {
+  if (typeof args !== "string" || args === "") return null;
+  // `wtRoot` comes from `join()`, so it already carries whichever separator
+  // built it - "\" on Windows, "/" everywhere else. The old code hardcoded
+  // "/", so on Windows the pattern was "C:\...\worktrees/" and never matched
+  // a real argv string, which is backslash-joined there too. Read the
+  // separator OFF wtRoot itself rather than off `process.platform` (or off
+  // `path.sep`, which is bound to the OS running the test, not the OS that
+  // produced the string) so the fix is a pure function of its input and
+  // provable on any machine.
+  const wtSep = wtRoot.includes("\\") ? "\\" : "/";
+  const wtPattern = `${wtRoot}${wtSep}`;
+  const idx = args.indexOf(wtPattern);
+  if (idx < 0) return null;
+
+  // The directory name is everything up to the next "/" or "\" or
+  // whitespace - both separators always, not just the platform's own, so a
+  // path that mixes them (as a Windows argv string sometimes does) still
+  // stops at the right place.
+  const nameMatch = args.slice(idx + wtPattern.length).match(/^([^\s/\\]+)/);
+  if (!nameMatch) return null;
+  const wtName = nameMatch[1];
+  // A CHAT WORKTREE IS NEVER REAPED (brief 25, ruling 1, 2026-09-07: one
+  // long-lived chat worktree per agent per folder, kept). The reaper's whole
+  // question is "the tree is gone, so is this process an orphan of it?" - and
+  // a chat tree that is momentarily gone (swept by hand, pruned) is minted
+  // again by the next message rather than abandoned, so a process running in
+  // one is never an orphan of a dead session. A `chat-` name also never
+  // carries the `glytch-` prefix below, so this states the rule rather than
+  // adding one: it is here so that renaming either prefix cannot quietly put
+  // a chat conversation's child on the kill list.
+  if (wtName.startsWith(CHAT_PREFIX)) return null;
+  if (!wtName.startsWith(`${GLYTCH}-`)) return null;
+
+  // argv[0] is the command; compare on its basename so an absolute path to the
+  // binary (/opt/homebrew/bin/claude, or C:\...\claude.exe) counts the same
+  // as a bare `claude`.
+  const argv0 = args.trim().split(/\s+/)[0] ?? "";
+  const binary = basenameOf(argv0);
+  if (!AGENT_BINARIES.has(binary)) return null;
+
+  return wtName;
+}
+
+export async function reapOrphanedWorktreeProcesses(root, log = () => {}, platform = process.platform) {
+  const wtRoot = join(root, ".claude", "worktrees");
+  // On Windows the same rows come from Win32_Process rather than from `ps`;
+  // everything after this line is the same decision over the same shape.
+  // (The worktrees pattern and the argv0 basename inside reapableWorktreeName
+  // are still POSIX-shaped - `${wtRoot}/` and a "/" split - and are session
+  // 1's to fix. Until they are, this list is built correctly on Windows and
+  // matches nothing, which is the safe direction.)
+  if (platform === "win32") {
+    const table = await processTable(platform);
+    return reapFromList(
+      [...table].map(([pid, entry]) => ({ pid, args: entry.args })),
+      wtRoot,
+      log,
+    );
+  }
+  // Pattern to match in process argv: the worktrees directory path.
+  const psList = await new Promise((resolve) => {
+    execFile("ps", ["-eo", "pid,args"], { timeout: 10_000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
+      if (error || !stdout.trim()) return resolve([]);
+      resolve(
+        stdout
+          .trim()
+          .split("\n")
+          .slice(1) // skip header
+          .map((line) => {
+            const trimmed = line.trim();
+            const spaceIdx = trimmed.indexOf(" ");
+            if (spaceIdx < 0) return null;
+            const pid = parseInt(trimmed.slice(0, spaceIdx), 10);
+            const args = trimmed.slice(spaceIdx + 1);
+            return Number.isFinite(pid) && pid > 1 ? { pid, args } : null;
+          })
+          .filter(Boolean),
+      );
+    });
+  });
+  return reapFromList(psList, wtRoot, log);
+}
+
+/** The decision half of the reaper, over a `{pid, args}` list from whichever
+ * process source the platform has. */
+async function reapFromList(psList, wtRoot, log) {
+  if (psList.length === 0) return { killed: 0 };
+
+  const own = process.pid;
+  const killed = [];
+
+  for (const { pid, args } of psList) {
+    if (pid === own) continue;
+    const wtName = reapableWorktreeName(args, wtRoot);
+    if (!wtName) continue;
+    const wtPath = join(wtRoot, wtName);
+
+    if (await exists(wtPath)) continue; // directory still exists, leave it
+
+    // The directory is gone but the process is alive. Kill it.
+    log(`reaping pid ${pid} (${wtName}): worktree deleted, process still running`);
+    try { await killTree(pid); killed.push(pid); } catch { /* already gone */ }
+  }
+
+  if (killed.length > 0) {
+    log(`reaped ${killed.length} orphaned process(es): ${killed.join(", ")}`);
+    // Give them a moment to exit.
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return { killed: killed.length };
+}