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

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 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 RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
+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";
 
@@ -121,10 +124,14 @@ 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. */
+  /** The known flaws of this VICE version; keyboard and joystick results name them. */
   flaws?: readonly string[];
+  /** Lists the entries of a disk image, so an autostart index is checked first. 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
@@ -151,6 +158,7 @@ export class ViceSession implements ViceSessionHandle {
   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;
@@ -177,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;
@@ -218,6 +228,7 @@ 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) ?? (() => {});
@@ -374,14 +385,16 @@ 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).
+        // Port 1 shares the keyboard lines: a held direction types keys into the RUN that the autostart types.
         const centred: Array<1 | 2> = [];
         for (const [port, joystick] of this.#joysticks) {
           if (joystick.direction === "center" && !joystick.fire) continue;
@@ -445,6 +458,8 @@ export class ViceSession implements ViceSessionHandle {
         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 () => {
@@ -462,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"];
@@ -508,7 +527,12 @@ export class ViceSession implements ViceSessionHandle {
     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", cartridge: this.#cartridge };
-    if (status.state === "stopped") status.pc = await this.#pc();
+    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;
   }
 
@@ -539,7 +563,13 @@ export class ViceSession implements ViceSessionHandle {
         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 };
+      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") {
@@ -600,7 +630,7 @@ 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 }, anchor?: { line: number; cycle: number }): 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"; pointId?: number }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
     // A frame ends where the raster passes the anchor; without one, where this run starts.
@@ -642,13 +672,127 @@ export class ViceSession implements ViceSessionHandle {
         }
         // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
         const driveStop = this.#driveStop;
-        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc, space: driveStop ? "drive8" : "c64" };
+        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: 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
@@ -659,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++) {
@@ -669,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;
         }
@@ -683,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));
@@ -734,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 stop in the drive reports the drive's (F-31).
+      // A stop event carries the computer's PC; a stop in the drive reports the drive's.
       const pc = outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
-      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space };
+      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space, ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }) };
     } finally {
       await this.#machine.deleteCheckpoint(checkpoint);
     }
@@ -801,7 +954,7 @@ export class ViceSession implements ViceSessionHandle {
     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).
+    // A breakpoint over a range stops at the first instruction executed in it: exec, not a watch.
     const added = await this.#addPoint({
       ...(params.size === undefined ? pointRange({ address: params.address }) : { start: params.address, end: params.address + params.size - 1, operation: 0x04 }),
       space: params.space,
@@ -1002,7 +1155,7 @@ export class ViceSession implements ViceSessionHandle {
     return { restored: true, state: "stopped" };
   }
 
-  /** A snapshot as bytes (D41): export a named one into `reply`, or restore from the attached .vsf. */
+  /** A snapshot as bytes: 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);
@@ -1012,7 +1165,7 @@ export class ViceSession implements ViceSessionHandle {
       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).
+    // Checked before the machine stops: VICE gives no reason for a file that is no snapshot.
     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 {
@@ -1185,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) {
@@ -1360,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";
     }
   }
@@ -1400,6 +1556,17 @@ 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, 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;
@@ -1407,6 +1574,7 @@ export function viceSessionFactory(options: {
   log?: (line: string) => void;
   /** The known flaws of the VICE version that the host checked at start. */
   flaws?: readonly string[];
+  directory?: DiskDirectory;
 }): ViceSessionFactory {
   return async ({ videoStandard, log = options.log ?? (() => {}) }) => {
     const launch: ViceLauncher = (mode, launchLog) =>
@@ -1421,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), ...(options.flaws === undefined ? {} : { flaws: options.flaws }) });
+    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 }),
+    });
   };
 }

package/src/host-client/autostart.ts

@@ -42,7 +42,7 @@ export async function runProgram(client: ViceSessionClient, path: string, prg: U
 /**
  * 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
+ * its entry at the same raster line and timer values. False when BASIC
  * runs no line within RUN_LIMIT_FRAMES.
  */
 export async function typeRun(client: ViceSessionClient): Promise<boolean> {

package/src/host-client/connect.ts

@@ -37,7 +37,7 @@ 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 }));
 }
 
-/** A host that does not run or cannot be reached is machine-unavailable for every role (D37). */
+/** A host that does not run or cannot be reached is machine-unavailable for every role. */
 function unreachable(): WireFailure {
   return new WireFailure(
     "machine-unavailable",

package/src/host-client/coverage.ts

@@ -1,40 +1,13 @@
-// Reads the emulator's memory access map as coverage bytes (D40): one byte
+// Reads the emulator's memory access map as coverage bytes: 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). */
+/** A full coverage file: offset n is address n. */
 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);

package/src/host-client/image.ts

@@ -0,0 +1,66 @@
+// An image.json of the c64-unpacker skill (a 64 KiB memory and its segments)
+// or a PRG, read from the project to put it into the knowledge.
+
+import { posix } from "node:path";
+
+import { formatC64Address, prgRange } from "../c64.ts";
+import { readProjectFile } from "./transfer.ts";
+
+/** A file that is no image: the scripts report it as a bad call. */
+export class ImageError extends Error {
+  override name = "ImageError";
+}
+
+export interface Image {
+  segments: Array<{ start: number; end: number }>;
+  /** The byte at an address inside a segment. */
+  byteAt: (address: number) => number;
+  entry?: number;
+  /** entry_state.json next to image.json. */
+  statePath?: string;
+  /** The stages of the capture in image.json, as the unpacker wrote them. */
+  stages?: Array<Record<string, unknown>>;
+}
+
+/** Reads an image.json or a PRG, relative to the project folder. */
+export function readImage(path: string): Image {
+  const { bytes } = readProjectFile(path);
+  if (!path.endsWith(".json")) {
+    let range: ReturnType<typeof prgRange>;
+    try {
+      range = prgRange(bytes);
+    } catch (error) {
+      throw new ImageError(`${path}: ${(error as Error).message}`);
+    }
+    return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
+  }
+  const fail = (what: string): never => {
+    throw new ImageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
+  };
+  const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  const manifest = isObject(parsed) ? parsed : fail("it is not a JSON object");
+  const address = (value: unknown, what: string) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail(`${what} is not a $ address`));
+  if (typeof manifest.image !== "string") fail("it has no image");
+  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it has no segments");
+  const segments = (manifest.segments as unknown[])
+    .map((segment, index) => (isObject(segment) ? segment : fail(`segment ${index + 1} is not an object`)))
+    .map((segment, index) => ({ start: address(segment.start, `segment ${index + 1} start`), end: address(segment.end, `segment ${index + 1} end`) }))
+    .sort((a, b) => a.start - b.start);
+  segments.forEach((segment, index) => {
+    if (segment.end < segment.start) fail(`the segment at ${formatC64Address(segment.start)} ends before it starts`);
+    if (index > 0 && segment.start <= segments[index - 1]!.end) fail(`the segments at ${formatC64Address(segments[index - 1]!.start)} and ${formatC64Address(segment.start)} overlap`);
+  });
+  const directory = posix.dirname(path);
+  const memory = readProjectFile(posix.join(directory, manifest.image as string)).bytes;
+  if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
+  const image: Image = { segments, byteAt: (at) => memory[at]!, statePath: posix.join(directory, "entry_state.json") };
+  if (manifest.entry !== undefined) image.entry = address(manifest.entry, "entry");
+  if (Array.isArray(manifest.stages)) image.stages = manifest.stages.map((stage, index) => (isObject(stage) ? stage : fail(`stage ${index + 1} is not an object`)));
+  return image;
+}

package/src/host-client/steps.ts

@@ -1,4 +1,4 @@
-// The action steps of the step language (D43): write, registers, joystick,
+// The action steps of the step language: write, registers, joystick,
 // type, frames and runUntil. c64-testing scenarios and the c64-unpacker
 // steps file share them; each caller adds its own steps around them.
 
@@ -90,12 +90,12 @@ export function checkActionStep(kind: string, step: Record<string, unknown>, at:
       return;
     }
     case "frames":
-      if (!isInteger(step.frames, 1, MAX_EXECUTION_COUNT)) fail(`${at} needs a frame count from 1 to ${MAX_EXECUTION_COUNT}`);
+      if (!isInteger(step.frames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
       return;
     case "runUntil": {
       const target = step.runUntil;
       const keys = isObject(target) ? Object.keys(target).sort().join(",") : "";
-      // at, raster, at with raster (the address only on that line, D46), or memory.
+      // at, raster, at with raster (the address only on that line), or memory.
       if (!["at", "raster", "at,raster", "memory"].includes(keys)) return fail(`${at}: runUntil needs at, raster, at and raster, or memory`);
       const until = target as Record<string, unknown>;
       if ("raster" in until && !isInteger(until.raster, 0, MAX_RASTER_LINE)) fail(`${at}: runUntil.raster must be a raster line from 0 to ${MAX_RASTER_LINE}`);
@@ -154,7 +154,12 @@ export async function runActionStep(client: ViceSessionClient, step: ActionStep,
     await client.keyboard(textToPetscii(step.type));
   } else if ("frames" in step) {
     await stop(client);
-    await client.execution({ action: "advance-frames", count: step.frames, space: "c64" });
+    // One advance-frames runs at most MAX_EXECUTION_COUNT frames. Each part ends at the raster position
+    // where it started, so the parts give the same frames as one run; a breakpoint ends them all.
+    for (let left = step.frames; left > 0; left -= MAX_EXECUTION_COUNT) {
+      const part = await client.execution({ action: "advance-frames", count: Math.min(left, MAX_EXECUTION_COUNT), space: "c64" });
+      if (part.stopReason !== "frames") break;
+    }
   } else {
     const until = step.runUntil;
     const target: RunTarget =

package/src/host-client/tools.ts

@@ -87,3 +87,4 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 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, maskCoversFrame } from "../protocol/vice.ts";
+export { MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, type TraceHit, type TraceKind } from "../protocol/vice.ts";