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

package/src/host/main.ts

@@ -7,6 +7,7 @@ import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
 import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
 import { viceFlaws, type ViceVersion } from "../native/discover.ts";
+import { inspect } from "./tools/c1541.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
@@ -34,8 +35,9 @@ Options:
                            directory, with a copy of each VICE log.
   --help                   Show this help.
 
-Without --log-console and --log-dir the host logs only its start, its stop,
-connections and failures. C64RT_TRACE does not apply to the host.`;
+The host always logs its start and stop, connections, failures, and each call
+from a skill script (c1541, petcat) with its outcome. --log-console adds the
+calls of the MCP server and the tool runs. C64RT_TRACE does not apply to the host.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-host: ${line}\n`);
@@ -76,6 +78,9 @@ async function main(): Promise<number> {
     return 2;
   }
 
+  // First, so that every start, also a refused one, tells which runtime runs.
+  log(`${PACKAGE.name} ${PACKAGE.version} (Node.js ${process.version}, ${process.platform} ${process.arch})`);
+
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
     findVice(process.env);
@@ -101,7 +106,7 @@ async function main(): Promise<number> {
   }
   log(`VICE ${vice.major}.${vice.minor}${vice.revision === undefined ? "" : ` r${vice.revision}`} starts`);
   const flaws = viceFlaws(vice);
-  // A known VICE flaw is named, not worked around (D56).
+  // A known VICE flaw is named, not worked around.
   for (const flaw of flaws) log(`Known VICE flaw: ${flaw}`);
 
   let server;
@@ -110,7 +115,16 @@ async function main(): Promise<number> {
       host: "0.0.0.0",
       port,
       log,
-      createViceSession: viceSessionFactory({ supervisor, log, flaws }),
+      createViceSession: viceSessionFactory({
+        supervisor,
+        log,
+        flaws,
+        // c1541 lists the disk, so an autostart index selects a program.
+        directory: async (imageType, image) => {
+          const { result } = await inspect({ action: "directory", imageType }, image, { supervisor, signal: new AbortController().signal, log });
+          return result.action === "directory" ? result.entries : [];
+        },
+      }),
       tools: createToolDispatcher({ supervisor, log, vice }),
     });
   } catch (error) {

package/src/host/server.ts

@@ -4,7 +4,7 @@ import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { checkHello, isOneOf, HEARTBEAT_TIMEOUT_MS, parseClientMessage, ProtocolError, type HostMessage, type ReceivedRequest, type VideoStandard, type WireError, WireFailure } from "../protocol/messages.ts";
 import { TOOL_OPERATIONS, validateToolParams, type ToolOperation, type ToolOperations } from "../protocol/tools.ts";
 import { attachmentCount, VICE_OPERATIONS, validateViceParams, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
-import { elapsedMs, trace } from "../trace.ts";
+import { elapsedMs, summarize, trace } from "../trace.ts";
 
 /** One live VICE session, owned by one connection. */
 export interface ViceSessionHandle {
@@ -234,8 +234,15 @@ class Connection {
 
   async #answer(request: ReceivedRequest, attachments: Buffer[]): Promise<void> {
     const started = performance.now();
-    const record = (outcome: Record<string, unknown>) =>
-      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms: elapsedMs(started), ...outcome });
+    const record = (outcome: Record<string, unknown>) => {
+      const ms = elapsedMs(started);
+      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms, ...outcome });
+      // A call from a skill script (c1541, petcat, status) is always logged; the many calls of a VICE session only in the trace.
+      if (this.#isTool) {
+        const what = outcome.ok === true ? "ok" : `${String(outcome.code)}: ${String(outcome.message)}`;
+        this.#log(`${request.op} ${JSON.stringify(summarize(request.params) ?? {})}: ${what} (${ms} ms)`);
+      }
+    };
     try {
       let result: unknown;
       let replyAttachments: Buffer[] = [];

package/src/host/tools/petcat.ts

@@ -18,7 +18,7 @@ const TIMEOUT_MS = 30_000;
 const LISTING = "listing.txt";
 /**
  * petcat's listing lines ("   10 sys2061"), as number and text. petcat
- * prints π ($ff) as `~`, which is no PETSCII character: the text has π (F-13).
+ * prints π ($ff) as `~`, which is no PETSCII character: the text has π.
  */
 export function parseListing(listing: string): Array<{ number: number; text: string }> {
   const lines: Array<{ number: number; text: string }> = [];

package/src/host/tools/status.ts

@@ -38,7 +38,7 @@ export async function hostStatus(context: ToolContext, started?: ViceVersion): P
   );
   const tools = started === undefined ? probed : [{ name: VICE.name, found: true, path: findVice(context.env ?? process.env), version: versionText(started), runs: true }, ...probed];
   const checked = tools.map((status, index) => requireMinimum(status, specs[index]!));
-  // VICE runs with its known flaws; status names them (D56).
+  // VICE runs with its known flaws; status names them.
   const vice = checked[0]!;
   const version = vice.runs ? viceVersionOf(vice.version ?? "") : undefined;
   const flaws = version === undefined ? [] : viceFlaws(version);

package/src/host/vice/adapter.ts

@@ -4,7 +4,8 @@
 import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
 import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry, type Instruction, type MemmapRange, type ProfileEntry, type JoystickState, type MemoryView, type RegisterValues, type Registers, type Space } from "../../protocol/vice.ts";
 import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
-import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
+import type { IndexedFrame } from "../../graphics.ts";
+import { decodeDisplay, decodePalette, visibleFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
 import type { CiaHidden } from "./chips.ts";
 import {
@@ -260,7 +261,7 @@ function unknownForm(what: string, lines: string[]): WireFailure {
   return new WireFailure("operation-failed", `VICE printed the ${what} in a form that c64-re-tools does not read: ${JSON.stringify(lines.slice(0, 3))}`);
 }
 
-/** The coverage byte (D40) of one memmap row's I/O, ROM and RAM columns, each "rwx" with "-" for no access. */
+/** The coverage byte of one memmap row's I/O, ROM and RAM columns, each "rwx" with "-" for no access. */
 export function memmapFlags(io: string, rom: string, ram: string): number {
   let flags = 0;
   if (ram[0] === "r") flags |= COVERAGE.ramRead;
@@ -434,7 +435,7 @@ export class ViceAdapter {
 
   /**
    * The timer latches and the interrupt mask of the CIA at `base`, from VICE's
-   * text-monitor dump: no register read gives them (D63).
+   * text-monitor dump: no register read gives them.
    */
   async ciaHidden(base: 0xdc00 | 0xdd00): Promise<CiaHidden> {
     const answer = await this.#computerText(`io ${hex4(base)}`);

package/src/host/vice/process.ts

@@ -12,7 +12,7 @@
 // - autostart of a PRG needs `-autostartprgmode 1` (inject into RAM);
 // - the joyport command reaches the C64 only through the "Joyport I/O
 //   simulation" device (37). In VICE 3.10 and older it holds bits 5-7 of
-//   both CIA 1 ports low (VICE bug #2202, a known flaw named by D56);
+//   both CIA 1 ports low (VICE bug #2202, a known flaw);
 // - with the default JAM action a jammed CPU hangs silently; -jamaction 2
 //   enters the monitor instead;
 // - the monitor's profiler prints numbers in the host locale, so VICE runs
@@ -97,7 +97,7 @@ 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).
+    // VICE's default waits a random time before an autostart types its LOAD, so two runs of one file differ.
     "+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.

package/src/host/vice/screen.ts

@@ -1,18 +1,10 @@
 // Canonical emulator-frame capture: VICE's own rendered VIC-II frame, never a
 // desktop screenshot; the frame comparison and difference image for baselines.
 
-import { crc32, deflateSync } from "node:zlib";
-
+import type { IndexedFrame } from "../../graphics.ts";
 import type { VideoStandard } from "../../protocol/messages.ts";
 import { FRAME_SIZE } from "../../protocol/vice.ts";
 
-export interface IndexedFrame {
-  width: number;
-  height: number;
-  /** One palette index per pixel, row by row. */
-  pixels: Uint8Array;
-}
-
 export interface RawDisplay {
   /** Full buffer size, blanking included. */
   bufferWidth: number;
@@ -83,39 +75,6 @@ export function decodePalette(body: Buffer): Array<[number, number, number]> {
   return colours;
 }
 
-function chunk(type: string, data: Uint8Array): Buffer {
-  const length = Buffer.alloc(4);
-  length.writeUInt32BE(data.length, 0);
-  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(body), 0);
-  return Buffer.concat([length, body, crc]);
-}
-
-/** Encodes an indexed frame as an 8-bit palette PNG. */
-export function encodePng(frame: IndexedFrame, palette: ReadonlyArray<readonly [number, number, number]>): Buffer {
-  for (const index of frame.pixels) {
-    if (index >= palette.length) throw new Error(`pixel colour ${index} is not in the ${palette.length}-colour palette`);
-  }
-  const header = Buffer.alloc(13);
-  header.writeUInt32BE(frame.width, 0);
-  header.writeUInt32BE(frame.height, 4);
-  header[8] = 8; // bit depth
-  header[9] = 3; // indexed colour
-  const rows = Buffer.alloc((frame.width + 1) * frame.height);
-  for (let row = 0; row < frame.height; row++) {
-    // Filter byte 0 (none), then the row.
-    rows.set(frame.pixels.subarray(row * frame.width, (row + 1) * frame.width), row * (frame.width + 1) + 1);
-  }
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    chunk("IHDR", header),
-    chunk("PLTE", Buffer.from(palette.flat())),
-    chunk("IDAT", deflateSync(rows)),
-    chunk("IEND", new Uint8Array(0)),
-  ]);
-}
-
 export interface FrameDifference {
   mismatchingPixels: number;
   /** Pixels compared: the frame minus the masked ones. */

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",