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

package/skills/c64-testing/scripts/scenario.ts

@@ -4,7 +4,7 @@
 // explicit, and the result is PASS, FAIL or INCONCLUSIVE.
 
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
-import { MAX_BASELINES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, WireFailure } from "#src/host-client/tools.ts";
+import { MAX_BASELINES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, maskCoversFrame, WireFailure } from "#src/host-client/tools.ts";
 import { LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, runProgram } from "#src/host-client/autostart.ts";
 import { ACTION_STEP_KEYS, checkActionStep, checkLocation, isInteger, isObject, runActionStep, type ActionStep, type Location } from "#src/host-client/steps.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
@@ -129,7 +129,7 @@ export function readScenario(path: string): Scenario {
     const allowed = [...(STEP_KEYS[kind] ?? [kind]), ...(kind === "observe" ? [] : ["side"])];
     for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
     if (step.side !== undefined && !(SIDES as unknown[]).includes(step.side)) fail(`${at}: side must be original or rebuild`);
-    checkStep(kind, step, at, fail);
+    checkStep(kind, step, at, fail, scenario.videoStandard ?? "pal");
     if (kind === "observe") {
       if (labels.has(step.observe as string)) fail(`${at} needs a new checkpoint name`);
       labels.add(step.observe as string);
@@ -142,7 +142,7 @@ export function readScenario(path: string): Scenario {
 }
 
 /** Checks the value of one step against its kind. */
-function checkStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never): void {
+function checkStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never, videoStandard: "pal" | "ntsc"): void {
   switch (kind) {
     case "reset":
       if (step.reset !== "hard" && step.reset !== "soft") fail(`${at}: reset must be hard or soft`);
@@ -165,11 +165,11 @@ function checkStep(kind: string, step: Record<string, unknown>, at: string, fail
     case "runUntil":
       return checkActionStep(kind, step, at, fail);
     default:
-      checkObserve(step, at, fail);
+      checkObserve(step, at, fail, videoStandard);
   }
 }
 
-function checkObserve(step: Record<string, unknown>, at: string, fail: (message: string) => never): void {
+function checkObserve(step: Record<string, unknown>, at: string, fail: (message: string) => never, videoStandard: "pal" | "ntsc"): void {
   if (typeof step.observe !== "string" || step.observe === "") fail(`${at} needs a new checkpoint name`);
   if (step.memory !== undefined) {
     if (!Array.isArray(step.memory) || step.memory.length === 0) fail(`${at}: memory must be a list of names, $ addresses or objects with at`);
@@ -216,6 +216,8 @@ function checkObserve(step: Record<string, unknown>, at: string, fail: (message:
           isInteger(rectangle.height, 1, 4096);
         if (!ok) fail(`${at}: a screen.mask rectangle needs whole numbers x and y from 0, and width and height from 1`);
       }
+      // The emulator refuses such a compare too, but only after the original side ran (b2/03).
+      if (maskCoversFrame(screen.mask as Array<{ x: number; y: number; width: number; height: number }>, videoStandard)) fail(`${at}: screen.mask covers the whole screen, so nothing is compared`);
     }
   }
   if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);

package/skills/c64-unpacker/SKILL.md

@@ -36,7 +36,7 @@ node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
 | `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
-| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. |
+| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. The scripts start the program as a c64-testing scenario does. Thus the same steps in a scenario get the program to the entry at the same time. |
 | `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
 | `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
 | `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
@@ -76,7 +76,7 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `image.bin`: all 64 KiB of RAM at the entry.
    - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
    - One PRG for each segment.
-   - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
+   - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `cia` gives the CIA timer latches and interrupt masks. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
 5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it.
 6. Give `image.bin` to the c64-static-analysis skill with its `--flat64k` option, or give it the segment PRGs.
 7. Use `--range` only when you know the area of the program. Then the capture writes that one segment.

package/skills/c64-unpacker/scripts/loads.ts

@@ -4,8 +4,8 @@
 // image with its entry state, and with --drive the drive RAM as a PRG for
 // knowledge space drive8. No tool guesses where a load ends: the steps decide.
 
-import { COVERAGE, formatC64Address, parseC64Address, textToPetscii } from "#src/c64.ts";
-import { autostartLoaded, LOAD_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
+import { COVERAGE, formatC64Address, parseC64Address } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage } from "#src/host-client/coverage.ts";
 import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
@@ -113,7 +113,8 @@ export async function loads(program: string, options: { out: string; steps: Load
       previous.fill(0, load, Math.min(0x10000, load + bytes.length - 2));
       loadedProgram = bytes;
       await client.memmap({ action: "clear" });
-      await client.keyboard(textToPetscii("RUN\n"));
+      // RUN as c64-testing types it: the steps start at the same time as a scenario's (D62).
+      if (!(await typeRun(client))) return { output: { loaded: false, reason: `After RUN, BASIC ran no program line in ${RUN_LIMIT_FRAMES} frames.` }, failed: true };
     } else {
       // A disk, tape or cartridge: VICE loads and starts it. The RAM test of the KERNAL puts back what it writes.
       previous = await readRam(client, 0x0000, 0x10000);

package/skills/c64-unpacker/scripts/machine.ts

@@ -14,10 +14,19 @@ export const IO_AREAS = { vic: [0xd000, 0x2f], sid: [0xd400, 0x1d], cia1: [0xdc0
 /** Frames from a hard reset to the READY prompt, with margin. */
 export const READY_FRAMES = 200;
 
+/** What no register read of a CIA gives (D63). */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
 export interface MachineState {
   port: Buffer;
   pages: Buffer;
   io: Record<keyof typeof IO_AREAS, Buffer>;
+  /** The timer latches and the interrupt mask of each CIA. */
+  cia: { cia1: CiaHidden; cia2: CiaHidden };
   romVectors: Buffer;
 }
 
@@ -36,8 +45,9 @@ export async function machineState(client: ViceSessionClient): Promise<MachineSt
   const pages = await readRam(client, 0x0000, 0x400);
   const io = {} as Record<keyof typeof IO_AREAS, Buffer>;
   for (const [name, [address, size]] of Object.entries(IO_AREAS)) io[name as keyof typeof IO_AREAS] = Buffer.from((await client.ioRead(address, size)).data, "hex");
+  const [cia1, cia2] = (await client.cia("both")).chips.map(({ latchA, latchB, interruptMask }) => ({ latchA, latchB, interruptMask }));
   const romVectors = Buffer.from((await client.memoryRead({ address: 0xfffa, size: 6, space: "c64", view: "cpu" })).data, "hex");
-  return { port, pages, io, romVectors };
+  return { port, pages, io, cia: { cia1: cia1!, cia2: cia2! }, romVectors };
 }
 
 const word = (bytes: Buffer, offset: number) => formatC64Address(bytes[offset]! | (bytes[offset + 1]! << 8));
@@ -60,6 +70,8 @@ export function entryState(registers: Registers, state: MachineState, vectors: R
     cpuPort: { $00: state.port[0], $01: state.port[1] },
     pages: Object.fromEntries([0, 1, 2, 3].map((page) => [formatC64Address(page << 8), state.pages.subarray(page << 8, (page + 1) << 8).toString("hex")])),
     io: Object.fromEntries(Object.entries(IO_AREAS).map(([name, [address]]) => [name, { from: formatC64Address(address), bytes: state.io[name as keyof typeof IO_AREAS].toString("hex") }])),
+    // The CIA latches and interrupt masks: write-only on the chip, so the I/O bytes do not hold them (D63).
+    cia: state.cia,
     vectors,
     ...(differsFromReset === undefined ? {} : { differsFromReset }),
   };

package/skills/c64-unpacker/scripts/unpack.ts

@@ -8,8 +8,8 @@
 
 import { parseArgs } from "node:util";
 
-import { COVERAGE, EXECUTE, formatC64Address, parseC64Address, READ, textToPetscii, WRITE } from "#src/c64.ts";
-import { autostartLoaded, LOAD_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
+import { COVERAGE, EXECUTE, formatC64Address, parseC64Address, READ, WRITE } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES, RUN_LIMIT_FRAMES, typeRun } from "#src/host-client/autostart.ts";
 import { readCoverage, writtenBlocks } from "#src/host-client/coverage.ts";
 import { checkActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
@@ -107,10 +107,8 @@ async function trace(program: string, options: { frames: number; entry?: number;
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
     // Loaded but not started, so the memory map can start empty: the KERNAL start-up writes all of RAM.
-    if (!(await autostartLoaded(client, program, bytes))) return { output: { traced: false, reason: `The program was not in memory at ${formatC64Address(load)} after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
-    await client.memmap({ action: "clear" });
-    if (options.entry !== undefined) await client.registersSet("c64", { pc: options.entry });
-    else await client.keyboard(textToPetscii("RUN\n"));
+    const notStarted = await startLoaded(client, program, bytes, options.entry);
+    if (notStarted !== undefined) return { output: { traced: false, reason: notStarted }, failed: true };
     const stepFailed = await runSteps(client, options.steps);
     if (stepFailed !== undefined) return { output: { traced: false, reason: stepFailed }, failed: true };
     let ran = 0;
@@ -191,6 +189,26 @@ const SYS_FRAMES = 50;
  * The first PC in the program after its BASIC text, for a SYS whose address
  * BASIC computes: an exec breakpoint over that part of the program stops there.
  */
+/**
+ * Starts the program as a c64-testing scenario does (D62): hard reset, load,
+ * an empty memory map, then RUN up to the first BASIC line, or the pc at
+ * `entry`. Gives why it did not start.
+ */
+async function startLoaded(client: ViceSessionClient, program: string, bytes: Uint8Array, entry: number | undefined): Promise<string | undefined> {
+  await client.reset({ mode: "hard", run: false });
+  if (!(await autostartLoaded(client, program, bytes))) return `The program was not in memory at ${formatC64Address(bytes[0]! | (bytes[1]! << 8))} after ${LOAD_LIMIT_FRAMES} frames.`;
+  await client.memmap({ action: "clear" });
+  if (entry !== undefined) await client.registersSet("c64", { pc: entry });
+  else if (!(await typeRun(client))) return `After RUN, BASIC ran no program line in ${RUN_LIMIT_FRAMES} frames.`;
+  return undefined;
+}
+
+/** The raster position now: where a step's frames end (D62). */
+async function rasterAt(client: ViceSessionClient): Promise<{ line: number; cycle: number }> {
+  const { timing } = await client.observe({ timing: true });
+  return { line: timing!.rasterLine, cycle: timing!.rasterCycle };
+}
+
 async function firstPcAfterBasic(client: ViceSessionClient, from: number, to: number): Promise<number | undefined> {
   return from > to ? undefined : firstPcIn(client, [{ start: from, end: to }]);
 }
@@ -246,10 +264,11 @@ async function follow(
   const load = bytes[0]! | (bytes[1]! << 8);
   const basic = basicStart(bytes);
   if (options.entry === undefined && basic === undefined) throw new UsageError(NO_BASIC);
-  if (!(await autostartLoaded(client, program, bytes))) return { stages: [], frames: 0, reached: false, failed: `The program was not in memory at ${formatC64Address(load)} after ${LOAD_LIMIT_FRAMES} frames.` };
-  await client.memmap({ action: "clear" });
-  if (options.entry !== undefined) await client.registersSet("c64", { pc: options.entry });
-  else await client.keyboard(textToPetscii("RUN\n"));
+  const notStarted = await startLoaded(client, program, bytes, options.entry);
+  if (notStarted !== undefined) return { stages: [], frames: 0, reached: false, failed: notStarted };
+  // The frames of each step end where a scenario's do: the first step counts from RUN, a later one from where it starts (D62).
+  let anchor: { line: number; cycle: number } | undefined = await rasterAt(client);
+  const framed = () => (anchor === undefined ? {} : { anchor });
   const found: Stage[] = [];
   const start = options.entry ?? basic!.sys?.address ?? (await firstPcAfterBasic(client, basic!.basicEnd, load + bytes.length - 3));
   if (start === undefined) return { stages: [], frames: 0, reached: false, failed: `After RUN, the CPU did not execute the program after its BASIC text (${formatC64Address(basic!.basicEnd)} on) in ${SYS_FRAMES} frames. Give --entry <address>.` };
@@ -311,7 +330,7 @@ async function follow(
       await client.snapshot({ action: "save", name: CALL_SNAPSHOT });
       const point = await client.breakpoint({ action: "add", address: back, space: "c64" });
       try {
-        const run = await client.execution({ action: "advance-frames", count: frames, space: "c64" });
+        const run = await client.execution({ action: "advance-frames", count: frames, space: "c64", ...framed() });
         if ((run.pc ?? (await client.registersGet("c64")).pc) === back) return run.advancedFrames ?? 0;
         await client.snapshot({ action: "restore", name: CALL_SNAPSHOT });
         return undefined;
@@ -330,7 +349,7 @@ async function follow(
         }
         const written = (address: number) => ((stage.map[address]! | map[address]!) & COVERAGE.ramWrite) !== 0;
         await arm(stagePoints(candidates, stage.own, written, stage.called));
-        const run = await client.execution({ action: "advance-frames", count: left, space: "c64" });
+        const run = await client.execution({ action: "advance-frames", count: left, space: "c64", ...framed() });
         const advanced = run.advancedFrames ?? 0;
         used += advanced;
         left -= advanced;
@@ -365,13 +384,21 @@ async function follow(
 
   /** Tracks the stages for some frames; true when the CPU got to stopAt. */
   const track = async (frames: number): Promise<boolean> => {
+    anchor ??= await rasterAt(client);
+    try {
+      return await trackFrom(frames);
+    } finally {
+      anchor = undefined;
+    }
+  };
+  const trackFrom = async (frames: number): Promise<boolean> => {
     let left = frames;
     let stopped = false;
     while (left > 0 && !ended && !stopped && found.length < MAX_STAGES) {
       await client.snapshot({ action: "save", name: STAGE_SNAPSHOT });
       await client.memmap({ action: "clear" });
       const chunk = Math.min(STAGE_CHUNK_FRAMES, left);
-      const first = await client.execution({ action: "advance-frames", count: chunk, space: "c64" });
+      const first = await client.execution({ action: "advance-frames", count: chunk, space: "c64", ...framed() });
       const firstPc = first.pc ?? (await client.registersGet("c64")).pc;
       const map = await readCoverage(client);
       const candidates = stageCandidates(stage.map, map, stage.own, options.minStage, stage.called);

package/src/c64.ts

@@ -163,7 +163,9 @@ const MIN_BASIC_LOAD = 0x0400;
  * zero, the "marker" is the first machine code after the BASIC text (SYS
  * lines that jump right behind themselves). The stored links are not read:
  * BASIC relinks a loaded program, and a crack can store odd links to hide
- * lines from LIST. A load address below $0400 is a memory dump (F-12).
+ * lines from LIST. A load address below $0400 is a memory dump (F-12), and so
+ * is a file whose bytes run past $ffff: a 64 KiB dump from $0000 always does
+ * (b2/01, R3-02).
  */
 export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (program.length < 4) return { reason: "The file is too short for a BASIC program." };
@@ -171,6 +173,9 @@ export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (loadAddress < MIN_BASIC_LOAD) {
     return { reason: `The load address ${formatC64Address(loadAddress)} is below $0400, in the zero page, the stack or the system pages. The file is a memory dump or machine code, not a BASIC program.` };
   }
+  if (loadAddress + program.length - 2 > 0x10000) {
+    return { reason: `The file holds ${program.length - 2} bytes from ${formatC64Address(loadAddress)}, which runs past $ffff. The file is a memory dump, not a BASIC program.` };
+  }
   const lines: TokenizedLine[] = [];
   let at = 2;
   const ended = (basicEnd: number): TokenizedProgram => ({ loadAddress, basicEnd, textBytes: at, lines });

package/src/host/main.ts

@@ -15,7 +15,7 @@ import { PACKAGE } from "../package.ts";
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>]
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>] [--log-console] [--log-dir <directory>]
   c64-re-tools-host --help
 
 Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
@@ -27,8 +27,15 @@ connected c64-re-tools-mcp process, and runs the tools that come with VICE
 emulator and tool it started.
 
 Options:
-  --port <port>       Listen on this port instead (0 picks a free port).
-  --help              Show this help.`;
+  --port <port>            Listen on this port instead (0 picks a free port).
+  --log-console            Also print each request with its result, and each run
+                           of c1541 or petcat, to the console.
+  --log-dir <directory>    Write the same events as JSON lines to a file in this
+                           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.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-host: ${line}\n`);
@@ -36,9 +43,12 @@ function log(line: string): void {
 }
 
 async function main(): Promise<number> {
-  let values: { help?: boolean; port?: string };
+  let values: { help?: boolean; port?: string; "log-console"?: boolean; "log-dir"?: string };
   try {
-    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" } }, strict: true }));
+    ({ values } = parseArgs({
+      options: { help: { type: "boolean" }, port: { type: "string" }, "log-console": { type: "boolean" }, "log-dir": { type: "string" } },
+      strict: true,
+    }));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
     return 2;
@@ -47,7 +57,18 @@ async function main(): Promise<number> {
     process.stdout.write(`${HELP}\n`);
     return 0;
   }
-  startTrace("host", { warn: log });
+  const logDir = values["log-dir"];
+  if (logDir === "") {
+    process.stderr.write("--log-dir needs a directory.\n");
+    return 2;
+  }
+  startTrace("host", {
+    target: {
+      ...(logDir === undefined ? {} : { dir: { path: logDir, given: `--log-dir ${logDir}` } }),
+      ...(values["log-console"] ? { echo: (line: string) => process.stderr.write(`c64-re-tools-host: ${line}\n`) } : {}),
+    },
+    warn: log,
+  });
 
   const port = values.port === undefined ? DEFAULT_HOST_PORT : parsePort(values.port);
   if (port === undefined) {

package/src/host/vice/adapter.ts

@@ -6,6 +6,7 @@ import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry
 import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
 import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
+import type { CiaHidden } from "./chips.ts";
 import {
   BinaryMonitor,
   Command,
@@ -431,6 +432,19 @@ export class ViceAdapter {
     return bytes.toString("hex");
   }
 
+  /**
+   * The timer latches and the interrupt mask of the CIA at `base`, from VICE's
+   * text-monitor dump: no register read gives them (D63).
+   */
+  async ciaHidden(base: 0xdc00 | 0xdd00): Promise<CiaHidden> {
+    const answer = await this.#computerText(`io ${hex4(base)}`);
+    const mask = /\(mask: ([0-9a-f]{2})\)/i.exec(answer);
+    const latchA = /Timer A: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    const latchB = /Timer B: [0-9a-f]{4} \(latched ([0-9a-f]{4})\)/i.exec(answer);
+    if (mask === null || latchA === null || latchB === null) throw unknownForm("CIA dump", answer.split("\n"));
+    return { latchA: Number.parseInt(latchA[1]!, 16), latchB: Number.parseInt(latchB[1]!, 16), interruptMask: Number.parseInt(mask[1]!, 16) & 0x1f };
+  }
+
   /** Reads C64 I/O registers through the I/O bank, whatever the CPU has banked in, without side effects. */
   async readIo(start: number, size: number): Promise<Uint8Array> {
     const response = await this.#monitor.request(

package/src/host/vice/chips.ts

@@ -57,8 +57,15 @@ function bcd(value: number): number {
   return (value >> 4) * 10 + (value & 0x0f);
 }
 
+/** The parts of a CIA that no register read gives: the timer latches and the interrupt mask. */
+export interface CiaHidden {
+  latchA: number;
+  latchB: number;
+  interruptMask: number;
+}
+
 /** `registers` holds $dc00-$dc0f or $dd00-$dd0f. TOD hours become 0-23. */
-export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
+export function decodeCia(id: 1 | 2, registers: Uint8Array, hidden: CiaHidden): CiaState {
   const word = (low: number) => registers[low]! | (registers[low + 1]! << 8);
   const hourRegister = registers[0x0b]!;
   const pm = (hourRegister & 0x80) !== 0;
@@ -70,9 +77,12 @@ export function decodeCia(id: 1 | 2, registers: Uint8Array): CiaState {
     ddrB: registers[0x03]!,
     timerA: word(0x04),
     timerB: word(0x06),
+    latchA: hidden.latchA,
+    latchB: hidden.latchB,
     controlA: registers[0x0e]!,
     controlB: registers[0x0f]!,
     interruptStatus: registers[0x0d]!,
+    interruptMask: hidden.interruptMask,
     tod: {
       hours: (bcd(hourRegister & 0x1f) % 12) + (pm ? 12 : 0),
       minutes: bcd(registers[0x0a]! & 0x7f),

package/src/host/vice/screen.ts

@@ -4,6 +4,7 @@
 import { crc32, deflateSync } from "node:zlib";
 
 import type { VideoStandard } from "../../protocol/messages.ts";
+import { FRAME_SIZE } from "../../protocol/vice.ts";
 
 export interface IndexedFrame {
   width: number;
@@ -44,8 +45,8 @@ export function decodeDisplay(body: Buffer): RawDisplay {
  * offsets: PAL 384×272, NTSC 384×247.
  */
 const VISIBLE: Record<VideoStandard, { dx: number; dy: number; width: number; height: number }> = {
-  pal: { dx: -32, dy: -36, width: 384, height: 272 },
-  ntsc: { dx: -32, dy: -23, width: 384, height: 247 },
+  pal: { dx: -32, dy: -36, ...FRAME_SIZE.pal },
+  ntsc: { dx: -32, dy: -23, ...FRAME_SIZE.ntsc },
 };
 
 /** Crops the visible bordered frame out of VICE's full raster buffer. */

package/src/host/vice/session.ts

@@ -381,12 +381,21 @@ export class ViceSession implements ViceSessionHandle {
           this.#cartridge = false;
           this.#replaceStaged("cartridge", undefined);
         }
+        // Port 1 shares the keyboard lines: a held direction types keys into the RUN that the autostart types (R3-05).
+        const centred: Array<1 | 2> = [];
+        for (const [port, joystick] of this.#joysticks) {
+          if (joystick.direction === "center" && !joystick.fire) continue;
+          const centre: JoystickState = { port, direction: "center", fire: false };
+          await this.#observe(() => this.#machine.setJoystick(centre));
+          this.#joysticks.set(port, centre);
+          centred.push(port);
+        }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
         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 } : {}) };
+        return { state: "running", ...(type === "tap" && this.#inputFlaw !== undefined ? { emulatorFlaw: this.#inputFlaw } : {}), ...(centred.length === 0 ? {} : { joysticksCentred: centred }) };
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
@@ -498,8 +507,7 @@ export class ViceSession implements ViceSessionHandle {
   async #status(): Promise<MachineStatus> {
     const warp = await this.#observe(() => this.#machine.warp());
     // Read after #observe: it resumes a running machine, unless a breakpoint or a JAM stopped it meanwhile.
-    const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window" };
-    if (this.#cartridge) status.cartridge = true;
+    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();
     return status;
   }
@@ -526,7 +534,11 @@ export class ViceSession implements ViceSessionHandle {
     }
     if (params.action === "advance-frames") {
       if (params.count === undefined) throw new WireFailure("invalid-input", "advance-frames needs count, the number of frames");
-      const outcome = await this.#runFrames(params.count);
+      const raster = RASTER[this.#videoStandard];
+      if (params.anchor !== undefined && (params.anchor.line >= raster.lines || params.anchor.cycle >= raster.cycles)) {
+        throw new WireFailure("invalid-input", `The anchor is outside the frame: a ${this.#videoStandard} frame has lines 0-${raster.lines - 1} and cycles 0-${raster.cycles - 1}.`);
+      }
+      const outcome = await this.#runFrames(params.count, undefined, params.anchor);
       return { state: "stopped", pc: outcome.pc, advancedFrames: outcome.frames };
     }
     await this.#stop();
@@ -588,10 +600,11 @@ export class ViceSession implements ViceSessionHandle {
    * checkpoint, a user breakpoint or watchpoint, or a JAM ends the run early.
    * The machine is stopped afterwards.
    */
-  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }): Promise<{ end: RunEnd; frames: number; pc: number; 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" }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
-    const start = await this.#machine.rasterPosition();
+    // A frame ends where the raster passes the anchor; without one, where this run starts.
+    const start = anchor ?? (await this.#machine.rasterPosition());
     const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
     const ending = rasterWindowExpression(start.line, start.cycle, lines);
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
@@ -920,7 +933,10 @@ export class ViceSession implements ViceSessionHandle {
   async #cias(which: CiaSelection): Promise<CiaState[]> {
     const ids: Array<1 | 2> = which === "both" ? [1, 2] : [Number(which) as 1 | 2];
     const chips = [];
-    for (const id of ids) chips.push(decodeCia(id, await this.#machine.readIo(id === 1 ? 0xdc00 : 0xdd00, 0x10)));
+    for (const id of ids) {
+      const base = id === 1 ? 0xdc00 : 0xdd00;
+      chips.push(decodeCia(id, await this.#machine.readIo(base, 0x10), await this.#machine.ciaHidden(base)));
+    }
     return chips;
   }
 

package/src/host-client/autostart.ts

@@ -36,10 +36,20 @@ export const RUN_LIMIT_FRAMES = 300;
  */
 export async function runProgram(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<"not-loaded" | "not-started" | undefined> {
   if (!(await autostartLoaded(client, path, prg))) return "not-loaded";
+  return (await typeRun(client)) ? undefined : "not-started";
+}
+
+/**
+ * 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
+ * runs no line within RUN_LIMIT_FRAMES.
+ */
+export async function typeRun(client: ViceSessionClient): Promise<boolean> {
   await client.keyboard(textToPetscii("RUN\n"));
   const started = await client.runUntil({
     target: { kind: "memory", address: CURLIN_HIGH, operator: "ne", value: 0xff, space: "c64", view: "ram" },
     timeoutFrames: RUN_LIMIT_FRAMES,
   });
-  return started.reached ? undefined : "not-started";
+  return started.reached;
 }

package/src/host-client/tools.ts

@@ -86,4 +86,4 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
 export { DISK_ACTIONS } from "../protocol/tools.ts";
-export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";

package/src/mcp/tools/debug.ts

@@ -41,7 +41,8 @@ export const c64Breakpoint = defineTool({
   description:
     "Manage breakpoints. A breakpoint stops the CPU when it is about to execute the instruction at an address. " +
     "Action add sets one at address in space c64 or drive8. With a condition, it stops only when the condition is true. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
     "Breakpoints stay through a reset.",
   inputSchema: z
     .object({
@@ -84,7 +85,8 @@ export const c64Watchpoint = defineTool({
     "Manage watchpoints. A watchpoint stops the CPU when an instruction reads or writes memory in a range. " +
     `Action add sets one at address for size bytes (1 to ${MAX_WATCH_SIZE}, default 1), with access read, write or read-write. ` +
     "With a condition, it stops only when the condition is true. For a write, a memory condition sees the memory after the write. " +
-    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
   inputSchema: z
     .object({
       action: z.enum(CHECKPOINT_ACTIONS),
@@ -205,7 +207,8 @@ export const c64Profile = defineTool({
   name: "c64_profile",
   title: "Cycle profile",
   description:
-    "Get the routines where the C64 CPU spent the most cycles since the session started. " +
+    "Get the routines where the C64 CPU spent the most cycles since the session started or since the last c64_window. " +
+    "After c64_window or a snapshot restore, the emulator can give the cycles to a routine that ran before the restore, for example $fd50. Do not trust the routine addresses then. " +
     `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
     "Each entry gives the routine address, its total cycles with the routines it calls, and its own cycles. " +
     "percent is the part of all cycles that the routine used itself. " +

package/src/mcp/tools/machine.ts

@@ -22,7 +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"),
+    cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -32,8 +32,8 @@ export const c64Status = defineTool({
       videoStandard: status.videoStandard,
       warp: status.warp,
       window: status.window,
+      cartridge: status.cartridge,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
-      ...(status.cartridge === undefined ? {} : { cartridge: status.cartridge }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -21,6 +21,7 @@ export const c64Autostart = defineTool({
     `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. " +
+    "Both joysticks are centred first: joystick port 1 uses the keyboard lines, and a held direction changes the RUN that the autostart types. " +
     "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
@@ -33,6 +34,7 @@ export const c64Autostart = defineTool({
   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"),
+    joysticksCentred: z.array(z.union([z.literal(1), z.literal(2)])).optional().describe("the joystick ports that held a direction or fire and were centred before the reset"),
   }),
   readOnly: false,
   async run(input, session) {

package/src/mcp/tools/video.ts

@@ -74,9 +74,12 @@ const CiaOutput = z.object({
   ddrB: Byte,
   timerA: z.number().int().min(0).max(0xffff),
   timerB: z.number().int().min(0).max(0xffff),
+  latchA: z.number().int().min(0).max(0xffff).describe("the value that timer A loads when it underflows"),
+  latchB: z.number().int().min(0).max(0xffff).describe("the value that timer B loads when it underflows"),
   controlA: Byte,
   controlB: Byte,
   interruptStatus: Byte,
+  interruptMask: z.number().int().min(0).max(0x1f).describe("the interrupt sources that are on, as bits 0-4 of the interrupt control register"),
   tod: z.object({ hours: z.number().int(), minutes: z.number().int(), seconds: z.number().int(), tenths: z.number().int() }),
 });
 
@@ -84,8 +87,8 @@ export const c64Cia = defineTool({
   name: "c64_cia",
   title: "CIA state",
   description:
-    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers and the current timer values. " +
-    `It also has the control registers, the interrupt flags and the time of day (hours 0 to 23). ${NO_CHANGE}`,
+    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers, the current timer values and the timer latches. " +
+    `It also has the control registers, the interrupt flags, the interrupt mask and the time of day (hours 0 to 23). ${NO_CHANGE}`,
   inputSchema: z.object({ cia: z.enum(CIA_SELECTIONS).default("both") }).strict(),
   outputSchema: z.object({ chips: z.array(CiaOutput) }),
   readOnly: true,