c64bridge 1.0.0 → 1.0.1

package/dist/tools/audio.js

@@ -9,6 +9,12 @@ const NOTE_PATTERN = /^([A-Ga-g])([#b]?)(-?\d+)$/;
 const DEFAULT_SILENCE_VERIFY_DURATION_SECONDS = 1.5;
 const DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD = 0.02;
 const DEFAULT_SILENCE_VERIFY_WAIT_MS = 150;
+const generatedPlaybacks = new Set();
+export function cancelGeneratedSidPlayback() {
+    for (const controller of generatedPlaybacks)
+        controller.abort();
+    generatedPlaybacks.clear();
+}
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -473,6 +479,7 @@ export const audioModule = defineToolModule({
                 try {
                     const parsed = sidResetArgsSchema.parse(args ?? {});
                     ctx.logger.info("Resetting SID", { mode: parsed.hard ? "hard" : "soft" });
+                    cancelGeneratedSidPlayback(); // Reset is the documented way to stop a generated arpeggio.
                     const result = await ctx.client.sidReset(parsed.hard);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 firmware reported failure while resetting SID", {
@@ -622,6 +629,7 @@ export const audioModule = defineToolModule({
                     const parsed = sidSilenceArgsSchema.parse(args ?? {});
                     const verify = Boolean(parsed.verify);
                     ctx.logger.info("Silencing all SID voices", { verify });
+                    cancelGeneratedSidPlayback(); // Otherwise its remaining notes would resume writing right after this silences the chip.
                     const result = await ctx.client.sidSilenceAll();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 firmware reported failure while silencing SID", {
@@ -812,10 +820,17 @@ export const audioModule = defineToolModule({
                         tempoMs: parsed.tempoMs,
                         waveform: parsed.waveform,
                     });
+                    cancelGeneratedSidPlayback(); // Replace any prior generated arpeggio rather than letting two run at once.
+                    const controller = new AbortController();
+                    generatedPlaybacks.add(controller);
+                    const pinnedFacadePromise = ctx.client.pinFacade ? ctx.client.pinFacade() : Promise.resolve(undefined); // Pin once so a later select_backend can't retarget notes mid-arpeggio (HARD01-030).
                     void (async () => {
                         try {
-                            await ctx.client.sidSetVolume(8);
+                            const pinnedFacade = await pinnedFacadePromise;
+                            await ctx.client.sidSetVolume(8, pinnedFacade);
                             for (let i = 0; i < parsed.steps; i += 1) {
+                                if (controller.signal.aborted)
+                                    break;
                                 const iv = intervals[i % intervals.length];
                                 const note = transposeNote(parsed.root, iv);
                                 await ctx.client.sidNoteOn({
@@ -827,18 +842,24 @@ export const audioModule = defineToolModule({
                                     decay: 7,
                                     sustain: 15,
                                     release: 0,
-                                });
+                                }, pinnedFacade);
                                 const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
-                                await sleep(durationMs);
+                                await sleep(Math.max(1, Math.min(20, Math.floor(durationMs / 8)))); // Clear GATE between notes so every note retriggers ADSR.
+                                await ctx.client.sidNoteOff(1, pinnedFacade);
+                                if (!controller.signal.aborted)
+                                    await sleep(Math.max(0, durationMs - Math.max(1, Math.min(20, Math.floor(durationMs / 8)))));
                             }
-                            await ctx.client.sidNoteOff(1);
+                            await ctx.client.sidNoteOff(1, pinnedFacade);
                         }
                         catch (playbackError) {
                             const message = playbackError instanceof Error ? playbackError.message : String(playbackError);
                             ctx.logger.warn("music_generate playback failed", { error: message });
                         }
+                        finally {
+                            generatedPlaybacks.delete(controller);
+                        }
                     })();
-                    return textResult(`Scheduled ${parsed.steps} note arpeggio starting on ${parsed.root}.`, {
+                    return textResult(`Scheduled ${parsed.steps} note arpeggio starting on ${parsed.root}. Playback is running and will be replaced by the next generated sequence.`, {
                         success: true,
                         root: parsed.root,
                         intervals,

package/dist/tools/input.js

@@ -91,13 +91,9 @@ function expandPetsciiTokens(text) {
 }
 // ---------------------------------------------------------------------------
 // Joystick helpers
-// Port 2 → CIA1 Port A ($DC00), Port 1 → CIA1 Port B ($DC01)
-// Bits 0-4: Up / Down / Left / Right / Fire, active LOW (0 = pressed)
+// Bits 0-4: Up / Down / Left / Right / Fire, active LOW (0 = pressed).
+// VICE must use Binary Monitor Joyport Set; CIA register writes are not input.
 // ---------------------------------------------------------------------------
-const JOYSTICK_PORT_ADDRESS = {
-    1: 0xDC01,
-    2: 0xDC00,
-};
 const JOYSTICK_BIT = {
     up: 0,
     down: 1,
@@ -174,11 +170,11 @@ export const keyArgsSchema = objectSchema({
     additionalProperties: false,
 });
 export const joystickArgsSchema = objectSchema({
-    description: "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
+    description: "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
     properties: {
         op: literalSchema("joystick"),
         port: numberSchema({
-            description: "Joystick port (1 = $DC01, 2 = $DC00).",
+            description: "Joystick port (1 or 2).",
             integer: true,
             minimum: 1,
             maximum: 2,
@@ -309,24 +305,23 @@ const inputOperationHandlers = {
                     success: true, port, action: parsed.action, controls: parsed.controls, state,
                 });
             }
-            const addr = JOYSTICK_PORT_ADDRESS[port];
             if (parsed.controls.some((control) => !(control in JOYSTICK_BIT))) {
                 throw new ToolValidationError("VICE joystick supports up, down, left, right, and fire only.", { path: "$.controls" });
             }
             if (parsed.action === "release") {
-                await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
-                ctx.logger.info("Released joystick", { port, address: `$${addr.toString(16).toUpperCase()}` });
+                await ctx.client.viceJoyportSet(port, releasedByte);
+                ctx.logger.info("Released joystick", { port });
                 return textResult(`Joystick port ${port} released.`, { success: true, port, action: "release" });
             }
             if (parsed.action === "press") {
-                await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+                await ctx.client.viceJoyportSet(port, pressedByte);
                 ctx.logger.info("Pressed joystick", { port, controls: parsed.controls, byte: pressedByte });
                 return textResult(`Joystick port ${port} pressed: ${parsed.controls.join(", ") || "none"}.`, { success: true, port, action: "press", controls: parsed.controls });
             }
             // tap: press → wait → release
-            await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+            await ctx.client.viceJoyportSet(port, pressedByte);
             await new Promise((res) => setTimeout(res, durationMs));
-            await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
+            await ctx.client.viceJoyportSet(port, releasedByte);
             ctx.logger.info("Tapped joystick", { port, controls: parsed.controls, durationMs });
             return textResult(`Joystick port ${port} tapped: ${parsed.controls.join(", ") || "none"} for ${durationMs}ms.`, { success: true, port, action: "tap", controls: parsed.controls, durationMs });
         }

package/dist/tools/memory.js

@@ -243,11 +243,12 @@ async function executeWriteMemory(rawArgs, ctx) {
                 details: detailRecord,
             });
         }
+        const pinnedFacade = ctx.client.pinFacade ? await ctx.client.pinFacade() : undefined; // Pin for this whole pause/read/write/resume sequence so a concurrent select_backend can't retarget it (HARD01-016).
         const canPause = supportsMachinePause(ctx);
         let paused = false;
         try {
             if (canPause) {
-                const pauseResult = await ctx.client.pause();
+                const pauseResult = await ctx.client.pause(pinnedFacade);
                 if (!pauseResult.success) {
                     throw new ToolExecutionError("C64 firmware reported failure while pausing", {
                         details: normaliseFailure(pauseResult.details),
@@ -258,7 +259,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             const expectedBytes = expectedInfo?.bytes ?? new Uint8Array();
             const maskBytes = maskInfo?.bytes;
             const readLength = Math.max(1, Math.max(writeInfo.bytes.length, expectedBytes.length));
-            const preRead = await ctx.client.readMemory(parsed.address, String(readLength));
+            const preRead = await ctx.client.readMemory(parsed.address, String(readLength), pinnedFacade);
             if (!preRead.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
                     details: normaliseFailure(preRead.details),
@@ -286,13 +287,13 @@ async function executeWriteMemory(rawArgs, ctx) {
                     });
                 }
             }
-            const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical);
+            const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical, pinnedFacade);
             if (!writeResult.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
                     details: normaliseFailure(writeResult.details),
                 });
             }
-            const postRead = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeInfo.bytes.length)));
+            const postRead = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeInfo.bytes.length)), pinnedFacade);
             if (!postRead.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while reading back memory", {
                     details: normaliseFailure(postRead.details),
@@ -336,6 +337,20 @@ async function executeWriteMemory(rawArgs, ctx) {
             if (preMismatches.length > 0) {
                 verificationMetadata.preReadMismatches = preMismatches;
             }
+            if (paused) { // A failed resume here leaves the machine paused: a recoverable operation failure, not a log.
+                const resumeResult = await ctx.client.resume(pinnedFacade);
+                if (!resumeResult.success) {
+                    throw new ToolExecutionError("Write completed but the machine could not be resumed", {
+                        details: {
+                            machinePaused: true,
+                            resume: normaliseFailure(resumeResult.details),
+                            recovery: "Call c64_system with op 'resume' before further machine operations.",
+                            verification: verificationMetadata,
+                        },
+                    });
+                }
+                paused = false;
+            }
             return textResult(`Wrote ${resolvedLength ?? "the provided"} bytes starting at ${resolvedAddress} (verified).`, {
                 success: true,
                 address: resolvedAddress,
@@ -350,7 +365,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         finally {
             if (paused) {
                 try {
-                    const resumeResult = await ctx.client.resume();
+                    const resumeResult = await ctx.client.resume(pinnedFacade);
                     if (!resumeResult.success) {
                         ctx.logger.warn("C64 resume reported failure after write", {
                             details: normaliseFailure(resumeResult.details),

package/dist/tools/meta/artifacts.js

@@ -1,8 +1,8 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { promises as fs } from "node:fs";
-import { resolve as resolvePath, join as joinPath } from "node:path";
+import { resolve as resolvePath, join as joinPath, relative, sep, isAbsolute } from "node:path";
 const bundleRunArtifactsArgsSchema = objectSchema({
     description: "Gather screen capture, memory snapshot, and debugreg into a structured bundle.",
     properties: {
@@ -41,29 +41,32 @@ export const tools = [
             try {
                 const parsed = bundleRunArtifactsArgsSchema.parse(args ?? {});
                 const runId = parsed.runId;
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === "." || runId === "..") {
+                    throw new ToolValidationError("runId must be a non-empty safe filename (letters, digits, dot, underscore, and dash only).", { path: "$.runId" });
+                }
                 const outputPath = resolvePath(String(parsed.outputPath));
                 const captureScreen = parsed.captureScreen !== false;
                 const captureDebugReg = parsed.captureDebugReg !== false;
                 const memoryRanges = (parsed.memoryRanges ?? []);
                 await fs.mkdir(outputPath, { recursive: true });
-                const runPath = resolvePath(joinPath(outputPath, runId));
+                const runPath = containedPath(outputPath, runId);
                 await fs.mkdir(runPath, { recursive: true });
                 const artifacts = {};
                 // Capture screen
                 if (captureScreen) {
                     const screen = await ctx.client.readScreen();
-                    const screenPath = resolvePath(joinPath(runPath, "screen.txt"));
+                    const screenPath = containedPath(runPath, "screen.txt");
                     await fs.writeFile(screenPath, screen, "utf8");
                     artifacts.screen = screenPath;
                 }
                 // Capture memory ranges
                 if (memoryRanges.length > 0) {
-                    const memoryPath = resolvePath(joinPath(runPath, "memory"));
+                    const memoryPath = containedPath(runPath, "memory");
                     await fs.mkdir(memoryPath, { recursive: true });
                     for (let i = 0; i < memoryRanges.length; i++) {
                         const range = memoryRanges[i];
                         const result = await ctx.client.readMemory(range.address, String(range.length));
-                        const rangePath = resolvePath(joinPath(memoryPath, `range_${i}_${range.address}.hex`));
+                        const rangePath = containedPath(memoryPath, `range_${i}.hex`);
                         await fs.writeFile(rangePath, result.data ?? "", "utf8");
                         artifacts[`memory_range_${i}`] = rangePath;
                     }
@@ -71,12 +74,12 @@ export const tools = [
                 // Capture debugreg
                 if (captureDebugReg) {
                     const debugreg = await ctx.client.debugregRead();
-                    const debugPath = resolvePath(joinPath(runPath, "debugreg.json"));
+                    const debugPath = containedPath(runPath, "debugreg.json");
                     await fs.writeFile(debugPath, JSON.stringify(debugreg, null, 2), "utf8");
                     artifacts.debugreg = debugPath;
                 }
                 // Write manifest
-                const manifestPath = resolvePath(joinPath(runPath, "manifest.json"));
+                const manifestPath = containedPath(runPath, "manifest.json");
                 const manifest = {
                     runId,
                     createdAt: new Date().toISOString(),
@@ -93,3 +96,12 @@ export const tools = [
         },
     },
 ];
+function containedPath(base, name) {
+    if (!name || isAbsolute(name) || name.includes("/") || name.includes("\\"))
+        throw new ToolValidationError("Unsafe artifact filename.");
+    const candidate = resolvePath(joinPath(base, name));
+    const rel = relative(base, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw new ToolValidationError("Artifact path escapes its output directory.");
+    return candidate;
+}

package/dist/tools/meta/background.js

@@ -86,6 +86,13 @@ async function ensureTasksLoaded() {
         if (parsed && Array.isArray(parsed.tasks)) {
             for (const pt of parsed.tasks) {
                 const t = fromPersistedTask(pt);
+                if (t.status === "running") {
+                    t.status = "stopped";
+                    t.stoppedAt = new Date();
+                    t.updatedAt = new Date();
+                    t.lastError = "Interrupted by MCP server restart; start the task again to resume monitoring.";
+                    t.nextRunAt = null;
+                }
                 TASKS.set(t.name, t);
             }
         }
@@ -184,7 +191,10 @@ function scheduleNextRun(task, ctx) {
         if (task.status !== "running")
             return;
         try {
-            await runOperation(task.operation, task.args, ctx);
+            const result = await runOperation(task.operation, task.args, ctx);
+            if (result && typeof result === "object" && "success" in result && result.success === false) {
+                throw new Error(`Operation returned failure: ${JSON.stringify(result.details ?? result)}`);
+            }
             task.iterations += 1;
             task.updatedAt = new Date();
             if (task.maxIterations && task.iterations >= task.maxIterations) {

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/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";
@@ -73,6 +74,7 @@ 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);

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/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)) {