@henols/c64-re-tools 1.0.0 → 2.0.0-rc.2

package/src/native/ghidra/scripts/C64Export.java

@@ -0,0 +1,242 @@
+// Runs after Ghidra's analysis. Arguments: <request.json> <out.json>.
+//
+// Writes the structural result for the loaded image: functions with the
+// source of their names, code and defined-data regions, memory references
+// from instructions, and the requested decompilations within their bounds.
+//@category c64-re-tools
+
+import java.io.FileReader;
+import java.io.FileWriter;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+import com.google.gson.Gson;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.app.decompiler.DecompileResults;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.address.AddressSet;
+import ghidra.program.model.listing.CodeUnit;
+import ghidra.program.model.listing.Data;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.symbol.RefType;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.SourceType;
+
+public class C64Export extends GhidraScript {
+	private static final java.util.regex.Pattern NAME = java.util.regex.Pattern.compile("^\\.?[A-Za-z_][A-Za-z0-9_]{0,63}$");
+	/** The longest reason that the result check accepts. */
+	private static final int MAX_REASON = 1000;
+	/** The longest time for one decompilation, in seconds. */
+	private static final int MAX_DECOMPILE_SECONDS = 60;
+
+	@Override
+	public void run() throws Exception {
+		String[] args = getScriptArgs();
+		JsonObject request;
+		try (FileReader reader = new FileReader(args[0])) {
+			request = new Gson().fromJson(reader, JsonObject.class);
+		}
+		long start = request.get("start").getAsLong();
+		long end = request.get("end").getAsLong();
+		AddressSet coverage = new AddressSet(toAddr(start), toAddr(end));
+
+		JsonObject out = new JsonObject();
+		JsonArray coverageOut = new JsonArray();
+		coverageOut.add(range(start, end));
+		out.add("coverage", coverageOut);
+		out.add("functions", functions(coverage));
+		out.add("regions", regions(coverage));
+		out.add("references", references(coverage));
+		JsonArray notDecompiled = new JsonArray();
+		out.add("decompilations", decompile(request, notDecompiled));
+		out.add("notDecompiled", notDecompiled);
+		JsonObject completeness = new JsonObject();
+		completeness.addProperty("functions", true);
+		completeness.addProperty("regions", true);
+		completeness.addProperty("references", true);
+		out.add("completeness", completeness);
+		try (FileWriter writer = new FileWriter(args[1])) {
+			new Gson().toJson(out, writer);
+		}
+	}
+
+	private static JsonObject range(long start, long end) {
+		JsonObject range = new JsonObject();
+		range.addProperty("start", start);
+		range.addProperty("end", end);
+		return range;
+	}
+
+	private JsonArray functions(AddressSet coverage) {
+		JsonArray functions = new JsonArray();
+		for (Function function : currentProgram.getFunctionManager().getFunctions(coverage, true)) {
+			String name = function.getName();
+			SourceType source = function.getSymbol().getSource();
+			// Only the seeds carry user-defined names in this disposable project.
+			String nameSource = source == SourceType.USER_DEFINED ? "seed" : source == SourceType.DEFAULT ? "generated" : "native";
+			if (!NAME.matcher(name).matches()) {
+				// A name that this script makes is generated, whatever name it replaces.
+				name = String.format("FUN_%04x", function.getEntryPoint().getOffset());
+				nameSource = "generated";
+			}
+			JsonObject item = new JsonObject();
+			item.addProperty("entry", function.getEntryPoint().getOffset());
+			item.addProperty("name", name);
+			item.addProperty("nameSource", nameSource);
+			functions.add(item);
+		}
+		return functions;
+	}
+
+	/** Instructions are code and defined data is data; undefined bytes are not classified. */
+	private JsonArray regions(AddressSet coverage) {
+		JsonArray regions = new JsonArray();
+		String kind = null;
+		long first = 0;
+		long last = -2;
+		for (CodeUnit unit : currentProgram.getListing().getCodeUnits(coverage, true)) {
+			String unitKind = unit instanceof Instruction ? "code" : (unit instanceof Data && ((Data) unit).isDefined()) ? "data" : null;
+			long unitStart = unit.getMinAddress().getOffset();
+			long unitEnd = Math.min(unit.getMaxAddress().getOffset(), coverage.getMaxAddress().getOffset());
+			if (unitKind != null && unitKind.equals(kind) && unitStart == last + 1) {
+				last = unitEnd;
+				continue;
+			}
+			if (kind != null) {
+				JsonObject region = range(first, last);
+				region.addProperty("classification", kind);
+				regions.add(region);
+			}
+			kind = unitKind;
+			first = unitStart;
+			last = unitEnd;
+		}
+		if (kind != null) {
+			JsonObject region = range(first, last);
+			region.addProperty("classification", kind);
+			regions.add(region);
+		}
+		return regions;
+	}
+
+	private JsonArray references(AddressSet coverage) {
+		Set<String> seen = new LinkedHashSet<>();
+		JsonArray references = new JsonArray();
+		for (Instruction instruction : currentProgram.getListing().getInstructions(coverage, true)) {
+			for (Reference reference : instruction.getReferencesFrom()) {
+				RefType type = reference.getReferenceType();
+				Address to = reference.getToAddress();
+				if (!reference.isMemoryReference() || !to.isMemoryAddress() || type == RefType.FALL_THROUGH) {
+					continue;
+				}
+				long from = instruction.getMinAddress().getOffset();
+				if (type.isCall()) {
+					add(references, seen, from, to.getOffset(), "call");
+				} else if (type.isJump() || type.isFlow()) {
+					add(references, seen, from, to.getOffset(), "jump");
+				} else {
+					if (type.isRead()) {
+						add(references, seen, from, to.getOffset(), "read");
+					}
+					if (type.isWrite()) {
+						add(references, seen, from, to.getOffset(), "write");
+					}
+					if (!type.isRead() && !type.isWrite()) {
+						add(references, seen, from, to.getOffset(), "reference");
+					}
+				}
+			}
+		}
+		return references;
+	}
+
+	private static void add(JsonArray references, Set<String> seen, long from, long to, String type) {
+		if (!seen.add(from + ":" + to + ":" + type)) {
+			return;
+		}
+		JsonObject reference = new JsonObject();
+		reference.addProperty("from", from);
+		reference.addProperty("to", to);
+		reference.addProperty("type", type);
+		references.add(reference);
+	}
+
+	/** A requested routine without decompiled code, and the decompiler's reason. */
+	private static void notDecompiled(JsonArray list, long entry, String reason) {
+		JsonObject item = new JsonObject();
+		item.addProperty("entry", entry);
+		String text = reason == null || reason.isBlank() ? "the decompiler gave no reason" : reason.strip();
+		item.addProperty("reason", text.length() > MAX_REASON ? text.substring(0, MAX_REASON) : text);
+		list.add(item);
+	}
+
+	private JsonArray decompile(JsonObject request, JsonArray failures) {
+		JsonArray decompilations = new JsonArray();
+		JsonArray entries = request.getAsJsonArray("decompile");
+		if (entries.size() == 0) {
+			return decompilations;
+		}
+		int perFunction = request.get("maxChars").getAsInt();
+		int remaining = request.get("maxTotalChars").getAsInt();
+		// The time that is left for the decompilations, as a clock time in milliseconds.
+		long deadline = request.get("decompileDeadline").getAsLong();
+		int routinesLeft = entries.size();
+		DecompInterface decompiler = new DecompInterface();
+		try {
+			// Ghidra ships no native decompiler for some platforms (macOS): it then does not start.
+			if (!decompiler.openProgram(currentProgram)) {
+				String reason = "the Ghidra decompiler did not start: " + decompiler.getLastMessage();
+				for (JsonElement element : entries) {
+					notDecompiled(failures, element.getAsLong(), reason);
+				}
+				return decompilations;
+			}
+			for (JsonElement element : entries) {
+				// Each routine gets an equal part of the time that is left, so every routine gets a turn.
+				long secondsLeft = (deadline - System.currentTimeMillis()) / 1000;
+				int seconds = (int) Math.min(MAX_DECOMPILE_SECONDS, secondsLeft / routinesLeft);
+				routinesLeft--;
+				Function function = getFunctionAt(toAddr(element.getAsLong()));
+				if (function == null) {
+					notDecompiled(failures, element.getAsLong(), "no function starts at this address");
+					continue;
+				}
+				if (remaining <= 0) {
+					notDecompiled(failures, element.getAsLong(), "the decompiled text of the other routines used the whole limit");
+					continue;
+				}
+				if (seconds < 1) {
+					notDecompiled(failures, element.getAsLong(), "the time for the Ghidra run ended before this routine");
+					continue;
+				}
+				DecompileResults results = decompiler.decompileFunction(function, seconds, monitor);
+				if (!results.decompileCompleted() || results.getDecompiledFunction() == null) {
+					notDecompiled(failures, element.getAsLong(), results.getErrorMessage());
+					continue;
+				}
+				String text = results.getDecompiledFunction().getC();
+				int limit = Math.min(perFunction, remaining);
+				boolean truncated = text.length() > limit;
+				if (truncated) {
+					text = text.substring(0, limit);
+				}
+				remaining -= text.length();
+				JsonObject item = new JsonObject();
+				item.addProperty("entry", function.getEntryPoint().getOffset());
+				item.addProperty("text", text);
+				item.addProperty("truncated", truncated);
+				decompilations.add(item);
+			}
+		}
+		finally {
+			decompiler.dispose();
+		}
+		return decompilations;
+	}
+}

package/src/native/ghidra/scripts/C64Prepare.java

@@ -0,0 +1,60 @@
+// Runs before Ghidra's analysis. Arguments: <seeds.json>.
+//
+// Fills the rest of the 64 KiB address space with uninitialized memory, so
+// references to I/O and other RAM resolve, then applies the knowledge seeds:
+// labels (user-defined names), data ranges (defined bytes that analysis does
+// not disassemble) and entry points (disassembled functions).
+//@category c64-re-tools
+
+import java.io.FileReader;
+
+import com.google.gson.Gson;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.data.ArrayDataType;
+import ghidra.program.model.data.ByteDataType;
+import ghidra.program.model.mem.Memory;
+import ghidra.program.model.symbol.SourceType;
+
+public class C64Prepare extends GhidraScript {
+	@Override
+	public void run() throws Exception {
+		JsonObject seeds;
+		try (FileReader reader = new FileReader(getScriptArgs()[0])) {
+			seeds = new Gson().fromJson(reader, JsonObject.class);
+		}
+		long start = seeds.get("start").getAsLong();
+		long end = seeds.get("end").getAsLong();
+		Memory memory = currentProgram.getMemory();
+		if (start > 0) {
+			memory.createUninitializedBlock("RAM_LOW", toAddr(0), start, false);
+		}
+		if (end < 0xffff) {
+			memory.createUninitializedBlock("RAM_HIGH", toAddr(end + 1), 0xffff - end, false);
+		}
+
+		for (JsonElement element : seeds.getAsJsonArray("labels")) {
+			JsonObject label = element.getAsJsonObject();
+			createLabel(toAddr(label.get("address").getAsLong()), label.get("name").getAsString(), true, SourceType.USER_DEFINED);
+		}
+		for (JsonElement element : seeds.getAsJsonArray("dataRanges")) {
+			JsonObject range = element.getAsJsonObject();
+			Address first = toAddr(range.get("start").getAsLong());
+			Address last = toAddr(range.get("end").getAsLong());
+			int length = (int) (last.getOffset() - first.getOffset() + 1);
+			currentProgram.getListing().clearCodeUnits(first, last, false);
+			currentProgram.getListing().createData(first, new ArrayDataType(ByteDataType.dataType, length, 1));
+		}
+		for (JsonElement element : seeds.getAsJsonArray("entryPoints")) {
+			Address entry = toAddr(element.getAsLong());
+			addEntryPoint(entry);
+			disassemble(entry);
+			if (getFunctionAt(entry) == null) {
+				createFunction(entry, null);
+			}
+		}
+	}
+}

package/src/native/local.ts

@@ -0,0 +1,34 @@
+// The context for running native tools inside a skill script or the CLI:
+// one supervisor whose exit guard stops every tool process group when
+// the script ends, also on Ctrl+C or SIGTERM, and whose watchdog does the same
+// when the script dies without its exit guard, for example by SIGKILL.
+// A line that a tool adapter logs goes to the trace of the script.
+
+import { trace } from "../trace.ts";
+import { ProcessSupervisor } from "./processes.ts";
+
+export interface LocalToolContext {
+  supervisor: ProcessSupervisor;
+  signal: AbortSignal;
+  log: (line: string) => void;
+}
+
+let shared: LocalToolContext | undefined;
+
+/** The script's one tool context; created on first use. */
+export function localToolContext(): LocalToolContext {
+  if (shared !== undefined) return shared;
+  const supervisor = new ProcessSupervisor();
+  // The watchdog also installs the exit guard.
+  supervisor.startWatchdog("skill-script");
+  const controller = new AbortController();
+  // A signal ends the script through process.exit, so the exit guard runs.
+  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143]] as const) {
+    process.once(signal, () => {
+      controller.abort();
+      process.exit(code);
+    });
+  }
+  shared = { supervisor, signal: controller.signal, log: (line) => trace().log(line) };
+  return shared;
+}

package/src/native/processes.ts

@@ -0,0 +1,350 @@
+import { spawn, spawnSync, type ChildProcess, type StdioOptions } from "node:child_process";
+import type { Writable } from "node:stream";
+import { mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+
+import { WireFailure } from "../protocol/messages.ts";
+
+/** How long a process group gets between SIGTERM and SIGKILL. */
+export const STOP_GRACE_MS = 5_000;
+/** How long to wait for the group to vanish after SIGKILL before giving up. */
+const KILL_WAIT_MS = 2_000;
+const POLL_MS = 25;
+
+export interface SpawnOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv | undefined;
+  stdio?: StdioOptions;
+}
+
+export interface ExitStatus {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  /** The error code, for example ENOENT, when the program did not start. */
+  spawnError?: string;
+}
+
+/** A child started in its own process group. Stopping it stops every descendant in that group. */
+export interface SupervisedProcess {
+  readonly pid: number;
+  readonly child: ChildProcess;
+  /** Settles when the group leader exits, for any reason. */
+  readonly exited: Promise<ExitStatus>;
+  /** Terminates the whole process group: SIGTERM, then SIGKILL after the grace period. */
+  stop(): Promise<void>;
+}
+
+/**
+ * A process's state letter and process group on Linux, from /proc; undefined
+ * when it is gone. A zombie (Z) or a dead process (X) has exited: only the
+ * wait of its parent is missing. In a container whose PID 1 never reaps (for
+ * example `tail -f /dev/null`), an orphan stays a zombie for ever.
+ */
+function linuxProcess(pid: number | string): { state: string; group: number } | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const [state, , group] = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return state === undefined ? undefined : { state, group: Number(group) };
+  } catch {
+    return undefined;
+  }
+}
+
+const exitedState = (state: string) => state === "Z" || state === "X";
+
+/** True while a process runs, also one this process may not signal (EPERM). A zombie does not run. */
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
+  }
+  if (process.platform !== "linux") return true;
+  const found = linuxProcess(pid);
+  return found !== undefined && !exitedState(found.state);
+}
+
+/** Linux: true while a member of the process group runs; zombies do not count. */
+function groupRuns(pgid: number): boolean {
+  for (const entry of readdirSync("/proc")) {
+    if (!/^\d+$/.test(entry)) continue;
+    const found = linuxProcess(entry);
+    if (found !== undefined && found.group === pgid && !exitedState(found.state)) return true;
+  }
+  return false;
+}
+
+/**
+ * Quotes one argument as the Microsoft C runtime and Java read it:
+ * backslashes before a quote and at the end are doubled, and an inner quote
+ * is escaped. A path that ends in a backslash then cannot swallow the
+ * arguments after it.
+ */
+export function windowsQuote(arg: string): string {
+  return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+}
+
+/**
+ * On Windows a .bat or .cmd file (Ghidra's analyzeHeadless.bat, for example)
+ * starts only through cmd.exe: Node refuses it without a shell (EINVAL). /s
+ * keeps the quoted command line as it is. Undefined for any other program.
+ */
+export function batchInvocation(argv: readonly string[], comSpec = "cmd.exe"): { command: string; args: string[] } | undefined {
+  if (!/\.(bat|cmd)$/i.test(argv[0] ?? "")) return undefined;
+  const quote = windowsQuote;
+  return { command: comSpec, args: ["/d", "/s", "/c", `"${argv.map(quote).join(" ")}"`] };
+}
+
+/** How long taskkill may block: it runs synchronously, so without a limit it could stop this whole process. */
+const TASKKILL_LIMIT_MS = 5_000;
+
+/**
+ * Ends a process and every descendant on Windows, which has no process
+ * groups. taskkill finds the descendants through the process, so it must run
+ * while the process still runs. Returns undefined when taskkill ended the tree
+ * or found no such process, else why it failed.
+ */
+export function killTree(pid: number): string | undefined {
+  const result = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: TASKKILL_LIMIT_MS });
+  if (result.error !== undefined) return `taskkill did not run (${(result.error as NodeJS.ErrnoException).code ?? result.error.message})`;
+  // taskkill exits with 128 when no process has this pid: the process has ended.
+  if (result.status === 0 || result.status === 128) return undefined;
+  return `taskkill ended with exit code ${result.status ?? result.signal}`;
+}
+
+/** True when Node has seen the child's exit. */
+const hasExited = (child: ChildProcess) => child.exitCode !== null || child.signalCode !== null;
+
+/** Sends a signal to a process group (POSIX). Returns false when the group does not exist. */
+export function signalGroup(pgid: number, signal: NodeJS.Signals | 0): boolean {
+  try {
+    process.kill(-pgid, signal);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // macOS answers EPERM for a group whose members are all zombies, which is a stopped group too.
+    if (code === "ESRCH" || (code === "EPERM" && process.platform === "darwin")) return false;
+    throw error;
+  }
+}
+
+/** True while a process group has a running member (POSIX); a group of zombies has ended. */
+export function isGroupRunning(pgid: number): boolean {
+  return signalGroup(pgid, 0) && (process.platform !== "linux" || groupRuns(pgid));
+}
+
+async function waitForGroupGone(pgid: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (isGroupRunning(pgid)) {
+    if (Date.now() >= deadline) return false;
+    await sleep(POLL_MS);
+  }
+  return true;
+}
+
+/** What the watchdog must clean up if the Host Runtime dies: process groups and paths. */
+export interface Registry {
+  groups: number[];
+  paths: string[];
+}
+
+/** The watchdog's program, next to this module. A new URL literal, so an installed skill gets it too. */
+const WATCHDOG = fileURLToPath(new URL("./watchdog.ts", import.meta.url));
+
+/**
+ * The one child-process supervisor of a process: the Host Runtime, or a
+ * skill script that runs its own tools. Every emulator and native tool
+ * is started here, with an argv array and never a shell string,
+ * as the leader of its own process group. It also owns scratch paths, so
+ * that they go away with the processes that used them.
+ */
+export class ProcessSupervisor {
+  readonly #children = new Set<SupervisedProcess>();
+  readonly #paths = new Set<string>();
+  readonly #graceMs: number;
+  #exitGuardInstalled = false;
+  /** The registry file that the watchdog reads, once a watchdog runs. */
+  #registry: string | undefined;
+  #watchdogPid: number | undefined;
+  /** The writing end of the watchdog's pipe. Kept open until this process ends: its end tells the watchdog that this process is gone. */
+  #watchdogPipe: Writable | undefined;
+
+  constructor(options: { graceMs?: number } = {}) {
+    this.#graceMs = options.graceMs ?? STOP_GRACE_MS;
+  }
+
+  /** Number of process groups that have not been stopped yet. */
+  get size(): number {
+    return this.#children.size;
+  }
+
+  /** The process id of the watchdog, once a watchdog runs. */
+  get watchdogPid(): number | undefined {
+    return this.#watchdogPid;
+  }
+
+  /** Starts argv[0] with argv[1..] as the leader of a new process group. */
+  spawn(argv: readonly string[], options: SpawnOptions = {}): SupervisedProcess {
+    const program = argv[0];
+    if (program === undefined) throw new TypeError("argv must name a command");
+    const batch = process.platform === "win32" ? batchInvocation(argv, process.env.ComSpec) : undefined;
+    const { command, args } = batch ?? { command: program, args: argv.slice(1) };
+    let child: ChildProcess;
+    try {
+      child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: options.stdio ?? "ignore",
+        detached: process.platform !== "win32",
+        windowsHide: true,
+        ...(batch === undefined ? {} : { windowsVerbatimArguments: true }),
+      });
+    } catch (error) {
+      // Some failures throw at once instead of an "error" event: a file Windows cannot start
+      // (EFTYPE, for example a broken build) or a .bat without a shell (EINVAL).
+      const code = (error as NodeJS.ErrnoException).code ?? "an unknown error";
+      throw new WireFailure("installation-incomplete", `${program} is not a program that this system can start (${code}). Install it again.`);
+    }
+    const exited = new Promise<ExitStatus>((resolve) => {
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+      // A failed spawn emits "error" and never "exit". A later "error" (a failed kill) changes nothing:
+      // the listener stays, so that such an error does not end this process.
+      child.on("error", (error: NodeJS.ErrnoException) => {
+        if (child.pid === undefined) resolve({ code: null, signal: null, spawnError: error.code ?? "an unknown error" });
+      });
+    });
+    if (child.pid === undefined) {
+      // Spawn failed (for example ENOENT); "error" follows asynchronously.
+      const failed: SupervisedProcess = { pid: -1, child, exited, stop: async () => {} };
+      return failed;
+    }
+
+    const pid = child.pid;
+    let stopping: Promise<void> | undefined;
+    const supervised: SupervisedProcess = {
+      pid,
+      child,
+      exited,
+      stop: () => {
+        stopping ??= this.#stopGroup(pid, child, exited).then(
+          () => {
+            this.#children.delete(supervised);
+            this.#writeRegistry();
+          },
+          (error: unknown) => {
+            // The group may still run: it stays registered for the exit guard and the watchdog, and a later stop tries again.
+            stopping = undefined;
+            throw error;
+          },
+        );
+        return stopping;
+      },
+    };
+    this.#children.add(supervised);
+    this.#writeRegistry();
+    return supervised;
+  }
+
+  /** Makes a scratch path part of what this supervisor cleans up. Returns the release for a normal removal. */
+  ownPath(path: string): () => void {
+    this.#paths.add(path);
+    this.#writeRegistry();
+    return () => {
+      this.#paths.delete(path);
+      this.#writeRegistry();
+    };
+  }
+
+  /**
+   * Starts a watchdog process that cleans up if this process dies without
+   * running its exit guard, for example by SIGKILL: it stops every
+   * registered process group and removes every owned path. It ends by itself
+   * when this process exits normally. Its registry directory names the owner.
+   */
+  startWatchdog(owner: "host" | "skill-script"): void {
+    if (this.#registry !== undefined) return;
+    const directory = mkdtempSync(join(tmpdir(), `c64-re-tools-${owner}-watchdog-`));
+    this.#registry = join(directory, "registry.json");
+    this.#writeRegistry();
+    // The watchdog runs in the temporary directory, never in the caller's directory: Windows refuses
+    // to remove a directory that a running process uses. Its standard input is a pipe from this
+    // process, which the system closes when this process ends.
+    const watchdog = spawn(process.execPath, [...process.execArgv, WATCHDOG, String(process.pid), this.#registry], { cwd: tmpdir(), detached: true, stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+    watchdog.unref();
+    // The pipe does not keep this process running, and an error on it does not end this process.
+    const pipe = watchdog.stdin as (Writable & { unref?: () => void }) | null;
+    pipe?.on("error", () => {});
+    pipe?.unref?.();
+    this.#watchdogPipe = pipe ?? undefined;
+    this.#watchdogPid = watchdog.pid;
+    this.installExitGuard();
+  }
+
+  #writeRegistry(): void {
+    if (this.#registry === undefined) return;
+    const registry: Registry = { groups: [...this.#children].map((child) => child.pid), paths: [...this.#paths] };
+    // Write and rename, so the watchdog never reads half a file.
+    writeFileSync(`${this.#registry}.next`, JSON.stringify(registry));
+    renameSync(`${this.#registry}.next`, this.#registry);
+  }
+
+  /** Stops every process group this supervisor started. */
+  async stopAll(): Promise<void> {
+    await Promise.all([...this.#children].map((child) => child.stop()));
+  }
+
+  /**
+   * SIGKILLs every remaining group and removes every owned path, synchronously.
+   * For process "exit", where nothing async runs. The watchdog then ends.
+   */
+  killAllSync(): void {
+    for (const supervised of this.#children) {
+      // On Windows the pid of an ended leader can belong to another process now.
+      if (process.platform === "win32") {
+        if (!hasExited(supervised.child)) killTree(supervised.pid);
+      } else signalGroup(supervised.pid, "SIGKILL");
+    }
+    this.#children.clear();
+    for (const path of this.#paths) rmSync(path, { recursive: true, force: true });
+    this.#paths.clear();
+    if (this.#registry !== undefined) rmSync(join(this.#registry, ".."), { recursive: true, force: true });
+  }
+
+  /** Makes any exit of this process, however it happens, SIGKILL the remaining groups. Idempotent. */
+  installExitGuard(): void {
+    if (this.#exitGuardInstalled) return;
+    this.#exitGuardInstalled = true;
+    process.on("exit", () => this.killAllSync());
+  }
+
+  async #stopGroup(pid: number, child: ChildProcess, exited: Promise<ExitStatus>): Promise<void> {
+    if (process.platform === "win32") {
+      // Windows has no SIGTERM for a console process. taskkill finds the descendants through the
+      // leader, so it runs first, and only while the leader runs: the pid of an ended leader can
+      // belong to another process. child.kill then ends the leader through its own handle: after
+      // taskkill alone, Node does not always report the leader's exit. The exit wait has a limit.
+      const failure = hasExited(child) ? undefined : killTree(pid);
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // The leader has ended already.
+      }
+      await Promise.race([exited, sleep(this.#graceMs)]);
+      if (!hasExited(child)) throw new Error(`process ${pid} did not end${failure === undefined ? "" : `: ${failure}`}`);
+      return;
+    }
+    // The group outlives its leader when descendants remain, so wait on the group, not the leader.
+    if (signalGroup(pid, "SIGTERM") && !(await waitForGroupGone(pid, this.#graceMs))) {
+      signalGroup(pid, "SIGKILL");
+      if (!(await waitForGroupGone(pid, KILL_WAIT_MS))) {
+        throw new Error(`process group ${pid} survived SIGKILL`);
+      }
+    }
+    // A group of zombies counts as gone before Node reaps the leader and reports its exit;
+    // stopped means that Node has seen that exit.
+    await Promise.race([exited, sleep(KILL_WAIT_MS)]);
+  }
+}