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

package/src/host/vice/text-monitor.ts

@@ -0,0 +1,223 @@
+// VICE remote text monitor client, used only for operations the binary monitor
+// cannot do (warp, file load/attach, checkpoint ignore counts, device switch).
+// Raw monitor syntax never leaves src/host/vice.
+//
+// Framing: every command ends with a prompt
+// such as "(C:$e5cf) ", but a command that makes VICE enter the monitor gets
+// an extra prompt first. So prompts cannot delimit answers. Each command is
+// followed by a sentinel `~ $nnnn` whose distinctive four-line answer marks
+// where the command's own output ends. The sentinel is sent only after a
+// prompt shows the command was taken: VICE drops the rest of an input chunk
+// when the command in it makes VICE enter the monitor. Only idempotent
+// commands go through here (see resendAfterMs).
+//
+// VICE sometimes reads a line but runs it only when more input comes. So a
+// late sentinel is sent again, and stray sentinel answers are removed from
+// output. The second answer of a resent sentinel can arrive in parts, while
+// the next command starts: that command waits until the answer is whole
+// before it drops what is left over, so no part of it is read as output. VICE also prints its step message here when the binary monitor
+// steps, sometimes after the next text command was sent; no command of this
+// client steps, so that message is removed from output too.
+
+import type { Socket } from "node:net";
+
+import { connectWithTimeout } from "./connect.ts";
+
+export class TextMonitorError extends Error {
+  override name = "TextMonitorError";
+}
+
+/** A command got no answer in time, but the connection is open; it may still run later. */
+export class TextMonitorTimeoutError extends TextMonitorError {
+  override name = "TextMonitorTimeoutError";
+}
+
+const PROMPT = /\((?:C|\d+):\$[0-9a-f]{4}\) /g;
+export const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+/** The default of TextMonitor.resendAfterMs. */
+const RESEND_AFTER_MS = 3_000;
+/** The default of TextMonitor.overdueTimeoutMs. */
+const OVERDUE_COMMAND_TIMEOUT_MS = 1_000;
+/** The default of TextMonitor.sentinelResendMs. */
+const SENTINEL_RESEND_MS = 1_000;
+/** The longest delay a Node timer takes. */
+const MAX_TIMER_MS = 2_147_483_647;
+const ANY_SENTINEL_ANSWER = /\+\d+\n\$[0-9a-f]{4}\n[0-7]+\n%[01 ]+\n/g;
+const STEP_MESSAGE = /^Stepping through the next \d+ instruction\(s\)\.\n/gm;
+
+function sentinelPattern(nonce: number): RegExp {
+  const hex = nonce.toString(16).padStart(4, "0");
+  return new RegExp(`\\+${nonce}\\n\\$${hex}\\n[0-7]+\\n%[01 ]+\\n\\((?:C|\\d+):\\$[0-9a-f]{4}\\) `);
+}
+
+/** Strips prompts, stray sentinel answers, step messages and surrounding blank space from a command's raw output. */
+export function cleanOutput(raw: string): string {
+  return raw.replace(/\r/g, "").replace(ANY_SENTINEL_ANSWER, "").replace(STEP_MESSAGE, "").replace(PROMPT, "").trim();
+}
+
+export class TextMonitor {
+  readonly closed: Promise<Error | undefined>;
+  readonly #socket: Socket;
+  #buffer = "";
+  #wake: (() => void) | undefined;
+  #queue: Promise<unknown> = Promise.resolve();
+  #nonce = 0x1000 + Math.floor(Math.random() * 0x1000);
+  #closedByUs = false;
+  #failure: Error | undefined;
+  /** The time limit of a command that names none. */
+  defaultTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS;
+  /**
+   * How long to wait for any answer before sending the command once more.
+   * VICE sometimes holds a command line until more input comes; every
+   * command this client sends is idempotent, so a repeat is harmless. A
+   * command that has printed output but no prompt yet still runs, and is not
+   * sent again.
+   */
+  resendAfterMs = RESEND_AFTER_MS;
+  /** How long to wait for a sentinel's answer before sending the sentinel again. */
+  sentinelResendMs = SENTINEL_RESEND_MS;
+  /** While an earlier command timed out, later ones are waited for only this long (see BinaryMonitor). */
+  overdueTimeoutMs = OVERDUE_COMMAND_TIMEOUT_MS;
+  /** Set when a command timed out; cleared by the next command that is answered. */
+  #overdue = false;
+  /** The answers that a resent sentinel of the last command can still give. */
+  #strays: { nonce: number; count: number } | undefined;
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setNoDelay(true);
+    socket.on("data", (chunk) => {
+      this.#buffer += chunk.toString("latin1");
+      this.#wake?.();
+    });
+    socket.on("error", (error) => (this.#failure ??= new TextMonitorError(`text monitor connection failed: ${error.message}`)));
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        this.#wake?.();
+        resolve(this.#closedByUs ? undefined : (this.#failure ?? new TextMonitorError("VICE closed the text monitor connection")));
+      });
+    });
+  }
+
+  static connect(port: number, host = "127.0.0.1", timeoutMs = 2_000): Promise<TextMonitor> {
+    return connectWithTimeout({
+      port,
+      host,
+      timeoutMs,
+      wrap: (socket) => new TextMonitor(socket),
+      failure: (message) => new TextMonitorError(`text monitor ${message}`),
+    });
+  }
+
+  /**
+   * Runs one idempotent command and returns its output without prompts.
+   * Commands run one at a time. A command makes VICE stop the machine if it
+   * was running. `timeoutMs` Infinity waits with no limit, also after a
+   * command that timed out.
+   */
+  command(line: string, timeoutMs = this.defaultTimeoutMs): Promise<string> {
+    if (/[\r\n]/.test(line)) return Promise.reject(new TypeError("a monitor command must be one line"));
+    const run = this.#queue.then(async () => {
+      try {
+        const limit = this.#overdue && timeoutMs !== Infinity ? Math.min(timeoutMs, this.overdueTimeoutMs) : timeoutMs;
+        const output = await this.#exchange(line, limit);
+        this.#overdue = false;
+        return output;
+      } catch (error) {
+        if (error instanceof TextMonitorTimeoutError) this.#overdue = true;
+        throw error;
+      }
+    });
+    this.#queue = run.catch(() => {});
+    return run;
+  }
+
+  close(): Promise<void> {
+    this.#closedByUs = true;
+    this.#socket.destroy();
+    return this.closed.then(() => {});
+  }
+
+  async #exchange(line: string, timeoutMs: number): Promise<string> {
+    if (this.#socket.destroyed) throw new TextMonitorError("text monitor connection is closed");
+    this.#nonce = this.#nonce >= 0xfffe ? 0x1000 : this.#nonce + 1;
+    const sentinel = sentinelPattern(this.#nonce);
+    const deadline = Date.now() + timeoutMs;
+    await this.#settleStrays(deadline, timeoutMs);
+    // Anything left over belongs to no command; drop it so it cannot be misread.
+    this.#buffer = "";
+    this.#socket.write(`${line}\n`);
+    const prompted = () => new RegExp(PROMPT.source).exec(this.#buffer);
+    const resendAt = Math.min(deadline, Date.now() + this.resendAfterMs);
+    try {
+      await this.#waitFor(prompted, resendAt, timeoutMs);
+    } catch (error) {
+      if (this.#socket.destroyed || Date.now() >= deadline) throw error;
+      // Output without a prompt: VICE runs the command and still prints. A repeat would run it twice.
+      if (cleanOutput(this.#buffer) === "") this.#socket.write(`${line}\n`);
+      await this.#waitFor(prompted, deadline, timeoutMs);
+    }
+    const sentinelLine = `~ $${this.#nonce.toString(16)}\n`;
+    let sends = 0;
+    for (;;) {
+      this.#socket.write(sentinelLine);
+      sends++;
+      let found: RegExpExecArray;
+      try {
+        found = await this.#waitFor(() => sentinel.exec(this.#buffer), Math.min(deadline, Date.now() + this.sentinelResendMs), timeoutMs);
+      } catch (error) {
+        if (this.#socket.destroyed || Date.now() >= deadline) throw error;
+        continue;
+      }
+      const output = this.#buffer.slice(0, found.index);
+      this.#buffer = this.#buffer.slice(found.index + found[0].length);
+      this.#strays = sends > 1 ? { nonce: this.#nonce, count: sends - 1 } : undefined;
+      return cleanOutput(output);
+    }
+  }
+
+  /**
+   * Waits a short time for the answers that a resent sentinel of the last
+   * command can still give, and until an answer that has begun is whole. An
+   * answer that VICE holds until more input comes arrives whole inside the
+   * next command's output, where cleanOutput removes it.
+   */
+  async #settleStrays(deadline: number, timeoutMs: number): Promise<void> {
+    const strays = this.#strays;
+    this.#strays = undefined;
+    if (strays === undefined) return;
+    const whole = new RegExp(sentinelPattern(strays.nonce).source, "g");
+    const begun = new RegExp(`\\+${strays.nonce}\\b|\\+\\d*$`);
+    const complete = () => ((this.#buffer.match(whole)?.length ?? 0) >= strays.count ? true : null);
+    const partial = () => begun.test(this.#buffer.replace(whole, ""));
+    try {
+      await this.#waitFor(complete, Math.min(deadline, Date.now() + this.sentinelResendMs), timeoutMs);
+    } catch (error) {
+      if (!(error instanceof TextMonitorTimeoutError)) throw error;
+      if (partial()) await this.#waitFor(() => (partial() ? null : true), deadline, timeoutMs);
+    }
+  }
+
+  /** Waits until `probe` finds something in the received text, and returns what it found. */
+  async #waitFor<T>(probe: () => T | null, deadline: number, timeoutMs: number): Promise<T> {
+    for (;;) {
+      const found = probe();
+      if (found !== null) return found;
+      if (this.#socket.destroyed) throw new TextMonitorError("text monitor connection closed during a command");
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        // The raw tail goes to the host log only; it is never shown to the LLM.
+        throw new TextMonitorTimeoutError(`text monitor command got no answer in ${timeoutMs} ms (received: ${JSON.stringify(this.#buffer.slice(-200))})`);
+      }
+      await new Promise<void>((resolve) => {
+        // No timer for a wait with no limit; a timer longer than Node allows would fire at once.
+        const timer = remaining === Infinity ? undefined : setTimeout(resolve, Math.min(remaining, MAX_TIMER_MS));
+        this.#wake = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+      this.#wake = undefined;
+    }
+  }
+}

package/src/host-client/autostart.ts

@@ -0,0 +1,55 @@
+// Autostart without the autostart's own RUN: the caller decides when the
+// program starts, so keys it types later never mix with VICE's typing.
+
+import { textToPetscii } from "../c64.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** How often, and for how long, a load is checked. */
+export const LOAD_POLL_FRAMES = 25;
+export const LOAD_LIMIT_FRAMES = 1500;
+
+/**
+ * Autostarts the PRG at `path` with run false and advances frames until its
+ * first bytes are at its load address. Returns false when they do not arrive
+ * within LOAD_LIMIT_FRAMES.
+ */
+export async function autostartLoaded(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<boolean> {
+  const load = prg[0]! | (prg[1]! << 8);
+  const head = Buffer.from(prg.subarray(2, Math.min(prg.length, 2 + 64))).toString("hex");
+  await client.autostart({ path, index: 0, run: false });
+  for (let frames = 0; frames < LOAD_LIMIT_FRAMES; frames += LOAD_POLL_FRAMES) {
+    await client.execution({ action: "advance-frames", count: LOAD_POLL_FRAMES, space: "c64" });
+    if ((await client.memoryRead({ address: load, size: head.length / 2, space: "c64", view: "ram" })).data === head) return true;
+  }
+  return false;
+}
+
+/** CURLIN high byte: $ff while BASIC waits in direct mode, a line number's high byte while a program runs. */
+const CURLIN_HIGH = 0x003a;
+export const RUN_LIMIT_FRAMES = 300;
+
+/**
+ * Autostart that returns only when the program runs: load without VICE's
+ * own RUN, type RUN, and wait until BASIC runs a program line. A key that a
+ * later step types then reaches the program, never the READY prompt. Returns
+ * why it did not start, or undefined when it runs.
+ */
+export async function runProgram(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<"not-loaded" | "not-started" | undefined> {
+  if (!(await autostartLoaded(client, path, prg))) return "not-loaded";
+  return (await typeRun(client)) ? undefined : "not-started";
+}
+
+/**
+ * Types RUN at the READY prompt and stops where BASIC starts the first line,
+ * before its SYS. Every tool that starts a loaded program this way reaches
+ * its entry at the same raster line and timer values (D62). False when BASIC
+ * runs no line within RUN_LIMIT_FRAMES.
+ */
+export async function typeRun(client: ViceSessionClient): Promise<boolean> {
+  await client.keyboard(textToPetscii("RUN\n"));
+  const started = await client.runUntil({
+    target: { kind: "memory", address: CURLIN_HIGH, operator: "ne", value: 0xff, space: "c64", view: "ram" },
+    timeoutFrames: RUN_LIMIT_FRAMES,
+  });
+  return started.reached;
+}

package/src/host-client/connect.ts

@@ -0,0 +1,241 @@
+// Deterministic connection to the Host Runtime and the version handshake.
+
+import { connect as connectTcp, type Socket } from "node:net";
+
+import { encodeFrame, MessageReader } from "../protocol/framing.ts";
+import { elapsedMs, trace } from "../trace.ts";
+import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, withStopAndAsk, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+import { PACKAGE } from "../package.ts";
+
+export interface Endpoint {
+  host: string;
+  port: number;
+}
+
+/** How long one endpoint may take to accept a TCP connection. */
+const CONNECT_TIMEOUT_MS = 1_500;
+/**
+ * How long the host may take to answer hello. A VICE session starts its
+ * emulator first, and the host tries the start up to three times.
+ */
+export const DEFAULT_READY_TIMEOUT_MS = 120_000;
+
+/**
+ * The endpoints to try, in order: C64RT_HOST=host:port alone when set,
+ * else loopback, then the Docker and Podman host bridges.
+ */
+export function hostEndpoints(env: NodeJS.ProcessEnv = process.env): Endpoint[] {
+  const override = env.C64RT_HOST;
+  if (override !== undefined && override !== "") {
+    const match = /^(?:\[([^\]]+)\]|([^:]+)):(\d{1,5})$/.exec(override);
+    const port = match === null ? NaN : Number(match[3]);
+    if (match === null || !(port > 0 && port <= 0xffff)) {
+      throw new WireFailure("installation-incomplete", "C64RT_HOST must have the form host:port, for example 127.0.0.1:6464.");
+    }
+    return [{ host: match[1] ?? match[2]!, port }];
+  }
+  return ["127.0.0.1", "host.docker.internal", "host.containers.internal"].map((host) => ({ host, port: DEFAULT_HOST_PORT }));
+}
+
+/** A host that does not run or cannot be reached is machine-unavailable for every role (D37). */
+function unreachable(): WireFailure {
+  return new WireFailure(
+    "machine-unavailable",
+    withStopAndAsk(
+      `The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host) and try again.`,
+    ),
+  );
+}
+
+function stopped(): WireFailure {
+  return new WireFailure(
+    "machine-unavailable",
+    "The connection to the c64-re-tools host runtime stopped before the host runtime was ready.",
+  );
+}
+
+/** Resolves undefined when the endpoint refuses, does not answer in time, or `signal` stops the attempt. */
+function tcpConnect(endpoint: Endpoint, signal: AbortSignal | undefined): Promise<Socket | undefined> {
+  return new Promise((resolve) => {
+    const socket = connectTcp({ host: endpoint.host, port: endpoint.port });
+    const fail = () => finish(undefined);
+    const finish = (result: Socket | undefined) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", fail);
+      if (result === undefined) socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(fail, CONNECT_TIMEOUT_MS);
+    signal?.addEventListener("abort", fail, { once: true });
+    socket.once("connect", () => {
+      socket.removeAllListeners("error");
+      finish(socket);
+    });
+    socket.once("error", fail);
+  });
+}
+
+/** A handshaken, framed connection to the Host Runtime. */
+export class HostConnection {
+  /** Settles when the connection is gone; carries the reason unless we closed it. */
+  readonly closed: Promise<Error | undefined>;
+  readonly #socket: Socket;
+  readonly #reader = new MessageReader();
+  #listener: ((message: HostMessage, attachments: Buffer[]) => void) | undefined;
+  #failure: Error | undefined;
+  #closedByUs = false;
+  #pingTimer: NodeJS.Timeout | undefined;
+  #silenceTimer: NodeJS.Timeout | undefined;
+  #heartbeat = false;
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setNoDelay(true);
+    socket.setKeepAlive(true, 10_000);
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        const reason = this.#closedByUs ? undefined : (this.#failure ?? new Error("the host runtime closed the connection"));
+        trace().event("host.closed", { byUs: this.#closedByUs, reason });
+        resolve(reason);
+      });
+    });
+    socket.on("error", (error) => (this.#failure ??= error));
+    socket.on("close", () => {
+      clearInterval(this.#pingTimer);
+      clearTimeout(this.#silenceTimer);
+    });
+    socket.on("data", (chunk) => {
+      this.#restartSilence();
+      try {
+        for (const { message, attachments } of this.#reader.push(chunk)) {
+          const parsed = parseHostMessage(message);
+          if (parsed.type !== "pong") this.#listener?.(parsed, attachments);
+        }
+      } catch (error) {
+        // A broken frame, or a listener that throws, ends the connection with a
+        // reason; nothing escapes the socket handler.
+        this.#failure =
+          error instanceof ProtocolError
+            ? error
+            : new Error(`could not handle a message from the host runtime: ${error instanceof Error ? error.message : String(error)}`);
+        socket.destroy();
+      }
+    });
+  }
+
+  /**
+   * Connects to the first endpoint that accepts, then handshakes. Once an
+   * endpoint accepts, its answer is final: no later endpoint is tried.
+   */
+  static async open(options: {
+    role: Role;
+    videoStandard?: VideoStandard;
+    env?: NodeJS.ProcessEnv;
+    /** Stops the connect and the handshake at once; the open then fails and its socket is closed. */
+    signal?: AbortSignal;
+  }): Promise<HostConnection> {
+    const signal = options.signal;
+    const started = performance.now();
+    let socket: Socket | undefined;
+    for (const endpoint of hostEndpoints(options.env)) {
+      if (signal?.aborted) break;
+      const attempt = performance.now();
+      socket = await tcpConnect(endpoint, signal);
+      trace().event("host.connect", { ...endpoint, role: options.role, accepted: socket !== undefined, ms: elapsedMs(attempt) });
+      if (socket !== undefined) break;
+    }
+    if (signal?.aborted) {
+      socket?.destroy();
+      throw stopped();
+    }
+    if (socket === undefined) throw unreachable();
+
+    const connection = new HostConnection(socket);
+    const hello: Hello = { type: "hello", protocol: HOST_PROTOCOL_ID, version: HOST_PROTOCOL_VERSION, role: options.role };
+    if (options.videoStandard !== undefined) hello.videoStandard = options.videoStandard;
+
+    const stop = () => void connection.close();
+    signal?.addEventListener("abort", stop, { once: true });
+    const answer = await new Promise<HostMessage | Error>((resolve) => {
+      const timer = setTimeout(() => resolve(new Error("no answer to hello in time")), DEFAULT_READY_TIMEOUT_MS);
+      connection.#listener = (message) => {
+        clearTimeout(timer);
+        resolve(message);
+      };
+      void connection.closed.then((reason) => {
+        clearTimeout(timer);
+        resolve(reason ?? new Error("closed"));
+      });
+      connection.#send(hello);
+    });
+    connection.#listener = undefined;
+    signal?.removeEventListener("abort", stop);
+    if (signal?.aborted) {
+      await connection.close();
+      throw stopped();
+    }
+
+    if (!(answer instanceof Error) && answer.type === "ready") {
+      trace().event("host.ready", { role: options.role, ms: elapsedMs(started) });
+      connection.#startHeartbeat();
+      return connection;
+    }
+    trace().event("host.handshake-failed", { role: options.role, ms: elapsedMs(started), ...(answer instanceof Error ? { error: answer } : answer) });
+    await connection.close();
+    if (answer instanceof Error) {
+      if (answer instanceof ProtocolError) {
+        throw new WireFailure(
+          "installation-incomplete",
+          "The c64-re-tools host runtime is from another release. Stop the host runtime and start it again with npx, then restart the agent session. npx then starts the newest release on both sides.",
+        );
+      }
+      throw new WireFailure(
+        "machine-unavailable",
+        "The c64-re-tools host runtime did not finish the handshake. Check that it is running and try again.",
+      );
+    }
+    if (answer.type === "error") throw new WireFailure(answer.error.code, answer.error.message);
+    throw new WireFailure("installation-incomplete", "The c64-re-tools host runtime answered out of turn. Install the same c64-re-tools release on both sides.");
+  }
+
+  /** Receives every message after the handshake, with any attachments. */
+  onMessage(listener: (message: HostMessage, attachments: Buffer[]) => void): void {
+    this.#listener = listener;
+  }
+
+  send(request: Request, attachments: readonly Uint8Array[] = []): void {
+    if (!this.#socket.destroyed) this.#socket.write(encodeFrame(request, attachments));
+  }
+
+  close(): Promise<void> {
+    this.#closedByUs = true;
+    this.#socket.destroy();
+    return this.closed.then(() => {});
+  }
+
+  /**
+   * Pings the host so it knows this client is alive, and closes the connection
+   * when the host has sent nothing for the timeout: a host that vanished
+   * without a close then fails like a closed one. The timers never keep
+   * the process alive.
+   */
+  #startHeartbeat(): void {
+    this.#heartbeat = true;
+    const ping: Ping = { type: "ping" };
+    this.#pingTimer = setInterval(() => this.#send(ping), HEARTBEAT_INTERVAL_MS).unref();
+    this.#restartSilence();
+  }
+
+  #restartSilence(): void {
+    if (!this.#heartbeat || this.#socket.destroyed) return;
+    clearTimeout(this.#silenceTimer);
+    this.#silenceTimer = setTimeout(() => {
+      this.#failure ??= new Error(`the host runtime sent nothing for ${HEARTBEAT_TIMEOUT_MS} ms`);
+      this.#socket.destroy();
+    }, HEARTBEAT_TIMEOUT_MS).unref();
+  }
+
+  #send(message: Hello | Request | Ping): void {
+    if (!this.#socket.destroyed) this.#socket.write(encodeFrame(message));
+  }
+}

package/src/host-client/coverage.ts

@@ -0,0 +1,63 @@
+// Reads the emulator's memory access map as coverage bytes (D40): one byte
+// per address, RAM, ROM and I/O apart. The MCP tool and the skill scripts share it.
+
+import { COVERAGE, type CodeRange } from "../c64.ts";
+import { MAX_MEMMAP_RANGES, type MemmapRange } from "../protocol/vice.ts";
+import { readProjectFile } from "./transfer.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** A full coverage file: offset n is address n (D40). */
+export const FULL_COVERAGE = 0x10000;
+
+/** Reads full coverage files from the project, one map per file. `fail` refuses a file of another size. */
+export function readCoverageMaps(paths: string[], fail: (message: string) => never): Uint8Array[] {
+  return paths.map((path) => {
+    const { bytes } = readProjectFile(path);
+    if (bytes.length !== FULL_COVERAGE) {
+      fail(`--coverage ${path} has ${bytes.length} bytes; a full coverage file has 65536, one for each address. Write it with c64_memmap action read and out, without start and end.`);
+    }
+    return bytes;
+  });
+}
+
+/** Joins coverage maps: an address has every flag that any run gave it. */
+export function joinCoverage(maps: readonly Uint8Array[]): Uint8Array {
+  const joined = new Uint8Array(FULL_COVERAGE);
+  for (const map of maps) for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= map[address]!;
+  return joined;
+}
+
+/**
+ * Reads full coverage files from the project and joins them: an address has
+ * every flag that any run gave it. `fail` refuses a file of another size.
+ */
+export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
+  return paths.length === 0 ? undefined : joinCoverage(readCoverageMaps(paths, fail));
+}
+
+/** The coverage bytes of start..end, read from the session in parts. */
+export async function readCoverage(session: Pick<ViceSessionClient, "memmap">, start = 0x0000, end = 0xffff): Promise<Uint8Array> {
+  const map = new Uint8Array(end - start + 1);
+  for (let from: number | undefined = start; from !== undefined; ) {
+    const part: { ranges: MemmapRange[]; next?: number } = await session.memmap({ action: "read", start: from, end, maxRanges: MAX_MEMMAP_RANGES });
+    for (const range of part.ranges) map.fill(range.flags, range.start - start, range.end - start + 1);
+    from = part.next;
+  }
+  return map;
+}
+
+/** Runs of RAM that a program wrote, at least `minimum` bytes each, in a map from $0000. */
+export function writtenBlocks(map: Uint8Array, minimum: number): CodeRange[] {
+  const blocks: CodeRange[] = [];
+  let start = -1;
+  for (let address = 0; address <= map.length; address++) {
+    const written = address < map.length && (map[address]! & COVERAGE.ramWrite) !== 0;
+    if (written && start < 0) start = address;
+    if (!written && start >= 0) {
+      if (address - start >= minimum) blocks.push({ start, end: address - 1 });
+      start = -1;
+    }
+  }
+  return blocks;
+}
+