@henols/c64-re-tools 2.0.0-rc.6 → 2.0.0-rc.8

package/src/host/vice/adapter.ts

@@ -6,6 +6,7 @@ import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry
 import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
 import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
+import type { CiaHidden } from "./chips.ts";
 import {
   BinaryMonitor,
   Command,
@@ -135,7 +136,7 @@ export function parseDisassembly(answer: string, start: number): Instruction[] {
   for (const line of answer.split("\n")) {
     const match = /^\.(?:C|\d+):([0-9a-f]{4})\s+((?:[0-9a-f]{2} )*[0-9a-f]{2})\s+(.*?)\s*$/i.exec(line);
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     const address = Number.parseInt(match[1]!, 16);
@@ -164,7 +165,7 @@ export function parseHistory(answer: string): Array<Omit<HistoryEntry, "rasterLi
         line,
       );
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     entries.push({
@@ -193,7 +194,7 @@ export function parseHunt(answer: string, limit: number): number[] {
   for (const line of answer.split("\n")) {
     const match = /^([0-9a-f]{4})$/i.exec(line.trim());
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     if (matches.length < limit) matches.push(Number.parseInt(match[1]!, 16));
@@ -236,14 +237,15 @@ export function parseProfile(answer: string): ProfileEntry[] {
   const unknown: string[] = [];
   for (const line of answer.split("\n")) {
     // Counts can carry the host locale's digit grouping ("1,123,200") and the percent a decimal comma.
-    const row = new RegExp(`^\\s*(${COUNT})\\s+[\\d.,]+%\\s+(${COUNT})\\s+([\\d.,]+)%\\s+(\\S+)\\s*$`).exec(line);
+    // A profile of zero cycles, as after a window move restarts it, prints its percents as "-nan".
+    const row = new RegExp(`^\\s*(${COUNT})\\s+(?:[\\d.,]+|-?nan)%\\s+(${COUNT})\\s+([\\d.,]+|-?nan)%\\s+(\\S+)\\s*$`, "i").exec(line);
     if (row === null) {
-      if (line.trim() !== "" && !/^Total\s+%\s+Self\s+%$/.test(line.trim()) && !/^[-\s]+$/.test(line)) unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim()) && !/^Total\s+%\s+Self\s+%$/.test(line.trim()) && !/^[-\s]+$/.test(line)) unknown.push(line.trim());
       continue;
     }
     // A row named ROOT or by a label has no routine address.
     if (!/^[0-9a-f]{4}$/i.test(row[4]!)) continue;
-    entries.push({ address: Number.parseInt(row[4]!, 16), totalCycles: digits(row[1]!), selfCycles: digits(row[2]!), percent: Number(row[3]!.replace(",", ".")) });
+    entries.push({ address: Number.parseInt(row[4]!, 16), totalCycles: digits(row[1]!), selfCycles: digits(row[2]!), percent: /nan/i.test(row[3]!) ? 0 : Number(row[3]!.replace(",", ".")) });
   }
   // An answer in another form must not read as "nothing ran".
   if (entries.length === 0 && unknown.length > 0) throw unknownForm("profile", unknown);
@@ -284,7 +286,7 @@ export function parseMemmap(answer: string, maxRanges: number): { ranges: Memmap
   for (const line of answer.split("\n")) {
     const match = /^([0-9a-f]{4}): (\S{3}) (\S{3}) (\S{3})/i.exec(line);
     if (match === null) {
-      if (line.trim() !== "" && !/^addr:\s+IO\s+ROM\s+RAM$/.test(line.trim())) unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim()) && !/^addr:\s+IO\s+ROM\s+RAM$/.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     const address = Number.parseInt(match[1]!, 16);
@@ -308,12 +310,19 @@ export function parseMemmap(answer: string, maxRanges: number): { ranges: Memmap
  */
 const STOP_LINE = /^(?:#\d+ \((?:Stop on|Trace)\s|\.(?:C|\d+):[0-9a-f]{4}\s)/i;
 
-/** The lines of a text command's answer that are not blank, not a stop line and not `known`. */
+/**
+ * The line VICE prints on the text monitor when the binary monitor sets a
+ * checkpoint condition. It can come late, in the answer of the next text
+ * command (seen on Windows).
+ */
+const CONDITION_LINE = /^Setting checkpoint \d+ condition to: /;
+
+/** The lines of a text command's answer that are not blank, not a stop line, not a condition line and not `known`. */
 function otherLines(answer: string, known?: RegExp): string[] {
   return answer
     .split("\n")
     .map((line) => line.trim())
-    .filter((line) => line !== "" && !STOP_LINE.test(line) && known?.test(line) !== true);
+    .filter((line) => line !== "" && !STOP_LINE.test(line) && !CONDITION_LINE.test(line) && known?.test(line) !== true);
 }
 
 /** Refuses the answer of a text command that prints nothing, or only `known` lines, when it works. */
@@ -423,6 +432,19 @@ export class ViceAdapter {
     return bytes.toString("hex");
   }
 
+  /**
+   * The timer latches and the interrupt mask of the CIA at `base`, from VICE's
+   * text-monitor dump: no register read gives them (D63).
+   */
+  async ciaHidden(base: 0xdc00 | 0xdd00): Promise<CiaHidden> {
+    const answer = await this.#computerText(`io ${hex4(base)}`);
+    const mask = /\(mask: ([0-9a-f]{2})\)/i.exec(answer);
+    const latchA = /Timer A: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    const latchB = /Timer B: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    if (mask === null || latchA === null || latchB === null) throw unknownForm("CIA dump", answer.split("\n"));
+    return { latchA: Number.parseInt(latchA[1]!, 16), latchB: Number.parseInt(latchB[1]!, 16), interruptMask: Number.parseInt(mask[1]!, 16) & 0x1f };
+  }
+
   /** Reads C64 I/O registers through the I/O bank, whatever the CPU has banked in, without side effects. */
   async readIo(start: number, size: number): Promise<Uint8Array> {
     const response = await this.#monitor.request(
@@ -631,6 +653,12 @@ export class ViceAdapter {
     await this.#monitor.request(Command.autostart, Buffer.concat([head, name]));
   }
 
+  /** Detaches every cartridge. VICE powers the cartridge off; the C64 keeps running. */
+  async detachCartridge(): Promise<void> {
+    // Device 32 is the cartridge port; the monitor reads numbers as hex. VICE prints nothing when it detaches.
+    expectQuiet("cartridge detach answer", await this.#text.command("detach 20"));
+  }
+
   /** Attaches a disk image file from the host file system to drive 8. */
   async attachDisk(file: string): Promise<void> {
     const answer = await this.#text.command(`attach ${quoted(file)} 8`);

package/src/host/vice/chips.ts

@@ -57,8 +57,15 @@ function bcd(value: number): number {
   return (value >> 4) * 10 + (value & 0x0f);
 }
 
+/** The parts of a CIA that no register read gives: the timer latches and the interrupt mask. */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
 /** `registers` holds $dc00-$dc0f or $dd00-$dd0f. TOD hours become 0-23. */
-export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
+export function decodeCia(id: 1 | 2, registers: Uint8Array, hidden: CiaHidden): CiaState {
   const word = (low: number) => registers[low]! | (registers[low + 1]! << 8);
   const hourRegister = registers[0x0b]!;
   const pm = (hourRegister & 0x80) !== 0;
@@ -70,9 +77,12 @@ export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
     ddrB: registers[0x03]!,
     timerA: word(0x04),
     timerB: word(0x06),
+    latchA: hidden.latchA,
+    latchB: hidden.latchB,
     controlA: registers[0x0e]!,
     controlB: registers[0x0f]!,
     interruptStatus: registers[0x0d]!,
+    interruptMask: hidden.interruptMask,
     tod: {
       hours: (bcd(hourRegister & 0x1f) % 12) + (pm ? 12 : 0),
       minutes: bcd(registers[0x0a]! & 0x7f),

package/src/host/vice/process.ts

@@ -1,5 +1,7 @@
 // VICE launch, readiness and termination. The launch contract of x64sc:
 // - `-default` must come before `-binarymonitor`, or the monitor never binds;
+// - `-config` must come first: VICE's trunk (after 3.10) drops every argument
+//   before it, so the monitors would never start;
 // - the monitor may accept a connection during startup and then drop it, so
 //   readiness is a connect plus a successful ping, retried until a deadline;
 // - any monitor command stops the machine, so readiness ends with `exit`;
@@ -76,6 +78,9 @@ export function viceArguments(options: {
   const headless = options.mode === "headless" ? ["-console", "-sounddev", "dummy"] : [];
   return [
     options.binary,
+    // VICE's trunk (after 3.10) drops every argument before -config, so it comes first.
+    "-config",
+    options.configFile,
     "-default",
     "-logfile",
     options.logFile,
@@ -85,8 +90,6 @@ export function viceArguments(options: {
     "-remotemonitor",
     "-remotemonitoraddress",
     `ip4://127.0.0.1:${options.textPort}`,
-    "-config",
-    options.configFile,
     "-model",
     options.videoStandard === "ntsc" ? "ntsc" : "c64",
     "-drive8type",
@@ -94,6 +97,8 @@ export function viceArguments(options: {
     // Autostart injects a PRG into RAM; the default mode copies it to a disk image first.
     "-autostartprgmode",
     "1",
+    // VICE's default waits a random time before an autostart types its LOAD, so two runs of one file differ (R2-12).
+    "+autostart-delay-random",
     // The same RAM after every power-up: a hard reset is a power cycle, and VICE's default can flip
     // random bits, so two runs from one start state could differ.
     "-raminitstartvalue",

package/src/host/vice/screen.ts

@@ -4,6 +4,7 @@
 import { crc32, deflateSync } from "node:zlib";
 
 import type { VideoStandard } from "../../protocol/messages.ts";
+import { FRAME_SIZE } from "../../protocol/vice.ts";
 
 export interface IndexedFrame {
   width: number;
@@ -44,8 +45,8 @@ export function decodeDisplay(body: Buffer): RawDisplay {
  * offsets: PAL 384×272, NTSC 384×247.
  */
 const VISIBLE: Record<VideoStandard, { dx: number; dy: number; width: number; height: number }> = {
-  pal: { dx: -32, dy: -36, width: 384, height: 272 },
-  ntsc: { dx: -32, dy: -23, width: 384, height: 247 },
+  pal: { dx: -32, dy: -36, ...FRAME_SIZE.pal },
+  ntsc: { dx: -32, dy: -23, ...FRAME_SIZE.ntsc },
 };
 
 /** Crops the visible bordered frame out of VICE's full raster buffer. */

package/src/host/vice/session.ts

@@ -125,6 +125,20 @@ export interface SessionOptions {
   flaws?: readonly string[];
 }
 
+/**
+ * Where VICE keeps a staged file: an autostarted disk stays in drive 8, a tape
+ * in the datasette and a cartridge in the port, until the same place gets
+ * another file. Only a program is read once.
+ */
+type StagedKind = "program" | "disk" | "tape" | "cartridge";
+
+function stagedKind(type: string): StagedKind {
+  if (type === "crt") return "cartridge";
+  if (type === "tap" || type === "t64") return "tape";
+  if (type === "prg" || type === "p00") return "program";
+  return "disk";
+}
+
 export class ViceSession implements ViceSessionHandle {
   /** The current VICE. A window move replaces it. */
   #vice: ViceProcess;
@@ -179,8 +193,10 @@ export class ViceSession implements ViceSessionHandle {
   #timingStart = 0n;
   /** Counts staged media files, for unique names. */
   #staged = 0;
+  /** True after an autostart of a cartridge, until an autostart of another file detaches it. */
+  #cartridge = false;
   /** The last staged file of each kind that VICE took; VICE can still read it. */
-  readonly #stagedFiles = new Map<"autostart" | "disk", string>();
+  readonly #stagedFiles = new Map<StagedKind, string>();
   /** Session-local ids: one counter for breakpoints and watchpoints, from 1. */
   #nextPointId = 1;
   /**
@@ -359,9 +375,27 @@ export class ViceSession implements ViceSessionHandle {
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
         const file = this.#stage(onlyAttachment(attachments), type);
+        // VICE keeps a cartridge through every reset and autostart, as a real C64 does.
+        if (type !== "crt" && this.#cartridge) {
+          await this.#observe(() => this.#machine.detachCartridge());
+          this.#cartridge = false;
+          this.#replaceStaged("cartridge", undefined);
+        }
+        // Port 1 shares the keyboard lines: a held direction types keys into the RUN that the autostart types (R3-05).
+        const centred: Array<1 | 2> = [];
+        for (const [port, joystick] of this.#joysticks) {
+          if (joystick.direction === "center" && !joystick.fire) continue;
+          const centre: JoystickState = { port, direction: "center", fire: false };
+          await this.#observe(() => this.#machine.setJoystick(centre));
+          this.#joysticks.set(port, centre);
+          centred.push(port);
+        }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
-        this.#replaceStaged("autostart", file);
-        return { state: "running" };
+        if (type === "crt") this.#cartridge = true;
+        this.#replaceStaged(stagedKind(type), file);
+        // A reset sets the CPU clock back, so the stopwatch starts again.
+        this.#timingStart = 0n;
+        return { state: "running", ...(type === "tap" && this.#inputFlaw !== undefined ? { emulatorFlaw: this.#inputFlaw } : {}), ...(centred.length === 0 ? {} : { joysticksCentred: centred }) };
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
@@ -473,7 +507,7 @@ export class ViceSession implements ViceSessionHandle {
   async #status(): Promise<MachineStatus> {
     const warp = await this.#observe(() => this.#machine.warp());
     // Read after #observe: it resumes a running machine, unless a breakpoint or a JAM stopped it meanwhile.
-    const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window" };
+    const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window", cartridge: this.#cartridge };
     if (status.state === "stopped") status.pc = await this.#pc();
     return status;
   }
@@ -500,7 +534,11 @@ export class ViceSession implements ViceSessionHandle {
     }
     if (params.action === "advance-frames") {
       if (params.count === undefined) throw new WireFailure("invalid-input", "advance-frames needs count, the number of frames");
-      const outcome = await this.#runFrames(params.count);
+      const raster = RASTER[this.#videoStandard];
+      if (params.anchor !== undefined && (params.anchor.line >= raster.lines || params.anchor.cycle >= raster.cycles)) {
+        throw new WireFailure("invalid-input", `The anchor is outside the frame: a ${this.#videoStandard} frame has lines 0-${raster.lines - 1} and cycles 0-${raster.cycles - 1}.`);
+      }
+      const outcome = await this.#runFrames(params.count, undefined, params.anchor);
       return { state: "stopped", pc: outcome.pc, advancedFrames: outcome.frames };
     }
     await this.#stop();
@@ -531,6 +569,8 @@ export class ViceSession implements ViceSessionHandle {
 
   async #reset(params: { mode: "soft" | "hard"; run: boolean }): Promise<{ state: RunState; pc?: number }> {
     await this.#stop();
+    // A reset sets the CPU clock back, so the stopwatch starts again.
+    this.#timingStart = 0n;
     if (params.run) {
       await this.#runningCommand(() => this.#machine.reset(params.mode));
       return { state: "running" };
@@ -560,10 +600,11 @@ export class ViceSession implements ViceSessionHandle {
    * checkpoint, a user breakpoint or watchpoint, or a JAM ends the run early.
    * The machine is stopped afterwards.
    */
-  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
+  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }, anchor?: { line: number; cycle: number }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
-    const start = await this.#machine.rasterPosition();
+    // A frame ends where the raster passes the anchor; without one, where this run starts.
+    const start = anchor ?? (await this.#machine.rasterPosition());
     const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
     const ending = rasterWindowExpression(start.line, start.cycle, lines);
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
@@ -817,14 +858,21 @@ export class ViceSession implements ViceSessionHandle {
   }
 
   /**
-   * Records the staged file that VICE took for `kind`, and removes the file
-   * it replaces: VICE does not read that one again. A file that VICE did not
-   * take stays until the session closes, because a held VICE can still read it.
+   * Records the staged file that VICE took for `kind`, or that it no longer
+   * has, and removes the file it replaces: VICE does not read that one again.
+   * A file that VICE did not take stays until the session closes, because a
+   * held VICE can still read it. So does a file that Windows does not let go.
    */
-  #replaceStaged(kind: "autostart" | "disk", file: string): void {
+  #replaceStaged(kind: StagedKind, file: string | undefined): void {
     const previous = this.#stagedFiles.get(kind);
-    this.#stagedFiles.set(kind, file);
-    if (previous !== undefined) rmSync(previous, { force: true });
+    if (file === undefined) this.#stagedFiles.delete(kind);
+    else this.#stagedFiles.set(kind, file);
+    if (previous === undefined || previous === file) return;
+    try {
+      rmSync(previous, { force: true });
+    } catch {
+      // The session directory goes when the session closes.
+    }
   }
 
   /** Loads a PRG without reset or start; finishes stopped. */
@@ -885,7 +933,10 @@ export class ViceSession implements ViceSessionHandle {
   async #cias(which: CiaSelection): Promise<CiaState[]> {
     const ids: Array<1 | 2> = which === "both" ? [1, 2] : [Number(which) as 1 | 2];
     const chips = [];
-    for (const id of ids) chips.push(decodeCia(id, await this.#machine.readIo(id === 1 ? 0xdc00 : 0xdd00, 0x10)));
+    for (const id of ids) {
+      const base = id === 1 ? 0xdc00 : 0xdd00;
+      chips.push(decodeCia(id, await this.#machine.readIo(base, 0x10), await this.#machine.ciaHidden(base)));
+    }
     return chips;
   }
 
@@ -1074,10 +1125,12 @@ export class ViceSession implements ViceSessionHandle {
     if (baseline === undefined) throw new WireFailure("not-found", `There is no baseline named ${params.baseline}.`);
     const current = await this.#observe(() => this.#machine.captureFrame(this.#videoStandard));
     const difference = compareFrames(baseline.frame, current.frame, params.mask);
-    const mismatchRatio = difference.comparedPixels === 0 ? 0 : difference.mismatchingPixels / difference.comparedPixels;
+    if (difference.comparedPixels === 0) throw new WireFailure("invalid-input", "The mask covers the whole screen: nothing to compare.");
+    const mismatchRatio = difference.mismatchingPixels / difference.comparedPixels;
     const result: ScreenComparison = {
       match: mismatchRatio <= params.maxMismatchRatio,
       mismatchingPixels: difference.mismatchingPixels,
+      comparedPixels: difference.comparedPixels,
       mismatchRatio,
     };
     if (difference.bounds !== undefined) result.bounds = difference.bounds;

package/src/host-client/autostart.ts

@@ -36,10 +36,20 @@ export const RUN_LIMIT_FRAMES = 300;
  */
 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 ? undefined : "not-started";
+  return started.reached;
 }

package/src/host-client/connect.ts

@@ -4,7 +4,7 @@ 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 ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.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 {
@@ -37,19 +37,19 @@ export function hostEndpoints(env: NodeJS.ProcessEnv = process.env): Endpoint[]
   return ["127.0.0.1", "host.docker.internal", "host.containers.internal"].map((host) => ({ host, port: DEFAULT_HOST_PORT }));
 }
 
-function unreachable(role: Role): WireFailure {
-  const code: ErrorCode = role === "vice-session" ? "machine-unavailable" : "operation-failed";
+/** A host that does not run or cannot be reached is machine-unavailable for every role (D37). */
+function unreachable(): WireFailure {
   return new WireFailure(
-    code,
+    "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(role: Role): WireFailure {
+function stopped(): WireFailure {
   return new WireFailure(
-    role === "vice-session" ? "machine-unavailable" : "operation-failed",
+    "machine-unavailable",
     "The connection to the c64-re-tools host runtime stopped before the host runtime was ready.",
   );
 }
@@ -146,9 +146,9 @@ export class HostConnection {
     }
     if (signal?.aborted) {
       socket?.destroy();
-      throw stopped(options.role);
+      throw stopped();
     }
-    if (socket === undefined) throw unreachable(options.role);
+    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 };
@@ -172,7 +172,7 @@ export class HostConnection {
     signal?.removeEventListener("abort", stop);
     if (signal?.aborted) {
       await connection.close();
-      throw stopped(options.role);
+      throw stopped();
     }
 
     if (!(answer instanceof Error) && answer.type === "ready") {
@@ -190,7 +190,7 @@ export class HostConnection {
         );
       }
       throw new WireFailure(
-        options.role === "vice-session" ? "machine-unavailable" : "operation-failed",
+        "machine-unavailable",
         "The c64-re-tools host runtime did not finish the handshake. Check that it is running and try again.",
       );
     }

package/src/host-client/coverage.ts

@@ -9,23 +9,32 @@ 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 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 {
-  if (paths.length === 0) return undefined;
-  const joined = new Uint8Array(FULL_COVERAGE);
-  for (const path of paths) {
+/** 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.`);
     }
-    for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= bytes[address]!;
-  }
+    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);

package/src/host-client/tools.ts

@@ -4,7 +4,7 @@
 // ACME, DXA and Ghidra themselves through src/native.
 
 import { ProtocolError, WireFailure } from "../protocol/messages.ts";
-import { DISK_IMAGE_TYPES, validateToolResult, type C1541Result, type DiskAction, type DiskImageType, type PetcatResult, type ToolOperation, type ToolOperations, type ToolStatus } from "../protocol/tools.ts";
+import { DISK_IMAGE_TYPES, validateToolResult, type C1541Result, type DiskAction, type DiskImageType, type PetcatResult, type ToolOperation, type ToolOperations, type HostInfo, type ToolStatus } from "../protocol/tools.ts";
 import { HostConnection } from "./connect.ts";
 import { readProjectFile } from "./transfer.ts";
 
@@ -43,7 +43,7 @@ export async function callTool<O extends ToolOperation>(
         }
       });
       void connection.closed.then(() =>
-        reject(new WireFailure("operation-failed", "The connection to the c64-re-tools host runtime was lost during the request. Check that the Host Runtime (c64-re-tools-host) is running.")),
+        reject(new WireFailure("machine-unavailable", "The connection to the c64-re-tools host runtime was lost during the request. Check that the Host Runtime (c64-re-tools-host) is running.")),
       );
       connection.send({ type: "request", id: 1, op, params }, attachments);
     });
@@ -78,12 +78,12 @@ export async function decodeBasic(request: { program: string }, options: ToolCal
   return (await callTool("petcat.decode", {}, [file.bytes], options)).result;
 }
 
-/** host.status: each native tool on the host, found and run once. */
-export async function hostTools(options: ToolCallOptions = {}): Promise<ToolStatus[]> {
-  return (await callTool("host.status", {}, [], options)).result.tools;
+/** host.status: the Host Runtime, and each native tool on the host, found and run once. */
+export async function hostTools(options: ToolCallOptions = {}): Promise<{ host: HostInfo; tools: ToolStatus[] }> {
+  return (await callTool("host.status", {}, [], options)).result;
 }
 
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
 export { DISK_ACTIONS } from "../protocol/tools.ts";
-export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";

package/src/host-client/vice-session.ts

@@ -134,7 +134,7 @@ export class ViceSessionClient {
   }
 
   /** Autostarts a project program or image, as VICE's autostart does. */
-  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState }> {
+  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState; emulatorFlaw?: string }> {
     const file = readProjectFile(params.path);
     return this.#request("autostart", { type: file.type, index: params.index, run: params.run }, [file.bytes]);
   }

package/src/knowledge/schema.ts

@@ -45,6 +45,13 @@ export type SuppressionEntity = (typeof SUPPRESSION_ENTITIES)[number];
 
 /** A module file of the generated source (D48): a plain name that ends in .asm, no directory. */
 export const MODULE_FILE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,59}\.asm$/;
+/** Files that c64-source writes itself: no module can have these names. */
+export const GENERATED_FILES = ["main.asm", "loader.asm", "constants.asm"] as const;
+
+/** True for a generated file name in any letter case: the file systems of macOS and Windows ignore case. */
+export function isGeneratedFile(file: string): boolean {
+  return (GENERATED_FILES as readonly string[]).includes(file.toLowerCase());
+}
 
 /**
  * The address space of a knowledge row (D53): the C64, the 1541 drive, or a

package/src/knowledge/write.ts

@@ -41,6 +41,8 @@ import {
   MAX_ELEMENT,
   MODULE_FILE,
   DEFAULT_SPACE,
+  GENERATED_FILES,
+  isGeneratedFile,
   SPACE,
   NO_ELEMENT_TYPES,
   REFERENCE_KINDS,
@@ -431,6 +433,9 @@ function checkModule(request: ModuleRequest): void {
   checkSpace(request);
   checkAddress(request.start, "start");
   if (!MODULE_FILE.test(request.file)) throw new KnowledgeError("invalid-input", "A module file is a name of letters, digits, underscores or hyphens (at most 60) that ends in .asm, without a directory.");
+  if (isGeneratedFile(request.file)) {
+    throw new KnowledgeError("invalid-input", `c64-source writes ${GENERATED_FILES.join(", ")} itself, in any letter case, so a module cannot have the file ${request.file}. Give the module another file.`);
+  }
   if (request.title !== undefined && (request.title.trim().length === 0 || request.title.length > MAX_COMMENT)) throw new KnowledgeError("invalid-input", `A module title has 1 to ${MAX_COMMENT} characters.`);
 }
 

package/src/mcp/tools/debug.ts

@@ -41,7 +41,8 @@ export const c64Breakpoint = defineTool({
   description:
     "Manage breakpoints. A breakpoint stops the CPU when it is about to execute the instruction at an address. " +
     "Action add sets one at address in space c64 or drive8. With a condition, it stops only when the condition is true. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
     "Breakpoints stay through a reset.",
   inputSchema: z
     .object({
@@ -84,7 +85,8 @@ export const c64Watchpoint = defineTool({
     "Manage watchpoints. A watchpoint stops the CPU when an instruction reads or writes memory in a range. " +
     `Action add sets one at address for size bytes (1 to ${MAX_WATCH_SIZE}, default 1), with access read, write or read-write. ` +
     "With a condition, it stops only when the condition is true. For a write, a memory condition sees the memory after the write. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
   inputSchema: z
     .object({
       action: z.enum(CHECKPOINT_ACTIONS),
@@ -129,7 +131,7 @@ export const c64CpuHistory = defineTool({
   description:
     "Get the last instructions that the CPU executed, oldest first. " +
     `limit is the number of instructions (1 to ${MAX_HISTORY}, default 50). ` +
-    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp. " +
+    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp before the instruction executed. " +
     "In space c64, it also gives the raster line and cycle when the instruction started. " +
     "With out, it writes the entries as text lines to that project file, and the result gives the file in place of the entries. " +
     "This does not change the run state of the machine.",
@@ -191,7 +193,8 @@ export const c64Timing = defineTool({
   title: "Cycle stopwatch",
   description:
     "A stopwatch that counts C64 CPU cycles. Action start sets it to zero. Action read gives the cycles since the last start, " +
-    "or since the session started, as a decimal string. A PAL frame has 19656 cycles and an NTSC frame 17095.",
+    "or since the session started, as a decimal string. A reset and c64_autostart start it again from the reset. " +
+    "A PAL frame has 19656 cycles and an NTSC frame 17095.",
   inputSchema: z.object({ action: z.enum(TIMING_ACTIONS) }).strict(),
   outputSchema: z.object({ started: z.boolean().optional(), cycles: z.string().regex(/^\d+$/).optional() }),
   readOnly: false,
@@ -204,7 +207,8 @@ export const c64Profile = defineTool({
   name: "c64_profile",
   title: "Cycle profile",
   description:
-    "Get the routines where the C64 CPU spent the most cycles since the session started. " +
+    "Get the routines where the C64 CPU spent the most cycles since the session started or since the last c64_window. " +
+    "After c64_window or a snapshot restore, the emulator can give the cycles to a routine that ran before the restore, for example $fd50. Do not trust the routine addresses then. " +
     `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
     "Each entry gives the routine address, its total cycles with the routines it calls, and its own cycles. " +
     "percent is the part of all cycles that the routine used itself. " +