@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

package/src/native/c64run.ts

@@ -12,7 +12,7 @@ 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 = 1;
+export const C64RUN_PROTOCOL = 2;
 
 /** CPU cycles in one PAL frame: 312 lines of 63 cycles. */
 export const PAL_FRAME_CYCLES = 19_656;

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,7 +6,7 @@
 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, C64RUN, DXA, findTool, INSTALL_STEPS } from "./discover.ts";
 import { findGhidra, ghidraVersion, NO_USABLE_JDK, noJdk } from "./ghidra/index.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 };
 }
 

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 };

package/src/protocol/vice.ts

@@ -549,8 +549,8 @@ export interface ViceOperations {
   };
   screenBaselines: { params: Record<string, never>; result: { baselines: string[] } };
   snapshot: {
-    params: { action: "save" | "restore" | "discard"; name: string } | { action: "list" };
-    result: { saved: boolean; name: string } | { restored: boolean; state: RunState } | { snapshots: string[] } | { discarded: boolean };
+    params: { action: "save" | "restore" | "remove"; name: string } | { action: "list" };
+    result: { saved: boolean; name: string } | { restored: boolean; state: RunState } | { snapshots: string[] } | { removed: boolean };
   };
   /**
    * Snapshot files: export sends the bytes of a named snapshot back as
@@ -560,7 +560,7 @@ export interface ViceOperations {
     params: { action: "export"; name: string } | { action: "restore" };
     result: { exported: boolean; bytes: number } | { restored: boolean; state: RunState };
   };
-  screenDiscard: { params: { baseline: string }; result: { discarded: boolean } };
+  screenDiscard: { params: { baseline: string }; result: { removed: boolean } };
   warp: { params: { enabled: boolean }; result: { enabled: boolean } };
   window: { params: { action: (typeof WINDOW_ACTIONS)[number] }; result: WindowResult };
 }
@@ -633,8 +633,8 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
     case "snapshot": {
       onlyFields(params, params.action === "list" ? ["action"] : ["action", "name"]);
       if (params.action === "list") return { action: "list" } as ViceOperations[O]["params"];
-      if (params.action !== "save" && params.action !== "restore" && params.action !== "discard") {
-        invalid("action must be save, restore, list or discard");
+      if (params.action !== "save" && params.action !== "restore" && params.action !== "remove") {
+        invalid("action must be save, restore, list or remove");
       }
       return { action: params.action, name: validName(params.name, "name") } as ViceOperations[O]["params"];
     }
@@ -1231,7 +1231,7 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "screenDiscard": {
-      if (value.discarded !== true) throw new ProtocolError("screenDiscard result is malformed");
+      if (value.removed !== true) throw new ProtocolError("screenDiscard result is malformed");
       break;
     }
     case "snapshot": {
@@ -1239,7 +1239,7 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         (value.saved === true && typeof value.name === "string") ||
         (value.restored === true && isOneOf(RUN_STATES, value.state)) ||
         (Array.isArray(value.snapshots) && value.snapshots.every((name) => typeof name === "string")) ||
-        value.discarded === true;
+        value.removed === true;
       if (!ok) throw new ProtocolError("snapshot result is malformed");
       break;
     }