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

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

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. */
@@ -1074,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;

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(),

package/src/native/discover.ts

@@ -96,7 +96,8 @@ const VICE_FLAWS = [
     text:
       "VICE 3.10 and older hold bits 5-7 of CIA 1 ports A and B low with the joystick device that c64-re-tools uses (VICE bug #2202). " +
       "$DC00 and $DC01 read $1F with no input. A program that waits for one key of the keyboard matrix (for example LDA $DC01 / CMP #$EF for SPACE) waits forever. " +
-      "A program that compares the full byte of a joystick port also waits forever. The fix is in the next VICE release, and in VICE nightly builds now (SVN r45971 or later). " +
+      "A program that compares the full byte of a joystick port also waits forever. " +
+      "A KERNAL tape LOAD of a .tap image stops after FOUND, with no LOADING, and the C64 shows READY. The fix is in the next VICE release, and in VICE nightly builds now (SVN r45971 or later). " +
       "Install the latest VICE when this matters.",
   },
 ] as const;

package/src/platform.ts

@@ -345,12 +345,13 @@ export function lookup(address: number): Lookup {
  * The platform name of each named address (D52): system variables, ROM
  * entries and I/O registers, not mirrors, in address order. Only names that
  * an assembler can use as a symbol, and each name once, at its lowest address.
+ * `end` is the last address of the entry: a vector has two bytes.
  */
-export function platformNames(): Array<{ address: number; name: string; meaning: string }> {
+export function platformNames(): Array<{ address: number; end: number; name: string; meaning: string }> {
   const io = IO.flatMap((block) => block.registers);
   const seen = new Set<string>();
   return [...SYSTEM, ...ROM, ...io]
-    .map((entry) => ({ address: entry.start, name: entry.name, meaning: entry.meaning }))
+    .map((entry) => ({ address: entry.start, end: entry.end, name: entry.name, meaning: entry.meaning }))
     .filter((entry) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.name))
     .sort((a, b) => a.address - b.address)
     .filter((entry) => !seen.has(entry.name) && seen.add(entry.name) !== undefined);

package/src/protocol/tools.ts

@@ -41,7 +41,8 @@ export interface DiskSector {
 
 export type C1541Result =
   | { action: "directory"; diskName: string; diskId: string; dosType: string; freeBlocks: number; entries: DiskFile[] }
-  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> }
+  /** unreferenced: the used sectors that no file, the header, the directory or the BAM holds. */
+  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }>; unreferenced: DiskSector[] }
   | { action: "entry"; found: false }
   | { action: "entry"; found: true; entry: DiskFile & { startTrack: number; startSector: number } }
   | { action: "chain"; found: false }
@@ -83,8 +84,18 @@ export interface ToolStatus {
   flaws?: string[];
 }
 
+/** The Host Runtime itself: its package version and the system it runs on. */
+export interface HostInfo {
+  version: string;
+  /** Node's name of the operating system: linux, darwin or win32. */
+  platform: string;
+  /** The release of the operating system. */
+  release: string;
+  arch: string;
+}
+
 export interface ToolOperations {
-  "host.status": { params: Record<string, never>; result: { tools: ToolStatus[] } };
+  "host.status": { params: Record<string, never>; result: { host: HostInfo; tools: ToolStatus[] } };
   "c1541.inspect": { params: C1541Params; result: C1541Result };
   "petcat.decode": { params: PetcatParams; result: PetcatResult };
 }
@@ -177,7 +188,9 @@ export function validateToolResult<O extends ToolOperation>(op: O, value: unknow
         typeof tool.runs === "boolean" &&
         [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string") &&
         (tool.flaws === undefined || (Array.isArray(tool.flaws) && tool.flaws.every((flaw: unknown) => typeof flaw === "string")));
-      if (!Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
+      const host = value.host;
+      const isHost = isObject(host) && [host.version, host.platform, host.release, host.arch].every((field) => typeof field === "string");
+      if (!isHost || !Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
       return value as unknown as ToolOperations[O]["result"];
     }
   }
@@ -214,7 +227,9 @@ function isC1541Result(value: Fields, attachments: readonly Uint8Array[]): boole
     case "bam":
       return (
         Array.isArray(value.tracks) &&
-        value.tracks.every((track) => isObject(track) && isInteger(track.track, 1, 255) && isSectorList(track.freeSectors) && isSectorList(track.usedSectors))
+        value.tracks.every((track) => isObject(track) && isInteger(track.track, 1, 255) && isSectorList(track.freeSectors) && isSectorList(track.usedSectors)) &&
+        Array.isArray(value.unreferenced) &&
+        value.unreferenced.every(isTrackSector)
       );
     case "entry":
       return (