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

package/src/native/run.ts

@@ -0,0 +1,172 @@
+// Bounded native-tool execution: argv only, no shell, a fixed
+// timeout, capped output, and the whole process group stopped on timeout or abort.
+
+import { realpathSync } from "node:fs";
+import { sep } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { elapsedMs, trace } from "../trace.ts";
+import type { ProcessSupervisor } from "./processes.ts";
+
+export const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+export const DEFAULT_OUTPUT_LIMIT = 1024 * 1024;
+
+/** What running a native tool needs from its caller: the supervisor that owns it, the request's abort signal, and optionally its environment and a log. */
+export interface ToolContext {
+  supervisor: ProcessSupervisor;
+  signal: AbortSignal;
+  env?: NodeJS.ProcessEnv | undefined;
+  log?: ((line: string) => void) | undefined;
+}
+
+export interface ToolRun {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  aborted: boolean;
+  /** True when output beyond the limit was dropped. */
+  truncated: boolean;
+  /** The error code, for example ENOENT, when the program did not start. */
+  spawnError?: string;
+}
+
+const TAIL_LINES = 20;
+const TAIL_CHARS = 2_000;
+const TRACE_TAIL_LINES = 40;
+
+/** The last lines of a tool's output, without empty ones, for the trace. */
+function lastLines(text: string): string {
+  return text
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== "")
+    .slice(-TRACE_TAIL_LINES)
+    .join("\n");
+}
+
+/**
+ * The last lines that a tool printed, for a refusal: empty lines and lines
+ * that do not match `only` are left out, and so is the workspace root in a
+ * path. At most 20 lines and 2000 characters. Empty when nothing is left.
+ */
+export function outputTail(tool: string, run: Pick<ToolRun, "stdout" | "stderr">, root: string, only?: RegExp): string {
+  const roots = new Set([root]);
+  try {
+    roots.add(realpathSync(root));
+  } catch {
+    // The workspace is gone: only the root as given is left out.
+  }
+  const variants = [...roots].flatMap((path) => [path, path.split(sep).join("/")]).sort((a, b) => b.length - a.length);
+  const withoutRoot = (line: string) => variants.reduce((text, path) => text.split(`${path}${sep}`).join("").split(`${path}/`).join("").split(path).join("."), line);
+  const lines = `${run.stdout}\n${run.stderr}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && (only === undefined || only.test(line)))
+    .slice(-TAIL_LINES)
+    .map(withoutRoot);
+  while (lines.length > 1 && lines.join("\n").length > TAIL_CHARS) lines.shift();
+  const first = lines[0];
+  if (first === undefined) return "";
+  lines[0] = first.slice(-TAIL_CHARS);
+  return `\nThe last output of ${tool}:\n  ${lines.join("\n  ")}`;
+}
+
+/** Spawn errors that mean the file is not a program that this system can start. */
+const NOT_A_PROGRAM = new Set(["ENOENT", "EACCES", "ENOEXEC", "EFTYPE", "EINVAL", "EPERM", "ENOTDIR"]);
+
+export async function runTool(options: {
+  argv: string[];
+  cwd: string;
+  supervisor: ProcessSupervisor;
+  signal: AbortSignal;
+  timeoutMs?: number;
+  outputLimit?: number;
+  env?: NodeJS.ProcessEnv | undefined;
+}): Promise<ToolRun> {
+  const limit = options.outputLimit ?? DEFAULT_OUTPUT_LIMIT;
+  const started = performance.now();
+  const child = options.supervisor.spawn(options.argv, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+  // "exit" can come before the output streams finish; "close" comes after both.
+  const closed = new Promise<void>((resolve) => {
+    if (child.pid < 0) resolve();
+    else child.child.once("close", () => resolve());
+  });
+  const output = { stdout: "", stderr: "", truncated: false };
+  // The limit counts bytes. A decoder per stream keeps a character whose bytes arrive in two chunks whole.
+  let bytes = 0;
+  const decoders = { stdout: new StringDecoder("utf8"), stderr: new StringDecoder("utf8") };
+  const collect = (stream: "stdout" | "stderr") => (chunk: Buffer) => {
+    const room = limit - bytes;
+    if (chunk.length > room) output.truncated = true;
+    if (room <= 0) return;
+    const kept = chunk.subarray(0, room);
+    bytes += kept.length;
+    output[stream] += decoders[stream].write(kept);
+  };
+  child.child.stdout?.on("data", collect("stdout"));
+  child.child.stderr?.on("data", collect("stderr"));
+
+  let timedOut = false;
+  let aborted = false;
+  // A failed stop here is not lost: the stop after the exit below tries again and rejects the run.
+  const stopQuietly = () => {
+    void child.stop().catch(() => {});
+    // A process outside the group can hold the output pipes open: the run does not wait for it.
+    child.child.stdout?.destroy();
+    child.child.stderr?.destroy();
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    stopQuietly();
+  }, options.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS);
+  const onAbort = () => {
+    aborted = true;
+    stopQuietly();
+  };
+  if (options.signal.aborted) onAbort();
+  else options.signal.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    const status = await child.exited;
+    // A tool that exited may have left descendants in its group, and they can hold its output
+    // pipes open: stop them before the wait for the end of the output.
+    await child.stop();
+    await closed;
+    output.stdout += decoders.stdout.end();
+    output.stderr += decoders.stderr.end();
+    trace().event("tool.run", { argv: options.argv, cwd: options.cwd, pid: child.pid, ms: elapsedMs(started), ...status, timedOut, aborted, truncated: output.truncated, stdout: lastLines(output.stdout), stderr: lastLines(output.stderr) });
+    return { ...status, ...output, timedOut, aborted };
+  } finally {
+    clearTimeout(timer);
+    options.signal.removeEventListener("abort", onAbort);
+  }
+}
+
+/**
+ * Runs one task of a named tool and turns a cancelled or timed-out run, a
+ * program that did not start and a stop by a signal into a WireFailure. With
+ * `truncated`, output beyond the limit is refused with that message too. Any
+ * exit code is returned to the caller. `root` (the default is `cwd`) is left
+ * out of the tool output that a refusal quotes.
+ */
+export async function runToolOrFail(
+  tool: string,
+  task: string,
+  options: { argv: string[]; cwd: string; timeoutMs: number; outputLimit?: number; truncated?: string; root?: string },
+  context: ToolContext,
+): Promise<ToolRun> {
+  const { truncated, root, ...runOptions } = options;
+  const run = await runTool({ ...runOptions, supervisor: context.supervisor, signal: context.signal, env: context.env });
+  if (run.aborted) throw new WireFailure("operation-failed", `${task} was cancelled.`);
+  if (run.timedOut) throw new WireFailure("operation-failed", `${tool} did not finish within ${options.timeoutMs / 1000} seconds.`);
+  if (run.spawnError !== undefined) {
+    if (NOT_A_PROGRAM.has(run.spawnError)) throw new WireFailure("installation-incomplete", `${tool} is not a program that this system can start (${run.spawnError}). Install it again.`);
+    throw new WireFailure("operation-failed", `${tool} did not start (${run.spawnError}).`);
+  }
+  // A tool that a signal stopped has crashed: that is not a result of the task.
+  if (run.signal !== null) throw new WireFailure("operation-failed", `${tool} stopped on the signal ${run.signal}.${outputTail(tool, run, root ?? options.cwd)}`);
+  if (run.truncated && truncated !== undefined) throw new WireFailure("operation-failed", truncated);
+  return run;
+}

package/src/native/staging.ts

@@ -0,0 +1,83 @@
+// Request-owned temporary workspaces. Everything staged lives
+// outside the user's project and is removed when the request ends.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { isRelativePath, type SourceTree } from "../protocol/tools.ts";
+import type { ProcessSupervisor } from "./processes.ts";
+
+/** How often a removal tries again when a file is busy, for example one that Windows still holds open. */
+const REMOVE_RETRIES = 5;
+
+export class Workspace {
+  readonly root: string;
+  /** The owner's release, when a supervisor owns the workspace. */
+  readonly #release: (() => void) | undefined;
+
+  private constructor(root: string, release: (() => void) | undefined) {
+    this.root = root;
+    this.#release = release;
+  }
+
+  /**
+   * A fresh, empty workspace in the temporary directory. With a supervisor,
+   * the workspace is also removed if its process dies.
+   */
+  static create(owner?: Pick<ProcessSupervisor, "ownPath">, prefix = "c64-re-tools-request-"): Workspace {
+    const root = mkdtempSync(join(tmpdir(), prefix));
+    return new Workspace(root, owner?.ownPath(root));
+  }
+
+  /** The absolute path of a relative path inside the workspace; refuses any escape. */
+  path(path: string): string {
+    if (!isRelativePath(path)) throw new WireFailure("invalid-input", `${path} is not a relative path inside the workspace.`);
+    const full = resolve(this.root, path);
+    const fromRoot = relative(this.root, full);
+    if (fromRoot.startsWith(`..${sep}`) || fromRoot === ".." || isAbsolute(fromRoot)) {
+      throw new WireFailure("invalid-input", `${path} leaves the workspace.`);
+    }
+    return full;
+  }
+
+  /** Writes a transferred tree under `directory` as ordinary files. Returns the directory's absolute path. */
+  materialize(directory: string, files: SourceTree, contents: readonly Uint8Array[]): string {
+    const base = this.path(directory);
+    mkdirSync(base, { recursive: true });
+    files.forEach((file, index) => {
+      const content = contents[index];
+      if (content === undefined) throw new WireFailure("invalid-input", `The request gives no bytes for ${file.path}.`);
+      const target = this.path(`${directory}/${file.path}`);
+      mkdirSync(dirname(target), { recursive: true });
+      // wx: never write through a file or link that is already there.
+      writeFileSync(target, content, { flag: "wx" });
+    });
+    return base;
+  }
+
+  /** A directory inside the workspace, created empty. */
+  directory(path: string): string {
+    const full = this.path(path);
+    rmSync(full, { recursive: true, force: true });
+    mkdirSync(full, { recursive: true });
+    return full;
+  }
+
+  /**
+   * Removes the workspace. An owned workspace that cannot be removed stays
+   * owned, and its supervisor removes it when its process ends: the error is
+   * not thrown, so that it cannot replace the failure of the request that
+   * used the workspace. Without an owner the error is thrown.
+   */
+  remove(): void {
+    try {
+      rmSync(this.root, { recursive: true, force: true, maxRetries: REMOVE_RETRIES });
+    } catch (error) {
+      if (this.#release === undefined) throw error;
+      return;
+    }
+    this.#release?.();
+  }
+}

package/src/native/status.ts

@@ -0,0 +1,101 @@
+// Tool status: finds each native tool the way its operations do and runs it
+// once with a version option, so a user can see in advance which tools work.
+// The Host Runtime reports VICE and its tools (host.status); the CLI reports
+// the tools that skill scripts run themselves (ACME, DXA, Ghidra).
+
+import { tmpdir } from "node:os";
+import { stripVTControlCharacters } from "node:util";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { type ToolStatus } from "../protocol/tools.ts";
+import { ACME, DXA, findTool } from "./discover.ts";
+import { findGhidra, ghidraVersion } from "./ghidra/index.ts";
+import { runTool, type ToolContext } from "./run.ts";
+import { Workspace } from "./staging.ts";
+
+const PROBE_TIMEOUT_MS = 20_000;
+
+export interface Probe {
+  name: string;
+  /** The executable; throws WireFailure(installation-incomplete) when missing. */
+  find: (env: NodeJS.ProcessEnv) => string;
+  args: string[];
+  /** The version line; no such line means the tool did not run correctly. */
+  pattern: RegExp;
+}
+
+/** dxa's version line, also as "D:\\tools\\dxa.exe v0.1.5 -- symbolic 65xx disassembler" on Windows. */
+export const DXA_VERSION = /^(?:.*[\\/])?dxa(?:\.exe)? v\d/i;
+
+/** The first output line that matches, without terminal color codes (c1541 colors an OpenCBM notice). */
+export function versionLine(output: string, pattern: RegExp): string | undefined {
+  return stripVTControlCharacters(output)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => pattern.test(line));
+}
+
+async function run(name: string, path: string, args: string[], version: (output: string) => string | undefined, context: ToolContext): Promise<ToolStatus> {
+  const result = await runTool({ argv: [path, ...args], cwd: tmpdir(), supervisor: context.supervisor, signal: context.signal, timeoutMs: PROBE_TIMEOUT_MS, env: context.env });
+  const found = version(`${result.stdout}\n${result.stderr}`);
+  if (found !== undefined) return { name, found: true, path, version: found, runs: true };
+  const problem = result.timedOut ? "It did not answer in time." : result.spawnError !== undefined ? `It did not start (${result.spawnError}).` : `It did not run correctly (exit ${result.code ?? result.signal}).`;
+  return { name, found: true, path, runs: false, problem };
+}
+
+function missing(name: string, error: unknown): ToolStatus {
+  if (!(error instanceof WireFailure)) throw error;
+  return { name, found: false, runs: false, problem: error.message };
+}
+
+/** Finds and runs each probed tool once. */
+export function probeTools(probes: Probe[], context: ToolContext): Promise<ToolStatus[]> {
+  const env = context.env ?? process.env;
+  return Promise.all(
+    probes.map(async (probe) => {
+      let path: string;
+      try {
+        path = probe.find(env);
+      } catch (error) {
+        return missing(probe.name, error);
+      }
+      return run(probe.name, path, probe.args, (output) => versionLine(output, probe.pattern), context);
+    }),
+  );
+}
+
+/** Ghidra: without arguments analyzeHeadless starts Java and prints its usage, which proves that it runs. */
+export async function probeGhidra(context: ToolContext): Promise<ToolStatus> {
+  const env = context.env ?? process.env;
+  try {
+    const ghidra = findGhidra(env);
+    // Its own settings directory keeps the user's Ghidra settings and logs untouched.
+    const workspace = Workspace.create(context.supervisor, "c64-re-tools-ghidra-status-");
+    const settings = workspace.root;
+    try {
+      const status = await run(
+        "Ghidra",
+        ghidra.analyzeHeadless,
+        [],
+        (output) => (/Headless Analyzer Usage/.test(output) ? ghidraVersion(ghidra) : undefined),
+        { ...context, env: { ...env, XDG_CONFIG_HOME: settings, XDG_CACHE_HOME: settings } },
+      );
+      return { ...status, path: ghidra.root };
+    } finally {
+      workspace.remove();
+    }
+  } catch (error) {
+    return missing("Ghidra", error);
+  }
+}
+
+/** The tools that skill scripts run themselves, on this machine. */
+export async function localToolStatus(context: ToolContext): Promise<ToolStatus[]> {
+  const probes: Probe[] = [
+    { name: "ACME", find: (env) => findTool(ACME, env), args: ["--version"], pattern: /^This is ACME, release / },
+    // dxa -V prints its version and exits with status 1. It names itself by argv[0], without the
+    // directory only where that uses "/": on Windows the line starts with the full path.
+    { name: "dxa", find: (env) => findTool(DXA, env), args: ["-V"], pattern: DXA_VERSION },
+  ];
+  return [...(await probeTools(probes, context)), await probeGhidra(context)];
+}

package/src/native/types.ts

@@ -0,0 +1,228 @@
+// Types of the native tools that skill scripts run directly (ACME, DXA,
+// Ghidra), and the checks of their complete results. The skill script runs
+// these tools itself: nothing here crosses the Host Runtime wire. Bytes
+// (a program, an image, a listing) go next to these values as attachments.
+
+import { prgRange, REFERENCE_KINDS, SYMBOL_NAME, type ReferenceKind } from "../c64.ts";
+import { isInteger, isObject, isOneOf, WireFailure } from "../protocol/messages.ts";
+import { type SourceTree } from "../protocol/tools.ts";
+
+export interface Diagnostic {
+  severity: "error" | "warning" | "note";
+  /** Relative to the source root; absent when the message has no source location. */
+  file?: string;
+  line?: number;
+  message: string;
+}
+
+export interface AcmeParams {
+  files: SourceTree;
+  /** Relative to the source root. */
+  entrySource: string;
+  /** Directories relative to the source root. */
+  includeDirs: string[];
+  defines: Record<string, number | boolean>;
+  setPc?: number;
+}
+
+/** A symbol from the assembly: an address inside the program, or a constant value. */
+export type AssembledSymbol = { name: string; kind: "address"; address: number; used: boolean } | { name: string; kind: "constant"; value: number; used: boolean };
+
+export interface AcmeResult {
+  assembled: boolean;
+  /** Present when assembled: where the program loads. The program bytes are the one attachment that assemble returns. */
+  loadRange?: { start: number; end: number; bytes: number };
+  symbols?: AssembledSymbol[];
+  diagnostics: Diagnostic[];
+}
+
+export const IMAGE_KINDS = ["prg", "flat64k"] as const;
+export type ImageKind = (typeof IMAGE_KINDS)[number];
+
+export const GHIDRA_LIMITS = { entryPoints: 1024, dataRanges: 1024, labels: 4096, decompile: 32, decompiledChars: 16_000, decompiledTotalChars: 128_000 } as const;
+
+/** The Ghidra analysis. Its image is given next to these fields: a PRG, or 64 KiB from $0000. */
+export interface GhidraParams {
+  imageKind: ImageKind;
+  /** Seeds from current knowledge. */
+  entryPoints: number[];
+  dataRanges: Array<{ start: number; end: number }>;
+  labels: Array<{ address: number; name: string }>;
+  /** Routine entries to decompile for immediate reasoning; the text is never stored. */
+  decompile: number[];
+}
+
+export interface GhidraResult {
+  coverage: Array<{ start: number; end: number }>;
+  functions: Array<{ entry: number; name: string; nameSource: "seed" | "generated" | "native" }>;
+  regions: Array<{ start: number; end: number; classification: "code" | "data" }>;
+  references: Array<{ from: number; to: number; type: ReferenceKind }>;
+  decompilations: Array<{ entry: number; text: string; truncated: boolean }>;
+  /** Requested routines without decompiled code, with the decompiler's reason. */
+  notDecompiled?: Array<{ entry: number; reason: string }>;
+  /** Which categories are complete inside the coverage; private to the importer. */
+  completeness: { functions: boolean; regions: boolean; references: boolean };
+  /** The version of the Ghidra that made the result, for example "Ghidra 12.1.3". */
+  toolVersion?: string;
+}
+
+/** Refuses a DXA or Ghidra request with more seeds or decompilations than the request bounds allow, by name. */
+export function checkRequestBounds(params: DxaParams & { decompile?: number[] }): void {
+  const bounds = [
+    ["entry points", params.entryPoints.length, GHIDRA_LIMITS.entryPoints],
+    ["data ranges", params.dataRanges.length, GHIDRA_LIMITS.dataRanges],
+    ["labels", params.labels.length, GHIDRA_LIMITS.labels],
+    ["routines to decompile", params.decompile?.length ?? 0, GHIDRA_LIMITS.decompile],
+  ] as const;
+  for (const [name, count, limit] of bounds) {
+    if (count > limit) throw new WireFailure("invalid-input", `The request has ${count} ${name}. Give at most ${limit} ${name}.`);
+  }
+}
+
+/** The DXA analysis: the same image and seeds as Ghidra, without decompilation. */
+export type DxaParams = Omit<GhidraParams, "decompile">;
+
+export interface DxaResult {
+  coverage: Array<{ start: number; end: number }>;
+  regions: Array<{ start: number; end: number; classification: "code" | "data" }>;
+  labels: Array<{ address: number; name: string }>;
+  /** The size of the listing, which is the one attachment that analyze returns (UTF-8 text). */
+  listingBytes: number;
+  /** Which categories are complete inside the coverage; private to the importer. */
+  completeness: { regions: boolean; labels: boolean };
+  /** The version line of the dxa that made the result; absent when dxa prints none. */
+  toolVersion?: string;
+}
+
+/** The longest tool version that a result can carry. */
+const MAX_TOOL_VERSION = 200;
+
+/** True for a tool version that a result can carry: absent, or one line of text without control characters, at most MAX_TOOL_VERSION characters. */
+const isToolVersion = (value: unknown) => value === undefined || (typeof value === "string" && value.length <= MAX_TOOL_VERSION && /^[^\p{Cc}]+$/u.test(value));
+
+/** Ends a result check with the Error that names its first problem. */
+function fail(message: string): never {
+  throw new Error(message);
+}
+
+/** Narrows to a list whose items are still unchecked. */
+const isList = (value: unknown): value is unknown[] => Array.isArray(value);
+
+/**
+ * Checks a complete Ghidra result: every field typed and in range, every
+ * function, region and reference source inside the coverage, regions sorted
+ * and without overlap. Throws an Error naming the first problem.
+ */
+export function checkGhidraResult(value: unknown): GhidraResult {
+  if (!isObject(value)) fail("not an object");
+  const { coverage, functions, regions, references, decompilations, notDecompiled, completeness, toolVersion } = value;
+  if (!isList(coverage) || coverage.length === 0) fail("no coverage");
+  const ranges: Array<{ start: number; end: number }> = [];
+  for (const range of coverage) {
+    if (!isObject(range) || !isInteger(range.start, 0, 0xffff) || !isInteger(range.end, range.start, 0xffff)) fail("bad coverage range");
+    ranges.push({ start: range.start, end: range.end });
+  }
+  const covered = (address: number) => ranges.some((range) => range.start <= address && address <= range.end);
+  if (!isList(functions)) fail("no functions");
+  for (const fn of functions) {
+    if (!isObject(fn) || !isInteger(fn.entry, 0, 0xffff) || typeof fn.name !== "string" || !SYMBOL_NAME.test(fn.name) || !isOneOf(["seed", "generated", "native"] as const, fn.nameSource)) fail("bad function");
+    if (!covered(fn.entry)) fail("a function lies outside the coverage");
+  }
+  if (!isList(regions)) fail("no regions");
+  let previousEnd = -1;
+  for (const region of regions) {
+    if (!isObject(region) || !isInteger(region.start, 0, 0xffff) || !isInteger(region.end, region.start, 0xffff) || (region.classification !== "code" && region.classification !== "data")) fail("bad region");
+    const start = region.start;
+    const end = region.end;
+    if (start <= previousEnd) fail("regions overlap or are out of order");
+    if (!ranges.some((range) => range.start <= start && end <= range.end)) fail("a region lies outside the coverage");
+    previousEnd = end;
+  }
+  if (!isList(references)) fail("no references");
+  for (const reference of references) {
+    if (!isObject(reference) || !isInteger(reference.from, 0, 0xffff) || !isInteger(reference.to, 0, 0xffff) || !isOneOf(REFERENCE_KINDS, reference.type)) fail("bad reference");
+    if (!covered(reference.from)) fail("a reference source lies outside the coverage");
+  }
+  if (!isList(decompilations) || decompilations.length > GHIDRA_LIMITS.decompile) fail("bad decompilations");
+  let total = 0;
+  for (const item of decompilations) {
+    if (!isObject(item) || !isInteger(item.entry, 0, 0xffff) || typeof item.text !== "string" || typeof item.truncated !== "boolean") fail("bad decompilation");
+    if (item.text.length > GHIDRA_LIMITS.decompiledChars) fail("a decompilation is too long");
+    total += item.text.length;
+  }
+  if (total > GHIDRA_LIMITS.decompiledTotalChars) fail("the decompilations are too long together");
+  if (notDecompiled !== undefined) {
+    if (!isList(notDecompiled) || notDecompiled.length > GHIDRA_LIMITS.decompile) fail("bad list of routines that were not decompiled");
+    for (const item of notDecompiled) {
+      if (!isObject(item) || !isInteger(item.entry, 0, 0xffff) || typeof item.reason !== "string" || item.reason.length > 1000) fail("bad routine that was not decompiled");
+    }
+  }
+  if (!isObject(completeness) || typeof completeness.functions !== "boolean" || typeof completeness.regions !== "boolean" || typeof completeness.references !== "boolean") fail("no completeness");
+  if (!isToolVersion(toolVersion)) fail("bad tool version");
+  // Every field is checked: the object is the result as it is.
+  return value as unknown as GhidraResult;
+}
+
+/**
+ * Checks a complete DXA result: typed fields, regions in order, without
+ * overlap and covering the coverage exactly, labels inside the coverage, and
+ * the listing as the one attachment. Throws an Error naming the first problem.
+ */
+export function checkDxaResult(value: unknown, attachments: readonly Uint8Array[]): DxaResult {
+  if (!isObject(value)) fail("not an object");
+  const { coverage, regions, labels, listingBytes, completeness, toolVersion } = value;
+  if (!isList(coverage) || coverage.length !== 1) fail("the coverage is not one range");
+  const range = coverage[0];
+  if (!isObject(range) || !isInteger(range.start, 0, 0xffff) || !isInteger(range.end, range.start, 0xffff)) fail("bad coverage range");
+  const start = range.start;
+  const end = range.end;
+  if (!isList(regions)) fail("no regions");
+  let next = start;
+  for (const region of regions) {
+    if (!isObject(region) || !isInteger(region.start, 0, 0xffff) || !isInteger(region.end, region.start, 0xffff) || (region.classification !== "code" && region.classification !== "data")) fail("bad region");
+    if (region.start !== next) fail("the regions leave a gap or overlap");
+    next = region.end + 1;
+  }
+  if (next !== end + 1) fail("the regions do not reach the end of the coverage");
+  if (!isList(labels)) fail("no labels");
+  for (const label of labels) {
+    if (!isObject(label) || !isInteger(label.address, start, end) || typeof label.name !== "string" || !SYMBOL_NAME.test(label.name)) fail("bad label");
+  }
+  const [listing] = attachments;
+  if (attachments.length !== 1 || listing === undefined || listingBytes !== listing.length) fail("the listing is missing");
+  if (!isObject(completeness) || typeof completeness.regions !== "boolean" || typeof completeness.labels !== "boolean") fail("no completeness");
+  if (!isToolVersion(toolVersion)) fail("bad tool version");
+  // Every field is checked: the object is the result as it is.
+  return value as unknown as DxaResult;
+}
+
+/**
+ * The address range of an analyzer image: a PRG at its load address, or 64 KiB
+ * of memory from $0000. Throws WireFailure(invalid-input) for anything else.
+ */
+export function imageRange(kind: ImageKind, image: Uint8Array): { start: number; end: number; body: Uint8Array } {
+  if (kind === "flat64k") {
+    if (image.length !== 0x10000) throw new WireFailure("invalid-input", "A flat 64 KiB image has exactly 65536 bytes.");
+    return { start: 0, end: 0xffff, body: image };
+  }
+  try {
+    return prgRange(image);
+  } catch (error) {
+    if (!(error instanceof RangeError)) throw error;
+    throw new WireFailure("invalid-input", error.message);
+  }
+}
+
+/**
+ * The seeds that an analysis of [start, end] can use: the entry points inside
+ * it, and the data ranges cut to it. A data range that holds an entry point
+ * is left out, so that the entry point is disassembled.
+ */
+export function seedsInside(params: Pick<DxaParams, "entryPoints" | "dataRanges">, start: number, end: number): Pick<DxaParams, "entryPoints" | "dataRanges"> {
+  const entryPoints = params.entryPoints.filter((address) => address >= start && address <= end);
+  const dataRanges = params.dataRanges
+    .filter((range) => range.end >= start && range.start <= end)
+    .map((range) => ({ start: Math.max(range.start, start), end: Math.min(range.end, end) }))
+    .filter((range) => !entryPoints.some((entry) => entry >= range.start && entry <= range.end));
+  return { entryPoints, dataRanges };
+}

package/src/native/watchdog.ts

@@ -0,0 +1,78 @@
+// The watchdog of a supervisor's process (the Host Runtime or a skill
+// script), started by ProcessSupervisor.startWatchdog.
+// Arguments: <owner pid> <registry file>. Standard input: a pipe whose
+// writing end only the owner holds.
+//
+// It runs in its own process group, so a signal to the owner's group does
+// not reach it. When the owner dies without its exit guard (SIGKILL, a
+// crash), it stops every process group in the registry and removes every
+// path. When the owner exits normally, the exit guard removes the registry
+// and the watchdog ends.
+//
+// The end of the pipe tells it at once that the owner is gone: the system
+// closes the owner's end when the owner ends, however it ends, and a pid that
+// another process now uses cannot keep the pipe open. A poll of the owner's
+// pid is the fallback for a pipe that does not end.
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { isAlive, killTree, signalGroup, type Registry } from "./processes.ts";
+
+const POLL_MS = 500;
+const GRACE_MS = 2_000;
+
+const [ownerPidText, registryArgument] = process.argv.slice(2);
+const ownerPid = Number(ownerPidText);
+if (!Number.isInteger(ownerPid) || ownerPid <= 0 || registryArgument === undefined) process.exit(2);
+const registryFile: string = registryArgument;
+
+function signal(group: number, name: NodeJS.Signals): void {
+  try {
+    if (process.platform !== "win32") signalGroup(group, name);
+    else if (name === "SIGKILL") killTree(group);
+  } catch {
+    // The group is gone already.
+  }
+}
+
+/** Removes a path. A path that cannot be removed does not stop the removal of the others; nothing reads the watchdog's output. */
+function remove(path: string): void {
+  try {
+    rmSync(path, { recursive: true, force: true });
+  } catch {
+    // The path stays.
+  }
+}
+
+let cleaning = false;
+
+function cleanUp(): void {
+  if (cleaning) return;
+  cleaning = true;
+  clearInterval(timer);
+  let registry: Registry;
+  try {
+    registry = JSON.parse(readFileSync(registryFile, "utf8")) as Registry;
+  } catch {
+    process.exit(0);
+  }
+  for (const group of registry.groups) signal(group, "SIGTERM");
+  setTimeout(() => {
+    for (const group of registry.groups) signal(group, "SIGKILL");
+    for (const path of registry.paths) remove(path);
+    remove(dirname(registryFile));
+    process.exit(0);
+  }, GRACE_MS);
+}
+
+// The owner writes nothing: only the end of the pipe (or an error, which also ends it) counts.
+process.stdin.on("data", () => {});
+process.stdin.once("end", cleanUp);
+process.stdin.once("error", cleanUp);
+
+const timer = setInterval(() => {
+  // A normal exit removed the registry: nothing is left to do.
+  if (!existsSync(registryFile)) process.exit(0);
+  if (!isAlive(ownerPid)) cleanUp();
+}, POLL_MS);