viewable-one 0.0.0-stage → 0.12.1

package/lib/kill.mjs

@@ -0,0 +1,104 @@
+// STOPPING A PROCESS, on a platform that has signals and on one that does not.
+//
+// Brief 21 session 3, ruling 4A (2026-09-07). Every kill in this package
+// was `process.kill(pid, "SIGTERM")` then `"SIGKILL"` after a grace, and on
+// Windows that is a fiction twice over: Node maps BOTH signals to
+// TerminateProcess, so the grace the code promises never happens and the child
+// never flushes its log; and it terminates ONE pid, while `claude.cmd` runs the
+// real agent as a grandchild - which then survives and keeps billing. The
+// Windows equivalent of the pair is `taskkill /pid <pid> /t` and, after the
+// same grace, `taskkill /pid <pid> /t /f`: /t is the tree, /f is the force.
+//
+// THE POSIX PATH IS UNCHANGED, deliberately and to the byte. The call it makes
+// is the caller's own `signal` - `child.kill(sig)` in child.mjs, so the "one
+// pid and never the process group" ruling of 2026-09-06 still holds there
+// (lib/child.mjs's kill closure says why that is load-bearing), and
+// `process.kill(pid, sig)` everywhere else, so an ESRCH still throws and a
+// caller that reads a throw as "gone" (lib/devserver.mjs) keeps reading it
+// that way. Windows mirrors that: a taskkill that exits non-zero throws.
+//
+// NOTHING HERE DECIDES WHETHER A PID MAY BE KILLED. That decision lives with
+// the callers - `verifyRecordedServer` in devserver.mjs, `isOursToKill` in
+// procs.mjs - and ruling 4A keeps it there: never a kill on a bare pid.
+
+import { execFile } from "node:child_process";
+
+/** The Windows binary. Named once so a test can assert the argv without
+ * repeating the string. */
+export const TASKKILL = "taskkill";
+
+/** The argv `taskkill` is given for a pid. `/t` is the whole tree, which is
+ * the point: the agent is a grandchild of the `.cmd` shim. `/f` is only added
+ * for the force pass, so the first pass still asks politely and the process
+ * still gets the grace to flush. Pure, so the sequence can be pinned on any
+ * platform. */
+export function taskkillArgs(pid, force = false) {
+  const args = ["/pid", String(pid), "/t"];
+  if (force) args.push("/f");
+  return args;
+}
+
+/** "The process exists, and it will not go politely."
+ *
+ * 2026-09-07, brief 21, the first windows-latest run. `taskkill /pid <pid> /t`
+ * with no `/f` asks a process to close by posting WM_CLOSE to its windows - so
+ * for a console-less process, which every child this package spawns is, the
+ * polite pass ALWAYS fails, with exit 1 and "This process with PID x could not
+ * be terminated. Reason: This process can only be terminated forcefully (with
+ * /F option)." killTree threw that, and `stopRecordedServer` reads a throw from
+ * the first pass as "gone" and returns without ever reaching the force pass -
+ * so a verified detached dev server was never stopped on Windows at all.
+ *
+ * That answer is not a failure and it is not "gone": it is the grace being
+ * declined, which is precisely what the second pass is for. Everything else
+ * taskkill can say - not found, access denied - still throws, so a caller that
+ * reads a throw as "the process is already gone" keeps reading it that way. */
+export const refusedTheGrace = (text) =>
+  /can only be terminated forcefully|with\s*\/F\s*option/i.test(String(text ?? ""));
+
+/** The signal a non-Windows kill sends. */
+export const signalFor = (force) => (force ? "SIGKILL" : "SIGTERM");
+
+const defaultExec = (bin, args) =>
+  new Promise((resolve) => {
+    execFile(bin, args, { timeout: 10_000, windowsHide: true }, (error, stdout, stderr) =>
+      resolve({
+        ok: !error,
+        code: error?.code ?? 0,
+        stdout: String(stdout ?? ""),
+        stderr: String(stderr ?? ""),
+      }),
+    );
+  });
+
+const defaultSignal = (pid, sig) => process.kill(pid, sig);
+
+/** Stop `pid`. `force` picks the second pass (SIGKILL / `/t /f`) rather than
+ * the first (SIGTERM / `/t`).
+ *
+ * `platform`, `exec` and `signal` are injected so Windows behaviour is proven
+ * without a Windows machine and macOS behaviour is proven to be what it was.
+ * Returns what it did; THROWS what the underlying kill throws, because "the
+ * process is already gone" is a caller's decision to make and every existing
+ * caller makes it from the throw. */
+export async function killTree(pid, { force = false, platform = process.platform, exec = defaultExec, signal = defaultSignal } = {}) {
+  const usable = Number.isFinite(Number(pid)) && Number(pid) > 1;
+  if (platform === "win32" && usable) {
+    const args = taskkillArgs(Number(pid), force);
+    const result = await exec(TASKKILL, args);
+    if (!result?.ok) {
+      const said = `${result?.stderr ?? ""}\n${result?.stdout ?? ""}`;
+      // The grace declined is not a failure and not a disappearance: say so,
+      // and let the caller's force pass be the answer. See refusedTheGrace.
+      if (!force && refusedTheGrace(said)) {
+        return { how: "taskkill", argv: [TASKKILL, ...args], force, refusedTheGrace: true };
+      }
+      const detail = String(result?.stderr ?? "").trim() || `exit ${result?.code ?? "?"}`;
+      throw new Error(`taskkill ${args.join(" ")} failed: ${detail}`);
+    }
+    return { how: "taskkill", argv: [TASKKILL, ...args], force };
+  }
+  const sig = signalFor(force);
+  signal(pid, sig);
+  return { how: "signal", signal: sig, force };
+}