@henols/vice-mcp 0.1.9 → 0.1.11

package/stock-input.ts

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// stock-input.ts
+//
+// THE keyboard and joystick handlers for Family D: vice_keyboard_type,
+// vice_keyboard_petscii, and vice_joystick_set. Ships the input half of the
+// tool families this milestone builds on stock VICE's binary monitor.
+//
+// WHY THIS FILE EXISTS: KEYBOARD_FEED (0x72) and JOYPORT_SET (0xa2) are
+// thin wire opcodes -- the argument validation, ASCII->PETSCII conversion
+// routing, and the composed-value bookkeeping that make them safe and
+// legible to an agent all have to live somewhere. This is that somewhere:
+// every handler here follows the shared StockSessionHandler contract
+// (stock-handler.ts), builds its wire body through stock-protocol.ts's
+// encoders only, and answers through stockAnswer() so D-06's runState stamp
+// is never missed.
+//
+// WHAT NOT TO DO:
+//   - Never convert text to PETSCII inline. stock-petscii.ts's
+//     asciiToPetscii() is the ONE conversion path -- a second hand-rolled
+//     version here is exactly the failure mode that module's own header
+//     comment warns about.
+//   - Never send an EXIT so the queued keyboard buffer gets consumed.
+//     D-05 is absolute: this client never issues a resume the agent did not
+//     explicitly ask for. The answer says the machine is halted; the agent
+//     resumes explicitly, on its own schedule.
+//   - Never add vice_joystick_tap. A tap needs the machine to RUN for a
+//     measured interval -- an unrequested EXIT (forbidden by D-05) plus a
+//     frame/cycle measurement that does not exist on stock until Phase 7's
+//     timing route lands (docs/stock-vice-parity.md section A item 7).
+//     vice_joystick_set (hold/release/centre) satisfies DIRECT-07's
+//     joystick half in the meantime.
+//   - Never construct an ok-answer outside stockAnswer(). Every successful
+//     result below is built through it, never a bare
+//     `{ content: [...], isError: false }` literal.
+import { CommandType, joyportSetBody, keyboardFeedBody } from "./stock-protocol.ts";
+import { asciiToPetscii, StockPetsciiError } from "./stock-petscii.ts";
+import { convertWireError, isErrorText, stockAnswer, type StockSessionHandler } from "./stock-handler.ts";
+
+/** True iff `value` is a well-formed, generic JSON object -- not null, not
+ * an array. Matches vice.ts's own isPlainObject() predicate exactly -- the
+ * same narrowing discipline this module tree uses everywhere a parsed JSON
+ * value's fields are touched. Declared privately per this codebase's own
+ * convention (re-declared per consuming module, never imported). */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// vice_keyboard_type / vice_keyboard_petscii
+// ---------------------------------------------------------------------------
+
+/** Halted-machine note every keyboard answer carries -- docs/stock-vice-parity.md
+ * section A item 7's recorded divergence: input lands in the buffer of a
+ * machine now halted (D-05: any command halts it), and nothing consumes the
+ * buffer until the agent explicitly resumes. */
+const KEYBOARD_HALTED_NOTE =
+  "Bytes are queued in the KERNAL keyboard buffer -- nothing consumes them until the machine runs. " +
+  "This client never issues an unrequested resume (D-05); resume explicitly to have the buffer read.";
+
+/**
+ * vice_keyboard_type -- types `text` (converted to PETSCII via
+ * stock-petscii.ts's asciiToPetscii()) into the keyboard buffer.
+ * Arguments: `text` (required string), `petscii_upper` (optional boolean,
+ * default true) -- the fork's exact argument names, including the
+ * snake_case `petscii_upper`.
+ */
+export const handleKeyboardType: StockSessionHandler = async (args, session) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_keyboard_type: arguments must be an object");
+  }
+
+  const { text, petscii_upper: petsciiUpperArg } = args;
+  if (typeof text !== "string") {
+    return isErrorText("vice_keyboard_type: text is required and must be a string");
+  }
+  if (petsciiUpperArg !== undefined && typeof petsciiUpperArg !== "boolean") {
+    return isErrorText("vice_keyboard_type: petscii_upper must be a boolean");
+  }
+  const petsciiUpper = petsciiUpperArg === undefined ? true : petsciiUpperArg;
+
+  let petscii: Buffer;
+  try {
+    petscii = asciiToPetscii(text, { upper: petsciiUpper });
+  } catch (err) {
+    // A StockPetsciiError's own message is returned VERBATIM -- never
+    // re-worded, and never a fallback to sending the raw, unconverted
+    // bytes instead.
+    if (err instanceof StockPetsciiError) {
+      return isErrorText(err.message);
+    }
+    throw err;
+  }
+
+  const body = keyboardFeedBody({ petscii });
+  try {
+    await session.client.send(CommandType.KeyboardFeed, body);
+  } catch (err) {
+    return convertWireError("vice_keyboard_type", err);
+  }
+
+  return stockAnswer(session.client, {
+    text,
+    petsciiUpper,
+    byteCount: petscii.length,
+    petsciiHex: petscii.toString("hex"),
+    note: KEYBOARD_HALTED_NOTE,
+  });
+};
+
+/**
+ * vice_keyboard_petscii -- feeds explicit, already-PETSCII bytes into the
+ * keyboard buffer with no conversion. This is the deliberate escape hatch
+ * handleKeyboardType()'s control-code refusal points callers at: a caller
+ * that genuinely wants a PETSCII control code (e.g. 0x93, clear screen)
+ * states it here, one byte at a time, rather than through an ASCII string.
+ * Argument: `data` (required array of integers, 1-255 elements, each
+ * 0x00-0xff).
+ */
+export const handleKeyboardPetscii: StockSessionHandler = async (args, session) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_keyboard_petscii: arguments must be an object");
+  }
+
+  const { data } = args;
+  if (!Array.isArray(data)) {
+    return isErrorText("vice_keyboard_petscii: data is required and must be an array");
+  }
+  if (data.length === 0) {
+    return isErrorText("vice_keyboard_petscii: data must not be empty");
+  }
+  if (data.length > 255) {
+    return isErrorText(`vice_keyboard_petscii: data exceeds 255 bytes (${data.length}) -- KEYBOARD_FEED's textLen field is a uint8`);
+  }
+  for (let index = 0; index < data.length; index++) {
+    const value: unknown = data[index];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0x00 || value > 0xff) {
+      return isErrorText(`vice_keyboard_petscii: data[${index}] must be an integer in 0..0xff, got ${JSON.stringify(value)}`);
+    }
+  }
+
+  const petscii = Buffer.from(data as number[]);
+  const body = keyboardFeedBody({ petscii });
+  try {
+    await session.client.send(CommandType.KeyboardFeed, body);
+  } catch (err) {
+    return convertWireError("vice_keyboard_petscii", err);
+  }
+
+  return stockAnswer(session.client, {
+    byteCount: petscii.length,
+    petsciiHex: petscii.toString("hex"),
+    note: KEYBOARD_HALTED_NOTE,
+  });
+};
+
+// ---------------------------------------------------------------------------
+// vice_joystick_set -- and the deliberate absence of vice_joystick_tap
+// ---------------------------------------------------------------------------
+
+/**
+ * JOYPORT_SET's `value` bit layout. **[ASSUMED]** -- RESEARCH.md
+ * Assumptions Log row A3: derived from general VICE joystick-driver
+ * knowledge, never confirmed against the manual or a probe run against a
+ * real binary. Probe debt filed at
+ * .planning/todos/pending/2026-08-14-probe-phase3-assumed-wire-details.md.
+ * Do not remove the [ASSUMED] label until that todo's acceptance check
+ * closes it -- do not write a comment claiming this mapping is verified.
+ *
+ * Exported as a single named constant so a future probe session has
+ * exactly one place to correct it -- joyportSetBody() itself deliberately
+ * takes an already-composed raw `value` for the same reason.
+ */
+export const JOYPORT_BITS = { up: 0x01, down: 0x02, left: 0x04, right: 0x08, fire: 0x10 } as const;
+
+const VALID_DIRECTIONS = ["up", "down", "left", "right", "center"] as const;
+type JoystickDirection = (typeof VALID_DIRECTIONS)[number];
+
+function isValidDirection(value: string): value is JoystickDirection {
+  return (VALID_DIRECTIONS as readonly string[]).includes(value);
+}
+
+/**
+ * vice_joystick_set -- composes a JOYPORT_SET value from `direction`
+ * (string or array of strings) and `fire`, and sends it. Arguments: `port`
+ * (optional number, default 1), `direction` (optional string or array of
+ * strings, default "center"), `fire` (optional boolean, default false) --
+ * the fork's exact names and documented string-or-array shape.
+ *
+ * vice_joystick_tap is deliberately absent from this module (and the whole
+ * stock manifest) -- a tap needs the machine to run for a measured
+ * interval, which is an unrequested EXIT (forbidden by D-05) plus a
+ * frame/cycle measurement stock does not have until Phase 7's timing route
+ * lands (docs/stock-vice-parity.md section A item 7). Do not approximate it
+ * with a sleep; do not implement it here.
+ */
+export const handleJoystickSet: StockSessionHandler = async (args, session) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_joystick_set: arguments must be an object");
+  }
+
+  const portArg = args.port === undefined ? 1 : args.port;
+  if (typeof portArg !== "number" || !Number.isInteger(portArg) || (portArg !== 1 && portArg !== 2)) {
+    return isErrorText(`vice_joystick_set: port must be 1 or 2, got ${JSON.stringify(args.port)}`);
+  }
+  const port = portArg;
+
+  const fireArg = args.fire === undefined ? false : args.fire;
+  if (typeof fireArg !== "boolean") {
+    return isErrorText("vice_joystick_set: fire must be a boolean");
+  }
+  const fire = fireArg;
+
+  const rawDirection = args.direction === undefined ? "center" : args.direction;
+  const directionInputs: unknown[] = Array.isArray(rawDirection) ? rawDirection : [rawDirection];
+
+  const directions: JoystickDirection[] = [];
+  for (let index = 0; index < directionInputs.length; index++) {
+    const rawValue = directionInputs[index];
+    const normalized = typeof rawValue === "string" ? rawValue.trim().toLowerCase() : undefined;
+    if (normalized === undefined || !isValidDirection(normalized)) {
+      return isErrorText(
+        `vice_joystick_set: direction[${index}] must be one of up, down, left, right, center -- got ${JSON.stringify(rawValue)}`,
+      );
+    }
+    directions.push(normalized);
+  }
+
+  const hasUp = directions.includes("up");
+  const hasDown = directions.includes("down");
+  const hasLeft = directions.includes("left");
+  const hasRight = directions.includes("right");
+  const hasCenter = directions.includes("center");
+
+  // A composed value asserting two opposite switches at once is a state no
+  // real joystick can produce -- refused before any send, per this module's
+  // own T-3-02 threat mitigation.
+  if (hasUp && hasDown) {
+    return isErrorText("vice_joystick_set: direction cannot contain both 'up' and 'down' -- no real joystick can assert two opposite switches at once");
+  }
+  if (hasLeft && hasRight) {
+    return isErrorText("vice_joystick_set: direction cannot contain both 'left' and 'right' -- no real joystick can assert two opposite switches at once");
+  }
+  if (hasCenter && directions.length > 1) {
+    return isErrorText("vice_joystick_set: 'center' cannot be combined with any other direction");
+  }
+
+  let value = 0;
+  const valueBits: string[] = [];
+  for (const direction of ["up", "down", "left", "right"] as const) {
+    if (directions.includes(direction)) {
+      value |= JOYPORT_BITS[direction];
+      valueBits.push(direction);
+    }
+  }
+  if (fire) {
+    value |= JOYPORT_BITS.fire;
+    valueBits.push("fire");
+  }
+
+  const body = joyportSetBody({ port, value });
+  try {
+    await session.client.send(CommandType.JoyportSet, body);
+  } catch (err) {
+    return convertWireError("vice_joystick_set", err);
+  }
+
+  return stockAnswer(session.client, {
+    port,
+    directions,
+    fire,
+    value,
+    valueBits,
+  });
+};

package/stock-machine.ts

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+// stock-machine.ts
+//
+// Family D: the machine-control half of Phase 3's stock tool surface --
+// `vice_machine_reset`, `vice_autostart`, `vice_disk_attach`,
+// `vice_snapshot_save` and `vice_snapshot_load`. Five tools that either
+// restart the machine (RESET, AUTOSTART) or hand VICE a filename THE HOST
+// opens (AUTOSTART, DUMP, UNDUMP) -- every filename-carrying send in this
+// file routes through stock-paths.ts's one translation wrapper (imported
+// below), never a local path heuristic.
+//
+// WHAT NOT TO DO:
+//   - Never gate or deny vice_machine_reset's hard mode. CLAUDE.md's
+//     power-cycle warning is about RESOURCE_SET (0x52) writes to
+//     MachineVideoStandard/VICIIModel/MachinePowerFrequency -- Phase 6
+//     territory, a DIFFERENT opcode entirely. RESET (0xcc) is a distinct
+//     command, and an agent-requested hard reset via RESET is exactly what
+//     DIRECT-06 asks for. It needs no deny-list (RESEARCH.md Pitfall 1).
+//   - Never look for a per-unit disk-attach route mid-implementation.
+//     AUTOSTART (0xdd) has NO drive-unit field on the wire at all -- this is
+//     a protocol gap, not a code bug you can fix by looking harder
+//     (RESEARCH.md Pitfall 2).
+//   - Never add a disk-detach handler here. D-13 ships that tool in Phase 7
+//     through the text monitor -- grep-gated to zero occurrences of its name
+//     in this file's own acceptance criteria.
+//   - Never build a host path outside stock-paths.ts. Every filename this
+//     file sends through the wire goes through that same one wrapper --
+//     grep-gated to zero direct hostPath()/hostPathCandidates() calls here.
+//   - Never construct an ok-answer outside stockAnswer(). D-06 requires
+//     every stock tool answer to carry runState, and stockAnswer() is the
+//     one place that is stamped.
+import { resolve, dirname } from "node:path";
+import { mkdirSync, existsSync, readdirSync, writeFileSync, readFileSync } from "node:fs";
+
+import { CommandType, ResetMode, resetBody, autostartBody, dumpBody, undumpBody } from "./stock-protocol.ts";
+import { stockAnswer, convertWireError, isErrorText, type StockSessionHandler } from "./stock-handler.ts";
+import { withEmulatorSidePath, snapshotPathFor, snapshotMetaPathFor, sanitizeSnapshotName } from "./stock-paths.ts";
+
+/** True iff `value` is a well-formed, generic JSON object -- not null, not
+ * an array. Matches this module tree's own isPlainObject() convention
+ * (vice.ts:314, stock-condition.ts:228) -- redeclared privately here, not
+ * imported, per the established per-module convention. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// handleMachineReset -- RESET (0xcc), with an OPTIONAL follow-up EXIT (0xaa).
+// ---------------------------------------------------------------------------
+
+/**
+ * `mode` defaults to "soft"; `run_after` defaults to **false** on stock --
+ * the divergence docs/stock-vice-parity.md records. RESET has no run-after
+ * field on the wire at all, so honouring `run_after: true` means sending a
+ * follow-up EXIT -- fine when the agent explicitly asked for it (D-05
+ * licenses this: the agent's own argument IS the request, not an
+ * auto-resume), but a *default* of true would resume a machine nobody asked
+ * to resume, which D-05's absolute no-unrequested-resume policy forbids.
+ * This is one of only two EXIT call sites in this phase -- the other is
+ * vice_execution_run.
+ */
+export const handleMachineReset: StockSessionHandler = async (args, session) => {
+  const a = isPlainObject(args) ? args : {};
+
+  const modeArg = a.mode;
+  if (modeArg !== undefined && modeArg !== "soft" && modeArg !== "hard") {
+    return isErrorText(`vice_machine_reset: mode must be "soft" or "hard", got ${JSON.stringify(modeArg)}`);
+  }
+  const mode: "soft" | "hard" = modeArg === "hard" ? "hard" : "soft";
+
+  const runAfterArg = a.run_after;
+  if (runAfterArg !== undefined && typeof runAfterArg !== "boolean") {
+    return isErrorText(`vice_machine_reset: run_after must be a boolean, got ${typeof runAfterArg}`);
+  }
+  const runAfter = runAfterArg === true; // default false on stock (D-03/D-05)
+
+  try {
+    await session.client.send(CommandType.Reset, resetBody({ mode: mode === "hard" ? ResetMode.Hard : ResetMode.Soft }));
+
+    let resumed = false;
+    if (runAfter) {
+      // Licensed by D-05: run_after: true is the AGENT's own explicit
+      // request, not an auto-resume -- one of only two EXIT sites in this
+      // phase (the other is vice_execution_run).
+      await session.client.send(CommandType.Exit);
+      resumed = true;
+    }
+
+    return stockAnswer(session.client, { mode, runAfter, resumed });
+  } catch (err) {
+    return convertWireError("vice_machine_reset", err);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// handleAutostart -- AUTOSTART (0xdd), run flag honoured, path translated.
+// ---------------------------------------------------------------------------
+
+/**
+ * `program` is refused when supplied (D-03): AUTOSTART supports only a
+ * numeric `fileIndex` and has no load-by-name field, so an argument stock
+ * cannot honour is refused rather than silently dropped.
+ */
+export const handleAutostart: StockSessionHandler = async (args, session) => {
+  const a = isPlainObject(args) ? args : {};
+
+  const path = a.path;
+  if (typeof path !== "string" || path.length === 0) {
+    return isErrorText("vice_autostart: path is required and must be a non-empty string");
+  }
+
+  if (a.program !== undefined) {
+    return isErrorText(
+      "vice_autostart: program is not supported on the stock backend -- AUTOSTART (0xdd) supports only a numeric " +
+        "fileIndex field and has no load-by-name field. Use index to select a program by position instead.",
+    );
+  }
+
+  const runArg = a.run;
+  if (runArg !== undefined && typeof runArg !== "boolean") {
+    return isErrorText(`vice_autostart: run must be a boolean, got ${typeof runArg}`);
+  }
+  const run = runArg === undefined ? true : runArg; // matches the fork's own default
+
+  const indexArg = a.index;
+  if (indexArg !== undefined && (typeof indexArg !== "number" || !Number.isInteger(indexArg) || indexArg < 0 || indexArg > 0xffff)) {
+    return isErrorText(`vice_autostart: index must be an integer in 0..0xffff, got ${JSON.stringify(indexArg)}`);
+  }
+  const index = indexArg === undefined ? 0 : indexArg;
+
+  const containerPath = resolve(path);
+  try {
+    const { sentPath } = await withEmulatorSidePath("vice_autostart", containerPath, (hostPath) =>
+      session.client.send(CommandType.AutoStart, autostartBody({ runAfter: run, fileIndex: index, filename: hostPath })),
+    );
+    return stockAnswer(session.client, { path: containerPath, sentPath, run, index });
+  } catch (err) {
+    return convertWireError("vice_autostart", err);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// handleDiskAttach -- AUTOSTART (0xdd) again, the D-14 approximation.
+// ---------------------------------------------------------------------------
+
+/**
+ * Kept the fork's exact `unit`+`path` argument shape (D-03). Units 9-11 are
+ * refused, never silently retargeted to unit 8 -- AUTOSTART is the only wire
+ * route to attaching an image and its request body has NO drive-unit field
+ * at all, so an agent told "attached to unit 9" when the image landed on
+ * unit 8 would debug the wrong drive. See docs/stock-vice-parity.md's D-14
+ * entry.
+ */
+export const handleDiskAttach: StockSessionHandler = async (args, session) => {
+  const a = isPlainObject(args) ? args : {};
+
+  const unit = a.unit;
+  if (typeof unit !== "number" || !Number.isInteger(unit) || unit < 8 || unit > 11) {
+    return isErrorText(`vice_disk_attach: unit must be an integer in 8..11, got ${JSON.stringify(a.unit)}`);
+  }
+
+  const path = a.path;
+  if (typeof path !== "string" || path.length === 0) {
+    return isErrorText("vice_disk_attach: path is required and must be a non-empty string");
+  }
+
+  if (unit !== 8) {
+    return isErrorText(
+      `vice_disk_attach: unit ${unit} cannot be targeted on the stock backend -- AUTOSTART (0xdd) is the only wire ` +
+        "route to attaching a disk image on the stock binary monitor and its request body has no drive-unit field at " +
+        "all, so units 9-11 cannot be targeted. Only unit 8 is reachable; the call was refused rather than silently " +
+        "retargeted to unit 8 so you do not debug the wrong drive. See docs/stock-vice-parity.md's D-14 entry.",
+    );
+  }
+
+  const containerPath = resolve(path);
+  try {
+    const { sentPath } = await withEmulatorSidePath("vice_disk_attach", containerPath, (hostPath) =>
+      session.client.send(CommandType.AutoStart, autostartBody({ runAfter: false, fileIndex: 0, filename: hostPath })),
+    );
+    return stockAnswer(session.client, {
+      unit: 8,
+      path: containerPath,
+      sentPath,
+      approximation: "AUTOSTART with the run flag clear (D-14)",
+    });
+  } catch (err) {
+    return convertWireError("vice_disk_attach", err);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// handleSnapshotSave / handleSnapshotLoad -- DUMP (0x41) / UNDUMP (0x42).
+// ---------------------------------------------------------------------------
+
+const MAX_DESCRIPTION_LENGTH = 512;
+
+/**
+ * `name` is sanitised through stock-paths.ts's sanitizeSnapshotName() into a
+ * workspace-internal path -- never treated as a path fragment. The client-
+ * side metadata sidecar (docs/stock-vice-parity.md item 6: "DUMP writes
+ * state; JSON metadata is our own bookkeeping") is written ONLY after a
+ * successful DUMP, so a failed save never leaves a sidecar claiming a
+ * snapshot that does not exist; a sidecar WRITE failure is reported in the
+ * answer as `metadataWritten: false` with a reason, never thrown -- the
+ * snapshot itself succeeded and the agent must be told exactly that (T-3-10).
+ */
+export const handleSnapshotSave: StockSessionHandler = async (args, session) => {
+  const a = isPlainObject(args) ? args : {};
+
+  let name: string;
+  try {
+    name = sanitizeSnapshotName(a.name);
+  } catch (err) {
+    return isErrorText(`vice_snapshot_save: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const descriptionArg = a.description;
+  if (descriptionArg !== undefined && typeof descriptionArg !== "string") {
+    return isErrorText(`vice_snapshot_save: description must be a string, got ${typeof descriptionArg}`);
+  }
+  if (typeof descriptionArg === "string" && descriptionArg.length > MAX_DESCRIPTION_LENGTH) {
+    return isErrorText(`vice_snapshot_save: description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${descriptionArg.length})`);
+  }
+  const description: string | null = typeof descriptionArg === "string" ? descriptionArg : null;
+
+  const includeRomsArg = a.include_roms;
+  if (includeRomsArg !== undefined && typeof includeRomsArg !== "boolean") {
+    return isErrorText(`vice_snapshot_save: include_roms must be a boolean, got ${typeof includeRomsArg}`);
+  }
+  const includeRoms = includeRomsArg === true;
+
+  const includeDisksArg = a.include_disks;
+  if (includeDisksArg !== undefined && typeof includeDisksArg !== "boolean") {
+    return isErrorText(`vice_snapshot_save: include_disks must be a boolean, got ${typeof includeDisksArg}`);
+  }
+  const includeDisks = includeDisksArg === true;
+
+  const containerPath = snapshotPathFor(name);
+  // VICE opens the file for writing and will not create the directory --
+  // the same mkdirSync-before-translate ordering vice-sync.ts's screenshot()
+  // already uses.
+  mkdirSync(dirname(containerPath), { recursive: true });
+
+  let sentPath: string;
+  try {
+    const result = await withEmulatorSidePath("vice_snapshot_save", containerPath, (hostPath) =>
+      session.client.send(CommandType.Dump, dumpBody({ saveRoms: includeRoms, saveDisks: includeDisks, filename: hostPath })),
+    );
+    sentPath = result.sentPath;
+  } catch (err) {
+    return convertWireError("vice_snapshot_save", err);
+  }
+
+  // DUMP succeeded -- write the metadata sidecar. A write failure here is
+  // reported, never thrown: the snapshot itself is good.
+  const metadataPath = snapshotMetaPathFor(name);
+  let metadataWritten = true;
+  let metadataFailureReason: string | null = null;
+  try {
+    const metadata = {
+      name,
+      description,
+      createdAt: new Date().toISOString(),
+      includeRoms,
+      includeDisks,
+      viceVersion: session.versionQuad,
+      backend: "stock" as const,
+      snapshotPath: containerPath,
+    };
+    writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+  } catch (err) {
+    metadataWritten = false;
+    metadataFailureReason = err instanceof Error ? err.message : String(err);
+  }
+
+  return stockAnswer(session.client, {
+    name,
+    path: containerPath,
+    sentPath,
+    includeRoms,
+    includeDisks,
+    metadataWritten,
+    ...(metadataFailureReason !== null ? { metadataFailureReason } : {}),
+    metadataPath,
+  });
+};
+
+/**
+ * Refuses with an explanatory message, listing the `.vsf` basenames present
+ * in the snapshot directory, when the named snapshot file does not exist --
+ * the useful half of what the deleted `vice_snapshot_list` used to provide
+ * (D-16 deleted the tool because it had no consumer), delivered at the point
+ * of failure rather than as its own tool.
+ *
+ * Loading a snapshot REPLACES THE ENTIRE MACHINE STATE, so this handler's
+ * `runState` reflects whatever the event stream reports after UNDUMP and
+ * nothing is asserted about it here.
+ */
+export const handleSnapshotLoad: StockSessionHandler = async (args, session) => {
+  const a = isPlainObject(args) ? args : {};
+
+  let name: string;
+  try {
+    name = sanitizeSnapshotName(a.name);
+  } catch (err) {
+    return isErrorText(`vice_snapshot_load: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const containerPath = snapshotPathFor(name);
+  if (!existsSync(containerPath)) {
+    const dir = dirname(containerPath);
+    let available: string[] = [];
+    try {
+      available = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".vsf")) : [];
+    } catch {
+      available = [];
+    }
+    return isErrorText(
+      `vice_snapshot_load: no snapshot named "${name}" exists at ${containerPath}. ` +
+        (available.length > 0 ? `Available snapshots: ${available.join(", ")}` : "No snapshots exist yet."),
+    );
+  }
+
+  let sentPath: string;
+  let programCounter: number | null = null;
+  try {
+    const result = await withEmulatorSidePath("vice_snapshot_load", containerPath, (hostPath) =>
+      session.client.send(CommandType.Undump, undumpBody({ filename: hostPath })),
+    );
+    sentPath = result.sentPath;
+    const reply = result.result;
+    if (reply && typeof reply === "object" && "type" in reply && (reply as { type: unknown }).type === "undump") {
+      programCounter = (reply as { programCounter: number }).programCounter;
+    }
+  } catch (err) {
+    return convertWireError("vice_snapshot_load", err);
+  }
+
+  const metadataPath = snapshotMetaPathFor(name);
+  let metadata: { description?: string | null; createdAt?: string } | null = null;
+  try {
+    if (existsSync(metadataPath)) {
+      const parsed: unknown = JSON.parse(readFileSync(metadataPath, "utf8"));
+      if (isPlainObject(parsed)) {
+        metadata = {
+          description: typeof parsed.description === "string" ? parsed.description : null,
+          createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : undefined,
+        };
+      }
+    }
+  } catch {
+    metadata = null; // a missing or unparsable sidecar is reported as null, never an error
+  }
+
+  return stockAnswer(session.client, { name, path: containerPath, sentPath, programCounter, metadata });
+};