c64bridge 0.9.3 → 1.0.1

package/dist/tools/pollValidator.js

@@ -75,13 +75,7 @@ function concatBuffers(...buffers) {
  * Looks for patterns like "?SYNTAX ERROR" or "SYNTAX ERROR IN 120".
  */
 function extractBasicError(screen) {
-    const upperScreen = screen.toUpperCase();
-    // Check if ERROR appears on screen
-    if (!upperScreen.includes("ERROR")) {
-        return null;
-    }
-    // Try to match "?ERROR_TYPE ERROR" or "ERROR_TYPE ERROR IN LINE"
-    const errorMatch = /\?([A-Z\s]+)\s+ERROR(?:\s+IN\s+(\d+))?/i.exec(screen);
+    const errorMatch = /(?:^|\n)\s*\?([A-Z\s]+?)\s+ERROR(?:\s+IN\s+(\d+))?(?=\s|$)/im.exec(screen); // A real error has a leading "?"; ordinary output like "0 ERRORS FOUND" must never match.
     if (errorMatch) {
         const errorType = errorMatch[1]?.trim().replace(/\s+/g, " ");
         const lineStr = errorMatch[2];
@@ -91,8 +85,7 @@ function extractBasicError(screen) {
             line: Number.isFinite(line) ? line : undefined,
         };
     }
-    // Fallback: just "ERROR" appears
-    return { message: "UNKNOWN ERROR" };
+    return null;
 }
 /**
  * Poll for BASIC program outcome by detecting errors on screen.
@@ -124,17 +117,20 @@ async function pollBasicOutcome(client, logger, config) {
                     line: errorInfo.line,
                 };
             }
-            // If we detected RUN and no error yet, continue polling
-            if (runDetected) {
-                // Continue polling for a bit to catch any delayed errors
-                // but if we've been polling for a while without errors, consider it successful
-            }
         }
         catch (error) {
             logger.debug("Failed to read screen during BASIC polling", { error, pollCount });
         }
         await delay(config.intervalMs);
     }
+    if (!runDetected) { // Neither "RUN" nor an error ever appeared for the whole window. On working backends the firmware's own LOAD/RUN echo shows this text, so its total absence means execution never started despite the reported success (HARD01-011/036).
+        logger.debug("BASIC polling completed without ever observing RUN or an error", { pollCount, elapsed: Date.now() - startTime });
+        return {
+            status: "error",
+            type: "BASIC",
+            message: "No execution activity detected: the firmware reported success, but the program does not appear to have run.",
+        };
+    }
     logger.debug("BASIC polling completed without errors", { pollCount, elapsed: Date.now() - startTime });
     return {
         status: "ok",
@@ -178,38 +174,20 @@ async function pollAsmOutcome(client, logger, config) {
         }
         await delay(config.intervalMs);
     }
-    // If RUN never appeared, assume instant execution (success)
-    if (!runDetected) {
-        logger.debug("RUN never detected, assuming instant execution");
-        return {
-            status: "ok",
-            type: "ASM",
-        };
+    if (!runDetected) { // Fall through to the liveness check rather than assuming success. Skipping it here used to report false success for any run that never types anything visible, e.g. a firmware run_prg that silently no-ops instead of running the PRG (HARD01-036).
+        logger.debug("RUN never detected; falling through to hardware liveness check instead of assuming success");
     }
-    // Now poll hardware regions to detect activity
-    let prevIoSignature = null;
-    let prevJiffyClock = null;
+    let previousSignature = null; // Only stable RAM: reading I/O can ack CIA interrupts on Ultimate, and raster/timer values aren't evidence of liveness.
     let alive = false;
     const pollDeadline = Date.now() + config.maxMs;
     while (Date.now() < pollDeadline && !alive) {
         pollCount++;
         try {
-            // Read I/O regions in optimized batches as per comment #3466803675
-            // All of $D000-$DFFF in a single call (covers VIC-II, SID, CIA1, CIA2)
-            const ioRegions = await client.readMemoryRaw(0xD000, 0x1000); // $D000-$DFFF
-            // Read low memory through screen RAM in a single call: $0000-$07E7
-            // This covers zero page, stack, jiffy clock ($00A0-$00A2), and screen memory
-            const lowMemAndScreen = await client.readMemoryRaw(0x0000, 0x7E8); // $0000-$07E7
-            // Extract jiffy clock for separate comparison (at offset $00A0 in the buffer)
-            const jiffyClock = lowMemAndScreen.slice(0xA0, 0xA3);
-            // Exclude the jiffy clock from the broad signature so it can be tracked separately.
-            const lowMemSignatureBuffer = lowMemAndScreen.slice();
-            lowMemSignatureBuffer.fill(0, 0xA0, 0xA3);
-            const combinedBuffer = concatBuffers(ioRegions, lowMemSignatureBuffer);
-            const ioSignature = computeCrc32(combinedBuffer);
+            const screenRam = await client.readMemoryRaw(0x0400, 0x03e8);
+            const signature = computeCrc32(screenRam);
             // Check for any activity
-            if (prevIoSignature !== null && ioSignature !== prevIoSignature) {
-                logger.debug("Hardware or screen activity detected", {
+            if (previousSignature !== null && signature !== previousSignature) {
+                logger.debug("Program-visible screen activity detected", {
                     pollCount,
                     elapsed: Date.now() - startTime,
                     signatureChanged: true
@@ -217,17 +195,7 @@ async function pollAsmOutcome(client, logger, config) {
                 alive = true;
                 break;
             }
-            if (prevJiffyClock !== null && !buffersEqual(jiffyClock, prevJiffyClock)) {
-                logger.debug("Jiffy clock advanced", {
-                    pollCount,
-                    elapsed: Date.now() - startTime,
-                    clockChanged: true
-                });
-                alive = true;
-                break;
-            }
-            prevIoSignature = ioSignature;
-            prevJiffyClock = jiffyClock;
+            previousSignature = signature;
         }
         catch (error) {
             logger.debug("Failed to read memory during ASM polling", { error, pollCount });
@@ -246,7 +214,7 @@ async function pollAsmOutcome(client, logger, config) {
     return {
         status: "crashed",
         type: "ASM",
-        reason: "no VIC/CIA/TI/screen progression within window",
+        reason: "no program-visible screen progression within window",
     };
 }
 /**

package/dist/tools/printer.js

@@ -225,6 +225,7 @@ function validateEpsonDensity(args) {
 }
 export const printerModule = defineToolModule({
     domain: "printer",
+    supportedPlatforms: ["c64u", "u2"],
     summary: "Printer workflow helpers for Commodore MPS and Epson FX devices, including prompt templates.",
     resources: [
         "c64://printer/spec",

package/dist/tools/programRunners.js

@@ -668,7 +668,7 @@ export const programRunnersModule = defineToolModule({
                 "Invoke right after you generate BASIC source so it runs on the C64 without extra user steps.",
                 "Ensure the program includes line numbers and uppercase keywords before calling the tool.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeUploadRunBasic(args, ctx);
             },
@@ -693,7 +693,7 @@ export const programRunnersModule = defineToolModule({
                 "Use when the user requests to run new 6502 code; surface any assembler diagnostics in your reply.",
                 "Mention the entry routine or important addresses after execution so the user can continue debugging.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeUploadRunAsm(args, ctx);
             },
@@ -717,7 +717,7 @@ export const programRunnersModule = defineToolModule({
                 "Stage PRG files without running when the user wants to inspect memory first.",
                 "Confirm the Ultimate filesystem path (e.g. //USB0/demo.prg) is accessible before invoking.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 return executeLoadPrg(args, ctx);
             },
@@ -733,7 +733,7 @@ export const programRunnersModule = defineToolModule({
                 "Call when the user provides a PRG path and expects immediate execution without compiling.",
                 "Mention that firmware issues a RUN so the user knows the machine state changed.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             prerequisites: ["drives_list"],
             examples: [
                 {
@@ -765,7 +765,7 @@ export const programRunnersModule = defineToolModule({
                     arguments: { path: "//USB0/game.crt" },
                 },
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     const parsed = crtFileArgsSchema.parse(args ?? {});

package/dist/tools/rag.js

@@ -181,7 +181,7 @@ export const ragModule = defineToolModule({
     ],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["rag", "search"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Call RAG tools when the user needs references or examples before generating new code.",
         "Summarise the number of refs returned and suggest follow-up actions like reading specific docs.",

package/dist/tools/registry/batch.js

@@ -35,7 +35,7 @@ const executeBatchArgsSchema = objectSchema({
 export const batchModuleGroup = defineToolModule({
     domain: "batch",
     summary: "Execute multiple tool calls in a single MCP request for reduced round-trip overhead.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: [],
     prompts: [],
     defaultTags: ["batch", "orchestration"],

package/dist/tools/registry/config.js

@@ -154,7 +154,7 @@ export const configModuleGroup = defineToolModule({
     resources: ["c64://guide/bootstrap", "c64://guide/index"],
     prompts: ["memory-debug"],
     defaultTags: ["config", "diagnostics"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "List categories before changing values so users can confirm firmware-provided names.",
         "Mention when operations persist to flash or modify debug registers to highlight impacts.",
@@ -171,12 +171,12 @@ export const configModuleGroup = defineToolModule({
             }),
             tags: ["config", "diagnostics", "grouped"],
             operationPlatforms: {
-                load_flash: ["c64u"],
-                save_flash: ["c64u"],
-                reset_defaults: ["c64u"],
+                load_flash: ["c64u", "u2"],
+                save_flash: ["c64u", "u2"],
+                reset_defaults: ["c64u", "u2"],
                 read_debugreg: ["c64u"],
                 write_debugreg: ["c64u"],
-                shuffle: ["c64u"],
+                shuffle: ["c64u", "u2"],
             },
             operationToolNames: {
                 load_flash: "config_load_from_flash",

package/dist/tools/registry/disk.js

@@ -251,7 +251,7 @@ const diskOperationHandlers = createOperationHandlers(diskOperations);
 export const diskModuleGroup = defineToolModule({
     domain: "storage",
     summary: "Grouped disk image management, mounting, and discovery tools.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     prompts: ["drive-management"],
     defaultTags: ["storage", "drive"],
@@ -269,7 +269,7 @@ export const diskModuleGroup = defineToolModule({
                 variants: diskOperations.map((operation) => operation.schema),
             }),
             tags: ["storage", "drive", "grouped"],
-            operationPlatforms: { file_info: ["c64u"], create_image: ["c64u"], find_and_run: ["c64u"] },
+            operationPlatforms: { file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"] },
             operationToolNames: {
                 file_info: "file_info",
                 create_image: "create_image",

package/dist/tools/registry/drive.js

@@ -33,7 +33,7 @@ const driveOperationHandlers = createOperationHandlers(driveOperations);
 export const driveModuleGroup = defineToolModule({
     domain: "drive",
     summary: "Grouped drive power, reset, ROM, and mode helpers.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     defaultTags: ["drive", "hardware"],
     workflowHints: [
@@ -50,7 +50,7 @@ export const driveModuleGroup = defineToolModule({
                 variants: driveOperations.map((operation) => operation.schema),
             }),
             tags: ["drive", "hardware", "grouped"],
-            operationPlatforms: { load_rom: ["c64u"] },
+            operationPlatforms: { load_rom: ["c64u", "u2"] },
             operationToolNames: { load_rom: "drive_load_rom" },
             examples: [
                 {

package/dist/tools/registry/graphics.js

@@ -89,7 +89,7 @@ function parseVicState(d011, d016, d018, dd00, d020, d021) {
     };
 }
 const getDisplayStateArgsSchema = objectSchema({
-    description: "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+    description: "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical.",
     properties: {
         op: literalSchema("get_display_state"),
     },
@@ -212,7 +212,7 @@ export const graphicsModuleGroup = defineToolModule({
         "Use render helpers for PETSCII text, PETSCII art, sprites, and bitmaps; clarify whether PETSCII art executed or stayed a dry run.",
         "Mention sprite positions/colours so follow-up memory inspection stays grounded.",
     ],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     tools: [
         {
             name: "c64_graphics",

package/dist/tools/registry/memory.js

@@ -27,7 +27,7 @@ const memoryOperations = [
     },
     {
         op: "disassemble",
-        schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE." }),
+        schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE." }),
         handler: groupedMemoryHandlers.disassemble,
     },
     {
@@ -60,7 +60,7 @@ const memoryOperationHandlers = createOperationHandlers(memoryOperations);
 export const memoryModuleGroup = defineToolModule({
     domain: "memory",
     summary: "Grouped memory, screen, and polling operations.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],

package/dist/tools/registry/platform.js

@@ -1,4 +1,5 @@
 import { describePlatformCapabilities } from "../../platform.js";
+import { cancelGeneratedSidPlayback } from "../audio.js";
 import { debugModuleGroup as debugModule } from "../debug.js";
 import { viceModuleGroup as viceModule } from "../vice.js";
 import { jsonResult } from "../responses.js";
@@ -50,7 +51,7 @@ const selectBackendSchema = operationSchema("select", {
     properties: {
         backend: {
             type: "string",
-            enum: ["c64u", "vice"],
+            enum: ["c64u", "u2", "vice"],
             description: "Backend to activate for subsequent tool calls.",
         },
     },
@@ -73,17 +74,20 @@ const platformOperationHandlers = {
                 isError: true,
             };
         }
+        cancelGeneratedSidPlayback(); // A backend switch is the documented cue to stop it rather than let it keep playing on the old backend.
         ctx.client.switchBackend(backend);
         ctx.setPlatform(backend);
         const { availableTools, unavailableTools } = describeTargetPlatform(backend);
-        const switchBackTarget = backend === "c64u" ? "vice" : "c64u";
+        const switchBackTarget = availableBackends.find((candidate) => candidate !== backend);
         const data = {
             success: true,
             activeBackend: backend,
             configuredBackends: availableBackends,
             availableTools,
             unavailableTools,
-            usageHint: `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`,
+            usageHint: switchBackTarget
+                ? `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`
+                : "No other backend is configured.",
         };
         return jsonResult(data, { success: true });
     },
@@ -91,7 +95,7 @@ const platformOperationHandlers = {
 export const platformModuleGroup = defineToolModule({
     domain: "platform",
     summary: "Runtime backend selection and platform-status coordination.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://platform/status", "c64://guide/bootstrap"],
     prompts: [],
     defaultTags: ["platform", "backend", "grouped"],
@@ -101,7 +105,7 @@ export const platformModuleGroup = defineToolModule({
     tools: [
         {
             name: "c64_select_backend",
-            description: "Switch the active backend between C64U hardware and the VICE emulator at runtime.",
+            description: "Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.",
             summary: "Changes the active backend without restarting the MCP server and reports resulting tool availability.",
             inputSchema: discriminatedUnionSchema({
                 description: "Runtime backend selection operations.",

package/dist/tools/registry/printer.js

@@ -116,6 +116,7 @@ function invokePrintTool(toolName, rawArgs, ctx) {
 }
 export const printerModuleGroup = defineToolModule({
     domain: "printer",
+    supportedPlatforms: ["c64u", "u2"],
     summary: "Grouped printer text, bitmap, and character definition helpers.",
     resources: ["c64://guide/bootstrap"],
     defaultTags: ["printer", "device"],

package/dist/tools/registry/program.js

@@ -12,7 +12,7 @@ const programOperations = [
     },
     {
         op: "run_prg",
-        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE." }),
+        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "run_prg", rawArgs, ctx),
     },
     {
@@ -55,10 +55,10 @@ export const programModule = defineToolModule({
     defaultTags: ["programs", "execution"],
     workflowHints: [
         "Choose BASIC or assembly uploaders based on the language you just generated for the user.",
-        "Prefer PRG or CRT runners when the user supplies a file path instead of source text; PRG paths are host-local on VICE and Ultimate-visible on c64u.",
-        "For a quick visible confirmation on VICE and/or C64U, prefer cross_platform_greeting instead of composing manual backend switches and BASIC upload steps.",
+        "Prefer PRG or CRT runners when the user supplies a file path instead of source text; PRG paths are host-local on VICE and Ultimate-visible on hardware.",
+        "For a quick visible confirmation on VICE, C64U/U64, or U2-family hardware, prefer cross_platform_greeting instead of composing manual backend switches and BASIC upload steps.",
     ],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     tools: [
         {
             name: "c64_program",
@@ -69,7 +69,7 @@ export const programModule = defineToolModule({
                 variants: programOperations.map((operation) => operation.schema),
             }),
             tags: ["programs", "execution", "grouped"],
-            operationPlatforms: { load_prg: ["c64u"], run_crt: ["c64u"], bundle_run: ["c64u"] },
+            operationPlatforms: { load_prg: ["c64u", "u2"], run_crt: ["c64u", "u2"], bundle_run: ["c64u", "u2"] },
             operationToolNames: {
                 load_prg: "load_prg",
                 run_crt: "run_crt",

package/dist/tools/registry/rag.js

@@ -25,7 +25,7 @@ export const ragModuleGroup = defineToolModule({
         "Use BASIC retrieval before synthesising new BASIC code and mention primary resources in responses.",
         "For assembly, note registers or addresses surfaced so the user can inspect them further.",
     ],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     tools: [
         {
             name: "c64_rag",

package/dist/tools/registry/sound.js

@@ -139,7 +139,7 @@ const soundOperationHandlers = createOperationHandlers(soundOperations);
 export const soundModuleGroup = defineToolModule({
     domain: "audio",
     summary: "Grouped SID control, playback, composition, and analysis operations.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://sound/sid/spec", "c64://sound/sidwave/spec", "c64://sound/sid/file-format"],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
@@ -159,9 +159,9 @@ export const soundModuleGroup = defineToolModule({
             tags: ["sid", "audio", "grouped"],
             operationPlatforms: {
                 capture_samples: ["c64u"],
-                play_sid_file: ["c64u"],
-                play_mod_file: ["c64u"],
-                pipeline: ["c64u"],
+                play_sid_file: ["c64u", "u2"],
+                play_mod_file: ["c64u", "u2"],
+                pipeline: ["c64u", "u2"],
                 analyze: ["c64u"],
                 record_analyze: ["c64u"],
             },

package/dist/tools/registry/system.js

@@ -30,11 +30,21 @@ const systemOperations = [
         schema: extendSchemaWithOp("poweroff", ensureDescriptor(machineDescriptorIndex, "poweroff").inputSchema, { description: "Request a controlled shutdown via the Ultimate firmware." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "poweroff", rawArgs, ctx),
     },
+    {
+        op: "power_cycle",
+        schema: extendSchemaWithOp("power_cycle", ensureDescriptor(machineDescriptorIndex, "power_cycle").inputSchema, { description: "Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "power_cycle", rawArgs, ctx),
+    },
     {
         op: "menu",
         schema: extendSchemaWithOp("menu", ensureDescriptor(machineDescriptorIndex, "menu_button").inputSchema, { description: "Toggle the Ultimate menu button for navigation." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "menu_button", rawArgs, ctx),
     },
+    {
+        op: "read_menu_screen",
+        schema: extendSchemaWithOp("read_menu_screen", ensureDescriptor(machineDescriptorIndex, "read_menu_screen").inputSchema, { description: "Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+)." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "read_menu_screen", rawArgs, ctx),
+    },
     {
         op: "start_task",
         schema: extendSchemaWithOp("start_task", ensureDescriptor(metaDescriptorIndex, "start_background_task").inputSchema, { description: "Start a named background task that runs on an interval." }),
@@ -65,7 +75,7 @@ const systemOperationHandlers = createOperationHandlers(systemOperations);
 export const systemModuleGroup = defineToolModule({
     domain: "system",
     summary: "Grouped machine control and background task orchestration.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["system", "control"],
@@ -83,8 +93,8 @@ export const systemModuleGroup = defineToolModule({
                 variants: systemOperations.map((operation) => operation.schema),
             }),
             tags: ["system", "control", "grouped"],
-            operationPlatforms: { pause: ["c64u"], resume: ["c64u"], menu: ["c64u"] },
-            operationToolNames: { pause: "pause", resume: "resume", menu: "menu_button" },
+            operationPlatforms: { pause: ["c64u", "u2"], resume: ["c64u", "u2"], menu: ["c64u", "u2"], read_menu_screen: ["c64u", "u2"] },
+            operationToolNames: { pause: "pause", resume: "resume", menu: "menu_button", read_menu_screen: "read_menu_screen" },
             examples: [
                 {
                     name: "Soft reset",

package/dist/tools/storage.js

@@ -143,7 +143,7 @@ const createDnpArgsSchema = objectSchema({
 export const storageModule = defineToolModule({
     domain: "storage",
     summary: "Drive management, disk image creation, and file inspection utilities.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["drive", "storage"],

package/dist/vice/mockServer.js

@@ -2,6 +2,10 @@ import net from "node:net";
 import { asciiToScreenCodes } from "./readiness.js";
 const SCREEN_BASE = 0x0400;
 const SCREEN_SIZE = 40 * 25;
+const KEYBOARD_BUFFER = 0x0277; // KERNAL keyboard buffer base ($0277), where a typed SYS command lands.
+const SYS_COMMAND_PATTERN = /SYS\s*\d+/i; // upload_run_asm enters an assembled program via a typed SYSnnnnn.
+const HEARTBEAT_GRANULARITY_MS = 10; // Well below the poll interval so consecutive liveness reads always differ.
+const HEARTBEAT_DURATION_MS = 1000; // How long a SYS-triggered program keeps "running".
 function buildDefaultRegisterMetadata() {
     return Object.freeze([
         { id: 0, name: "PC", bits: 16 },
@@ -30,6 +34,7 @@ export class ViceMockServer {
         this.server = null;
         this.memory = new Uint8Array(0x10000);
         this.helloReady = false;
+        this.heartbeat = null;
         this.checkpoints = new Map();
         this.nextCheckpointId = 1;
         this.registerMetadata = buildDefaultRegisterMetadata();
@@ -186,6 +191,7 @@ export class ViceMockServer {
                 for (let i = 0; i < length; i += 1) {
                     payload[2 + i] = this.memory[(start + i) & 0xffff];
                 }
+                this.applyHeartbeatOverlay(start, length, payload);
                 return buildResponse(cmd, reqId, payload);
             }
             case 0x02: { // mem set
@@ -197,6 +203,12 @@ export class ViceMockServer {
                 }
                 if (start <= SCREEN_BASE && end >= SCREEN_BASE) {
                     this.helloReady = false;
+                    this.heartbeat = null; // A client writing screen RAM has taken over; end any simulated run.
+                }
+                this.maybeStartAsmHeartbeat(start, end, payload);
+                const KEYBOARD_NDX = 0x00c6; // This mock runs no real 6502 code, so simulate the KERNAL IRQ draining $00C6 shortly after each write.
+                if (start <= KEYBOARD_NDX && end >= KEYBOARD_NDX) {
+                    setTimeout(() => { this.memory[KEYBOARD_NDX] = 0; }, 5).unref();
                 }
                 return buildResponse(cmd, reqId);
             }
@@ -411,6 +423,7 @@ export class ViceMockServer {
         this.memory[0x31] = 0x03;
         this.memory[0x32] = 0x08;
         this.helloReady = false;
+        this.heartbeat = null;
         this.checkpoints.clear();
         this.nextCheckpointId = 1;
         this.registerValues.clear();
@@ -431,6 +444,26 @@ export class ViceMockServer {
         hello.copy(Buffer.from(this.memory.buffer, offset, hello.length));
         this.helloReady = true;
     }
+    maybeStartAsmHeartbeat(start, end, payload) {
+        if (start > KEYBOARD_BUFFER || end < KEYBOARD_BUFFER)
+            return; // Only a write covering the KERNAL keyboard buffer can be a typed SYS trigger.
+        if (!SYS_COMMAND_PATTERN.test(payload.toString("ascii")))
+            return;
+        this.heartbeat = { startedAt: Date.now(), baseValue: this.memory[SCREEN_BASE] };
+    }
+    applyHeartbeatOverlay(start, length, payload) {
+        const heartbeat = this.heartbeat;
+        if (!heartbeat)
+            return;
+        const elapsed = Date.now() - heartbeat.startedAt;
+        if (elapsed < 0 || elapsed >= HEARTBEAT_DURATION_MS)
+            return;
+        const offset = SCREEN_BASE - start;
+        if (offset < 0 || offset >= length)
+            return;
+        const ticks = Math.floor(elapsed / HEARTBEAT_GRANULARITY_MS);
+        payload[2 + offset] = (heartbeat.baseValue + ticks) & 0xff;
+    }
 }
 export async function startViceMockServer(options) {
     const server = new ViceMockServer(options);

package/dist/vice/process.js

@@ -378,10 +378,20 @@ export async function startViceProcess(options) {
             await terminateProcess(xvfb, "SIGKILL", 200);
         }
     };
+    const stopSync = () => {
+        for (const process of [child, xvfb]) {
+            if (!process || process.exitCode !== null || process.signalCode !== null)
+                continue;
+            try {
+                process.kill("SIGKILL");
+            }
+            catch { }
+        }
+    };
     child.once("exit", async () => {
         await terminateProcess(xvfb, "SIGTERM", 0);
     });
-    return { host: options.host, port: options.port, process: child, stop };
+    return { host: options.host, port: options.port, process: child, stop, stopSync };
 }
 function isIgnorableSocketDirError(error) {
     if (!error || typeof error !== "object" || !("code" in error)) {