c64bridge 0.9.0 → 0.9.2

package/dist/tools/translation/disassembler.js

@@ -0,0 +1,150 @@
+/**
+ * 6502/6510 disassembler covering the full 256-opcode space, including
+ * undocumented (illegal) opcodes. Mnemonic naming follows the canonical
+ * convention used by the 1541U monitor (HLT->JAM, ASO->SLO, LSE->SRE,
+ * DCM->DCP, INS->ISC).
+ */
+import { OpcodeAddressingMode as Mode, OPCODES_BY_BYTE as OPCODES, opcodeSize as modeSize, } from "./opcodeInventory.js";
+function hex2(v) {
+    return v.toString(16).toUpperCase().padStart(2, "0");
+}
+function hex4(v) {
+    return v.toString(16).toUpperCase().padStart(4, "0");
+}
+function labelOrHex4(addr, symbols) {
+    const label = symbols?.get(addr);
+    return label ? `${label} ($${hex4(addr)})` : `$${hex4(addr)}`;
+}
+function formatOperand(mode, bytes, offset, instrAddr, symbols) {
+    switch (mode) {
+        case Mode.Imp:
+            return "";
+        case Mode.Acc:
+            return "A";
+        case Mode.Imm:
+            return `#$${hex2(bytes[offset + 1] ?? 0)}`;
+        case Mode.Zp:
+            return `$${hex2(bytes[offset + 1] ?? 0)}`;
+        case Mode.ZpX:
+            return `$${hex2(bytes[offset + 1] ?? 0)},X`;
+        case Mode.ZpY:
+            return `$${hex2(bytes[offset + 1] ?? 0)},Y`;
+        case Mode.ZpS:
+            return `$${hex2(bytes[offset + 1] ?? 0)},S`;
+        case Mode.Rel: {
+            const rel = bytes[offset + 1] ?? 0;
+            const signed = rel >= 0x80 ? rel - 0x100 : rel;
+            const target = (instrAddr + 2 + signed) & 0xffff;
+            return labelOrHex4(target, symbols);
+        }
+        case Mode.Abs: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return labelOrHex4(addr, symbols);
+        }
+        case Mode.AbsX: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `${labelOrHex4(addr, symbols)},X`;
+        }
+        case Mode.AbsY: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `${labelOrHex4(addr, symbols)},Y`;
+        }
+        case Mode.Ind: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `($${hex4(addr)})`;
+        }
+        case Mode.IndX:
+            return `($${hex2(bytes[offset + 1] ?? 0)},X)`;
+        case Mode.IndY:
+            return `($${hex2(bytes[offset + 1] ?? 0)}),Y`;
+    }
+}
+/**
+ * Disassemble a block of 6502/6510 bytes.
+ *
+ * @param bytes               Raw memory bytes (may be longer than needed)
+ * @param baseAddress         The C64 memory address of `bytes[0]`
+ * @param countOrOptions      Either a max-instruction count (legacy form) or an options object
+ * @param symbols             Optional address->label map (legacy positional form)
+ */
+export function disassemble(bytes, baseAddress, countOrOptions, symbols) {
+    const options = typeof countOrOptions === "object" && countOrOptions !== null
+        ? countOrOptions
+        : { count: countOrOptions, symbols };
+    const limit = options.count ?? Infinity;
+    const symMap = options.symbols ?? symbols;
+    const allowUndocumented = options.allowUndocumented !== false;
+    const lines = [];
+    let offset = 0;
+    while (offset < bytes.length && lines.length < limit) {
+        const instrAddr = (baseAddress + offset) & 0xffff;
+        const opcode = bytes[offset] ?? 0;
+        const op = OPCODES[opcode];
+        const label = symMap?.get(instrAddr);
+        if (op.illegal && !allowUndocumented) {
+            lines.push({
+                address: instrAddr,
+                bytes: [opcode],
+                label,
+                mnemonic: "???",
+                operand: `$${hex2(opcode)}`,
+                undocumented: true,
+            });
+            offset += 1;
+            continue;
+        }
+        const size = modeSize(op.mode);
+        const instrBytes = [];
+        for (let i = 0; i < size && offset + i < bytes.length; i += 1) {
+            instrBytes.push(bytes[offset + i] ?? 0);
+        }
+        const operand = formatOperand(op.mode, bytes, offset, instrAddr, symMap);
+        lines.push({
+            address: instrAddr,
+            bytes: instrBytes,
+            label,
+            mnemonic: op.mnemonic,
+            operand,
+            undocumented: op.illegal,
+        });
+        offset += size;
+    }
+    return lines;
+}
+/**
+ * Render disassembly lines as a human-readable string.
+ * Format: [label:\n] $ADDR  XX XX XX  MNEM operand   ; *undocumented*
+ */
+export function formatDisassembly(lines) {
+    const parts = [];
+    for (const line of lines) {
+        if (line.label) {
+            parts.push(`${line.label}:`);
+        }
+        const addrStr = `$${hex4(line.address)}`;
+        const byteStr = line.bytes.map((b) => hex2(b)).join(" ").padEnd(8);
+        const mnemonic = line.undocumented ? `${line.mnemonic}*` : line.mnemonic;
+        const instrStr = line.operand
+            ? `${mnemonic} ${line.operand}`
+            : mnemonic;
+        parts.push(`  ${addrStr}  ${byteStr}  ${instrStr}`);
+    }
+    return parts.join("\n");
+}
+/** Returns true when the opcode is undocumented per the 1541U reference. */
+export function isUndocumentedOpcode(opcode) {
+    return OPCODES[opcode & 0xff].illegal;
+}
+/** Lookup helper used by tests to verify table coverage. */
+export function opcodeMetadata(opcode) {
+    const entry = OPCODES[opcode & 0xff];
+    return { mnemonic: entry.mnemonic, undocumented: entry.illegal, size: modeSize(entry.mode) };
+}

package/dist/tools/translation/opcodeInventory.js

@@ -0,0 +1,126 @@
+/**
+ * Shared 6502/6510 opcode inventory.
+ *
+ * Entries are sorted by increasing binary opcode and cover the complete
+ * 256-byte opcode space, including undocumented opcodes. Mnemonic naming
+ * follows the canonical 1541U monitor convention:
+ * HLT -> JAM, ASO -> SLO, LSE -> SRE, DCM -> DCP, INS -> ISC.
+ */
+export const OpcodeAddressingMode = {
+    Imp: "implied",
+    Acc: "accumulator",
+    Imm: "immediate",
+    Zp: "zeroPage",
+    ZpX: "zeroPageX",
+    ZpY: "zeroPageY",
+    ZpS: "zeroPageS",
+    Rel: "relative",
+    Abs: "absolute",
+    AbsX: "absoluteX",
+    AbsY: "absoluteY",
+    Ind: "indirect",
+    IndX: "indirectX",
+    IndY: "indirectY",
+};
+const M = OpcodeAddressingMode;
+const OPCODE_ROWS = [
+    // 0x00-0x0F
+    [["BRK", M.Imp], ["ORA", M.IndX], ["HLT", M.Imp], ["ASO", M.IndX], ["NOP", M.Zp], ["ORA", M.Zp], ["ASL", M.Zp], ["ASO", M.Zp], ["PHP", M.Imp], ["ORA", M.Imm], ["ASL", M.Acc], ["ANC", M.Imm], ["NOP", M.Abs], ["ORA", M.Abs], ["ASL", M.Abs], ["ASO", M.Abs]],
+    // 0x10-0x1F
+    [["BPL", M.Rel], ["ORA", M.IndY], ["HLT", M.Imp], ["ASO", M.IndY], ["NOP", M.ZpX], ["ORA", M.ZpX], ["ASL", M.ZpX], ["ASO", M.ZpX], ["CLC", M.Imp], ["ORA", M.AbsY], ["NOP", M.Imp], ["ASO", M.AbsY], ["NOP", M.AbsX], ["ORA", M.AbsX], ["ASL", M.AbsX], ["ASO", M.AbsX]],
+    // 0x20-0x2F
+    [["JSR", M.Abs], ["AND", M.IndX], ["HLT", M.Imp], ["RLA", M.IndX], ["BIT", M.Zp], ["AND", M.Zp], ["ROL", M.Zp], ["RLA", M.Zp], ["PLP", M.Imp], ["AND", M.Imm], ["ROL", M.Acc], ["ANC", M.Imm], ["BIT", M.Abs], ["AND", M.Abs], ["ROL", M.Abs], ["RLA", M.Abs]],
+    // 0x30-0x3F
+    [["BMI", M.Rel], ["AND", M.IndY], ["HLT", M.Imp], ["RLA", M.IndY], ["NOP", M.ZpX], ["AND", M.ZpX], ["ROL", M.ZpX], ["RLA", M.ZpX], ["SEC", M.Imp], ["AND", M.AbsY], ["NOP", M.Imp], ["RLA", M.AbsY], ["NOP", M.AbsX], ["AND", M.AbsX], ["ROL", M.AbsX], ["RLA", M.AbsX]],
+    // 0x40-0x4F
+    [["RTI", M.Imp], ["EOR", M.IndX], ["HLT", M.Imp], ["LSE", M.IndX], ["NOP", M.Zp], ["EOR", M.Zp], ["LSR", M.Zp], ["LSE", M.Zp], ["PHA", M.Imp], ["EOR", M.Imm], ["LSR", M.Acc], ["ALR", M.Imm], ["JMP", M.Abs], ["EOR", M.Abs], ["LSR", M.Abs], ["LSE", M.Abs]],
+    // 0x50-0x5F
+    [["BVC", M.Rel], ["EOR", M.IndY], ["HLT", M.Imp], ["LSE", M.IndY], ["NOP", M.ZpX], ["EOR", M.ZpX], ["LSR", M.ZpX], ["LSE", M.ZpX], ["CLI", M.Imp], ["EOR", M.AbsY], ["NOP", M.Imp], ["LSE", M.AbsY], ["NOP", M.AbsX], ["EOR", M.AbsX], ["LSR", M.AbsX], ["LSE", M.AbsX]],
+    // 0x60-0x6F
+    [["RTS", M.Imp], ["ADC", M.IndX], ["HLT", M.Imp], ["RRA", M.IndX], ["NOP", M.Zp], ["ADC", M.Zp], ["ROR", M.Zp], ["RRA", M.Zp], ["PLA", M.Imp], ["ADC", M.Imm], ["ROR", M.Acc], ["ARR", M.Imm], ["JMP", M.Ind], ["ADC", M.Abs], ["ROR", M.Abs], ["RRA", M.Abs]],
+    // 0x70-0x7F
+    [["BVS", M.Rel], ["ADC", M.IndY], ["HLT", M.Imp], ["RRA", M.IndY], ["NOP", M.ZpX], ["ADC", M.ZpX], ["ROR", M.ZpX], ["RRA", M.ZpX], ["SEI", M.Imp], ["ADC", M.AbsY], ["NOP", M.Imp], ["RRA", M.AbsY], ["NOP", M.AbsX], ["ADC", M.AbsX], ["ROR", M.AbsX], ["RRA", M.AbsX]],
+    // 0x80-0x8F
+    [["NOP", M.Imm], ["STA", M.IndX], ["NOP", M.Imm], ["SAX", M.IndX], ["STY", M.Zp], ["STA", M.Zp], ["STX", M.Zp], ["SAX", M.Zp], ["DEY", M.Imp], ["NOP", M.Imm], ["TXA", M.Imp], ["XAA", M.Imm], ["STY", M.Abs], ["STA", M.Abs], ["STX", M.Abs], ["SAX", M.Abs]],
+    // 0x90-0x9F
+    [["BCC", M.Rel], ["STA", M.IndY], ["HLT", M.Imp], ["AHX", M.IndY], ["STY", M.ZpX], ["STA", M.ZpX], ["STX", M.ZpY], ["SAX", M.ZpY], ["TYA", M.Imp], ["STA", M.AbsY], ["TXS", M.Imp], ["TAS", M.AbsY], ["SHY", M.AbsX], ["STA", M.AbsX], ["SHX", M.AbsY], ["AHX", M.AbsY]],
+    // 0xA0-0xAF
+    [["LDY", M.Imm], ["LDA", M.IndX], ["LDX", M.Imm], ["LAX", M.IndX], ["LDY", M.Zp], ["LDA", M.Zp], ["LDX", M.Zp], ["LAX", M.Zp], ["TAY", M.Imp], ["LDA", M.Imm], ["TAX", M.Imp], ["LAX", M.Imm], ["LDY", M.Abs], ["LDA", M.Abs], ["LDX", M.Abs], ["LAX", M.Abs]],
+    // 0xB0-0xBF
+    [["BCS", M.Rel], ["LDA", M.IndY], ["HLT", M.Imp], ["LAX", M.IndY], ["LDY", M.ZpX], ["LDA", M.ZpX], ["LDX", M.ZpY], ["LAX", M.ZpY], ["CLV", M.Imp], ["LDA", M.AbsY], ["TSX", M.Imp], ["LAS", M.AbsY], ["LDY", M.AbsX], ["LDA", M.AbsX], ["LDX", M.AbsY], ["LAX", M.AbsY]],
+    // 0xC0-0xCF
+    [["CPY", M.Imm], ["CMP", M.IndX], ["NOP", M.Imm], ["DCM", M.IndX], ["CPY", M.Zp], ["CMP", M.Zp], ["DEC", M.Zp], ["DCM", M.Zp], ["INY", M.Imp], ["CMP", M.Imm], ["DEX", M.Imp], ["AXS", M.Imm], ["CPY", M.Abs], ["CMP", M.Abs], ["DEC", M.Abs], ["DCM", M.Abs]],
+    // 0xD0-0xDF
+    [["BNE", M.Rel], ["CMP", M.IndY], ["HLT", M.Imp], ["DCM", M.IndY], ["NOP", M.ZpX], ["CMP", M.ZpX], ["DEC", M.ZpX], ["DCM", M.ZpX], ["CLD", M.Imp], ["CMP", M.AbsY], ["NOP", M.Imp], ["DCM", M.AbsY], ["NOP", M.AbsX], ["CMP", M.AbsX], ["DEC", M.AbsX], ["DCM", M.AbsX]],
+    // 0xE0-0xEF
+    [["CPX", M.Imm], ["SBC", M.IndX], ["NOP", M.Imm], ["INS", M.IndX], ["CPX", M.Zp], ["SBC", M.Zp], ["INC", M.Zp], ["INS", M.Zp], ["INX", M.Imp], ["SBC", M.Imm], ["NOP", M.Imp], ["SBC", M.Imm], ["CPX", M.Abs], ["SBC", M.Abs], ["INC", M.Abs], ["INS", M.Abs]],
+    // 0xF0-0xFF
+    [["BEQ", M.Rel], ["SBC", M.IndY], ["HLT", M.Imp], ["INS", M.IndY], ["NOP", M.ZpS], ["SBC", M.ZpX], ["INC", M.ZpX], ["INS", M.ZpX], ["SED", M.Imp], ["SBC", M.AbsY], ["NOP", M.Imp], ["INS", M.AbsY], ["NOP", M.AbsX], ["SBC", M.AbsX], ["INC", M.AbsX], ["INS", M.AbsX]],
+];
+const ILLEGAL_MAP = [
+    0x989C, 0x9C9C, 0x888C, 0x9C9C,
+    0x889C, 0x9C9C, 0x889C, 0x9C9C,
+    0x8A8D, 0xD88C, 0x8888, 0x888C,
+    0x888C, 0x9C9C, 0x888C, 0x9C9C,
+];
+function isIllegal(opcode) {
+    const row = ILLEGAL_MAP[opcode >> 4];
+    return ((row >> (opcode & 0x0F)) & 1) !== 0;
+}
+function canonical(mnemonic) {
+    switch (mnemonic) {
+        case "HLT": return "JAM";
+        case "ASO": return "SLO";
+        case "LSE": return "SRE";
+        case "DCM": return "DCP";
+        case "INS": return "ISC";
+        default: return mnemonic;
+    }
+}
+function buildOpcodeInventory() {
+    const entries = OPCODE_ROWS.flatMap((row, rowIndex) => row.map(([mnemonic, mode], columnIndex) => {
+        const opcode = (rowIndex << 4) | columnIndex;
+        return {
+            opcode,
+            mnemonic: canonical(mnemonic),
+            mode,
+            illegal: isIllegal(opcode),
+        };
+    }));
+    validateOpcodeInventory(entries);
+    return entries;
+}
+function validateOpcodeInventory(entries) {
+    if (entries.length !== 256) {
+        throw new Error(`Opcode inventory must contain 256 entries, found ${entries.length}`);
+    }
+    for (let opcode = 0; opcode < 256; opcode += 1) {
+        const entry = entries[opcode];
+        if (!entry || entry.opcode !== opcode) {
+            throw new Error(`Opcode inventory is not sorted at $${opcode.toString(16).padStart(2, "0")}`);
+        }
+    }
+}
+export function opcodeSize(mode) {
+    switch (mode) {
+        case M.Imp:
+        case M.Acc:
+            return 1;
+        case M.Imm:
+        case M.Zp:
+        case M.ZpX:
+        case M.ZpY:
+        case M.ZpS:
+        case M.Rel:
+        case M.IndX:
+        case M.IndY:
+            return 2;
+        case M.Abs:
+        case M.AbsX:
+        case M.AbsY:
+        case M.Ind:
+            return 3;
+    }
+}
+export const OPCODE_INVENTORY = Object.freeze(buildOpcodeInventory());
+export const OPCODES_BY_BYTE = OPCODE_INVENTORY;

package/dist/tools/translation/symbolRegistry.js

@@ -0,0 +1,49 @@
+/**
+ * In-process symbol registry for VICE debug sessions.
+ * Maps addresses to label names so the disassembler can annotate output.
+ * Cleared and repopulated each time a new program is loaded.
+ */
+const viceAddressToLabel = new Map();
+export function setViceSymbols(nameToAddress) {
+    viceAddressToLabel.clear();
+    for (const [name, address] of nameToAddress) {
+        if (address >= 0 && address <= 0xffff) {
+            viceAddressToLabel.set(address, name);
+        }
+    }
+}
+export function getViceSymbol(address) {
+    return viceAddressToLabel.get(address);
+}
+export function clearViceSymbols() {
+    viceAddressToLabel.clear();
+}
+export function getViceSymbols() {
+    return viceAddressToLabel;
+}
+/**
+ * Parse a VICE symbol file (.vs) into a name->address map.
+ *
+ * Supported line formats:
+ *   add_label 0x0810 .main
+ *   add_label C:0810 .main
+ *   al C:0810 .main
+ *   al 0810 .main
+ */
+export function parseViceSymbolFile(content) {
+    const symbols = new Map();
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(";") || line.startsWith("#"))
+            continue;
+        const match = /^(?:add_label|al)\s+(?:[A-Za-z]+:)?(?:0x|\$)?([0-9A-Fa-f]+)\s+\.?(\S+)/i.exec(line);
+        if (match) {
+            const addr = parseInt(match[1], 16);
+            const name = match[2];
+            if (!isNaN(addr) && addr >= 0 && addr <= 0xffff && name) {
+                symbols.set(name, addr);
+            }
+        }
+    }
+    return symbols;
+}

package/dist/tools/types.js

@@ -36,16 +36,30 @@ export function discriminatedUnionSchema(options) {
     const opValues = [];
     const mergedProperties = {};
     const opDescriptions = [];
+    const operationMetadata = [];
     for (const variant of variants) {
         const variantProps = variant.properties ?? {};
         const discProp = variantProps[discriminator];
         const opValue = discProp?.const;
+        const variantDesc = variant.description ?? discProp?.description ?? "";
+        const requiredInputs = (variant.required ?? []).filter((name) => name !== discriminator);
+        const optionalInputs = Object.keys(variantProps).filter((name) => name !== discriminator && !requiredInputs.includes(name));
         if (opValue) {
             opValues.push(opValue);
-            const variantDesc = variant.description ?? discProp?.description ?? "";
-            if (variantDesc) {
-                opDescriptions.push(`${opValue}: ${variantDesc}`);
-            }
+            const requiredSummary = requiredInputs.length > 0
+                ? ` Required inputs: ${requiredInputs.join(", ")}.`
+                : " Required inputs: none.";
+            const optionalSummary = optionalInputs.length > 0
+                ? ` Optional inputs: ${optionalInputs.join(", ")}.`
+                : "";
+            opDescriptions.push(`${opValue}: ${variantDesc || `Operation ${opValue}`}${requiredSummary}${optionalSummary}`);
+            operationMetadata.push({
+                op: opValue,
+                ...(variantDesc ? { description: variantDesc } : {}),
+                required: requiredInputs,
+                optional: optionalInputs,
+                inputSchema: variant,
+            });
         }
         for (const [key, propSchema] of Object.entries(variantProps)) {
             if (key === discriminator)
@@ -74,6 +88,7 @@ export function discriminatedUnionSchema(options) {
         },
         required: [discriminator],
         additionalProperties: false,
+        ...(operationMetadata.length > 0 ? { "x-c64bridge-operations": operationMetadata } : {}),
     };
     return schema;
 }

package/dist/vice/process.js

@@ -187,8 +187,19 @@ export async function terminateProcess(child, signal = "SIGTERM", timeoutMs = 10
 }
 export async function startViceProcess(options) {
     const debugEnabled = process.env.VICE_DEVICE_TEST_DEBUG === "1";
-    const { useXvfb, display: requestedDisplay } = shouldUseXvfb(options.visible);
-    const display = useXvfb ? resolveXvfbDisplayForLaunch(requestedDisplay) : requestedDisplay;
+    // When headless=true, skip Xvfb entirely and rely on VICE's own -headless flag (VICE 3.5+).
+    const useHeadless = options.headless === true || process.env.VICE_HEADLESS === "1";
+    let useXvfb;
+    let display;
+    if (useHeadless) {
+        useXvfb = false;
+        display = "";
+    }
+    else {
+        const probe = shouldUseXvfb(options.visible);
+        useXvfb = probe.useXvfb;
+        display = useXvfb ? resolveXvfbDisplayForLaunch(probe.display) : probe.display;
+    }
     const viceEnv = { ...process.env };
     let xvfb = null;
     const xvfbOutput = createOutputTailCapture("xvfb");
@@ -198,6 +209,7 @@ export async function startViceProcess(options) {
         directory: options.directory,
         display,
         extraArgs: options.extraArgs ?? [],
+        headless: useHeadless,
         host: options.host,
         port: options.port,
         useXvfb,
@@ -239,6 +251,7 @@ export async function startViceProcess(options) {
         "-binarymonitoraddress", `${options.host}:${options.port}`,
         "-sounddev", "dummy",
         "-config", "/dev/null",
+        ...(useHeadless ? ["-headless"] : []),
         ...(options.directory ? ["-directory", options.directory] : []),
         ...(options.extraArgs ?? []),
     ];
@@ -370,15 +383,43 @@ export async function startViceProcess(options) {
     });
     return { host: options.host, port: options.port, process: child, stop };
 }
+function isIgnorableSocketDirError(error) {
+    if (!error || typeof error !== "object" || !("code" in error)) {
+        return false;
+    }
+    const code = String(error.code ?? "");
+    return code === "EACCES" || code === "EPERM" || code === "EROFS" || code === "EEXIST";
+}
 export function ensureXvfbSocketDir(debugEnabled) {
     const socketDir = "/tmp/.X11-unix";
     try {
         if (!fs.existsSync(socketDir)) {
             fs.mkdirSync(socketDir, { mode: 0o1777 });
         }
+    }
+    catch (error) {
+        if (isIgnorableSocketDirError(error)) {
+            if (debugEnabled) {
+                console.error("[vice-process] unable to create Xvfb socket dir; continuing", error);
+            }
+            return;
+        }
+        writeDiagnosticEvent("xvfb_socket_dir_failed", { socketDir, error });
+        if (debugEnabled) {
+            console.error("[vice-process] failed to prepare Xvfb socket dir", error);
+        }
+        return;
+    }
+    try {
         fs.chmodSync(socketDir, 0o1777);
     }
     catch (error) {
+        if (isIgnorableSocketDirError(error)) {
+            if (debugEnabled) {
+                console.error("[vice-process] unable to chmod Xvfb socket dir; continuing", error);
+            }
+            return;
+        }
         writeDiagnosticEvent("xvfb_socket_dir_failed", { socketDir, error });
         if (debugEnabled) {
             console.error("[vice-process] failed to prepare Xvfb socket dir", error);

package/dist/vice/viceClient.js

@@ -9,6 +9,9 @@ export class ViceClient {
         this.pending = new Map();
         this.closing = false;
     }
+    setUnsolicitedHandler(handler) {
+        this.onUnsolicitedHandler = handler;
+    }
     async connect(port, host = "127.0.0.1") {
         this.socket = net.connect({ host, port });
         this.closing = false;
@@ -77,7 +80,8 @@ export class ViceClient {
             const err = frame[7];
             const reqId = frame.readUInt32LE(8);
             if (reqId === 0xffffffff) {
-                continue; // unsolicited event
+                this.onUnsolicitedHandler?.(responseType, frame);
+                continue;
             }
             const pending = this.pending.get(reqId);
             if (!pending) {

package/doc/reviews/audit.md

@@ -0,0 +1,143 @@
+# C64 Bridge MCP Server Audit
+
+## Scope
+
+This audit reviews the C64 Bridge repository as an MCP server for C64 Ultimate/C64U REST devices and VICE emulator control. It covers server initialization, tool/resource/prompt registration, tool schemas and results, device-control safety, VICE integration, C64 Ultimate integration, documentation consistency, and test/coverage architecture.
+
+## Assumptions
+
+- The local repository is the source of truth for supported behavior.
+- The current branch is `fix/readme`.
+- Pre-existing modified `data/**` files are user-owned unless a finding specifically requires editing them.
+- Real hardware is not required for fixes where mock or emulator tests cover the behavior.
+- Compatibility aliases for removed legacy resource URIs are not required; tests already assert legacy URI rejection.
+
+## Methodology
+
+1. Inspected repository layout, package scripts, README, AGENTS instructions, skill routing, and MCP generated artifacts.
+2. Inspected `src/mcp-server.ts`, tool registries, schema utilities, knowledge resource registry, VICE backend, C64U backend, and client device-control helpers.
+3. Ran baseline install/build/test/coverage commands.
+4. Scanned for top-level tool schema combinators, stale resource URIs, broad validation gaps, and hidden-result patterns.
+5. Classified findings with the requested severity model and mapped fixes to tests.
+
+## Repository Areas Inspected
+
+- `src/mcp-server.ts`
+- `src/tools/**`
+- `src/rag/resourceUris.ts`
+- `src/rag/knowledgeIndex.ts`
+- `src/c64Client.ts`
+- `src/device.ts`
+- `src/vice/**`
+- `src/prompts/registry.ts`
+- `scripts/run-coverage.mjs`
+- `scripts/run-tests.ts`
+- `README.md`
+- `AGENTS.md`
+- `.github/skills/**`
+- `mcp/**`
+- `test/**`
+
+## MCP Server Design Review
+
+The server uses the official TypeScript MCP SDK and registers `resources/list`, `resources/read`, `tools/list`, `tools/call`, `prompts/list`, and `prompts/get` handlers over stdio. Diagnostics are written to stderr/files, leaving stdout for the MCP protocol. Tool errors are returned as tool results with `isError`, which matches MCP expectations for model-visible tool failures.
+
+Confirmed non-issue: optional HTTP CLI parsing exists but current `main()` always connects stdio; the README describes stdio as canonical. No fix is required for this audit because no HTTP server path is advertised as the normal agent transport.
+
+## Tool Design Review
+
+Most public tools are grouped under names such as `c64_program`, `c64_memory`, `c64_config`, and `c64_sound` with an `op` discriminator. The shared `discriminatedUnionSchema` intentionally flattens operations to avoid top-level `oneOf`, which is correct for common MCP/LLM client compatibility.
+
+Confirmed issue: `c64_input` is an outlier and still exposes top-level `oneOf` plus `discriminator`. Its metadata also references `c64://specs/assembly` and `c64://specs/memory-map`, which are not registered resources.
+
+## Resource URI Design Review
+
+Canonical resources use the `c64://` scheme with concise namespaces such as `guide`, `basic`, `assembly`, `graphics`, `sound`, `memory`, `io`, `printer`, `vice`, and `platform`. The registered resource list is stable, discoverable, and documented in README-generated sections. Tests assert old legacy URI forms are rejected.
+
+Confirmed non-issue: legacy resource aliases do not need to be preserved because repository tests already reject legacy direct reads.
+
+Confirmed issue: tool metadata in `c64_input` points to stale `c64://specs/*` URIs outside the canonical resource set.
+
+## Device-Control Safety Review
+
+The tool layer generally bounds address lengths, file image parameters, stream names, joystick values, and grouped operations. Memory mutation paths support verification and C64U pause/resume where applicable.
+
+Confirmed issue: lower-level client parsing accepts partial numeric literals through `parseInt`, so values such as `$04ZZ` can resolve to `$0004`. Hex byte parsing can also silently truncate through `Buffer.from(value, "hex")`, so malformed data such as `$AAZZ` can become `$AA`. Raw memory helpers do not consistently reject address ranges that cross `$FFFF` before calling a backend.
+
+## VICE Integration Review
+
+VICE support is separated through `ViceBackend`, `ViceClient`, readiness helpers, and Binary Monitor guidance resources. Tests cover monitor framing, single-client behavior, process launch, readiness, resource get/set, mock and device smoke paths. Joystick simulation is correctly marked VICE-only at operation-platform level.
+
+Confirmed issue: `c64_input` schema compatibility affects VICE joystick discoverability in some clients.
+
+## C64 Ultimate REST Integration Review
+
+C64U REST base URLs are normalized through config and environment handling. Network passwords are sent as `X-Password`. HTTP clients use timeouts. Tests cover mock REST endpoints, password behavior, memory, runners, drives, config, streams, and files.
+
+Possible issue requiring external confirmation: local option-list validation for arbitrary C64U configuration values is limited because firmware-provided option inventories are not fully represented in repository data. The current safe approach is to list/read config first and rely on firmware rejection for unknown values. This was not fixed without a reliable local option source.
+
+## Error Handling Review
+
+Tool errors are normalized through `ToolValidationError`, `ToolExecutionError`, `toolErrorResult`, and `unknownErrorResult`. Tool-level failures are model-visible rather than protocol-level except for unknown tool lookup through registry invocation.
+
+Confirmed issue: memory parse failures for partial literals are not reliably raised today, reducing the value of this error-handling layer for device safety.
+
+## Schema/Input Validation Review
+
+Most grouped tools use flattened schemas with enum-constrained `op`. String, number, boolean, array, object, and optional schema helpers enforce runtime validation.
+
+Confirmed issue: `c64_input` still has a top-level `oneOf`.
+
+Confirmed issue: C64Client numeric and hex parsing needs stricter validation below the tool layer so public methods and internal raw paths fail safely.
+
+## Documentation Review
+
+README, AGENTS, skills, and generated `mcp/**` files are broadly consistent with current grouped tool names and canonical resource URIs. README resource lists are generated.
+
+Confirmed issue: generated `mcp/tools.json` and schema output inherit the stale `c64_input` resources and top-level `oneOf` until source is fixed and generation reruns.
+
+## Test Architecture and Coverage Review
+
+The repository has broad unit, integration, MCP harness, VICE mock, and VICE device tests. `npm test` passes. Coverage is intended to be enforced by `scripts/run-coverage.mjs` and `.c8rc.json` with 90% thresholds.
+
+Confirmed issue: baseline `npm run coverage` failed after passing shards because the wrapper attempted to copy a missing `coverage/lcov.info` for the VICE device shard.
+
+## Findings
+
+| ID | Severity | Area | Finding | Evidence | Impact | Recommended fix | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| MCP-AUDIT-001 | High | Device-control safety | Numeric and hex parsing can accept partial malformed input, and raw memory access lacks consistent 64 KB range guards. | `src/c64Client.ts` uses `parseInt`; `hexStringToBuffer` and `src/tools/memory.ts` parse hex through `Buffer.from(..., "hex")`; raw reads/writes do not consistently validate range overflow. | Malformed addresses or bytes can target the wrong memory location or write truncated data before a device call fails. | Enforce full-literal parsing, strict hex validation, and range checks before memory reads/writes. Add regression tests. | Planned |
+| MCP-AUDIT-002 | High | MCP schema/resource metadata | `c64_input` exposes top-level `oneOf`/`discriminator` and stale `c64://specs/*` resources. | `src/tools/input.ts`; generated `mcp/tools.json` and `mcp/schemas/c64_input.schema.json`. | Some MCP/LLM clients may fail to call the tool, and metadata points agents to resources that cannot be read. | Use flattened `discriminatedUnionSchema` and canonical resources. Regenerate MCP artifacts and tests. | Planned |
+| MCP-AUDIT-003 | Medium | Coverage architecture | Coverage command fails with `ENOENT` copying `coverage/lcov.info` after VICE device shard. | Baseline `npm run coverage` failed in `scripts/run-coverage.mjs:181`. | Required coverage verification cannot complete reliably even when tests pass. | Make the wrapper robust to Bun temporary LCOV output and add script regression tests. | Planned |
+| MCP-AUDIT-004 | Low | Dependency hygiene | `npm install` reports 1 moderate and 1 high vulnerability. | Baseline install output. | Potential dependency risk, but not enough local evidence to safely upgrade during this audit. | Defer to a dependency/security review with package upgrade testing. | Deferred |
+| MCP-AUDIT-005 | Trivial | Formatting | Some inspected source has indentation inconsistencies. | `src/rag/knowledgeIndex.ts`, `src/tools/memory.ts`. | Cosmetic only. | Defer unless adjacent to required edits. | Deferred |
+
+## Fix Plan Mapped To Findings
+
+- MCP-AUDIT-001: update strict parsers and range guards in `src/c64Client.ts` and `src/tools/memory.ts`; update `test/c64ClientInvalidInputs.test.mjs` and `test/memory.test.mjs`.
+- MCP-AUDIT-002: update `src/tools/input.ts`; update input/schema tests; regenerate `README.md` and `mcp/**` via `npm run build`.
+- MCP-AUDIT-003: update `scripts/run-coverage.mjs`; update `test/scripts/run-coverage.test.mjs`.
+
+## Confirmed Issues
+
+- MCP-AUDIT-001
+- MCP-AUDIT-002
+- MCP-AUDIT-003
+
+## Possible Issues Requiring External Confirmation
+
+- Full local option-list validation for C64U firmware configuration values depends on firmware-provided category/item/value metadata not present in repository evidence.
+
+## Non-Issues
+
+- Legacy resource URI aliases are intentionally absent.
+- Stdio-first transport is consistent with repository instructions.
+- VICE Binary Monitor reference is present and routed through canonical resource and skills.
+
+## Trivialities Intentionally Deferred
+
+- Formatting-only indentation cleanup not adjacent to required edits.
+
+## Final Status After Implementation
+
+Implementation has not yet started. This section will be updated after fixes and final verification.