c64bridge 1.0.3 → 1.0.5

package/dist/sidwaveCompiler.js

@@ -71,19 +71,15 @@ export function compileSidwaveToPrg(doc) {
             }
             if (pat.type === "arpeggio" && Array.isArray(pat.notes) && pat.notes.length) {
                 const stepFrames = Math.max(1, Math.round((pat.frame_rate ? fps / pat.frame_rate : framesPerBeat)));
-                let idx = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        idx = (idx + 1) % pat.notes.length;
+                    const idx = Math.floor(f / stepFrames) % pat.notes.length;
                     notesForSong.push(String(pat.notes[idx]));
                 }
             }
             else if (Array.isArray(pat.groove) && pat.groove.length) {
                 const stepFrames = framesPerBeat; // one note per beat
-                let gi = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        gi = (gi + 1) % pat.groove.length;
+                    const gi = Math.floor(f / stepFrames) % pat.groove.length;
                     notesForSong.push(String(pat.groove[gi]));
                 }
             }
@@ -95,10 +91,8 @@ export function compileSidwaveToPrg(doc) {
                 const lengthBeats = Math.max(1, Math.floor(pat.length ?? 1));
                 const stepFrames = framesPerBeat * lengthBeats;
                 const baseNote = "C3";
-                let mi = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        mi = (mi + 1) % Math.max(1, intervals.length);
+                    const mi = Math.floor(f / stepFrames) % Math.max(1, intervals.length);
                     const iv = intervals.length ? intervals[mi] : 0;
                     notesForSong.push(transposeNote(baseNote, iv));
                 }

package/dist/tools/audio.js

@@ -4,12 +4,14 @@ import { recordAndAnalyzeAudio } from "../audio/record_and_analyze_audio.js";
 import { defineToolModule } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
-import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { ToolError, ToolExecutionError, ToolValidationError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { getPlatformStatus } from "../platform.js";
 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();
+let lastGeneratedPlayback = Promise.resolve();
 export function cancelGeneratedSidPlayback() {
     for (const controller of generatedPlaybacks)
         controller.abort();
@@ -244,7 +246,7 @@ const musicCompileArgsSchema = objectSchema({
             enum: ["yaml", "json"],
         })),
         output: optionalSchema(stringSchema({
-            description: "Playback target format.",
+            description: "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
             enum: ["prg", "sid"],
             default: "prg",
         }), "prg"),
@@ -316,8 +318,20 @@ function transposeNote(note, semitones) {
     const newOctave = Math.floor(midi / 12) - 1;
     return `${names[wrapped]}${newOctave}`;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
 }
 function shouldAutoAnalyze(request) {
     const lowered = request.toLowerCase();
@@ -824,8 +838,12 @@ export const audioModule = defineToolModule({
                     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 () => {
+                    // A replaced sequence sends its final gate-off on voice 1; waiting for it
+                    // keeps that gate-off from cutting off this sequence's first note.
+                    const previousPlayback = lastGeneratedPlayback;
+                    lastGeneratedPlayback = (async () => {
                         try {
+                            await previousPlayback;
                             const pinnedFacade = await pinnedFacadePromise;
                             await ctx.client.sidSetVolume(8, pinnedFacade);
                             for (let i = 0; i < parsed.steps; i += 1) {
@@ -844,10 +862,14 @@ export const audioModule = defineToolModule({
                                     release: 0,
                                 }, pinnedFacade);
                                 const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
-                                await sleep(Math.max(1, Math.min(20, Math.floor(durationMs / 8)))); // Clear GATE between notes so every note retriggers ADSR.
+                                // Hold GATE for most of the note, then clear it for a short gap so the next note retriggers ADSR.
+                                const gateGapMs = Math.max(1, Math.min(20, Math.floor(durationMs / 8)));
+                                // Cancellation ends the sleep at once, so the final gate-off below follows promptly.
+                                await sleep(Math.max(0, durationMs - gateGapMs), controller.signal);
+                                if (controller.signal.aborted)
+                                    break;
                                 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 sleep(gateGapMs, controller.signal);
                             }
                             await ctx.client.sidNoteOff(1, pinnedFacade);
                         }
@@ -902,6 +924,10 @@ export const audioModule = defineToolModule({
                         throw new ToolValidationError("Provide sidwave or cpg source", { path: "$.sidwave" });
                     }
                     const outputFormat = parsed.output ?? "prg";
+                    const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                    if (outputFormat === "sid" && !parsed.dryRun && platform === "vice") {
+                        throw new ToolUnsupportedPlatformError("sidplay_attachment (use output: prg or dryRun: true on VICE)", platform, ["c64u", "u2"]);
+                    }
                     ctx.logger.info("Compiling SIDWAVE composition", {
                         output: outputFormat,
                         dryRun: parsed.dryRun,

package/dist/tools/debug.js

@@ -572,17 +572,17 @@ function formatAddress(value) {
 }
 function parseAddress(value, label) {
     const trimmed = value.trim();
-    let radix = 10;
-    let literal = trimmed;
-    if (trimmed.startsWith("$")) {
-        radix = 16;
-        literal = trimmed.slice(1);
+    // 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 (trimmed.toLowerCase().startsWith("0x")) {
-        radix = 16;
-        literal = trimmed.slice(2);
+    else if (/^0x[0-9a-f]+$/i.test(trimmed)) {
+        parsed = Number.parseInt(trimmed.slice(2), 16);
+    }
+    else if (/^[0-9]+$/.test(trimmed)) {
+        parsed = Number.parseInt(trimmed, 10);
     }
-    const parsed = Number.parseInt(literal, radix);
     if (!Number.isInteger(parsed) || parsed < 0 || parsed > 0xffff) {
         throw new ToolValidationError(`Invalid ${label}`, { path: `$.${label}` });
     }

package/dist/tools/errors.js

@@ -44,10 +44,21 @@ export function toolErrorResult(error) {
         ...(error.code !== undefined ? { code: error.code } : {}),
         ...(error.details !== undefined ? { details: error.details } : {}),
     };
-    const message = error.path ? `${error.message} (at ${error.path})` : error.message;
+    const located = error.path ? `${error.message} (at ${error.path})` : error.message;
+    // Clients often show only the text content, so surface the underlying cause
+    // (for example a range check or firmware error string) next to the summary.
+    const detailMessage = describeDetailMessage(error.details);
+    const message = detailMessage && !located.includes(detailMessage) ? `${located}: ${detailMessage}` : located;
     const base = textResult(message, { error: metadata });
     return { ...base, isError: true };
 }
+function describeDetailMessage(details) {
+    if (!details || typeof details !== "object") {
+        return undefined;
+    }
+    const message = details.message;
+    return typeof message === "string" && message.trim().length > 0 ? message.trim() : undefined;
+}
 export function unknownErrorResult(error) {
     if (error instanceof ToolError) {
         return toolErrorResult(error);

package/dist/tools/hex.js

@@ -0,0 +1,9 @@
+/**
+ * Normalise a user-supplied hex byte string such as "$A9 $00", "A9_00" or
+ * "$A900" to bare hex digits. A "$" may prefix the whole string or each
+ * whitespace-separated byte group; whitespace and "_" separators are removed.
+ * The result is not validated, so callers still check length and digits.
+ */
+export function stripHexByteSeparators(input) {
+    return input.trim().replace(/(^|\s)\$/g, "$1").replace(/[\s_]/g, "");
+}

package/dist/tools/input.js

@@ -68,25 +68,31 @@ const PETSCII_TOKENS = {
     CURSOR_LEFT: 157,
     CURSOR_RIGHT: 29,
 };
+// ASCII a-z are shifted graphics characters in PETSCII, so typed "print" would
+// reach BASIC as graphics and give ?SYNTAX ERROR. Literal letters are therefore
+// sent as the unshifted PETSCII letters $41-$5A; {tokens} keep their codes.
 function expandPetsciiTokens(text) {
-    return text.replace(/\{([^}]+)\}/g, (_match, token) => {
+    return text.replace(/\{([^}]+)\}|[a-z]/g, (_match, token) => {
+        if (token === undefined) {
+            return _match.toUpperCase();
+        }
         const upper = token.trim().toUpperCase();
         const code = PETSCII_TOKENS[upper];
         if (code !== undefined) {
             return String.fromCharCode(code);
         }
-        // Numeric form: {$1D} or {29}
-        let num;
-        if (upper.startsWith("$")) {
+        // Numeric form: {$1D} or {29}. Anchored, so {12AB} is not read as {12}.
+        let num = NaN;
+        if (/^\$[0-9A-F]{1,2}$/.test(upper)) {
             num = parseInt(upper.slice(1), 16);
         }
-        else {
+        else if (/^\d{1,3}$/.test(upper)) {
             num = parseInt(upper, 10);
         }
         if (!isNaN(num) && num >= 0 && num <= 255) {
             return String.fromCharCode(num);
         }
-        return _match; // leave unrecognised tokens as-is
+        return _match.toUpperCase(); // type unrecognised tokens literally
     });
 }
 // ---------------------------------------------------------------------------
@@ -266,7 +272,7 @@ const inputOperationHandlers = {
             const keyByte = tokenCode !== undefined
                 ? tokenCode
                 : parsed.key.length === 1
-                    ? parsed.key.charCodeAt(0) & 0xff
+                    ? parsed.key.toUpperCase().charCodeAt(0) & 0xff
                     : (() => {
                         throw new ToolValidationError(`Unrecognised key: ${parsed.key}. Use a single character or a PETSCII token name.`, { path: "$.key" });
                     })();

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);
@@ -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: {

package/dist/tools/meta/artifacts.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolValidationError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath, relative, sep, isAbsolute } from "node:path";
 const bundleRunArtifactsArgsSchema = objectSchema({
@@ -18,7 +19,7 @@ const bundleRunArtifactsArgsSchema = objectSchema({
             required: ["address", "length"],
             additionalProperties: false,
         }))),
-        captureDebugReg: optionalSchema(booleanSchema({ description: "Capture debugreg state", default: true }), true),
+        captureDebugReg: optionalSchema(booleanSchema({ description: "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE." })),
     },
     required: ["runId", "outputPath"],
     additionalProperties: false,
@@ -46,7 +47,11 @@ export const tools = [
                 }
                 const outputPath = resolvePath(String(parsed.outputPath));
                 const captureScreen = parsed.captureScreen !== false;
-                const captureDebugReg = parsed.captureDebugReg !== false;
+                const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                const captureDebugReg = parsed.captureDebugReg ?? (platform === "c64u");
+                if (captureDebugReg && platform !== "c64u") {
+                    throw new ToolUnsupportedPlatformError("debugreg_read", platform, ["c64u"]);
+                }
                 const memoryRanges = (parsed.memoryRanges ?? []);
                 await fs.mkdir(outputPath, { recursive: true });
                 const runPath = containedPath(outputPath, runId);

package/dist/tools/meta/audio.js

@@ -2,7 +2,8 @@ import { compileSidwaveToPrg, compileSidwaveToSid } from "../../sidwaveCompiler.
 import { parseSidwave } from "../../sidwave.js";
 import { recordAndAnalyzeAudio } from "../../audio/record_and_analyze_audio.js";
 import { jsonResult } from "../responses.js";
-import { ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolExecutionError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { sleep } from "./util.js";
 import { arraySchema, booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "../schema.js";
 const DEFAULT_SILENCE_DURATION_SECONDS = 1.5;
@@ -68,7 +69,7 @@ const musicCompilePlayAnalyzeArgsSchema = objectSchema({
     properties: {
         sidwave: optionalSchema(stringSchema({ description: "SIDWAVE source in YAML or JSON format.", minLength: 1 })),
         cpg: optionalSchema(stringSchema({ description: "Legacy CPG input format.", minLength: 1 })),
-        output: optionalSchema(stringSchema({ description: "Playback artifact format.", enum: ["prg", "sid"], default: "prg" }), "prg"),
+        output: optionalSchema(stringSchema({ description: "Playback artifact format. PRG works on all backends; SID attachment playback requires C64U/U64 or U2.", enum: ["prg", "sid"], default: "prg" }), "prg"),
         waitBeforeCaptureMs: optionalSchema(numberSchema({ description: "Delay between starting playback and beginning analysis capture (milliseconds).", minimum: 0, maximum: 5000 }), DEFAULT_PLAYBACK_WAIT_MS),
         analysisDurationSeconds: optionalSchema(numberSchema({ description: "Audio capture length in seconds.", minimum: 0.5, maximum: 20 }), DEFAULT_ANALYSIS_DURATION_SECONDS),
         expectedSidwave: optionalSchema(stringSchema({ description: "Optional expected SIDWAVE used to refine analysis comparisons.", minLength: 1 })),
@@ -91,11 +92,11 @@ const musicPlayPresetArgsSchema = objectSchema({
         }), "fuer_elise"),
         platforms: optionalSchema(arraySchema(stringSchema({
             description: "Backends to target in sequence.",
-            enum: ["vice", "c64u"],
+            enum: ["vice", "c64u", "u2"],
             minLength: 1,
         }))),
         verify: optionalSchema(booleanSchema({
-            description: "Capture and analyze audio on supported backends after playback starts.",
+            description: "Capture and analyze audio after playback starts: native streaming on C64U/U64, host audio input on U2/VICE (PortAudio required).",
             default: true,
         }), true),
         analysisDurationSeconds: optionalSchema(numberSchema({
@@ -147,7 +148,7 @@ function normalizeSidwaveInput(input) {
     return undefined;
 }
 function canonicalPresetBackends() {
-    return ["vice", "c64u"];
+    return ["vice", "c64u", "u2"];
 }
 function uniquePresetBackends(backends) {
     return backends.filter((backend, index) => backends.indexOf(backend) === index);
@@ -285,30 +286,22 @@ export const tools = [
                         }
                         let verification = null;
                         if (verify) {
-                            if (backend === "c64u") {
-                                if (waitBeforeCaptureMs > 0) {
-                                    await sleep(waitBeforeCaptureMs);
-                                }
-                                const analysis = await analyzer({
-                                    durationSeconds: analysisDurationSeconds,
-                                    expectedSidwave: preset.sidwave,
-                                });
-                                const metrics = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
-                                verification = {
-                                    mode: "audio-analysis",
-                                    durationSeconds: analysis.analysis?.durationSeconds ?? analysisDurationSeconds,
-                                    averageRms: metrics.average,
-                                    maxRms: metrics.max,
-                                    voices: analysis.analysis?.voices ?? [],
-                                    analysis,
-                                };
-                            }
-                            else {
-                                verification = {
-                                    mode: "playback-launch",
-                                    note: "Audio analysis is only available on c64u; verified that playback launched on this backend.",
-                                };
+                            if (waitBeforeCaptureMs > 0) {
+                                await sleep(waitBeforeCaptureMs);
                             }
+                            const analysis = await analyzer({
+                                durationSeconds: analysisDurationSeconds,
+                                expectedSidwave: preset.sidwave,
+                            });
+                            const metrics = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
+                            verification = {
+                                mode: "audio-analysis",
+                                durationSeconds: analysis.analysis?.durationSeconds ?? analysisDurationSeconds,
+                                averageRms: metrics.average,
+                                maxRms: metrics.max,
+                                voices: analysis.analysis?.voices ?? [],
+                                analysis,
+                            };
                         }
                         await trySilenceSid(context);
                         backendResult.verification = verification;
@@ -409,6 +402,10 @@ export const tools = [
                     throw new ToolExecutionError("Provide sidwave or cpg source");
                 }
                 const format = (parsed.output ?? "prg");
+                const platform = context.platform?.id ?? getPlatformStatus().id;
+                if (format === "sid" && platform === "vice") {
+                    throw new ToolUnsupportedPlatformError("sidplay_attachment (use output: prg on VICE)", platform, ["c64u", "u2"]);
+                }
                 const waitBeforeCaptureMs = parsed.waitBeforeCaptureMs ?? DEFAULT_PLAYBACK_WAIT_MS;
                 const analysisDurationSeconds = parsed.analysisDurationSeconds ?? DEFAULT_ANALYSIS_DURATION_SECONDS;
                 const verifySilenceBefore = parsed.verifySilenceBefore ?? true;

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/config.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
 import { captureConfigSnapshot, validateSnapshotCategories } from "./configInventory.js";
@@ -10,7 +11,7 @@ const configSnapshotAndRestoreArgsSchema = objectSchema({
     properties: {
         action: stringSchema({ description: "One of: snapshot|restore|diff", enum: ["snapshot", "restore", "diff"] }),
         path: stringSchema({ description: "Snapshot file path", minLength: 1 }),
-        applyToFlash: optionalSchema(booleanSchema({ description: "Save configuration to flash after restore", default: false }), false),
+        applyToFlash: optionalSchema(booleanSchema({ description: "Save configuration to flash after restore (C64U/U64 and U2 only)", default: false }), false),
     },
     required: ["action", "path"],
     additionalProperties: false,
@@ -26,9 +27,13 @@ export const tools = [
             try {
                 const parsed = configSnapshotAndRestoreArgsSchema.parse(args ?? {});
                 const action = parsed.action;
+                const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                if (action === "restore" && parsed.applyToFlash && platform === "vice") {
+                    throw new ToolUnsupportedPlatformError("config_save_to_flash", platform, ["c64u", "u2"]);
+                }
                 const path = resolvePath(String(parsed.path));
-                await fs.mkdir(dirname(path), { recursive: true });
                 if (action === "snapshot") {
+                    await fs.mkdir(dirname(path), { recursive: true });
                     const [version, info, snapshotData] = await Promise.all([
                         ctx.client.version(),
                         ctx.client.info(),
@@ -66,7 +71,10 @@ export const tools = [
                         throw new ToolExecutionError("Batch update failed", { details: normalizeErrorDetails(result.details) });
                     }
                     if (parsed.applyToFlash) {
-                        await ctx.client.configSaveToFlash();
+                        const saved = await ctx.client.configSaveToFlash();
+                        if (!saved.success) {
+                            throw new ToolExecutionError("Configuration restored, but saving to flash failed", { details: normalizeErrorDetails(saved.details) });
+                        }
                     }
                     return jsonResult({ restored: true, categories: Object.keys(payload).length }, { success: true });
                 }

package/dist/tools/meta/configInventory.js

@@ -96,7 +96,10 @@ function normalizeSnapshotValue(value, entry) {
     if (value
         && typeof value === "object"
         && !Array.isArray(value)
-        && Object.keys(value).length === 1
+        && (Object.keys(value).length === 1
+            || (value.category === entry.category
+                && value.item === entry.item
+                && ["int", "string"].includes(String(value.type))))
         && Object.prototype.hasOwnProperty.call(value, "value")) {
         return value.value;
     }

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 } });
     }