@henols/c64-re-tools 2.0.1 → 2.1.0-rc.2

package/src/native/c64run.ts

@@ -0,0 +1,162 @@
+// The c64run session: one replay core (a C64 emulator, see
+// devcontainer/src/c64-re-tools/c64run.c) for the life of a skill script,
+// driven by one command line and one answer line at a time over its stdin and
+// stdout. It is started through the supervisor like every native tool, so it
+// stops with the script.
+
+import { createInterface } from "node:readline";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { C64RUN, findTool, INSTALL_STEPS } from "./discover.ts";
+import type { SupervisedProcess } from "./processes.ts";
+import type { ToolContext } from "./run.ts";
+
+/** The command protocol that this module speaks; c64run --version and version name it. */
+export const C64RUN_PROTOCOL = 2;
+
+/** CPU cycles in one PAL frame: 312 lines of 63 cycles. */
+export const PAL_FRAME_CYCLES = 19_656;
+
+const STOP_MS = 5_000;
+
+/** The machine state that most commands answer with. */
+export interface CoreStatus {
+  /** CPU cycles since the opcode fetch at the reset vector. */
+  tick: number;
+  /** At an opcode fetch: pc is the address of the next instruction. */
+  sync: boolean;
+  pc: number;
+  a: number;
+  x: number;
+  y: number;
+  s: number;
+  p: number;
+  line: number;
+  cycle: number;
+  /** FNV-1a of RAM from $0002 and of colour RAM. */
+  hash: string;
+  /** The word after "ok", if any: "reached" or "not-reached" for run-pc and run-reads. */
+  word?: string;
+}
+
+export function parseStatus(answer: string): CoreStatus {
+  const parts = answer.split(" ").slice(1);
+  const fields = new Map<string, string>();
+  let word: string | undefined;
+  for (const part of parts) {
+    const at = part.indexOf("=");
+    if (at < 0) word ??= part;
+    else fields.set(part.slice(0, at), part.slice(at + 1));
+  }
+  const hex = (key: string) => Number.parseInt(fields.get(key) ?? "", 16);
+  if (!fields.has("tick")) throw new WireFailure("operation-failed", `c64run gave no machine state: ${answer}`);
+  return {
+    tick: Number(fields.get("tick")),
+    sync: fields.get("sync") === "1",
+    pc: hex("pc"),
+    a: hex("a"),
+    x: hex("x"),
+    y: hex("y"),
+    s: hex("s"),
+    p: hex("p"),
+    line: Number(fields.get("line")),
+    cycle: Number(fields.get("cycle")),
+    hash: fields.get("hash") ?? "",
+    ...(word === undefined ? {} : { word }),
+  };
+}
+
+export class C64RunSession {
+  readonly #process: SupervisedProcess;
+  readonly #waiting: Array<{ resolve: (line: string) => void; reject: (error: Error) => void }> = [];
+  #stderr = "";
+  #ended: WireFailure | undefined;
+
+  private constructor(process: SupervisedProcess) {
+    this.#process = process;
+    const child = process.child;
+    // A core that ended (or never started) closes its stdin: the exit handler reports it.
+    child.stdin!.on("error", () => {});
+    child.stderr!.setEncoding("utf8");
+    child.stderr!.on("data", (chunk: string) => (this.#stderr = (this.#stderr + chunk).slice(-4000)));
+    createInterface({ input: child.stdout! }).on("line", (line) => this.#waiting.shift()?.resolve(line));
+    void process.exited.then((status) => {
+      const how = status.spawnError !== undefined ? `did not start (${status.spawnError})` : `ended (exit ${status.code ?? status.signal})`;
+      this.#ended = new WireFailure(status.spawnError !== undefined ? "installation-incomplete" : "operation-failed", `c64run ${how}.${this.#stderr === "" ? "" : ` ${this.#stderr.trim()}`}`);
+      for (const waiting of this.#waiting.splice(0)) waiting.reject(this.#ended);
+    });
+  }
+
+  /** Starts c64run (C64RT_C64RUN, else c64run on PATH) and checks its protocol. Refuses by name when it is missing. */
+  static async open(context: ToolContext): Promise<C64RunSession> {
+    const env = context.env ?? process.env;
+    const path = findTool(C64RUN, env);
+    const session = new C64RunSession(context.supervisor.spawn([path], { stdio: ["pipe", "pipe", "pipe"], env }));
+    const onAbort = () => void session.close();
+    context.signal.addEventListener("abort", onAbort, { once: true });
+    const version = await session.command("version");
+    const protocol = Number(/protocol=(\d+)/.exec(version)?.[1]);
+    if (protocol !== C64RUN_PROTOCOL) {
+      await session.close();
+      throw new WireFailure("installation-incomplete", `${path} speaks c64run protocol ${Number.isNaN(protocol) ? "(none)" : protocol}; c64-re-tools needs protocol ${C64RUN_PROTOCOL}. ${C64RUN.remedy}`);
+    }
+    return session;
+  }
+
+  /** Sends one command and gives its "ok ..." answer. An "err ..." answer throws operation-failed. */
+  command(text: string): Promise<string> {
+    if (this.#ended !== undefined) return Promise.reject(this.#ended);
+    const answer = new Promise<string>((resolve, reject) => this.#waiting.push({ resolve, reject }));
+    this.#process.child.stdin!.write(`${text}\n`);
+    return answer.then((line) => {
+      if (line.startsWith("ok")) return line;
+      throw new WireFailure("operation-failed", `c64run ${text.split(" ")[0]}: ${line.replace(/^err /, "")}`);
+    });
+  }
+
+  /** A command that answers with the machine state. */
+  async status(text: string): Promise<CoreStatus> {
+    return parseStatus(await this.command(text));
+  }
+
+  /** Power-on: the CPU stops at the reset vector, tick 0. Missing ROMs refuse with the remedy. */
+  async init(romFolder?: string): Promise<CoreStatus> {
+    try {
+      return await this.status(romFolder === undefined ? "init" : `init ${romFolder}`);
+    } catch (error) {
+      if (error instanceof WireFailure && /no ROM/.test(error.message)) {
+        throw new WireFailure(
+          "installation-incomplete",
+          `${error.message}. c64run needs the C64 ROMs kernal-901227-03.bin, basic-901226-01.bin and chargen-901225-01.bin: set C64RT_C64_ROMS to a folder with them (the C64 folder of VICE has them). ${INSTALL_STEPS}`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  /** Writes bytes into RAM (the RAM view), in parts that fit one command line. */
+  async write(address: number, bytes: Uint8Array): Promise<void> {
+    for (let at = 0; at < bytes.length; at += 4096) {
+      await this.command(`write ${((address + at) & 0xffff).toString(16)} ${Buffer.from(bytes.subarray(at, at + 4096)).toString("hex")}`);
+    }
+  }
+
+  /** RAM bytes (the RAM view). */
+  async peek(address: number, size: number): Promise<Uint8Array> {
+    const parts: Buffer[] = [];
+    for (let at = 0; at < size; at += 4096) {
+      const answer = await this.command(`peek ${((address + at) & 0xffff).toString(16)} ${Math.min(4096, size - at)}`);
+      parts.push(Buffer.from(answer.slice(3), "hex"));
+    }
+    return Buffer.concat(parts);
+  }
+
+  /** Ends c64run: quit, then the stop of its process group (at once when it ended, else after STOP_MS). */
+  async close(): Promise<void> {
+    if (this.#ended === undefined) {
+      this.#process.child.stdin!.end("quit\n");
+      await Promise.race([this.#process.exited, new Promise((resolve) => setTimeout(resolve, STOP_MS).unref())]);
+    }
+    await this.#process.stop();
+  }
+}

package/src/native/discover.ts

@@ -55,6 +55,14 @@ export const DXA: ToolSpec = {
   remedy: `Install dxa 0.1.5 on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path. ${INSTALL_STEPS}`,
 };
 
+export const C64RUN: ToolSpec = {
+  name: "c64run",
+  envVar: "C64RT_C64RUN",
+  binaries: ["c64run"],
+  where: "on this machine",
+  remedy: `Install c64run (the replay core of c64-testing, with its C64 ROMs) on the machine that runs the skill scripts so that c64run is on PATH, or set C64RT_C64RUN to its full path. The dev container has it. ${INSTALL_STEPS}`,
+};
+
 export const VICE: ToolSpec = {
   name: "VICE (x64sc)",
   envVar: "C64RT_VICE",

package/src/native/dxa.ts

@@ -7,6 +7,7 @@
 
 import { writeFileSync } from "node:fs";
 
+import { Refusal } from "../errors.ts";
 import { SYMBOL_NAME } from "../c64.ts";
 import { describeError, WireFailure } from "../protocol/messages.ts";
 import { checkDxaResult, checkRequestBounds, imageRange, seedsInside, type DxaParams, type DxaResult } from "./types.ts";
@@ -61,7 +62,7 @@ export function parseListing(listing: string, start: number, end: number): Pick<
     const label = /^([0-9a-f]{4})\s+(\.?[A-Za-z_]\w*):\s*$/.exec(line);
     if (label !== null) {
       const address = Number.parseInt(label[1]!, 16);
-      if (address < start || address > end || !SYMBOL_NAME.test(label[2]!)) throw new Error(`label ${label[2]} at $${label[1]} is not usable`);
+      if (address < start || address > end || !SYMBOL_NAME.test(label[2]!)) throw new Refusal("operation-failed", `label ${label[2]} at $${label[1]} is not usable`);
       labels.push({ address, name: label[2]! });
       continue;
     }
@@ -72,17 +73,17 @@ export function parseListing(listing: string, start: number, end: number): Pick<
   }
   const first = statements[0];
   const last = statements.at(-1);
-  if (first === undefined || last === undefined) throw new Error("the listing has no statements");
-  if (first.address !== start) throw new Error(`the listing starts at $${hex(first.address)}, not at $${hex(start)}`);
-  if (last.address > end) throw new Error("the listing runs past the end of the program");
+  if (first === undefined || last === undefined) throw new Refusal("operation-failed", "the listing has no statements");
+  if (first.address !== start) throw new Refusal("operation-failed", `the listing starts at $${hex(first.address)}, not at $${hex(start)}`);
+  if (last.address > end) throw new Refusal("operation-failed", "the listing runs past the end of the program");
   const regions: DxaResult["regions"] = [];
   statements.forEach((statement, index) => {
     const next = statements[index + 1]?.address ?? end + 1;
     const size = next - statement.address;
-    if (size <= 0) throw new Error(`the listing goes back at $${hex(next)}`);
+    if (size <= 0) throw new Refusal("operation-failed", `the listing goes back at $${hex(next)}`);
     // Data lines count their items; an instruction line dumps exactly its bytes.
     const expected = statement.data ?? statement.dumped;
-    if (expected !== size) throw new Error(`the line at $${hex(statement.address)} holds ${expected} bytes, but the next line is ${size} bytes later`);
+    if (expected !== size) throw new Refusal("operation-failed", `the line at $${hex(statement.address)} holds ${expected} bytes, but the next line is ${size} bytes later`);
     const classification = statement.data === undefined ? "code" : "data";
     const last = regions.at(-1);
     if (last?.classification === classification) last.end = next - 1;

package/src/native/ghidra/analyze.ts

@@ -4,6 +4,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 
+import { Refusal } from "../../errors.ts";
 import { describeError, isObject, WireFailure } from "../../protocol/messages.ts";
 import { checkGhidraResult, checkRequestBounds, GHIDRA_LIMITS, imageRange, seedsInside, type GhidraParams, type GhidraResult } from "../types.ts";
 import { outputTail, type ToolContext } from "../run.ts";
@@ -74,7 +75,7 @@ export async function analyze(
       // The version comes from the installation's application.properties, which findGhidra read.
       result = checkGhidraResult(isObject(exported) ? { ...exported, toolVersion: ghidraVersion(ghidra) } : exported);
       const [range] = result.coverage;
-      if (result.coverage.length !== 1 || range === undefined || range.start !== start || range.end !== end) throw new Error("the coverage is not the loaded program");
+      if (result.coverage.length !== 1 || range === undefined || range.start !== start || range.end !== end) throw new Refusal("operation-failed", "the coverage is not the loaded program");
     } catch (error) {
       context.log?.(`Ghidra result rejected: ${describeError(error)}`);
       throw new WireFailure("operation-failed", `Ghidra returned an incomplete or inconsistent result. Nothing was imported. The check found: ${describeError(error)}.`);

package/src/native/ghidra/index.ts

@@ -9,6 +9,7 @@ import { userInfo } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { Refusal } from "../../errors.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { findOnPath, INSTALL_STEPS, isExecutableFile } from "../discover.ts";
 import type { ProcessSupervisor } from "../processes.ts";
@@ -42,7 +43,7 @@ function installationAt(root: string, source: string): GhidraInstallation {
   const analyzeHeadless = join(root, "support", `analyzeHeadless${LAUNCHER_SUFFIX}`);
   let properties: string;
   try {
-    if (!isExecutableFile(analyzeHeadless)) throw new Error("no analyzeHeadless");
+    if (!isExecutableFile(analyzeHeadless)) throw new Refusal("operation-failed", "no analyzeHeadless");
     properties = readFileSync(join(root, "Ghidra", "application.properties"), "utf8");
   } catch {
     throw new WireFailure("installation-incomplete", `${source} does not point to a Ghidra installation. ${REMEDY}`);

package/src/native/processes.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 
+import { Refusal } from "../errors.ts";
 import { WireFailure } from "../protocol/messages.ts";
 
 /** How long a process group gets between SIGTERM and SIGKILL. */
@@ -189,7 +190,7 @@ export class ProcessSupervisor {
   /** Starts argv[0] with argv[1..] as the leader of a new process group. */
   spawn(argv: readonly string[], options: SpawnOptions = {}): SupervisedProcess {
     const program = argv[0];
-    if (program === undefined) throw new TypeError("argv must name a command");
+    if (program === undefined) throw new Refusal("operation-failed", "argv must name a command");
     const batch = process.platform === "win32" ? batchInvocation(argv, process.env.ComSpec) : undefined;
     const { command, args } = batch ?? { command: program, args: argv.slice(1) };
     let child: ChildProcess;
@@ -333,14 +334,14 @@ export class ProcessSupervisor {
         // The leader has ended already.
       }
       await Promise.race([exited, sleep(this.#graceMs)]);
-      if (!hasExited(child)) throw new Error(`process ${pid} did not end${failure === undefined ? "" : `: ${failure}`}`);
+      if (!hasExited(child)) throw new Refusal("operation-failed", `process ${pid} did not end${failure === undefined ? "" : `: ${failure}`}`);
       return;
     }
     // The group outlives its leader when descendants remain, so wait on the group, not the leader.
     if (signalGroup(pid, "SIGTERM") && !(await waitForGroupGone(pid, this.#graceMs))) {
       signalGroup(pid, "SIGKILL");
       if (!(await waitForGroupGone(pid, KILL_WAIT_MS))) {
-        throw new Error(`process group ${pid} survived SIGKILL`);
+        throw new Refusal("operation-failed", `process group ${pid} survived SIGKILL`);
       }
     }
     // A group of zombies counts as gone before Node reaps the leader and reports its exit;

package/src/native/status.ts

@@ -6,9 +6,9 @@
 import { tmpdir } from "node:os";
 import { stripVTControlCharacters } from "node:util";
 
-import { WireFailure } from "../protocol/messages.ts";
+import { isRefusal } from "../errors.ts";
 import { type ToolStatus } from "../protocol/tools.ts";
-import { ACME, DXA, findTool } from "./discover.ts";
+import { ACME, C64RUN, DXA, findTool, INSTALL_STEPS } from "./discover.ts";
 import { findGhidra, ghidraVersion, NO_USABLE_JDK, noJdk } from "./ghidra/index.ts";
 import { runTool, type ToolContext } from "./run.ts";
 import { Workspace } from "./staging.ts";
@@ -55,7 +55,7 @@ async function run(
 }
 
 function missing(name: string, error: unknown): ToolStatus {
-  if (!(error instanceof WireFailure)) throw error;
+  if (!isRefusal(error)) throw error;
   return { name, found: false, runs: false, problem: error.message };
 }
 
@@ -101,6 +101,27 @@ export async function probeGhidra(context: ToolContext): Promise<ToolStatus> {
   }
 }
 
+/** c64run: --version prints its version and whether its ROM folder has the three C64 ROMs. */
+export async function probeC64run(context: ToolContext): Promise<ToolStatus> {
+  const env = context.env ?? process.env;
+  try {
+    const path = findTool(C64RUN, env);
+    return await run(
+      "c64run",
+      path,
+      ["--version"],
+      (output) => (/^roms=ok /m.test(output) ? versionLine(output, /^c64run protocol=/) : undefined),
+      context,
+      (output) => {
+        const missing = /^roms=missing (.*)$/m.exec(output)?.[1];
+        return missing === undefined ? undefined : `It has no C64 ROMs: ${missing}. Set C64RT_C64_ROMS to a folder with kernal-901227-03.bin, basic-901226-01.bin and chargen-901225-01.bin (the C64 folder of VICE has them). ${INSTALL_STEPS}`;
+      },
+    );
+  } catch (error) {
+    return missing("c64run", error);
+  }
+}
+
 /** The tools that skill scripts run themselves, on this machine. */
 export async function localToolStatus(context: ToolContext): Promise<ToolStatus[]> {
   const probes: Probe[] = [
@@ -109,5 +130,5 @@ export async function localToolStatus(context: ToolContext): Promise<ToolStatus[
     // directory only where that uses "/": on Windows the line starts with the full path.
     { name: "dxa", find: (env) => findTool(DXA, env), args: ["-V"], pattern: DXA_VERSION },
   ];
-  return [...(await probeTools(probes, context)), await probeGhidra(context)];
+  return [...(await probeTools(probes, context)), await probeGhidra(context), await probeC64run(context)];
 }

package/src/native/types.ts

@@ -3,6 +3,7 @@
 // these tools itself: nothing here crosses the Host Runtime wire. Bytes
 // (a program, an image, a listing) go next to these values as attachments.
 
+import { Refusal } from "../errors.ts";
 import { prgRange, REFERENCE_KINDS, SYMBOL_NAME, type ReferenceKind } from "../c64.ts";
 import { isInteger, isObject, isOneOf, WireFailure } from "../protocol/messages.ts";
 import { type SourceTree } from "../protocol/tools.ts";
@@ -118,7 +119,7 @@ const isToolVersion = (value: unknown) => value === undefined || (typeof value =
 
 /** Ends a result check with the Error that names its first problem. */
 function fail(message: string): never {
-  throw new Error(message);
+  throw new Refusal("operation-failed", message);
 }
 
 /** Narrows to a list whose items are still unchecked. */
@@ -237,12 +238,7 @@ export function imageRange(kind: ImageKind, image: Uint8Array): { start: number;
     if (image.length !== 0x10000) throw new WireFailure("invalid-input", "A flat 64 KiB image has exactly 65536 bytes.");
     return { start: 0, end: 0xffff, body: image };
   }
-  try {
-    return prgRange(image);
-  } catch (error) {
-    if (!(error instanceof RangeError)) throw error;
-    throw new WireFailure("invalid-input", error.message);
-  }
+  return prgRange(image);
 }
 
 /**

package/src/opcodes.ts

@@ -4,6 +4,8 @@
 // spelling, ACME writes only one of them: the generator finds those with a
 // probe and writes the others as bytes.
 
+import { formatC64Byte, formatC64Address } from "./c64.ts";
+
 export type Mode = "imp" | "imm" | "zp" | "zpx" | "zpy" | "abs" | "abx" | "aby" | "ind" | "izx" | "izy" | "rel";
 
 export interface Opcode {
@@ -75,8 +77,6 @@ export function useKind(opcode: number): UseKind {
   return "read";
 }
 
-const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
-const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 
 /** The text of the instruction in `bytes` at `pc`, for example "sta $d011" or "bne $c002". */
 export function instructionText(bytes: readonly number[], pc: number): string {
@@ -85,17 +85,17 @@ export function instructionText(bytes: readonly number[], pc: number): string {
   const word = low | ((bytes[2] ?? 0) << 8);
   const operand: Record<Mode, string> = {
     imp: "",
-    imm: `#${hex2(low)}`,
-    zp: hex2(low),
-    zpx: `${hex2(low)},x`,
-    zpy: `${hex2(low)},y`,
-    abs: hex4(word),
-    abx: `${hex4(word)},x`,
-    aby: `${hex4(word)},y`,
-    ind: `(${hex4(word)})`,
-    izx: `(${hex2(low)},x)`,
-    izy: `(${hex2(low)}),y`,
-    rel: hex4((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
+    imm: `#${formatC64Byte(low)}`,
+    zp: formatC64Byte(low),
+    zpx: `${formatC64Byte(low)},x`,
+    zpy: `${formatC64Byte(low)},y`,
+    abs: formatC64Address(word),
+    abx: `${formatC64Address(word)},x`,
+    aby: `${formatC64Address(word)},y`,
+    ind: `(${formatC64Address(word)})`,
+    izx: `(${formatC64Byte(low)},x)`,
+    izy: `(${formatC64Byte(low)}),y`,
+    rel: formatC64Address((pc + 2 + (low < 0x80 ? low : low - 0x100)) & 0xffff),
   };
   return operand[mode] === "" ? mnemonic : `${mnemonic} ${operand[mode]}`;
 }

package/src/platform.ts

@@ -3,7 +3,8 @@
 // Names follow "Mapping the Commodore 64". Only platform facts live here:
 // an address without one belongs to the application.
 
-import { d018Offsets, vicBankBase } from "./c64.ts";
+import { d018Offsets, formatC64Address, vicBankBase } from "./c64.ts";
+import { Refusal } from "./errors.ts";
 
 export interface Entry {
   start: number;
@@ -321,7 +322,6 @@ const AREAS: Array<{ start: number; end: number; area: string; kind: Lookup["kin
   { start: 0xe000, end: 0xffff, area: "KERNAL ROM or RAM", kind: "platform", meaning: "KERNAL ROM when $01 bit 1 is set, else RAM." },
 ];
 
-const hex = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
 
 export interface Area {
   name: string;
@@ -353,7 +353,7 @@ export function lookup(address: number): Lookup {
     const base = block.start + ((address - block.start) % block.period);
     const register = block.registers.find((entry) => entry.start === base);
     const mirror = base !== address ? { mirrorOf: base } : {};
-    if (register === undefined) return { address, kind: "platform", area: block.area, meaning: `Unused register (${hex(base)}): reads give no useful value.`, ...mirror };
+    if (register === undefined) return { address, kind: "platform", area: block.area, meaning: `Unused register (${formatC64Address(base)}): reads give no useful value.`, ...mirror };
     return { address, kind: "platform", area: block.area, name: register.name, meaning: register.meaning, ...mirror };
   }
   const entry = [...SYSTEM, ...ROM].find((candidate) => address >= candidate.start && address <= candidate.end);
@@ -455,13 +455,13 @@ export function decode(register: number, value: number, dd00?: number): Decoded
       return { xScroll: value & 0x07, columns: value & 0x08 ? 40 : 38, multicolorMode: (value & 0x10) !== 0 };
     case 0xd018: {
       const { screen, characters, bitmap } = d018Offsets(value);
-      const result: Decoded = { screenOffset: hex(screen), characterOffset: hex(characters), bitmapOffset: hex(bitmap) };
+      const result: Decoded = { screenOffset: formatC64Address(screen), characterOffset: formatC64Address(characters), bitmapOffset: formatC64Address(bitmap) };
       if (dd00 !== undefined) {
         const bank = vicBank(dd00);
         result.bank = bank.bank;
-        result.screen = hex(bank.start + screen);
-        result.characters = hex(bank.start + characters);
-        result.bitmap = hex(bank.start + bitmap);
+        result.screen = formatC64Address(bank.start + screen);
+        result.characters = formatC64Address(bank.start + characters);
+        result.bitmap = formatC64Address(bank.start + bitmap);
         if (bank.bank === 0 || bank.bank === 2) result.note = "In banks 0 and 2 the VIC-II sees the character ROM at offsets $1000-$1FFF.";
       } else {
         result.note = "Offsets are inside the VIC-II bank; give --bank with the $DD00 value for addresses.";
@@ -470,7 +470,7 @@ export function decode(register: number, value: number, dd00?: number): Decoded
     }
     case 0xdd00: {
       const bank = vicBank(value);
-      return { vicBank: bank.bank, vicAddresses: `${hex(bank.start)}-${hex(bank.end)}` };
+      return { vicBank: bank.bank, vicAddresses: `${formatC64Address(bank.start)}-${formatC64Address(bank.end)}` };
     }
     case 0xd015:
     case 0xd017:
@@ -499,6 +499,6 @@ export function decode(register: number, value: number, dd00?: number): Decoded
       };
     }
     default:
-      throw new RangeError(`no decoder for ${hex(register)}; decoders exist for $0001, $d010, $d011, $d015-$d01f (sprite and interrupt bits), $d016, $d018, $dc0d, $dd00 and $dd0d`);
+      throw new Refusal("invalid-input", `There is no decoder for ${formatC64Address(register)}. Decoders exist for $0001, $d010, $d011, $d015-$d01f (sprite and interrupt bits), $d016, $d018, $dc0d, $dd00 and $dd0d`);
   }
 }

package/src/project.ts

@@ -4,6 +4,7 @@
 // project path is relative to that folder. .c64-re-tools/local/ holds what
 // the agent saves for itself and ignores itself in git.
 
+import { Refusal } from "./errors.ts";
 import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -23,17 +24,6 @@ const SEARCH_DEPTH = 3;
 /** At most this many projects are named in a refusal. */
 const LISTED_PROJECTS = 20;
 
-/** A refusal of the project rules, with a stable code, shown to the LLM unchanged. */
-export class ProjectError extends Error {
-  override name = "ProjectError";
-  readonly code: "invalid-input" | "not-found";
-
-  constructor(code: "invalid-input" | "not-found", message: string) {
-    super(message);
-    this.code = code;
-  }
-}
-
 /** How a refusal tells the caller to name a project: "--project <folder>" for a script, "project" for an MCP tool. */
 export interface ProjectRemedy {
   remedy?: string;
@@ -95,7 +85,7 @@ function listed(projects: readonly string[]): string {
  * The project of the working directory `cwd` by the project rules: the nearest
  * folder at or above it with .c64-re-tools/, below the home folder. Without
  * one, `cwd` itself, unless projects are below it or it is the home folder:
- * then a ProjectError names them and the remedy, so no write lands outside a
+ * then a Refusal names them and the remedy, so no write lands outside a
  * project.
  */
 export function findProject(cwd: string = process.cwd(), options: ProjectRemedy = {}): string {
@@ -105,11 +95,11 @@ export function findProject(cwd: string = process.cwd(), options: ProjectRemedy
     if (isProject(folder)) return folder;
   }
   if (start === homedir()) {
-    throw new ProjectError("invalid-input", `The home folder is not a project folder. Start in a project folder, or ${remedy.charAt(0).toLowerCase()}${remedy.slice(1)}.`);
+    throw new Refusal("invalid-input", `The home folder is not a project folder. Start in a project folder, or ${remedy.charAt(0).toLowerCase()}${remedy.slice(1)}.`);
   }
   const below = projectsBelow(start);
   if (below.length > 0) {
-    throw new ProjectError("invalid-input", `${start} is not a project folder. These folders below it are projects: ${listed(below)}. ${remedy} with one of them.`);
+    throw new Refusal("invalid-input", `${start} is not a project folder. These folders below it are projects: ${listed(below)}. ${remedy} with one of them.`);
   }
   return start;
 }
@@ -121,15 +111,15 @@ export function findProject(cwd: string = process.cwd(), options: ProjectRemedy
  * home folder.
  */
 export function namedProject(folder: string, cwd: string = process.cwd()): string {
-  if (folder.length === 0) throw new ProjectError("invalid-input", "The project folder must not be empty.");
+  if (folder.length === 0) throw new Refusal("invalid-input", "The project folder must not be empty.");
   const path = resolve(cwd, folder);
   const stat = statSync(path, { throwIfNoEntry: false });
-  if (stat === undefined) throw new ProjectError("not-found", `There is no folder ${folder}.`);
-  if (!stat.isDirectory()) throw new ProjectError("invalid-input", `${folder} is not a folder.`);
-  if (path === homedir()) throw new ProjectError("invalid-input", "The home folder is not a project folder.");
+  if (stat === undefined) throw new Refusal("not-found", `There is no folder ${folder}.`);
+  if (!stat.isDirectory()) throw new Refusal("invalid-input", `${folder} is not a folder.`);
+  if (path === homedir()) throw new Refusal("invalid-input", "The home folder is not a project folder.");
   const outer = foldersUpFrom(path).slice(1).find(isProject);
   if (outer !== undefined) {
-    throw new ProjectError("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || "."}. Give that project folder.`);
+    throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || "."}. Give that project folder.`);
   }
   return path;
 }
@@ -159,7 +149,7 @@ export function resolveProject(folder: string | undefined, cwd: string = process
   return root;
 }
 
-/** Sets the project of this process from --project. Throws ProjectError for a folder that the rules refuse. */
+/** Sets the project of this process from --project. Refuses a folder that the rules refuse. */
 export function useProject(folder: string): void {
   chosen = namedProject(folder);
 }
@@ -179,18 +169,18 @@ export function projectRoot(): string {
 
 export function resolveProjectPath(path: string, root = projectRoot()): string {
   if (path.length === 0) {
-    throw new TypeError("Project path must not be empty");
+    throw new Refusal("invalid-input", "A project path must not be empty.");
   }
   if (isAbsolute(path)) {
-    throw new TypeError("Project path must be relative");
+    throw new Refusal("invalid-input", `${path} is not relative: give a path relative to the project folder.`);
   }
 
   const candidate = resolve(root, path);
   if (isInside(root, candidate)) return candidate;
-  throw new TypeError("Project path escapes the project root");
+  throw new Refusal("invalid-input", `${path} leads out of the project folder: give a path that stays inside it.`);
 }
 
-/** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Throws TypeError as resolveProjectPath does. */
+/** A project path in one spelling: relative to the project folder, with / and without ./, .. or a double /. Refuses a path as resolveProjectPath does. */
 export function projectRelative(path: string, root = projectRoot()): string {
   return relative(root, resolveProjectPath(path, root)).split(sep).join("/");
 }
@@ -204,13 +194,13 @@ export function isInside(root: string, candidate: string): boolean {
 /**
  * Resolves a project-relative path to an existing file system entry whose real
  * location is inside the project too, so a symbolic link cannot reach outside
- * it. Throws TypeError for a refused path; lets ENOENT through.
+ * it. Refuses a path that leads out; lets ENOENT through.
  */
 export function resolveProjectFile(path: string, root = projectRoot()): string {
   const candidate = resolveProjectPath(path, root);
   const real = realpathSync(candidate);
   if (!isInside(realpathSync(root), real)) {
-    throw new TypeError("Project path escapes the project root through a symbolic link");
+    throw new Refusal("invalid-input", `${path} leads out of the project folder through a symbolic link.`);
   }
   return real;
 }

package/src/protocol/messages.ts

@@ -1,6 +1,7 @@
 // The message layer of the Host Runtime wire: protocol identity, error codes, the message shapes and
 // their parsers, and the field checks that every validator uses.
 
+import { ERROR_CODES, Refusal, type ErrorCode } from "../errors.ts";
 import type { ToolOperation, ToolOperations } from "./tools.ts";
 import type { ViceOperation, ViceOperations } from "./vice.ts";
 
@@ -18,20 +19,6 @@ export const DEFAULT_HOST_PORT = 6464;
 // ---------------------------------------------------------------------------
 // Shared vocabulary
 
-export const ERROR_CODES = [
-  "invalid-input",
-  "machine-running",
-  "machine-unavailable",
-  "machine-state-lost",
-  "not-found",
-  "media-error",
-  "limit-exceeded",
-  "unsupported-in-space",
-  "installation-incomplete",
-  "operation-failed",
-] as const;
-export type ErrorCode = (typeof ERROR_CODES)[number];
-
 /** An actionable failure carried on the wire and shown to the LLM unchanged. */
 export interface WireError {
   code: ErrorCode;
@@ -122,14 +109,9 @@ export function shownMessage(error: { code: string; message: string }): string {
   return error.code === "installation-incomplete" ? withStopAndAsk(error.message) : error.message;
 }
 
-export class WireFailure extends Error implements WireError {
+/** A refusal that crosses the Host Runtime wire. */
+export class WireFailure extends Refusal implements WireError {
   override name = "WireFailure";
-  readonly code: ErrorCode;
-
-  constructor(code: ErrorCode, message: string) {
-    super(message);
-    this.code = code;
-  }
 
   toWire(): WireError {
     return { code: this.code, message: this.message };