c64bridge 1.0.4 → 1.0.6

package/dist/tools/memory.js

@@ -8,6 +8,7 @@ import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, un
 import { disassemble, formatDisassembly } from "./translation/disassembler.js";
 import { getViceSymbols } from "./translation/symbolRegistry.js";
 import { resolveAddressSymbol } from "../knowledge.js";
+import { stripHexByteSeparators } from "./hex.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -24,9 +25,7 @@ function normaliseFailure(details) {
     return { value: details };
 }
 function cleanHex(input) {
-    const trimmed = input.trim();
-    const withoutPrefix = trimmed.startsWith("$") ? trimmed.slice(1) : trimmed;
-    return withoutPrefix.replace(/[\s_]/g, "").toUpperCase();
+    return stripHexByteSeparators(input).toUpperCase();
 }
 function parseHexInternal(value, path) {
     const cleaned = cleanHex(value);
@@ -187,7 +186,7 @@ async function executeReadMemory(rawArgs, ctx) {
         ctx.logger.info("Reading C64 memory", { address: parsed.address, length: parsed.length });
         const result = await ctx.client.readMemory(parsed.address, String(parsed.length));
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
+            throw new ToolExecutionError("C64 backend reported failure while reading memory", {
                 details: normaliseFailure(result.details),
             });
         }
@@ -201,7 +200,9 @@ async function executeReadMemory(rawArgs, ctx) {
             hexData: result.data ?? null,
             details: detailRecord,
         };
-        const base = textResult(`Read ${resolvedLength} bytes starting at ${resolvedAddress}.`, data);
+        // Many clients show only the text content, so it carries the bytes too.
+        const hexSummary = typeof result.data === "string" && result.data.length > 0 ? `\n${result.data}` : "";
+        const base = textResult(`Read ${resolvedLength} bytes starting at ${resolvedAddress}.${hexSummary}`, data);
         return {
             ...base,
             structuredContent: {
@@ -228,7 +229,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         if (!shouldVerify) {
             const result = await ctx.client.writeMemory(parsed.address, writeInfo.canonical);
             if (!result.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
+                throw new ToolExecutionError("C64 backend reported failure while writing memory", {
                     details: normaliseFailure(result.details),
                 });
             }
@@ -250,7 +251,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             if (canPause) {
                 const pauseResult = await ctx.client.pause(pinnedFacade);
                 if (!pauseResult.success) {
-                    throw new ToolExecutionError("C64 firmware reported failure while pausing", {
+                    throw new ToolExecutionError("C64 backend reported failure while pausing", {
                         details: normaliseFailure(pauseResult.details),
                     });
                 }
@@ -261,7 +262,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             const readLength = Math.max(1, Math.max(writeInfo.bytes.length, expectedBytes.length));
             const preRead = await ctx.client.readMemory(parsed.address, String(readLength), pinnedFacade);
             if (!preRead.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
+                throw new ToolExecutionError("C64 backend reported failure while reading memory", {
                     details: normaliseFailure(preRead.details),
                 });
             }
@@ -289,13 +290,13 @@ async function executeWriteMemory(rawArgs, ctx) {
             }
             const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical, pinnedFacade);
             if (!writeResult.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
+                throw new ToolExecutionError("C64 backend reported failure while writing memory", {
                     details: normaliseFailure(writeResult.details),
                 });
             }
             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", {
+                throw new ToolExecutionError("C64 backend reported failure while reading back memory", {
                     details: normaliseFailure(postRead.details),
                 });
             }

package/dist/tools/meta/audio.js

@@ -267,7 +267,7 @@ export const tools = [
                 const results = [];
                 let restoreError;
                 try {
-                    for (const backend of requestedBackends) {
+                    for (const [backendIndex, backend] of requestedBackends.entries()) {
                         context.client.switchBackend(backend);
                         context.setPlatform(backend);
                         await trySilenceSid(context);
@@ -303,7 +303,11 @@ export const tools = [
                                 analysis,
                             };
                         }
-                        await trySilenceSid(context);
+                        // Stop this backend's playback only before moving on to the next one;
+                        // the last backend keeps playing so the preset can be heard in full.
+                        if (backendIndex < requestedBackends.length - 1) {
+                            await trySilenceSid(context);
+                        }
                         backendResult.verification = verification;
                         backendResult.success = true;
                         results.push(backendResult);
@@ -493,6 +497,8 @@ export const tools = [
                         entryAddress: compiled.entryAddress,
                         prgBytes: compiled.prg.length,
                         title: document.song?.title ?? null,
+                        basicFreeBytes: compiled.basicFreeBytes,
+                        warnings: compiled.warnings,
                     },
                     playback: {
                         method: playbackMethod,

package/dist/tools/meta/background.js

@@ -231,7 +231,12 @@ const noArgsSchema = objectSchema({ description: "No arguments", properties: {},
 const startBackgroundTaskArgsSchema = objectSchema({
     description: "Start a named background task that invokes a simple operation at fixed intervals.",
     properties: {
-        name: stringSchema({ description: "Unique task name", minLength: 1 }),
+        // The name becomes part of the task folder path, so it must be a single safe path segment.
+        name: stringSchema({
+            description: "Unique task name (letters, digits, spaces, '_', '-', '.'; must not start with '.' or a space).",
+            minLength: 1,
+            pattern: /^[A-Za-z0-9_][A-Za-z0-9_. -]*$/,
+        }),
         operation: stringSchema({ description: "Operation name (e.g., read, read_screen)", minLength: 1 }),
         arguments: optionalSchema(objectSchema({ description: "Operation-specific arguments", properties: {}, additionalProperties: true }), {}),
         intervalMs: optionalSchema(numberSchema({ description: "Interval milliseconds", integer: true, minimum: 1, default: 1000 }), 1000),

package/dist/tools/meta/filesystem.js

@@ -45,6 +45,28 @@ const filesystemStatsArgsSchema = objectSchema({
     required: [],
     additionalProperties: false,
 });
+/**
+ * Find a drive in drivesList() output. Ultimate firmware lists drives as a/b
+ * with a configurable bus_id, so "drive8" or "8" is matched by bus number.
+ */
+function findListedDrive(drives, drive) {
+    const wanted = drive.trim().toLowerCase();
+    const exact = drives.find((d) => String(d?.id ?? "").toLowerCase() === wanted);
+    if (exact)
+        return exact;
+    // VICE lists drives as driveN; the Ultimate letters a and b default to buses 8 and 9 there.
+    const letterBus = wanted === "a" ? 8 : wanted === "b" ? 9 : undefined;
+    const bus = /^(?:drive)?\s*(\d+)$/.exec(wanted);
+    if (!bus && letterBus === undefined)
+        return undefined;
+    const busId = letterBus ?? Number(bus[1]);
+    if (letterBus !== undefined) {
+        return drives.find((d) => String(d?.id ?? "").toLowerCase() === `drive${busId}`);
+    }
+    const onBus = drives.filter((d) => Number(d?.raw?.bus_id) === busId || String(d?.id ?? "").toLowerCase() === `drive${busId}`);
+    // Prefer the enabled drive; a disabled drive can keep the same bus_id setting.
+    return onBus.find((d) => d?.raw?.enabled !== false) ?? onBus[0];
+}
 function extractPaths(value) {
     const acc = [];
     const stack = [value];
@@ -651,7 +673,7 @@ export const tools = [
                 if (powerOnIfNeeded) {
                     try {
                         const drives = await ctx.client.drivesList();
-                        const targetDrive = Array.isArray(drives) ? drives.find((d) => d.id === drive) : null;
+                        const targetDrive = Array.isArray(drives) ? findListedDrive(drives, drive) : null;
                         if (!targetDrive) {
                             log.push({ step: "check_drive_exists", success: false, error: `Drive ${drive} not found` });
                             throw new ToolExecutionError(`Drive ${drive} not found in firmware drive list`, { details: { drive } });
@@ -676,18 +698,23 @@ export const tools = [
                         throw new ToolExecutionError("Failed to check or power on drive", { details: { error: error instanceof Error ? error.message : String(error) } });
                     }
                 }
-                // Step 2: Mount with retries
+                // Step 2: Switch the drive emulation mode. The mount's own "mode"
+                // option is the read/write attachment mode, not the drive type.
+                if (mode) {
+                    const setMode = await ctx.client.driveSetMode(drive, mode);
+                    log.push({ step: "set_mode", success: setMode.success === true, details: setMode.details });
+                    if (!setMode.success) {
+                        throw new ToolExecutionError(`Failed to set drive ${drive} to ${mode} mode`, { details: setMode.details });
+                    }
+                }
+                // Step 3: Mount with retries
                 let mountSuccess = false;
                 let lastMountError = null;
                 let attempts = 0;
                 for (let attempt = 0; attempt <= maxRetries && !mountSuccess; attempt += 1) {
                     attempts = attempt + 1;
                     try {
-                        const mountOptions = {};
-                        if (mode) {
-                            mountOptions.mode = mode;
-                        }
-                        const mount = await ctx.client.driveMount(drive, imagePath, mountOptions);
+                        const mount = await ctx.client.driveMount(drive, imagePath);
                         if (mount.success) {
                             mountSuccess = true;
                             log.push({ step: `mount_attempt_${attempts}`, success: true, details: mount.details });
@@ -717,7 +744,7 @@ export const tools = [
                         details: { lastError: lastMountError }
                     });
                 }
-                // Step 3: Reset drive if requested
+                // Step 4: Reset drive if requested
                 if (resetAfterMount) {
                     try {
                         const reset = await ctx.client.driveReset(drive);
@@ -735,12 +762,12 @@ export const tools = [
                         ctx.logger.warn?.("Drive reset threw error", { error });
                     }
                 }
-                // Step 4: Verify mount
+                // Step 5: Verify mount
                 let verificationResult = null;
                 if (verifyMount) {
                     try {
                         const drives = await ctx.client.drivesList();
-                        const targetDrive = Array.isArray(drives) ? drives.find((d) => d.id === drive) : null;
+                        const targetDrive = Array.isArray(drives) ? findListedDrive(drives, drive) : null;
                         if (!targetDrive) {
                             log.push({ step: "verify", success: false, error: "Drive not found in list" });
                             throw new ToolExecutionError("Drive disappeared after mount", { details: { drive } });

package/dist/tools/meta/graphics.js

@@ -13,21 +13,16 @@ function parseAddressNumeric(value) {
         throw new ToolValidationError("Address must be a non-empty string", { path: "$.address" });
     }
     const trimmed = value.trim();
-    let literal = trimmed;
-    let radix = 10;
-    if (trimmed.startsWith("$")) {
-        radix = 16;
-        literal = trimmed.slice(1);
-    }
-    else if (trimmed.startsWith("0x")) {
-        radix = 16;
-        literal = trimmed.slice(2);
-    }
-    else if (trimmed.startsWith("%")) {
-        radix = 2;
-        literal = trimmed.slice(1);
-    }
-    const parsed = Number.parseInt(literal, radix);
+    // Anchored patterns: Number.parseInt alone would read "$08G0" as $0008.
+    let parsed = Number.NaN;
+    if (/^\$[0-9a-f]+$/i.test(trimmed))
+        parsed = Number.parseInt(trimmed.slice(1), 16);
+    else if (/^0x[0-9a-f]+$/i.test(trimmed))
+        parsed = Number.parseInt(trimmed.slice(2), 16);
+    else if (/^%[01]+$/.test(trimmed))
+        parsed = Number.parseInt(trimmed.slice(1), 2);
+    else if (/^[0-9]+$/.test(trimmed))
+        parsed = Number.parseInt(trimmed, 10);
     if (!Number.isFinite(parsed) || Number.isNaN(parsed)) {
         throw new ToolValidationError("Invalid address value", { path: "$.address", details: { value } });
     }
@@ -228,7 +223,7 @@ export const tools = [
                 try {
                     const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(length));
                     if (!read.success || typeof read.data !== "string") {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading memory", { details: normalizeErrorDetails(read.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(read.details) });
                     }
                     const bytes = hexToBytes(read.data);
                     if (bytes.length < length) {

package/dist/tools/meta/memory.js

@@ -5,14 +5,13 @@ import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
 import { createHash } from "node:crypto";
 import { normalizeErrorDetails } from "./util.js";
+import { stripHexByteSeparators } from "../hex.js";
 function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id ?? ctx.client?.type;
     return platformId !== "vice";
 }
 function hexClean(input) {
-    const trimmed = input.trim();
-    const withoutPrefix = trimmed.startsWith("$") ? trimmed.slice(1) : trimmed;
-    return withoutPrefix.replace(/[\s_]/g, "").toLowerCase();
+    return stripHexByteSeparators(input).toLowerCase();
 }
 function hexToBytes(input) {
     const cleaned = hexClean(input);
@@ -31,21 +30,16 @@ function parseAddressNumeric(value) {
         throw new ToolValidationError("Address must be a non-empty string", { path: "$.address" });
     }
     const lower = value.trim().toLowerCase();
-    let radix = 10;
-    let literal = lower;
-    if (lower.startsWith("$")) {
-        radix = 16;
-        literal = lower.slice(1);
-    }
-    else if (lower.startsWith("0x")) {
-        radix = 16;
-        literal = lower.slice(2);
-    }
-    else if (lower.startsWith("%")) {
-        radix = 2;
-        literal = lower.slice(1);
-    }
-    const parsed = Number.parseInt(literal, radix);
+    // Anchored patterns: Number.parseInt alone would read "$20ZZ" as $0020.
+    let parsed = Number.NaN;
+    if (/^\$[0-9a-f]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(1), 16);
+    else if (/^0x[0-9a-f]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(2), 16);
+    else if (/^%[01]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(1), 2);
+    else if (/^[0-9]+$/.test(lower))
+        parsed = Number.parseInt(lower, 10);
     if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0 || parsed > 0xFFFF) {
         throw new ToolValidationError("Invalid address value", { path: "$.address", details: { value } });
     }
@@ -103,7 +97,7 @@ export const tools = [
                 if (canPause) {
                     const pauseResult = await ctx.client.pause();
                     if (!pauseResult.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
                     }
                     paused = true;
                 }
@@ -111,7 +105,7 @@ export const tools = [
                 try {
                     const pre = await ctx.client.readMemory(parsed.address, String(Math.max(1, readLen)));
                     if (!pre.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading memory", { details: normalizeErrorDetails(pre.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(pre.details) });
                     }
                     preReadHex = pre.data ?? "$";
                     const preBytes = hexToBytes(preReadHex);
@@ -131,11 +125,11 @@ export const tools = [
                     }
                     const write = await ctx.client.writeMemory(parsed.address, bytesToHex(writeBytes));
                     if (!write.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while writing memory", { details: normalizeErrorDetails(write.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while writing memory", { details: normalizeErrorDetails(write.details) });
                     }
                     const post = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeBytes.length)));
                     if (!post.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading back memory", { details: normalizeErrorDetails(post.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading back memory", { details: normalizeErrorDetails(post.details) });
                     }
                     const postBytes = hexToBytes(post.data ?? "$");
                     const diffs = [];

package/dist/tools/meta/program.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
 import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { measureSidSilence } from "../audio.js";
 import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
@@ -8,6 +9,7 @@ import { sleep, formatTimestampSpec } from "./util.js";
 import { getTasksHomeDir } from "./background.js";
 import { Jimp } from "jimp";
 import { withDiagnosticSpan } from "../../diagnostics.js";
+import { stripHexByteSeparators } from "../hex.js";
 const C64_SCREENSHOT_PALETTE = [
     0x000000ff,
     0xffffffff,
@@ -62,6 +64,9 @@ function canonicalGreetingBackends() {
 function uniqueGreetingBackends(backends) {
     return backends.filter((backend, index) => backends.indexOf(backend) === index);
 }
+function normaliseAssertionHex(value) {
+    return stripHexByteSeparators(value).toUpperCase();
+}
 function normaliseScreenText(screen) {
     return screen.replace(/\r\n?/g, "\n").replace(/\s+/g, " ").trim().toUpperCase();
 }
@@ -202,7 +207,7 @@ const batchRunWithAssertionsArgsSchema = objectSchema({
                 assertions: optionalSchema(arraySchema(objectSchema({
                     description: "Assertion to check after run",
                     properties: {
-                        type: stringSchema({ description: "Assertion type", enum: ["screen_contains", "memory_equals", "sid_silent"] }),
+                        type: stringSchema({ description: "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).", enum: ["screen_contains", "memory_equals", "sid_silent"] }),
                         pattern: optionalSchema(stringSchema({ description: "Pattern for screen_contains", minLength: 1 })),
                         address: optionalSchema(stringSchema({ description: "Address for memory_equals", minLength: 1 })),
                         expected: optionalSchema(stringSchema({ description: "Expected value (hex)", minLength: 1 })),
@@ -696,9 +701,17 @@ export const tools = [
                             else if (assertion.type === "memory_equals") {
                                 const addr = assertion.address ?? "$0400";
                                 const expected = assertion.expected ?? "$00";
-                                const result = await ctx.client.readMemory(addr, "1");
-                                const actual = result.data ?? "$00";
-                                const matched = actual.toLowerCase() === expected.toLowerCase();
+                                // Compare every expected byte, and treat a failed read as an error rather than as $00.
+                                const expectedHex = normaliseAssertionHex(expected);
+                                if (expectedHex.length === 0 || expectedHex.length % 2 !== 0 || !/^[0-9A-F]+$/.test(expectedHex)) {
+                                    throw new Error(`memory_equals expected value ${expected} is not a whole number of hex bytes`);
+                                }
+                                const result = await ctx.client.readMemory(addr, String(expectedHex.length / 2));
+                                if (!result.success || typeof result.data !== "string") {
+                                    throw new Error(`Failed to read memory at ${addr} for memory_equals assertion`);
+                                }
+                                const actual = result.data;
+                                const matched = normaliseAssertionHex(actual) === expectedHex;
                                 assertionResults.push({
                                     type: assertion.type,
                                     status: matched ? "pass" : "fail",
@@ -708,14 +721,20 @@ export const tools = [
                                     status = "fail";
                             }
                             else if (assertion.type === "sid_silent") {
-                                // Check SID gate bits are off (simple check)
-                                const result = await ctx.client.readMemory("$D404", "1");
-                                const gate1 = parseInt((result.data ?? "$00").slice(1), 16) & 0x01;
-                                const isSilent = gate1 === 0;
+                                // SID control registers are write-only (an Ultimate 64 reads $D404 as $00
+                                // whatever was written), so silence is measured from the Ultimate audio
+                                // stream. Other backends would fall back to the host microphone, which
+                                // measures the room rather than the C64, so they report an error instead.
+                                const backend = ctx.platform?.id ?? await ctx.client.getActiveBackendType?.();
+                                if (backend !== undefined && backend !== "c64u") {
+                                    throw new Error(`sid_silent needs the C64 Ultimate audio stream and is not available on ${backend}`);
+                                }
+                                const silence = await measureSidSilence(ctx);
+                                const isSilent = silence.silent;
                                 assertionResults.push({
                                     type: assertion.type,
                                     status: isSilent ? "pass" : "fail",
-                                    message: isSilent ? undefined : "SID voice 1 gate is on",
+                                    message: isSilent ? undefined : `SID output is not silent (peak RMS ${silence.maxRms.toFixed(3)} > ${silence.threshold})`,
                                 });
                                 if (!isSilent)
                                     status = "fail";

package/dist/tools/pollValidator.js

@@ -75,7 +75,7 @@ function concatBuffers(...buffers) {
  * Looks for patterns like "?SYNTAX ERROR" or "SYNTAX ERROR IN 120".
  */
 function extractBasicError(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.
+    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. The apostrophe covers UNDEF'D STATEMENT, REDIM'D ARRAY and CAN'T CONTINUE.
     if (errorMatch) {
         const errorType = errorMatch[1]?.trim().replace(/\s+/g, " ");
         const lineStr = errorMatch[2];
@@ -87,6 +87,19 @@ function extractBasicError(screen) {
     }
     return null;
 }
+/**
+ * True when the most recent typed SYS command is followed by a READY. prompt,
+ * which is how a machine-code routine that ends with RTS hands back to BASIC.
+ */
+function returnedToBasicAfterSys(screen) {
+    const lines = screen.split("\n").map((line) => line.trim().toUpperCase());
+    let sysLine = -1;
+    lines.forEach((line, index) => {
+        if (/^SYS\s*\d+$/.test(line))
+            sysLine = index;
+    });
+    return sysLine >= 0 && lines.slice(sysLine + 1).some((line) => line === "READY.");
+}
 /**
  * Poll for BASIC program outcome by detecting errors on screen.
  * First waits for RUN or ERROR to appear, then continues polling for errors.
@@ -157,7 +170,12 @@ async function pollAsmOutcome(client, logger, config) {
         try {
             const screen = await client.readScreen();
             const upperScreen = screen.toUpperCase();
-            if (upperScreen.includes("RUN") || upperScreen.includes("ERROR")) {
+            if (returnedToBasicAfterSys(screen)) {
+                // The typed SYS line is followed by READY., so the routine ran and returned with RTS.
+                logger.debug("ASM program returned to BASIC", { elapsed: Date.now() - startTime });
+                return { status: "ok", type: "ASM" };
+            }
+            if (upperScreen.includes("RUN") || upperScreen.includes("SYS") || upperScreen.includes("ERROR")) {
                 runDetected = true;
                 logger.debug("RUN detected, starting stabilization window", {
                     elapsed: Date.now() - startTime,
@@ -182,6 +200,16 @@ async function pollAsmOutcome(client, logger, config) {
     const pollDeadline = Date.now() + config.maxMs;
     while (Date.now() < pollDeadline && !alive) {
         pollCount++;
+        try {
+            // A routine that works for a while before RTS shows READY. only after the first screen read.
+            if (returnedToBasicAfterSys(await client.readScreen())) {
+                logger.debug("ASM program returned to BASIC", { pollCount, elapsed: Date.now() - startTime });
+                return { status: "ok", type: "ASM" };
+            }
+        }
+        catch (error) {
+            logger.debug("Failed to read screen during ASM polling", { error, pollCount });
+        }
         try {
             const screenRam = await client.readMemoryRaw(0x0400, 0x03e8);
             const signature = computeCrc32(screenRam);

package/dist/tools/printer.js

@@ -278,7 +278,7 @@ export const printerModule = defineToolModule({
                         formFeed: parsed.formFeed,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing text", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing text", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -337,7 +337,7 @@ export const printerModule = defineToolModule({
                         ensureMsb: parsed.ensureMsb,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing Commodore bitmap", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing Commodore bitmap", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -398,7 +398,7 @@ export const printerModule = defineToolModule({
                         timesPerLine: parsed.timesPerLine,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing Epson bitmap", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing Epson bitmap", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -458,7 +458,7 @@ export const printerModule = defineToolModule({
                         secondaryAddress: parsed.secondaryAddress,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while defining DLL characters", {
+                        throw new ToolExecutionError("C64 backend reported failure while defining DLL characters", {
                             details: normaliseFailure(result.details),
                         });
                     }

package/dist/tools/programRunners.js

@@ -52,7 +52,8 @@ function parseBasicRuntimeErrors(screen) {
             continue;
         }
         seen.add(lineNumber);
-        const typeMatch = /\?([A-Z ?]+?)\s+ERROR\s+IN/i.exec(row.toUpperCase());
+        // The apostrophe covers UNDEF'D STATEMENT, REDIM'D ARRAY and UNDEF'D FUNCTION.
+        const typeMatch = /\?([A-Z' ?]+?)\s+ERROR\s+IN/i.exec(row.toUpperCase());
         const type = typeMatch?.[1]?.trim().replace(/\s+/g, " ") || undefined;
         errors.push({
             line: lineNumber,
@@ -266,7 +267,7 @@ async function executeUploadRunBasic(rawArgs, ctx) {
         const runBasic = async (source) => ctx.client.uploadAndRunBasic(source);
         let result = await runBasic(activeProgram);
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while running BASIC program", {
+            throw new ToolExecutionError("C64 backend reported failure while running BASIC program", {
                 details: extractFailureDetails(result.details),
             });
         }
@@ -441,13 +442,13 @@ async function executeUploadRunAsm(rawArgs, ctx) {
         // Assemble locally to expose structured metadata and capture symbols
         const asmResult = assemblyToPrgDetailed(parsed.program);
         const prg = asmResult.prg;
-        const entryAddress = prg.readUInt16LE(0);
+        const entryAddress = asmResult.entryAddress;
         if (ctx.platform.id === "vice") {
             setViceSymbols(asmResult.symbols.entries());
         }
         const result = await ctx.client.uploadAndRunAsm(parsed.program);
         if (!result.success) {
-            return toolErrorResult(new ToolExecutionError("C64 firmware reported failure while running assembly program", {
+            return toolErrorResult(new ToolExecutionError("C64 backend reported failure while running assembly program", {
                 details: extractFailureDetails(result.details),
             }));
         }
@@ -515,7 +516,7 @@ async function executeLoadPrg(rawArgs, ctx) {
         ctx.logger.info("Loading PRG file", { path: parsed.path });
         const result = await ctx.client.loadPrgFile(parsed.path);
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while loading PRG", {
+            throw new ToolExecutionError("C64 backend reported failure while loading PRG", {
                 details: extractFailureDetails(result.details),
             });
         }
@@ -565,7 +566,7 @@ async function executeRunPrg(rawArgs, ctx) {
         }
         const result = await ctx.client.runPrgFile(parsed.path);
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while running PRG", {
+            throw new ToolExecutionError("C64 backend reported failure while running PRG", {
                 details: extractFailureDetails(result.details),
             });
         }
@@ -600,7 +601,7 @@ async function executeRunCrt(rawArgs, ctx) {
         ctx.logger.info("Running CRT file", { path: parsed.path });
         const result = await ctx.client.runCrtFile(parsed.path);
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while running CRT", {
+            throw new ToolExecutionError("C64 backend reported failure while running CRT", {
                 details: extractFailureDetails(result.details),
             });
         }
@@ -686,7 +687,7 @@ export const programRunnersModule = defineToolModule({
                 {
                     name: "Set screen char",
                     description: "Write 1 to $0400 then RTS",
-                    arguments: { program: ".org $0801\nstart: lda #$01\n sta $0400\n rts" },
+                    arguments: { program: "start: lda #$01\n sta $0400\n rts" },
                 },
             ],
             workflowHints: [
@@ -772,7 +773,7 @@ export const programRunnersModule = defineToolModule({
                     ctx.logger.info("Running CRT file", { path: parsed.path });
                     const result = await ctx.client.runCrtFile(parsed.path);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while running CRT", {
+                        throw new ToolExecutionError("C64 backend reported failure while running CRT", {
                             details: extractFailureDetails(result.details),
                         });
                     }

package/dist/tools/registry/disk.js

@@ -76,7 +76,7 @@ const createImageArgsSchema = objectSchema({
             maxLength: 16,
         })),
         tracks: optionalSchema(numberSchema({
-            description: "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+            description: "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
             integer: true,
             minimum: 1,
             maximum: 255,
@@ -210,10 +210,10 @@ const diskOperations = [
             const { path, diskname, tracks } = parsed;
             switch (format) {
                 case "d64":
-                    if (tracks !== undefined && tracks !== 35 && tracks !== 40) {
-                        throw new ToolValidationError("D64 images support 35 or 40 tracks", {
+                    if (tracks !== undefined && (tracks < 35 || tracks > 41)) {
+                        throw new ToolValidationError("D64 images support 35 to 41 tracks", {
                             path: "$.tracks",
-                            details: { allowed: [35, 40], received: tracks },
+                            details: { minimum: 35, maximum: 41, received: tracks },
                         });
                     }
                     return storageModule.invoke("create_d64", { path, tracks, diskname }, ctx);
@@ -274,8 +274,10 @@ export const diskModuleGroup = defineToolModule({
                 variants: diskOperations.map((operation) => operation.schema),
             }),
             tags: ["storage", "drive", "grouped"],
-            operationPlatforms: { file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"] },
+            // The VICE Binary Monitor has no command to detach a disk image, so unmount is Ultimate-only.
+            operationPlatforms: { unmount: ["c64u", "u2"], file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"] },
             operationToolNames: {
+                unmount: "drive_remove",
                 file_info: "file_info",
                 create_image: "create_image",
                 find_and_run: "find_and_run_program_by_name",