@henols/c64-re-tools 2.0.0-rc.5 → 2.0.0-rc.7

package/src/host/tools/index.ts

@@ -3,6 +3,7 @@
 // ACME, DXA and Ghidra themselves. One entry per operation, never a
 // generic executable route.
 
+import type { ViceVersion } from "../../native/discover.ts";
 import type { ProcessSupervisor } from "../../native/processes.ts";
 import type { ToolContext } from "../../native/run.ts";
 import type { ToolOperation, ToolOperations } from "../../protocol/tools.ts";
@@ -24,8 +25,11 @@ const ADAPTERS: { [O in ToolOperation]: Adapter<O> } = {
   "petcat.decode": (_params, attachments, context) => decode(attachments[0]!, context),
 };
 
-export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void }): ToolDispatcher {
+/** `vice`: the version that the host read from the emulator at start, for host.status. */
+export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void; vice?: ViceVersion }): ToolDispatcher {
   return (op, params, attachments, signal) => {
-    return ADAPTERS[op](params, attachments, { supervisor: options.supervisor, signal, env: options.env, log: options.log });
+    const context = { supervisor: options.supervisor, signal, env: options.env, log: options.log };
+    if (op === "host.status") return hostStatus(context, options.vice) as ReturnType<ToolDispatcher>;
+    return ADAPTERS[op](params, attachments, context);
   };
 }

package/src/host/tools/petcat.ts

@@ -16,14 +16,17 @@ import { runToolOrFail, type ToolContext } from "../../native/run.ts";
 
 const TIMEOUT_MS = 30_000;
 const LISTING = "listing.txt";
-/** petcat's listing lines ("   10 sys2061"), as number and text. */
+/**
+ * petcat's listing lines ("   10 sys2061"), as number and text. petcat
+ * prints π ($ff) as `~`, which is no PETSCII character: the text has π (F-13).
+ */
 export function parseListing(listing: string): Array<{ number: number; text: string }> {
   const lines: Array<{ number: number; text: string }> = [];
   for (const line of listing.split(/\r?\n/)) {
     if (line.trim() === "") continue;
     const match = /^\s*(\d+) ?(.*)$/.exec(line);
     if (match === null) throw new WireFailure("operation-failed", "petcat printed a listing line without a line number.");
-    lines.push({ number: Number(match[1]), text: match[2]! });
+    lines.push({ number: Number(match[1]), text: match[2]!.replaceAll("~", "π") });
   }
   return lines;
 }

package/src/host/tools/status.ts

@@ -1,9 +1,15 @@
 // host.status: VICE and the tools that come with it, each found the way its
 // operations find it and run once with a version option. A tool from a
 // VICE older than MIN_VICE is reported as not working, as its operations refuse it.
+// VICE itself is reported with the version that the host read from the
+// running emulator at start: the Homebrew x64sc of VICE 3.10 on macOS stops
+// on -version ("argv[0] is NULL") although the emulator runs.
 
-import type { ToolStatus } from "../../protocol/tools.ts";
-import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceFlaws, viceVersionOf, type ToolSpec } from "../../native/discover.ts";
+import { arch, platform, release } from "node:os";
+
+import { PACKAGE } from "../../package.ts";
+import type { HostInfo, ToolStatus } from "../../protocol/tools.ts";
+import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceFlaws, viceVersionOf, type ToolSpec, type ViceVersion } from "../../native/discover.ts";
 import type { ToolContext } from "../../native/run.ts";
 import { probeTools } from "../../native/status.ts";
 import { findVice } from "../vice/process.ts";
@@ -16,21 +22,26 @@ function requireMinimum(status: ToolStatus, tool: ToolSpec): ToolStatus {
   return { ...status, runs: false, problem: `${found}, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${tool.remedy}` };
 }
 
-export async function hostStatus(context: ToolContext): Promise<{ result: { tools: ToolStatus[] } }> {
+/** The version text of a VICE version, as x64sc -version prints it. */
+const versionText = (version: ViceVersion) => `x64sc (VICE ${version.major}.${version.minor}${version.revision === undefined ? "" : ` SVN r${version.revision}`})`;
+
+/** `started`: the version that the host read from the emulator at start; without it, VICE is probed with -version too. */
+export async function hostStatus(context: ToolContext, started?: ViceVersion): Promise<{ result: { host: HostInfo; tools: ToolStatus[] } }> {
   const specs = [VICE, C1541, PETCAT];
-  const tools = await probeTools(
+  const probed = await probeTools(
     [
-      { name: VICE.name, find: findVice, args: ["-version"], pattern: /^x64sc \(VICE \d/ },
+      ...(started === undefined ? [{ name: VICE.name, find: findVice, args: ["-version"], pattern: /^x64sc \(VICE \d/ }] : []),
       { name: C1541.name, find: (env) => findTool(C1541, env), args: ["-version"], pattern: /^c1541 \(VICE \d/ },
       { name: PETCAT.name, find: (env) => findTool(PETCAT, env), args: ["-version"], pattern: /^petcat \(VICE \d/ },
     ],
     context,
   );
+  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).
   const vice = checked[0]!;
   const version = vice.runs ? viceVersionOf(vice.version ?? "") : undefined;
   const flaws = version === undefined ? [] : viceFlaws(version);
   if (flaws.length > 0) checked[0] = { ...vice, flaws };
-  return { result: { tools: checked } };
+  return { result: { host: { version: PACKAGE.version, platform: platform(), release: release(), arch: arch() }, tools: checked } };
 }

package/src/host/vice/adapter.ts

@@ -135,7 +135,7 @@ export function parseDisassembly(answer: string, start: number): Instruction[] {
   for (const line of answer.split("\n")) {
     const match = /^\.(?:C|\d+):([0-9a-f]{4})\s+((?:[0-9a-f]{2} )*[0-9a-f]{2})\s+(.*?)\s*$/i.exec(line);
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     const address = Number.parseInt(match[1]!, 16);
@@ -164,7 +164,7 @@ export function parseHistory(answer: string): Array<Omit<HistoryEntry, "rasterLi
         line,
       );
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     entries.push({
@@ -193,7 +193,7 @@ export function parseHunt(answer: string, limit: number): number[] {
   for (const line of answer.split("\n")) {
     const match = /^([0-9a-f]{4})$/i.exec(line.trim());
     if (match === null) {
-      if (line.trim() !== "") unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     if (matches.length < limit) matches.push(Number.parseInt(match[1]!, 16));
@@ -236,14 +236,15 @@ export function parseProfile(answer: string): ProfileEntry[] {
   const unknown: string[] = [];
   for (const line of answer.split("\n")) {
     // Counts can carry the host locale's digit grouping ("1,123,200") and the percent a decimal comma.
-    const row = new RegExp(`^\\s*(${COUNT})\\s+[\\d.,]+%\\s+(${COUNT})\\s+([\\d.,]+)%\\s+(\\S+)\\s*$`).exec(line);
+    // A profile of zero cycles, as after a window move restarts it, prints its percents as "-nan".
+    const row = new RegExp(`^\\s*(${COUNT})\\s+(?:[\\d.,]+|-?nan)%\\s+(${COUNT})\\s+([\\d.,]+|-?nan)%\\s+(\\S+)\\s*$`, "i").exec(line);
     if (row === null) {
-      if (line.trim() !== "" && !/^Total\s+%\s+Self\s+%$/.test(line.trim()) && !/^[-\s]+$/.test(line)) unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim()) && !/^Total\s+%\s+Self\s+%$/.test(line.trim()) && !/^[-\s]+$/.test(line)) unknown.push(line.trim());
       continue;
     }
     // A row named ROOT or by a label has no routine address.
     if (!/^[0-9a-f]{4}$/i.test(row[4]!)) continue;
-    entries.push({ address: Number.parseInt(row[4]!, 16), totalCycles: digits(row[1]!), selfCycles: digits(row[2]!), percent: Number(row[3]!.replace(",", ".")) });
+    entries.push({ address: Number.parseInt(row[4]!, 16), totalCycles: digits(row[1]!), selfCycles: digits(row[2]!), percent: /nan/i.test(row[3]!) ? 0 : Number(row[3]!.replace(",", ".")) });
   }
   // An answer in another form must not read as "nothing ran".
   if (entries.length === 0 && unknown.length > 0) throw unknownForm("profile", unknown);
@@ -284,7 +285,7 @@ export function parseMemmap(answer: string, maxRanges: number): { ranges: Memmap
   for (const line of answer.split("\n")) {
     const match = /^([0-9a-f]{4}): (\S{3}) (\S{3}) (\S{3})/i.exec(line);
     if (match === null) {
-      if (line.trim() !== "" && !/^addr:\s+IO\s+ROM\s+RAM$/.test(line.trim())) unknown.push(line.trim());
+      if (line.trim() !== "" && !CONDITION_LINE.test(line.trim()) && !/^addr:\s+IO\s+ROM\s+RAM$/.test(line.trim())) unknown.push(line.trim());
       continue;
     }
     const address = Number.parseInt(match[1]!, 16);
@@ -308,12 +309,19 @@ export function parseMemmap(answer: string, maxRanges: number): { ranges: Memmap
  */
 const STOP_LINE = /^(?:#\d+ \((?:Stop on|Trace)\s|\.(?:C|\d+):[0-9a-f]{4}\s)/i;
 
-/** The lines of a text command's answer that are not blank, not a stop line and not `known`. */
+/**
+ * The line VICE prints on the text monitor when the binary monitor sets a
+ * checkpoint condition. It can come late, in the answer of the next text
+ * command (seen on Windows).
+ */
+const CONDITION_LINE = /^Setting checkpoint \d+ condition to: /;
+
+/** The lines of a text command's answer that are not blank, not a stop line, not a condition line and not `known`. */
 function otherLines(answer: string, known?: RegExp): string[] {
   return answer
     .split("\n")
     .map((line) => line.trim())
-    .filter((line) => line !== "" && !STOP_LINE.test(line) && known?.test(line) !== true);
+    .filter((line) => line !== "" && !STOP_LINE.test(line) && !CONDITION_LINE.test(line) && known?.test(line) !== true);
 }
 
 /** Refuses the answer of a text command that prints nothing, or only `known` lines, when it works. */
@@ -631,6 +639,12 @@ export class ViceAdapter {
     await this.#monitor.request(Command.autostart, Buffer.concat([head, name]));
   }
 
+  /** Detaches every cartridge. VICE powers the cartridge off; the C64 keeps running. */
+  async detachCartridge(): Promise<void> {
+    // Device 32 is the cartridge port; the monitor reads numbers as hex. VICE prints nothing when it detaches.
+    expectQuiet("cartridge detach answer", await this.#text.command("detach 20"));
+  }
+
   /** Attaches a disk image file from the host file system to drive 8. */
   async attachDisk(file: string): Promise<void> {
     const answer = await this.#text.command(`attach ${quoted(file)} 8`);

package/src/host/vice/process.ts

@@ -1,5 +1,7 @@
 // VICE launch, readiness and termination. The launch contract of x64sc:
 // - `-default` must come before `-binarymonitor`, or the monitor never binds;
+// - `-config` must come first: VICE's trunk (after 3.10) drops every argument
+//   before it, so the monitors would never start;
 // - the monitor may accept a connection during startup and then drop it, so
 //   readiness is a connect plus a successful ping, retried until a deadline;
 // - any monitor command stops the machine, so readiness ends with `exit`;
@@ -76,6 +78,9 @@ export function viceArguments(options: {
   const headless = options.mode === "headless" ? ["-console", "-sounddev", "dummy"] : [];
   return [
     options.binary,
+    // VICE's trunk (after 3.10) drops every argument before -config, so it comes first.
+    "-config",
+    options.configFile,
     "-default",
     "-logfile",
     options.logFile,
@@ -85,8 +90,6 @@ export function viceArguments(options: {
     "-remotemonitor",
     "-remotemonitoraddress",
     `ip4://127.0.0.1:${options.textPort}`,
-    "-config",
-    options.configFile,
     "-model",
     options.videoStandard === "ntsc" ? "ntsc" : "c64",
     "-drive8type",
@@ -94,6 +97,8 @@ export function viceArguments(options: {
     // Autostart injects a PRG into RAM; the default mode copies it to a disk image first.
     "-autostartprgmode",
     "1",
+    // VICE's default waits a random time before an autostart types its LOAD, so two runs of one file differ (R2-12).
+    "+autostart-delay-random",
     // The same RAM after every power-up: a hard reset is a power cycle, and VICE's default can flip
     // random bits, so two runs from one start state could differ.
     "-raminitstartvalue",
@@ -307,6 +312,7 @@ async function launchOnce(options: LaunchOptions): Promise<ViceProcess> {
         clearInterval(slow);
       }
       if (failure !== undefined) throw failure;
+      log(`VICE stopped (pid ${child.pid}, in ${Date.now() - started} ms)`);
     })();
     return stopping;
   };
@@ -325,7 +331,7 @@ async function launchOnce(options: LaunchOptions): Promise<ViceProcess> {
     if (error instanceof WireFailure) throw error;
     throw new WireFailure("machine-unavailable", "The emulator could not be started on the host.");
   }
-  log(`VICE started (pid ${child.pid}, monitor ports ${port} and ${textPort})`);
+  log(`VICE started (${mode}, pid ${child.pid}, monitor ports ${port} and ${textPort})`);
   trace().event("vice.ready", { pid: child.pid, ms: elapsedMs(launched) });
   return { pid: child.pid, monitor, text, exited: child.exited, outputTail, stop };
 }

package/src/host/vice/session.ts

@@ -125,6 +125,20 @@ export interface SessionOptions {
   flaws?: readonly string[];
 }
 
+/**
+ * Where VICE keeps a staged file: an autostarted disk stays in drive 8, a tape
+ * in the datasette and a cartridge in the port, until the same place gets
+ * another file. Only a program is read once.
+ */
+type StagedKind = "program" | "disk" | "tape" | "cartridge";
+
+function stagedKind(type: string): StagedKind {
+  if (type === "crt") return "cartridge";
+  if (type === "tap" || type === "t64") return "tape";
+  if (type === "prg" || type === "p00") return "program";
+  return "disk";
+}
+
 export class ViceSession implements ViceSessionHandle {
   /** The current VICE. A window move replaces it. */
   #vice: ViceProcess;
@@ -179,8 +193,10 @@ export class ViceSession implements ViceSessionHandle {
   #timingStart = 0n;
   /** Counts staged media files, for unique names. */
   #staged = 0;
+  /** True after an autostart of a cartridge, until an autostart of another file detaches it. */
+  #cartridge = false;
   /** The last staged file of each kind that VICE took; VICE can still read it. */
-  readonly #stagedFiles = new Map<"autostart" | "disk", string>();
+  readonly #stagedFiles = new Map<StagedKind, string>();
   /** Session-local ids: one counter for breakpoints and watchpoints, from 1. */
   #nextPointId = 1;
   /**
@@ -359,9 +375,18 @@ export class ViceSession implements ViceSessionHandle {
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
         const file = this.#stage(onlyAttachment(attachments), type);
+        // VICE keeps a cartridge through every reset and autostart, as a real C64 does.
+        if (type !== "crt" && this.#cartridge) {
+          await this.#observe(() => this.#machine.detachCartridge());
+          this.#cartridge = false;
+          this.#replaceStaged("cartridge", undefined);
+        }
         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 } : {}) };
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
@@ -474,6 +499,7 @@ 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" };
+    if (this.#cartridge) status.cartridge = true;
     if (status.state === "stopped") status.pc = await this.#pc();
     return status;
   }
@@ -531,6 +557,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" };
@@ -817,14 +845,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. */
@@ -988,6 +1023,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"),
@@ -1073,10 +1109,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;
@@ -1354,8 +1392,7 @@ export function viceSessionFactory(options: {
   /** The known flaws of the VICE version that the host checked at start. */
   flaws?: readonly string[];
 }): ViceSessionFactory {
-  const log = options.log ?? (() => {});
-  return async ({ videoStandard }) => {
+  return async ({ videoStandard, log = options.log ?? (() => {}) }) => {
     const launch: ViceLauncher = (mode, launchLog) =>
       launchVice({
         videoStandard,

package/src/host-client/connect.ts

@@ -4,7 +4,7 @@ import { connect as connectTcp, type Socket } from "node:net";
 
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { elapsedMs, trace } from "../trace.ts";
-import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, withStopAndAsk, type ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, withStopAndAsk, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
 import { PACKAGE } from "../package.ts";
 
 export interface Endpoint {
@@ -37,19 +37,19 @@ export function hostEndpoints(env: NodeJS.ProcessEnv = process.env): Endpoint[]
   return ["127.0.0.1", "host.docker.internal", "host.containers.internal"].map((host) => ({ host, port: DEFAULT_HOST_PORT }));
 }
 
-function unreachable(role: Role): WireFailure {
-  const code: ErrorCode = role === "vice-session" ? "machine-unavailable" : "operation-failed";
+/** A host that does not run or cannot be reached is machine-unavailable for every role (D37). */
+function unreachable(): WireFailure {
   return new WireFailure(
-    code,
+    "machine-unavailable",
     withStopAndAsk(
       `The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host) and try again.`,
     ),
   );
 }
 
-function stopped(role: Role): WireFailure {
+function stopped(): WireFailure {
   return new WireFailure(
-    role === "vice-session" ? "machine-unavailable" : "operation-failed",
+    "machine-unavailable",
     "The connection to the c64-re-tools host runtime stopped before the host runtime was ready.",
   );
 }
@@ -146,9 +146,9 @@ export class HostConnection {
     }
     if (signal?.aborted) {
       socket?.destroy();
-      throw stopped(options.role);
+      throw stopped();
     }
-    if (socket === undefined) throw unreachable(options.role);
+    if (socket === undefined) throw unreachable();
 
     const connection = new HostConnection(socket);
     const hello: Hello = { type: "hello", protocol: HOST_PROTOCOL_ID, version: HOST_PROTOCOL_VERSION, role: options.role };
@@ -172,7 +172,7 @@ export class HostConnection {
     signal?.removeEventListener("abort", stop);
     if (signal?.aborted) {
       await connection.close();
-      throw stopped(options.role);
+      throw stopped();
     }
 
     if (!(answer instanceof Error) && answer.type === "ready") {
@@ -190,7 +190,7 @@ export class HostConnection {
         );
       }
       throw new WireFailure(
-        options.role === "vice-session" ? "machine-unavailable" : "operation-failed",
+        "machine-unavailable",
         "The c64-re-tools host runtime did not finish the handshake. Check that it is running and try again.",
       );
     }

package/src/host-client/coverage.ts

@@ -9,23 +9,32 @@ import type { ViceSessionClient } from "./vice-session.ts";
 /** A full coverage file: offset n is address n (D40). */
 export const FULL_COVERAGE = 0x10000;
 
-/**
- * Reads full coverage files from the project and joins them: an address has
- * every flag that any run gave it. `fail` refuses a file of another size.
- */
-export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
-  if (paths.length === 0) return undefined;
-  const joined = new Uint8Array(FULL_COVERAGE);
-  for (const path of paths) {
+/** Reads full coverage files from the project, one map per file. `fail` refuses a file of another size. */
+export function readCoverageMaps(paths: string[], fail: (message: string) => never): Uint8Array[] {
+  return paths.map((path) => {
     const { bytes } = readProjectFile(path);
     if (bytes.length !== FULL_COVERAGE) {
       fail(`--coverage ${path} has ${bytes.length} bytes; a full coverage file has 65536, one for each address. Write it with c64_memmap action read and out, without start and end.`);
     }
-    for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= bytes[address]!;
-  }
+    return bytes;
+  });
+}
+
+/** Joins coverage maps: an address has every flag that any run gave it. */
+export function joinCoverage(maps: readonly Uint8Array[]): Uint8Array {
+  const joined = new Uint8Array(FULL_COVERAGE);
+  for (const map of maps) for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= map[address]!;
   return joined;
 }
 
+/**
+ * Reads full coverage files from the project and joins them: an address has
+ * every flag that any run gave it. `fail` refuses a file of another size.
+ */
+export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
+  return paths.length === 0 ? undefined : joinCoverage(readCoverageMaps(paths, fail));
+}
+
 /** The coverage bytes of start..end, read from the session in parts. */
 export async function readCoverage(session: Pick<ViceSessionClient, "memmap">, start = 0x0000, end = 0xffff): Promise<Uint8Array> {
   const map = new Uint8Array(end - start + 1);

package/src/host-client/tools.ts

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

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

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

package/src/knowledge/schema.ts

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

package/src/knowledge/write.ts

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

package/src/mcp/tools/debug.ts

@@ -129,7 +129,7 @@ export const c64CpuHistory = defineTool({
   description:
     "Get the last instructions that the CPU executed, oldest first. " +
     `limit is the number of instructions (1 to ${MAX_HISTORY}, default 50). ` +
-    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp. " +
+    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp before the instruction executed. " +
     "In space c64, it also gives the raster line and cycle when the instruction started. " +
     "With out, it writes the entries as text lines to that project file, and the result gives the file in place of the entries. " +
     "This does not change the run state of the machine.",
@@ -191,7 +191,8 @@ export const c64Timing = defineTool({
   title: "Cycle stopwatch",
   description:
     "A stopwatch that counts C64 CPU cycles. Action start sets it to zero. Action read gives the cycles since the last start, " +
-    "or since the session started, as a decimal string. A PAL frame has 19656 cycles and an NTSC frame 17095.",
+    "or since the session started, as a decimal string. A reset and c64_autostart start it again from the reset. " +
+    "A PAL frame has 19656 cycles and an NTSC frame 17095.",
   inputSchema: z.object({ action: z.enum(TIMING_ACTIONS) }).strict(),
   outputSchema: z.object({ started: z.boolean().optional(), cycles: z.string().regex(/^\d+$/).optional() }),
   readOnly: false,

package/src/mcp/tools/machine.ts

@@ -13,7 +13,8 @@ export const c64Status = defineTool({
   description:
     "Get the state of the C64. The result tells if the CPU runs or has stopped, the video standard (pal or ntsc), " +
     "and if warp mode is on. It also tells if the emulator window is open (window). " +
-    "When the CPU has stopped, the result also gives the program counter (pc).",
+    "When the CPU has stopped, the result also gives the program counter (pc). " +
+    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it.",
   inputSchema: z.object({}).strict(),
   outputSchema: z.object({
     state: z.enum(RUN_STATES),
@@ -21,6 +22,7 @@ export const c64Status = defineTool({
     warp: z.boolean(),
     window: z.boolean().describe("true when the emulator window is open (c64_window)"),
     pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
+    cartridge: z.literal(true).optional().describe("true while a cartridge is attached. Absent when none is"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -31,6 +33,7 @@ export const c64Status = defineTool({
       warp: status.warp,
       window: status.window,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
+      ...(status.cartridge === undefined ? {} : { cartridge: status.cartridge }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -20,6 +20,7 @@ export const c64Autostart = defineTool({
   description:
     `Start a program, or a disk, tape or cartridge image, from the project (${list(AUTOSTART_TYPES)}). ` +
     "The C64 resets and loads the file. With run true (the default), it also runs the file. A disk image stays in drive 8. " +
+    "A cartridge stays in the C64 through every reset, as on a real C64. An autostart of a file that is not a cartridge detaches it first. " +
     "Without index, a disk image loads like LOAD\"*\",8,1. index selects one directory entry by its number in the c64-disk directory list (0 is the first entry). " +
     "The machine runs when this tool returns, and the load continues.",
   inputSchema: z
@@ -29,7 +30,10 @@ export const c64Autostart = defineTool({
       run: z.boolean().default(true).describe("true runs the program after it loads"),
     })
     .strict(),
-  outputSchema: z.object({ state: z.enum(RUN_STATES) }),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    emulatorFlaw: z.string().optional().describe("for a tape image: a known flaw of this VICE version that stops a tape load"),
+  }),
   readOnly: false,
   async run(input, session) {
     // VICE numbers the directory entries from 1, and its 0 loads "*".

package/src/mcp/tools/video.ts

@@ -133,6 +133,7 @@ export const c64Screen = defineTool({
     "With out, capture writes the PNG to that project file, and compare writes its difference image there. The result then has no image. " +
     "With baseline, the session also keeps that frame under the name. " +
     "Action compare compares the current frame with a baseline, pixel by pixel. mask lists rectangles to ignore. " +
+    "A mask that covers the whole frame is invalid input. comparedPixels is the number of pixels outside the mask. " +
     "match is true when the part of compared pixels that differ is at most maxMismatchRatio (default 0). bounds holds every different pixel. " +
     "With includeDiff, compare also returns an image with the different pixels in magenta. " +
     "Action list gives the baseline names. Action discard removes a baseline. Baselines stay until the session ends. " +
@@ -154,6 +155,7 @@ export const c64Screen = defineTool({
     baseline: z.string().optional(),
     match: z.boolean().optional(),
     mismatchingPixels: z.number().int().min(0).optional(),
+    comparedPixels: z.number().int().min(1).optional(),
     mismatchRatio: z.number().min(0).max(1).optional(),
     bounds: Rectangle.optional(),
     baselines: z.array(z.string()).optional(),