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

package/src/c64.ts

@@ -128,7 +128,7 @@ export function textToPetsciiName(text: string): Uint8Array {
 /** BASIC refuses higher line numbers when a line is entered. */
 const MAX_LINE_NUMBER = 63999;
 
-const TOKEN = { data: 0x83, rem: 0x8f, sys: 0x9e, usr: 0xb7, plus: 0xaa, minus: 0xab, times: 0xac, divide: 0xad } as const;
+const TOKEN = { data: 0x83, rem: 0x8f, sys: 0x9e, usr: 0xb7, plus: 0xaa, minus: 0xab, times: 0xac, divide: 0xad, pi: 0xff } as const;
 const QUOTE = 0x22;
 const COLON = 0x3a;
 
@@ -138,15 +138,27 @@ export interface TokenizedLine {
   tokens: Uint8Array;
 }
 
-/** A machine-code handoff in BASIC program text: SYS with a constant address, or a SYS or USR whose target needs run-time values. */
-export type BasicHandoff = { kind: "sys"; line: number; address: number } | { kind: "sys" | "usr"; line: number; computed: true };
+/**
+ * A machine-code handoff in BASIC program text: SYS with a constant address, a
+ * SYS whose argument needs run-time values (with the argument as text), or a USR.
+ */
+export type BasicHandoff =
+  | { kind: "sys"; line: number; address: number }
+  | { kind: "sys"; line: number; computed: true; expression: string }
+  | { kind: "usr"; line: number; computed: true };
 
-export type TokenizedProgram = { loadAddress: number; basicEnd: number; lines: TokenizedLine[] } | { reason: string };
+/**
+ * `basicEnd` is the first address that holds no BASIC; `textBytes` is the
+ * number of file bytes (load address included) before the end of the BASIC text.
+ */
+export type TokenizedProgram = { loadAddress: number; basicEnd: number; textBytes: number; lines: TokenizedLine[] } | { reason: string };
 
 /**
  * Splits a PRG into BASIC lines the way BASIC relinks a loaded program: each
  * line ends at a zero byte, and a link whose high byte is zero ends the
- * program. The stored links are not trusted.
+ * program. The stored links are not trusted. A real end marker is two zero
+ * bytes; when only the high byte is zero, the "marker" is the first machine
+ * code after the BASIC text (SYS lines that jump right behind themselves).
  */
 export function parseTokenized(program: Uint8Array): TokenizedProgram {
   if (program.length < 4) return { reason: "The file is too short for a BASIC program." };
@@ -157,12 +169,13 @@ export function parseTokenized(program: Uint8Array): TokenizedProgram {
   for (;;) {
     // A file that ends right after a line leaves the end marker to the zeros after it in memory;
     // basicEnd is the address after that marker, as when the file holds it.
-    if (at === program.length && lines.length > 0) return { loadAddress, basicEnd: loadAddress + at, lines };
+    if (at === program.length && lines.length > 0) return { loadAddress, basicEnd: loadAddress + at, textBytes: at, lines };
     if (at + 1 >= program.length) return { reason: "The BASIC program has no end marker." };
     if (program[at + 1] === 0) {
       // An end marker before any line, with more bytes after it, is how machine code at a non-BASIC address often starts.
       if (lines.length === 0 && at + 2 < program.length) return { reason: "The file holds no BASIC line before other bytes, so it is no BASIC program." };
-      return { loadAddress, basicEnd: loadAddress + at, lines };
+      const marker = program[at] === 0;
+      return { loadAddress, basicEnd: loadAddress + (marker ? at : at - 2), textBytes: at, lines };
     }
     if (at + 4 > program.length) return { reason: "The last BASIC line is cut off." };
     const number = program[at + 2]! | (program[at + 3]! << 8);
@@ -188,13 +201,20 @@ const KEYWORDS = [
  * 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} `;
+  return `${line.number} ${basicText(line.tokens)}`;
+}
+
+/** Tokenized BASIC bytes as text, as for basicLineText; pi is π. */
+function basicText(tokens: Uint8Array): string {
+  let text = "";
   let literal = false;
-  for (const byte of line.tokens) {
+  for (const byte of 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 if (!literal && byte === TOKEN.pi) {
+      text += "π";
     } else {
       text += petsciiNameToText(Uint8Array.of(byte));
     }
@@ -203,7 +223,7 @@ export function basicLineText(line: TokenizedLine): string {
 }
 
 /**
- * Evaluates a SYS argument that holds only numbers, + - * / and brackets.
+ * Evaluates a SYS argument that holds only numbers, π, + - * / and brackets.
  * Returns undefined for anything that needs run-time values.
  */
 export function constantExpression(bytes: Uint8Array): number | undefined {
@@ -242,6 +262,10 @@ export function constantExpression(bytes: Uint8Array): number | undefined {
       if (value === undefined || tokens[at++] !== 0x29) return undefined;
       return value;
     }
+    if (peek() === TOKEN.pi) {
+      at++;
+      return Math.PI;
+    }
     return number();
   };
   const product = (): number | undefined => {
@@ -297,8 +321,9 @@ export function findHandoffs(lines: TokenizedLine[]): BasicHandoff[] {
         // The argument ends at the statement end or at a comma (extra SYS parameters).
         let end = at + 1;
         while (end < tokens.length && tokens[end] !== COLON && tokens[end] !== 0x2c) end++;
-        const value = constantExpression(tokens.subarray(at + 1, end));
-        if (value === undefined) handoffs.push({ kind: "sys", line: number, computed: true });
+        const argument = tokens.subarray(at + 1, end);
+        const value = constantExpression(argument);
+        if (value === undefined) handoffs.push({ kind: "sys", line: number, computed: true, expression: basicText(argument).trim() });
         // BASIC drops the fraction; outside 0-65535 SYS stops with ILLEGAL QUANTITY and jumps nowhere.
         else if (Math.trunc(value) >= 0 && Math.trunc(value) <= 0xffff) handoffs.push({ kind: "sys", line: number, address: Math.trunc(value) });
         at = end - 1;

package/src/cli/main.ts

@@ -7,7 +7,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 
-import { PACKAGE } from "../../distribution/package.ts";
+import { PACKAGE } from "../package.ts";
 import { localToolContext } from "../native/local.ts";
 import { localToolStatus } from "../native/status.ts";
 import { WireFailure } from "../protocol/messages.ts";
@@ -51,9 +51,12 @@ async function status(): Promise<number> {
   console.log(`Package: ${join(here, "..", "..")}`);
   console.log(`Node: ${process.version} (${process.execPath})`);
   // The skill scripts run these tools here, on this machine.
-  for (const line of toolLines("Tools here:", await localToolStatus(localToolContext()))) console.log(line);
-  for (const line of await hostStatusLines()) console.log(line);
-  return 0;
+  const local = await localToolStatus(localToolContext());
+  for (const line of toolLines("Tools here:", local)) console.log(line);
+  const host = await hostStatusLines();
+  for (const line of host.lines) console.log(line);
+  // A script or a CI check can tell a ready setup from a broken one.
+  return host.ready && local.every((tool) => tool.runs) ? 0 : 1;
 }
 
 async function main(argv: string[]): Promise<number> {

package/src/cli/status.ts

@@ -5,32 +5,34 @@ 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. */
+/** One line per tool under `heading`: its version, or why it does not run; then each known flaw of it. */
 export function toolLines(heading: string, tools: readonly ToolStatus[]): string[] {
   return [
     heading,
-    ...tools.map((tool) =>
+    ...tools.flatMap((tool) => [
       tool.runs
         ? `  ${tool.name}: ${tool.version} (${tool.path})`
         : tool.found
           ? `  ${tool.name}: found at ${tool.path} but it does not run. ${tool.problem}`
           : `  ${tool.name}: missing. ${tool.problem}`,
-    ),
+      ...(tool.flaws ?? []).map((flaw) => `    Known flaw: ${flaw}`),
+    ]),
   ];
 }
 
 /**
  * Whether the Host Runtime answers, and the tools it has. VICE and its tools
  * live on the host; it finds and runs each one. One request shows both that
- * the host answers and what it has.
+ * the host answers and what it has. `ready` is true when the host answers and
+ * every tool on it runs.
  */
-export async function hostStatusLines(options: ToolCallOptions = {}): Promise<string[]> {
+export async function hostStatusLines(options: ToolCallOptions = {}): Promise<{ lines: string[]; ready: boolean }> {
   let tools: ToolStatus[];
   try {
     tools = await hostTools(options);
   } catch (error) {
     // 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 { lines: [`Host Runtime: not reachable. ${(error as Error).message.replace(` ${STOP_AND_ASK}`, "")}`], ready: false };
   }
-  return ["Host Runtime: reachable", ...toolLines("Tools on the host:", tools)];
+  return { lines: ["Host Runtime: reachable", ...toolLines("Tools on the host:", tools)], ready: tools.every((tool) => tool.runs) };
 }

package/src/host/main.ts

@@ -6,14 +6,16 @@ import { DEFAULT_HOST_PORT } from "../protocol/messages.ts";
 import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
 import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { viceFlaws } from "../native/discover.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
+import { PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>]
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} 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
@@ -68,14 +70,17 @@ async function main(): Promise<number> {
   supervisor.startWatchdog("host");
 
   // Finding x64sc is not enough: VICE without its ROM files exits at once.
+  let flaws: string[];
   try {
-    await checkViceStarts({ supervisor });
+    flaws = viceFlaws(await checkViceStarts({ supervisor }));
   } catch (error) {
     process.stderr.write(`${(error as Error).message}\n`);
     await supervisor.stopAll();
     return 1;
   }
   log("VICE starts");
+  // A known VICE flaw is named, not worked around (D56).
+  for (const flaw of flaws) log(`Known VICE flaw: ${flaw}`);
 
   let server;
   try {
@@ -83,7 +88,7 @@ async function main(): Promise<number> {
       host: "0.0.0.0",
       port,
       log,
-      createViceSession: viceSessionFactory({ supervisor, log }),
+      createViceSession: viceSessionFactory({ supervisor, log, flaws }),
       tools: createToolDispatcher({ supervisor, log }),
     });
   } catch (error) {

package/src/host/tools/petcat.ts

@@ -36,9 +36,13 @@ export async function decode(
   if ("reason" in tokenized) return { result: { decoded: false, reason: tokenized.reason } };
   const executable = findTool(PETCAT, context.env);
   await requireMinimumVersion(PETCAT, executable, context);
+  // petcat gets the BASIC text only, closed with a real end marker: after a
+  // link that only ends BASIC (machine code right after the last line), petcat
+  // prints a comment line where a listing line belongs.
+  const text = Buffer.concat([program.subarray(0, tokenized.textBytes), Buffer.of(0, 0)]);
   const workspace = Workspace.create(context.supervisor);
   try {
-    workspace.materialize("input", [{ path: "program.prg", size: program.length }], [program]);
+    workspace.materialize("input", [{ path: "program.prg", size: text.length }], [text]);
     const listingPath = join(workspace.directory("out"), LISTING);
     const run = await runToolOrFail(
       "petcat",

package/src/host/tools/status.ts

@@ -3,7 +3,7 @@
 // VICE older than MIN_VICE is reported as not working, as its operations refuse it.
 
 import type { ToolStatus } from "../../protocol/tools.ts";
-import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceVersionOf, type ToolSpec } from "../../native/discover.ts";
+import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceFlaws, viceVersionOf, type ToolSpec } from "../../native/discover.ts";
 import type { ToolContext } from "../../native/run.ts";
 import { probeTools } from "../../native/status.ts";
 import { findVice } from "../vice/process.ts";
@@ -26,5 +26,11 @@ export async function hostStatus(context: ToolContext): Promise<{ result: { tool
     ],
     context,
   );
-  return { result: { tools: tools.map((status, index) => requireMinimum(status, specs[index]!)) } };
+  const checked = tools.map((status, index) => requireMinimum(status, specs[index]!));
+  // VICE runs with its known flaws; status names them (D56).
+  const vice = checked[0]!;
+  const version = vice.runs ? viceVersionOf(vice.version ?? "") : undefined;
+  const flaws = version === undefined ? [] : viceFlaws(version);
+  if (flaws.length > 0) checked[0] = { ...vice, flaws };
+  return { result: { tools: checked } };
 }

package/src/host/vice/process.ts

@@ -9,7 +9,8 @@
 //   operations only it offers; both act on the same machine;
 // - autostart of a PRG needs `-autostartprgmode 1` (inject into RAM);
 // - the joyport command reaches the C64 only through the "Joyport I/O
-//   simulation" device (37), whose lines start all pressed until set;
+//   simulation" device (37). In VICE 3.10 and older it holds bits 5-7 of
+//   both CIA 1 ports low (VICE bug #2202, a known flaw named by D56);
 // - with the default JAM action a jammed CPU hangs silently; -jamaction 2
 //   enters the monitor instead;
 // - the monitor's profiler prints numbers in the host locale, so VICE runs
@@ -29,7 +30,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
 import { elapsedMs, trace } from "../../trace.ts";
-import { findTool, isOlderThanMinimum, MIN_VICE, VICE } from "../../native/discover.ts";
+import { findTool, isOlderThanMinimum, MIN_VICE, VICE, type ViceVersion } from "../../native/discover.ts";
 import type { ExitStatus, ProcessSupervisor, SupervisedProcess } from "../../native/processes.ts";
 import { BinaryMonitor, Command, decodeMemory, memoryGetBody } from "./binary-monitor.ts";
 import { TextMonitor } from "./text-monitor.ts";
@@ -200,9 +201,10 @@ export function startErrorLines(output: string[]): string[] {
 /**
  * Starts VICE once, as a session does, and stops it again. Finding
  * x64sc is not enough: without its ROM files VICE exits at once. Throws
- * WireFailure installation-incomplete with VICE's own error lines.
+ * WireFailure installation-incomplete with VICE's own error lines. Returns
+ * the VICE version.
  */
-export async function checkViceStarts(options: Omit<LaunchOptions, "videoStandard" | "log">): Promise<void> {
+export async function checkViceStarts(options: Omit<LaunchOptions, "videoStandard" | "log">): Promise<ViceVersion> {
   const binary = findVice(options.env ?? process.env);
   const output: string[] = [];
   let vice: ViceProcess;
@@ -231,13 +233,16 @@ export async function checkViceStarts(options: Omit<LaunchOptions, "videoStandar
   } finally {
     await vice.stop();
   }
-  const version = { major: info[1] ?? 0, minor: info[2] ?? 0 };
+  // The SVN revision is 0 in a release build.
+  const revision = info.length >= 10 ? info.readUInt32LE(6) : 0;
+  const version = { major: info[1] ?? 0, minor: info[2] ?? 0, ...(revision === 0 ? {} : { revision }) };
   if (isOlderThanMinimum(version)) {
     throw new WireFailure(
       "installation-incomplete",
       `VICE (${binary}) is version ${version.major}.${version.minor}, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${VICE.remedy}`,
     );
   }
+  return version;
 }
 
 async function launchOnce(options: LaunchOptions): Promise<ViceProcess> {

package/src/host/vice/session.ts

@@ -74,6 +74,8 @@ const WINDOW_CLOSED =
   "Breakpoints and watchpoints are kept. Check the machine state before you continue.";
 
 /** Emulator state that a move to another VICE cannot carry. */
+/** The first bytes of every VICE snapshot file. */
+const VSF_MAGIC = Buffer.from("VICE Snapshot File\x1a", "latin1");
 const NOT_CARRIED = ["cpu history", "memory map", "profile", "keyboard input not yet typed"];
 
 /** Starts another VICE for this session; `log` also gets that launch's lines. */
@@ -119,6 +121,8 @@ export interface SessionOptions {
   launch?: ViceLauncher;
   /** Makes the host remove a path if it dies; returns the release. */
   ownPath?: (path: string) => () => void;
+  /** The known flaws of this VICE version (D56); keyboard and joystick results name them. */
+  flaws?: readonly string[];
 }
 
 export class ViceSession implements ViceSessionHandle {
@@ -128,6 +132,8 @@ export class ViceSession implements ViceSessionHandle {
   #mode: ViceMode = "headless";
   readonly #videoStandard: VideoStandard;
   readonly #log: (line: string) => void;
+  /** The known VICE flaws that keyboard and joystick input meet, as one text, or undefined. */
+  readonly #inputFlaw: string | undefined;
   readonly #untilReturnLimitMs: number;
   readonly #stepLimitMs: number;
   readonly #launch: ViceLauncher | undefined;
@@ -196,6 +202,7 @@ export class ViceSession implements ViceSessionHandle {
     this.#untilReturnLimitMs = options.untilReturnLimitMs ?? UNTIL_RETURN_LIMIT_MS;
     this.#stepLimitMs = options.stepLimitMs ?? RUNNING_COMMAND_TIMEOUT_MS;
     this.#launch = options.launch;
+    this.#inputFlaw = options.flaws === undefined || options.flaws.length === 0 ? undefined : options.flaws.join(" ");
     this.#workDir = mkdtempSync(join(tmpdir(), "c64-re-tools-session-"));
     this.#releaseWorkDir = options.ownPath?.(this.#workDir) ?? (() => {});
     this.#watch(vice);
@@ -268,7 +275,7 @@ export class ViceSession implements ViceSessionHandle {
           session.#timingStart = await session.#adapter.clock();
           // c64_profile reports what ran since the session started.
           await session.#adapter.startProfiler();
-          // The control-port lines start all pressed; release them before the C64 reads them.
+          // In VICE 3.10 and older the control-port lines start all pressed; release them before the C64 reads them.
           for (const joystick of session.#joysticks.values()) await session.#adapter.setJoystick(joystick);
         }),
       );
@@ -368,7 +375,7 @@ export class ViceSession implements ViceSessionHandle {
       case "keyboard": {
         const bytes = Buffer.from((params as ViceOperations["keyboard"]["params"]).data, "hex");
         await this.#observe(() => this.#machine.feedKeyboard(bytes));
-        return { queuedBytes: bytes.length };
+        return { queuedBytes: bytes.length, ...(this.#inputFlaw === undefined ? {} : { emulatorFlaw: this.#inputFlaw }) };
       }
       case "breakpoint":
         return this.#breakpoint(params as BreakpointParams);
@@ -450,7 +457,7 @@ export class ViceSession implements ViceSessionHandle {
         const joystick = params as JoystickState;
         await this.#observe(() => this.#machine.setJoystick(joystick));
         this.#joysticks.set(joystick.port, joystick);
-        return joystick;
+        return { ...joystick, ...(this.#inputFlaw === undefined ? {} : { emulatorFlaw: this.#inputFlaw }) };
       }
       case "warp": {
         const { enabled } = params as ViceOperations["warp"]["params"];
@@ -553,7 +560,7 @@ export class ViceSession implements ViceSessionHandle {
    * checkpoint, a user breakpoint or watchpoint, or a JAM ends the run early.
    * The machine is stopped afterwards.
    */
-  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }): Promise<{ end: RunEnd; frames: number; pc: number }> {
+  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
     const start = await this.#machine.rasterPosition();
@@ -582,18 +589,19 @@ export class ViceSession implements ViceSessionHandle {
             }
           } else {
             frames++;
-            if (frames >= limit) return { end: "frames", frames, pc: stop.pc };
+            if (frames >= limit) return { end: "frames", frames, pc: stop.pc, space: "c64" };
             await this.#machine.setCondition(clock, arming);
           }
           armingPhase = !armingPhase;
           continue;
         }
         if (end === "unknown") {
-          if (await this.#jammedAt(stop.pc)) return { end: "jam", frames, pc: stop.pc };
+          if (await this.#jammedAt(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.
-        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc };
+        // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
+        const driveStop = this.#driveStop;
+        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc, space: driveStop ? "drive8" : "c64" };
       }
     } finally {
       await this.#machine.deleteCheckpoint(clock);
@@ -685,9 +693,9 @@ export class ViceSession implements ViceSessionHandle {
       if (expression !== undefined) await this.#machine.setCondition(checkpoint, expression);
       const outcome = await this.#runFrames(params.timeoutFrames, { checkpoint, deferred });
       const stopReason = outcome.end === "frames" ? "timeout" : outcome.end;
-      // A stop event carries the computer's PC; a drive target reports the drive's.
-      const pc = target.kind !== "raster" && target.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
-      return { reached: stopReason === "target", stopReason, state: "stopped", pc };
+      // A stop event carries the computer's PC; a stop in the drive reports the drive's (F-31).
+      const pc = outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
+      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space };
     } finally {
       await this.#machine.deleteCheckpoint(checkpoint);
     }
@@ -952,7 +960,10 @@ export class ViceSession implements ViceSessionHandle {
       reply.push(bytes);
       return { exported: true, bytes: bytes.length };
     }
-    const file = this.#stage(onlyAttachment(attachments), "vsf");
+    const bytes = onlyAttachment(attachments);
+    // Checked before the machine stops: VICE gives no reason for a file that is no snapshot (F-07).
+    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");
     try {
       return await this.#restoreFrom(file);
     } catch (error) {
@@ -1340,6 +1351,8 @@ export function viceSessionFactory(options: {
   supervisor: ProcessSupervisor;
   env?: NodeJS.ProcessEnv;
   log?: (line: string) => void;
+  /** The known flaws of the VICE version that the host checked at start. */
+  flaws?: readonly string[];
 }): ViceSessionFactory {
   const log = options.log ?? (() => {});
   return async ({ videoStandard }) => {
@@ -1355,6 +1368,6 @@ export function viceSessionFactory(options: {
         ...(options.env === undefined ? {} : { env: options.env }),
       });
     const vice = await launch("headless", () => {});
-    return ViceSession.start(vice, videoStandard, log, { launch, ownPath: (path) => options.supervisor.ownPath(path) });
+    return ViceSession.start(vice, videoStandard, log, { launch, ownPath: (path) => options.supervisor.ownPath(path), ...(options.flaws === undefined ? {} : { flaws: options.flaws }) });
   };
 }

package/src/host-client/connect.ts

@@ -5,6 +5,7 @@ import { connect as connectTcp, type Socket } from "node:net";
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { elapsedMs, trace } from "../trace.ts";
 import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, withStopAndAsk, type ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+import { PACKAGE } from "../package.ts";
 
 export interface Endpoint {
   host: string;
@@ -41,7 +42,7 @@ function unreachable(role: Role): WireFailure {
   return new WireFailure(
     code,
     withStopAndAsk(
-      "The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host) and try again.",
+      `The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host) and try again.`,
     ),
   );
 }

package/src/host-client/coverage.ts

@@ -52,8 +52,3 @@ export function writtenBlocks(map: Uint8Array, minimum: number): CodeRange[] {
   return blocks;
 }
 
-/** True when the CPU executed an instruction in RAM somewhere in the range. */
-export function executedIn(map: Uint8Array, range: CodeRange): boolean {
-  for (let address = range.start; address <= range.end; address++) if ((map[address]! & COVERAGE.ramExecute) !== 0) return true;
-  return false;
-}

package/src/host-client/vice-session.ts

@@ -7,9 +7,20 @@ import { HostConnection } from "./connect.ts";
 import { readProjectFile } from "./transfer.ts";
 
 const HOST_LOST =
-  "The connection to the c64-re-tools host runtime was lost, and the emulator and its machine state went with it. " +
-  "Check that the Host Runtime (c64-re-tools-host) is running, then restart the c64-re-tools MCP server.";
+  "The connection to the c64-re-tools host runtime was lost. The emulator and its machine state are gone: memory, registers, breakpoints, snapshots and the loaded program. " +
+  "The next call starts a new machine when the Host Runtime (c64-re-tools-host) runs. Load the program again and set the breakpoints again.";
 const SESSION_CLOSED = "The C64 session is closed because the c64-re-tools MCP server stops.";
+const LOST_BEFORE_ANSWER = "The connection to the c64-re-tools host runtime was lost before the emulator answered. No machine state was lost. Do the call again.";
+
+/**
+ * The loss of a session that never answered (D57): it had no machine state,
+ * so the caller can do the call again on a new session.
+ */
+export class LostBeforeAnswer extends WireFailure {
+  constructor() {
+    super("machine-unavailable", LOST_BEFORE_ANSWER);
+  }
+}
 
 interface Pending {
   op: ViceOperation;
@@ -24,6 +35,8 @@ export class ViceSessionClient {
   readonly #pending = new Map<number, Pending>();
   #nextId = 1;
   #lost: WireFailure | undefined;
+  #answered = false;
+  #lossReported = false;
 
   private constructor(connection: HostConnection) {
     this.#connection = connection;
@@ -33,6 +46,7 @@ export class ViceSessionClient {
       const pending = this.#pending.get(message.id);
       if (pending === undefined) return; // not ours; ignore
       this.#pending.delete(message.id);
+      this.#answered = true;
       if ("error" in message) {
         pending.reject(new WireFailure(message.error.code, message.error.message));
         return;
@@ -50,7 +64,8 @@ export class ViceSessionClient {
       }
     });
     this.closed = connection.closed.then(() => {
-      this.#lost ??= new WireFailure("machine-state-lost", HOST_LOST);
+      this.#lost ??= this.#answered ? new WireFailure("machine-state-lost", HOST_LOST) : new LostBeforeAnswer();
+      this.#lossReported = this.#pending.size > 0;
       for (const pending of this.#pending.values()) pending.reject(this.#lost);
       this.#pending.clear();
     });
@@ -246,6 +261,21 @@ export class ViceSessionClient {
     return this.#request("window", { action });
   }
 
+  /** True when the connection to the host is gone, whatever the reason. */
+  get lost(): boolean {
+    return this.#lost !== undefined;
+  }
+
+  /** True when the emulator answered a request: then the session had machine state to lose (D57). */
+  get answered(): boolean {
+    return this.#answered;
+  }
+
+  /** The loss of a lost session, when no request got it; undefined while the session lives (D57). */
+  get unreportedLoss(): WireFailure | undefined {
+    return this.#lost?.code === "machine-state-lost" && !this.#lossReported ? this.#lost : undefined;
+  }
+
   /** Ends the session; the host stops its emulator. Open and later requests fail as closed. */
   async close(): Promise<void> {
     this.#lost ??= new WireFailure("machine-unavailable", SESSION_CLOSED);
@@ -267,7 +297,10 @@ export class ViceSessionClient {
     params: ViceOperations[O]["params"],
     attachments: readonly Uint8Array[] = [],
   ): Promise<{ result: ViceOperations[O]["result"]; attachments: Buffer[] }> {
-    if (this.#lost !== undefined) return Promise.reject(this.#lost);
+    if (this.#lost !== undefined) {
+      this.#lossReported = true;
+      return Promise.reject(this.#lost);
+    }
     const id = this.#nextId;
     this.#nextId = this.#nextId >= 0xffff_ffff ? 1 : this.#nextId + 1;
     return new Promise((resolve, reject) => {

package/src/knowledge/history.ts

@@ -103,6 +103,14 @@ export function historyNamed(db: DatabaseSync | undefined, name: string, space:
     .sort(bySequence);
 }
 
+/** Why a revision was written and what it rests on: its description and its evidence, when it has them. */
+export function revisionNote(db: DatabaseSync | undefined, id: number): { reason?: string; evidence?: Evidence[] } {
+  const raw = db?.prepare("SELECT * FROM revisions WHERE id = ?").get(id) as Raw | undefined;
+  if (db === undefined || raw === undefined) return {};
+  const { description, evidence } = withEvidence(db, toRevision(raw));
+  return { ...(description === undefined ? {} : { reason: description }), ...(evidence === undefined ? {} : { evidence }) };
+}
+
 /** The revision with its evidence, when it has any. */
 function withEvidence(db: DatabaseSync, revision: Revision): Revision {
   const rows = db.prepare("SELECT kind, ref, sha256 FROM evidence WHERE revision = ? ORDER BY id").all(revision.id) as Raw[];