@henols/c64-re-tools 2.1.0 → 2.1.1

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

@@ -12,10 +12,11 @@ import { readCoverage, writtenBlocks } from "#src/host-client/coverage.ts";
 import { resetToReady } from "#src/host-client/entry-state.ts";
 import { readActionSteps, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
-import { readProjectFile, writeReported, type Written } from "#src/host-client/transfer.ts";
+import { readPrg } from "#src/host-client/image.ts";
+import { writeReported, type Written } from "#src/host-client/transfer.ts";
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { knowledgeAt, knowledgeNames } from "#src/knowledge/names.ts";
-import { OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec } from "#src/script.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call, type CommandSpec, type OptionSpec } from "#src/script.ts";
 import { basicStart, inspect, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
 import { loads, readLoadSteps } from "./lib/loads.ts";
 import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, withoutRanges } from "./lib/stages.ts";
@@ -38,10 +39,12 @@ async function runSteps(client: ViceSessionClient, steps: ActionStep[]): Promise
   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");
-  if (options.entry === undefined && basicStart(bytes) === undefined) throw new UsageError(NO_BASIC);
+/** inspect, trace, stages and capture take a PRG: a disk, tape or cartridge file goes to loads. */
+const NOT_PRG_REMEDY = "Use loads, which runs a disk, tape or cartridge image, or get the PRG out of it with disk.ts read of the c64-disk skill";
+const readProgram = (path: string) => readPrg(path, NOT_PRG_REMEDY).bytes;
+
+async function trace(program: string, options: { frames: number; entry?: number; steps: ActionStep[]; max: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const bytes = startable(program, options.entry);
   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.
@@ -54,7 +57,12 @@ async function trace(program: string, options: { frames: number; entry?: number;
       const step = await client.execution({ action: "advance-frames", count: Math.min(MAX_ADVANCE, options.frames - ran), space: "c64" });
       const advanced = step.advancedFrames ?? 0;
       ran += advanced;
-      if (advanced === 0) break;
+      // A JAM or a point stops the run before its frames: the evidence would be of a run that did not happen.
+      if ((step.stopReason !== undefined && step.stopReason !== "frames") || advanced === 0) {
+        const stopReason = step.stopReason ?? "no-frames";
+        const at = step.pc ?? (await client.registersGet("c64")).pc;
+        return { output: { traced: false, frames: ran, stopReason, pc: formatC64Address(at), reason: stoppedEarly(stopReason, at, ran, options.frames) }, failed: true };
+      }
     }
     const { pc } = await client.registersGet("c64");
     const ranges = await readMemoryMap(async (start) => {
@@ -80,7 +88,7 @@ async function trace(program: string, options: { frames: number; entry?: number;
         traced: true,
         frames: ran,
         pc: formatC64Address(pc),
-        writtenThenExecuted: written.map((range) => ({
+        writtenThenExecuted: listed(written, options.max, (range) => ({
           start: formatC64Address(range.start),
           end: formatC64Address(range.end),
           ...(underRom(range.start) ? { underRom: true } : {}),
@@ -107,6 +115,12 @@ async function trace(program: string, options: { frames: number; entry?: number;
 
 const NO_BASIC = "the program is no BASIC program at $0801, so RUN cannot start it. Give --entry <address>.";
 
+/** Why a run stopped before its frames: what stopped the CPU, where, and after how many frames. */
+function stoppedEarly(stopReason: string, pc: number, ran: number, frames: number): string {
+  const what = stopReason === "jam" ? "a JAM instruction" : stopReason === "no-frames" ? "the emulator, which ran no frame" : `a ${stopReason}`;
+  return `The CPU stopped at ${formatC64Address(pc)} by ${what} after ${ran} of ${frames} frames. Check --entry and the steps: the program must run for the frames.`;
+}
+
 /** The first PC in one of the ranges within SYS_FRAMES frames, found with exec breakpoints over them. */
 async function firstPcIn(client: ViceSessionClient, ranges: Array<{ start: number; end: number }>): Promise<number | undefined> {
   const points = [];
@@ -175,6 +189,8 @@ interface Followed {
   reached: boolean;
   /** Why the program did not start, when it did not. */
   failed?: string;
+  /** What stopped the CPU before the frames ran: a JAM or a point of the program. */
+  halted?: { stopReason: string; pc: number };
 }
 
 type RunUntilStep = Extract<ActionStep, { runUntil: unknown }>;
@@ -197,13 +213,11 @@ function trackedRunUntil(step: ActionStep): step is RunUntilStep & { runUntil: {
 async function follow(
   client: ViceSessionClient,
   program: string,
+  bytes: Uint8Array,
   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 basic = basicStart(bytes);
-  if (options.entry === undefined && basic === undefined) throw new UsageError(NO_BASIC);
   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.
@@ -216,6 +230,7 @@ async function follow(
   let firstFrame = 0;
   let total = 0;
   let ended = false;
+  let halted: { stopReason: string; pc: number } | undefined;
   /** Where the run stops: the target of a runUntil step while it runs, then until. */
   let stopAt: number | undefined;
   const atTarget = (pc: number) => stopAt !== undefined && pc === stopAt;
@@ -235,7 +250,7 @@ async function follow(
    * blocks, and stops at the first opcode that the stage wrote and the CPU
    * then executes. Own code stops the run once; a write watch arms it again.
    */
-  const rerun = async (candidates: AddressRange[], frames: number): Promise<{ used: number; map: Uint8Array; next?: number; atTarget: boolean }> => {
+  const rerun = async (candidates: AddressRange[], frames: number): Promise<{ used: number; map: Uint8Array; next?: number; atTarget: boolean; halted?: { stopReason: string; pc: number } }> => {
     const points = new Map<string, { kind: "exec" | "watch"; id: number }>();
     const arm = async (wanted: { exec: AddressRange[]; watch: AddressRange[] }) => {
       const keys = new Set([...wanted.exec.map((range) => `exec:${range.start}:${range.end}`), ...wanted.watch.map((range) => `watch:${range.start}:${range.end}`)]);
@@ -295,6 +310,7 @@ async function follow(
         left -= advanced;
         const pc = run.pc ?? (await client.registersGet("c64")).pc;
         map = await readCoverage(client);
+        if (run.stopReason === "jam") return { used, map, atTarget: false, halted: { stopReason: "jam", pc } };
         // A frame can end in written code that the stage called before: that stop starts no stage.
         if (inRanges(candidates, pc) && !inRanges(stage.called, pc)) {
           if (written(pc)) {
@@ -341,6 +357,14 @@ async function follow(
       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);
+      // A JAM, or a point that is not the target, ends the run before its frames.
+      if (first.stopReason !== undefined && first.stopReason !== "frames" && !atTarget(firstPc)) {
+        total += first.advancedFrames ?? 0;
+        mergeMaps(stage.map, map);
+        halted = { stopReason: first.stopReason, pc: firstPc };
+        ended = true;
+        continue;
+      }
       const candidates = stageCandidates(stage.map, map, stage.own, options.minStage, stage.called);
       if (candidates.length === 0) {
         const advanced = first.advancedFrames ?? 0;
@@ -369,6 +393,10 @@ async function follow(
       if (again.next !== undefined) await startStage(again.next, again.map);
       else mergeMaps(stage.map, again.map);
       if (again.atTarget) stopped = true;
+      if (again.halted !== undefined) {
+        halted = again.halted;
+        ended = true;
+      }
     }
     return stopped;
   };
@@ -389,7 +417,8 @@ async function follow(
     else if (trackedRunUntil(step)) {
       if (!(await trackTo(knowledgeAt()(step.runUntil.target.address), step.runUntil.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.runUntil.timeoutFrames} frames. It is at ${formatC64Address(pc)}.` };
+        const why = halted === undefined ? "" : ` ${stoppedEarly(halted.stopReason, halted.pc, total, step.runUntil.timeoutFrames)}`;
+        return { stages: found, frames: total, reached: false, failed: `Step ${index + 1} did not reach its target in ${step.runUntil.timeoutFrames} frames. It is at ${formatC64Address(pc)}.${why}` };
       }
     } else await runActionStep(client, step, knowledgeAt());
   }
@@ -400,7 +429,7 @@ async function follow(
   await client.snapshot({ action: "remove", name: STAGE_SNAPSHOT }).catch(() => undefined);
   mergeMaps(stage.map, await readCoverage(client));
   found.push({ entry, firstFrame, frames: total - firstFrame, wrote: writtenBlocks(stage.map, options.minStage) });
-  return { stages: found, frames: total, reached };
+  return { stages: found, frames: total, reached, ...(halted === undefined ? {} : { halted }) };
 }
 
 const showRange = (range: { start: number; end: number }) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) });
@@ -413,11 +442,23 @@ const showStages = (stages: Stage[]) =>
     ...(stage.next === undefined ? {} : { next: formatC64Address(stage.next) }),
   }));
 
+/** The bytes of a PRG that the emulator starts: RUN needs a BASIC program at $0801, else --entry gives the start. Checked before the emulator opens. */
+function startable(program: string, entry: number | undefined): Uint8Array {
+  const bytes = readProgram(program);
+  if (entry === undefined && basicStart(bytes) === undefined) throw new UsageError(NO_BASIC);
+  return bytes;
+}
+
 async function stages(program: string, options: { frames: number; entry?: number; steps: ActionStep[]; minStage: number }): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const bytes = startable(program, options.entry);
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
-    const followed = await follow(client, program, options);
+    const followed = await follow(client, program, bytes, options);
     if (followed.failed !== undefined) return { output: { followed: false, reason: followed.failed }, failed: true };
+    if (followed.halted !== undefined) {
+      const { stopReason, pc } = followed.halted;
+      return { output: { followed: false, frames: followed.frames, stopReason, pc: formatC64Address(pc), reason: stoppedEarly(stopReason, pc, followed.frames, options.frames), stages: showStages(followed.stages) }, failed: true };
+    }
     return {
       output: {
         followed: true,
@@ -437,14 +478,20 @@ async function capture(
   program: string,
   options: { until: number; out: string; range?: AddressRange; exclude: AddressRange[]; timeoutFrames: number; entry?: number; steps: ActionStep[]; minStage: number },
 ): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const bytes = startable(program, options.entry);
   const client = await ViceSessionClient.open({ videoStandard: "pal" });
   try {
-    const followed = await follow(client, program, { frames: options.timeoutFrames, steps: options.steps, minStage: options.minStage, until: options.until, ...(options.entry === undefined ? {} : { entry: options.entry }) });
+    const followed = await follow(client, program, bytes, { frames: options.timeoutFrames, steps: options.steps, minStage: options.minStage, until: options.until, ...(options.entry === undefined ? {} : { entry: options.entry }) });
     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 is at ${formatC64Address(registers.pc)}.`, stages: showStages(followed.stages) },
+        output: {
+          captured: false,
+          reason: `The program did not get to ${formatC64Address(options.until)} in ${options.timeoutFrames} frames. It is at ${formatC64Address(registers.pc)}.${followed.halted === undefined ? "" : ` ${stoppedEarly(followed.halted.stopReason, followed.halted.pc, followed.frames, options.timeoutFrames)}`}`,
+          ...(followed.halted === undefined ? {} : { stopReason: followed.halted.stopReason }),
+          stages: showStages(followed.stages),
+        },
         failed: true,
       };
     }
@@ -453,10 +500,6 @@ async function capture(
     const state = await machineState(client);
     // The segments: what the stages wrote, without loader leftovers, with no overlap.
     const found = options.range !== undefined ? [options.range] : captureSegments(followed.stages, registers.pc);
-    const inside = options.exclude.find((range) => registers.pc >= range.start && registers.pc <= range.end);
-    if (inside !== undefined) {
-      return { output: { captured: false, reason: `The entry ${formatC64Address(registers.pc)} is in --exclude ${formatC64Address(inside.start)}-${formatC64Address(inside.end)}. A segment must hold the entry.` }, failed: true };
-    }
     const segments = withoutRanges(found, options.exclude);
     const file = (path: string) => `${options.out}/${path}`;
     const written: Written[] = [];
@@ -534,14 +577,14 @@ const COMMANDS: CommandSpec[] = [
     name: "inspect",
     summary: "Packing evidence: the BASIC start and the entropy of the bytes.",
     subjects: [PROGRAM],
-    run: (call) => inspect(readProjectFile(call.subject(0)).bytes),
+    run: (call) => inspect(readProgram(call.subject(0))),
   },
   {
     name: "trace",
     summary: "Runs the program and reports the memory that it wrote and then executed.",
     subjects: [PROGRAM],
-    options: { frames: FRAMES, entry: ENTRY, steps: STEPS },
-    run: async (call) => outcome(await trace(call.subject(0), { frames: call.count("frames")!, steps: stepsOf(call), ...entryOf(call) })),
+    options: { frames: FRAMES, entry: ENTRY, steps: STEPS, "max-listed": OPTIONS["max-listed"] },
+    run: async (call) => outcome(await trace(call.subject(0), { frames: call.count("frames")!, steps: stepsOf(call), max: call.count("max-listed")!, ...entryOf(call) })),
   },
   {
     name: "stages",
@@ -573,7 +616,14 @@ const COMMANDS: CommandSpec[] = [
     notes: "entry_state.json has the registers, $00/$01, pages 0-3, the VIC, SID and CIA registers, the vectors, and what differs from a clean reset.",
     run: async (call) => {
       const range = call.range("range");
-      return outcome(await capture(call.subject(0), { until: call.address("until")!, out: call.string("out")!, ...(range === undefined ? {} : { range }), exclude: call.ranges("exclude"), timeoutFrames: call.count("timeout-frames")!, steps: stepsOf(call), minStage: call.count("min-stage")!, ...entryOf(call) }));
+      const until = call.address("until")!;
+      // A segment must hold the entry: refused before the emulator runs.
+      const show = (item: AddressRange) => `${formatC64Address(item.start)}-${formatC64Address(item.end)}`;
+      const holds = (item: AddressRange) => until >= item.start && until <= item.end;
+      const excluded = call.ranges("exclude").find(holds);
+      if (excluded !== undefined) throw new UsageError(`--exclude ${show(excluded)} holds the entry --until ${formatC64Address(until)}. A segment must hold the entry: give an --exclude range without it`);
+      if (range !== undefined && !holds(range)) throw new UsageError(`--range ${show(range)} does not hold the entry --until ${formatC64Address(until)}. Give a --range that holds the entry`);
+      return outcome(await capture(call.subject(0), { until, out: call.string("out")!, ...(range === undefined ? {} : { range }), exclude: call.ranges("exclude"), timeoutFrames: call.count("timeout-frames")!, steps: stepsOf(call), minStage: call.count("min-stage")!, ...entryOf(call) }));
     },
   },
   {

package/src/host/vice/session.ts

@@ -187,6 +187,16 @@ export class ViceSession implements ViceSessionHandle {
   #haltCount = 0;
   /** What stopped the machine last, when a user breakpoint or watchpoint or a JAM did; cleared when it runs again. */
   #lastStop: { stopReason: PointStopReason; pointId?: number } | undefined;
+  /**
+   * The pc of the JAM that holds the CPU. A jammed CPU runs again only after a
+   * reset, a snapshot restore or an autostart: VICE 3.10 keeps it jammed after a
+   * pc write, and reports the JAM only once.
+   */
+  #jammed: number | undefined;
+  /** VICE records no CPU history after a JAM until the next reset. */
+  #historyStopped = false;
+  /** The CPU ran again after a JAM without a reset: the CPU history that VICE gives is old. */
+  #historyOld = false;
   #queue: Promise<unknown> = Promise.resolve();
   #closed = false;
   #lost = false;
@@ -404,6 +414,7 @@ export class ViceSession implements ViceSessionHandle {
           centred.push(port);
         }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
+        this.#clearJam();
         if (type === "crt") this.#cartridge = true;
         this.#replaceStaged(stagedKind(type), file);
         // A reset sets the CPU clock back, so the stopwatch starts again.
@@ -431,7 +442,7 @@ export class ViceSession implements ViceSessionHandle {
       case "screenCapture": {
         const { baseline } = params as ViceOperations["screenCapture"]["params"];
         if (baseline !== undefined && !this.#baselines.has(baseline) && this.#baselines.size >= MAX_BASELINES) {
-          throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_BASELINES} baselines. Discard one first.`);
+          throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_BASELINES} baselines. Remove one first with c64_screen action remove.`);
         }
         const shot = await this.#observe(() => this.#machine.captureFrame(this.#videoStandard));
         if (baseline !== undefined) this.#baselines.set(baseline, shot);
@@ -530,7 +541,7 @@ export class ViceSession implements ViceSessionHandle {
     if (status.state === "stopped") {
       status.pc = await this.#pc();
       // VICE 3.9 sends no JAM event: the opcode at the pc tells.
-      const stop = this.#lastStop ?? ((await this.#jammedAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
+      const stop = this.#lastStop ?? ((await this.#jamAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
       if (stop !== undefined) Object.assign(status, stop);
     }
     return status;
@@ -538,7 +549,10 @@ export class ViceSession implements ViceSessionHandle {
 
   async #execution(params: ExecutionParams): Promise<ExecutionResult> {
     if (params.action === "resume") {
-      if (this.#state === "stopped") await this.#resume();
+      if (this.#state === "stopped") {
+        await this.#refuseJammed("resume");
+        await this.#resume();
+      }
       return { state: "running" };
     }
     if (params.action === "pause") {
@@ -546,6 +560,9 @@ export class ViceSession implements ViceSessionHandle {
       // A drive checkpoint can stop the machine just before the pause does.
       return { state: "stopped", pc: (await this.#completeDriveStop()) ?? (await this.#pc()) };
     }
+    if (params.space === "drive8" && params.action === "advance-frames") {
+      throw new WireFailure("unsupported-in-space", "advance-frames counts the video frames of the computer: use space c64. A breakpoint or watchpoint in space drive8 also stops it.");
+    }
     if (params.space === "drive8") {
       // Stock VICE runs the 1541 CPU in batches that catch up with the computer's clock;
       // neither monitor can stop it after exactly one of its instructions.
@@ -565,13 +582,16 @@ export class ViceSession implements ViceSessionHandle {
       const outcome = await this.#runFrames(params.count, undefined, params.anchor);
       return {
         state: "stopped",
-        pc: outcome.pc,
+        // A stop event carries the computer's PC; a stop in the drive reports the drive's.
+        pc: outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc,
+        space: outcome.space,
         advancedFrames: outcome.frames,
         stopReason: outcome.end === "target" ? "frames" : outcome.end,
         ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }),
       };
     }
     await this.#stop();
+    await this.#refuseJammed(params.action);
     if (params.action === "until-return") {
       const stopped = this.#nextStop(this.#untilReturnLimitMs);
       await this.#resumingCommand(() => this.#machine.untilReturn());
@@ -599,6 +619,7 @@ export class ViceSession implements ViceSessionHandle {
 
   async #reset(params: { mode: "soft" | "hard"; run: boolean }): Promise<{ state: RunState; pc?: number }> {
     await this.#stop();
+    this.#clearJam();
     // A reset sets the CPU clock back, so the stopwatch starts again.
     this.#timingStart = 0n;
     if (params.run) {
@@ -637,11 +658,15 @@ export class ViceSession implements ViceSessionHandle {
     const start = anchor ?? (await this.#machine.rasterPosition());
     const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
     const ending = rasterWindowExpression(start.line, start.cycle, lines);
+    const startPc = await this.#pc();
+    if (await this.#jamAt(startPc)) return { end: "jam", frames: 0, pc: startPc, space: "c64" };
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       await this.#machine.setCondition(clock, arming);
       let armingPhase = true;
       let frames = 0;
+      // VICE reports a JAM only once until a reset: a jammed CPU stops the clock at the same pc again and again.
+      let clockPc = startPc;
       for (;;) {
         const next = this.#nextStop(HALF_FRAME_LIMIT_MS);
         await this.#resume();
@@ -652,6 +677,8 @@ export class ViceSession implements ViceSessionHandle {
         }
         const end = this.#stopCause(stop, clock, target?.checkpoint);
         if (end === "clock") {
+          if (stop.pc === clockPc && (await this.#jamAt(stop.pc))) return { end: "jam", frames, pc: stop.pc, space: "c64" };
+          clockPc = stop.pc;
           if (armingPhase) {
             await this.#machine.setCondition(clock, ending);
             if (target?.deferred) {
@@ -667,7 +694,7 @@ export class ViceSession implements ViceSessionHandle {
           continue;
         }
         if (end === "unknown") {
-          if (await this.#jammedAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
+          if (await this.#jamAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
           throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this run.");
         }
         // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
@@ -699,6 +726,9 @@ export class ViceSession implements ViceSessionHandle {
     const points: number[] = [];
     const hits: TraceHit[] = [];
     let frames = 0;
+    const startPc = await this.#pc();
+    if (await this.#jamAt(startPc)) return { hits, frames, end: "jam", pc: startPc };
+    let clockPc = startPc;
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       for (const point of params.points) points.push(await this.#machine.addCheckpoint({ start: point.start, end: point.end, operation: operation[point.kind], space: "c64" }));
@@ -718,6 +748,8 @@ export class ViceSession implements ViceSessionHandle {
           if (hits.length >= params.maxHits) return { hits, frames, end: "hits", pc: stop.pc };
         }
         if (stop.hits.includes(clock)) {
+          if (stop.pc === clockPc && (await this.#jamAt(stop.pc))) return { hits, frames, end: "jam", pc: stop.pc };
+          clockPc = stop.pc;
           if (armingPhase) await this.#machine.setCondition(clock, ending);
           else {
             frames++;
@@ -730,7 +762,7 @@ export class ViceSession implements ViceSessionHandle {
         if (traced.length > 0) continue;
         const point = this.#userPoint(stop.hits);
         if (point !== undefined) return { hits, frames, end: point.stopReason, pc: stop.pc };
-        if (await this.#jammedAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
+        if (await this.#jamAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
         throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this trace.");
       }
     } finally {
@@ -844,9 +876,40 @@ export class ViceSession implements ViceSessionHandle {
     return undefined;
   }
 
-  async #jammedAt(pc: number): Promise<boolean> {
+  /**
+   * True when a JAM holds the CPU at `pc`: the session saw a JAM since the last
+   * reset, restore or autostart, or the opcode at `pc` is a JAM. The CPU stops
+   * on such an opcode, so it executes nothing more. The session keeps the JAM.
+   */
+  async #jamAt(pc: number): Promise<boolean> {
+    if (this.#jammed !== undefined) return true;
     const opcode = await this.#machine.readMemory({ address: pc, size: 1, space: "c64", view: "cpu" });
-    return JAM_OPCODES.has(Number.parseInt(opcode, 16));
+    if (!JAM_OPCODES.has(Number.parseInt(opcode, 16))) return false;
+    this.#jam(pc);
+    return true;
+  }
+
+  #jam(pc: number): void {
+    this.#jammed = pc;
+    this.#historyStopped = true;
+  }
+
+  /** A reset or an autostart starts a jammed CPU and the CPU history again. */
+  #clearJam(): void {
+    this.#jammed = undefined;
+    this.#historyStopped = false;
+    this.#historyOld = false;
+  }
+
+  /** Refuses an action that needs the CPU to execute, while a JAM holds it. */
+  async #refuseJammed(action: string): Promise<void> {
+    const pc = await this.#pc();
+    if (!(await this.#jamAt(pc))) return;
+    throw new WireFailure(
+      "operation-failed",
+      `The CPU is jammed by the JAM opcode at ${formatC64Address(this.#jammed ?? pc)}, so ${action} cannot execute an instruction. ` +
+        "The CPU runs again only after c64_reset, a snapshot restore or c64_autostart.",
+    );
   }
 
   /** Runs until a target is reached or `timeoutFrames` frames pass. */
@@ -1050,6 +1113,13 @@ export class ViceSession implements ViceSessionHandle {
    * stop, whose position is known, mapped back through the frame.
    */
   async #cpuHistory(params: { limit: number; space: "c64" | "drive8" }): Promise<{ entries: HistoryEntry[] }> {
+    if (params.space === "c64" && this.#historyOld) {
+      throw new WireFailure(
+        "operation-failed",
+        "VICE records no CPU history after a JAM until the next reset, and the CPU ran after the JAM. The history would show old instructions. " +
+          "Use c64_reset to record again, or use c64_trace.",
+      );
+    }
     return this.#observe(async () => {
       const raw = await this.#machine.history(params.limit, params.space);
       if (params.space === "drive8") return { entries: raw.map(({ clock: _clock, ...entry }) => entry) };
@@ -1128,7 +1198,7 @@ export class ViceSession implements ViceSessionHandle {
     const existing = this.#snapshots.get(params.name);
     if (params.action === "save") {
       if (existing === undefined && this.#snapshots.size >= MAX_SNAPSHOTS) {
-        throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_SNAPSHOTS} snapshots. Discard one first.`);
+        throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_SNAPSHOTS} snapshots. Remove one first with action remove.`);
       }
       const file = existing ?? join(this.#workDir, `snapshot-${++this.#snapshotFiles}.vsf`);
       await this.#observe(() => this.#machine.saveSnapshot(file));
@@ -1149,6 +1219,9 @@ export class ViceSession implements ViceSessionHandle {
     await this.#stop();
     const elapsed = (await this.#machine.clock()) - this.#timingStart;
     await this.#machine.restoreSnapshot(file);
+    // A restore starts a jammed CPU again, but VICE still records no CPU history.
+    this.#jammed = undefined;
+    if (this.#historyStopped) this.#historyOld = true;
     this.#state = "stopped";
     // The cycle clock jumped with the restore; the stopwatch keeps its reading, as a window move does.
     this.#timingStart = (await this.#machine.clock()) - elapsed;
@@ -1168,13 +1241,26 @@ export class ViceSession implements ViceSessionHandle {
     // Checked before the machine stops: VICE gives no reason for a file that is no snapshot.
     if (!bytes.subarray(0, VSF_MAGIC.length).equals(VSF_MAGIC)) throw new WireFailure("invalid-input", "The file is not a VICE snapshot file (.vsf). Give a file that c64_snapshot save wrote.");
     const file = this.#stage(bytes, "vsf");
+    // VICE resets the machine after a snapshot file that it cannot read: a backup keeps the state before the restore.
+    const backup = join(this.#workDir, "before-restore.vsf");
+    await this.#stop();
+    await this.#machine.saveSnapshot(backup);
     try {
       return await this.#restoreFrom(file);
     } catch (error) {
+      const kept = await this.#restoreFrom(backup).then(
+        () => true,
+        () => false,
+      );
+      if (!kept) throw new WireFailure("machine-state-lost", "The emulator did not restore this snapshot file, and the machine state from before the restore is lost. Load the program again.");
       if (error instanceof WireFailure) throw error;
-      throw new WireFailure("invalid-input", "The emulator did not restore this snapshot file. A snapshot file restores only in the emulator version and with the machine settings that saved it.");
+      throw new WireFailure(
+        "invalid-input",
+        "The emulator did not restore this snapshot file. The machine state is as before. A snapshot file restores only in the emulator version and with the machine settings that saved it.",
+      );
     } finally {
       rmSync(file, { force: true });
+      rmSync(backup, { force: true });
     }
   }
 
@@ -1255,6 +1341,8 @@ export class ViceSession implements ViceSessionHandle {
       if (this.#closed) throw new WireFailure("machine-unavailable", "The emulator session is closed.");
       this.#vice = vice;
       this.#adapter = adapter;
+      // A new emulator: no JAM holds its CPU, and it records CPU history.
+      this.#clearJam();
       this.#mode = mode;
       for (const [point, checkpoint] of points) point.checkpoint = checkpoint;
       this.#timingStart = clock - handover.elapsed;
@@ -1515,6 +1603,7 @@ export class ViceSession implements ViceSessionHandle {
       if (stop.hits.length > 0 || event.type === ResponseType.jam) this.#haltCount++;
       if (stop.hits.some((hit) => this.#adapter?.isDriveCheckpoint(hit))) this.#driveStop = true;
       this.#lastStop = event.type === ResponseType.jam ? { stopReason: "jam" } : this.#userPoint(stop.hits);
+      if (event.type === ResponseType.jam) this.#jam(stop.pc);
       this.#checkpointHits = [];
       this.#state = "stopped";
       this.#stopWaiters = this.#stopWaiters.filter((waiter) => !waiter(stop));

package/src/host-client/image.ts

@@ -21,6 +21,38 @@ export interface Image {
   stages?: Array<Record<string, unknown>>;
 }
 
+/** The kinds of media files that are no PRG, by extension. */
+const MEDIA_KINDS: Record<string, string> = {
+  d64: "a disk image",
+  d71: "a disk image",
+  d81: "a disk image",
+  g64: "a disk image",
+  x64: "a disk image",
+  t64: "a tape file",
+  tap: "a tape file",
+  crt: "a cartridge file",
+};
+
+/** The remedy for a disk, tape or cartridge file where a PRG must be: get the PRG out of it. */
+export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts crt for a cartridge) of the c64-disk skill";
+
+/**
+ * Reads a PRG of the project: a 2-byte load address, and bytes that end at
+ * $ffff or before. Refuses a disk, tape or cartridge file and any other file
+ * that is no PRG with invalid-input; `remedy` tells what to do in its place.
+ */
+export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
+  const { bytes, type } = readProjectFile(path);
+  const media = MEDIA_KINDS[type];
+  if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+  try {
+    return { bytes, ...prgRange(bytes) };
+  } catch (error) {
+    if (isRefusal(error)) throw new Refusal("invalid-input", `${path} is not a PRG: ${error.message} ${remedy}.`);
+    throw error;
+  }
+}
+
 /** Reads an image.json or a PRG, relative to the project folder. */
 export function readImage(path: string): Image {
   const { bytes } = readProjectFile(path);