c64-debug-mcp 0.1.0

package/dist/http.cjs

@@ -0,0 +1,3603 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/http.ts
+var import_node_http = __toESM(require("http"), 1);
+
+// src/server.ts
+var import_tools = require("@mastra/core/tools");
+var import_mcp = require("@mastra/mcp");
+var import_zod4 = require("zod");
+
+// src/contracts.ts
+var import_zod = require("zod");
+var VICE_API_VERSION = 2;
+var VICE_STX = 2;
+var VICE_BROADCAST_REQUEST_ID = 4294967295;
+var DEFAULT_MONITOR_HOST = "127.0.0.1";
+var DEFAULT_C64_BINARY = "x64sc";
+var DEFAULT_FORBIDDEN_PORTS = /* @__PURE__ */ new Set([6502]);
+var transportStateSchema = import_zod.z.enum([
+  "not_started",
+  "starting",
+  "waiting_for_monitor",
+  "connecting",
+  "connected",
+  "reconnecting",
+  "disconnected",
+  "stopped",
+  "faulted"
+]);
+var processStateSchema = import_zod.z.enum(["not_applicable", "launching", "running", "exited", "crashed"]);
+var executionStateSchema = import_zod.z.enum(["unknown", "running", "stopped"]);
+var stopReasonSchema = import_zod.z.enum([
+  "none",
+  "breakpoint",
+  "watchpoint_read",
+  "watchpoint_write",
+  "step_complete",
+  "reset",
+  "monitor_entry",
+  "program_end",
+  "error",
+  "unknown"
+]);
+var sessionHealthSchema = import_zod.z.enum(["not_configured", "starting", "ready", "recovering", "stopped", "error"]);
+var breakpointKindSchema = import_zod.z.enum(["exec", "read", "write", "read_write"]);
+var resetModeSchema = import_zod.z.enum(["soft", "hard"]);
+var inputActionSchema = import_zod.z.enum(["press", "release", "tap"]);
+var joystickControlSchema = import_zod.z.enum(["up", "down", "left", "right", "fire"]);
+var joystickPortSchema = import_zod.z.union([import_zod.z.literal(1), import_zod.z.literal(2)]);
+var toolErrorCategorySchema = import_zod.z.enum([
+  "validation",
+  "configuration",
+  "session_state",
+  "process_launch",
+  "connection",
+  "protocol",
+  "timeout",
+  "io",
+  "unsupported",
+  "internal"
+]);
+var warningItemSchema = import_zod.z.object({
+  code: import_zod.z.string(),
+  message: import_zod.z.string()
+});
+var c64ConfigSchema = import_zod.z.object({
+  binaryPath: import_zod.z.string().optional(),
+  workingDirectory: import_zod.z.string().optional(),
+  arguments: import_zod.z.string().optional()
+});
+var responseMetaSchema = import_zod.z.object({
+  freshEmulator: import_zod.z.boolean(),
+  launchId: import_zod.z.number().int().nonnegative(),
+  restartCount: import_zod.z.number().int().nonnegative()
+});
+var C64_REGISTER_DEFINITIONS = [
+  { fieldName: "PC", viceName: "PC", widthBits: 16, min: 0, max: 65535, description: "Program counter register" },
+  { fieldName: "A", viceName: "A", widthBits: 8, min: 0, max: 255, description: "Accumulator register" },
+  { fieldName: "X", viceName: "X", widthBits: 8, min: 0, max: 255, description: "X index register" },
+  { fieldName: "Y", viceName: "Y", widthBits: 8, min: 0, max: 255, description: "Y index register" },
+  { fieldName: "SP", viceName: "SP", widthBits: 8, min: 0, max: 255, description: "Stack pointer register" },
+  { fieldName: "FL", viceName: "FL", widthBits: 8, min: 0, max: 255, description: "CPU flags register" },
+  { fieldName: "00", viceName: "00", widthBits: 8, min: 0, max: 255, description: "Zero-page processor port register 00" },
+  { fieldName: "01", viceName: "01", widthBits: 8, min: 0, max: 255, description: "Zero-page processor port register 01" },
+  { fieldName: "LIN", viceName: "LIN", widthBits: 16, min: 0, max: 65535, description: "Current raster line register" },
+  { fieldName: "CYC", viceName: "CYC", widthBits: 16, min: 0, max: 65535, description: "Current cycle position register" }
+];
+var toolErrorSchema = import_zod.z.object({
+  code: import_zod.z.string(),
+  message: import_zod.z.string(),
+  category: toolErrorCategorySchema,
+  retryable: import_zod.z.boolean(),
+  details: import_zod.z.record(import_zod.z.unknown()).optional()
+});
+function mainMemSpaceToProtocol() {
+  return 0;
+}
+function breakpointKindToOperation(kind) {
+  switch (kind) {
+    case "read":
+      return 1;
+    case "write":
+      return 2;
+    case "read_write":
+      return 3;
+    case "exec":
+      return 4;
+  }
+}
+function cpuOperationToBreakpointKind(operation) {
+  if ((operation & 4) === 4) {
+    return "exec";
+  }
+  if ((operation & 1) === 1 && (operation & 2) === 2) {
+    return "read_write";
+  }
+  if ((operation & 1) === 1) {
+    return "read";
+  }
+  if ((operation & 2) === 2) {
+    return "write";
+  }
+  return "exec";
+}
+
+// src/errors.ts
+var import_zod3 = require("zod");
+
+// src/schemas.ts
+var import_zod2 = require("zod");
+var warningSchema = warningItemSchema;
+var address16Schema = import_zod2.z.number().int().min(0).max(65535);
+var byteValueSchema = import_zod2.z.number().int().min(0).max(255).describe("Single raw byte value");
+var byteArraySchema = import_zod2.z.array(byteValueSchema).describe("Raw bytes as a JSON array");
+var c64RegisterValueSchema = import_zod2.z.object(
+  Object.fromEntries(
+    C64_REGISTER_DEFINITIONS.map((register) => [
+      register.fieldName,
+      import_zod2.z.number().int().min(register.min).max(register.max).describe(register.description)
+    ])
+  )
+);
+var c64PartialRegisterValueSchema = import_zod2.z.object(
+  Object.fromEntries(
+    C64_REGISTER_DEFINITIONS.map((register) => [
+      register.fieldName,
+      import_zod2.z.number().int().min(register.min).max(register.max).describe(register.description).optional()
+    ])
+  )
+);
+var debugStateSchema = import_zod2.z.object({
+  executionState: executionStateSchema.describe("Current execution state of the emulator"),
+  lastStopReason: stopReasonSchema.describe("Reason the emulator most recently stopped in the monitor"),
+  programCounter: address16Schema.describe("Current program counter"),
+  registers: c64RegisterValueSchema
+});
+var monitorStateSchema = import_zod2.z.object({
+  executionState: executionStateSchema.describe("Current execution state reported by the monitor"),
+  lastStopReason: stopReasonSchema.describe("Reason the monitor most recently reported a stop-like state"),
+  runtimeKnown: import_zod2.z.boolean().describe("Whether the monitor has reported a runtime event in this session"),
+  programCounter: address16Schema.nullable().describe("Program counter from the latest monitor event, or null if unknown")
+});
+var sessionStateResultSchema = import_zod2.z.object({
+  transportState: import_zod2.z.enum([
+    "not_started",
+    "starting",
+    "waiting_for_monitor",
+    "connecting",
+    "connected",
+    "reconnecting",
+    "disconnected",
+    "stopped",
+    "faulted"
+  ]),
+  processState: import_zod2.z.enum(["not_applicable", "launching", "running", "exited", "crashed"]),
+  executionState: executionStateSchema.describe("Current execution state of the emulator session"),
+  lastStopReason: stopReasonSchema.describe("Reason the emulator most recently stopped in the monitor"),
+  idleAutoResumeArmed: import_zod2.z.boolean().describe("Whether the idle auto-resume timer is currently armed"),
+  explicitPauseActive: import_zod2.z.boolean().describe("Whether execution was explicitly paused by the caller"),
+  lastCheckpointId: import_zod2.z.number().int().nullable().describe("Most recent hit checkpoint/watchpoint id when known"),
+  lastCheckpointKind: breakpointKindSchema.nullable().describe("Most recent hit checkpoint/watchpoint kind when known"),
+  recoveryInProgress: import_zod2.z.boolean(),
+  launchId: import_zod2.z.number().int().nonnegative(),
+  restartCount: import_zod2.z.number().int().nonnegative(),
+  freshEmulatorPending: import_zod2.z.boolean(),
+  connectedSince: import_zod2.z.string().nullable(),
+  lastResponseAt: import_zod2.z.string().nullable(),
+  processId: import_zod2.z.number().int().nullable(),
+  warnings: import_zod2.z.array(warningSchema)
+});
+var breakpointSchema = import_zod2.z.object({
+  id: import_zod2.z.number().int().describe("Breakpoint identifier"),
+  address: address16Schema.describe("Start address of the breakpoint range"),
+  length: import_zod2.z.number().int().positive().describe("Size of the breakpoint range in bytes"),
+  enabled: import_zod2.z.boolean().describe("Whether the breakpoint is enabled"),
+  temporary: import_zod2.z.boolean().describe("Whether the breakpoint is temporary"),
+  hasCondition: import_zod2.z.boolean().describe("Whether the breakpoint has a condition expression"),
+  kind: breakpointKindSchema.describe("Breakpoint trigger kind"),
+  label: import_zod2.z.string().nullable().optional().describe("Optional caller-provided label")
+});
+var joystickStateSchema = import_zod2.z.object({
+  up: import_zod2.z.boolean().describe("Whether up is currently held on the selected joystick port"),
+  down: import_zod2.z.boolean().describe("Whether down is currently held on the selected joystick port"),
+  left: import_zod2.z.boolean().describe("Whether left is currently held on the selected joystick port"),
+  right: import_zod2.z.boolean().describe("Whether right is currently held on the selected joystick port"),
+  fire: import_zod2.z.boolean().describe("Whether fire is currently held on the selected joystick port")
+});
+var programLoadResultSchema = import_zod2.z.object({
+  filePath: import_zod2.z.string().describe("Absolute path to the program file that was loaded"),
+  autoStart: import_zod2.z.boolean().describe("Whether the loaded program was requested to start immediately after loading"),
+  fileIndex: import_zod2.z.number().int().nonnegative().describe("Autostart file index inside the image, when applicable"),
+  executionState: executionStateSchema.describe("Execution state after the monitor-driven load request")
+});
+var captureDisplayResultSchema = import_zod2.z.object({
+  imagePath: import_zod2.z.string().describe("Absolute path to the rendered PNG image"),
+  width: import_zod2.z.number().int().positive().describe("Width of the visible rendered screen image"),
+  height: import_zod2.z.number().int().positive().describe("Height of the visible rendered screen image"),
+  debugWidth: import_zod2.z.number().int().positive().describe("Width of the full uncropped debug display buffer"),
+  debugHeight: import_zod2.z.number().int().positive().describe("Height of the full uncropped debug display buffer"),
+  debugOffsetX: import_zod2.z.number().int().nonnegative().describe("X offset of the visible inner area within the debug display buffer"),
+  debugOffsetY: import_zod2.z.number().int().nonnegative().describe("Y offset of the visible inner area within the debug display buffer"),
+  bitsPerPixel: import_zod2.z.number().int().positive().describe("Bits per pixel reported by the emulator display payload")
+});
+var graphicsModeSchema = import_zod2.z.enum([
+  "standard_text",
+  "multicolor_text",
+  "standard_bitmap",
+  "multicolor_bitmap",
+  "extended_background_color_text",
+  "invalid_text_mode",
+  "invalid_bitmap_mode_1",
+  "invalid_bitmap_mode_2"
+]);
+var displayStateResultSchema = import_zod2.z.object({
+  graphicsMode: graphicsModeSchema.describe("Decoded VIC-II graphics mode from D011/D016"),
+  extendedColorMode: import_zod2.z.boolean().describe("Whether extended background color mode is enabled"),
+  bitmapMode: import_zod2.z.boolean().describe("Whether bitmap mode is enabled"),
+  multicolorMode: import_zod2.z.boolean().describe("Whether multicolor mode is enabled"),
+  vicBankAddress: address16Schema.describe("Base address of the active 16K VIC bank"),
+  screenRamAddress: address16Schema.describe("Base address of the active 1000-byte screen matrix"),
+  characterMemoryAddress: address16Schema.nullable().describe("Base address of the active character memory when the current mode uses character data"),
+  bitmapMemoryAddress: address16Schema.nullable().describe("Base address of the active bitmap memory when the current mode uses bitmap data"),
+  colorRamAddress: address16Schema.describe("Base address of the 1000-byte color RAM area"),
+  borderColor: import_zod2.z.number().int().min(0).max(15).describe("Current border color value"),
+  backgroundColor0: import_zod2.z.number().int().min(0).max(15).describe("Current background color 0 value"),
+  backgroundColor1: import_zod2.z.number().int().min(0).max(15).describe("Current background color 1 value"),
+  backgroundColor2: import_zod2.z.number().int().min(0).max(15).describe("Current background color 2 value"),
+  backgroundColor3: import_zod2.z.number().int().min(0).max(15).describe("Current background color 3 value"),
+  vicRegisters: import_zod2.z.object({
+    d011: byteValueSchema.describe("Raw VIC-II register $D011"),
+    d016: byteValueSchema.describe("Raw VIC-II register $D016"),
+    d018: byteValueSchema.describe("Raw VIC-II register $D018"),
+    dd00: byteValueSchema.describe("Raw CIA2/VIC bank register $DD00"),
+    d020: byteValueSchema.describe("Raw border color register $D020"),
+    d021: byteValueSchema.describe("Raw background color register $D021"),
+    d022: byteValueSchema.describe("Raw background color register $D022"),
+    d023: byteValueSchema.describe("Raw background color register $D023"),
+    d024: byteValueSchema.describe("Raw background color register $D024")
+  }),
+  screenRam: byteArraySchema.describe("Raw 1000-byte screen matrix contents"),
+  colorRam: byteArraySchema.describe("Raw 1000-byte color RAM contents, masked to the low nybble")
+});
+var displayTextResultSchema = import_zod2.z.object({
+  graphicsMode: graphicsModeSchema.describe("Decoded VIC-II graphics mode from D011/D016"),
+  textMode: import_zod2.z.boolean().describe("Whether the current graphics mode supports direct screen-text decoding"),
+  lossy: import_zod2.z.boolean().describe("Whether the screen-code to ASCII translation may lose C64-specific glyph information"),
+  columns: import_zod2.z.number().int().positive().describe("Number of text columns decoded per row"),
+  rows: import_zod2.z.number().int().positive().describe("Number of decoded text rows"),
+  screenRamAddress: address16Schema.describe("Base address of the active 1000-byte screen matrix"),
+  textLines: import_zod2.z.array(import_zod2.z.string()).describe("Decoded text rows from screen RAM, trimmed on the right"),
+  tokenLines: import_zod2.z.array(import_zod2.z.string()).optional().describe("Optional richer tokenized rows, included only when non-ASCII or ambiguous C64 glyphs are present")
+});
+var keyboardInputResultSchema = import_zod2.z.object({
+  action: inputActionSchema.describe("Keyboard action that was applied"),
+  keys: import_zod2.z.array(import_zod2.z.string()).min(1).max(4).describe("Normalized symbolic key names"),
+  applied: import_zod2.z.boolean().describe("Whether the request was accepted and applied"),
+  held: import_zod2.z.boolean().describe("Whether the keys are still treated as held after this request"),
+  mode: import_zod2.z.enum(["buffered_text", "buffered_text_repeat"]).describe("Keyboard delivery mode supported by the emulator debug connection")
+});
+var joystickInputResultSchema = import_zod2.z.object({
+  port: joystickPortSchema.describe("Joystick port that received the input"),
+  action: inputActionSchema.describe("Joystick action that was applied"),
+  control: joystickControlSchema.describe("Joystick control that was applied"),
+  applied: import_zod2.z.boolean().describe("Whether the request was accepted and applied"),
+  state: joystickStateSchema
+});
+var waitForStateResultSchema = import_zod2.z.object({
+  executionState: executionStateSchema.describe("Current execution state after waiting"),
+  lastStopReason: stopReasonSchema.describe("Reason the emulator most recently stopped in the monitor"),
+  runtimeKnown: import_zod2.z.boolean().describe("Whether the monitor has reported a runtime event in this session"),
+  programCounter: address16Schema.nullable().describe("Program counter from the latest monitor event, or null if unknown"),
+  reachedTarget: import_zod2.z.boolean().describe("Whether the requested target state was reached before timeout"),
+  waitedMs: import_zod2.z.number().int().nonnegative().describe("Milliseconds spent waiting")
+});
+function toolOutputSchema(dataSchema) {
+  return import_zod2.z.object({
+    meta: responseMetaSchema,
+    data: dataSchema
+  });
+}
+
+// src/errors.ts
+var ViceMcpError = class extends Error {
+  code;
+  category;
+  retryable;
+  details;
+  constructor(code, message, category, retryable = false, details) {
+    super(message);
+    this.name = "ViceMcpError";
+    this.code = code;
+    this.category = category;
+    this.retryable = retryable;
+    this.details = details;
+  }
+};
+function validationError(message, details) {
+  throw new ViceMcpError("validation_error", message, "validation", false, details);
+}
+function debuggerNotPausedError(commandName, details) {
+  throw new ViceMcpError(
+    "debugger_not_paused",
+    `${commandName} can only be executed when the emulator is stopped.`,
+    "session_state",
+    false,
+    { commandName, requiredState: "stopped", ...details }
+  );
+}
+function emulatorNotRunningError(commandName, details) {
+  throw new ViceMcpError(
+    "emulator_not_running",
+    `${commandName} can only be executed when the emulator is running.`,
+    "session_state",
+    false,
+    { commandName, requiredState: "running", ...details }
+  );
+}
+function unsupportedError(message, details) {
+  throw new ViceMcpError("unsupported", message, "unsupported", false, details);
+}
+function asToolError(error) {
+  return toolErrorSchema.parse({
+    code: error.code,
+    message: error.message,
+    category: error.category,
+    retryable: error.retryable,
+    details: error.details
+  });
+}
+function zodDetails(error) {
+  return {
+    issues: error.issues.map((issue) => ({
+      code: issue.code,
+      message: issue.message,
+      path: issue.path
+    }))
+  };
+}
+function publicMessageFor(error) {
+  switch (error.code) {
+    case "debugger_not_paused":
+      return error.message;
+    case "emulator_not_running":
+      return error.message;
+    case "validation_error":
+    case "invalid_prg":
+    case "unsupported":
+    case "program_file_missing":
+    case "program_file_invalid":
+      return error.message;
+    case "port_allocation_failed":
+    case "port_in_use":
+    case "monitor_timeout":
+      return "The server could not start a usable emulator session. Check the emulator configuration and try again.";
+    case "not_connected":
+    case "connection_closed":
+    case "socket_write_failed":
+    case "timeout":
+      return "The server could not communicate with the emulator. Try the request again.";
+    case "protocol_invalid_stx":
+    case "emulator_protocol_error":
+      return "The emulator returned an unexpected debugger response. Try the request again.";
+    default:
+      switch (error.category) {
+        case "validation":
+        case "session_state":
+        case "unsupported":
+          return error.message;
+        case "configuration":
+        case "process_launch":
+          return "The server could not start the emulator with the current configuration.";
+        case "connection":
+        case "timeout":
+          return "The server could not communicate with the emulator. Try the request again.";
+        case "protocol":
+          return "The emulator returned an unexpected debugger response. Try the request again.";
+        case "io":
+          return "The requested file operation could not be completed.";
+        case "internal":
+          return "The server hit an unexpected error.";
+      }
+  }
+}
+function publicDetailsFor(error) {
+  switch (error.category) {
+    case "validation":
+    case "session_state":
+    case "unsupported":
+    case "io":
+      return error.details;
+    default:
+      return void 0;
+  }
+}
+function normalizeToolError(error) {
+  if (error instanceof ViceMcpError) {
+    const normalized = asToolError(error);
+    return new ViceMcpError(
+      normalized.code,
+      publicMessageFor(error),
+      normalized.category,
+      normalized.retryable,
+      publicDetailsFor(error)
+    );
+  }
+  if (error instanceof import_zod3.ZodError) {
+    return new ViceMcpError(
+      "validation_error",
+      error.issues.map((issue) => issue.message).join("; ") || "Validation failed",
+      "validation",
+      false,
+      zodDetails(error)
+    );
+  }
+  if (error instanceof Error) {
+    return new ViceMcpError("internal_error", "The server hit an unexpected error.", "internal", false);
+  }
+  return new ViceMcpError("internal_error", "The server hit an unexpected error.", "internal", false);
+}
+
+// src/session.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_fs = require("fs");
+var import_node_net2 = __toESM(require("net"), 1);
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
+var import_node_zlib = __toESM(require("zlib"), 1);
+
+// src/vice-protocol.ts
+var import_node_events = require("events");
+var import_node_net = __toESM(require("net"), 1);
+function parseLittleEndianVariableWidth(bytes) {
+  let value = 0;
+  for (let index = 0; index < bytes.length; index += 1) {
+    value += (bytes[index] ?? 0) * 2 ** (index * 8);
+  }
+  return value;
+}
+function encodeHeader(commandType, requestId, body) {
+  const header = Buffer.alloc(11);
+  header[0] = VICE_STX;
+  header[1] = VICE_API_VERSION;
+  header.writeUInt32LE(body.length, 2);
+  header.writeUInt32LE(requestId, 6);
+  header[10] = commandType;
+  return Buffer.concat([header, body]);
+}
+function parseBuffer(buffer) {
+  const responses = [];
+  let offset = 0;
+  while (offset + 12 <= buffer.length) {
+    if (buffer[offset] !== VICE_STX) {
+      throw new ViceMcpError("protocol_invalid_stx", "Invalid response prefix from emulator debug connection", "protocol");
+    }
+    const bodyLength = buffer.readUInt32LE(offset + 2);
+    const frameLength = 12 + bodyLength;
+    if (offset + frameLength > buffer.length) {
+      break;
+    }
+    const body = buffer.subarray(offset + 12, offset + frameLength);
+    const responseType = buffer[offset + 6];
+    const errorCode = buffer[offset + 7];
+    const requestId = buffer.readUInt32LE(offset + 8);
+    responses.push(parseResponse(responseType, errorCode, requestId, body));
+    offset += frameLength;
+  }
+  return { responses, remainder: buffer.subarray(offset) };
+}
+function parseResponse(responseType, errorCode, requestId, body) {
+  switch (responseType) {
+    case 1 /* MemoryGet */: {
+      const length = errorCode === 0 /* OK */ ? body.readUInt16LE(0) : 0;
+      return { type: "memory_get", requestId, errorCode, bytes: body.subarray(2, 2 + length) };
+    }
+    case 49 /* RegisterInfo */: {
+      const count = errorCode === 0 /* OK */ ? body.readUInt16LE(0) : 0;
+      const registers = Array.from({ length: count }, (_, index) => {
+        const start = 2 + index * 4;
+        return { id: body[start + 1], value: body.readUInt16LE(start + 2) };
+      });
+      return { type: "registers", requestId, errorCode, registers };
+    }
+    case 131 /* RegistersAvailable */: {
+      const count = errorCode === 0 /* OK */ ? body.readUInt16LE(0) : 0;
+      let offset = 2;
+      const registers = [];
+      for (let index = 0; index < count; index += 1) {
+        const itemSize = body[offset];
+        const id = body[offset + 1];
+        const size = body[offset + 2];
+        const nameLength = body[offset + 3];
+        const name = body.subarray(offset + 4, offset + 4 + nameLength).toString("ascii");
+        registers.push({ id, size, name });
+        offset += itemSize + 1;
+      }
+      return { type: "registers_available", requestId, errorCode, registers };
+    }
+    case 133 /* Info */: {
+      const mainVersionLength = body[0] ?? 0;
+      const version = Array.from(body.subarray(1, 1 + mainVersionLength));
+      const svnLengthOffset = 1 + mainVersionLength;
+      const svnLength = body[svnLengthOffset] ?? 0;
+      const svnBytes = body.subarray(svnLengthOffset + 1, svnLengthOffset + 1 + svnLength);
+      return {
+        type: "info",
+        requestId,
+        errorCode,
+        version,
+        versionString: version.join("."),
+        svnVersion: parseLittleEndianVariableWidth(svnBytes)
+      };
+    }
+    case 17 /* CheckpointInfo */: {
+      const operation = body[11] ?? 4;
+      const checkpoint = {
+        id: body.readUInt32LE(0),
+        currentlyHit: body[4] === 1,
+        start: body.readUInt16LE(5),
+        end: body.readUInt16LE(7),
+        stopWhenHit: body[9] === 1,
+        enabled: body[10] === 1,
+        kind: cpuOperationToBreakpointKind(operation),
+        temporary: body[12] === 1,
+        hitCount: body.readUInt32LE(13),
+        ignoreCount: body.readUInt32LE(17),
+        hasCondition: body[21] === 1
+      };
+      return { type: "checkpoint_info", requestId, errorCode, checkpoint };
+    }
+    case 20 /* CheckpointList */: {
+      return {
+        type: "checkpoint_list",
+        requestId,
+        errorCode,
+        total: errorCode === 0 /* OK */ ? body.readUInt32LE(0) : 0,
+        checkpoints: []
+      };
+    }
+    case 132 /* DisplayGet */: {
+      const infoLength = errorCode === 0 /* OK */ ? body.readUInt32LE(0) : 0;
+      const imageLength = errorCode === 0 /* OK */ ? body.readUInt32LE(17) : 0;
+      return {
+        type: "display",
+        requestId,
+        errorCode,
+        debugWidth: body.readUInt16LE(4),
+        debugHeight: body.readUInt16LE(6),
+        debugOffsetX: body.readUInt16LE(8),
+        debugOffsetY: body.readUInt16LE(10),
+        innerWidth: body.readUInt16LE(12),
+        innerHeight: body.readUInt16LE(14),
+        bitsPerPixel: body[16] ?? 0,
+        imageBytes: body.subarray(infoLength + 4, infoLength + 4 + imageLength)
+      };
+    }
+    case 145 /* PaletteGet */: {
+      const count = errorCode === 0 /* OK */ ? body.readUInt16LE(0) : 0;
+      let offset = 2;
+      const items = [];
+      for (let index = 0; index < count; index += 1) {
+        const itemSize = body[offset] ?? 0;
+        items.push({
+          index,
+          red: body[offset + 1] ?? 0,
+          green: body[offset + 2] ?? 0,
+          blue: body[offset + 3] ?? 0
+        });
+        offset += itemSize + 1;
+      }
+      return { type: "palette", requestId, errorCode, items };
+    }
+    case 98 /* Stopped */:
+      return { type: "stopped", requestId, errorCode, programCounter: body.readUInt16LE(0) };
+    case 99 /* Resumed */:
+      return { type: "resumed", requestId, errorCode, programCounter: body.readUInt16LE(0) };
+    case 97 /* Jam */:
+      return { type: "jam", requestId, errorCode, programCounter: body.readUInt16LE(0) };
+    case 66 /* Undump */:
+      return { type: "undump", requestId, errorCode, programCounter: body.readUInt16LE(0) };
+    default:
+      return { type: "empty", requestId, errorCode, responseType };
+  }
+}
+var ViceMonitorClient = class extends import_node_events.EventEmitter {
+  #socket = null;
+  #buffer = Buffer.alloc(0);
+  #nextRequestId = 1;
+  #pending = /* @__PURE__ */ new Map();
+  #chain = Promise.resolve();
+  #host = null;
+  #port = null;
+  #runtimeState = {
+    connected: false,
+    runtimeKnown: false,
+    lastEventType: "unknown",
+    programCounter: null
+  };
+  get connected() {
+    return this.#socket != null && !this.#socket.destroyed;
+  }
+  runtimeState() {
+    return { ...this.#runtimeState };
+  }
+  async connect(host2, port2) {
+    if (this.connected && this.#host === host2 && this.#port === port2) {
+      return;
+    }
+    await this.disconnect();
+    this.#host = host2;
+    this.#port = port2;
+    this.#buffer = Buffer.alloc(0);
+    await new Promise((resolve, reject) => {
+      const socket = import_node_net.default.createConnection({ host: host2, port: port2 }, () => {
+        this.#socket = socket;
+        this.#runtimeState = {
+          connected: true,
+          runtimeKnown: false,
+          lastEventType: "unknown",
+          programCounter: null
+        };
+        resolve();
+      });
+      socket.on("data", (chunk) => this.#onData(chunk));
+      socket.on("close", () => this.#onClose());
+      socket.on("error", (error) => {
+        if (!this.#socket) {
+          reject(error);
+          return;
+        }
+        this.emit("transport-error", error);
+      });
+    });
+  }
+  async disconnect() {
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new ViceMcpError("connection_closed", "Emulator debug connection closed", "connection", true));
+    }
+    this.#pending.clear();
+    if (!this.#socket) {
+      return;
+    }
+    const socket = this.#socket;
+    this.#socket = null;
+    this.#runtimeState = {
+      connected: false,
+      runtimeKnown: false,
+      lastEventType: "unknown",
+      programCounter: null
+    };
+    await new Promise((resolve) => {
+      socket.once("close", () => resolve());
+      socket.destroy();
+    });
+  }
+  async ping(timeoutMs = 2e3) {
+    await this.send(129 /* Ping */, Buffer.alloc(0), timeoutMs);
+  }
+  async getInfo() {
+    return this.send(133 /* Info */, Buffer.alloc(0));
+  }
+  async captureDisplay(useVic = true) {
+    return this.send(132 /* DisplayGet */, Buffer.from([useVic ? 1 : 0, 0]));
+  }
+  async getPalette(useVic = true) {
+    return this.send(145 /* PaletteGet */, Buffer.from([useVic ? 1 : 0]));
+  }
+  async getRegistersAvailable() {
+    return this.send(131 /* RegistersAvailable */, Buffer.from([mainMemSpaceToProtocol()]));
+  }
+  async getRegisters() {
+    return this.send(49 /* RegistersGet */, Buffer.from([mainMemSpaceToProtocol()]));
+  }
+  async setRegisters(registers) {
+    const body = Buffer.alloc(3 + registers.length * 4);
+    body[0] = mainMemSpaceToProtocol();
+    body.writeUInt16LE(registers.length, 1);
+    registers.forEach((register, index) => {
+      const offset = 3 + index * 4;
+      body[offset] = 3;
+      body[offset + 1] = register.id;
+      body.writeUInt16LE(register.value, offset + 2);
+    });
+    return this.send(50 /* RegistersSet */, body);
+  }
+  async readMemory(start, end, bankId = 0) {
+    const body = Buffer.alloc(8);
+    body[0] = 0;
+    body.writeUInt16LE(start, 1);
+    body.writeUInt16LE(end, 3);
+    body[5] = mainMemSpaceToProtocol();
+    body.writeUInt16LE(bankId, 6);
+    return this.send(1 /* MemoryGet */, body);
+  }
+  async writeMemory(start, bytes, bankId = 0) {
+    const body = Buffer.alloc(8 + bytes.length);
+    body[0] = 0;
+    body.writeUInt16LE(start, 1);
+    body.writeUInt16LE(start + bytes.length - 1, 3);
+    body[5] = mainMemSpaceToProtocol();
+    body.writeUInt16LE(bankId, 6);
+    Buffer.from(bytes).copy(body, 8);
+    return this.send(2 /* MemorySet */, body);
+  }
+  async continueExecution() {
+    return this.send(170 /* Exit */, Buffer.alloc(0));
+  }
+  async stepInstruction(count = 1, stepOver = false) {
+    const body = Buffer.alloc(3);
+    body[0] = stepOver ? 1 : 0;
+    body.writeUInt16LE(count, 1);
+    return this.send(113 /* AdvanceInstruction */, body);
+  }
+  async stepOut() {
+    return this.send(115 /* ExecuteUntilReturn */, Buffer.alloc(0));
+  }
+  async reset(mode) {
+    const body = Buffer.from([mode === "hard" ? 1 : 0]);
+    return this.send(204 /* Reset */, body);
+  }
+  async setBreakpoint(options) {
+    const body = Buffer.alloc(8);
+    body.writeUInt16LE(options.start, 0);
+    body.writeUInt16LE(options.end ?? options.start, 2);
+    body[4] = options.stopWhenHit === false ? 0 : 1;
+    body[5] = options.enabled === false ? 0 : 1;
+    body[6] = breakpointKindToOperation(options.kind);
+    body[7] = options.temporary ? 1 : 0;
+    const response = await this.send(18 /* CheckpointSet */, body);
+    if (options.condition && response.type === "checkpoint_info") {
+      const conditionBody = Buffer.alloc(5 + options.condition.length);
+      conditionBody.writeUInt32LE(response.checkpoint.id, 0);
+      conditionBody[4] = options.condition.length;
+      conditionBody.write(options.condition, 5, "ascii");
+      await this.send(34 /* ConditionSet */, conditionBody);
+      return {
+        ...response,
+        checkpoint: {
+          ...response.checkpoint,
+          hasCondition: true
+        }
+      };
+    }
+    return response;
+  }
+  async getBreakpoint(id) {
+    const body = Buffer.alloc(4);
+    body.writeUInt32LE(id, 0);
+    return this.send(17 /* CheckpointGet */, body);
+  }
+  async listBreakpoints() {
+    return this.send(20 /* CheckpointList */, Buffer.alloc(0));
+  }
+  async deleteBreakpoint(id) {
+    const body = Buffer.alloc(4);
+    body.writeUInt32LE(id, 0);
+    return this.send(19 /* CheckpointDelete */, body);
+  }
+  async toggleBreakpoint(id, enabled) {
+    const body = Buffer.alloc(5);
+    body.writeUInt32LE(id, 0);
+    body[4] = enabled ? 1 : 0;
+    return this.send(21 /* CheckpointToggle */, body);
+  }
+  async setBreakpointCondition(id, condition) {
+    const conditionBytes = Buffer.from(condition, "ascii");
+    const body = Buffer.alloc(5 + conditionBytes.length);
+    body.writeUInt32LE(id, 0);
+    body[4] = conditionBytes.length;
+    conditionBytes.copy(body, 5);
+    return this.send(34 /* ConditionSet */, body);
+  }
+  async autostartProgram(filename, autoStart, fileIndex = 0) {
+    const body = Buffer.alloc(4 + Buffer.byteLength(filename));
+    body[0] = autoStart ? 1 : 0;
+    body.writeUInt16LE(fileIndex, 1);
+    body[3] = Buffer.byteLength(filename);
+    body.write(filename, 4, "ascii");
+    return this.send(221 /* AutoStart */, body);
+  }
+  async quit() {
+    return this.send(187 /* Quit */, Buffer.alloc(0));
+  }
+  async sendKeys(text) {
+    const encoded = Buffer.from(text, "binary");
+    const body = Buffer.alloc(1 + encoded.length);
+    body[0] = encoded.length;
+    encoded.copy(body, 1);
+    return this.send(114 /* KeyboardFeed */, body);
+  }
+  async setJoyport(port2, value) {
+    const body = Buffer.alloc(4);
+    body.writeUInt16LE(port2, 0);
+    body.writeUInt16LE(value, 2);
+    return this.send(162 /* JoyportSet */, body);
+  }
+  async send(commandType, body, timeoutMs = 5e3) {
+    const next = this.#chain.catch(() => void 0).then(async () => this.#execute(commandType, body, timeoutMs));
+    this.#chain = next.then(
+      () => void 0,
+      () => void 0
+    );
+    return next;
+  }
+  async #execute(commandType, body, timeoutMs) {
+    if (!this.#socket || this.#socket.destroyed) {
+      throw new ViceMcpError("not_connected", "Emulator debug connection is not connected", "connection", true);
+    }
+    const requestId = this.#nextRequestId++;
+    const packet = encodeHeader(commandType, requestId, body);
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(requestId);
+        reject(new ViceMcpError("timeout", `Emulator debug command timed out (0x${commandType.toString(16)})`, "timeout", true));
+      }, timeoutMs);
+      this.#pending.set(requestId, {
+        type: commandType,
+        timer,
+        resolve: (response) => resolve(response),
+        reject,
+        linkedCheckpointInfo: commandType === 20 /* CheckpointList */ ? [] : void 0
+      });
+      this.#socket.write(packet, (error) => {
+        if (error) {
+          clearTimeout(timer);
+          this.#pending.delete(requestId);
+          reject(new ViceMcpError("socket_write_failed", error.message, "connection", true));
+        }
+      });
+    });
+  }
+  #onData(chunk) {
+    this.#buffer = Buffer.concat([this.#buffer, chunk]);
+    const { responses, remainder } = parseBuffer(this.#buffer);
+    this.#buffer = Buffer.from(remainder);
+    for (const response of responses) {
+      this.emit("response", response);
+      if (response.requestId === VICE_BROADCAST_REQUEST_ID) {
+        this.#applyRuntimeResponse(response);
+        this.emit("event", response);
+        continue;
+      }
+      const pending = this.#pending.get(response.requestId);
+      if (!pending) {
+        this.emit("event", response);
+        continue;
+      }
+      if (pending.type === 20 /* CheckpointList */ && response.type === "checkpoint_info") {
+        pending.linkedCheckpointInfo?.push(response);
+        continue;
+      }
+      clearTimeout(pending.timer);
+      this.#pending.delete(response.requestId);
+      if (response.errorCode !== 0 /* OK */) {
+        pending.reject(
+          new ViceMcpError("emulator_protocol_error", `Emulator returned error ${response.errorCode}`, "protocol", false, {
+            commandType: pending.type,
+            requestId: response.requestId,
+            emulatorErrorCode: response.errorCode
+          })
+        );
+        continue;
+      }
+      if (pending.type === 20 /* CheckpointList */ && response.type === "checkpoint_list") {
+        if (!pending.linkedCheckpointInfo) {
+          pending.linkedCheckpointInfo = [];
+        }
+        response.checkpoints = pending.linkedCheckpointInfo.map((entry) => entry.checkpoint);
+      }
+      pending.resolve(response);
+    }
+  }
+  #onClose() {
+    const pendingError = new ViceMcpError("connection_closed", "Emulator debug connection closed", "connection", true);
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(pendingError);
+    }
+    this.#pending.clear();
+    this.#socket = null;
+    this.#runtimeState = {
+      connected: false,
+      runtimeKnown: false,
+      lastEventType: "unknown",
+      programCounter: null
+    };
+    this.emit("close");
+  }
+  #applyRuntimeResponse(response) {
+    switch (response.type) {
+      case "resumed":
+      case "stopped":
+      case "jam":
+        this.#runtimeState = {
+          connected: this.connected,
+          runtimeKnown: true,
+          lastEventType: response.type,
+          programCounter: response.programCounter
+        };
+        break;
+      default:
+        break;
+    }
+  }
+};
+
+// src/session.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function defaultC64Config() {
+  return c64ConfigSchema.parse({});
+}
+async function buildViceLaunchEnv() {
+  const env = { ...process.env };
+  const uid = import_node_os.default.userInfo().uid;
+  const runtimeDir = env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
+  env.XDG_RUNTIME_DIR ||= runtimeDir;
+  if (!env.WAYLAND_DISPLAY) {
+    const waylandDisplay = await firstRuntimeEntry(runtimeDir, /^wayland-\d+$/);
+    if (waylandDisplay) {
+      env.WAYLAND_DISPLAY = waylandDisplay;
+    }
+  }
+  if (!env.XAUTHORITY) {
+    const xauthority = await firstRuntimeEntry(runtimeDir, /^\.mutter-Xwaylandauth\./, true);
+    if (xauthority) {
+      env.XAUTHORITY = xauthority;
+    }
+  }
+  if (!env.DISPLAY) {
+    env.DISPLAY = ":0";
+  }
+  return env;
+}
+async function firstRuntimeEntry(runtimeDir, pattern, returnAbsolutePath = false) {
+  try {
+    const entries = await import_promises.default.readdir(runtimeDir);
+    const match = entries.find((entry) => pattern.test(entry));
+    if (!match) {
+      return null;
+    }
+    return returnAbsolutePath ? import_node_path.default.join(runtimeDir, match) : match;
+  } catch {
+    return null;
+  }
+}
+function makeWarning(message, code = "warning") {
+  return { code, message };
+}
+function lowNibble(value) {
+  return value & 15;
+}
+function decodeVicBankAddress(dd00) {
+  return ((dd00 ^ 3) & 3) * 16384;
+}
+function decodeGraphicsMode(d011, d016) {
+  const extendedColorMode = (d011 & 64) !== 0;
+  const bitmapMode = (d011 & 32) !== 0;
+  const multicolorMode = (d016 & 16) !== 0;
+  let graphicsMode;
+  if (!extendedColorMode && !bitmapMode && !multicolorMode) {
+    graphicsMode = "standard_text";
+  } else if (!extendedColorMode && !bitmapMode && multicolorMode) {
+    graphicsMode = "multicolor_text";
+  } else if (!extendedColorMode && bitmapMode && !multicolorMode) {
+    graphicsMode = "standard_bitmap";
+  } else if (!extendedColorMode && bitmapMode && multicolorMode) {
+    graphicsMode = "multicolor_bitmap";
+  } else if (extendedColorMode && !bitmapMode && !multicolorMode) {
+    graphicsMode = "extended_background_color_text";
+  } else if (extendedColorMode && !bitmapMode && multicolorMode) {
+    graphicsMode = "invalid_text_mode";
+  } else if (extendedColorMode && bitmapMode && !multicolorMode) {
+    graphicsMode = "invalid_bitmap_mode_1";
+  } else {
+    graphicsMode = "invalid_bitmap_mode_2";
+  }
+  return {
+    graphicsMode,
+    extendedColorMode,
+    bitmapMode,
+    multicolorMode
+  };
+}
+function isTextGraphicsMode(graphicsMode) {
+  return graphicsMode === "standard_text" || graphicsMode === "multicolor_text" || graphicsMode === "extended_background_color_text" || graphicsMode === "invalid_text_mode";
+}
+function petsciiToScreenCode(value) {
+  if (value === 255) {
+    return 94;
+  }
+  if (value < 32) {
+    return value ^ 128;
+  }
+  if (value < 96) {
+    return value & 63;
+  }
+  if (value < 128) {
+    return value & 95;
+  }
+  if (value < 160) {
+    return value | 64;
+  }
+  if (value < 192) {
+    return value ^ 192;
+  }
+  if (value < 255) {
+    return value ^ 128;
+  }
+  return 94;
+}
+function decodeScreenCodeCell(code) {
+  if (code === 32 || code === 160) {
+    return { ascii: " ", lossy: false };
+  }
+  if (code >= 1 && code <= 26) {
+    return { ascii: String.fromCharCode(64 + code), lossy: false };
+  }
+  if (code >= 48 && code <= 57) {
+    return { ascii: String.fromCharCode(code), lossy: false };
+  }
+  switch (code) {
+    case 0:
+      return { ascii: "@", lossy: false };
+    case 27:
+      return { ascii: "[", lossy: false };
+    case 28:
+      return { ascii: "\xA3", lossy: false };
+    case 29:
+      return { ascii: "]", lossy: false };
+    case 34:
+      return { ascii: '"', lossy: false };
+    case 35:
+      return { ascii: "#", lossy: false };
+    case 36:
+      return { ascii: "$", lossy: false };
+    case 37:
+      return { ascii: "%", lossy: false };
+    case 38:
+      return { ascii: "&", lossy: false };
+    case 39:
+      return { ascii: "'", lossy: false };
+    case 40:
+      return { ascii: "(", lossy: false };
+    case 41:
+      return { ascii: ")", lossy: false };
+    case 42:
+      return { ascii: "*", lossy: false };
+    case 43:
+      return { ascii: "+", lossy: false };
+    case 44:
+      return { ascii: ",", lossy: false };
+    case 45:
+      return { ascii: "-", lossy: false };
+    case 46:
+      return { ascii: ".", lossy: false };
+    case 47:
+      return { ascii: "/", lossy: false };
+    case 58:
+      return { ascii: ":", lossy: false };
+    case 59:
+      return { ascii: ";", lossy: false };
+    case 60:
+      return { ascii: "\u2191", lossy: false };
+    case 61:
+      return { ascii: "=", lossy: false };
+    case 62:
+      return { ascii: "\u2190", lossy: false };
+    case 63:
+      return { ascii: "?", lossy: false };
+    case 94:
+      return { ascii: "\u03C0", lossy: false };
+    default:
+      return {
+        ascii: "\uFFFD",
+        token: SCREEN_CODE_TOKEN_MAP.get(code) ?? `<SC:${code}>`,
+        lossy: true
+      };
+  }
+}
+function uint32(value) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(value, 0);
+  return buffer;
+}
+var CRC_TABLE = new Uint32Array(256).map((_, index) => {
+  let c = index;
+  for (let k = 0; k < 8; k += 1) {
+    c = (c & 1) === 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  }
+  return c >>> 0;
+});
+function crc32(buffer) {
+  let crc = 4294967295;
+  for (const byte of buffer) {
+    crc = CRC_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function pngChunk(type, data) {
+  const typeBuffer = Buffer.from(type, "ascii");
+  const crc = crc32(Buffer.concat([typeBuffer, data]));
+  return Buffer.concat([uint32(data.length), typeBuffer, data, uint32(crc >>> 0)]);
+}
+function encodePngRgb(width, height, pixels) {
+  const stride = width * 3;
+  const rows = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    const rowOffset = y * (stride + 1);
+    rows[rowOffset] = 0;
+    Buffer.from(pixels.subarray(y * stride, y * stride + stride)).copy(rows, rowOffset + 1);
+  }
+  const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  const chunks = [
+    pngChunk(
+      "IHDR",
+      Buffer.concat([
+        uint32(width),
+        uint32(height),
+        Buffer.from([8, 2, 0, 0, 0])
+      ])
+    ),
+    pngChunk("IDAT", import_node_zlib.default.deflateSync(rows)),
+    pngChunk("IEND", Buffer.alloc(0))
+  ];
+  return Buffer.concat([signature, ...chunks]);
+}
+var PETSCII_TOKEN_DEFINITIONS = [
+  { canonical: "RETURN", bytes: [13], aliases: ["ENTER"] },
+  { canonical: "SHIFT RETURN", bytes: [141], aliases: ["SHIFT ENTER", "SH RETURN", "SH ENTER", "STRET"] },
+  { canonical: "SPACE", bytes: [32], aliases: ["SPC"] },
+  { canonical: "SHIFT SPACE", bytes: [160], aliases: ["SH SPACE"] },
+  { canonical: "HOME", bytes: [19], aliases: ["CURSOR HOME", "CUR HOME"] },
+  { canonical: "CLEAR", bytes: [147], aliases: ["CLR", "CLEAR SCREEN"] },
+  { canonical: "DELETE", bytes: [20], aliases: ["DEL", "BACKSPACE"] },
+  { canonical: "INSERT", bytes: [148], aliases: ["INST", "INS"] },
+  { canonical: "DOWN", bytes: [17], aliases: ["CURSOR DOWN", "CUR DOWN"] },
+  { canonical: "UP", bytes: [145], aliases: ["CURSOR UP", "CUR UP"] },
+  { canonical: "LEFT", bytes: [157], aliases: ["CURSOR LEFT", "CUR LEFT"] },
+  { canonical: "RIGHT", bytes: [29], aliases: ["CURSOR RIGHT", "CUR RIGHT"] },
+  { canonical: "REVERSE ON", bytes: [18], aliases: ["RVS ON", "RVON", "RVRS ON"] },
+  { canonical: "REVERSE OFF", bytes: [146], aliases: ["RVS OFF", "RVOF", "RVRS OFF"] },
+  { canonical: "BLACK", bytes: [144], aliases: ["BLK"] },
+  { canonical: "WHITE", bytes: [5], aliases: ["WHT"] },
+  { canonical: "RED", bytes: [28], aliases: [] },
+  { canonical: "CYAN", bytes: [159], aliases: ["CYN"] },
+  { canonical: "PURPLE", bytes: [156], aliases: ["PUR"] },
+  { canonical: "GREEN", bytes: [30], aliases: ["GRN"] },
+  { canonical: "BLUE", bytes: [31], aliases: ["BLU"] },
+  { canonical: "YELLOW", bytes: [158], aliases: ["YEL"] },
+  { canonical: "ORANGE", bytes: [129], aliases: ["ORNG"] },
+  { canonical: "BROWN", bytes: [149], aliases: ["BRN"] },
+  { canonical: "LIGHT RED", bytes: [150], aliases: ["LRED", "PINK", "LT RED"] },
+  { canonical: "DARK GRAY", bytes: [151], aliases: ["DARK GREY", "GRAY1", "GREY1", "GRY1"] },
+  { canonical: "GRAY", bytes: [152], aliases: ["GREY", "GRAY2", "GREY2", "GRY2", "MEDIUM GRAY", "MEDIUM GREY"] },
+  { canonical: "LIGHT GREEN", bytes: [153], aliases: ["LGRN", "LT GREEN"] },
+  { canonical: "LIGHT BLUE", bytes: [154], aliases: ["LBLU", "LT BLUE"] },
+  { canonical: "LIGHT GRAY", bytes: [155], aliases: ["LIGHT GREY", "GRAY3", "GREY3", "GRY3"] },
+  { canonical: "F1", bytes: [133], aliases: [] },
+  { canonical: "F2", bytes: [137], aliases: [] },
+  { canonical: "F3", bytes: [134], aliases: [] },
+  { canonical: "F4", bytes: [138], aliases: [] },
+  { canonical: "F5", bytes: [135], aliases: [] },
+  { canonical: "F6", bytes: [139], aliases: [] },
+  { canonical: "F7", bytes: [136], aliases: [] },
+  { canonical: "F8", bytes: [140], aliases: [] },
+  { canonical: "STOP", bytes: [3], aliases: ["RUN STOP", "RUNSTOP"] },
+  { canonical: "LOWER", bytes: [14], aliases: ["LOWERCASE", "SWLC"] },
+  { canonical: "UPPER", bytes: [142], aliases: ["UPPERCASE", "SWUC"] },
+  { canonical: "POUND", bytes: [92], aliases: ["GBP", "UK POUND"] },
+  { canonical: "UP ARROW", bytes: [94], aliases: ["ARROW UP"] },
+  { canonical: "LEFT ARROW", bytes: [95], aliases: ["ARROW LEFT", "BACK ARROW"] },
+  { canonical: "PI", bytes: [255], aliases: [] }
+];
+var PETSCII_TOKEN_MAP = /* @__PURE__ */ new Map();
+for (const definition of PETSCII_TOKEN_DEFINITIONS) {
+  PETSCII_TOKEN_MAP.set(definition.canonical, definition);
+  for (const alias of definition.aliases) {
+    PETSCII_TOKEN_MAP.set(alias, definition);
+  }
+}
+var SCREEN_CODE_TOKEN_MAP = /* @__PURE__ */ new Map();
+for (const definition of PETSCII_TOKEN_DEFINITIONS) {
+  for (const byte of definition.bytes) {
+    const screenCode = petsciiToScreenCode(byte);
+    if (!SCREEN_CODE_TOKEN_MAP.has(screenCode)) {
+      SCREEN_CODE_TOKEN_MAP.set(screenCode, `<${definition.canonical}>`);
+    }
+  }
+}
+var DIRECT_PETSCII_CHAR_BYTES = /* @__PURE__ */ new Map([
+  ["\xA3", 92],
+  ["\u2191", 94],
+  ["\u2190", 95],
+  ["\u03C0", 255],
+  ["\u03A0", 255]
+]);
+function normalizePetsciiTokenName(token) {
+  return token.trim().toUpperCase().replace(/[\s_-]+/g, " ");
+}
+function lookupPetsciiToken(token) {
+  const normalized = normalizePetsciiTokenName(token);
+  const definition = PETSCII_TOKEN_MAP.get(normalized);
+  if (!definition) {
+    unsupportedError("Requested keyboard token is not representable through PETSCII keyboard-buffer input.", {
+      token,
+      normalizedToken: normalized
+    });
+  }
+  return definition;
+}
+function encodeLiteralPetsciiChar(char) {
+  if (char === "\n" || char === "\r") {
+    return 13;
+  }
+  if (char === "	") {
+    return 32;
+  }
+  const direct = DIRECT_PETSCII_CHAR_BYTES.get(char);
+  if (direct != null) {
+    return direct;
+  }
+  const code = char.codePointAt(0);
+  if (code == null) {
+    validationError("write_text received an empty character while encoding PETSCII");
+  }
+  if (code >= 97 && code <= 122) {
+    return code - 32;
+  }
+  if (code >= 32 && code <= 93) {
+    return code;
+  }
+  validationError("write_text only supports characters representable in the supported PETSCII subset", {
+    character: char,
+    codePoint: code
+  });
+}
+function decodeWriteTextToPetscii(input) {
+  const bytes = [];
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (char === "\\") {
+      const next = input[index + 1];
+      if (next == null) {
+        validationError("write_text received a trailing backslash escape with no character after it");
+      }
+      switch (next) {
+        case "n":
+          bytes.push(13);
+          break;
+        case "r":
+          bytes.push(13);
+          break;
+        case "t":
+          bytes.push(32);
+          break;
+        case "\\":
+          bytes.push(encodeLiteralPetsciiChar("\\"));
+          break;
+        case '"':
+          bytes.push(encodeLiteralPetsciiChar('"'));
+          break;
+        case "'":
+          bytes.push(encodeLiteralPetsciiChar("'"));
+          break;
+        default:
+          validationError("write_text received an unsupported escape sequence", {
+            escape: `\\${next}`
+          });
+      }
+      index += 1;
+      continue;
+    }
+    if (char === "{") {
+      const end = input.indexOf("}", index + 1);
+      if (end === -1) {
+        validationError("write_text received an opening brace without a closing brace", {
+          position: index
+        });
+      }
+      const rawToken = input.slice(index + 1, end);
+      if (!rawToken.trim()) {
+        validationError("write_text received an empty brace token", {
+          position: index
+        });
+      }
+      const definition = lookupPetsciiToken(rawToken);
+      bytes.push(...definition.bytes);
+      index = end;
+      continue;
+    }
+    bytes.push(encodeLiteralPetsciiChar(char));
+  }
+  return Uint8Array.from(bytes);
+}
+function resolveKeyboardInputKey(key) {
+  const trimmed = key.trim();
+  if (!trimmed) {
+    validationError("keyboard_input requires a non-empty key name");
+  }
+  if (trimmed.length === 1) {
+    return {
+      canonical: normalizePetsciiTokenName(trimmed),
+      bytes: Uint8Array.from([encodeLiteralPetsciiChar(trimmed)])
+    };
+  }
+  const definition = lookupPetsciiToken(trimmed);
+  return {
+    canonical: definition.canonical,
+    bytes: Uint8Array.from(definition.bytes)
+  };
+}
+var JOYSTICK_CONTROL_BITS = {
+  up: 1,
+  down: 2,
+  left: 4,
+  right: 8,
+  fire: 16
+};
+var JOYSTICK_RELEASED_MASK = 31;
+var DEFAULT_INPUT_TAP_MS = 75;
+var DEFAULT_KEYBOARD_REPEAT_MS = 100;
+var VICE_PROCESS_LOG_PATH = import_node_path.default.join(import_node_os.default.tmpdir(), "c64-debug-mcp-x64sc.log");
+var DISPLAY_CAPTURE_DIR = import_node_path.default.resolve(process.cwd(), ".vice-debug-mcp-artifacts");
+var MIRROR_EMULATOR_LOGS_TO_STDERR = /^(1|true|yes|on)$/i.test(process.env.C64_DEBUG_CONSOLE_LOGS ?? "");
+var EXECUTION_EVENT_WAIT_MS = 1e3;
+var EXECUTION_SETTLE_DELAY_MS = 2e3;
+var BOOTSTRAP_INITIAL_DELAY_MS = 2e3;
+var BOOTSTRAP_SETTLE_TIMEOUT_MS = 15e3;
+var BOOTSTRAP_POLL_MS = 250;
+var BOOTSTRAP_RUNNING_STABLE_MS = 3e3;
+var BOOTSTRAP_RESUME_COOLDOWN_MS = 500;
+var PROGRAM_LOAD_SETTLE_TIMEOUT_MS = 15e3;
+var PROGRAM_LOAD_SETTLE_POLL_MS = 250;
+var PROGRAM_LOAD_RUNNING_STABLE_MS = 3e3;
+var PROGRAM_LOAD_RESUME_COOLDOWN_MS = 500;
+var DISPLAY_SETTLE_TIMEOUT_MS = 5e3;
+var DISPLAY_SETTLE_POLL_MS = 100;
+var DISPLAY_PAUSE_TIMEOUT_MS = 5e3;
+var DISPLAY_RUNNING_STABLE_MS = 750;
+var MAX_WRITE_TEXT_BYTES = 64;
+var DISPLAY_RESUME_COOLDOWN_MS = 250;
+var INPUT_SETTLE_TIMEOUT_MS = 5e3;
+var INPUT_SETTLE_POLL_MS = 100;
+var INPUT_RUNNING_STABLE_MS = 750;
+var INPUT_RESUME_COOLDOWN_MS = 250;
+var CHECKPOINT_HIT_SETTLE_MS = 1e3;
+var STOPPED_IDLE_TIMEOUT_MS = 2e4;
+var MIN_TAP_DURATION_MS = 10;
+var MAX_TAP_DURATION_MS = 1e4;
+var RESET_GRACE_PERIOD_MS = 150;
+function clampTapDuration(durationMs) {
+  if (durationMs == null) {
+    return DEFAULT_INPUT_TAP_MS;
+  }
+  if (!Number.isInteger(durationMs)) {
+    validationError("durationMs must be an integer", { durationMs });
+  }
+  return Math.max(MIN_TAP_DURATION_MS, Math.min(MAX_TAP_DURATION_MS, durationMs));
+}
+function joystickPortToProtocol(port2) {
+  return port2 - 1;
+}
+var PortAllocator = class {
+  #forbiddenPorts;
+  constructor(forbiddenPorts) {
+    this.#forbiddenPorts = new Set(forbiddenPorts ?? DEFAULT_FORBIDDEN_PORTS);
+  }
+  get forbiddenPorts() {
+    return [...this.#forbiddenPorts].sort((left, right) => left - right);
+  }
+  assertAllowed(port2) {
+    if (this.#forbiddenPorts.has(port2)) {
+      validationError("Standard/default debug monitor ports are forbidden in managed mode", {
+        port: port2,
+        forbiddenPorts: this.forbiddenPorts
+      });
+    }
+  }
+  async allocate() {
+    for (let attempts = 0; attempts < 30; attempts += 1) {
+      const candidate = await this.#probeEphemeralPort();
+      if (candidate < 1024 || this.#forbiddenPorts.has(candidate)) {
+        continue;
+      }
+      return candidate;
+    }
+    throw new ViceMcpError("port_allocation_failed", "Could not allocate a non-default monitor port", "configuration");
+  }
+  async ensureFree(port2, host2 = DEFAULT_MONITOR_HOST) {
+    this.assertAllowed(port2);
+    const available = await isPortAvailable(host2, port2);
+    if (!available) {
+      throw new ViceMcpError("port_in_use", `Monitor port ${port2} is already in use`, "configuration", false, {
+        host: host2,
+        port: port2
+      });
+    }
+  }
+  async #probeEphemeralPort() {
+    return await new Promise((resolve, reject) => {
+      const server = import_node_net2.default.createServer();
+      server.once("error", reject);
+      server.listen(0, DEFAULT_MONITOR_HOST, () => {
+        const address = server.address();
+        if (address && typeof address === "object") {
+          const port2 = address.port;
+          server.close((error) => {
+            if (error) {
+              reject(error);
+              return;
+            }
+            resolve(port2);
+          });
+          return;
+        }
+        reject(new Error("Failed to allocate port"));
+      });
+    });
+  }
+};
+async function isPortAvailable(host2, port2) {
+  return await new Promise((resolve) => {
+    const socket = import_node_net2.default.connect({ host: host2, port: port2 });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("error", () => resolve(true));
+  });
+}
+var ViceSession = class {
+  #client = new ViceMonitorClient();
+  #portAllocator;
+  #transportState = "not_started";
+  #processState = "not_applicable";
+  #executionState = "unknown";
+  #lastStopReason = "none";
+  #host = null;
+  #port = null;
+  #connectedSince = null;
+  #lastResponseAt = null;
+  #process = null;
+  #processLogStream = null;
+  #stdoutMirrorBuffer = "";
+  #stderrMirrorBuffer = "";
+  #warnings = [];
+  #lastExecutionIntent = "unknown";
+  #lastRegisters = null;
+  #lastRuntimeEventType = "unknown";
+  #lastRuntimeProgramCounter = null;
+  #config = null;
+  #recoveryInProgress = false;
+  #recoveryPromise = null;
+  #freshEmulatorPending = false;
+  #launchId = 0;
+  #restartCount = 0;
+  #suppressRecovery = false;
+  #shuttingDown = false;
+  #heldKeyboardIntervals = /* @__PURE__ */ new Map();
+  #heldJoystickMasks = /* @__PURE__ */ new Map();
+  #breakpointLabels = /* @__PURE__ */ new Map();
+  #stoppedAt = null;
+  #autoResumeTimer = null;
+  #explicitPauseActive = false;
+  #pendingCheckpointHit = null;
+  #lastCheckpointHit = null;
+  #checkpointQueryPending = false;
+  #executionOperationLock = null;
+  #displayOperationLock = null;
+  constructor(portAllocator = new PortAllocator()) {
+    this.#portAllocator = portAllocator;
+    this.#client.on("response", (response) => {
+      this.#lastResponseAt = nowIso();
+      this.#writeProcessLogLine(`[monitor-response] type=${response.type} requestId=${response.requestId} errorCode=${response.errorCode}`);
+    });
+    this.#client.on("close", () => {
+      this.#writeProcessLogLine("[monitor-close] debugger connection closed");
+      if (this.#transportState !== "stopped") {
+        this.#transportState = "disconnected";
+      }
+      this.#syncMonitorRuntimeState();
+      if (!this.#suppressRecovery && !this.#shuttingDown && this.#config) {
+        void this.#scheduleRecovery();
+      }
+    });
+    this.#client.on("event", (event) => {
+      if (event.type === "checkpoint_info" && event.checkpoint.currentlyHit) {
+        this.#pendingCheckpointHit = {
+          id: event.checkpoint.id,
+          kind: event.checkpoint.kind,
+          observedAt: Date.now()
+        };
+      }
+      const programCounter = "programCounter" in event && typeof event.programCounter === "number" ? event.programCounter : null;
+      this.#writeProcessLogLine(
+        `[monitor-event] type=${event.type}${programCounter == null ? "" : ` pc=$${programCounter.toString(16).padStart(4, "0")}`}`
+      );
+      this.#syncMonitorRuntimeState();
+    });
+  }
+  snapshot() {
+    return {
+      transportState: this.#transportState,
+      processState: this.#processState,
+      executionState: this.#executionState,
+      lastStopReason: this.#lastStopReason,
+      idleAutoResumeArmed: this.#autoResumeTimer != null,
+      explicitPauseActive: this.#explicitPauseActive,
+      lastCheckpointId: this.#lastCheckpointHit?.id ?? null,
+      lastCheckpointKind: this.#lastCheckpointHit?.kind ?? null,
+      recoveryInProgress: this.#recoveryInProgress,
+      launchId: this.#launchId,
+      restartCount: this.#restartCount,
+      freshEmulatorPending: this.#freshEmulatorPending,
+      connectedSince: this.#connectedSince,
+      lastResponseAt: this.#lastResponseAt,
+      processId: this.#process?.pid ?? null,
+      warnings: [...this.#warnings]
+    };
+  }
+  async getMonitorState() {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    const runtime = this.#client.runtimeState();
+    return {
+      executionState: this.#executionState,
+      lastStopReason: this.#lastStopReason,
+      runtimeKnown: runtime.runtimeKnown,
+      programCounter: runtime.programCounter
+    };
+  }
+  async getRegisters() {
+    await this.#ensurePausedForDebug("get_registers");
+    return {
+      registers: await this.#readRegisters()
+    };
+  }
+  async shutdown() {
+    if (this.#shuttingDown) {
+      return;
+    }
+    this.#shuttingDown = true;
+    this.#clearIdleAutoResume();
+    this.#suppressRecovery = true;
+    this.#config = null;
+    this.#recoveryPromise = null;
+    this.#recoveryInProgress = false;
+    this.#freshEmulatorPending = false;
+    this.#clearHeldInputState();
+    this.#breakpointLabels.clear();
+    try {
+      await this.#resumeBeforeShutdown();
+      await this.#stopManagedProcess(true);
+    } finally {
+      this.#transportState = "stopped";
+      this.#processState = "not_applicable";
+      this.#executionState = "unknown";
+      this.#lastStopReason = "none";
+      this.#explicitPauseActive = false;
+      this.#pendingCheckpointHit = null;
+      this.#lastCheckpointHit = null;
+      this.#lastRuntimeEventType = "unknown";
+      this.#lastRuntimeProgramCounter = null;
+      this.#host = null;
+      this.#port = null;
+      this.#connectedSince = null;
+      this.#lastRegisters = null;
+    }
+  }
+  takeResponseMeta() {
+    const meta = {
+      freshEmulator: this.#freshEmulatorPending,
+      launchId: this.#launchId,
+      restartCount: this.#restartCount
+    };
+    this.#freshEmulatorPending = false;
+    return meta;
+  }
+  async execute(action, count = 1, resetMode = "soft", waitUntilRunningStable = false) {
+    switch (action) {
+      case "pause":
+        return await this.pauseExecution();
+      case "resume":
+        return await this.continueExecution(waitUntilRunningStable);
+      case "step":
+        return await this.stepInstruction(count, false);
+      case "step_over":
+        return await this.stepInstruction(count, true);
+      case "step_out":
+        return await this.stepOut();
+      case "reset":
+        return await this.resetMachine(resetMode);
+    }
+  }
+  async setRegisters(registers) {
+    await this.#ensurePausedForDebug("set_registers");
+    const metadata = await this.#client.getRegistersAvailable();
+    const metadataByName = new Map(metadata.registers.map((item) => [item.name.toUpperCase(), item]));
+    const payload = Object.entries(registers).map(([fieldName, value]) => {
+      const definition = C64_REGISTER_DEFINITIONS.find((item) => item.fieldName === fieldName);
+      if (!definition) {
+        validationError(`Unknown register ${fieldName}`, { registerName: fieldName });
+      }
+      if (!Number.isInteger(value)) {
+        validationError(`Register ${fieldName} must be an integer`, { registerName: fieldName, value });
+      }
+      if (value < definition.min || value > definition.max) {
+        validationError(`Register ${fieldName} must be between ${definition.min} and ${definition.max}`, {
+          registerName: fieldName,
+          min: definition.min,
+          max: definition.max,
+          value
+        });
+      }
+      const meta = metadataByName.get(definition.viceName.toUpperCase());
+      if (!meta) {
+        validationError(`Required C64 register is missing from the emulator: ${definition.viceName}`, {
+          registerName: definition.fieldName,
+          viceName: definition.viceName
+        });
+      }
+      return {
+        id: meta.id,
+        value
+      };
+    });
+    const response = await this.#client.setRegisters(payload);
+    const updatedById = new Map(response.registers.map((register) => [register.id, register.value]));
+    this.#lastRegisters = this.#mergeRegisters(
+      this.#lastRegisters,
+      Object.fromEntries(
+        C64_REGISTER_DEFINITIONS.flatMap((definition) => {
+          const meta = metadataByName.get(definition.viceName.toUpperCase());
+          if (!meta) {
+            return [];
+          }
+          const value = updatedById.get(meta.id);
+          if (value == null) {
+            return [];
+          }
+          return [[definition.fieldName, value]];
+        })
+      )
+    );
+    return {
+      updated: Object.fromEntries(
+        C64_REGISTER_DEFINITIONS.flatMap((definition) => {
+          const meta = metadataByName.get(definition.viceName.toUpperCase());
+          if (!meta) {
+            return [];
+          }
+          const value = updatedById.get(meta.id);
+          if (value == null) {
+            return [];
+          }
+          return [[definition.fieldName, value]];
+        })
+      ),
+      executionState: this.#executionState
+    };
+  }
+  async readMemory(start, end, bank = 0) {
+    await this.#ensurePausedForDebug("memory_read");
+    this.#validateRange(start, end);
+    const response = await this.#client.readMemory(start, end, bank);
+    return {
+      length: response.bytes.length,
+      data: Array.from(response.bytes)
+    };
+  }
+  async writeMemory(start, data, bank = 0) {
+    await this.#ensurePausedForDebug("memory_write");
+    const bytes = Uint8Array.from(data);
+    if (bytes.length === 0) {
+      validationError("write_memory requires at least one byte");
+    }
+    if (data.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) {
+      validationError("write_memory data must contain only integer byte values between 0 and 255");
+    }
+    await this.#client.writeMemory(start, bytes, bank);
+    const debugState = await this.#readDebugState();
+    return {
+      address: start,
+      length: bytes.length,
+      worked: true,
+      executionState: debugState.executionState,
+      lastStopReason: debugState.lastStopReason,
+      programCounter: debugState.programCounter,
+      registers: debugState.registers
+    };
+  }
+  async pauseExecution() {
+    return this.#withExecutionLock(async () => {
+      await this.#ensureReady();
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "stopped") {
+        this.#explicitPauseActive = true;
+        const debugState2 = await this.#readDebugState();
+        return {
+          executionState: debugState2.executionState,
+          lastStopReason: debugState2.lastStopReason,
+          programCounter: debugState2.programCounter,
+          registers: debugState2.registers,
+          warnings: []
+        };
+      }
+      if (this.#executionState !== "running") {
+        emulatorNotRunningError("execute pause", {
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason
+        });
+      }
+      this.#explicitPauseActive = true;
+      this.#lastExecutionIntent = "monitor_entry";
+      this.#writeProcessLogLine("[tx] execute pause");
+      await this.#client.ping();
+      const paused = await this.waitForState("stopped", 5e3, 0);
+      if (!paused.reachedTarget) {
+        throw new ViceMcpError("pause_timeout", "execute pause could not reach a stopped state before timeout.", "timeout", true, {
+          executionState: paused.executionState,
+          lastStopReason: paused.lastStopReason
+        });
+      }
+      const debugState = await this.#readDebugState();
+      return {
+        executionState: debugState.executionState,
+        lastStopReason: debugState.lastStopReason,
+        programCounter: debugState.programCounter,
+        registers: debugState.registers,
+        warnings: []
+      };
+    });
+  }
+  async continueExecution(waitUntilRunningStable = false) {
+    return this.#withExecutionLock(async () => {
+      await this.#ensureReady();
+      if (this.#executionState !== "stopped") {
+        debuggerNotPausedError("execute resume", {
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason
+        });
+      }
+      const debugState = this.#lastRegisters == null ? await this.#readDebugState() : this.#buildDebugState(this.#lastRegisters);
+      this.#lastExecutionIntent = "unknown";
+      this.#writeProcessLogLine("[tx] execute resume");
+      const executionEvent = this.#waitForExecutionEvent(1e3);
+      await this.#client.continueExecution();
+      const event = await executionEvent;
+      if (!event || event.type !== "resumed") {
+        this.#writeProcessLogLine(`[execute-resume] no resumed event within 1000ms (got ${event?.type ?? "nothing"})`);
+      }
+      if (waitUntilRunningStable) {
+        await this.waitForState("running", 5e3, INPUT_RUNNING_STABLE_MS);
+      } else {
+        this.#syncMonitorRuntimeState();
+      }
+      this.#explicitPauseActive = false;
+      const runtime = this.#client.runtimeState();
+      const warnings = [];
+      const currentExecutionState = this.#executionState;
+      if (!waitUntilRunningStable && currentExecutionState !== "running") {
+        warnings.push(
+          makeWarning("Resume acknowledged but state transition not yet confirmed; use wait_for_state for authoritative state.", "resume_async")
+        );
+      }
+      return {
+        executionState: currentExecutionState,
+        lastStopReason: this.#lastStopReason,
+        programCounter: runtime.programCounter ?? debugState.programCounter,
+        registers: debugState.registers,
+        warnings
+      };
+    });
+  }
+  async stepInstruction(count = 1, stepOver = false) {
+    await this.#ensurePausedForDebug(stepOver ? "execute step_over" : "execute step");
+    this.#lastExecutionIntent = "step_complete";
+    this.#writeProcessLogLine(`[tx] ${stepOver ? "execute step_over" : "execute step"} count=${count}`);
+    await this.#client.stepInstruction(count, stepOver);
+    this.#syncMonitorRuntimeState();
+    const debugState = await this.#readDebugState();
+    return {
+      executionState: debugState.executionState,
+      lastStopReason: debugState.lastStopReason,
+      programCounter: debugState.programCounter,
+      registers: debugState.registers,
+      stepsExecuted: count,
+      warnings: []
+    };
+  }
+  async stepOut() {
+    await this.#ensurePausedForDebug("execute step_out");
+    this.#lastExecutionIntent = "step_complete";
+    this.#writeProcessLogLine("[tx] execute step_out");
+    await this.#client.stepOut();
+    this.#syncMonitorRuntimeState();
+    const debugState = await this.#readDebugState();
+    return {
+      executionState: debugState.executionState,
+      lastStopReason: debugState.lastStopReason,
+      programCounter: debugState.programCounter,
+      registers: debugState.registers,
+      warnings: []
+    };
+  }
+  async resetMachine(mode) {
+    return this.#withExecutionLock(async () => {
+      await this.#ensureReady();
+      const wasPaused = this.#explicitPauseActive;
+      this.#lastExecutionIntent = "reset";
+      this.#writeProcessLogLine(`[tx] execute reset mode=${mode}`);
+      await this.#client.reset(mode);
+      await sleep(RESET_GRACE_PERIOD_MS);
+      this.#explicitPauseActive = wasPaused;
+      this.#syncMonitorRuntimeState();
+      await sleep(50);
+      this.#syncMonitorRuntimeState();
+      const debugState = await this.#readDebugState();
+      return {
+        executionState: debugState.executionState,
+        lastStopReason: debugState.lastStopReason,
+        programCounter: debugState.programCounter,
+        registers: debugState.registers,
+        warnings: []
+      };
+    });
+  }
+  async listBreakpoints(includeDisabled = true) {
+    await this.#ensureReady();
+    this.#writeProcessLogLine(`[tx] breakpoint_list includeDisabled=${includeDisabled}`);
+    const response = await this.#client.listBreakpoints();
+    this.#pruneBreakpointLabels(response.checkpoints.map((breakpoint) => breakpoint.id));
+    return {
+      breakpoints: response.checkpoints.filter((breakpoint) => includeDisabled ? true : breakpoint.enabled).map((breakpoint) => this.#attachBreakpointLabel(breakpoint))
+    };
+  }
+  async setBreakpoint(options) {
+    await this.#ensureReady();
+    this.#writeProcessLogLine(
+      `[tx] breakpoint_set kind=${options.kind} start=$${options.start.toString(16).padStart(4, "0")}${options.end == null ? "" : ` end=$${options.end.toString(16).padStart(4, "0")}`}${options.temporary ? " temporary=true" : ""}${options.enabled === false ? " enabled=false" : ""}`
+    );
+    const response = await this.#client.setBreakpoint({
+      start: options.start,
+      end: options.end,
+      kind: options.kind,
+      condition: options.condition,
+      temporary: options.temporary,
+      enabled: options.enabled,
+      stopWhenHit: true
+    });
+    if (options.label?.trim()) {
+      this.#breakpointLabels.set(response.checkpoint.id, options.label.trim());
+    } else {
+      this.#breakpointLabels.delete(response.checkpoint.id);
+    }
+    return {
+      breakpoint: this.#attachBreakpointLabel(response.checkpoint),
+      executionState: this.#executionState,
+      lastStopReason: this.#lastStopReason,
+      programCounter: this.#lastRegisters?.PC ?? null,
+      registers: this.#lastRegisters
+    };
+  }
+  async deleteBreakpoint(breakpointId) {
+    await this.#ensureReady();
+    this.#writeProcessLogLine(`[tx] breakpoint_clear id=${breakpointId}`);
+    try {
+      await this.#client.deleteBreakpoint(breakpointId);
+    } catch (error) {
+      if (error instanceof ViceMcpError && error.code === "emulator_protocol_error" && error.details?.emulatorErrorCode === 1) {
+        return {
+          cleared: false,
+          breakpointId,
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason,
+          programCounter: this.#lastRegisters?.PC ?? null,
+          registers: this.#lastRegisters
+        };
+      }
+      throw error;
+    }
+    this.#breakpointLabels.delete(breakpointId);
+    return {
+      cleared: true,
+      breakpointId,
+      executionState: this.#executionState,
+      lastStopReason: this.#lastStopReason,
+      programCounter: this.#lastRegisters?.PC ?? null,
+      registers: this.#lastRegisters
+    };
+  }
+  async breakpointSet(options) {
+    const length = options.length ?? 1;
+    if (!Number.isInteger(length) || length <= 0) {
+      validationError("Breakpoint length must be a positive integer", { length });
+    }
+    const end = options.address + length - 1;
+    this.#validateRange(options.address, end);
+    return await this.setBreakpoint({
+      kind: options.kind,
+      start: options.address,
+      end,
+      condition: options.condition,
+      label: options.label,
+      temporary: options.temporary,
+      enabled: options.enabled
+    });
+  }
+  async breakpointClear(breakpointId) {
+    return await this.deleteBreakpoint(breakpointId);
+  }
+  async programLoad(options) {
+    const filePath = import_node_path.default.resolve(options.filePath);
+    await this.#assertReadableProgramFile(filePath);
+    await this.#ensureRunning("program_load");
+    this.#explicitPauseActive = false;
+    const result = await this.autostartProgram(filePath, options.autoStart ?? true, options.fileIndex ?? 0);
+    return {
+      filePath: result.filePath,
+      autoStart: result.autoStart,
+      fileIndex: result.fileIndex,
+      executionState: result.executionState
+    };
+  }
+  async captureDisplay(useVic = true) {
+    return this.#withDisplayLock(async () => {
+      await this.#ensureReady();
+      this.#syncMonitorRuntimeState();
+      const previousExecutionState = this.#executionState;
+      this.#writeProcessLogLine(`[tx] capture_display useVic=${useVic}`);
+      const display = await this.#client.captureDisplay(useVic);
+      const palette = await this.#client.getPalette(useVic);
+      if (display.bitsPerPixel !== 8) {
+        throw new ViceMcpError(
+          "display_bpp_unsupported",
+          `capture_display only supports 8-bit indexed display payloads, got ${display.bitsPerPixel}.`,
+          "unsupported",
+          false,
+          { bitsPerPixel: display.bitsPerPixel }
+        );
+      }
+      const expectedLength = display.debugWidth * display.debugHeight;
+      if (display.imageBytes.length !== expectedLength) {
+        throw new ViceMcpError(
+          "display_payload_invalid",
+          "capture_display received a display payload whose length does not match the reported debug dimensions.",
+          "protocol",
+          false,
+          {
+            debugWidth: display.debugWidth,
+            debugHeight: display.debugHeight,
+            expectedLength,
+            actualLength: display.imageBytes.length
+          }
+        );
+      }
+      if (palette.items.length === 0) {
+        throw new ViceMcpError("display_palette_missing", "capture_display received an empty display palette.", "protocol", false);
+      }
+      if (display.debugOffsetX + display.innerWidth > display.debugWidth || display.debugOffsetY + display.innerHeight > display.debugHeight) {
+        throw new ViceMcpError(
+          "display_crop_invalid",
+          "capture_display received crop geometry outside the display buffer bounds.",
+          "protocol",
+          false,
+          {
+            debugWidth: display.debugWidth,
+            debugHeight: display.debugHeight,
+            debugOffsetX: display.debugOffsetX,
+            debugOffsetY: display.debugOffsetY,
+            innerWidth: display.innerWidth,
+            innerHeight: display.innerHeight
+          }
+        );
+      }
+      const rgbPixels = new Uint8Array(display.innerWidth * display.innerHeight * 3);
+      for (let y = 0; y < display.innerHeight; y += 1) {
+        for (let x = 0; x < display.innerWidth; x += 1) {
+          const sourceX = display.debugOffsetX + x;
+          const sourceY = display.debugOffsetY + y;
+          const sourceIndex = sourceY * display.debugWidth + sourceX;
+          const paletteIndex = display.imageBytes[sourceIndex];
+          const color = palette.items[paletteIndex];
+          if (!color) {
+            throw new ViceMcpError(
+              "display_palette_index_invalid",
+              "capture_display encountered a pixel index that is outside the current palette.",
+              "protocol",
+              false,
+              { paletteIndex, paletteSize: palette.items.length }
+            );
+          }
+          const targetIndex = (y * display.innerWidth + x) * 3;
+          rgbPixels[targetIndex] = color.red;
+          rgbPixels[targetIndex + 1] = color.green;
+          rgbPixels[targetIndex + 2] = color.blue;
+        }
+      }
+      await import_promises.default.mkdir(DISPLAY_CAPTURE_DIR, { recursive: true });
+      const imagePath = import_node_path.default.join(DISPLAY_CAPTURE_DIR, `capture-${Date.now()}-${process.pid}.png`);
+      await import_promises.default.writeFile(imagePath, encodePngRgb(display.innerWidth, display.innerHeight, rgbPixels));
+      await this.#settleDisplayToolState("capture_display", previousExecutionState);
+      return {
+        imagePath,
+        width: display.innerWidth,
+        height: display.innerHeight,
+        debugWidth: display.debugWidth,
+        debugHeight: display.debugHeight,
+        debugOffsetX: display.debugOffsetX,
+        debugOffsetY: display.debugOffsetY,
+        bitsPerPixel: display.bitsPerPixel
+      };
+    });
+  }
+  async getDisplayState() {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    const previousExecutionState = this.#executionState;
+    await this.#pauseForDisplayInspection("get_display_state", previousExecutionState);
+    try {
+      this.#writeProcessLogLine("[tx] get_display_state");
+      const vicPrimary = await this.#client.readMemory(53265, 53272, 0);
+      const cia2Bank = await this.#client.readMemory(56576, 56576, 0);
+      const colors = await this.#client.readMemory(53280, 53284, 0);
+      const d011 = vicPrimary.bytes[0] ?? 0;
+      const d016 = vicPrimary.bytes[5] ?? 0;
+      const d018 = vicPrimary.bytes[7] ?? 0;
+      const dd00 = cia2Bank.bytes[0] ?? 0;
+      const d020 = colors.bytes[0] ?? 0;
+      const d021 = colors.bytes[1] ?? 0;
+      const d022 = colors.bytes[2] ?? 0;
+      const d023 = colors.bytes[3] ?? 0;
+      const d024 = colors.bytes[4] ?? 0;
+      const vicBankAddress = decodeVicBankAddress(dd00);
+      const screenRamAddress = vicBankAddress + (d018 >> 4 & 15) * 1024;
+      const characterMemoryAddress = vicBankAddress + (d018 >> 1 & 7) * 2048;
+      const bitmapMemoryAddress = vicBankAddress + (d018 >> 3 & 1) * 8192;
+      const { graphicsMode, extendedColorMode, bitmapMode, multicolorMode } = decodeGraphicsMode(d011, d016);
+      const screenRam = await this.#client.readMemory(screenRamAddress, screenRamAddress + 999, 0);
+      const colorRam = await this.#client.readMemory(55296, 55296 + 999, 0);
+      return {
+        graphicsMode,
+        extendedColorMode,
+        bitmapMode,
+        multicolorMode,
+        vicBankAddress,
+        screenRamAddress,
+        characterMemoryAddress: bitmapMode ? null : characterMemoryAddress,
+        bitmapMemoryAddress: bitmapMode ? bitmapMemoryAddress : null,
+        colorRamAddress: 55296,
+        borderColor: lowNibble(d020),
+        backgroundColor0: lowNibble(d021),
+        backgroundColor1: lowNibble(d022),
+        backgroundColor2: lowNibble(d023),
+        backgroundColor3: lowNibble(d024),
+        vicRegisters: {
+          d011,
+          d016,
+          d018,
+          dd00,
+          d020,
+          d021,
+          d022,
+          d023,
+          d024
+        },
+        screenRam: Array.from(screenRam.bytes),
+        colorRam: Array.from(colorRam.bytes, (value) => lowNibble(value))
+      };
+    } finally {
+      await this.#settleDisplayToolState("get_display_state", previousExecutionState);
+    }
+  }
+  async getDisplayText() {
+    let displayState = await this.getDisplayState();
+    if (displayState.screenRamAddress === 0 && displayState.graphicsMode === "standard_text") {
+      this.#writeProcessLogLine("[display] screen RAM address still zero in text mode, retrying display state after short settle");
+      await sleep(250);
+      displayState = await this.getDisplayState();
+    }
+    if (!isTextGraphicsMode(displayState.graphicsMode)) {
+      unsupportedError("get_display_text is only available when the current graphics mode is a text mode.", {
+        graphicsMode: displayState.graphicsMode
+      });
+    }
+    const columns = 40;
+    const rows = 25;
+    let hasDetailedTokens = false;
+    const textLines = Array.from({ length: rows }, (_, row) => {
+      const start = row * columns;
+      return displayState.screenRam.slice(start, start + columns).map((code) => {
+        const decoded = decodeScreenCodeCell(code);
+        hasDetailedTokens ||= decoded.lossy;
+        return decoded.ascii;
+      }).join("").replace(/\s+$/, "");
+    });
+    const tokenLines = hasDetailedTokens ? Array.from({ length: rows }, (_, row) => {
+      const start = row * columns;
+      return displayState.screenRam.slice(start, start + columns).map((code) => {
+        const decoded = decodeScreenCodeCell(code);
+        return decoded.token ?? decoded.ascii;
+      }).join("").replace(/\s+$/, "");
+    }) : void 0;
+    return {
+      graphicsMode: displayState.graphicsMode,
+      textMode: true,
+      lossy: hasDetailedTokens,
+      columns,
+      rows,
+      screenRamAddress: displayState.screenRamAddress,
+      textLines,
+      ...tokenLines ? { tokenLines } : {}
+    };
+  }
+  async autostartProgram(filePath, autoStart = true, fileIndex = 0) {
+    await this.#ensureReady();
+    const absolutePath = import_node_path.default.resolve(filePath);
+    const previousExecutionState = this.#executionState;
+    const previousStopReason = this.#lastStopReason;
+    const executionEvent = this.#waitForExecutionEvent(EXECUTION_EVENT_WAIT_MS);
+    this.#lastExecutionIntent = autoStart ? "none" : "monitor_entry";
+    try {
+      this.#writeProcessLogLine(`[tx] program_load filePath=${absolutePath} autoStart=${autoStart} fileIndex=${fileIndex}`);
+      await this.#client.autostartProgram(absolutePath, autoStart, fileIndex);
+    } catch (error) {
+      const event2 = await executionEvent;
+      const accepted = this.#autostartWasAcceptedAfterError(error, event2, previousExecutionState, previousStopReason);
+      if (!accepted) {
+        throw error;
+      }
+    }
+    const event = await executionEvent;
+    if (event) {
+    } else {
+      this.#writeProcessLogLine(
+        `[autostart] no runtime event observed within ${EXECUTION_EVENT_WAIT_MS}ms, waiting ${EXECUTION_SETTLE_DELAY_MS}ms for emulator settle`
+      );
+      await sleep(EXECUTION_SETTLE_DELAY_MS);
+    }
+    await this.#settleProgramLoadState(autoStart);
+    return {
+      filePath: absolutePath,
+      autoStart,
+      fileIndex,
+      executionState: this.#executionState
+    };
+  }
+  async #assertReadableProgramFile(filePath) {
+    let stats;
+    try {
+      await import_promises.default.access(filePath);
+      stats = await import_promises.default.stat(filePath);
+    } catch (error) {
+      throw new ViceMcpError("program_file_missing", `Program file does not exist or is not readable: ${filePath}`, "io", false, {
+        filePath,
+        cause: error instanceof Error ? error.message : String(error)
+      });
+    }
+    if (!stats.isFile()) {
+      throw new ViceMcpError("program_file_invalid", `Program path is not a regular file: ${filePath}`, "io", false, {
+        filePath
+      });
+    }
+  }
+  async writeText(text) {
+    await this.#ensureRunning("write_text");
+    const encoded = decodeWriteTextToPetscii(text);
+    if (encoded.length > MAX_WRITE_TEXT_BYTES) {
+      validationError("write_text exceeds the maximum allowed byte length for one request", {
+        length: encoded.length,
+        max: MAX_WRITE_TEXT_BYTES
+      });
+    }
+    this.#writeProcessLogLine(`[tx] write_text length=${encoded.length} text=${JSON.stringify(text)}`);
+    await this.#client.sendKeys(Buffer.from(encoded).toString("binary"));
+    await this.#settleInputState("write_text", "running");
+    return {
+      sent: true,
+      length: encoded.length
+    };
+  }
+  async keyboardInput(action, keys, durationMs) {
+    await this.#ensureRunning("keyboard_input");
+    if (!Array.isArray(keys) || keys.length === 0 || keys.length > 4) {
+      validationError("keyboard_input requires between 1 and 4 keys", { keys });
+    }
+    const resolvedKeys = keys.map((key) => resolveKeyboardInputKey(key));
+    const normalizedKeys = resolvedKeys.map((key) => key.canonical);
+    this.#writeProcessLogLine(
+      `[tx] keyboard_input action=${action} keys=${normalizedKeys.join(",")}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
+    );
+    switch (action) {
+      case "tap": {
+        const duration = clampTapDuration(durationMs);
+        const bytes = Uint8Array.from(resolvedKeys.flatMap((key) => Array.from(key.bytes)));
+        await this.#client.sendKeys(Buffer.from(bytes).toString("binary"));
+        await this.#settleInputState("keyboard_input", "running");
+        await sleep(duration);
+        return {
+          action,
+          keys: normalizedKeys,
+          applied: true,
+          held: false,
+          mode: "buffered_text"
+        };
+      }
+      case "press": {
+        const singleByteKeys = resolvedKeys.map((key) => {
+          if (key.bytes.length !== 1) {
+            unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
+              key: key.canonical
+            });
+          }
+          return key.bytes[0];
+        });
+        for (let index = 0; index < normalizedKeys.length; index += 1) {
+          const heldKey = normalizedKeys[index];
+          const byte = singleByteKeys[index];
+          if (!this.#heldKeyboardIntervals.has(heldKey)) {
+            await this.#client.sendKeys(Buffer.from([byte]).toString("binary"));
+            await this.#settleInputState("keyboard_input", "running");
+            const interval = setInterval(() => {
+              void this.#client.sendKeys(Buffer.from([byte]).toString("binary")).then(() => this.#settleInputState("keyboard_input", "running")).catch(() => void 0);
+            }, DEFAULT_KEYBOARD_REPEAT_MS);
+            this.#heldKeyboardIntervals.set(heldKey, interval);
+          }
+        }
+        return {
+          action,
+          keys: normalizedKeys,
+          applied: true,
+          held: true,
+          mode: "buffered_text_repeat"
+        };
+      }
+      case "release": {
+        for (const key of resolvedKeys) {
+          if (key.bytes.length !== 1) {
+            unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
+              key: key.canonical
+            });
+          }
+        }
+        for (const heldKey of normalizedKeys) {
+          const interval = this.#heldKeyboardIntervals.get(heldKey);
+          if (interval) {
+            clearInterval(interval);
+            this.#heldKeyboardIntervals.delete(heldKey);
+          }
+        }
+        return {
+          action,
+          keys: normalizedKeys,
+          applied: true,
+          held: false,
+          mode: "buffered_text_repeat"
+        };
+      }
+    }
+  }
+  async joystickInput(port2, action, control, durationMs) {
+    await this.#ensureRunning("joystick_input");
+    const previousExecutionState = this.#executionState;
+    const bit = JOYSTICK_CONTROL_BITS[control];
+    if (bit == null) {
+      validationError("Unsupported joystick control", { control });
+    }
+    this.#writeProcessLogLine(
+      `[tx] joystick_input port=${port2} action=${action} control=${control}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
+    );
+    switch (action) {
+      case "tap": {
+        const duration = clampTapDuration(durationMs);
+        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
+        await sleep(duration);
+        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
+        break;
+      }
+      case "press":
+        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
+        break;
+      case "release":
+        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
+        break;
+    }
+    await this.#settleInputState("joystick_input", previousExecutionState);
+    return {
+      port: port2,
+      action,
+      control,
+      applied: true,
+      state: this.#describeJoystickState(port2)
+    };
+  }
+  async waitForState(targetState, timeoutMs = 5e3, stableMs = targetState === "running" ? INPUT_RUNNING_STABLE_MS : 0) {
+    await this.#ensureReady();
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    let matchingSince = null;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === targetState) {
+        matchingSince ??= Date.now();
+        if (Date.now() - matchingSince >= stableMs) {
+          const runtime = this.#client.runtimeState();
+          return {
+            executionState: this.#executionState,
+            lastStopReason: this.#lastStopReason,
+            runtimeKnown: runtime.runtimeKnown,
+            programCounter: runtime.programCounter,
+            reachedTarget: true,
+            waitedMs: Date.now() - startedAt
+          };
+        }
+      } else {
+        matchingSince = null;
+      }
+      if (Date.now() >= deadline) {
+        const runtime = this.#client.runtimeState();
+        return {
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason,
+          runtimeKnown: runtime.runtimeKnown,
+          programCounter: runtime.programCounter,
+          reachedTarget: false,
+          waitedMs: Date.now() - startedAt
+        };
+      }
+      await sleep(INPUT_SETTLE_POLL_MS);
+    }
+  }
+  async #ensureReady() {
+    this.#ensureConfig();
+    await this.#ensureHealthyConnection();
+  }
+  async #ensurePausedForDebug(commandName) {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    if (this.#executionState !== "stopped") {
+      debuggerNotPausedError(commandName, {
+        executionState: this.#executionState,
+        lastStopReason: this.#lastStopReason
+      });
+    }
+  }
+  async #ensureRunning(commandName) {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    if (this.#executionState !== "running") {
+      emulatorNotRunningError(commandName, {
+        executionState: this.#executionState,
+        lastStopReason: this.#lastStopReason
+      });
+    }
+  }
+  async #ensureHealthyConnection() {
+    if (this.#recoveryPromise) {
+      await this.#recoveryPromise;
+    }
+    const processAlive = this.#process != null && this.#process.exitCode == null && !this.#process.killed;
+    if (processAlive && this.#client.connected) {
+      this.#syncMonitorRuntimeState();
+      return;
+    }
+    await this.#scheduleRecovery();
+  }
+  async #scheduleRecovery() {
+    this.#ensureConfig();
+    if (this.#recoveryPromise) {
+      return await this.#recoveryPromise;
+    }
+    this.#recoveryPromise = (async () => {
+      this.#recoveryInProgress = true;
+      try {
+        const processAlive = this.#process != null && this.#process.exitCode == null && !this.#process.killed;
+        if (processAlive && this.#host && this.#port) {
+          this.#transportState = "reconnecting";
+          await this.#client.connect(this.#host, this.#port);
+          this.#transportState = "connected";
+          if (!this.#connectedSince) {
+            this.#connectedSince = nowIso();
+          }
+          await this.#hydrateExecutionState();
+          return;
+        }
+        await this.#launchManagedEmulator("restart");
+      } finally {
+        this.#recoveryInProgress = false;
+        this.#recoveryPromise = null;
+      }
+    })();
+    return await this.#recoveryPromise;
+  }
+  async #replaceManagedEmulator(mode) {
+    await this.#stopManagedProcess(true);
+    await this.#launchManagedEmulator(mode);
+  }
+  async #launchManagedEmulator(mode) {
+    const config = this.#ensureConfig();
+    const host2 = DEFAULT_MONITOR_HOST;
+    const port2 = await this.#portAllocator.allocate();
+    await this.#portAllocator.ensureFree(port2, host2);
+    const binary = config.binaryPath ?? DEFAULT_C64_BINARY;
+    const args = ["-autostartprgmode", "1", "-binarymonitor", "-binarymonitoraddress", `${host2}:${port2}`];
+    if (config.arguments) {
+      args.push(...splitCommandLine(config.arguments));
+    }
+    this.#transportState = "starting";
+    this.#processState = "launching";
+    this.#host = host2;
+    this.#port = port2;
+    this.#connectedSince = null;
+    this.#executionState = "unknown";
+    this.#breakpointLabels.clear();
+    this.#explicitPauseActive = false;
+    this.#pendingCheckpointHit = null;
+    this.#lastCheckpointHit = null;
+    this.#lastRuntimeEventType = "unknown";
+    this.#lastRuntimeProgramCounter = null;
+    const env = await buildViceLaunchEnv();
+    const child = (0, import_node_child_process.spawn)(binary, args, {
+      cwd: config.workingDirectory ? import_node_path.default.resolve(config.workingDirectory) : void 0,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    this.#process = child;
+    this.#attachProcessLogging(child, binary, args);
+    this.#bindProcessLifecycle(child);
+    this.#processState = "running";
+    this.#transportState = "waiting_for_monitor";
+    try {
+      await waitForMonitor(host2, port2, 5e3);
+      await this.#client.connect(host2, port2);
+      this.#transportState = "connected";
+      this.#connectedSince = nowIso();
+      this.#launchId += 1;
+      if (mode === "restart") {
+        this.#restartCount += 1;
+      }
+      this.#freshEmulatorPending = true;
+      await this.#hydrateExecutionState();
+    } catch (error) {
+      this.#processState = "crashed";
+      this.#transportState = "faulted";
+      this.#warnings = [...this.#warnings.filter((warning) => warning.code !== "launch_failed"), makeWarning(String(error.message ?? error), "launch_failed")];
+      await this.#stopManagedProcess(true);
+      throw error;
+    }
+  }
+  #ensureConfig() {
+    if (!this.#config) {
+      this.#config = defaultC64Config();
+    }
+    return this.#config;
+  }
+  #bindProcessLifecycle(child) {
+    child.once("exit", (code, signal) => {
+      if (this.#process !== child) {
+        return;
+      }
+      this.#closeProcessLog(child, `process exit (${code ?? "null"} / ${signal ?? "null"})`);
+      this.#process = null;
+      this.#processState = code === 0 ? "exited" : "crashed";
+      this.#transportState = "disconnected";
+      this.#warnings = [
+        ...this.#warnings.filter((warning) => warning.code !== "process_exit"),
+        makeWarning(`C64 emulator process exited (${code ?? "null"} / ${signal ?? "null"})`, "process_exit")
+      ];
+      if (!this.#suppressRecovery && !this.#shuttingDown && this.#config) {
+        void this.#scheduleRecovery();
+      }
+    });
+    child.once("error", (error) => {
+      if (this.#process !== child) {
+        return;
+      }
+      this.#closeProcessLog(child, `process error (${error.message})`);
+      this.#process = null;
+      this.#processState = "crashed";
+      this.#transportState = "faulted";
+      this.#warnings = [...this.#warnings.filter((warning) => warning.code !== "process_error"), makeWarning(error.message, "process_error")];
+      if (!this.#suppressRecovery && !this.#shuttingDown && this.#config) {
+        void this.#scheduleRecovery();
+      }
+    });
+  }
+  #attachProcessLogging(child, binary, args) {
+    const logStream = (0, import_node_fs.createWriteStream)(VICE_PROCESS_LOG_PATH, { flags: "a" });
+    this.#processLogStream = logStream;
+    this.#stdoutMirrorBuffer = "";
+    this.#stderrMirrorBuffer = "";
+    logStream.write(`
+=== Emulator launch ${nowIso()} ===
+`);
+    logStream.write(`binary: ${binary}
+`);
+    logStream.write(`args: ${args.join(" ")}
+`);
+    child.stdout?.pipe(logStream, { end: false });
+    child.stderr?.pipe(logStream, { end: false });
+    if (MIRROR_EMULATOR_LOGS_TO_STDERR) {
+      child.stdout?.on("data", (chunk) => {
+        this.#mirrorViceOutputChunk("stdout", chunk);
+      });
+      child.stderr?.on("data", (chunk) => {
+        this.#mirrorViceOutputChunk("stderr", chunk);
+      });
+    }
+  }
+  #closeProcessLog(child, reason) {
+    const logStream = this.#processLogStream;
+    if (!logStream) {
+      return;
+    }
+    child.stdout?.unpipe(logStream);
+    child.stderr?.unpipe(logStream);
+    this.#flushViceOutputMirror("stdout");
+    this.#flushViceOutputMirror("stderr");
+    logStream.write(`
+=== Emulator stream closed ${nowIso()} (${reason}) ===
+`);
+    logStream.end();
+    this.#processLogStream = null;
+  }
+  #mirrorViceOutputChunk(stream, chunk) {
+    const text = String(chunk);
+    const buffer = stream === "stdout" ? this.#stdoutMirrorBuffer : this.#stderrMirrorBuffer;
+    const combined = buffer + text;
+    const lines = combined.split(/\r?\n/);
+    const remainder = lines.pop() ?? "";
+    for (const line of lines) {
+      process.stderr.write(`[vice ${stream}] ${line}
+`);
+    }
+    if (stream === "stdout") {
+      this.#stdoutMirrorBuffer = remainder;
+    } else {
+      this.#stderrMirrorBuffer = remainder;
+    }
+  }
+  #flushViceOutputMirror(stream) {
+    const remainder = stream === "stdout" ? this.#stdoutMirrorBuffer : this.#stderrMirrorBuffer;
+    if (!remainder) {
+      return;
+    }
+    process.stderr.write(`[vice ${stream}] ${remainder}
+`);
+    if (stream === "stdout") {
+      this.#stdoutMirrorBuffer = "";
+    } else {
+      this.#stderrMirrorBuffer = "";
+    }
+  }
+  #writeProcessLogLine(line) {
+    this.#processLogStream?.write(`${nowIso()} ${line}
+`);
+    if (MIRROR_EMULATOR_LOGS_TO_STDERR) {
+      process.stderr.write(`[vice monitor] ${line}
+`);
+    }
+  }
+  async #stopManagedProcess(fullReset) {
+    this.#suppressRecovery = true;
+    try {
+      this.#clearHeldInputState();
+      const processId = this.#process?.pid ?? null;
+      this.#breakpointLabels.clear();
+      this.#explicitPauseActive = false;
+      this.#pendingCheckpointHit = null;
+      this.#lastCheckpointHit = null;
+      if (this.#client.connected) {
+        try {
+          await this.#client.quit();
+        } catch {
+          if (this.#process) {
+            this.#process.kill("SIGTERM");
+          }
+        }
+      } else if (this.#process) {
+        this.#process.kill("SIGTERM");
+      }
+      if (this.#process) {
+        await waitForProcessExit(this.#process, 1e3).catch(() => {
+          this.#process?.kill("SIGKILL");
+        });
+      }
+      await this.#client.disconnect();
+      this.#process = null;
+      if (fullReset) {
+        this.#transportState = "stopped";
+        this.#processState = processId == null ? "not_applicable" : "exited";
+      }
+    } finally {
+      this.#suppressRecovery = false;
+    }
+  }
+  async #resumeBeforeShutdown() {
+    if (!this.#client.connected) {
+      return;
+    }
+    this.#syncMonitorRuntimeState();
+    if (this.#executionState !== "stopped") {
+      return;
+    }
+    this.#writeProcessLogLine("[shutdown] emulator stopped in monitor, resuming before quit");
+    try {
+      this.#lastExecutionIntent = "unknown";
+      await this.#client.continueExecution();
+      await this.#waitForExecutionEvent(1e3);
+      this.#syncMonitorRuntimeState();
+    } catch (error) {
+      this.#writeProcessLogLine(
+        `[shutdown] resume before quit failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  async #hydrateExecutionState() {
+    await this.#stabilizeLaunchExecutionState();
+  }
+  async #readRegisters() {
+    const metadata = await this.#client.getRegistersAvailable();
+    const values = await this.#client.getRegisters();
+    const registers = this.#mapC64Registers(metadata.registers, values.registers);
+    this.#lastRegisters = registers;
+    return registers;
+  }
+  async #readDebugState() {
+    const registers = await this.#readRegisters();
+    return this.#buildDebugState(registers);
+  }
+  #buildDebugState(registers) {
+    this.#lastRegisters = registers;
+    return {
+      executionState: this.#executionState,
+      lastStopReason: this.#lastStopReason,
+      programCounter: registers.PC,
+      registers
+    };
+  }
+  #mergeRegisters(current, updated) {
+    if (!current) {
+      return null;
+    }
+    return {
+      ...current,
+      ...updated
+    };
+  }
+  #validateRange(start, end) {
+    if (end < start) {
+      validationError("End address must be greater than or equal to start address", { start, end });
+    }
+    if (start < 0 || end > 65535) {
+      validationError("Address range must fit in 16-bit address space", { start, end });
+    }
+  }
+  #mapC64Registers(metadata, values) {
+    const metadataByName = new Map(metadata.map((item) => [item.name.toUpperCase(), item]));
+    const valuesById = new Map(values.map((item) => [item.id, item.value]));
+    return Object.fromEntries(
+      C64_REGISTER_DEFINITIONS.map((definition) => {
+        const meta = metadataByName.get(definition.viceName.toUpperCase());
+        if (!meta) {
+          validationError(`Required C64 register is missing from the emulator: ${definition.viceName}`, {
+            registerName: definition.fieldName,
+            viceName: definition.viceName
+          });
+        }
+        const value = valuesById.get(meta.id);
+        if (value == null) {
+          validationError(`Required C64 register value is missing from the emulator: ${definition.viceName}`, {
+            registerName: definition.fieldName,
+            viceName: definition.viceName
+          });
+        }
+        return [definition.fieldName, value];
+      })
+    );
+  }
+  #getJoystickMask(port2) {
+    return this.#heldJoystickMasks.get(port2) ?? JOYSTICK_RELEASED_MASK;
+  }
+  async #applyJoystickMask(port2, mask) {
+    const normalizedMask = mask & JOYSTICK_RELEASED_MASK;
+    this.#heldJoystickMasks.set(port2, normalizedMask);
+    await this.#client.setJoyport(joystickPortToProtocol(port2), normalizedMask);
+  }
+  #describeJoystickState(port2) {
+    const mask = this.#getJoystickMask(port2);
+    return {
+      up: (mask & JOYSTICK_CONTROL_BITS.up) === 0,
+      down: (mask & JOYSTICK_CONTROL_BITS.down) === 0,
+      left: (mask & JOYSTICK_CONTROL_BITS.left) === 0,
+      right: (mask & JOYSTICK_CONTROL_BITS.right) === 0,
+      fire: (mask & JOYSTICK_CONTROL_BITS.fire) === 0
+    };
+  }
+  #clearHeldInputState() {
+    for (const interval of this.#heldKeyboardIntervals.values()) {
+      clearInterval(interval);
+    }
+    this.#heldKeyboardIntervals.clear();
+    this.#heldJoystickMasks.clear();
+  }
+  #attachBreakpointLabel(breakpoint) {
+    return {
+      ...breakpoint,
+      label: this.#breakpointLabels.get(breakpoint.id) ?? null
+    };
+  }
+  #pruneBreakpointLabels(activeBreakpointIds) {
+    const active = new Set(activeBreakpointIds);
+    for (const breakpointId of this.#breakpointLabels.keys()) {
+      if (!active.has(breakpointId)) {
+        this.#breakpointLabels.delete(breakpointId);
+      }
+    }
+  }
+  async #waitForExecutionEvent(timeoutMs) {
+    return await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.#client.off("event", onEvent);
+        resolve(null);
+      }, timeoutMs);
+      const onEvent = (event) => {
+        if (event.type !== "resumed" && event.type !== "stopped" && event.type !== "jam") {
+          return;
+        }
+        clearTimeout(timer);
+        this.#client.off("event", onEvent);
+        resolve({ type: event.type });
+      };
+      this.#client.on("event", onEvent);
+    });
+  }
+  async #stabilizeLaunchExecutionState() {
+    this.#writeProcessLogLine(`[bootstrap] waiting ${BOOTSTRAP_INITIAL_DELAY_MS}ms before probing launch state`);
+    await sleep(BOOTSTRAP_INITIAL_DELAY_MS);
+    const deadline = Date.now() + BOOTSTRAP_SETTLE_TIMEOUT_MS;
+    let runningSince = null;
+    let lastResumeAt = 0;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "running") {
+        runningSince ??= Date.now();
+        if (Date.now() - runningSince >= BOOTSTRAP_RUNNING_STABLE_MS) {
+          this.#writeProcessLogLine("[bootstrap] emulator reached stable running state after launch");
+          return;
+        }
+      } else {
+        runningSince = null;
+      }
+      if (this.#executionState !== "running" && Date.now() - lastResumeAt >= BOOTSTRAP_RESUME_COOLDOWN_MS) {
+        this.#writeProcessLogLine(`[bootstrap] observed ${this.#executionState} state after launch, sending resume`);
+        const previousExecutionState = this.#executionState;
+        const previousStopReason = this.#lastStopReason;
+        const executionEvent = this.#waitForExecutionEvent(EXECUTION_EVENT_WAIT_MS);
+        this.#lastExecutionIntent = "unknown";
+        try {
+          await this.#client.continueExecution();
+        } catch (error) {
+          const event2 = await executionEvent;
+          const accepted = this.#resumeWasAcceptedAfterError(error, event2, previousExecutionState, previousStopReason);
+          if (!accepted) {
+            this.#writeProcessLogLine(
+              `[bootstrap] resume after launch failed without runtime transition: ${error instanceof Error ? error.message : String(error)}`
+            );
+            throw error;
+          }
+        }
+        const event = await executionEvent;
+        if (!event) {
+          this.#writeProcessLogLine(
+            `[bootstrap] no runtime event observed within ${EXECUTION_EVENT_WAIT_MS}ms after resume, waiting ${BOOTSTRAP_POLL_MS}ms`
+          );
+          await sleep(BOOTSTRAP_POLL_MS);
+        }
+        lastResumeAt = Date.now();
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        this.#writeProcessLogLine(
+          `[bootstrap] settle timeout reached after ${BOOTSTRAP_SETTLE_TIMEOUT_MS}ms with executionState=${this.#executionState}`
+        );
+        throw new ViceMcpError(
+          "bootstrap_timeout",
+          "Emulator launch did not reach a stable running state before timeout.",
+          "timeout",
+          true,
+          {
+            executionState: this.#executionState,
+            lastStopReason: this.#lastStopReason
+          }
+        );
+      }
+      await sleep(BOOTSTRAP_POLL_MS);
+    }
+  }
+  async #withExecutionLock(operation) {
+    while (this.#executionOperationLock) {
+      await this.#executionOperationLock;
+    }
+    let resolve;
+    this.#executionOperationLock = new Promise((r) => resolve = r);
+    try {
+      return await operation();
+    } finally {
+      this.#executionOperationLock = null;
+      resolve();
+    }
+  }
+  async #withDisplayLock(operation) {
+    while (this.#displayOperationLock) {
+      await this.#displayOperationLock;
+    }
+    let resolve;
+    this.#displayOperationLock = new Promise((r) => resolve = r);
+    try {
+      return await operation();
+    } finally {
+      this.#displayOperationLock = null;
+      resolve();
+    }
+  }
+  async #settleProgramLoadState(autoStart) {
+    const deadline = Date.now() + PROGRAM_LOAD_SETTLE_TIMEOUT_MS;
+    let runningSince = null;
+    let lastResumeAt = 0;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "running") {
+        runningSince ??= Date.now();
+        if (Date.now() - runningSince >= PROGRAM_LOAD_RUNNING_STABLE_MS) {
+          return;
+        }
+      } else {
+        runningSince = null;
+      }
+      if (this.#executionState === "stopped" && Date.now() - lastResumeAt >= PROGRAM_LOAD_RESUME_COOLDOWN_MS) {
+        this.#writeProcessLogLine(
+          `[autostart] observed stopped state after load with autoStart=${autoStart}, sending resume`
+        );
+        this.#explicitPauseActive = false;
+        this.#lastExecutionIntent = "unknown";
+        await this.#client.continueExecution();
+        lastResumeAt = Date.now();
+      }
+      if (Date.now() >= deadline) {
+        this.#writeProcessLogLine(
+          `[autostart] settle timeout reached after ${PROGRAM_LOAD_SETTLE_TIMEOUT_MS}ms with executionState=${this.#executionState}`
+        );
+        return;
+      }
+      await sleep(PROGRAM_LOAD_SETTLE_POLL_MS);
+    }
+  }
+  async #pauseForDisplayInspection(commandName, previousExecutionState) {
+    if (previousExecutionState === "stopped") {
+      return;
+    }
+    if (previousExecutionState !== "running") {
+      emulatorNotRunningError(commandName, {
+        executionState: previousExecutionState,
+        lastStopReason: this.#lastStopReason
+      });
+    }
+    this.#writeProcessLogLine(`[display] ${commandName} started while running, waiting for a temporary stop`);
+    await this.#client.setBreakpoint({
+      start: 0,
+      end: 65535,
+      kind: "exec",
+      temporary: true,
+      enabled: true,
+      stopWhenHit: true
+    });
+    const deadline = Date.now() + DISPLAY_PAUSE_TIMEOUT_MS;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "stopped") {
+        return;
+      }
+      if (Date.now() >= deadline) {
+        throw new ViceMcpError(
+          "display_pause_timeout",
+          `${commandName} could not reach a temporary stopped state before timeout.`,
+          "timeout",
+          true,
+          {
+            commandName,
+            executionState: this.#executionState,
+            lastStopReason: this.#lastStopReason
+          }
+        );
+      }
+      await sleep(DISPLAY_SETTLE_POLL_MS);
+    }
+  }
+  async #settleDisplayToolState(commandName, previousExecutionState) {
+    this.#syncMonitorRuntimeState();
+    if (previousExecutionState !== "running") {
+      return;
+    }
+    const deadline = Date.now() + DISPLAY_SETTLE_TIMEOUT_MS;
+    let runningSince = null;
+    let lastResumeAt = 0;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "running") {
+        runningSince ??= Date.now();
+        if (Date.now() - runningSince >= DISPLAY_RUNNING_STABLE_MS) {
+          return;
+        }
+      } else {
+        runningSince = null;
+      }
+      if (this.#executionState === "stopped" && Date.now() - lastResumeAt >= DISPLAY_RESUME_COOLDOWN_MS) {
+        this.#writeProcessLogLine(`[display] observed stopped state after ${commandName}, sending resume`);
+        this.#lastExecutionIntent = "unknown";
+        await this.#client.continueExecution();
+        lastResumeAt = Date.now();
+      }
+      if (Date.now() >= deadline) {
+        this.#writeProcessLogLine(
+          `[display] settle timeout reached after ${DISPLAY_SETTLE_TIMEOUT_MS}ms after ${commandName} with executionState=${this.#executionState}`
+        );
+        if (this.#executionState !== "running") {
+          emulatorNotRunningError(commandName, {
+            executionState: this.#executionState,
+            lastStopReason: this.#lastStopReason
+          });
+        }
+        return;
+      }
+      await sleep(DISPLAY_SETTLE_POLL_MS);
+    }
+  }
+  async #settleInputState(commandName, previousExecutionState) {
+    if (previousExecutionState !== "running") {
+      return;
+    }
+    const deadline = Date.now() + INPUT_SETTLE_TIMEOUT_MS;
+    let runningSince = null;
+    let lastResumeAt = 0;
+    while (true) {
+      this.#syncMonitorRuntimeState();
+      if (this.#executionState === "running") {
+        runningSince ??= Date.now();
+        if (Date.now() - runningSince >= INPUT_RUNNING_STABLE_MS) {
+          return;
+        }
+      } else {
+        runningSince = null;
+      }
+      if (this.#executionState === "stopped" && Date.now() - lastResumeAt >= INPUT_RESUME_COOLDOWN_MS) {
+        this.#writeProcessLogLine(`[input] observed stopped state after ${commandName}, sending resume`);
+        this.#explicitPauseActive = false;
+        this.#lastExecutionIntent = "unknown";
+        await this.#client.continueExecution();
+        lastResumeAt = Date.now();
+      }
+      if (Date.now() >= deadline) {
+        this.#writeProcessLogLine(
+          `[input] settle timeout reached after ${INPUT_SETTLE_TIMEOUT_MS}ms with executionState=${this.#executionState}`
+        );
+        if (this.#executionState !== "running") {
+          emulatorNotRunningError(commandName, {
+            executionState: this.#executionState,
+            lastStopReason: this.#lastStopReason
+          });
+        }
+        return;
+      }
+      await sleep(INPUT_SETTLE_POLL_MS);
+    }
+  }
+  #autostartWasAcceptedAfterError(error, event, previousExecutionState, previousStopReason) {
+    if (!(error instanceof ViceMcpError)) {
+      return false;
+    }
+    if (!["emulator_protocol_error", "timeout", "connection_closed"].includes(error.code)) {
+      return false;
+    }
+    return this.#executionState !== previousExecutionState && (this.#executionState === "running" || this.#executionState === "stopped") && this.#lastStopReason !== previousStopReason && event != null;
+  }
+  #resumeWasAcceptedAfterError(error, event, previousExecutionState, previousStopReason) {
+    if (!(error instanceof ViceMcpError)) {
+      return false;
+    }
+    if (!["emulator_protocol_error", "timeout", "connection_closed"].includes(error.code)) {
+      return false;
+    }
+    if (event) {
+      this.#writeProcessLogLine(
+        `[bootstrap] resume probe accepted after ${error.code} because monitor reported ${event.type}`
+      );
+      return true;
+    }
+    return this.#executionState !== previousExecutionState || this.#lastStopReason !== previousStopReason;
+  }
+  #syncMonitorRuntimeState() {
+    const runtime = this.#client.runtimeState();
+    const eventType = runtime.lastEventType;
+    this.#executionState = runtime.runtimeKnown && eventType === "resumed" ? "running" : runtime.runtimeKnown ? "stopped" : "unknown";
+    if (eventType !== this.#lastRuntimeEventType || runtime.programCounter !== this.#lastRuntimeProgramCounter) {
+      this.#lastStopReason = this.#stopReasonFromMonitorEvent(eventType);
+      this.#lastRuntimeEventType = eventType;
+      this.#lastRuntimeProgramCounter = runtime.programCounter;
+    }
+    this.#writeProcessLogLine(
+      `[monitor-state] executionState=${this.#executionState} lastStopReason=${this.#lastStopReason} runtimeKnown=${runtime.runtimeKnown} lastEventType=${eventType}${runtime.programCounter == null ? "" : ` pc=$${runtime.programCounter.toString(16).padStart(4, "0")}`}`
+    );
+    this.#scheduleIdleAutoResume();
+  }
+  #stopReasonFromMonitorEvent(eventType) {
+    switch (eventType) {
+      case "resumed":
+        this.#pendingCheckpointHit = null;
+        return "none";
+      case "stopped":
+        if (this.#pendingCheckpointHit && Date.now() - this.#pendingCheckpointHit.observedAt <= CHECKPOINT_HIT_SETTLE_MS) {
+          this.#lastCheckpointHit = this.#pendingCheckpointHit;
+          const checkpointReason = this.#pendingCheckpointHit.kind === "exec" ? "breakpoint" : this.#pendingCheckpointHit.kind === "read" ? "watchpoint_read" : "watchpoint_write";
+          this.#pendingCheckpointHit = null;
+          return checkpointReason;
+        }
+        if (this.#lastExecutionIntent === "unknown" && !this.#checkpointQueryPending) {
+          void this.#scheduleCheckpointHitQuery();
+        }
+        return this.#lastExecutionIntent;
+      case "jam":
+        this.#pendingCheckpointHit = null;
+        return "error";
+      case "unknown":
+        this.#pendingCheckpointHit = null;
+        return "unknown";
+    }
+  }
+  async #scheduleCheckpointHitQuery() {
+    if (this.#checkpointQueryPending) {
+      return;
+    }
+    this.#checkpointQueryPending = true;
+    try {
+      await sleep(200);
+      if (this.#lastStopReason !== "unknown" && this.#lastStopReason !== this.#lastExecutionIntent) {
+        return;
+      }
+      this.#writeProcessLogLine("[checkpoint-query] probing for hit checkpoint after ambiguous stop");
+      const response = await this.#client.listBreakpoints();
+      const hit = response.checkpoints.find((cp) => cp.currentlyHit);
+      if (hit) {
+        this.#lastCheckpointHit = {
+          id: hit.id,
+          kind: hit.kind,
+          observedAt: Date.now()
+        };
+        const reason = hit.kind === "exec" ? "breakpoint" : hit.kind === "read" ? "watchpoint_read" : "watchpoint_write";
+        this.#lastStopReason = reason;
+        this.#writeProcessLogLine(`[checkpoint-query] retroactively identified stop reason: ${reason} (id=${hit.id})`);
+      }
+    } catch (error) {
+      this.#writeProcessLogLine(`[checkpoint-query] failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      this.#checkpointQueryPending = false;
+    }
+  }
+  #autoResumeAllowed() {
+    return !this.#shuttingDown && this.#client.connected && !this.#explicitPauseActive;
+  }
+  #scheduleIdleAutoResume() {
+    if (this.#executionState !== "stopped" || !this.#autoResumeAllowed()) {
+      this.#clearIdleAutoResume();
+      return;
+    }
+    this.#stoppedAt = Date.now();
+    if (this.#autoResumeTimer) {
+      clearTimeout(this.#autoResumeTimer);
+    }
+    this.#autoResumeTimer = setTimeout(() => {
+      this.#autoResumeTimer = null;
+      void this.#autoResumeDueToIdle();
+    }, STOPPED_IDLE_TIMEOUT_MS);
+  }
+  #clearIdleAutoResume() {
+    this.#stoppedAt = null;
+    if (this.#autoResumeTimer) {
+      clearTimeout(this.#autoResumeTimer);
+      this.#autoResumeTimer = null;
+    }
+  }
+  async #autoResumeDueToIdle() {
+    if (!this.#autoResumeAllowed() || this.#executionState !== "stopped") {
+      this.#stoppedAt = null;
+      return;
+    }
+    const stoppedMs = this.#stoppedAt ? Date.now() - this.#stoppedAt : STOPPED_IDLE_TIMEOUT_MS;
+    if (stoppedMs < STOPPED_IDLE_TIMEOUT_MS) {
+      this.#scheduleIdleAutoResume();
+      return;
+    }
+    this.#writeProcessLogLine(`[auto-resume] emulator stopped for ${STOPPED_IDLE_TIMEOUT_MS}ms, resuming to stay responsive`);
+    try {
+      this.#lastExecutionIntent = "unknown";
+      await this.#client.continueExecution();
+    } catch (error) {
+      this.#writeProcessLogLine(
+        `[auto-resume] resume attempt failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    } finally {
+      this.#stoppedAt = null;
+    }
+    this.#syncMonitorRuntimeState();
+  }
+};
+function splitCommandLine(input) {
+  const result = [];
+  let current = "";
+  let quote = null;
+  for (const char of input) {
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        result.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current) {
+    result.push(current);
+  }
+  return result;
+}
+async function waitForMonitor(host2, port2, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await isPortAvailable(host2, port2)) {
+      return;
+    }
+    await sleep(100);
+  }
+  throw new ViceMcpError("monitor_timeout", `Debugger monitor did not open on ${host2}:${port2}`, "timeout", true, {
+    host: host2,
+    port: port2
+  });
+}
+async function waitForProcessExit(process2, timeoutMs) {
+  if (process2.exitCode != null) {
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Timed out waiting for process exit")), timeoutMs);
+    process2.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+// src/server.ts
+var c64Session = new ViceSession();
+var noInputSchema = import_zod4.z.object({}).strict();
+function createViceTool(options) {
+  return (0, import_tools.createTool)({
+    id: options.id,
+    description: options.description,
+    ...options.inputSchema ? { inputSchema: options.inputSchema } : {},
+    outputSchema: toolOutputSchema(options.dataSchema),
+    mcp: options.mcp,
+    execute: async (input) => {
+      try {
+        const data = await options.execute(input);
+        return {
+          meta: c64Session.takeResponseMeta(),
+          data
+        };
+      } catch (error) {
+        throw normalizeToolError(error);
+      }
+    }
+  });
+}
+function normalizeBreakpoint(breakpoint) {
+  return {
+    id: breakpoint.id,
+    address: breakpoint.start,
+    length: breakpoint.end - breakpoint.start + 1,
+    enabled: breakpoint.enabled,
+    temporary: breakpoint.temporary,
+    hasCondition: breakpoint.hasCondition,
+    kind: breakpoint.kind,
+    label: breakpoint.label ?? null
+  };
+}
+var getMonitorStateTool = createViceTool({
+  id: "get_monitor_state",
+  description: "Returns whether the C64 is running or stopped, along with the current stop reason and program counter when available.",
+  inputSchema: noInputSchema,
+  dataSchema: monitorStateSchema,
+  execute: async () => await c64Session.getMonitorState()
+});
+var getSessionStateTool = createViceTool({
+  id: "get_session_state",
+  description: "Returns richer emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint when known.",
+  inputSchema: noInputSchema,
+  dataSchema: sessionStateResultSchema,
+  execute: async () => c64Session.snapshot()
+});
+var getRegistersTool = createViceTool({
+  id: "get_registers",
+  description: "Returns the current C64 register snapshot. This requires the emulator to already be stopped.",
+  inputSchema: noInputSchema,
+  dataSchema: import_zod4.z.object({
+    registers: c64RegisterValueSchema
+  }),
+  execute: async () => await c64Session.getRegisters()
+});
+var setRegistersTool = createViceTool({
+  id: "set_registers",
+  description: "Sets one or more C64 registers by field name.",
+  inputSchema: import_zod4.z.object({
+    registers: c64PartialRegisterValueSchema
+  }),
+  dataSchema: import_zod4.z.object({
+    updated: c64PartialRegisterValueSchema,
+    executionState: executionStateSchema
+  }),
+  execute: async (input) => await c64Session.setRegisters(input.registers)
+});
+var readMemoryTool = createViceTool({
+  id: "memory_read",
+  description: "Reads a memory chunk by start address and length and returns raw bytes as a JSON array.",
+  inputSchema: import_zod4.z.object({
+    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    length: import_zod4.z.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
+  }).refine((input) => input.address + input.length <= 65536, {
+    message: "address + length must stay within the 64K address space",
+    path: ["length"]
+  }),
+  dataSchema: import_zod4.z.object({
+    address: address16Schema.describe("Start address of the returned memory chunk"),
+    length: import_zod4.z.number().int().min(0).describe("Number of bytes returned"),
+    data: byteArraySchema.describe("Raw bytes returned from memory")
+  }),
+  execute: async (input) => {
+    const result = await c64Session.readMemory(input.address, input.address + input.length - 1);
+    return {
+      address: input.address,
+      length: result.length,
+      data: result.data
+    };
+  }
+});
+var writeMemoryTool = createViceTool({
+  id: "memory_write",
+  description: "Writes raw byte values into the active C64 memory space.",
+  inputSchema: import_zod4.z.object({
+    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    data: byteArraySchema.min(1).describe("Raw bytes to write into memory")
+  }).refine((input) => input.address + input.data.length - 1 <= 65535, {
+    message: "address + data.length must stay within the 16-bit address space",
+    path: ["data"]
+  }),
+  dataSchema: import_zod4.z.object({
+    worked: import_zod4.z.boolean().describe("Whether the write operation completed successfully"),
+    address: address16Schema.describe("Start address where the bytes were written"),
+    length: import_zod4.z.number().int().min(1).describe("Number of bytes written")
+  }).extend(debugStateSchema.shape),
+  execute: async (input) => await c64Session.writeMemory(input.address, input.data)
+});
+var executeTool = createViceTool({
+  id: "execute",
+  description: "Controls execution with pause, resume, step, step_over, step_out, or reset. Resume can optionally wait until running becomes stable.",
+  inputSchema: import_zod4.z.object({
+    action: import_zod4.z.enum(["pause", "resume", "step", "step_over", "step_out", "reset"]),
+    count: import_zod4.z.number().int().positive().default(1).describe("Instruction count for step and step_over actions"),
+    resetMode: resetModeSchema.default("soft").describe("Reset mode when action is reset"),
+    waitUntilRunningStable: import_zod4.z.boolean().default(false).describe("When action is resume, wait until running becomes stable before returning")
+  }),
+  dataSchema: debugStateSchema.extend({
+    stepsExecuted: import_zod4.z.number().int().positive().optional(),
+    warnings: import_zod4.z.array(warningSchema)
+  }),
+  execute: async (input) => await c64Session.execute(input.action, input.count, input.resetMode, input.waitUntilRunningStable)
+});
+var waitForStateTool = createViceTool({
+  id: "wait_for_state",
+  description: "Waits for the emulator to reach a target execution state and optionally remain there for a stability window.",
+  inputSchema: import_zod4.z.object({
+    executionState: import_zod4.z.enum(["running", "stopped"]).describe("Target execution state to wait for"),
+    timeoutMs: import_zod4.z.number().int().positive().default(5e3).describe("Maximum time to wait before returning"),
+    stableMs: import_zod4.z.number().int().nonnegative().optional().describe("Optional stability window the target state must remain true before returning")
+  }),
+  dataSchema: waitForStateResultSchema,
+  execute: async (input) => await c64Session.waitForState(input.executionState, input.timeoutMs, input.stableMs)
+});
+var listBreakpointsTool = createViceTool({
+  id: "list_breakpoints",
+  description: "Lists current breakpoints and watchpoints.",
+  inputSchema: import_zod4.z.object({
+    includeDisabled: import_zod4.z.boolean().default(true)
+  }),
+  dataSchema: import_zod4.z.object({
+    breakpoints: import_zod4.z.array(breakpointSchema)
+  }),
+  execute: async (input) => {
+    const result = await c64Session.listBreakpoints(input.includeDisabled);
+    return {
+      breakpoints: result.breakpoints.map((breakpoint) => normalizeBreakpoint(breakpoint))
+    };
+  }
+});
+var breakpointSetTool = createViceTool({
+  id: "breakpoint_set",
+  description: "Creates an execution breakpoint or read/write watchpoint.",
+  inputSchema: import_zod4.z.object({
+    kind: breakpointKindSchema,
+    address: address16Schema.describe("Start address of the breakpoint range"),
+    length: import_zod4.z.number().int().positive().default(1).describe("Size of the breakpoint range in bytes"),
+    condition: import_zod4.z.string().optional(),
+    label: import_zod4.z.string().optional(),
+    temporary: import_zod4.z.boolean().default(false),
+    enabled: import_zod4.z.boolean().default(true)
+  }),
+  dataSchema: import_zod4.z.object({
+    breakpoint: breakpointSchema,
+    executionState: executionStateSchema,
+    lastStopReason: stopReasonSchema,
+    programCounter: address16Schema.nullable(),
+    registers: c64PartialRegisterValueSchema.nullable()
+  }),
+  execute: async (input) => {
+    const result = await c64Session.breakpointSet(input);
+    return {
+      breakpoint: normalizeBreakpoint(result.breakpoint),
+      executionState: result.executionState,
+      lastStopReason: result.lastStopReason,
+      programCounter: result.programCounter,
+      registers: result.registers
+    };
+  }
+});
+var breakpointClearTool = createViceTool({
+  id: "breakpoint_clear",
+  description: "Deletes a breakpoint by numeric id.",
+  inputSchema: import_zod4.z.object({
+    breakpointId: import_zod4.z.number().int().nonnegative()
+  }),
+  dataSchema: import_zod4.z.object({
+    executionState: executionStateSchema,
+    lastStopReason: stopReasonSchema,
+    programCounter: address16Schema.nullable(),
+    registers: c64PartialRegisterValueSchema.nullable(),
+    cleared: import_zod4.z.boolean(),
+    breakpointId: import_zod4.z.number().int()
+  }),
+  execute: async (input) => await c64Session.breakpointClear(input.breakpointId)
+});
+var programLoadTool = createViceTool({
+  id: "program_load",
+  description: "Loads a C64 program and optionally starts it.",
+  inputSchema: import_zod4.z.object({
+    filePath: import_zod4.z.string(),
+    autoStart: import_zod4.z.boolean().default(true).describe("Whether the loaded program should be started immediately after loading"),
+    fileIndex: import_zod4.z.number().int().nonnegative().default(0).describe("Autostart file index inside the image, when applicable")
+  }),
+  dataSchema: programLoadResultSchema,
+  execute: async (input) => await c64Session.programLoad(input)
+});
+var captureDisplayTool = createViceTool({
+  id: "capture_display",
+  description: "Captures the current screen to a PNG file and returns the saved image path. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  inputSchema: import_zod4.z.object({
+    useVic: import_zod4.z.boolean().default(true).describe("Whether to capture the VIC-II display when supported")
+  }),
+  dataSchema: captureDisplayResultSchema,
+  execute: async (input) => await c64Session.captureDisplay(input.useVic)
+});
+var getDisplayStateTool = createViceTool({
+  id: "get_display_state",
+  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  inputSchema: noInputSchema,
+  dataSchema: displayStateResultSchema,
+  execute: async () => await c64Session.getDisplayState()
+});
+var getDisplayTextTool = createViceTool({
+  id: "get_display_text",
+  description: "Returns the current text screen as readable text when the C64 is in a text mode. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  inputSchema: noInputSchema,
+  dataSchema: displayTextResultSchema,
+  execute: async () => await c64Session.getDisplayText()
+});
+var writeTextTool = createViceTool({
+  id: "write_text",
+  description: "Types text into the C64 while it is running. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names; limit each request to 64 bytes.",
+  inputSchema: import_zod4.z.object({
+    text: import_zod4.z.string()
+  }),
+  dataSchema: import_zod4.z.object({
+    sent: import_zod4.z.boolean(),
+    length: import_zod4.z.number().int()
+  }),
+  execute: async (input) => await c64Session.writeText(input.text)
+});
+var keyboardInputTool = createViceTool({
+  id: "keyboard_input",
+  description: "Sends one to four keys or PETSCII tokens to the C64 while it is running. Use this for key presses, releases, and taps. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  inputSchema: import_zod4.z.object({
+    action: inputActionSchema.describe("Use tap for a single key event or press/release for repeated buffered input"),
+    keys: import_zod4.z.array(import_zod4.z.string().min(1)).min(1).max(4).describe("One to four literal keys or PETSCII token names such as RETURN, CLR, HOME, PI, LEFT, RED, or F1"),
+    durationMs: import_zod4.z.number().int().positive().optional().describe("Tap duration in milliseconds")
+  }),
+  dataSchema: keyboardInputResultSchema,
+  execute: async (input) => await c64Session.keyboardInput(input.action, input.keys, input.durationMs)
+});
+var joystickInputTool = createViceTool({
+  id: "joystick_input",
+  description: "Sends joystick input to C64 joystick port 1 or 2 while the C64 is running. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  inputSchema: import_zod4.z.object({
+    port: joystickPortSchema.describe("Joystick port number"),
+    action: inputActionSchema.describe("Joystick action to apply"),
+    control: joystickControlSchema.describe("Joystick direction or fire control"),
+    durationMs: import_zod4.z.number().int().optional().describe("Tap duration in milliseconds (will be clamped to reasonable range)")
+  }),
+  dataSchema: joystickInputResultSchema,
+  execute: async (input) => await c64Session.joystickInput(input.port, input.action, input.control, input.durationMs)
+});
+var c64DebugServer = new import_mcp.MCPServer({
+  id: "c64-debug-mcp",
+  name: "c64 debugger",
+  version: "0.1.0",
+  description: "MCP server for C64 debugging and interaction.",
+  instructions: "This server is for C64 debugging. Use the tools directly to inspect, control, and interact with the C64.",
+  tools: {
+    get_monitor_state: getMonitorStateTool,
+    get_session_state: getSessionStateTool,
+    get_registers: getRegistersTool,
+    set_registers: setRegistersTool,
+    memory_read: readMemoryTool,
+    memory_write: writeMemoryTool,
+    execute: executeTool,
+    wait_for_state: waitForStateTool,
+    list_breakpoints: listBreakpointsTool,
+    breakpoint_set: breakpointSetTool,
+    breakpoint_clear: breakpointClearTool,
+    program_load: programLoadTool,
+    capture_display: captureDisplayTool,
+    get_display_state: getDisplayStateTool,
+    get_display_text: getDisplayTextTool,
+    write_text: writeTextTool,
+    keyboard_input: keyboardInputTool,
+    joystick_input: joystickInputTool
+  }
+});
+
+// src/http.ts
+var host = process.env.C64_DEBUG_HTTP_HOST?.trim() || "127.0.0.1";
+var port = Number.parseInt(process.env.C64_DEBUG_HTTP_PORT?.trim() || "39080", 10);
+var mcpPath = process.env.C64_DEBUG_HTTP_PATH?.trim() || "/mcp";
+var healthPath = process.env.C64_DEBUG_HTTP_HEALTH_PATH?.trim() || "/healthz";
+var shuttingDown = false;
+var httpServer = import_node_http.default.createServer(async (req, res) => {
+  const url = new URL(req.url || "/", `http://${host}:${port}`);
+  if (url.pathname === healthPath) {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+  if (url.pathname !== mcpPath) {
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "not_found" }));
+    return;
+  }
+  try {
+    await c64DebugServer.startHTTP({
+      url,
+      httpPath: mcpPath,
+      req,
+      res,
+      options: {
+        enableJsonResponse: true
+      }
+    });
+  } catch (error) {
+    if (!res.headersSent) {
+      res.writeHead(500, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: "mcp_http_start_failed",
+          message: error instanceof Error ? error.message : String(error)
+        })
+      );
+      return;
+    }
+    res.end();
+  }
+});
+async function closeHttpServer() {
+  await new Promise((resolve, reject) => {
+    httpServer.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+async function shutdown(exitCode = 0, error) {
+  if (shuttingDown) {
+    return;
+  }
+  shuttingDown = true;
+  if (error) {
+    console.error("C64 Debug MCP HTTP server failed:", error);
+  }
+  try {
+    await closeHttpServer().catch(() => void 0);
+    await c64DebugServer.close().catch(() => void 0);
+    await c64Session.shutdown();
+  } catch (shutdownError) {
+    console.error("C64 Debug MCP HTTP shutdown failed:", shutdownError);
+    exitCode = exitCode === 0 ? 1 : exitCode;
+  } finally {
+    process.exit(exitCode);
+  }
+}
+process.once("SIGINT", () => {
+  void shutdown(0);
+});
+process.once("SIGTERM", () => {
+  void shutdown(0);
+});
+process.once("uncaughtException", (error) => {
+  void shutdown(1, error);
+});
+process.once("unhandledRejection", (reason) => {
+  void shutdown(1, reason);
+});
+httpServer.listen(port, host, () => {
+  console.error(`C64 Debug MCP HTTP listening on http://${host}:${port}${mcpPath}`);
+});