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

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";
@@ -19,7 +19,7 @@ import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./evidence.ts";
 import { loads, readLoadSteps } from "./loads.ts";
-import { inRanges, mergeMaps, stageCandidates, stagePoints, type Range } from "./stages.ts";
+import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, type Range } from "./stages.ts";
 import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./machine.ts";
 
 const USAGE = `unpack.ts inspect <program.prg>
@@ -31,7 +31,7 @@ unpack.ts loads <program> --steps <file> --out <dir> [--drive] [--min-block <byt
 inspect   packing evidence: the BASIC start and the entropy of the bytes
 trace     run the program for <n> frames (default 3000) and report the memory
           that it wrote and then executed; --entry starts it there instead of RUN
-capture   run the program until the CPU gets to <address>, and write into the
+capture   run the program until the CPU gets to <address> after the steps, and write into the
           directory --out: image.bin (64 KiB of RAM), image.json (the entry,
           the segments that the stages wrote, the vectors, the stages), a PRG
           for each segment, and entry_state.json (registers, $00/$01, pages
@@ -54,7 +54,8 @@ loads     run a multi-load program (a PRG, or a disk, tape or cartridge image)
 --steps <file>  a JSON list of input steps that run right after the program
           starts: write, registers, joystick, type, frames and runUntil, as in
           c64-testing scenarios, with $ addresses only. Use it to press a key
-          in an intro or to get through a menu.
+          in an intro or to get through a menu. stages and capture track the
+          stages in frames steps and in runUntil steps with at alone.
 
 Addresses are $ and four hex digits. The result is one JSON object.`;
 
@@ -106,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;
@@ -190,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 }]);
 }
@@ -200,6 +219,8 @@ const MAX_STAGES = 16;
 /** Most stops of one re-run of a chunk: own code and writes over it each stop once. */
 const MAX_STAGE_STOPS = 4096;
 const STAGE_SNAPSHOT = "stage-chunk";
+/** The snapshot at a call into written code, while the run checks if the call returns (D59). */
+const CALL_SNAPSHOT = "stage-call";
 
 interface Stage {
   entry: number;
@@ -218,14 +239,20 @@ interface Followed {
   failed?: string;
 }
 
+/** A runUntil step to an address alone: a breakpoint stops it, so the stages are tracked while it runs. */
+function trackedRunUntil(step: ActionStep): step is { runUntil: { at: string }; timeoutFrames: number } {
+  return "runUntil" in step && "at" in step.runUntil && !("raster" in step.runUntil);
+}
+
 /**
  * Starts the program and follows its stages (D43). The memory map holds what
  * the current stage wrote; when the CPU executed a block of at least
  * `minStage` written bytes during a chunk of frames, the chunk runs again from
  * its snapshot with exec breakpoints over those blocks, which stop at the
  * first instruction of the next stage. Steps run in the tracked time: a frames
- * step is tracked, the others act between two chunks. With `until`, the
- * run ends when the CPU gets there.
+ * step and a runUntil step to an address alone are tracked, the others act
+ * between two chunks. With `until`, the run ends when the CPU gets there
+ * after the steps.
  */
 async function follow(
   client: ViceSessionClient,
@@ -237,11 +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 target = options.until === undefined ? undefined : await client.breakpoint({ action: "add", address: options.until, space: "c64" });
+  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>.` };
@@ -249,16 +276,17 @@ async function follow(
   let firstFrame = 0;
   let total = 0;
   let ended = false;
-  let reached = false;
-  const atTarget = (pc: number) => options.until !== undefined && pc === options.until;
-  // The current stage: its memory map since it started, chunk by chunk, and its own code.
-  let stage = { map: new Uint8Array(0x10000), own: new Set<number>() };
+  /** Where the run stops: the target of a runUntil step while it runs, then until (R2-06). */
+  let stopAt: number | undefined;
+  const atTarget = (pc: number) => stopAt !== undefined && pc === stopAt;
+  // The current stage: its memory map since it started, chunk by chunk, its own code, and the written code it calls (D59).
+  let stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] as Range[] };
   const startStage = async (next: number, last: Uint8Array) => {
     mergeMaps(stage.map, last);
     found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage), next });
     entry = next;
     firstFrame = total;
-    stage = { map: new Uint8Array(0x10000), own: new Set<number>() };
+    stage = { map: new Uint8Array(0x10000), own: new Set<number>(), called: [] };
     await client.memmap({ action: "clear" });
   };
 
@@ -286,6 +314,31 @@ async function follow(
         if (!points.has(key)) points.set(key, { kind: "watch", id: (await client.watchpoint({ action: "add", address: range.start, size: range.end - range.start + 1, access: "write", space: "c64" })).id });
       }
     };
+    /**
+     * At written code that a JSR of the stage called: runs on until the call
+     * returns, in the frames left. Gives the frames used when it returns;
+     * otherwise the machine goes back to the stop and nothing is given.
+     */
+    const returns = async (map: Uint8Array, frames: number): Promise<number | undefined> => {
+      const { sp } = await client.registersGet("c64");
+      const stack = await readRam(client, 0x0100, 0x100);
+      const pushed = stack[(sp + 1) & 0xff]! | (stack[(sp + 2) & 0xff]! << 8);
+      const [opcode] = await readRam(client, (pushed - 2) & 0xffff, 1);
+      const back = callReturn(stack, sp, () => opcode!, (address) => ((stage.map[address]! | map[address]!) & COVERAGE.ramExecute) !== 0);
+      if (back === undefined) return undefined;
+      await arm({ exec: [], watch: [] });
+      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", ...framed() });
+        if ((run.pc ?? (await client.registersGet("c64")).pc) === back) return run.advancedFrames ?? 0;
+        await client.snapshot({ action: "restore", name: CALL_SNAPSHOT });
+        return undefined;
+      } finally {
+        await client.breakpoint({ action: "remove", id: point.id });
+        await client.snapshot({ action: "discard", name: CALL_SNAPSHOT });
+      }
+    };
     let left = frames;
     let used = 0;
     let map: Uint8Array = new Uint8Array(0x10000);
@@ -295,15 +348,27 @@ async function follow(
           throw new WireFailure("operation-failed", `The stage that starts at ${formatC64Address(entry)} stopped ${MAX_STAGE_STOPS} times in one chunk of frames without a new stage. Use --min-stage with a larger block size, or capture with --until.`);
         }
         const written = (address: number) => ((stage.map[address]! | map[address]!) & COVERAGE.ramWrite) !== 0;
-        await arm(stagePoints(candidates, stage.own, written));
-        const run = await client.execution({ action: "advance-frames", count: left, space: "c64" });
+        await arm(stagePoints(candidates, stage.own, written, stage.called));
+        const run = await client.execution({ action: "advance-frames", count: left, space: "c64", ...framed() });
         const advanced = run.advancedFrames ?? 0;
         used += advanced;
         left -= advanced;
         const pc = run.pc ?? (await client.registersGet("c64")).pc;
         map = await readCoverage(client);
-        if (inRanges(candidates, pc)) {
-          if (written(pc)) return { used, map, next: pc, atTarget: atTarget(pc) };
+        // A frame can end in written code that the stage called before (D59): that stop starts no stage.
+        if (inRanges(candidates, pc) && !inRanges(stage.called, pc)) {
+          if (written(pc)) {
+            const back = left > 0 && !atTarget(pc) ? await returns(map, left) : undefined;
+            if (back === undefined) return { used, map, next: pc, atTarget: atTarget(pc) };
+            used += back;
+            left -= back;
+            map = await readCoverage(client);
+            // The stage called the block and got the CPU back: the code that ran there is its own code.
+            const block = candidates.find((range) => pc >= range.start && pc <= range.end)!;
+            stage.called.push(...executedIn(map, block));
+            if (left <= 0) return { used, map, atTarget: false };
+            continue;
+          }
           stage.own.add(pc);
         }
         if (atTarget(pc)) return { used, map, atTarget: true };
@@ -317,28 +382,38 @@ async function follow(
     }
   };
 
-  const track = async (frames: number): Promise<void> => {
+  /** 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;
-    while (left > 0 && !ended && !reached && found.length < MAX_STAGES) {
+    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);
+      const candidates = stageCandidates(stage.map, map, stage.own, options.minStage, stage.called);
       if (candidates.length === 0) {
         const advanced = first.advancedFrames ?? 0;
         total += advanced;
         left -= advanced;
         if (atTarget(firstPc)) {
-          // The stop at until comes before its instruction runs: a target that the stage wrote starts a stage too.
+          // The stop at a target comes before its instruction runs: a target that the stage wrote starts a stage too.
           const combined = Uint8Array.from(stage.map);
           mergeMaps(combined, map);
           const wrote = (combined[firstPc]! & COVERAGE.ramWrite) !== 0 && inRanges(writtenBlocks(combined, options.minStage), firstPc);
           if (wrote) await startStage(firstPc, map);
           else mergeMaps(stage.map, map);
-          reached = true;
+          stopped = true;
         } else {
           mergeMaps(stage.map, map);
           if (advanced === 0) ended = true;
@@ -353,15 +428,35 @@ async function follow(
       left -= again.used;
       if (again.next !== undefined) await startStage(again.next, again.map);
       else mergeMaps(stage.map, again.map);
-      if (again.atTarget) reached = true;
+      if (again.atTarget) stopped = true;
     }
+    return stopped;
   };
-  for (const step of options.steps) {
+  /** Tracks the stages until the CPU gets to an address, with a breakpoint there. */
+  const trackTo = async (address: number, frames: number): Promise<boolean> => {
+    stopAt = address;
+    const point = await client.breakpoint({ action: "add", address, space: "c64" });
+    try {
+      return await track(frames);
+    } finally {
+      await client.breakpoint({ action: "remove", id: point.id });
+      stopAt = undefined;
+    }
+  };
+  // The steps run first and in the tracked time: a frames step and a runUntil step to an address (R2-06). The others act between two chunks.
+  for (const [index, step] of options.steps.entries()) {
     if ("frames" in step) await track(step.frames);
-    else await runActionStep(client, step, parseC64Address);
+    else if (trackedRunUntil(step)) {
+      if (!(await trackTo(parseC64Address(step.runUntil.at), step.timeoutFrames))) {
+        const { pc } = await client.registersGet("c64");
+        return { stages: found, frames: total, reached: false, failed: `Step ${index + 1} did not reach its target in ${step.timeoutFrames} frames. It is at ${formatC64Address(pc)}.` };
+      }
+    } else await runActionStep(client, step, parseC64Address);
   }
-  await track(Math.max(0, options.frames - total));
-  if (target !== undefined) await client.breakpoint({ action: "remove", id: target.id });
+  const left = Math.max(0, options.frames - total);
+  let reached = false;
+  if (options.until === undefined) await track(left);
+  else reached = await trackTo(options.until, left);
   await client.snapshot({ action: "discard", name: STAGE_SNAPSHOT }).catch(() => undefined);
   mergeMaps(stage.map, await readCoverage(client));
   found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage) });
@@ -417,10 +512,8 @@ async function capture(
     // The RAM view: unpacked code is often under the ROMs or the I/O area.
     const memory = await readRam(client, 0x0000, 0x10000);
     const state = await machineState(client);
-    // The segments: what the stages wrote, without the blocks that hold the code of an earlier stage.
-    const earlier = followed.stages.slice(0, -1).map((stage) => stage.entry);
-    const written = followed.stages.flatMap((stage, index) => stage.wrote.map((range) => ({ ...range, writtenBy: index })));
-    const segments = options.range !== undefined ? [{ start: options.range[0], end: options.range[1] }] : written.filter((range) => !earlier.some((entry) => entry >= range.start && entry <= range.end));
+    // The segments: what the stages wrote, without loader leftovers, with no overlap.
+    const segments = options.range !== undefined ? [{ start: options.range[0], end: options.range[1] }] : captureSegments(followed.stages, registers.pc);
     const file = (path: string) => `${options.out}/${path}`;
     const write = (path: string, bytes: Uint8Array) => writeProjectFile(file(path), bytes, { what: "--out" });
     write("image.bin", memory);
@@ -533,8 +626,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     const minStage = values["min-stage"] === undefined ? 64 : Number(values["min-stage"]);
     if (!Number.isInteger(minStage) || minStage < 1 || minStage > 0x10000) throw new UsageError("--min-stage must be from 1 to 65536");
     const steps = values.steps === undefined ? [] : readSteps(values.steps);
-    // A runUntil step cannot be tracked in chunks of frames; capture takes it.
-    if (steps.some((step) => "runUntil" in step)) throw new UsageError("stages takes no runUntil step; use frames steps");
+    // A runUntil step to a raster line or a memory value cannot be tracked in chunks of frames; capture takes it.
+    if (steps.some((step) => "runUntil" in step && !trackedRunUntil(step))) throw new UsageError("stages takes a runUntil step only with at alone; use frames steps or runUntil at");
     return stages(program, { frames, steps, minStage, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
   }
   if (command === "loads") {

package/src/c64.ts

@@ -153,29 +153,43 @@ export type BasicHandoff =
  */
 export type TokenizedProgram = { loadAddress: number; basicEnd: number; textBytes: number; lines: TokenizedLine[] } | { reason: string };
 
+/** BASIC text cannot start below the screen: there are the zero page, the stack and the system pages. */
+const MIN_BASIC_LOAD = 0x0400;
+
 /**
  * Splits a PRG into BASIC lines the way BASIC relinks a loaded program: each
  * line ends at a zero byte, and a link whose high byte is zero ends the
- * program. The stored links are not trusted. A real end marker is two zero
- * bytes; when only the high byte is zero, the "marker" is the first machine
- * code after the BASIC text (SYS lines that jump right behind themselves).
+ * program. A real end marker is two zero bytes; when only the high byte is
+ * 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), 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." };
   const loadAddress = program[0]! | (program[1]! << 8);
+  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 });
   // File offset k (from 2 on) loads at loadAddress + k - 2.
   for (;;) {
     // A file that ends right after a line leaves the end marker to the zeros after it in memory;
     // basicEnd is the address after that marker, as when the file holds it.
-    if (at === program.length && lines.length > 0) return { loadAddress, basicEnd: loadAddress + at, textBytes: at, lines };
+    if (at === program.length && lines.length > 0) return ended(loadAddress + at);
     if (at + 1 >= program.length) return { reason: "The BASIC program has no end marker." };
     if (program[at + 1] === 0) {
       // An end marker before any line, with more bytes after it, is how machine code at a non-BASIC address often starts.
       if (lines.length === 0 && at + 2 < program.length) return { reason: "The file holds no BASIC line before other bytes, so it is no BASIC program." };
       const marker = program[at] === 0;
-      return { loadAddress, basicEnd: loadAddress + (marker ? at : at - 2), textBytes: at, lines };
+      return ended(loadAddress + (marker ? at : at - 2));
     }
     if (at + 4 > program.length) return { reason: "The last BASIC line is cut off." };
     const number = program[at + 2]! | (program[at + 3]! << 8);

package/src/cli/status.ts

@@ -2,8 +2,10 @@
 // Runtime with its tools.
 
 import { hostTools, type ToolCallOptions } from "../host-client/tools.ts";
+import { viceVersionOf } from "../native/discover.ts";
+import { PACKAGE } from "../package.ts";
 import { STOP_AND_ASK } from "../protocol/messages.ts";
-import type { ToolStatus } from "../protocol/tools.ts";
+import type { HostInfo, ToolStatus } from "../protocol/tools.ts";
 
 /** One line per tool under `heading`: its version, or why it does not run; then each known flaw of it. */
 export function toolLines(heading: string, tools: readonly ToolStatus[]): string[] {
@@ -27,12 +29,33 @@ export function toolLines(heading: string, tools: readonly ToolStatus[]): string
  * every tool on it runs.
  */
 export async function hostStatusLines(options: ToolCallOptions = {}): Promise<{ lines: string[]; ready: boolean }> {
+  let host: HostInfo;
   let tools: ToolStatus[];
   try {
-    tools = await hostTools(options);
+    ({ host, tools } = await hostTools(options));
   } catch (error) {
     // status is read by a person: the instruction for an agent (D37) stays out.
     return { lines: [`Host Runtime: not reachable. ${(error as Error).message.replace(` ${STOP_AND_ASK}`, "")}`], ready: false };
   }
-  return { lines: ["Host Runtime: reachable", ...toolLines("Tools on the host:", tools)], ready: tools.every((tool) => tool.runs) };
+  const mixed = mixedViceBuilds(tools);
+  return {
+    lines: [
+      `Host Runtime: reachable, c64-re-tools ${host.version} on ${host.platform} ${host.release} (${host.arch})`,
+      ...(host.version === PACKAGE.version ? [] : [`  Warning: the Host Runtime is c64-re-tools ${host.version} and this is ${PACKAGE.version}. Start the host again so that both are the same version.`]),
+      ...toolLines("Tools on the host:", tools),
+      ...(mixed === undefined ? [] : [`  Warning: ${mixed}`]),
+    ],
+    ready: tools.every((tool) => tool.runs),
+  };
+}
+
+/** A warning when x64sc, c1541 and petcat that run come from different VICE versions or builds. */
+export function mixedViceBuilds(tools: readonly ToolStatus[]): string | undefined {
+  const running = tools.filter((tool) => tool.runs && tool.version !== undefined);
+  const builds = running.map((tool) => {
+    const version = viceVersionOf(tool.version!);
+    return version === undefined ? tool.version! : `VICE ${version.major}.${version.minor}${version.revision === undefined ? "" : ` SVN r${version.revision}`}`;
+  });
+  if (new Set(builds).size <= 1) return undefined;
+  return `the VICE tools come from different VICE builds: ${running.map((tool) => `${tool.version} (${tool.path})`).join(", ")}. Put x64sc, c1541 and petcat of one VICE first on PATH, or set C64RT_VICE, C64RT_C1541 and C64RT_PETCAT.`;
 }

package/src/host/tools/c1541.ts

@@ -37,11 +37,23 @@ const LAYOUTS: Record<string, Layout> = {
   "1581": { header: { track: 40, sector: 0 }, name: 0x04, id: 0x16, dos: 0x19 },
 };
 
+/** Used sectors of the format outside the header and directory chain: the 1571 BAM track 53, the two 1581 BAM blocks. */
+const RESERVED: Record<string, DiskSector[]> = {
+  "1541": [],
+  "1571": Array.from({ length: 19 }, (_, sector) => ({ track: 53, sector })),
+  "1581": [
+    { track: 40, sector: 1 },
+    { track: 40, sector: 2 },
+  ],
+};
+
 export interface DiskEntry extends DiskFile {
   /** The name's PETSCII bytes, up to the first shifted space ($a0). */
   nameBytes: Uint8Array;
   startTrack: number;
   startSector: number;
+  /** REL only: the first side sector. */
+  sideStart?: DiskSector;
 }
 
 const damaged = (message: string) => new WireFailure("media-error", `The disk image is damaged: ${message}`);
@@ -115,7 +127,7 @@ export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: st
       // Type 0 is an empty or scratched slot; the DOS lists no file there.
       if (typeByte === 0) continue;
       const nameBytes = nameField(block, offset + 5, 16);
-      entries.push({
+      const entry: DiskEntry = {
         name: petsciiNameToText(nameBytes),
         nameBytes,
         type: fileType(typeByte),
@@ -124,7 +136,10 @@ export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: st
         locked: (typeByte & 0x40) !== 0,
         startTrack: block.readUInt8(offset + 3),
         startSector: block.readUInt8(offset + 4),
-      });
+      };
+      const side = { track: block.readUInt8(offset + 0x15), sector: block.readUInt8(offset + 0x16) };
+      if (entry.type === "rel" && side.track !== 0) entry.sideStart = side;
+      entries.push(entry);
     }
   }
   return {
@@ -151,6 +166,13 @@ export function fileData(blocks: Buffer[], chain: DiskSector[]): Buffer {
   return Buffer.concat(parts);
 }
 
+/** The used sectors of the BAM that are not in `referenced`, in track and sector order. */
+export function unreferencedSectors(tracks: ReadonlyArray<{ track: number; usedSectors: number[] }>, referenced: Iterable<DiskSector>): DiskSector[] {
+  const known = new Set<string>();
+  for (const at of referenced) known.add(`${at.track}/${at.sector}`);
+  return tracks.flatMap(({ track, usedSectors }) => usedSectors.filter((sector) => !known.has(`${track}/${sector}`)).map((sector) => ({ track, sector })));
+}
+
 const toFile = (entry: DiskEntry): DiskFile => ({ name: entry.name, type: entry.type, blocks: entry.blocks, closed: entry.closed, locked: entry.locked });
 
 const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((byte, index) => byte === b[index]);
@@ -226,11 +248,18 @@ export async function inspect(params: C1541Params, image: Buffer, context: ToolC
     const layout = LAYOUTS[info.format];
     if (layout === undefined) throw new WireFailure("media-error", `The disk image has the drive format ${info.format}; only 1541, 1571 and 1581 disks are supported.`);
 
-    if (params.action === "bam") {
-      return { result: { action: "bam", tracks: parseBam(await c1541.run(["-bam"]), info.tracks) } };
-    }
     const headerChain = await c1541.chain(layout.header);
     const directory = parseDirectory(await c1541.blocks(headerChain), layout);
+    if (params.action === "bam") {
+      const tracks = parseBam(await c1541.run(["-bam"]), info.tracks);
+      // Every sector that the header, the directory or a file holds; a file without blocks has no chain.
+      const referenced = [...headerChain, ...(RESERVED[info.format] ?? [])];
+      for (const entry of directory.entries) {
+        if (entry.startTrack !== 0) referenced.push(...(await c1541.chain({ track: entry.startTrack, sector: entry.startSector })));
+        if (entry.sideStart !== undefined) referenced.push(...(await c1541.chain(entry.sideStart)));
+      }
+      return { result: { action: "bam", tracks, unreferenced: unreferencedSectors(tracks, referenced) } };
+    }
     if (params.action === "directory") {
       const { diskName, diskId, dosType, entries } = directory;
       return { result: { action: "directory", diskName, diskId, dosType, freeBlocks: parseFreeBlocks(overview), entries: entries.map(toFile) } };

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

@@ -5,7 +5,10 @@
 // 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 { 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";
@@ -23,7 +26,7 @@ function requireMinimum(status: ToolStatus, tool: ToolSpec): ToolStatus {
 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: { tools: ToolStatus[] } }> {
+export async function hostStatus(context: ToolContext, started?: ViceVersion): Promise<{ result: { host: HostInfo; tools: ToolStatus[] } }> {
   const specs = [VICE, C1541, PETCAT];
   const probed = await probeTools(
     [
@@ -40,5 +43,5 @@ export async function hostStatus(context: ToolContext, started?: ViceVersion): P
   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 } };
 }