c64bridge 0.7.4 → 0.8.1

package/dist/device.js

@@ -3,14 +3,43 @@
  */
 import axios from "axios";
 import { Buffer } from "node:buffer";
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
+import { ViceClient } from "./vice/viceClient.js";
+import { waitForBasicReady } from "./vice/readiness.js";
+import { startViceProcess } from "./vice/process.js";
 const DEFAULT_C64U_HOST = "c64u";
 const DEFAULT_C64U_PORT = 80;
+const DEFAULT_VICE_HOST = "127.0.0.1";
+const DEFAULT_VICE_PORT = 6502;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function coalesceMemoryWriteBlocks(blocks) {
+    const merged = [];
+    for (const block of blocks) {
+        if (!Number.isInteger(block.address) || block.address < 0 || block.address > 0xffff) {
+            throw new Error("Address must be within 0x0000-0xFFFF");
+        }
+        if (!(block.bytes instanceof Uint8Array) || block.bytes.length === 0) {
+            throw new Error("Bytes must be a non-empty Uint8Array");
+        }
+        const previous = merged[merged.length - 1];
+        const previousEnd = previous ? previous.address + previous.bytes.length : -1;
+        if (previous && previousEnd === block.address) {
+            const bytes = new Uint8Array(previous.bytes.length + block.bytes.length);
+            bytes.set(previous.bytes, 0);
+            bytes.set(block.bytes, previous.bytes.length);
+            previous.bytes = bytes;
+            continue;
+        }
+        merged.push({ address: block.address, bytes: Uint8Array.from(block.bytes) });
+    }
+    return merged;
+}
 function readConfigFile() {
     const envPath = process.env.C64BRIDGE_CONFIG;
     const candidates = [];
@@ -25,24 +54,41 @@ function readConfigFile() {
     const home = process.env.HOME || os.homedir();
     if (home)
         candidates.push(path.join(home, ".c64bridge.json"));
+    let foundCandidate = false;
+    const merged = {};
     for (const p of candidates) {
         try {
             if (fs.existsSync(p)) {
+                foundCandidate = true;
                 const text = fs.readFileSync(p, "utf8");
                 const json = JSON.parse(text);
-                return json ?? null;
+                if (!merged.c64u && json?.c64u && typeof json.c64u === "object" && !Array.isArray(json.c64u)) {
+                    merged.c64u = json.c64u;
+                }
+                if (!merged.vice && json?.vice && typeof json.vice === "object" && !Array.isArray(json.vice)) {
+                    merged.vice = json.vice;
+                }
+                if (merged.c64u && merged.vice) {
+                    break;
+                }
             }
         }
         catch { }
     }
-    return null;
+    return foundCandidate ? merged : null;
 }
 class C64uBackend {
     constructor(config) {
         this.type = "c64u";
-        const baseUrl = resolveBaseUrl(config);
+        const envHost = configuredString(process.env.C64U_HOST);
+        const envPort = configuredPort(process.env.C64U_PORT);
+        const configBaseUrl = normaliseBaseUrl(config.baseUrl);
+        const parsedConfigBaseUrl = configBaseUrl ? parseEndpoint(configBaseUrl) : {};
+        const baseUrl = envHost !== undefined || envPort !== undefined
+            ? buildBaseUrl(firstDefined(envHost, configuredString(config.host), configuredString(config.hostname), parsedConfigBaseUrl.hostname) ?? DEFAULT_C64U_HOST, firstDefined(envPort, configuredPort(config.port), parsedConfigBaseUrl.port) ?? DEFAULT_C64U_PORT)
+            : resolveBaseUrl(config);
         this.baseUrl = baseUrl;
-        this.networkPassword = configuredString(config.networkPassword);
+        this.networkPassword = firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(config.networkPassword));
         const http = createLoggingHttpClient({
             baseURL: baseUrl,
             timeout: 10000,
@@ -119,6 +165,10 @@ class C64uBackend {
             await this.api.v1.machineWritememCreate(":writemem", { address: addrStr }, Buffer.from(bytes), { headers: { "Content-Type": "application/octet-stream" } });
         }
     }
+    async writeMemoryBlocks(blocks) {
+        const mergedBlocks = coalesceMemoryWriteBlocks(blocks);
+        await Promise.all(mergedBlocks.map(({ address, bytes }) => this.writeMemory(address, bytes)));
+    }
     async reset() { const res = await this.api.v1.machineResetUpdate(":reset"); return { success: true, details: res.data }; }
     async reboot() { const res = await this.api.v1.machineRebootUpdate(":reboot"); return { success: true, details: res.data }; }
     async pause() { const res = await this.api.v1.machinePauseUpdate(":pause"); return { success: true, details: res.data }; }
@@ -153,61 +203,488 @@ class C64uBackend {
     async filesCreateDnp(p, tracks, options) { const res = await this.api.v1.filesCreateDnpUpdate(encodeURIComponent(p), ":create_dnp", { tracks, diskname: options?.diskname }); return { success: true, details: res.data }; }
     async modplayFile(pathStr) { const res = await this.api.v1.runnersModplayUpdate(":modplay", { file: pathStr }); return { success: true, details: res.data }; }
 }
-class ViceBackend {
+export class ViceBackend {
     constructor(config) {
         this.type = "vice";
-        this.exe = config.exe || which("x64sc") || which("x64") || "x64sc";
+        this.debugEnabled = process.env.VICE_DEVICE_TEST_DEBUG === "1";
+        this.startupPromise = null;
+        this.monitorQueue = Promise.resolve();
+        this.lastProcessStart = 0;
+        ViceBackend.ensureCleanupRegistration();
+        const envBinary = configuredString(process.env.VICE_BINARY);
+        const configBinary = config.exe !== undefined
+            ? configuredString(config.exe) ?? (typeof config.exe === "string" ? config.exe : String(config.exe))
+            : undefined;
+        this.exe = resolveViceBinary({ envBinary, configBinary });
+        const envHost = normaliseViceHost(process.env.VICE_HOST);
+        const envPort = normaliseVicePort(process.env.VICE_PORT);
+        this.host = firstDefined(envHost, normaliseViceHost(config.host)) ?? DEFAULT_VICE_HOST;
+        this.port = firstDefined(envPort, normaliseVicePort(config.port)) ?? DEFAULT_VICE_PORT;
+        this.directory = firstDefined(resolveViceDirectory(configuredString(process.env.VICE_DIRECTORY)), resolveViceDirectory(configuredString(config.directory)), findViceResourceDirectory(this.exe));
+        this.mockMode = (process.env.VICE_TEST_TARGET || "").toLowerCase() === "mock";
+        const hostLower = this.host.toLowerCase();
+        const isLocal = hostLower === "127.0.0.1" || hostLower === "localhost";
+        this.manageProcess = !this.mockMode && isLocal;
+        const warpEnv = configuredBoolean(process.env.VICE_WARP);
+        const visibleEnv = configuredBoolean(process.env.VICE_VISIBLE);
+        this.visible = visibleEnv ?? configuredBoolean(config.visible) ?? true;
+        this.warp = warpEnv ?? configuredBoolean(config.warp) ?? !this.visible;
+        this.extraArgs = resolveViceArgs(config);
     }
-    async ping() { return Boolean(which(this.exe)); }
-    async runPrg(prg) {
-        const tmp = writeTempPrg(prg);
+    async tryPingExisting() {
+        const client = new ViceClient();
         try {
-            const args = ["-silent", "-warp", "-autostart", tmp];
-            const exitCode = await spawnWithTimeout(this.exe, args, resolveTimeout());
-            return { success: exitCode === 0, details: { command: [this.exe, ...args].join(" "), exitCode } };
+            if (this.debugEnabled)
+                console.error("[vice-backend] probing existing VICE", this.host, this.port);
+            await client.connect(this.port, this.host);
+            await client.info();
+            if (this.debugEnabled)
+                console.error("[vice-backend] existing VICE is reachable");
+            return true;
+        }
+        catch {
+            return false;
         }
         finally {
+            client.close();
+        }
+    }
+    async waitForResponsiveMonitor(timeoutMs = 10000) {
+        const deadline = Date.now() + timeoutMs;
+        let lastError;
+        while (Date.now() < deadline) {
+            const client = new ViceClient();
             try {
-                fs.unlinkSync(tmp);
+                await client.connect(this.port, this.host);
+                await client.info();
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                await delay(250);
+            }
+            finally {
+                client.close();
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error(`VICE monitor at ${this.host}:${this.port} did not become responsive within ${timeoutMs}ms`);
+    }
+    async waitForUsableMachine(timeoutMs = 20000) {
+        const client = new ViceClient();
+        try {
+            await client.connect(this.port, this.host);
+            const readiness = await waitForBasicReady(client, { timeoutMs, ensurePrompt: true });
+            if (!readiness.pointersOk || !readiness.promptOk) {
+                throw new Error(`VICE machine at ${this.host}:${this.port} did not reach the BASIC prompt within ${timeoutMs}ms`);
+            }
+        }
+        finally {
+            client.close();
+        }
+    }
+    async ensureProcessInternal() {
+        if (!this.manageProcess)
+            return;
+        const key = `${this.host}:${this.port}`;
+        const existing = ViceBackend.supervisors.get(key);
+        if (existing) {
+            const running = existing.process.exitCode === null && existing.process.signalCode === null;
+            if (running)
+                return;
+            try {
+                await existing.stop();
             }
             catch { }
+            ViceBackend.supervisors.delete(key);
+        }
+        if (await this.tryPingExisting()) {
+            return;
+        }
+        if (this.debugEnabled) {
+            console.error("[vice-backend] starting VICE process", {
+                binary: this.exe,
+                host: this.host,
+                port: this.port,
+                warp: this.warp,
+                visible: this.visible,
+                extraArgs: this.extraArgs,
+            });
+        }
+        const handle = await startViceProcess({
+            binary: this.exe,
+            directory: this.directory,
+            host: this.host,
+            port: this.port,
+            warp: this.warp,
+            visible: this.visible,
+            extraArgs: this.extraArgs.length > 0 ? this.extraArgs : undefined,
+        });
+        this.lastProcessStart = Date.now();
+        if (this.debugEnabled) {
+            console.error("[vice-backend] VICE process started", { pid: handle.process.pid });
+        }
+        ViceBackend.supervisors.set(key, handle);
+        handle.process.once("exit", () => {
+            ViceBackend.supervisors.delete(key);
+        });
+        // Allow VICE to fully initialize its display before connecting to the monitor.
+        // Early monitor connection can interfere with the boot sequence.
+        await delay(1000);
+        await this.waitForResponsiveMonitor(20000);
+        await this.waitForUsableMachine(20000);
+    }
+    async ensureProcess() {
+        if (!this.manageProcess) {
+            return;
+        }
+        if (!this.startupPromise) {
+            this.startupPromise = this.ensureProcessInternal().finally(() => {
+                this.startupPromise = null;
+            });
+        }
+        await this.startupPromise;
+    }
+    static ensureCleanupRegistration() {
+        if (ViceBackend.cleanupRegistered) {
+            return;
         }
+        ViceBackend.cleanupRegistered = true;
+        process.once("exit", () => {
+            for (const [, handle] of ViceBackend.supervisors) {
+                handle.stop().catch(() => { });
+            }
+            ViceBackend.supervisors.clear();
+        });
+    }
+    async withClient(fn) {
+        const previous = this.monitorQueue;
+        let releaseQueue = () => { };
+        this.monitorQueue = new Promise((resolve) => {
+            releaseQueue = resolve;
+        });
+        await previous;
+        try {
+            if (!this.mockMode)
+                await this.ensureProcess();
+            const client = new ViceClient();
+            if (this.debugEnabled)
+                console.error("[vice-backend] connecting to VICE monitor", { host: this.host, port: this.port });
+            await client.connect(this.port, this.host);
+            if (this.manageProcess && this.lastProcessStart > 0) {
+                const sinceStart = Date.now() - this.lastProcessStart;
+                const settleDelay = 500 - sinceStart;
+                if (settleDelay > 0) {
+                    await delay(settleDelay);
+                }
+            }
+            try {
+                if (this.debugEnabled)
+                    console.error("[vice-backend] connected to VICE monitor");
+                return await fn(client);
+            }
+            finally {
+                if (this.debugEnabled)
+                    console.error("[vice-backend] closing VICE monitor connection");
+                client.close();
+            }
+        }
+        finally {
+            releaseQueue();
+        }
+    }
+    async withMonitor(fn) {
+        return this.withClient(fn);
+    }
+    async ping() {
+        const attempts = 8;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            try {
+                await this.withClient(async (client) => {
+                    await client.info();
+                });
+                return true;
+            }
+            catch (error) {
+                if (this.debugEnabled) {
+                    console.error(`[vice-backend] ping failed (attempt ${attempt}/${attempts})`, error);
+                }
+                if (attempt < attempts) {
+                    await delay(Math.min(1000, 200 * attempt));
+                }
+            }
+        }
+        return false;
+    }
+    async injectPrg(buffer) {
+        if (buffer.length < 2)
+            throw new Error("PRG data too short");
+        const loadAddress = buffer.readUInt16LE(0);
+        const body = buffer.subarray(2);
+        await this.withClient(async (client) => {
+            await client.reset();
+            await waitForBasicReady(client, { timeoutMs: 10000, ensurePrompt: true });
+            if (body.length > 0)
+                await client.memSet(loadAddress, body);
+            const programEnd = loadAddress + body.length;
+            const ptrs = Buffer.alloc(8);
+            ptrs.writeUInt16LE(loadAddress, 0);
+            ptrs.writeUInt16LE(programEnd, 2);
+            ptrs.writeUInt16LE(programEnd, 4);
+            ptrs.writeUInt16LE(programEnd, 6);
+            await client.memSet(0x002B, ptrs);
+            await client.keyboardFeed("RUN\r");
+            await client.exitMonitor();
+        });
+    }
+    async runPrg(prg) {
+        const buffer = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
+        await this.injectPrg(buffer);
+        return { success: true };
     }
     async loadPrgFile(_path) { throw unsupported("loadPrgFile"); }
     async runPrgFile(prgPath) {
-        const args = ["-silent", "-warp", "-autostart", prgPath];
-        const exitCode = await spawnWithTimeout(this.exe, args, resolveTimeout());
-        return { success: exitCode === 0, details: { command: [this.exe, ...args].join(" "), exitCode } };
+        const data = fs.readFileSync(prgPath);
+        await this.injectPrg(data);
+        return { success: true };
     }
     async runCrtFile(_path) { throw unsupported("runCrtFile"); }
     async sidplayFile(_p) { throw unsupported("sidplayFile"); }
     async sidplayAttachment(_sid) { throw unsupported("sidplayAttachment"); }
-    async readMemory(_a) { throw unsupported("readMemory"); }
-    async writeMemory(_a, _b) { throw unsupported("writeMemory"); }
-    async reset() { throw unsupported("reset"); }
-    async reboot() { throw unsupported("reboot"); }
-    async pause() { throw unsupported("pause"); }
-    async resume() { throw unsupported("resume"); }
-    async poweroff() { throw unsupported("poweroff"); }
+    async readMemory(address, length) {
+        if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
+            throw new Error("Address must be within 0x0000-0xFFFF");
+        }
+        if (!Number.isInteger(length) || length <= 0) {
+            throw new Error("Length must be positive");
+        }
+        const end = Math.min(0xffff, address + length - 1);
+        return await this.withClient(async (client) => {
+            const buf = await client.memGet(address, end);
+            return buf.subarray(0, Math.min(buf.length, length));
+        });
+    }
+    async writeMemory(address, bytes) {
+        if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
+            throw new Error("Address must be within 0x0000-0xFFFF");
+        }
+        if (!(bytes instanceof Uint8Array) || bytes.length === 0) {
+            throw new Error("Bytes must be a non-empty Uint8Array");
+        }
+        await this.withClient(async (client) => {
+            await client.memSet(address, Buffer.from(bytes));
+        });
+    }
+    async writeMemoryBlocks(blocks) {
+        const mergedBlocks = coalesceMemoryWriteBlocks(blocks);
+        await this.withClient(async (client) => {
+            for (const { address, bytes } of mergedBlocks) {
+                await client.memSet(address, Buffer.from(bytes));
+            }
+        });
+    }
+    async reset() {
+        await this.withClient(async (client) => {
+            await client.reset();
+            const opts = this.debugEnabled
+                ? {
+                    timeoutMs: 20000,
+                    ensurePrompt: true,
+                    onPointersSample: (p) => {
+                        console.error("[vice-backend] BASIC pointers", p);
+                    },
+                }
+                : { timeoutMs: 20000, ensurePrompt: true };
+            const readiness = await waitForBasicReady(client, opts);
+            if (this.debugEnabled)
+                console.error("[vice-backend] waitForBasicReady result", readiness);
+        });
+        return { success: true };
+    }
+    async reboot() { return this.reset(); }
+    async pause() {
+        return {
+            success: false,
+            details: {
+                code: "UNSUPPORTED",
+                message: "VICE pause is not implemented as a durable machine stop; use per-operation monitor access instead.",
+            },
+        };
+    }
+    async resume() {
+        return {
+            success: false,
+            details: {
+                code: "UNSUPPORTED",
+                message: "VICE resume is unavailable because durable pause is not supported.",
+            },
+        };
+    }
+    async poweroff() {
+        const key = this.supervisorKey();
+        const managedHandle = this.manageProcess ? ViceBackend.supervisors.get(key) : null;
+        try {
+            await this.withClient(async (client) => {
+                try {
+                    await client.quit();
+                }
+                catch {
+                    // Ignore transport errors during quit; the emulator will terminate regardless.
+                }
+            });
+            if (managedHandle) {
+                try {
+                    await managedHandle.stop();
+                }
+                catch { }
+                ViceBackend.supervisors.delete(key);
+            }
+            return { success: true };
+        }
+        catch (error) {
+            const details = error instanceof Error
+                ? { message: error.message }
+                : error;
+            return { success: false, details };
+        }
+    }
     async menuButton() { throw unsupported("menuButton"); }
     async debugregRead() { throw unsupported("debugregRead"); }
     async debugregWrite(_v) { throw unsupported("debugregWrite"); }
-    async version() { return { emulator: "vice" }; }
-    async info() { return { emulator: "vice", phase: 1 }; }
-    async drivesList() { throw unsupported("drivesList"); }
-    async driveMount() { throw unsupported("driveMount"); }
-    async driveRemove() { throw unsupported("driveRemove"); }
-    async driveReset() { throw unsupported("driveReset"); }
-    async driveOn() { throw unsupported("driveOn"); }
-    async driveOff() { throw unsupported("driveOff"); }
-    async driveSetMode() { throw unsupported("driveSetMode"); }
+    async version() { return { emulator: "vice", host: this.host, port: this.port }; }
+    async info() {
+        return await this.withClient(async (client) => {
+            await client.info();
+            return { emulator: "vice", host: this.host, port: this.port };
+        });
+    }
+    getEndpoint() {
+        return { host: this.host, port: this.port };
+    }
+    async drivesList() {
+        return await this.withClient(async (client) => {
+            const drives = [];
+            for (const n of [8, 9, 10, 11]) {
+                try {
+                    const enabled = await client.resourceGet(`Drive${n}CPUEnabled`);
+                    const image = await client.resourceGet(`Drive${n}Image`);
+                    const typeRes = await client.resourceGet(`Drive${n}Type`);
+                    drives.push({
+                        id: `drive${n}`,
+                        power: (typeof enabled.value === "number" ? enabled.value : 0) ? "on" : "off",
+                        image: typeof image.value === "string" && image.value ? image.value : null,
+                        type: typeRes.value,
+                    });
+                }
+                catch {
+                    drives.push({ id: `drive${n}`, power: "off", image: null, type: 0 });
+                }
+            }
+            return drives;
+        });
+    }
+    async driveMount(drive, imagePath) {
+        const n = parseDriveNumber(drive);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
+            await client.resourceSet(`Drive${n}Image`, imagePath);
+        });
+        return { success: true, details: { drive, image: imagePath } };
+    }
+    async driveRemove(drive) {
+        const n = parseDriveNumber(drive);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}Image`, "");
+        });
+        return { success: true, details: { drive } };
+    }
+    async driveReset(drive) {
+        const n = parseDriveNumber(drive);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}CPUEnabled`, 0);
+            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
+        });
+        return { success: true, details: { drive } };
+    }
+    async driveOn(drive) {
+        const n = parseDriveNumber(drive);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
+        });
+        return { success: true, details: { drive, power: "on" } };
+    }
+    async driveOff(drive) {
+        const n = parseDriveNumber(drive);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}CPUEnabled`, 0);
+        });
+        return { success: true, details: { drive, power: "off" } };
+    }
+    async driveSetMode(drive, mode) {
+        const n = parseDriveNumber(drive);
+        const DRIVE_TYPE = { "1541": 2, "1571": 8, "1581": 11 };
+        const typeNum = DRIVE_TYPE[mode];
+        if (typeNum === undefined)
+            throw new Error(`Unknown drive mode: ${mode}`);
+        await this.withClient(async (client) => {
+            await client.resourceSet(`Drive${n}Type`, typeNum);
+        });
+        return { success: true, details: { drive, mode } };
+    }
     async driveLoadRom() { throw unsupported("driveLoadRom"); }
     async streamStart() { throw unsupported("streamStart"); }
     async streamStop() { throw unsupported("streamStop"); }
-    async configsList() { throw unsupported("configsList"); }
-    async configGet() { throw unsupported("configGet"); }
-    async configSet() { throw unsupported("configSet"); }
-    async configBatchUpdate() { throw unsupported("configBatchUpdate"); }
+    async configsList() {
+        return {
+            categories: [
+                {
+                    name: "VICE",
+                    items: [
+                        "WarpMode", "SoundVolume", "Drive8CPUEnabled", "Drive9CPUEnabled",
+                        "Drive10CPUEnabled", "Drive11CPUEnabled", "Drive8Image", "Drive9Image",
+                        "Drive8Type", "Drive9Type", "VICIIBorderMode", "VICIIFullscreen",
+                    ],
+                },
+            ],
+        };
+    }
+    async configGet(_category, item) {
+        if (!item)
+            throw unsupported("configGet without item name");
+        return await this.withClient(async (client) => {
+            const res = await client.resourceGet(item);
+            return { category: _category, item, value: res.value, type: res.type };
+        });
+    }
+    async configSet(_category, item, value) {
+        const numValue = Number(value);
+        const parsed = !isNaN(numValue) && value.trim() !== "" ? numValue : value;
+        await this.withClient(async (client) => {
+            await client.resourceSet(item, parsed);
+        });
+        return { success: true, details: { item, value: parsed } };
+    }
+    async configBatchUpdate(payload) {
+        const results = [];
+        await this.withClient(async (client) => {
+            for (const [category, items] of Object.entries(payload)) {
+                for (const [item, value] of Object.entries(items)) {
+                    try {
+                        const str = String(value ?? "");
+                        const numValue = Number(str);
+                        const parsed = !isNaN(numValue) && str.trim() !== "" ? numValue : str;
+                        await client.resourceSet(item, parsed);
+                        results.push({ item: `${category}/${item}`, success: true });
+                    }
+                    catch (err) {
+                        results.push({ item: `${category}/${item}`, success: false, error: err instanceof Error ? err.message : String(err) });
+                    }
+                }
+            }
+        });
+        return { success: results.every((r) => r.success), details: { results } };
+    }
     async configLoadFromFlash() { throw unsupported("configLoadFromFlash"); }
     async configSaveToFlash() { throw unsupported("configSaveToFlash"); }
     async configResetToDefault() { throw unsupported("configResetToDefault"); }
@@ -216,8 +693,20 @@ class ViceBackend {
     async filesCreateD71() { throw unsupported("filesCreateD71"); }
     async filesCreateD81() { throw unsupported("filesCreateD81"); }
     async filesCreateDnp() { throw unsupported("filesCreateDnp"); }
+    supervisorKey() {
+        return `${this.host}:${this.port}`;
+    }
 }
+ViceBackend.supervisors = new Map();
+ViceBackend.cleanupRegistered = false;
 function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend in phase one`); err.code = "UNSUPPORTED"; return err; }
+function parseDriveNumber(drive) {
+    const match = /\d+/.exec(drive);
+    const n = match ? parseInt(match[0], 10) : NaN;
+    if (isNaN(n) || n < 8 || n > 11)
+        throw new Error(`Invalid drive specification: ${drive}`);
+    return n;
+}
 function extractBytes(data) {
     if (!data)
         return new Uint8Array();
@@ -271,24 +760,23 @@ function which(binary) {
     }
     return null;
 }
-function writeTempPrg(prg) {
-    const dir = process.env.TMPDIR || process.env.TEMP || "/tmp";
-    const file = path.join(dir, `c64bridge-${Date.now()}-${Math.random().toString(16).slice(2)}.prg`);
-    const buf = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
-    fs.writeFileSync(file, buf);
-    return file;
+function resolveViceBinary(options, findBinary = which) {
+    const explicit = firstDefined(options.envBinary, options.configBinary);
+    if (explicit) {
+        const resolvedExplicit = findBinary(explicit);
+        if (resolvedExplicit) {
+            return resolvedExplicit;
+        }
+    }
+    for (const candidate of ["/usr/local/bin/x64sc", "/usr/local/bin/x64"]) {
+        if (findBinary(candidate)) {
+            return candidate;
+        }
+    }
+    return findBinary("x64sc") ?? findBinary("x64") ?? "x64sc";
 }
-function resolveTimeout() { const n = Number(process.env.VICE_RUN_TIMEOUT_MS); return Number.isFinite(n) && n > 0 ? Math.floor(n) : 10000; }
-async function spawnWithTimeout(file, args, timeoutMs) {
-    return await new Promise((resolve) => {
-        const child = spawn(file, args, { stdio: ["ignore", "ignore", "pipe"] });
-        const timer = setTimeout(() => { try {
-            child.kill("SIGKILL");
-        }
-        catch { } }, Math.max(1000, timeoutMs));
-        child.on("close", (code) => { clearTimeout(timer); resolve(code ?? 0); });
-        child.on("error", () => { clearTimeout(timer); resolve(127); });
-    });
+export function __resolveViceBinaryForTests(options, findBinary) {
+    return resolveViceBinary(options, findBinary ?? which);
 }
 export async function createFacade(logger, options) {
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
@@ -312,7 +800,8 @@ export async function createFacade(logger, options) {
     if (envMode === "vice") {
         const backend = new ViceBackend(cfg?.vice ?? {});
         logger?.info?.("Active backend: vice (from env override)");
-        return { facade: backend, selected: "vice", reason: "env override", details: { exe: (cfg?.vice?.exe || which("x64sc") || "x64sc") } };
+        const endpoint = backend.getEndpoint();
+        return { facade: backend, selected: "vice", reason: "env override", details: { host: endpoint.host, port: endpoint.port } };
     }
     if (hasC64u && !hasVice) {
         const backend = new C64uBackend(cfg.c64u);
@@ -322,7 +811,8 @@ export async function createFacade(logger, options) {
     if (!hasC64u && hasVice) {
         const backend = new ViceBackend(cfg.vice);
         logger?.info?.("Active backend: vice (from config)");
-        return { facade: backend, selected: "vice", reason: "config only", details: { exe: (cfg.vice.exe || which("x64sc") || "x64sc") } };
+        const endpoint = backend.getEndpoint();
+        return { facade: backend, selected: "vice", reason: "config only", details: { host: endpoint.host, port: endpoint.port } };
     }
     if (hasC64u && hasVice) {
         const backend = new C64uBackend(cfg.c64u);
@@ -342,7 +832,46 @@ export async function createFacade(logger, options) {
     catch { }
     const backend = new ViceBackend(cfg?.vice ?? {});
     logger?.info?.("Active backend: vice (fallback – hardware unavailable)");
-    return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { exe: (cfg?.vice?.exe || which("x64sc") || "x64sc") } };
+    const endpoint = backend.getEndpoint();
+    return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { host: endpoint.host, port: endpoint.port } };
+}
+export async function createAllFacades(logger, options) {
+    const primary = await createFacade(logger);
+    const config = readConfigFile();
+    const secondaryType = primary.selected === "c64u" ? "vice" : "c64u";
+    if (secondaryType === "c64u" && shouldProvisionSecondaryC64u(config, options)) {
+        const secondaryConfig = {
+            ...(config?.c64u ?? {}),
+            ...(!config?.c64u?.baseUrl && options?.preferredC64uBaseUrl ? { baseUrl: options.preferredC64uBaseUrl } : {}),
+            ...(!config?.c64u?.networkPassword && options?.preferredC64uNetworkPassword
+                ? { networkPassword: options.preferredC64uNetworkPassword }
+                : {}),
+        };
+        return {
+            primary,
+            secondary: new C64uBackend(secondaryConfig),
+            secondaryType,
+        };
+    }
+    if (secondaryType === "vice" && config?.vice) {
+        return {
+            primary,
+            secondary: new ViceBackend(config.vice),
+            secondaryType,
+        };
+    }
+    return {
+        primary,
+        secondary: null,
+        secondaryType: null,
+    };
+}
+function shouldProvisionSecondaryC64u(config, options) {
+    return Boolean(config?.c64u
+        || options?.preferredC64uBaseUrl
+        || configuredString(process.env.C64U_HOST)
+        || configuredPort(process.env.C64U_PORT)
+        || configuredString(process.env.C64U_PASSWORD));
 }
 function resolveBaseUrl(config) {
     const explicit = normaliseBaseUrl(config.baseUrl);
@@ -367,6 +896,83 @@ function configuredString(value) {
     }
     return undefined;
 }
+function configuredBoolean(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    const input = configuredString(value);
+    if (!input)
+        return undefined;
+    const normalised = input.toLowerCase();
+    if (normalised === "1" || normalised === "true" || normalised === "yes" || normalised === "on") {
+        return true;
+    }
+    if (normalised === "0" || normalised === "false" || normalised === "no" || normalised === "off") {
+        return false;
+    }
+    return undefined;
+}
+function resolveViceArgs(config) {
+    const argsEnv = configuredString(process.env.VICE_ARGS);
+    if (argsEnv) {
+        return parseArgsList(argsEnv);
+    }
+    if (Array.isArray(config.args)) {
+        return config.args
+            .filter((value) => typeof value === "string")
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0);
+    }
+    if (typeof config.args === "string") {
+        return parseArgsList(config.args);
+    }
+    return [];
+}
+function resolveViceDirectory(value) {
+    const input = configuredString(value);
+    if (!input) {
+        return undefined;
+    }
+    return isViceResourceDirectory(input) ? input : undefined;
+}
+function findViceResourceDirectory(binaryPath) {
+    const candidates = new Set();
+    const resolvedBinary = configuredString(binaryPath);
+    if (resolvedBinary) {
+        const binaryDir = path.dirname(resolvedBinary);
+        candidates.add(path.resolve(binaryDir, "..", "share", "vice"));
+        candidates.add(path.resolve(binaryDir, "..", "..", "share", "vice"));
+    }
+    candidates.add("/usr/local/share/vice");
+    candidates.add("/usr/share/vice");
+    candidates.add("/opt/homebrew/share/vice");
+    candidates.add("/opt/local/share/vice");
+    for (const candidate of candidates) {
+        if (isViceResourceDirectory(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function isViceResourceDirectory(candidate) {
+    const normalized = configuredString(candidate);
+    if (!normalized) {
+        return false;
+    }
+    const requiredFiles = [
+        path.join(normalized, "C64", "kernal-901227-03.bin"),
+        path.join(normalized, "C64", "basic-901226-01.bin"),
+        path.join(normalized, "C64", "chargen-901225-01.bin"),
+    ];
+    return requiredFiles.every((filePath) => {
+        try {
+            return fs.existsSync(filePath);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 function configuredPort(value) {
     if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535) {
         return value;
@@ -418,6 +1024,16 @@ function formatHost(host) {
 function stripTrailingSlash(input) {
     return input.replace(/\/+$/, "");
 }
+function parseArgsList(input) {
+    const args = [];
+    const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;
+    let match;
+    while ((match = pattern.exec(input)) !== null) {
+        const value = match[1] ?? match[2] ?? match[3] ?? "";
+        args.push(value.replace(/\\(["'\\])/g, "$1"));
+    }
+    return args;
+}
 function firstDefined(...values) {
     for (const value of values) {
         if (value !== undefined && value !== null)
@@ -425,3 +1041,10 @@ function firstDefined(...values) {
     }
     return undefined;
 }
+function normaliseViceHost(input) {
+    const trimmed = configuredString(input);
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+function normaliseVicePort(value) {
+    return configuredPort(value);
+}