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

package/src/host/vice/session.ts

@@ -3,14 +3,17 @@
 // session starts headless and can move the machine into a VICE with a window
 // and back; breakpoints, watchpoints and the rest go along.
 
-import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
-import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { isOneOf, WireFailure, type VideoStandard } from "../../protocol/messages.ts";
+import { DISK_IMAGE_TYPES, type DiskFile, type DiskImageType } from "../../protocol/tools.ts";
+import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type PointRemoved, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type TraceHit, type TraceKind, type TraceResult, type PointStopReason, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
-import { formatC64Address } from "../../c64.ts";
+import { formatC64Address, instructionLength } from "../../c64.ts";
+import { encodePng, type IndexedFrame } from "../../graphics.ts";
+import { instructionText, operandAddress } from "../../opcodes.ts";
 import type { ProcessSupervisor } from "../../native/processes.ts";
 import { trace } from "../../trace.ts";
 import type { ViceSessionFactory, ViceSessionHandle } from "../server.ts";
@@ -26,7 +29,7 @@ import {
 } from "./adapter.ts";
 import { decodeProgramCounter, MonitorConnectionError, MonitorError, MonitorTimeoutError, ResponseType, type MonitorResponse } from "./binary-monitor.ts";
 import { decodeCia, decodeSid, decodeSprite, decodeVicii } from "./chips.ts";
-import { compareFrames, differenceImage, encodePng, type IndexedFrame } from "./screen.ts";
+import { compareFrames, differenceImage } from "./screen.ts";
 import { launchVice, startErrorLines, type ViceMode, type ViceProcess } from "./process.ts";
 import { TextMonitorError, TextMonitorTimeoutError } from "./text-monitor.ts";
 
@@ -74,6 +77,8 @@ const WINDOW_CLOSED =
   "Breakpoints and watchpoints are kept. Check the machine state before you continue.";
 
 /** Emulator state that a move to another VICE cannot carry. */
+/** The first bytes of every VICE snapshot file. */
+const VSF_MAGIC = Buffer.from("VICE Snapshot File\x1a", "latin1");
 const NOT_CARRIED = ["cpu history", "memory map", "profile", "keyboard input not yet typed"];
 
 /** Starts another VICE for this session; `log` also gets that launch's lines. */
@@ -119,6 +124,26 @@ export interface SessionOptions {
   launch?: ViceLauncher;
   /** Makes the host remove a path if it dies; returns the release. */
   ownPath?: (path: string) => () => void;
+  /** The known flaws of this VICE version (D56); keyboard and joystick results name them. */
+  flaws?: readonly string[];
+  /** Lists the entries of a disk image, so an autostart index is checked first (R2-08). Without it, VICE gets the index unchecked. */
+  directory?: DiskDirectory;
+}
+
+export type DiskDirectory = (type: DiskImageType, image: Buffer) => Promise<DiskFile[]>;
+
+/**
+ * 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 {
@@ -128,9 +153,12 @@ export class ViceSession implements ViceSessionHandle {
   #mode: ViceMode = "headless";
   readonly #videoStandard: VideoStandard;
   readonly #log: (line: string) => void;
+  /** The known VICE flaws that keyboard and joystick input meet, as one text, or undefined. */
+  readonly #inputFlaw: string | undefined;
   readonly #untilReturnLimitMs: number;
   readonly #stepLimitMs: number;
   readonly #launch: ViceLauncher | undefined;
+  readonly #directory: DiskDirectory | undefined;
   /** Session files that outlive one VICE: snapshots, staged media, handovers. */
   readonly #workDir: string;
   readonly #releaseWorkDir: () => void;
@@ -157,6 +185,8 @@ export class ViceSession implements ViceSessionHandle {
   #driveStop = false;
   /** Counts stops caused by checkpoints or a CPU JAM rather than by a monitor command. */
   #haltCount = 0;
+  /** What stopped the machine last, when a user breakpoint or watchpoint or a JAM did; cleared when it runs again. */
+  #lastStop: { stopReason: PointStopReason; pointId?: number } | undefined;
   #queue: Promise<unknown> = Promise.resolve();
   #closed = false;
   #lost = false;
@@ -173,8 +203,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;
   /**
@@ -196,6 +228,8 @@ export class ViceSession implements ViceSessionHandle {
     this.#untilReturnLimitMs = options.untilReturnLimitMs ?? UNTIL_RETURN_LIMIT_MS;
     this.#stepLimitMs = options.stepLimitMs ?? RUNNING_COMMAND_TIMEOUT_MS;
     this.#launch = options.launch;
+    this.#directory = options.directory;
+    this.#inputFlaw = options.flaws === undefined || options.flaws.length === 0 ? undefined : options.flaws.join(" ");
     this.#workDir = mkdtempSync(join(tmpdir(), "c64-re-tools-session-"));
     this.#releaseWorkDir = options.ownPath?.(this.#workDir) ?? (() => {});
     this.#watch(vice);
@@ -268,7 +302,7 @@ export class ViceSession implements ViceSessionHandle {
           session.#timingStart = await session.#adapter.clock();
           // c64_profile reports what ran since the session started.
           await session.#adapter.startProfiler();
-          // The control-port lines start all pressed; release them before the C64 reads them.
+          // In VICE 3.10 and older the control-port lines start all pressed; release them before the C64 reads them.
           for (const joystick of session.#joysticks.values()) await session.#adapter.setJoystick(joystick);
         }),
       );
@@ -283,9 +317,10 @@ export class ViceSession implements ViceSessionHandle {
     op: O,
     params: ViceOperations[O]["params"],
     attachments: Buffer[] = [],
+    reply: Buffer[] = [],
   ): Promise<ViceOperations[O]["result"]> {
     // A window request for the mode the session is in sends nothing to VICE, so a held VICE does not stop it.
-    return this.#enqueue(() => this.#run(op, params, attachments), { whileHeld: op === "window" }) as Promise<ViceOperations[O]["result"]>;
+    return this.#enqueue(() => this.#run(op, params, attachments, reply), { whileHeld: op === "window" }) as Promise<ViceOperations[O]["result"]>;
   }
 
   async close(): Promise<void> {
@@ -303,10 +338,15 @@ export class ViceSession implements ViceSessionHandle {
     return this.#adapter;
   }
 
-  async #run(op: ViceOperation, params: unknown, attachments: Buffer[]): Promise<unknown> {
+  async #run(op: ViceOperation, params: unknown, attachments: Buffer[], reply: Buffer[]): Promise<unknown> {
     switch (op) {
       case "status":
         return this.#status();
+      case "ioRead": {
+        const read = params as ViceOperations["ioRead"]["params"];
+        const bytes = await this.#observe(() => this.#machine.readIo(read.address, read.size));
+        return { address: read.address, data: Buffer.from(bytes).toString("hex") };
+      }
       case "memoryRead": {
         const read = params as ViceOperations["memoryRead"]["params"];
         const data = await this.#observe(() => this.#machine.readMemory(read));
@@ -345,10 +385,30 @@ export class ViceSession implements ViceSessionHandle {
         return this.#programLoad(params as ViceOperations["programLoad"]["params"], onlyAttachment(attachments));
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
-        const file = this.#stage(onlyAttachment(attachments), type);
+        const bytes = onlyAttachment(attachments);
+        if (index > 0 && this.#directory !== undefined && isOneOf(DISK_IMAGE_TYPES, type)) checkDirectoryEntry(await this.#directory(type, bytes), index);
+        const file = this.#stage(bytes, 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"];
@@ -362,7 +422,7 @@ export class ViceSession implements ViceSessionHandle {
       case "keyboard": {
         const bytes = Buffer.from((params as ViceOperations["keyboard"]["params"]).data, "hex");
         await this.#observe(() => this.#machine.feedKeyboard(bytes));
-        return { queuedBytes: bytes.length };
+        return { queuedBytes: bytes.length, ...(this.#inputFlaw === undefined ? {} : { emulatorFlaw: this.#inputFlaw }) };
       }
       case "breakpoint":
         return this.#breakpoint(params as BreakpointParams);
@@ -394,8 +454,12 @@ export class ViceSession implements ViceSessionHandle {
       }
       case "snapshot":
         return this.#snapshot(params as ViceOperations["snapshot"]["params"]);
+      case "snapshotFile":
+        return this.#snapshotFile(params as ViceOperations["snapshotFile"]["params"], attachments, reply);
       case "cpuHistory":
         return this.#cpuHistory(params as ViceOperations["cpuHistory"]["params"]);
+      case "trace":
+        return this.#trace(params as ViceOperations["trace"]["params"]);
       case "backtrace": {
         const { depth, space } = params as ViceOperations["backtrace"]["params"];
         return this.#observe(async () => {
@@ -413,8 +477,12 @@ export class ViceSession implements ViceSessionHandle {
         return { cycles: (now - this.#timingStart).toString() };
       }
       case "profile": {
-        const { limit } = params as ViceOperations["profile"]["params"];
-        return { entries: await this.#observe(() => this.#machine.profile(limit)) };
+        const request = params as ViceOperations["profile"]["params"];
+        if (request.action === "clear") {
+          await this.#observe(() => this.#machine.startProfiler());
+          return { cleared: true };
+        }
+        return { entries: await this.#observe(() => this.#machine.profile(request.limit)) };
       }
       case "memmap": {
         const request = params as ViceOperations["memmap"]["params"];
@@ -422,7 +490,7 @@ export class ViceSession implements ViceSessionHandle {
           await this.#observe(() => this.#machine.clearMemmap());
           return { cleared: true };
         }
-        return { ranges: await this.#observe(() => this.#machine.memmap(request.start, request.end, request.maxRanges)) };
+        return await this.#observe(() => this.#machine.memmap(request.start, request.end, request.maxRanges));
       }
       case "vicii":
         return this.#observe(() => this.#vicii());
@@ -442,7 +510,7 @@ export class ViceSession implements ViceSessionHandle {
         const joystick = params as JoystickState;
         await this.#observe(() => this.#machine.setJoystick(joystick));
         this.#joysticks.set(joystick.port, joystick);
-        return joystick;
+        return { ...joystick, ...(this.#inputFlaw === undefined ? {} : { emulatorFlaw: this.#inputFlaw }) };
       }
       case "warp": {
         const { enabled } = params as ViceOperations["warp"]["params"];
@@ -458,8 +526,13 @@ 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" };
-    if (status.state === "stopped") status.pc = await this.#pc();
+    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();
+      // VICE 3.9 sends no JAM event: the opcode at the pc tells.
+      const stop = this.#lastStop ?? ((await this.#jammedAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
+      if (stop !== undefined) Object.assign(status, stop);
+    }
     return status;
   }
 
@@ -485,8 +558,18 @@ 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);
-      return { state: "stopped", pc: outcome.pc, advancedFrames: outcome.frames };
+      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,
+        stopReason: outcome.end === "target" ? "frames" : outcome.end,
+        ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }),
+      };
     }
     await this.#stop();
     if (params.action === "until-return") {
@@ -516,6 +599,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" };
@@ -545,10 +630,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 }> {
+  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }, anchor?: { line: number; cycle: number }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8"; pointId?: number }> {
     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" });
@@ -574,24 +660,139 @@ export class ViceSession implements ViceSessionHandle {
             }
           } else {
             frames++;
-            if (frames >= limit) return { end: "frames", frames, pc: stop.pc };
+            if (frames >= limit) return { end: "frames", frames, pc: stop.pc, space: "c64" };
             await this.#machine.setCondition(clock, arming);
           }
           armingPhase = !armingPhase;
           continue;
         }
         if (end === "unknown") {
-          if (await this.#jammedAt(stop.pc)) return { end: "jam", frames, pc: stop.pc };
+          if (await this.#jammedAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
           throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this run.");
         }
-        // A drive stop is completed before the result names the computer's pc.
-        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc };
+        // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
+        const driveStop = this.#driveStop;
+        const pointId = end === "target" ? undefined : this.#userPoint(stop.hits)?.pointId;
+        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc, space: driveStop ? "drive8" : "c64", ...(pointId === undefined ? {} : { pointId }) };
       }
     } finally {
       await this.#machine.deleteCheckpoint(clock);
     }
   }
 
+  /**
+   * A trace (D76): runs the machine for up to `frames` frames, counted as
+   * #runFrames counts them, with a stopping checkpoint for each point. At each
+   * hit the session records the instruction, its registers and the raster
+   * position, and runs on. It ends at the frame limit, at `maxHits` hits, or
+   * where a user point or a JAM stops the program. VICE also reports the hits
+   * of a checkpoint that does not stop, but without the PC, the registers or
+   * the raster position, so each point stops.
+   */
+  async #trace(params: ViceOperations["trace"]["params"]): Promise<TraceResult> {
+    await this.#stop();
+    const lines = RASTER[this.#videoStandard].lines;
+    const start = await this.#machine.rasterPosition();
+    const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
+    const ending = rasterWindowExpression(start.line, start.cycle, lines);
+    const operation: Record<TraceKind, number> = { exec: 0x04, read: 0x01, write: 0x02 };
+    const points: number[] = [];
+    const hits: TraceHit[] = [];
+    let frames = 0;
+    const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
+    try {
+      for (const point of params.points) points.push(await this.#machine.addCheckpoint({ start: point.start, end: point.end, operation: operation[point.kind], space: "c64" }));
+      await this.#machine.setCondition(clock, arming);
+      let armingPhase = true;
+      for (;;) {
+        const next = this.#nextStop(HALF_FRAME_LIMIT_MS);
+        await this.#resume();
+        const stop = await next;
+        if (stop === undefined) {
+          await this.#stop();
+          throw new WireFailure("operation-failed", "The emulator did not reach the next frame in time.");
+        }
+        const traced = points.flatMap((checkpoint, index) => (stop.hits.includes(checkpoint) ? [index] : []));
+        for (const index of traced) {
+          hits.push(await this.#traceHit(index, params.points[index]!.kind, frames));
+          if (hits.length >= params.maxHits) return { hits, frames, end: "hits", pc: stop.pc };
+        }
+        if (stop.hits.includes(clock)) {
+          if (armingPhase) await this.#machine.setCondition(clock, ending);
+          else {
+            frames++;
+            if (frames >= params.frames) return { hits, frames, end: "frames", pc: stop.pc };
+            await this.#machine.setCondition(clock, arming);
+          }
+          armingPhase = !armingPhase;
+          continue;
+        }
+        if (traced.length > 0) continue;
+        const point = this.#userPoint(stop.hits);
+        if (point !== undefined) return { hits, frames, end: point.stopReason, pc: stop.pc };
+        if (await this.#jammedAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
+        throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this trace.");
+      }
+    } finally {
+      await this.#machine.deleteCheckpoint(clock);
+      for (const checkpoint of points) await this.#machine.deleteCheckpoint(checkpoint);
+    }
+  }
+
+  /**
+   * One hit of a trace point. An exec point stops before its instruction: the
+   * registers and the raster position are the ones of now. A read or write
+   * point stops after the instruction that made the access: the last entry of
+   * the CPU history is that instruction, with its registers and its clock.
+   */
+  async #traceHit(point: number, kind: TraceKind, frame: number): Promise<TraceHit> {
+    const position = await this.#machine.rasterPosition();
+    const byteAt = async (address: number) => Number.parseInt(await this.#machine.readMemory({ address, size: 1, space: "c64", view: "cpu" }), 16);
+    if (kind === "exec") {
+      const registers = await this.#machine.readRegisters("c64");
+      const bytes = [...Buffer.from(await this.#machine.readMemory({ address: registers.pc, size: 3, space: "c64", view: "cpu" }), "hex")];
+      const length = instructionLength(bytes[0]!);
+      return {
+        point,
+        pc: registers.pc,
+        bytes: Buffer.from(bytes.slice(0, length)).toString("hex"),
+        text: instructionText(bytes, registers.pc),
+        a: registers.a,
+        x: registers.x,
+        y: registers.y,
+        sp: registers.sp,
+        frame,
+        rasterLine: position.line,
+        rasterCycle: position.cycle,
+      };
+    }
+    const [entry] = await this.#machine.history(1, "c64");
+    if (entry === undefined) throw new WireFailure("operation-failed", "The emulator gave no CPU history at a trace hit.");
+    const now = await this.#machine.clock();
+    const { lines, cycles } = RASTER[this.#videoStandard];
+    const span = BigInt(lines * cycles);
+    const at = Number((((BigInt(position.line * cycles + position.cycle) - (now - entry.clock)) % span) + span) % span);
+    const bytes = [...Buffer.from(entry.bytes, "hex")];
+    // A zero-page pointer is read now: the instruction did not change it.
+    const pointer = new Map<number, number>();
+    for (const address of [bytes[1] ?? 0, ((bytes[1] ?? 0) + 1) & 0xff, ((bytes[1] ?? 0) + entry.x) & 0xff, ((bytes[1] ?? 0) + entry.x + 1) & 0xff]) pointer.set(address, await byteAt(address));
+    const address = operandAddress(bytes, entry.x, entry.y, (zp) => pointer.get(zp) ?? 0);
+    return {
+      point,
+      pc: entry.address,
+      bytes: entry.bytes,
+      text: instructionText(bytes, entry.address),
+      a: entry.a,
+      x: entry.x,
+      y: entry.y,
+      sp: entry.sp,
+      frame,
+      rasterLine: Math.floor(at / cycles),
+      rasterCycle: at % cycles,
+      ...(address === undefined ? {} : { address, value: await byteAt(address) }),
+    };
+  }
+
   /**
    * Completes a stop that a drive 8 checkpoint caused: the computer runs to
    * its next instruction boundary, where a computer checkpoint stops it, so
@@ -602,6 +803,8 @@ export class ViceSession implements ViceSessionHandle {
   async #completeDriveStop(): Promise<number | undefined> {
     if (!this.#driveStop) return undefined;
     this.#driveStop = false;
+    // The drive checkpoint stopped the machine; the stop at the boundary keeps that reason.
+    const reason = this.#lastStop;
     const boundary = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       for (let attempt = 0; attempt < DRIVE_STOP_TRIES; attempt++) {
@@ -612,6 +815,7 @@ export class ViceSession implements ViceSessionHandle {
         // The drive can hit its checkpoint again before the computer gets to the next instruction.
         if (stop.hits.includes(boundary)) {
           this.#driveStop = false;
+          this.#lastStop = reason;
           trace().event("vice.drive-stop", { pc: stop.pc, resumes: attempt + 1 });
           return stop.pc;
         }
@@ -626,14 +830,20 @@ export class ViceSession implements ViceSessionHandle {
   /** Names what caused a stop during a frame-clocked run. */
   #stopCause(stop: Stop, clock: number, target: number | undefined): Exclude<RunEnd, "frames" | "jam"> | "clock" | "unknown" {
     if (target !== undefined && stop.hits.includes(target)) return "target";
-    const isPoint = (registry: Map<number, { checkpoint: number }>) =>
-      [...registry.values()].some((point) => stop.hits.includes(point.checkpoint));
-    if (isPoint(this.#breakpoints)) return "breakpoint";
-    if (isPoint(this.#watchpoints)) return "watchpoint";
+    const point = this.#userPoint(stop.hits);
+    if (point !== undefined) return point.stopReason;
     if (stop.hits.includes(clock)) return "clock";
     return "unknown";
   }
 
+  /** The user breakpoint, else the user watchpoint, among the hit VICE checkpoints. */
+  #userPoint(hits: number[]): { stopReason: "breakpoint" | "watchpoint"; pointId: number } | undefined {
+    for (const [stopReason, registry] of [["breakpoint", this.#breakpoints], ["watchpoint", this.#watchpoints]] as const) {
+      for (const [pointId, point] of registry) if (hits.includes(point.checkpoint)) return { stopReason, pointId };
+    }
+    return undefined;
+  }
+
   async #jammedAt(pc: number): Promise<boolean> {
     const opcode = await this.#machine.readMemory({ address: pc, size: 1, space: "c64", view: "cpu" });
     return JAM_OPCODES.has(Number.parseInt(opcode, 16));
@@ -677,9 +887,9 @@ export class ViceSession implements ViceSessionHandle {
       if (expression !== undefined) await this.#machine.setCondition(checkpoint, expression);
       const outcome = await this.#runFrames(params.timeoutFrames, { checkpoint, deferred });
       const stopReason = outcome.end === "frames" ? "timeout" : outcome.end;
-      // A stop event carries the computer's PC; a drive target reports the drive's.
-      const pc = target.kind !== "raster" && target.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
-      return { reached: stopReason === "target", stopReason, state: "stopped", pc };
+      // A stop event carries the computer's PC; a stop in the drive reports the drive's (F-31).
+      const pc = outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
+      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space, ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }) };
     } finally {
       await this.#machine.deleteCheckpoint(checkpoint);
     }
@@ -716,34 +926,44 @@ export class ViceSession implements ViceSessionHandle {
   async #changePoint<T extends { checkpoint: number; enabled: boolean }>(
     registry: Map<number, T>,
     kind: string,
-    params: { action: "remove" | "enable" | "disable"; id: number },
+    params: { action: "enable" | "disable"; id: number },
   ): Promise<T> {
-    const point = registry.get(params.id);
-    if (point === undefined) throw new WireFailure("not-found", `There is no ${kind} with id ${params.id}.`);
-    if (params.action === "remove") {
-      await this.#observe(() => this.#machine.deleteCheckpoint(point.checkpoint));
-      registry.delete(params.id);
-    } else {
-      const enabled = params.action === "enable";
-      await this.#observe(() => this.#machine.toggleCheckpoint(point.checkpoint, enabled));
-      point.enabled = enabled;
-    }
+    const point = this.#point(registry, kind, params.id);
+    const enabled = params.action === "enable";
+    await this.#observe(() => this.#machine.toggleCheckpoint(point.checkpoint, enabled));
+    point.enabled = enabled;
+    return point;
+  }
+
+  async #removePoint(registry: Map<number, { checkpoint: number }>, kind: string, id: number): Promise<PointRemoved> {
+    const point = this.#point(registry, kind, id);
+    await this.#observe(() => this.#machine.deleteCheckpoint(point.checkpoint));
+    registry.delete(id);
+    return { removed: true, id };
+  }
+
+  #point<T>(registry: Map<number, T>, kind: string, id: number): T {
+    const point = registry.get(id);
+    if (point === undefined) throw new WireFailure("not-found", `There is no ${kind} with id ${id}.`);
     return point;
   }
 
-  async #breakpoint(params: BreakpointParams): Promise<Breakpoint | { breakpoints: Breakpoint[] }> {
+  async #breakpoint(params: BreakpointParams): Promise<Breakpoint | PointRemoved | { breakpoints: Breakpoint[] }> {
     const publicView = ({ checkpoint: _checkpoint, expression: _expression, ...point }: Breakpoint & { checkpoint: number; expression?: string }): Breakpoint =>
       point;
     if (params.action === "list") return { breakpoints: [...this.#breakpoints.values()].map(publicView) };
+    if (params.action === "remove") return this.#removePoint(this.#breakpoints, "breakpoint", params.id);
     if (params.action !== "add") return publicView(await this.#changePoint(this.#breakpoints, "breakpoint", params));
+    // A breakpoint over a range stops at the first instruction executed in it: exec, not a watch (D43).
     const added = await this.#addPoint({
-      ...pointRange({ address: params.address }),
+      ...(params.size === undefined ? pointRange({ address: params.address }) : { start: params.address, end: params.address + params.size - 1, operation: 0x04 }),
       space: params.space,
       ...(params.condition === undefined ? {} : { condition: params.condition }),
     });
     const point = {
       id: this.#nextPointId++,
       address: params.address,
+      ...(params.size === undefined ? {} : { size: params.size }),
       space: params.space,
       enabled: true,
       ...(params.condition === undefined ? {} : { condition: params.condition }),
@@ -753,10 +973,11 @@ export class ViceSession implements ViceSessionHandle {
     return publicView(point);
   }
 
-  async #watchpoint(params: WatchpointParams): Promise<Watchpoint | { watchpoints: Watchpoint[] }> {
+  async #watchpoint(params: WatchpointParams): Promise<Watchpoint | PointRemoved | { watchpoints: Watchpoint[] }> {
     const publicView = ({ checkpoint: _checkpoint, expression: _expression, ...point }: Watchpoint & { checkpoint: number; expression?: string }): Watchpoint =>
       point;
     if (params.action === "list") return { watchpoints: [...this.#watchpoints.values()].map(publicView) };
+    if (params.action === "remove") return this.#removePoint(this.#watchpoints, "watchpoint", params.id);
     if (params.action !== "add") return publicView(await this.#changePoint(this.#watchpoints, "watchpoint", params));
     const added = await this.#addPoint({
       ...pointRange({ address: params.address, size: params.size, access: params.access }),
@@ -790,14 +1011,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. */
@@ -858,7 +1086,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;
   }
 
@@ -910,15 +1141,43 @@ export class ViceSession implements ViceSessionHandle {
       this.#snapshots.delete(params.name);
       return { discarded: true };
     }
+    return this.#restoreFrom(existing);
+  }
+
+  /** Restores the machine from a .vsf in the session directory; the CPU stays stopped. */
+  async #restoreFrom(file: string): Promise<{ restored: true; state: "stopped" }> {
     await this.#stop();
     const elapsed = (await this.#machine.clock()) - this.#timingStart;
-    await this.#machine.restoreSnapshot(existing);
+    await this.#machine.restoreSnapshot(file);
     this.#state = "stopped";
     // The cycle clock jumped with the restore; the stopwatch keeps its reading, as a window move does.
     this.#timingStart = (await this.#machine.clock()) - elapsed;
     return { restored: true, state: "stopped" };
   }
 
+  /** A snapshot as bytes (D41): export a named one into `reply`, or restore from the attached .vsf. */
+  async #snapshotFile(params: ViceOperations["snapshotFile"]["params"], attachments: Buffer[], reply: Buffer[]): Promise<ViceOperations["snapshotFile"]["result"]> {
+    if (params.action === "export") {
+      const file = this.#snapshots.get(params.name);
+      if (file === undefined) throw new WireFailure("not-found", `There is no snapshot named ${params.name}.`);
+      const bytes = readFileSync(file);
+      reply.push(bytes);
+      return { exported: true, bytes: bytes.length };
+    }
+    const bytes = onlyAttachment(attachments);
+    // Checked before the machine stops: VICE gives no reason for a file that is no snapshot (F-07).
+    if (!bytes.subarray(0, VSF_MAGIC.length).equals(VSF_MAGIC)) throw new WireFailure("invalid-input", "The file is not a VICE snapshot file (.vsf). Give a file that c64_snapshot save wrote.");
+    const file = this.#stage(bytes, "vsf");
+    try {
+      return await this.#restoreFrom(file);
+    } catch (error) {
+      if (error instanceof WireFailure) throw error;
+      throw new WireFailure("invalid-input", "The emulator did not restore this snapshot file. A snapshot file restores only in the emulator version and with the machine settings that saved it.");
+    } finally {
+      rmSync(file, { force: true });
+    }
+  }
+
   /**
    * Moves the machine into a VICE of the other mode: a snapshot of this
    * one, restored in a new one, with the user points, joysticks, warp and the
@@ -933,6 +1192,7 @@ export class ViceSession implements ViceSessionHandle {
     if (this.#held !== undefined) throw new WireFailure("machine-unavailable", this.#heldWhy);
     if (this.#launch === undefined) throw new WireFailure("operation-failed", "This session cannot start another emulator.");
     const running = this.#state === "running";
+    this.#log(mode === "window" ? "moving the machine to a VICE with a window" : "moving the machine back to a headless VICE");
     await this.#stop();
     const handover: Handover = {
       file: join(this.#workDir, mode === "window" ? "window-open.vsf" : "window-close.vsf"),
@@ -1018,10 +1278,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;
@@ -1076,6 +1338,7 @@ export class ViceSession implements ViceSessionHandle {
    */
   async #resumingCommand(send: () => Promise<void>): Promise<void> {
     this.#state = "running";
+    this.#lastStop = undefined;
     try {
       await send();
     } catch (error) {
@@ -1251,10 +1514,12 @@ export class ViceSession implements ViceSessionHandle {
       const stop: Stop = { pc: decodeProgramCounter(event.body), hits: this.#checkpointHits };
       if (stop.hits.length > 0 || event.type === ResponseType.jam) this.#haltCount++;
       if (stop.hits.some((hit) => this.#adapter?.isDriveCheckpoint(hit))) this.#driveStop = true;
+      this.#lastStop = event.type === ResponseType.jam ? { stopReason: "jam" } : this.#userPoint(stop.hits);
       this.#checkpointHits = [];
       this.#state = "stopped";
       this.#stopWaiters = this.#stopWaiters.filter((waiter) => !waiter(stop));
     } else if (event.type === ResponseType.resumed) {
+      this.#lastStop = undefined;
       this.#state = "running";
     }
   }
@@ -1291,14 +1556,27 @@ async function setPoint(
   return checkpoint;
 }
 
+/**
+ * Refuses an autostart index that selects no program: VICE numbers the
+ * entries from 1, and the caller from 0, as the c64-disk directory list does.
+ * A DEL entry holds no program (R2-08), and an index past the last entry selects nothing.
+ */
+function checkDirectoryEntry(entries: DiskFile[], index: number): void {
+  const entry = entries[index - 1];
+  if (entry === undefined) throw new WireFailure("invalid-input", `The disk has ${entries.length} directory entries, so index ${index - 1} selects no entry. The c64-disk directory list gives the index of each entry.`);
+  if (entry.type === "del") throw new WireFailure("invalid-input", `Directory entry ${index - 1} (${entry.name}) is a DEL entry and holds no program. Give the index of a PRG entry.`);
+}
+
 /** The production factory: launch a headless VICE per session through the host's supervisor. */
 export function viceSessionFactory(options: {
   supervisor: ProcessSupervisor;
   env?: NodeJS.ProcessEnv;
   log?: (line: string) => void;
+  /** The known flaws of the VICE version that the host checked at start. */
+  flaws?: readonly string[];
+  directory?: DiskDirectory;
 }): ViceSessionFactory {
-  const log = options.log ?? (() => {});
-  return async ({ videoStandard }) => {
+  return async ({ videoStandard, log = options.log ?? (() => {}) }) => {
     const launch: ViceLauncher = (mode, launchLog) =>
       launchVice({
         videoStandard,
@@ -1311,6 +1589,11 @@ export function viceSessionFactory(options: {
         ...(options.env === undefined ? {} : { env: options.env }),
       });
     const vice = await launch("headless", () => {});
-    return ViceSession.start(vice, videoStandard, log, { launch, ownPath: (path) => options.supervisor.ownPath(path) });
+    return ViceSession.start(vice, videoStandard, log, {
+      launch,
+      ownPath: (path) => options.supervisor.ownPath(path),
+      ...(options.flaws === undefined ? {} : { flaws: options.flaws }),
+      ...(options.directory === undefined ? {} : { directory: options.directory }),
+    });
   };
 }