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

package/src/native/ghidra/scripts/C64Export.java

@@ -2,7 +2,8 @@
 //
 // Writes the structural result for the loaded image: functions with the
 // source of their names, code and defined-data regions, memory references
-// from instructions, and the requested decompilations within their bounds.
+// from instructions, every instruction with its bytes, mnemonic, operand
+// text and flow targets (D44), and the requested decompilations within their bounds.
 //@category c64-re-tools
 
 import java.io.FileReader;
@@ -53,6 +54,7 @@ public class C64Export extends GhidraScript {
 		out.add("functions", functions(coverage));
 		out.add("regions", regions(coverage));
 		out.add("references", references(coverage));
+		out.add("instructions", instructions(coverage));
 		JsonArray notDecompiled = new JsonArray();
 		out.add("decompilations", decompile(request, notDecompiled));
 		out.add("notDecompiled", notDecompiled);
@@ -156,6 +158,36 @@ public class C64Export extends GhidraScript {
 		return references;
 	}
 
+	/** Every instruction in the coverage, in address order, as Ghidra decoded it with the 6510 language. */
+	private JsonArray instructions(AddressSet coverage) throws Exception {
+		JsonArray instructions = new JsonArray();
+		for (Instruction instruction : currentProgram.getListing().getInstructions(coverage, true)) {
+			JsonObject item = new JsonObject();
+			item.addProperty("address", instruction.getMinAddress().getOffset());
+			StringBuilder bytes = new StringBuilder();
+			for (byte value : instruction.getBytes()) {
+				bytes.append(String.format("%02x", value & 0xff));
+			}
+			item.addProperty("bytes", bytes.toString());
+			item.addProperty("mnemonic", instruction.getMnemonicString().toLowerCase());
+			StringBuilder operands = new StringBuilder();
+			for (int index = 0; index < instruction.getNumOperands(); index++) {
+				if (index > 0) {
+					operands.append(",");
+				}
+				operands.append(instruction.getDefaultOperandRepresentation(index));
+			}
+			item.addProperty("operands", operands.toString());
+			JsonArray flows = new JsonArray();
+			for (Address flow : instruction.getFlows()) {
+				flows.add(flow.getOffset());
+			}
+			item.add("flows", flows);
+			instructions.add(item);
+		}
+		return instructions;
+	}
+
 	private static void add(JsonArray references, Set<String> seen, long from, long to, String type) {
 		if (!seen.add(from + ":" + to + ":" + type)) {
 			return;

package/src/native/status.ts

@@ -9,7 +9,7 @@ import { stripVTControlCharacters } from "node:util";
 import { WireFailure } from "../protocol/messages.ts";
 import { type ToolStatus } from "../protocol/tools.ts";
 import { ACME, DXA, findTool } from "./discover.ts";
-import { findGhidra, ghidraVersion } from "./ghidra/index.ts";
+import { findGhidra, ghidraVersion, NO_USABLE_JDK, noJdk } from "./ghidra/index.ts";
 import { runTool, type ToolContext } from "./run.ts";
 import { Workspace } from "./staging.ts";
 
@@ -35,10 +35,21 @@ export function versionLine(output: string, pattern: RegExp): string | undefined
     .find((line) => pattern.test(line));
 }
 
-async function run(name: string, path: string, args: string[], version: (output: string) => string | undefined, context: ToolContext): Promise<ToolStatus> {
+async function run(
+  name: string,
+  path: string,
+  args: string[],
+  version: (output: string) => string | undefined,
+  context: ToolContext,
+  /** A known cause in the output, said in place of the exit status. */
+  cause?: (output: string) => string | undefined,
+): Promise<ToolStatus> {
   const result = await runTool({ argv: [path, ...args], cwd: tmpdir(), supervisor: context.supervisor, signal: context.signal, timeoutMs: PROBE_TIMEOUT_MS, env: context.env });
-  const found = version(`${result.stdout}\n${result.stderr}`);
+  const output = `${result.stdout}\n${result.stderr}`;
+  const found = version(output);
   if (found !== undefined) return { name, found: true, path, version: found, runs: true };
+  const known = cause?.(output);
+  if (known !== undefined) return { name, found: true, path, runs: false, problem: known };
   const problem = result.timedOut ? "It did not answer in time." : result.spawnError !== undefined ? `It did not start (${result.spawnError}).` : `It did not run correctly (exit ${result.code ?? result.signal}).`;
   return { name, found: true, path, runs: false, problem };
 }
@@ -79,6 +90,7 @@ export async function probeGhidra(context: ToolContext): Promise<ToolStatus> {
         [],
         (output) => (/Headless Analyzer Usage/.test(output) ? ghidraVersion(ghidra) : undefined),
         { ...context, env: { ...env, XDG_CONFIG_HOME: settings, XDG_CACHE_HOME: settings } },
+        (output) => (NO_USABLE_JDK.test(output) ? noJdk(ghidra).message : undefined),
       );
       return { ...status, path: ghidra.root };
     } finally {

package/src/native/types.ts

@@ -52,6 +52,17 @@ export interface GhidraParams {
   decompile: number[];
 }
 
+export interface GhidraInstruction {
+  address: number;
+  /** Lowercase hex, 1 to 3 bytes. */
+  bytes: string;
+  mnemonic: string;
+  /** Ghidra's text of the operands, empty for an implied operand. */
+  operands: string;
+  /** Where the flow goes besides the next instruction: a branch, jump or call target. */
+  flows: number[];
+}
+
 export interface GhidraResult {
   coverage: Array<{ start: number; end: number }>;
   functions: Array<{ entry: number; name: string; nameSource: "seed" | "generated" | "native" }>;
@@ -60,6 +71,8 @@ export interface GhidraResult {
   decompilations: Array<{ entry: number; text: string; truncated: boolean }>;
   /** Requested routines without decompiled code, with the decompiler's reason. */
   notDecompiled?: Array<{ entry: number; reason: string }>;
+  /** Every instruction in the coverage, as Ghidra decoded it (D44). */
+  instructions: GhidraInstruction[];
   /** Which categories are complete inside the coverage; private to the importer. */
   completeness: { functions: boolean; regions: boolean; references: boolean };
   /** The version of the Ghidra that made the result, for example "Ghidra 12.1.3". */
@@ -115,7 +128,7 @@ const isList = (value: unknown): value is unknown[] => Array.isArray(value);
  */
 export function checkGhidraResult(value: unknown): GhidraResult {
   if (!isObject(value)) fail("not an object");
-  const { coverage, functions, regions, references, decompilations, notDecompiled, completeness, toolVersion } = value;
+  const { coverage, functions, regions, references, decompilations, notDecompiled, completeness, toolVersion, instructions } = value;
   if (!isList(coverage) || coverage.length === 0) fail("no coverage");
   const ranges: Array<{ start: number; end: number }> = [];
   for (const range of coverage) {
@@ -138,6 +151,22 @@ export function checkGhidraResult(value: unknown): GhidraResult {
     if (!ranges.some((range) => range.start <= start && end <= range.end)) fail("a region lies outside the coverage");
     previousEnd = end;
   }
+  if (!isList(instructions)) fail("no instructions");
+  for (const instruction of instructions) {
+    if (
+      !isObject(instruction) ||
+      !isInteger(instruction.address, 0, 0xffff) ||
+      typeof instruction.bytes !== "string" ||
+      !/^(?:[0-9a-f]{2}){1,3}$/.test(instruction.bytes) ||
+      typeof instruction.mnemonic !== "string" ||
+      typeof instruction.operands !== "string" ||
+      !isList(instruction.flows) ||
+      !instruction.flows.every((flow) => isInteger(flow, 0, 0xffff))
+    ) {
+      fail("bad instruction");
+    }
+    if (!covered(instruction.address)) fail("an instruction lies outside the coverage");
+  }
   if (!isList(references)) fail("no references");
   for (const reference of references) {
     if (!isObject(reference) || !isInteger(reference.from, 0, 0xffff) || !isInteger(reference.to, 0, 0xffff) || !isOneOf(REFERENCE_KINDS, reference.type)) fail("bad reference");

package/{skills/c64-memory-map/scripts → src}/platform.ts

@@ -1,8 +1,9 @@
-// C64 platform reference data and decoders for the c64-memory-map script.
+// C64 platform reference data and decoders: the c64-memory-map script, and the
+// platform names that c64-source uses (D52).
 // Names follow "Mapping the Commodore 64". Only platform facts live here:
 // an address without one belongs to the application.
 
-import { d018Offsets, vicBankBase } from "#src/c64.ts";
+import { d018Offsets, vicBankBase } from "./c64.ts";
 
 export interface Entry {
   start: number;
@@ -340,6 +341,21 @@ export function lookup(address: number): Lookup {
   return { address, kind: area.kind, area: area.area, meaning: area.meaning };
 }
 
+/**
+ * The platform name of each named address (D52): system variables, ROM
+ * entries and I/O registers, not mirrors, in address order. Only names that
+ * an assembler can use as a symbol, and each name once, at its lowest address.
+ */
+export function platformNames(): Array<{ address: number; name: string; meaning: string }> {
+  const io = IO.flatMap((block) => block.registers);
+  const seen = new Set<string>();
+  return [...SYSTEM, ...ROM, ...io]
+    .map((entry) => ({ address: entry.start, name: entry.name, meaning: entry.meaning }))
+    .filter((entry) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.name))
+    .sort((a, b) => a.address - b.address)
+    .filter((entry) => !seen.has(entry.name) && seen.add(entry.name) !== undefined);
+}
+
 export type Decoded = Record<string, unknown>;
 
 const bits = (value: number) => [0, 1, 2, 3, 4, 5, 6, 7].filter((bit) => (value & (1 << bit)) !== 0);

package/src/protocol/messages.ts

@@ -7,7 +7,7 @@ import type { ViceOperation, ViceOperations } from "./vice.ts";
 /** Private Host Runtime protocol identifier. */
 export const HOST_PROTOCOL_ID = "c64-re-tools-host" as const;
 /** Bumped on any incompatible change; a mismatch fails the handshake. */
-export const HOST_PROTOCOL_VERSION = 2;
+export const HOST_PROTOCOL_VERSION = 3;
 /** After ready, the client pings this often, on every connection. */
 export const HEARTBEAT_INTERVAL_MS = 10_000;
 /** Either side closes a connection that has sent nothing for this long. */
@@ -54,13 +54,8 @@ export interface Hello {
   role: Role;
   /** vice-session only; fixed for the session. */
   videoStandard?: VideoStandard;
-  /** The shared secret (C64RT_HOST_TOKEN) for a host that listens beyond loopback. */
-  token?: string;
 }
 
-/** Longest accepted shared token. */
-const MAX_TOKEN_LENGTH = 256;
-
 export interface Ready {
   type: "ready";
 }
@@ -111,6 +106,22 @@ export class ProtocolError extends Error {
 }
 
 /** Thrown by parameter/result validators; carries the wire code to answer with. */
+/**
+ * The instruction at the end of a refusal that only the user can fix: a
+ * missing or broken tool, or a Host Runtime that does not run (D37).
+ */
+export const STOP_AND_ASK = "Stop the task. Give this message to the user and wait for the user. Do not make a replacement for the tool or the host runtime.";
+
+/** The message with STOP_AND_ASK at its end, once. */
+export function withStopAndAsk(message: string): string {
+  return message.endsWith(STOP_AND_ASK) ? message : `${message} ${STOP_AND_ASK}`;
+}
+
+/** The message that the agent sees for a refusal: an installation-incomplete one ends with STOP_AND_ASK. */
+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 {
   override name = "WireFailure";
   readonly code: ErrorCode;
@@ -166,12 +177,8 @@ export function parseClientMessage(value: unknown): ReceivedClientMessage {
     if (value.videoStandard !== undefined && !isOneOf(VIDEO_STANDARDS, value.videoStandard)) {
       throw new ProtocolError("hello has an unknown video standard");
     }
-    if (value.token !== undefined && (typeof value.token !== "string" || value.token.length > MAX_TOKEN_LENGTH)) {
-      throw new ProtocolError("hello has a malformed token");
-    }
     const hello: Hello = { type: "hello", protocol: value.protocol, version: value.version, role: value.role };
     if (value.videoStandard !== undefined) hello.videoStandard = value.videoStandard;
-    if (value.token !== undefined) hello.token = value.token;
     return hello;
   }
   if (value.type === "request") {

package/src/protocol/vice.ts

@@ -94,6 +94,8 @@ export const MAX_WATCH_SIZE = 256;
 export interface Breakpoint {
   id: number;
   address: number;
+  /** A range from address: the CPU stops at the first instruction it executes in it (D43). One address when not given. */
+  size?: number;
   space: Space;
   enabled: boolean;
   /** The condition given at add, when there was one. */
@@ -112,15 +114,23 @@ export interface Watchpoint {
 }
 
 export type BreakpointParams =
-  | { action: "add"; address: number; space: Space; condition?: Condition }
-  | { action: "remove" | "enable" | "disable"; id: number }
+  | { action: "add"; address: number; size?: number; space: Space; condition?: Condition }
+  | { action: "remove"; id: number }
+  | { action: "enable" | "disable"; id: number }
   | { action: "list" };
 
 export type WatchpointParams =
   | { action: "add"; address: number; size: number; access: WatchAccess; space: Space; condition?: Condition }
-  | { action: "remove" | "enable" | "disable"; id: number }
+  | { action: "remove"; id: number }
+  | { action: "enable" | "disable"; id: number }
   | { action: "list" };
 
+/** The result of remove: the point is gone, so only its id comes back. */
+export interface PointRemoved {
+  removed: true;
+  id: number;
+}
+
 // Chip state
 
 export const VICII_MODES = ["text", "multicolor-text", "extended-color-text", "bitmap", "multicolor-bitmap", "invalid"] as const;
@@ -223,12 +233,11 @@ export interface ProfileEntry {
   percent: number;
 }
 
+/** Addresses with the same access flags: the coverage byte of src/c64.ts (D40), RAM, ROM and I/O apart. */
 export interface MemmapRange {
   start: number;
   end: number;
-  execute: boolean;
-  read: boolean;
-  write: boolean;
+  flags: number;
 }
 
 // Screen baselines and snapshots
@@ -386,6 +395,8 @@ export interface RunUntilResult {
 export interface ViceOperations {
   status: { params: Record<string, never>; result: MachineStatus };
   memoryRead: { params: MemoryReadParams; result: MemoryReadResult };
+  /** The I/O registers at $d000-$dfff as the chips hold them, whatever the CPU banks in, without side effects (D43). */
+  ioRead: { params: { address: number; size: number }; result: MemoryReadResult };
   registersGet: { params: { space: Space }; result: Registers };
   memoryWrite: { params: MemoryWriteParams; result: { address: number; bytesWritten: number } };
   /** `pattern`: bytes, with null as a wildcard. */
@@ -412,8 +423,8 @@ export interface ViceOperations {
   /** `data`: PETSCII bytes as lowercase hex. */
   keyboard: { params: { data: string }; result: { queuedBytes: number } };
   joystick: { params: JoystickState; result: JoystickState };
-  breakpoint: { params: BreakpointParams; result: Breakpoint | { breakpoints: Breakpoint[] } };
-  watchpoint: { params: WatchpointParams; result: Watchpoint | { watchpoints: Watchpoint[] } };
+  breakpoint: { params: BreakpointParams; result: Breakpoint | PointRemoved | { breakpoints: Breakpoint[] } };
+  watchpoint: { params: WatchpointParams; result: Watchpoint | PointRemoved | { watchpoints: Watchpoint[] } };
   cpuHistory: { params: { limit: number; space: Space }; result: { entries: HistoryEntry[] } };
   backtrace: { params: { depth: number; space: Space }; result: { frames: BacktraceFrame[] } };
   /** `cycles` is a decimal string. */
@@ -421,7 +432,8 @@ export interface ViceOperations {
   profile: { params: { limit: number }; result: { entries: ProfileEntry[] } };
   memmap: {
     params: { action: "read"; start: number; end: number; maxRanges: number } | { action: "clear" };
-    result: { ranges: MemmapRange[] } | { cleared: boolean };
+    /** `next`: more ranges follow from this address; read again from there. */
+    result: { ranges: MemmapRange[]; next?: number } | { cleared: boolean };
   };
   vicii: { params: Record<string, never>; result: ViciiState };
   /** `indexes`: unique sprite numbers 0-7, in the order to report them. */
@@ -440,6 +452,14 @@ export interface ViceOperations {
     params: { action: "save" | "restore" | "discard"; name: string } | { action: "list" };
     result: { saved: boolean; name: string } | { restored: boolean; state: RunState } | { snapshots: string[] } | { discarded: boolean };
   };
+  /**
+   * Snapshot files (D41): export sends the bytes of a named snapshot back as
+   * one attachment; restore takes the bytes of a .vsf as one attachment.
+   */
+  snapshotFile: {
+    params: { action: "export"; name: string } | { action: "restore" };
+    result: { exported: boolean; bytes: number } | { restored: boolean; state: RunState };
+  };
   screenDiscard: { params: { baseline: string }; result: { discarded: boolean } };
   warp: { params: { enabled: boolean }; result: { enabled: boolean } };
   window: { params: { action: (typeof WINDOW_ACTIONS)[number] }; result: WindowResult };
@@ -469,6 +489,8 @@ export const VICE_OPERATIONS = [
   "screenBaselines",
   "screenDiscard",
   "snapshot",
+  "snapshotFile",
+  "ioRead",
   "cpuHistory",
   "backtrace",
   "timing",
@@ -483,8 +505,9 @@ export const VICE_OPERATIONS = [
   "window",
 ] as const satisfies readonly ViceOperation[];
 
-/** How many attachments each operation takes. */
-export function attachmentCount(op: ViceOperation): number {
+/** How many attachments an operation takes; a snapshotFile restore takes the .vsf. */
+export function attachmentCount(op: ViceOperation, params?: unknown): number {
+  if (op === "snapshotFile") return isObject(params) && params.action === "restore" ? 1 : 0;
   return op === "programLoad" || op === "autostart" || op === "diskAttach" ? 1 : 0;
 }
 
@@ -514,6 +537,15 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       }
       return { action: params.action, name: validName(params.name, "name") } as ViceOperations[O]["params"];
     }
+    case "snapshotFile": {
+      if (params.action === "restore") {
+        onlyFields(params, ["action"]);
+        return { action: "restore" } as ViceOperations[O]["params"];
+      }
+      if (params.action !== "export") invalid("action must be export or restore");
+      onlyFields(params, ["action", "name"]);
+      return { action: "export", name: validName(params.name, "name") } as ViceOperations[O]["params"];
+    }
     case "screenCompare": {
       onlyFields(params, ["baseline", "maxMismatchRatio", "mask", "includeDiff"]);
       const ratio = params.maxMismatchRatio;
@@ -609,6 +641,12 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
       const result: MemoryReadParams = { address: params.address, size: params.size, space: params.space, view: params.view };
       return result as ViceOperations[O]["params"];
     }
+    case "ioRead": {
+      onlyFields(params, ["address", "size"]);
+      if (!isInteger(params.address, 0xd000, 0xdfff)) invalid("address must be in the I/O area $d000-$dfff");
+      if (!isInteger(params.size, 1, 0x1000) || params.address + params.size > 0xe000) invalid("the range must stay inside $d000-$dfff");
+      return { address: params.address, size: params.size } as ViceOperations[O]["params"];
+    }
     case "registersGet": {
       onlyFields(params, ["space"]);
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
@@ -765,7 +803,7 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
         if (!isInteger(params.id, 1, 0xffff_ffff)) invalid("id must be a positive integer");
         return { action: params.action, id: params.id } as ViceOperations[O]["params"];
       }
-      onlyFields(params, op === "watchpoint" ? ["action", "address", "space", "size", "access", "condition"] : ["action", "address", "space", "condition"]);
+      onlyFields(params, op === "watchpoint" ? ["action", "address", "space", "size", "access", "condition"] : ["action", "address", "space", "size", "condition"]);
       if (!isInteger(params.address, 0, 0xffff)) invalid("address must be an integer from 0 to 65535");
       if (!isOneOf(SPACES, params.space)) invalid("space must be c64 or drive8");
       const added: Record<string, unknown> = { action: "add", address: params.address, space: params.space };
@@ -775,6 +813,9 @@ export function validateViceParams<O extends ViceOperation>(op: O, params: unkno
         if (!isOneOf(WATCH_ACCESS, params.access)) invalid("access must be read, write or read-write");
         added.size = params.size;
         added.access = params.access;
+      } else if (params.size !== undefined) {
+        if (!isInteger(params.size, 1, 0x10000) || params.address + params.size > 0x10000) invalid("size must keep the range inside $0000-$ffff");
+        added.size = params.size;
       }
       if (params.condition !== undefined) added.condition = validateCondition(params.condition);
       return added as ViceOperations[O]["params"];
@@ -868,11 +909,16 @@ function validateRunTarget(value: unknown): RunTarget {
   return invalid("target kind must be address, memory or raster");
 }
 
+function isRemoved(value: unknown): value is PointRemoved {
+  return isObject(value) && value.removed === true && isInteger(value.id, 1, 0xffff_ffff) && Object.keys(value).length === 2;
+}
+
 function isBreakpoint(value: unknown): value is Breakpoint {
   return (
     isObject(value) &&
     isInteger(value.id, 1, 0xffff_ffff) &&
     isInteger(value.address, 0, 0xffff) &&
+    (value.size === undefined || isInteger(value.size, 1, 0x10000)) &&
     isOneOf(SPACES, value.space) &&
     typeof value.enabled === "boolean" &&
     (value.condition === undefined || isCondition(value.condition))
@@ -921,9 +967,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       if (!ok) throw new ProtocolError("status result is malformed");
       break;
     }
-    case "memoryRead": {
+    case "memoryRead":
+    case "ioRead": {
       if (!isInteger(value.address, 0, 0xffff) || !isHexData(value.data)) {
-        throw new ProtocolError("memoryRead result is malformed");
+        throw new ProtocolError(`${op} result is malformed`);
       }
       break;
     }
@@ -1017,12 +1064,12 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       break;
     }
     case "breakpoint": {
-      const ok = Array.isArray(value.breakpoints) ? value.breakpoints.every(isBreakpoint) : isBreakpoint(value);
+      const ok = Array.isArray(value.breakpoints) ? value.breakpoints.every(isBreakpoint) : isRemoved(value) || isBreakpoint(value);
       if (!ok) throw new ProtocolError("breakpoint result is malformed");
       break;
     }
     case "watchpoint": {
-      const ok = Array.isArray(value.watchpoints) ? value.watchpoints.every(isWatchpoint) : isWatchpoint(value);
+      const ok = Array.isArray(value.watchpoints) ? value.watchpoints.every(isWatchpoint) : isRemoved(value) || isWatchpoint(value);
       if (!ok) throw new ProtocolError("watchpoint result is malformed");
       break;
     }
@@ -1059,6 +1106,11 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
       if (!ok) throw new ProtocolError("snapshot result is malformed");
       break;
     }
+    case "snapshotFile": {
+      const ok = (value.exported === true && isInteger(value.bytes, 1, 0xffff_ffff)) || (value.restored === true && isOneOf(RUN_STATES, value.state));
+      if (!ok) throw new ProtocolError("snapshotFile result is malformed");
+      break;
+    }
     case "cpuHistory": {
       const ok =
         Array.isArray(value.entries) &&
@@ -1111,8 +1163,10 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         isObject(range) &&
         isInteger(range.start, 0, 0xffff) &&
         isInteger(range.end, 0, 0xffff) &&
-        (["execute", "read", "write"] as const).every((flag) => typeof range[flag] === "boolean");
-      const ok = Array.isArray(value.ranges) ? value.ranges.every(isRange) : value.cleared === true;
+        isInteger(range.flags, 1, 0xff);
+      const ok = Array.isArray(value.ranges)
+        ? value.ranges.every(isRange) && (value.next === undefined || isInteger(value.next, 0, 0xffff))
+        : value.cleared === true;
       if (!ok) throw new ProtocolError("memmap result is malformed");
       break;
     }

package/src/script.ts

@@ -2,7 +2,7 @@
 // a refusal prints {"error":{code,message}} with exit status 1, and a usage error prints the
 // usage text as an invalid-input error with exit status 2.
 
-import { WireFailure } from "./protocol/messages.ts";
+import { shownMessage, WireFailure } from "./protocol/messages.ts";
 import { elapsedMs, startTrace, trace, type TraceFields } from "./trace.ts";
 
 /** A wrong command line. The message names the problem; an empty message asks for the usage text alone. */
@@ -38,7 +38,8 @@ export async function runScript(body: () => unknown, options: { usage: string; r
     result = await body();
   } catch (error) {
     if ([WireFailure, ...(options.refusals ?? [])].some((refusal) => error instanceof refusal)) {
-      const { code, message } = error as Error & { code: string };
+      const { code } = error as Error & { code: string };
+      const message = shownMessage(error as Error & { code: string });
       printLine({ error: { code, message } });
       process.exitCode = 1;
       end({ error: { code, message } });