@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.4

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

@@ -3,33 +3,59 @@
 // wrote and then executed: the run-time evidence that also finds a simple
 // cruncher whose bytes look like code. "capture" runs the program in an
 // emulator until it reaches a given address (the unpacked entry point) and
-// writes the memory into the project. No native unpack tool is used.
+// writes the memory into the project. "loads" captures each part of a
+// multi-load program (D53). No native unpack tool is used.
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
-import { formatC64Address, parseC64Address, textToPetscii } from "#src/c64.ts";
+import { EXECUTE, formatC64Address, parseC64Address, READ, textToPetscii, WRITE } from "#src/c64.ts";
+import { autostartLoaded, LOAD_LIMIT_FRAMES } from "#src/host-client/autostart.ts";
+import { executedIn, 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";
-import { readProjectFile } from "#src/host-client/transfer.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./evidence.ts";
+import { loads, readLoadSteps } from "./loads.ts";
+import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./machine.ts";
 
 const USAGE = `unpack.ts inspect <program.prg>
-unpack.ts trace <program.prg> [--frames <n>] [--entry <address>]
-unpack.ts capture <program.prg> --until <address> --out <file> [--range <start> <end>] [--timeout-frames <n>]
+unpack.ts trace <program.prg> [--frames <n>] [--entry <address>] [--steps <file>]
+unpack.ts capture <program.prg> --until <address> --out <dir> [--range <start> <end>] [--timeout-frames <n>] [--steps <file>] [--min-stage <bytes>]
+unpack.ts stages <program.prg> [--frames <n>] [--entry <address>] [--steps <file>] [--min-stage <bytes>]
+unpack.ts loads <program> --steps <file> --out <dir> [--drive] [--min-block <bytes>]
 
 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>, then write memory:
-          with --range, a PRG of that range; without it, all 64 KiB of RAM
+capture   run the program until the CPU gets to <address>, 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
+          0-3, VIC, SID and CIA registers, vectors, and what differs from a
+          clean reset). --range gives one segment in place of the found ones.
+
+stages    run the program for <n> frames (default 3000) and report each stage:
+          where it starts, the memory it wrote, and where the next one starts.
+          A stage starts when the CPU executes a block of at least
+          --min-stage bytes (default 64) that the stage before wrote.
+
+loads     run a multi-load program (a PRG, or a disk, tape or cartridge image)
+          with the steps file; each capture step {"capture": "<name>"} writes
+          <dir>/<name>/ with image.bin, image.json, entry_state.json and a PRG
+          for each block of at least --min-block bytes (default 64) that the C64
+          side changed since the previous capture. --drive also writes the 2 KiB
+          drive RAM as drive8.prg, for knowledge space drive8.
+
+--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.
 
 Addresses are $ and four hex digits. The result is one JSON object.`;
 
-const MAX_READ = 4096;
 
 function address(text: string, option: string): number {
   try {
@@ -41,13 +67,36 @@ function address(text: string, option: string): number {
 
 /** Written-then-executed bytes from this many on are unpacking, decrypting or relocating, not self-changing code. */
 const UNPACKED_BYTES = 256;
-const LOAD_POLL_FRAMES = 25;
-const LOAD_LIMIT_FRAMES = 1500;
 const MAX_ADVANCE = 10_000;
 /** The most ranges one memory map read gives. */
 const MAX_RANGES = 1000;
 
-async function trace(program: string, options: { frames: number; entry?: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+/** Reads and checks a steps file: action steps with $ addresses only (D43). */
+function readSteps(path: string): ActionStep[] {
+  let value: unknown;
+  try {
+    value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
+  } catch (error) {
+    if (error instanceof WireFailure) throw error;
+    throw new UsageError(`--steps ${path} is not JSON: ${(error as Error).message}`);
+  }
+  return checkActionSteps(value, (message) => {
+    throw new UsageError(`--steps ${path}: ${message}`);
+  });
+}
+
+/** Runs the steps; the reason when a runUntil step did not reach its target. */
+async function runSteps(client: ViceSessionClient, steps: ActionStep[]): Promise<string | undefined> {
+  for (const [index, step] of steps.entries()) {
+    const notReached = await runActionStep(client, step, parseC64Address);
+    if (notReached !== undefined && "runUntil" in step) {
+      return `Step ${index + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+    }
+  }
+  return undefined;
+}
+
+async function trace(program: string, options: { frames: number; entry?: number; steps: ActionStep[] }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const { bytes } = readProjectFile(program);
   if (bytes.length < 3) throw new UsageError("the file is too short for a PRG");
   const load = bytes[0]! | (bytes[1]! << 8);
@@ -56,17 +105,12 @@ 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.
-    await client.autostart({ path: program, index: 0, run: false });
-    const head = bytes.subarray(2, Math.min(bytes.length, 2 + 64)).toString("hex");
-    let loaded = false;
-    for (let frames = 0; frames < LOAD_LIMIT_FRAMES && !loaded; frames += LOAD_POLL_FRAMES) {
-      await client.execution({ action: "advance-frames", count: LOAD_POLL_FRAMES, space: "c64" });
-      loaded = (await client.memoryRead({ address: load, size: head.length / 2, space: "c64", view: "ram" })).data === head;
-    }
-    if (!loaded) return { output: { traced: false, reason: `The program was not in memory at ${formatC64Address(load)} after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
+    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 stepFailed = await runSteps(client, options.steps);
+    if (stepFailed !== undefined) return { output: { traced: false, reason: stepFailed }, failed: true };
     let ran = 0;
     while (ran < options.frames) {
       const step = await client.execution({ action: "advance-frames", count: Math.min(MAX_ADVANCE, options.frames - ran), space: "c64" });
@@ -75,11 +119,12 @@ async function trace(program: string, options: { frames: number; entry?: number
       if (advanced === 0) break;
     }
     const { pc } = await client.registersGet("c64");
-    const ranges = await readMemoryMap(async (start, end) => {
-      const map = await client.memmap({ action: "read", start, end, maxRanges: MAX_RANGES });
+    const ranges = await readMemoryMap(async (start) => {
+      const map = await client.memmap({ action: "read", start, end: 0xffff, maxRanges: MAX_RANGES });
       if (!("ranges" in map)) throw new WireFailure("operation-failed", "The emulator did not give the memory map.");
-      return map.ranges;
-    }, MAX_RANGES);
+      const ranges = map.ranges.map(({ start: from, end, flags }) => ({ start: from, end, read: (flags & READ) !== 0, write: (flags & WRITE) !== 0, execute: (flags & EXECUTE) !== 0 }));
+      return map.next === undefined ? { ranges } : { ranges, next: map.next };
+    });
     const { written, bytes: count, running } = writtenThenExecuted(ranges, pc);
     const packing = count >= UNPACKED_BYTES || running !== undefined ? "likely" : count > 0 ? "unclear" : "unlikely";
     return {
@@ -112,37 +157,214 @@ async function trace(program: string, options: { frames: number; entry?: number
   }
 }
 
-async function capture(program: string, options: { until: number; out: string; range?: [number, number]; timeoutFrames: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+/** Frames between two looks at the memory map while stages are followed. */
+const STAGE_CHUNK_FRAMES = 25;
+const MAX_STAGES = 16;
+const STAGE_SNAPSHOT = "stage-chunk";
+
+interface Stage {
+  entry: number;
+  firstFrame: number;
+  frames: number;
+  wrote: Array<{ start: number; end: number }>;
+  next?: number;
+}
+
+interface Followed {
+  stages: Stage[];
+  frames: number;
+  /** True when the CPU got to `until`. */
+  reached: boolean;
+  /** Why the program did not start, when it did not. */
+  failed?: string;
+}
+
+/**
+ * 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.
+ */
+async function follow(
+  client: ViceSessionClient,
+  program: string,
+  options: { frames: number; entry?: number; steps: ActionStep[]; minStage: number; until?: number },
+): Promise<Followed> {
+  const { bytes } = readProjectFile(program);
+  if (bytes.length < 3) throw new UsageError("the file is too short for a PRG");
+  const load = bytes[0]! | (bytes[1]! << 8);
+  const sys = inspect(bytes).basicStart?.sys;
+  if (options.entry === undefined && sys === undefined) throw new UsageError("the program has no BASIC start line; give --entry <address>");
+  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 found: Stage[] = [];
+  let entry = options.entry ?? parseC64Address(sys!);
+  let firstFrame = 0;
+  let total = 0;
+  let ended = false;
+  let reached = false;
+  const atTarget = (pc: number) => options.until !== undefined && pc === options.until;
+  const track = async (frames: number): Promise<void> => {
+    let left = frames;
+    while (left > 0 && !ended && !reached && found.length < MAX_STAGES) {
+      await client.snapshot({ action: "save", name: STAGE_SNAPSHOT });
+      const chunk = Math.min(STAGE_CHUNK_FRAMES, left);
+      const first = await client.execution({ action: "advance-frames", count: chunk, space: "c64" });
+      const firstPc = first.pc ?? (await client.registersGet("c64")).pc;
+      const map = await readCoverage(client);
+      const entered = writtenBlocks(map, options.minStage).filter((block) => executedIn(map, block));
+      if (entered.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 in written memory starts a stage too.
+          const blocks = writtenBlocks(map, options.minStage);
+          if (blocks.some((block) => firstPc >= block.start && firstPc <= block.end)) {
+            found.push({ entry, firstFrame, frames: total - firstFrame, wrote: blocks, next: firstPc });
+            entry = firstPc;
+            firstFrame = total;
+            await client.memmap({ action: "clear" });
+          }
+          reached = true;
+        } else if (advanced === 0) ended = true;
+        continue;
+      }
+      // Again from the start of the chunk, with breakpoints over the blocks: the stop is the next entry.
+      await client.snapshot({ action: "restore", name: STAGE_SNAPSHOT });
+      const points = [];
+      for (const block of entered) points.push(await client.breakpoint({ action: "add", address: block.start, size: block.end - block.start + 1, space: "c64" }));
+      const rerun = await client.execution({ action: "advance-frames", count: chunk, space: "c64" });
+      for (const point of points) await client.breakpoint({ action: "remove", id: point.id });
+      const next = rerun.pc ?? (await client.registersGet("c64")).pc;
+      const used = rerun.advancedFrames ?? 0;
+      total += used;
+      left -= used;
+      if (entered.some((block) => next >= block.start && next <= block.end)) {
+        found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(await readCoverage(client), options.minStage), next });
+        entry = next;
+        firstFrame = total;
+        await client.memmap({ action: "clear" });
+      } else if (!atTarget(next)) {
+        throw new WireFailure("operation-failed", `The run from the snapshot did not enter the written memory again; it stopped at ${formatC64Address(next)}.`);
+      }
+      if (atTarget(next)) reached = true;
+    }
+  };
+  for (const step of options.steps) {
+    if ("frames" in step) await track(step.frames);
+    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 });
+  await client.snapshot({ action: "discard", name: STAGE_SNAPSHOT }).catch(() => undefined);
+  found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(await readCoverage(client), options.minStage) });
+  return { stages: found, frames: total, reached };
+}
+
+const showRange = (range: { start: number; end: number }) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
+const showStages = (stages: Stage[]) =>
+  stages.map((stage, index) => ({
+    stage: index,
+    entry: formatC64Address(stage.entry),
+    frames: stage.frames,
+    wrote: stage.wrote.map(showRange),
+    ...(stage.next === undefined ? {} : { next: formatC64Address(stage.next) }),
+  }));
+
+async function stages(program: string, options: { frames: number; entry?: number; steps: ActionStep[]; minStage: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const client = await ViceSessionClient.open({ videoStandard: "pal" });
+  try {
+    const followed = await follow(client, program, options);
+    if (followed.failed !== undefined) return { output: { followed: false, reason: followed.failed }, failed: true };
+    return {
+      output: {
+        followed: true,
+        frames: followed.frames,
+        stages: showStages(followed.stages),
+        pc: formatC64Address((await client.registersGet("c64")).pc),
+        ...(followed.stages.length > MAX_STAGES ? { moreStages: true } : {}),
+      },
+      failed: false,
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+
+async function capture(
+  program: string,
+  options: { until: number; out: string; range?: [number, number]; timeoutFrames: number; steps: ActionStep[]; minStage: number },
+): Promise<{ output: Record<string, unknown>; failed: boolean }> {
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
-    await client.autostart({ path: program, index: 0, run: true });
-    const reached = await client.runUntil({ target: { kind: "address", address: options.until, space: "c64" }, timeoutFrames: options.timeoutFrames });
-    if (!reached.reached) {
+    const followed = await follow(client, program, { frames: options.timeoutFrames, steps: options.steps, minStage: options.minStage, until: options.until });
+    if (followed.failed !== undefined) return { output: { captured: false, reason: followed.failed }, failed: true };
+    const registers = await client.registersGet("c64");
+    if (!followed.reached) {
       return {
-        output: { captured: false, reason: `The program did not get to ${formatC64Address(options.until)} in ${options.timeoutFrames} frames. It stopped by ${reached.stopReason} at ${formatC64Address(reached.pc)}.` },
+        output: { captured: false, reason: `The program did not get to ${formatC64Address(options.until)} in ${options.timeoutFrames} frames. It is at ${formatC64Address(registers.pc)}.`, stages: showStages(followed.stages) },
         failed: true,
       };
     }
-    const [start, end] = options.range ?? [0x0000, 0xffff];
-    const memory = Buffer.alloc(end - start + 1);
-    for (let at = start; at <= end; at += MAX_READ) {
-      const size = Math.min(MAX_READ, end - at + 1);
-      // The RAM view: unpacked code is often under the ROMs or the I/O area.
-      const read = await client.memoryRead({ address: at, size, space: "c64", view: "ram" });
-      Buffer.from(read.data, "hex").copy(memory, at - start);
-    }
-    const bytes = options.range === undefined ? memory : Buffer.concat([Buffer.from([start & 0xff, start >> 8]), memory]);
-    const path = resolveProjectPath(options.out);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, bytes);
-    const registers = await client.registersGet("c64");
+    // 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));
+    const file = (path: string) => `${options.out}/${path}`;
+    const write = (path: string, bytes: Uint8Array) => writeProjectFile(file(path), bytes, { what: "--out" });
+    write("image.bin", memory);
+    const files = segments.map((segment) => {
+      const name = `segment-${segment.start.toString(16).padStart(4, "0")}-${segment.end.toString(16).padStart(4, "0")}.prg`;
+      write(name, Buffer.concat([Buffer.from([segment.start & 0xff, segment.start >> 8]), memory.subarray(segment.start, segment.end + 1)]));
+      return name;
+    });
+    const vectors = vectorsOf(state, memory);
+    write(
+      "image.json",
+      Buffer.from(
+        `${JSON.stringify(
+          {
+            entry: formatC64Address(registers.pc),
+            segments: segments.map((segment, index) => ({ ...showRange(segment), ...("writtenBy" in segment ? { writtenBy: segment.writtenBy } : {}), file: files[index] })),
+            vectors,
+            stages: showStages(followed.stages),
+            image: "image.bin",
+          },
+          null,
+          2,
+        )}\n`,
+      ),
+    );
+    // A clean machine at the READY prompt shows what the loader and the stages changed.
+    await client.reset({ mode: "hard", run: true });
+    await client.execution({ action: "advance-frames", count: READY_FRAMES, space: "c64" });
+    const clean = await machineState(client);
+    const differs: Array<{ address: string; entry: number; reset: number }> = [];
+    const compare = (base: number, entry: Buffer, reset: Buffer) => entry.forEach((value, offset) => value !== reset[offset] && differs.push({ address: formatC64Address(base + offset), entry: value, reset: reset[offset]! }));
+    compare(0x0000, state.port, clean.port);
+    compare(0x0002, state.pages.subarray(2), clean.pages.subarray(2));
+    for (const [name, [address]] of Object.entries(IO_AREAS)) compare(address, state.io[name as keyof typeof IO_AREAS], clean.io[name as keyof typeof IO_AREAS]);
+    write("entry_state.json", json(entryState(registers, state, vectors, differs)));
     return {
       output: {
         captured: true,
         pc: formatC64Address(registers.pc),
-        output: options.out,
-        ...(options.range === undefined ? { flat64k: true } : { loadRange: { start: formatC64Address(start), end: formatC64Address(end) } }),
-        registers: { a: registers.a, x: registers.x, y: registers.y, sp: registers.sp },
+        out: options.out,
+        files: ["image.json", "image.bin", "entry_state.json", ...files],
+        segments: segments.map(showRange),
+        stages: followed.stages.length,
+        differsFromReset: differs.length,
       },
       failed: false,
     };
@@ -163,6 +385,10 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
       "timeout-frames": { type: "string" },
       frames: { type: "string" },
       entry: { type: "string" },
+      steps: { type: "string" },
+      "min-stage": { type: "string" },
+      "min-block": { type: "string" },
+      drive: { type: "boolean" },
       help: { type: "boolean" },
     },
   });
@@ -183,8 +409,33 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     if (rest.length > 0) throw new UsageError("trace takes one program");
     const frames = values.frames === undefined ? 3000 : Number(values.frames);
     if (!Number.isInteger(frames) || frames < 1 || frames > 30_000) throw new UsageError("--frames must be from 1 to 30000");
-    return trace(program, { frames, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
+    const steps = values.steps === undefined ? [] : readSteps(values.steps);
+    return trace(program, { frames, steps, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
+  }
+  if (command === "stages") {
+    if (rest.length > 0) throw new UsageError("stages takes one program");
+    const frames = values.frames === undefined ? 3000 : Number(values.frames);
+    if (!Number.isInteger(frames) || frames < 1 || frames > 30_000) throw new UsageError("--frames must be from 1 to 30000");
+    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");
+    return stages(program, { frames, steps, minStage, ...(values.entry === undefined ? {} : { entry: address(values.entry, "--entry") }) });
+  }
+  if (command === "loads") {
+    if (rest.length > 0) throw new UsageError("loads takes one program");
+    if (values.steps === undefined || values.out === undefined) throw new UsageError("loads needs --steps and --out");
+    try {
+      resolveProjectPath(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+    }
+    const minBlock = values["min-block"] === undefined ? 64 : Number(values["min-block"]);
+    if (!Number.isInteger(minBlock) || minBlock < 1 || minBlock > 0x10000) throw new UsageError("--min-block must be from 1 to 65536");
+    return loads(program, { out: values.out, steps: readLoadSteps(values.steps), drive: values.drive === true, minBlock });
   }
+  if (values.drive !== undefined || values["min-block"] !== undefined) throw new UsageError("--drive and --min-block work only with loads");
   if (command !== "capture") throw new UsageError(`unknown command ${command}`);
   if (values.until === undefined || values.out === undefined) throw new UsageError("capture needs --until and --out");
   // --range takes two values: the end is the next positional argument.
@@ -203,7 +454,10 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   }
   const timeoutFrames = values["timeout-frames"] === undefined ? 3000 : Number(values["timeout-frames"]);
   if (!Number.isInteger(timeoutFrames) || timeoutFrames < 1 || timeoutFrames > 30_000) throw new UsageError("--timeout-frames must be from 1 to 30000");
-  return capture(program, { until: address(values.until, "--until"), out: values.out, ...(range === undefined ? {} : { range }), timeoutFrames });
+  const steps = values.steps === undefined ? [] : readSteps(values.steps);
+  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");
+  return capture(program, { until: address(values.until, "--until"), out: values.out, ...(range === undefined ? {} : { range }), timeoutFrames, steps, minStage });
 }
 
 await runScript(

package/src/c64.ts

@@ -174,6 +174,34 @@ export function parseTokenized(program: Uint8Array): TokenizedProgram {
   }
 }
 
+/** BASIC V2 keywords for the tokens $80 to $cb, in token order. */
+const KEYWORDS = [
+  "END", "FOR", "NEXT", "DATA", "INPUT#", "INPUT", "DIM", "READ", "LET", "GOTO", "RUN", "IF", "RESTORE", "GOSUB", "RETURN", "REM",
+  "STOP", "ON", "WAIT", "LOAD", "SAVE", "VERIFY", "DEF", "POKE", "PRINT#", "PRINT", "CONT", "LIST", "CLR", "CMD", "SYS", "OPEN",
+  "CLOSE", "GET", "NEW", "TAB(", "TO", "FN", "SPC(", "THEN", "NOT", "STEP", "+", "-", "*", "/", "^", "AND",
+  "OR", ">", "=", "<", "SGN", "INT", "ABS", "USR", "FRE", "POS", "SQR", "RND", "LOG", "EXP", "COS", "SIN",
+  "TAN", "ATN", "PEEK", "LEN", "STR$", "VAL", "ASC", "CHR$", "LEFT$", "RIGHT$", "MID$", "GO",
+] as const;
+
+/**
+ * One BASIC line as text: keywords for tokens, text in quotes and after REM
+ * as it is, and {$xx} for bytes that are no character. For evidence, not a listing.
+ */
+export function basicLineText(line: TokenizedLine): string {
+  let text = `${line.number} `;
+  let literal = false;
+  for (const byte of line.tokens) {
+    if (byte === QUOTE) literal = !literal;
+    if (!literal && byte >= 0x80 && byte < 0x80 + KEYWORDS.length) {
+      text += KEYWORDS[byte - 0x80];
+      if (byte === TOKEN.rem) literal = true;
+    } else {
+      text += petsciiNameToText(Uint8Array.of(byte));
+    }
+  }
+  return text;
+}
+
 /**
  * Evaluates a SYS argument that holds only numbers, + - * / and brackets.
  * Returns undefined for anything that needs run-time values.
@@ -279,3 +307,66 @@ export function findHandoffs(lines: TokenizedLine[]): BasicHandoff[] {
   }
   return handoffs;
 }
+
+// Execution coverage (D40): the byte format of a coverage map, and the 6502
+// instruction lengths that turn the instruction starts in it into code ranges.
+// VICE marks only the opcode byte of an executed instruction as executed.
+
+/** One byte per address: the access flags as VICE reports them, RAM, ROM and I/O apart. */
+export const COVERAGE = {
+  ramRead: 1 << 0,
+  ramWrite: 1 << 1,
+  ramExecute: 1 << 2,
+  romRead: 1 << 3,
+  romExecute: 1 << 4,
+  ioRead: 1 << 5,
+  ioWrite: 1 << 6,
+  ioExecute: 1 << 7,
+} as const;
+
+export const EXECUTE = COVERAGE.ramExecute | COVERAGE.romExecute | COVERAGE.ioExecute;
+export const READ = COVERAGE.ramRead | COVERAGE.romRead | COVERAGE.ioRead;
+export const WRITE = COVERAGE.ramWrite | COVERAGE.ioWrite;
+
+/**
+ * The length in bytes of the NMOS 6502/6510 instruction with this opcode, for
+ * all 256 opcodes with the undocumented ones. The opcode is aaabbbcc: bbb
+ * selects the addressing mode within a group cc. JAM (KIL) and BRK count one byte.
+ */
+export function instructionLength(opcode: number): 1 | 2 | 3 {
+  const group = opcode & 0b11;
+  const mode = (opcode >> 2) & 0b111;
+  if (group === 0b00) {
+    if (mode === 0b000) return opcode === 0x20 ? 3 : opcode === 0x00 || opcode === 0x40 || opcode === 0x60 ? 1 : 2;
+    return ([2, 2, 1, 3, 2, 2, 1, 3] as const)[mode]!;
+  }
+  if (group === 0b10) {
+    if (mode === 0b000) return opcode === 0x02 || opcode === 0x22 || opcode === 0x42 || opcode === 0x62 ? 1 : 2;
+    return ([2, 2, 1, 3, 1, 2, 1, 3] as const)[mode]!;
+  }
+  // Groups 01 and 11 share their addressing modes.
+  return ([2, 2, 2, 3, 2, 2, 3, 3] as const)[mode]!;
+}
+
+export interface CodeRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * The executed code in RAM as ranges: each RAM instruction start in `map`
+ * with its operand bytes, by the opcode in `memory` (64 KiB from $0000).
+ * `map` starts at `base`. Adjacent and overlapping instructions merge.
+ */
+export function executedRamCode(map: Uint8Array, base: number, memory: Uint8Array): CodeRange[] {
+  const ranges: CodeRange[] = [];
+  for (let offset = 0; offset < map.length; offset++) {
+    if ((map[offset]! & COVERAGE.ramExecute) === 0) continue;
+    const start = base + offset;
+    const end = Math.min(0xffff, start + instructionLength(memory[start]!) - 1);
+    const last = ranges.at(-1);
+    if (last !== undefined && start <= last.end + 1) last.end = Math.max(last.end, end);
+    else ranges.push({ start, end });
+  }
+  return ranges;
+}

package/src/cli/status.ts

@@ -2,6 +2,7 @@
 // Runtime with its tools.
 
 import { hostTools, type ToolCallOptions } from "../host-client/tools.ts";
+import { STOP_AND_ASK } from "../protocol/messages.ts";
 import type { ToolStatus } from "../protocol/tools.ts";
 
 /** One line per tool under `heading`: its version, or why it does not run. */
@@ -28,7 +29,8 @@ export async function hostStatusLines(options: ToolCallOptions = {}): Promise<st
   try {
     tools = await hostTools(options);
   } catch (error) {
-    return [`Host Runtime: not reachable. ${(error as Error).message}`];
+    // status is read by a person: the instruction for an agent (D37) stays out.
+    return [`Host Runtime: not reachable. ${(error as Error).message.replace(` ${STOP_AND_ASK}`, "")}`];
   }
   return ["Host Runtime: reachable", ...toolLines("Tools on the host:", tools)];
 }

package/src/host/main.ts

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 import { DEFAULT_HOST_PORT } from "../protocol/messages.ts";
 import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
-import { isLoopback, ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
@@ -13,22 +13,19 @@ import { viceSessionFactory } from "./vice/session.ts";
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>] [--listen <address> ...]
+  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>]
   c64-re-tools-host --help
 
 Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
 once (x64sc on PATH, or C64RT_VICE) and does not start if VICE cannot run.
-It listens on 127.0.0.1:${DEFAULT_HOST_PORT}, starts one VICE emulator for each
+It listens on port ${DEFAULT_HOST_PORT} on every address, so a dev container
+reaches it as host.docker.internal. It starts one VICE emulator for each
 connected c64-re-tools-mcp process, and runs the tools that come with VICE
 (c1541, petcat) for skill scripts. Stop it with Ctrl+C; that stops every
 emulator and tool it started.
 
 Options:
   --port <port>       Listen on this port instead (0 picks a free port).
-  --listen <address>  Also listen on this address, on the same port, for
-                      example the container bridge (172.17.0.1). An address
-                      that is not loopback needs C64RT_HOST_TOKEN: set it to
-                      the same secret for this program and for the clients.
   --help              Show this help.`;
 
 function log(line: string): void {
@@ -37,9 +34,9 @@ function log(line: string): void {
 }
 
 async function main(): Promise<number> {
-  let values: { help?: boolean; port?: string; listen?: string[] };
+  let values: { help?: boolean; port?: string };
   try {
-    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" }, listen: { type: "string", multiple: true } }, strict: true }));
+    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" } }, strict: true }));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
     return 2;
@@ -56,13 +53,6 @@ async function main(): Promise<number> {
     return 2;
   }
 
-  const extraHosts = values.listen ?? [];
-  const token = process.env.C64RT_HOST_TOKEN;
-  if (extraHosts.some((address) => !isLoopback(address)) && (token === undefined || token.length < 16)) {
-    process.stderr.write("--listen with an address that is not loopback needs C64RT_HOST_TOKEN with at least 16 characters, so that only your clients can connect.\n");
-    return 2;
-  }
-
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
     findVice(process.env);
@@ -90,9 +80,8 @@ async function main(): Promise<number> {
   let server;
   try {
     server = await startHostServer({
+      host: "0.0.0.0",
       port,
-      extraHosts,
-      ...(token === undefined || token === "" ? {} : { token }),
       log,
       createViceSession: viceSessionFactory({ supervisor, log }),
       tools: createToolDispatcher({ supervisor, log }),
@@ -102,15 +91,11 @@ async function main(): Promise<number> {
       process.stderr.write(`Port ${error.port} on ${error.address} is in use. Is another c64-re-tools-host running?\n`);
       return 1;
     }
-    if (error instanceof ListenError && error.code === "EADDRNOTAVAIL") {
-      process.stderr.write(`The address ${error.address} in --listen does not belong to this machine.\n`);
-      return 1;
-    }
     throw error;
   }
-  const addresses = [server.host, ...extraHosts].map((address) => `${address}:${server.port}`);
-  process.stdout.write(`c64-re-tools-host listening on ${addresses.join(", ")}\n`);
-  trace().event("host.listening", { addresses });
+  const address = `${server.host}:${server.port}`;
+  process.stdout.write(`c64-re-tools-host listening on ${address}\n`);
+  trace().event("host.listening", { addresses: [address] });
 
   trace().event("host.stop", { signal: await stopSignal(log) });
   await server.close();