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

package/skills/c64-static-analysis/scripts/analyze.ts

@@ -9,6 +9,7 @@ import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
 import { COVERAGE, formatC64Address, parseC64Address, prgRange } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { analyze as analyzeWithDxa } from "#src/native/dxa.ts";
@@ -21,7 +22,7 @@ import { currentRevision } from "#src/knowledge/read.ts";
 import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageFiles } from "./coverage.ts";
+import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps } from "./coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
 import { findIdioms } from "./idioms.ts";
 import { instructionList } from "./instructions.ts";
@@ -38,8 +39,9 @@ const USAGE = `analyze.ts <image> [options]
                           mode, operand, target, executed) to this project file as JSON
   --coverage <file>       a coverage map of 64 KiB from c64_memmap (repeatable): its
                           executed code is seeded, and analyzer data over it is reported
-  --max-listed <n>        list at most n labels or functions (default 50, 0 for none);
-                          the counts are always given, and knowledge has all of them
+  --max-listed <n>        list at most n labels, functions or candidates (default 50,
+                          0 for none); the counts are always given, and knowledge has
+                          all labels and functions
   --space <space>         the knowledge space of the image: c64 (the default), drive8
                           for 1541 drive code, or bank0 to bank255 for a cartridge bank
 
@@ -158,7 +160,8 @@ async function run(argv: string[]): Promise<unknown> {
   if (space !== DEFAULT_SPACE && values.coverage !== undefined) throw new UsageError("--coverage works only in space c64");
   const imageKind = values.flat64k ? "flat64k" : "prg";
   const bytes = readProjectFile(image).bytes;
-  const coverage = readCoverageFiles(values.coverage ?? []);
+  const runs = readCoverageMaps(values.coverage ?? []);
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
   const byteAt = imageReader(bytes, imageKind);
   // With coverage, a code finding over an executed instruction start replaces the data of the other analyzer (D58), and the files are the evidence.
   const executed = coverage === undefined ? {} : { executed: (address: number) => (coverage[address]! & COVERAGE.ramExecute) !== 0 };
@@ -170,7 +173,7 @@ async function run(argv: string[]): Promise<unknown> {
   } catch (error) {
     throw new UsageError(`${image}: ${(error as Error).message}`);
   }
-  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, coverage);
+  const idioms = findIdioms(byteAt, { start: loaded.start, end: loaded.end }, runs);
 
   const reader = openForRead();
   const revision = currentRevision(reader);
@@ -192,7 +195,11 @@ async function run(argv: string[]): Promise<unknown> {
         revision: imported.revision,
         changes: { regions: imported.regions, references: imported.references },
         conflicts: imported.conflicts.map((conflict) => showConflict(conflict, "heuristic")),
-        candidates: { dop: idioms.candidates.dop.map(formatC64Address), selfModified: idioms.candidates.selfModified.map(formatC64Address) },
+        // Candidates are not knowledge: a larger --max-listed gives more of them.
+        candidates: {
+          dop: listed(idioms.candidates.dop, max, formatC64Address, "a larger --max-listed"),
+          selfModified: listed(idioms.candidates.selfModified, max, formatC64Address, "a larger --max-listed"),
+        },
       },
     };
   };

package/skills/c64-static-analysis/scripts/coverage.ts

@@ -5,7 +5,7 @@
 import type { DatabaseSync } from "node:sqlite";
 
 import { COVERAGE, instructionLength } from "#src/c64.ts";
-import { FULL_COVERAGE, readCoverageFiles as readFiles } from "#src/host-client/coverage.ts";
+import { FULL_COVERAGE, readCoverageMaps as readMaps } from "#src/host-client/coverage.ts";
 import { listRegions, type RegionRow } from "#src/knowledge/read.ts";
 import { CODE_REGION_TYPES, DEFAULT_SPACE, type Space } from "#src/knowledge/schema.ts";
 import { UsageError } from "#src/script.ts";
@@ -15,9 +15,9 @@ const FULL_MAP = FULL_COVERAGE;
 const FLOW_ENDS = new Set([0x00, 0x40, 0x4c, 0x60, 0x6c]);
 const ANALYZER_ORIGINS = new Set(["dxa", "ghidra", "heuristic"]);
 
-/** Reads coverage files and joins them: an address has every flag that any run gave it. */
-export function readCoverageFiles(paths: string[]): Uint8Array | undefined {
-  return readFiles(paths, (message) => {
+/** Reads coverage files, one map per file (a run). */
+export function readCoverageMaps(paths: string[]): Uint8Array[] {
+  return readMaps(paths, (message) => {
     throw new UsageError(message);
   });
 }

package/skills/c64-static-analysis/scripts/idioms.ts

@@ -1,10 +1,13 @@
 // 6502 idioms that hide code from a disassembler (D44): RTS dispatch tables,
 // JMP tables and BIT skips are found by their exact instruction patterns and
 // become heuristic findings and entry points; DOP padding and self-modified
-// opcodes are only reported. A table's length is not known statically:
-// entries count while each target is a plausible instruction in the program.
+// opcodes are only reported. A self-modified opcode is one that one run wrote
+// and executed, in either order, since a coverage file holds no order (R3-04):
+// a copier's writes in one run and their execution in another do not count (F-16). A table's length is not known statically: entries
+// count while each target is a plausible instruction in the program.
 
 import { COVERAGE } from "#src/c64.ts";
+import { joinCoverage } from "#src/host-client/coverage.ts";
 import type { NormalizedFindings } from "#src/knowledge/import.ts";
 import type { ImageByte } from "./coverage.ts";
 
@@ -22,7 +25,7 @@ export interface Idioms {
   /** Table ranges for the same run: they are data. */
   dataRanges: Array<{ start: number; end: number }>;
   counts: { rtsTables: number; jumpTables: number; bitSkips: number };
-  /** Seen in the coverage, not written: the LLM decides. */
+  /** Seen in the coverage, not written: the LLM decides. All of them: the result lists the first ones. */
   candidates: { dop: number[]; selfModified: number[] };
 }
 
@@ -38,7 +41,9 @@ const word = (byteAt: ImageByte, address: number) => {
   return low === undefined || high === undefined ? undefined : low | (high << 8);
 };
 
-export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, coverage?: Uint8Array): Idioms {
+/** `runs` are the coverage maps, one for each file. */
+export function findIdioms(byteAt: ImageByte, range: { start: number; end: number }, runs: readonly Uint8Array[] = []): Idioms {
+  const coverage = runs.length === 0 ? undefined : joinCoverage(runs);
   const regions: NormalizedFindings["regions"] = [];
   const references: NormalizedFindings["references"] = [];
   const entryPoints = new Set<number>();
@@ -113,14 +118,14 @@ export function findIdioms(byteAt: ImageByte, range: { start: number; end: numbe
     }
   }
 
-  // Candidates from the coverage: DOP padding that ran, and opcodes that the program wrote and then ran.
+  // Candidates from the coverage: DOP padding that ran, and opcodes that one run wrote and executed.
   const candidates = { dop: [] as number[], selfModified: [] as number[] };
   if (coverage !== undefined) {
+    const both = COVERAGE.ramWrite | COVERAGE.ramExecute;
     for (let address = range.start; address <= range.end; address++) {
-      const flags = coverage[address]!;
-      if ((flags & COVERAGE.ramExecute) === 0) continue;
-      if (DOPS.has(byteAt(address)!) && candidates.dop.length < MAX_TABLE) candidates.dop.push(address);
-      if ((flags & COVERAGE.ramWrite) !== 0 && candidates.selfModified.length < MAX_TABLE) candidates.selfModified.push(address);
+      if ((coverage[address]! & COVERAGE.ramExecute) === 0) continue;
+      if (DOPS.has(byteAt(address)!)) candidates.dop.push(address);
+      if (runs.some((run) => (run[address]! & both) === both)) candidates.selfModified.push(address);
     }
   }
 

package/skills/c64-testing/SKILL.md

@@ -86,7 +86,7 @@ PASS, FAIL or INCONCLUSIVE, the checkpoints and the smallest differences that ex
 - INCONCLUSIVE, "did not reach the checkpoint": one side did not reach the checkpoint in the frame limit. Find the reason with the c64-emulator skill. Do not report a FAIL.
 - INCONCLUSIVE, "has no symbol": one side has no symbol with that name. Add the name to the knowledge or to the rebuild source.
 - INCONCLUSIVE, "no emulator" or "could not run": the host runtime or the emulator failed. Tell the user the message.
-- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - A FAIL with only a `screen` difference: add `vicii` or `sprites` to the observation to find which chip state is different.
 - A program that uses random numbers: set the random seed with a `write` step on both sides. If that is not possible, observe only values that do not depend on the random numbers.
 - The two sides start differently, for example the original after a cracked intro. Give the steps that only one side needs a `side`. Then make the memory the same with a `normalize` step from the entry state of the c64-unpacker skill.

package/skills/c64-testing/references/scenario-format.md

@@ -73,7 +73,7 @@ An `observe` step has a checkpoint name. A scenario can have each name only one
 | `vicii` | The VIC-II state: mode, screen address, scroll and colors. |
 | `sprites` | A list of sprite numbers from 0 to 7. The script compares their position, color and flags. |
 
-A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A scenario can observe the screen at most at 64 checkpoints.
+A `tolerance` is the largest permitted difference for each byte. A `mask` has at most 64 rectangles. A `mask` must not cover all of the screen: PAL is 384×272 pixels and NTSC is 384×247 pixels. A scenario can observe the screen at most at 64 checkpoints.
 
 `exclude` is a list of bytes in the observed range that the comparison does not include. Each has `at` and a `reason`, for example `{ "at": "$d01e", "reason": "latched sprite collision, not writable" }`. The result lists each excluded byte with its reason.
 

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`);
@@ -283,7 +285,7 @@ export function resolve(location: Location, symbols: Map<string, number>, side:
 interface Observation {
   memory: Array<{ label: string; address: number; bytes: number[]; tolerance: number; excluded: Array<{ offset: number; at: Location; reason: string }> }>;
   registers: Partial<Record<ObservedRegister, unknown>>;
-  screen?: { match: boolean; mismatchingPixels: number; mismatchRatio: number; bounds?: unknown };
+  screen?: { match: boolean; mismatchingPixels: number; comparedPixels: number; mismatchRatio: number; bounds?: unknown };
   vicii?: unknown;
   sprites?: unknown;
   /** PNG images for the files of a FAIL (D46): the side's screen, and on the rebuild the difference image. */
@@ -371,7 +373,7 @@ async function runSide(client: ViceSessionClient, scenario: Scenario, side: Side
           if (files) observation.png = shot.png;
         } else {
           const compared = await client.screenCompare({ baseline, maxMismatchRatio: step.screen.maxMismatchRatio ?? 0, mask: step.screen.mask ?? [], includeDiff: files });
-          observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
+          observation.screen = { match: compared.match, mismatchingPixels: compared.mismatchingPixels, comparedPixels: compared.comparedPixels, mismatchRatio: compared.mismatchRatio, ...(compared.bounds === undefined ? {} : { bounds: compared.bounds }) };
           if (files) {
             observation.png = (await client.screenCapture()).png;
             if (compared.diffPng !== undefined) observation.diffPng = compared.diffPng;

package/skills/c64-unpacker/SKILL.md

@@ -26,17 +26,17 @@ node <skill>/scripts/unpack.ts stages original/game.prg --steps input.json
 node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out parts --drive
 ```
 
-`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages`, a `frames` step counts as run time, and a `runUntil` step is not possible.
+`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages` and `capture`, a `frames` step and a `runUntil` step with only `at` count as run time. `stages` refuses a `runUntil` step with `raster` or `memory`.
 
 | Option | Meaning |
 |---|---|
-| `--until '$c000'` | The address where the unpacked program starts. |
+| `--until '$c000'` | The address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
 | `--out unpacked/game.prg` | Where to write the result, relative to the project directory. |
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
 | `--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). |
@@ -64,18 +64,19 @@ A `type` step puts keys in the keyboard queue of the KERNAL. A program that read
    - `start`: the code at the SYS address. `jumpsOutside` and `writesOutside` give an address outside the loaded program, where the code jumps or writes.
    - `decodeLoops`: EOR instructions in loops that store with an index. This is usually decryption or decoding.
 2. Run `trace`. It gives the evidence from the run. Read `packing`:
-   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is usually the entry point of the unpacked program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
+   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is code that runs after the unpacking. It is not always the entry point of the program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
    - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
    - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
 3. Find the address where the unpacked program starts:
-   - Run `stages`. The `entry` of the last stage is usually the start of the program.
+   - Run `stages`. The `entry` of the last stage is usually the start of the program. A routine that a stage writes and calls is part of that stage when it returns to the stage.
    - Or use `runningRange.start` from `trace`, or `suggestedUntil`. The CPU gets to `suggestedUntil` after the unpacking.
    - Or use the c64-emulator skill: set a breakpoint after the unpack loop, or look at the last JMP of the unpacker.
+   - Disassemble the code at the address with the c64-emulator skill. Make sure that it is the start of the program. The start of a program often sets the stack pointer, the interrupts and the vectors.
 4. Run `capture` with that address and a directory in `--out`. Give the same `--steps` as before. The directory gets:
    - `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. Blocks with the code of an earlier stage are not segments. `writtenBy` tells which stage wrote the segment.
+   - `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.
@@ -113,7 +114,7 @@ Do not record the unpacker in the project knowledge, unless the user asks to exa
 
 The packing evidence, the stages, or the unpacked program with its image, segments and entry state in a directory of the project.
 
-For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture.
+For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
 
 The exit status is 0 for a result. The exit status is 1 for `traced: false`, for `captured: false`, for `loaded: false` and for an error. The exit status is 2 for a wrong argument.
 
@@ -122,10 +123,11 @@ The exit status is 0 for a result. The exit status is 1 for `traced: false`, for
 - `traced: false`: the emulator did not load the program into memory in the time limit. The reason gives the load address. Make sure that the file is a PRG that the C64 can load.
 - `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames. If it stopped in a key wait, give `--steps` with a key.
 - A step did not reach its target: the reason names the step. Change the step or give it more frames.
+- `loaded: false` and no capture has a segment: the program did not load a part, or it did not start. `keyWait: true` on a capture tells that the C64 waited at READY. or at an INPUT statement. For a tape image, read `emulatorFlaw`. A known VICE flaw can stop a tape load. Tell the user to install the latest VICE.
 - Do not name a packer from weak evidence. The script never names one.
 - Some programs unpack in more than one stage. Run `stages` to find each stage. Capture at the entry of the last stage. Make sure that it is the application and not a second unpacker.
 - `not-found` or `invalid-input`: a path or an argument is wrong. Read the message.
-- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 
 ## Handoffs
 

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";
@@ -24,6 +24,8 @@ const DRIVE_RAM = 0x0800;
 const FIRST_SEGMENT_ADDRESS = 0x0400;
 /** The KERNAL LOAD entry in the jump table. */
 const KERNAL_LOAD = 0xffd5;
+/** The KERNAL loop that waits for a key at READY. or at an INPUT statement. */
+const KERNAL_KEY_WAIT = { start: 0xe5cd, end: 0xe5d5 };
 
 /** Reads and checks the steps file of loads: action steps with $ addresses, and capture steps with new names. */
 export function readLoadSteps(path: string): LoadStep[] {
@@ -100,6 +102,8 @@ export async function loads(program: string, options: { out: string; steps: Load
     let loadedProgram: Buffer | undefined;
     /** False while the map holds the writes of the KERNAL RAM test. */
     let writesKnown = true;
+    /** A known flaw of the host's VICE version that a tape load meets (D56). */
+    let emulatorFlaw: string | undefined;
     if (program.toLowerCase().endsWith(".prg")) {
       const { bytes } = readProjectFile(program);
       if (!(await autostartLoaded(client, program, bytes))) return { output: { loaded: false, reason: `The program was not in memory after ${LOAD_LIMIT_FRAMES} frames.` }, failed: true };
@@ -109,12 +113,13 @@ 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);
       await client.memmap({ action: "clear" });
-      await client.autostart({ path: program, index: 0, run: true });
+      ({ emulatorFlaw } = await client.autostart({ path: program, index: 0, run: true }));
       writesKnown = false;
       if (!program.toLowerCase().endsWith(".crt")) {
         // The map starts again where the KERNAL LOAD starts, after the RAM test: then it holds only what the program wrote.
@@ -178,10 +183,12 @@ export async function loads(program: string, options: { out: string; steps: Load
         }),
       );
       write("entry_state.json", json(entryState(registers, state, vectors)));
+      const keyWait = registers.pc >= KERNAL_KEY_WAIT.start && registers.pc <= KERNAL_KEY_WAIT.end;
       captures.push({
         capture: step.capture,
         out: directory,
         pc: formatC64Address(registers.pc),
+        ...(keyWait ? { keyWait: true } : {}),
         segments: segments.map(showRange),
         ...(small === 0 ? {} : { smallChanges: small }),
         ...(drive === undefined ? {} : { drive: drive.file }),
@@ -190,6 +197,11 @@ export async function loads(program: string, options: { out: string; steps: Load
       await client.memmap({ action: "clear" });
       writesKnown = true;
     }
+    if (captures.length > 0 && captures.every((capture) => (capture.segments as unknown[]).length === 0)) {
+      const waits = captures.some((capture) => capture.keyWait === true) ? " The C64 waited for a key at READY. or at an INPUT statement, so the load ended or did not start." : "";
+      const reason = `No capture has a segment: the program changed no block of RAM from ${formatC64Address(FIRST_SEGMENT_ADDRESS)} on.${waits}`;
+      return { output: { loaded: false, reason, captures, ...(emulatorFlaw === undefined ? {} : { emulatorFlaw }) }, failed: true };
+    }
     return { output: { loaded: true, captures }, failed: false };
   } finally {
     await client.close();

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/stages.ts

@@ -4,7 +4,9 @@
 // starts only where the CPU executes an opcode byte that the current stage
 // wrote before the CPU got there. Code that the stage executed before it wrote
 // it is the stage's own code: it stops the run once, and then a write watch
-// over it arms it again.
+// over it arms it again. Written code that the stage calls, and that returns
+// to the stage, is the stage's own code too (D59): a packer hands off by JMP,
+// RTS or RTI and never runs its own code again.
 
 import { COVERAGE } from "#src/c64.ts";
 import { writtenBlocks } from "#src/host-client/coverage.ts";
@@ -26,12 +28,13 @@ export function mergeMaps(into: Uint8Array, from: Uint8Array): void {
  * code that can start a stage: every executed address except own code that
  * the stage has not written.
  */
-export function stageCandidates(stage: Uint8Array, chunk: Uint8Array, own: ReadonlySet<number>, minimum: number): Range[] {
+export function stageCandidates(stage: Uint8Array, chunk: Uint8Array, own: ReadonlySet<number>, minimum: number, called: readonly Range[] = []): Range[] {
   const combined = Uint8Array.from(stage);
   mergeMaps(combined, chunk);
   return writtenBlocks(combined, minimum).filter((block) => {
     for (let address = block.start; address <= block.end; address++) {
       if ((chunk[address]! & COVERAGE.ramExecute) === 0) continue;
+      if (inRanges(called, address)) continue;
       if (own.has(address) && (combined[address]! & COVERAGE.ramWrite) === 0) continue;
       return true;
     }
@@ -44,7 +47,7 @@ export function stageCandidates(stage: Uint8Array, chunk: Uint8Array, own: Reado
  * them except own code that is not written yet, and write watches over that
  * own code.
  */
-export function stagePoints(blocks: readonly Range[], own: ReadonlySet<number>, written: (address: number) => boolean): { exec: Range[]; watch: Range[] } {
+export function stagePoints(blocks: readonly Range[], own: ReadonlySet<number>, written: (address: number) => boolean, called: readonly Range[] = []): { exec: Range[]; watch: Range[] } {
   const exec: Range[] = [];
   const watch: Range[] = [];
   const add = (list: Range[], address: number) => {
@@ -54,6 +57,7 @@ export function stagePoints(blocks: readonly Range[], own: ReadonlySet<number>,
   };
   for (const block of blocks) {
     for (let address = block.start; address <= block.end; address++) {
+      if (inRanges(called, address)) continue;
       if (own.has(address) && !written(address)) add(watch, address);
       else add(exec, address);
     }
@@ -65,3 +69,62 @@ export function stagePoints(blocks: readonly Range[], own: ReadonlySet<number>,
 export function inRanges(ranges: readonly Range[], address: number): boolean {
   return ranges.some((range) => contains(range, address));
 }
+
+/**
+ * Where a call returns to the stage (D59): the return address on top of the
+ * stack, when a JSR that the stage executed pushed it. `stack` is page 1.
+ * Returns the address of the instruction after that JSR.
+ */
+export function callReturn(stack: Uint8Array, sp: number, byteAt: (address: number) => number, executed: (address: number) => boolean): number | undefined {
+  const pushed = stack[(sp + 1) & 0xff]! | (stack[(sp + 2) & 0xff]! << 8);
+  const jsr = (pushed - 2) & 0xffff;
+  if (byteAt(jsr) !== 0x20 || !executed(jsr)) return undefined;
+  return (pushed + 1) & 0xffff;
+}
+
+/**
+ * The code that ran in a block: its executed opcode bytes with the two bytes
+ * after each, which can be operands, joined and cut at the block's end.
+ */
+export function executedIn(map: Uint8Array, block: Range): Range[] {
+  const ranges: Range[] = [];
+  for (let address = block.start; address <= block.end; address++) {
+    if ((map[address]! & COVERAGE.ramExecute) === 0) continue;
+    const end = Math.min(block.end, address + 2);
+    const last = ranges[ranges.length - 1];
+    if (last !== undefined && address <= last.end + 1) last.end = Math.max(last.end, end);
+    else ranges.push({ start: address, end });
+  }
+  return ranges;
+}
+
+/**
+ * The segments of a capture: the blocks that the stages wrote, without loader
+ * leftovers, joined into ranges that do not overlap or touch (F-26). A block
+ * is a leftover when it holds the entry of an intermediate stage that started
+ * after the block's writer, and no write from that stage on replaced the code
+ * at that entry (R2-01). Code that a stage ran before a later stage wrote over
+ * it never drops a block, and the block that holds the capture entry is always
+ * a segment. The filter comes before the join: a join first would drop the
+ * program with a leftover. `writtenBy` is the last stage that wrote into the
+ * range.
+ */
+export function captureSegments(stages: ReadonlyArray<{ entry: number; wrote: readonly Range[] }>, entry: number): Array<Range & { writtenBy: number }> {
+  const last = stages.length - 1;
+  const replaced = (from: number, address: number) => stages.slice(from).some((stage) => inRanges(stage.wrote, address));
+  const leftover = (block: Range, writer: number) =>
+    !contains(block, entry) && stages.some((stage, index) => index > writer && index < last && contains(block, stage.entry) && !replaced(index, stage.entry));
+  const blocks = stages
+    .flatMap((stage, index) => stage.wrote.map((range) => ({ start: range.start, end: range.end, writtenBy: index })))
+    .filter((block) => !leftover(block, block.writtenBy))
+    .sort((a, b) => a.start - b.start);
+  const segments: Array<Range & { writtenBy: number }> = [];
+  for (const block of blocks) {
+    const previous = segments[segments.length - 1];
+    if (previous !== undefined && block.start <= previous.end + 1) {
+      previous.end = Math.max(previous.end, block.end);
+      previous.writtenBy = Math.max(previous.writtenBy, block.writtenBy);
+    } else segments.push({ ...block });
+  }
+  return segments;
+}