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

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)]);
+  }
+}

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?.();
+  }
+}