c64bridge 1.0.7 → 1.1.0

package/dist/config.js

@@ -24,6 +24,12 @@ export function loadConfig() {
         }
         catch (error) {
             if (error.code !== "ENOENT") {
+                if (candidatePath === configPath) {
+                    // An explicitly named file that cannot be used must not silently
+                    // hand control to another candidate, which may be another machine.
+                    // The parser message is omitted because it can quote file content.
+                    throw new Error(`C64BRIDGE_CONFIG file '${candidatePath}' cannot be parsed (${error instanceof Error ? error.name : "unreadable"}); fix or remove it`);
+                }
                 // Deliberately omit file contents/credentials. Configuration mistakes
                 // should not prevent the MCP server from exposing a recoverable path.
                 console.error(`[c64bridge] ignoring configuration '${candidatePath}': ${error instanceof Error ? error.name : "unreadable"}`);
@@ -86,14 +92,16 @@ export function resolveUltimateEndpoint(profile, section, legacy) {
     const envHost = profile === "u2" ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST;
     const envPort = profile === "u2" ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT;
     const envPassword = profile === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD;
-    const parsedSectionHost = parseEndpoint(configuredString(section?.host));
-    const parsedSectionHostname = parseEndpoint(configuredString(section?.hostname));
-    const parsedLegacyHost = parseEndpoint(configuredString(legacy?.c64_host));
-    const parsedLegacyIp = parseEndpoint(configuredString(legacy?.c64_ip));
-    const parsedEnvHost = parseEndpoint(configuredString(envHost));
+    const envHostName = profile === "u2" && process.env.U2_HOST !== undefined ? "U2_HOST" : "C64U_HOST";
+    const envPortName = profile === "u2" && process.env.U2_PORT !== undefined ? "U2_PORT" : "C64U_PORT";
+    const parsedSectionHost = parseEndpoint(configuredString(section?.host), `${profile}.host`);
+    const parsedSectionHostname = parseEndpoint(configuredString(section?.hostname), `${profile}.hostname`);
+    const parsedLegacyHost = parseEndpoint(configuredString(legacy?.c64_host), "c64_host");
+    const parsedLegacyIp = parseEndpoint(configuredString(legacy?.c64_ip), "c64_ip");
+    const parsedEnvHost = parseEndpoint(configuredString(envHost), envHostName);
     const parsedBaseOverrides = [
-        parseEndpoint(normaliseBaseUrl(configuredString(section?.baseUrl))),
-        parseEndpoint(normaliseBaseUrl(configuredString(legacy?.baseUrl))),
+        parseEndpoint(normaliseBaseUrl(configuredString(section?.baseUrl)), `${profile}.baseUrl`),
+        parseEndpoint(normaliseBaseUrl(configuredString(legacy?.baseUrl)), "baseUrl"),
     ];
     const hostCandidates = [
         parsedEnvHost.hostname,
@@ -104,12 +112,12 @@ export function resolveUltimateEndpoint(profile, section, legacy) {
         ...parsedBaseOverrides.map((entry) => entry.hostname),
     ];
     const portCandidates = [
-        configuredPort(envPort),
+        configuredPort(envPort, envPortName),
         parsedEnvHost.port,
-        configuredPort(section?.port),
+        configuredPort(section?.port, `${profile}.port`),
         parsedSectionHost.port,
         parsedSectionHostname.port,
-        configuredPort(legacy?.c64_port),
+        configuredPort(legacy?.c64_port, "c64_port"),
         parsedLegacyHost.port,
         parsedLegacyIp.port,
         ...parsedBaseOverrides.map((entry) => entry.port),
@@ -149,17 +157,23 @@ function nonEmptyString(value) {
     const trimmed = configuredString(value);
     return trimmed ? trimmed : undefined;
 }
-function configuredPort(value) {
-    if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535) {
-        return value;
+/** An absent or empty value is "not set"; any other value must be a valid port. */
+function configuredPort(value, source) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string" && !value.trim())
+        return undefined;
+    let parsed;
+    if (typeof value === "number") {
+        parsed = value;
     }
-    if (typeof value === "string" && value.trim()) {
-        const parsed = Number(value.trim());
-        if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) {
-            return parsed;
-        }
+    else if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+        parsed = Number(value.trim());
     }
-    return undefined;
+    if (parsed !== undefined && Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) {
+        return parsed;
+    }
+    throw new Error(`Invalid port ${JSON.stringify(typeof value === "string" ? value.trim() : value)} in ${source}: expected an integer from 1 to 65535`);
 }
 function configuredBoolean(value) {
     if (typeof value === "boolean") {
@@ -189,23 +203,31 @@ function normaliseBaseUrl(value) {
     }
     return stripTrailingSlash(input);
 }
-function parseEndpoint(value) {
+function parseEndpoint(value, source) {
     const input = configuredString(value);
     if (!input)
         return {};
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(input);
+    // A bare IPv6 address (two or more colons, no brackets) is not a valid URL
+    // authority until it is bracketed.
+    const bareIpv6 = !hasScheme && !input.startsWith("[") && (input.match(/:/g)?.length ?? 0) >= 2 && !input.includes("/");
+    let url;
     try {
-        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(input);
-        const url = new URL(hasScheme ? input : `http://${input}`);
+        url = new URL(hasScheme ? input : `http://${bareIpv6 ? `[${input}]` : input}`);
+    }
+    catch {
+        // Drop any user:password@ prefix before echoing the value.
+        const shown = input.replace(/^([a-z][a-z0-9+.-]*:\/\/)?[^@/]*@/i, "$1");
+        throw new Error(`Invalid host ${JSON.stringify(shown)} in ${source}: expected a host name or IP address, optionally with a port`);
+    }
+    {
         const hostname = url.hostname || undefined;
-        const port = url.port ? configuredPort(url.port) : undefined;
+        const port = url.port ? configuredPort(url.port, source) : undefined;
         const baseUrl = stripTrailingSlash(`${url.protocol}//${url.host}`);
         // Scheme and path prefix kept, for an Ultimate reached through a reverse proxy.
         const fullUrl = stripTrailingSlash(`${url.protocol}//${url.host}${url.pathname}`);
         return { hostname, port, baseUrl, fullUrl };
     }
-    catch {
-        return {};
-    }
 }
 function stripTrailingSlash(input) {
     return input.replace(/\/+$/, "");

package/dist/device.js

@@ -4,14 +4,25 @@
 import axios from "axios";
 import { Buffer } from "node:buffer";
 import fs from "node:fs";
+import { resolveHostPath, DISK_IMAGE_MAX_READ_BYTES } from "./hostPaths.js";
 import path from "node:path";
 import { Api } from "../generated/c64/index.js";
-import { createLoggingHttpClient } from "./loggingHttpClient.js";
+import { createLoggingHttpClient, RequestQueue } from "./loggingHttpClient.js";
 import { ViceClient } from "./vice/viceClient.js";
+import { resourceNameProblem } from "./vice/resourcePolicy.js";
 import { waitForBasicReady } from "./vice/readiness.js";
 import { screenCodesToAscii } from "./petscii.js";
 import { startViceProcess } from "./vice/process.js";
 import { loadConfig, resolveUltimateEndpoint } from "./config.js";
+let signalDelegate = false;
+/** Stops every VICE process started by this server, synchronously. */
+export function stopManagedViceProcessesSync() {
+    ViceBackend.stopAllSupervisorsSync();
+}
+/** Marks that the caller owns signal handling and process exit (see mcp-server shutdown). */
+export function delegateViceSignalHandling() {
+    signalDelegate = true;
+}
 const DEFAULT_VICE_HOST = "127.0.0.1";
 const DEFAULT_VICE_PORT = 6502;
 function delay(ms) {
@@ -56,9 +67,14 @@ function coalesceMemoryWriteBlocks(blocks) {
 function readConfigFile() {
     const config = loadConfig();
     const sections = config.backendConfig;
+    // An endpoint environment variable selects that backend explicitly, like a
+    // config section does, so an offline device is reported as unreachable
+    // instead of silently replaced by an emulator.
+    const envSelects = (prefix) => ["HOST", "PORT", "PASSWORD"]
+        .some((suffix) => (process.env[`${prefix}${suffix}`] ?? "").trim() !== "");
     return {
-        c64u: sections.c64u || config.legacyUltimateEndpoint ? config.ultimate.c64u : undefined,
-        u2: sections.u2 ? config.ultimate.u2 : undefined,
+        c64u: sections.c64u || config.legacyUltimateEndpoint || envSelects("C64U_") ? config.ultimate.c64u : undefined,
+        u2: sections.u2 || envSelects("U2_") ? config.ultimate.u2 : undefined,
         vice: sections.vice,
         endpoints: config.ultimate,
     };
@@ -82,16 +98,53 @@ function driveImage(info) {
 function uploadFile(bytes, name) {
     return new File([Uint8Array.from(bytes)], name, { type: "application/octet-stream" });
 }
+/**
+ * Reachability probe for an Ultimate REST endpoint: GET <baseUrl>/v1/version,
+ * keeping any reverse-proxy path prefix. Any HTTP response, including 403 or
+ * 404, shows that a server answers at the address; only a transport failure
+ * (refused, unreachable, timeout) counts as unreachable.
+ */
+export async function probeUltimateReachable(baseUrl, timeout, networkPassword) {
+    try {
+        await axios.get(`${baseUrl.replace(/\/+$/, "")}/v1/version`, {
+            timeout,
+            headers: buildC64uHeaders(networkPassword),
+            validateStatus: () => true,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resources that the VICE config inventory (configsList) advertises and that
+ * snapshot/restore round-trip. They are vetted here and are not host file
+ * names, so c64_config accepts them in addition to the shared c64_vice policy.
+ */
+const VICE_CONFIG_INVENTORY = [
+    "SoundVolume", "Drive8Type", "Drive9Type", "Drive10Type", "Drive11Type",
+    "VICIIBorderMode", "VICIIFullscreen", "MachineVideoStandard", "SidModel",
+];
+/** c64_config on VICE follows the same resource policy as c64_vice. */
+function assertAllowedViceResource(name) {
+    if (VICE_CONFIG_INVENTORY.includes(name))
+        return;
+    const problem = resourceNameProblem(name);
+    if (problem)
+        throw new Error(`VICE resource '${name}' is not allowed: ${problem.message}`);
+}
 class C64uBackend {
     constructor(endpoint, type = "c64u") {
         this.type = type;
         this.baseUrl = endpoint.baseUrl;
+        this.requestQueue = RequestQueue.forDevice(this.baseUrl);
         this.networkPassword = endpoint.networkPassword;
         const http = createLoggingHttpClient({
             baseURL: this.baseUrl,
             timeout: 10000,
             headers: buildC64uHeaders(this.networkPassword),
-        });
+        }, undefined, this.requestQueue);
         this.api = new Api(http);
     }
     requireC64u(feature) {
@@ -109,16 +162,7 @@ class C64uBackend {
             : { success: true, details: data };
     }
     async ping() {
-        try {
-            const res = await axios.get(this.baseUrl, {
-                timeout: 2000,
-                headers: buildC64uHeaders(this.networkPassword),
-            });
-            return res.status >= 200 && res.status < 500;
-        }
-        catch {
-            return false;
-        }
+        return this.requestQueue.run(() => probeUltimateReachable(this.baseUrl, 2000, this.networkPassword));
     }
     async runPrg(prg) {
         const payload = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
@@ -286,9 +330,9 @@ class C64uBackend {
     async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(encodeURIComponent(cat), encodeURIComponent(item)) : await this.api.v1.configsDetail(encodeURIComponent(cat)); return res.data; }
     async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(encodeURIComponent(cat), encodeURIComponent(item), { value }); return this.actionResult(res.data); }
     async configBatchUpdate(payload) { const res = await this.api.v1.configsCreate(payload); return this.actionResult(res.data); }
-    async configLoadFromFlash() { const res = await this.api.v1.configsLoadFromFlashUpdate(":load_from_flash"); return this.actionResult(res.data); }
-    async configSaveToFlash() { const res = await this.api.v1.configsSaveToFlashUpdate(":save_to_flash"); return this.actionResult(res.data); }
-    async configResetToDefault() { const res = await this.api.v1.configsResetToDefaultUpdate(":reset_to_default"); return this.actionResult(res.data); }
+    async configLoadFromFlash(category) { const res = await this.api.v1.configsLoadFromFlashUpdate(configActionRoute(":load_from_flash", category)); return this.actionResult(res.data); }
+    async configSaveToFlash(category) { const res = await this.api.v1.configsSaveToFlashUpdate(configActionRoute(":save_to_flash", category)); return this.actionResult(res.data); }
+    async configResetToDefault(category) { const res = await this.api.v1.configsResetToDefaultUpdate(configActionRoute(":reset_to_default", category)); return this.actionResult(res.data); }
     async filesInfo(p) { const res = await this.api.v1.filesInfoDetail(encodeDevicePath(p), ":info"); return res.data; }
     async filesCreateD64(p, options) { const res = await this.api.v1.filesCreateD64Update(encodeDevicePath(p), ":create_d64", { tracks: options?.tracks, diskname: options?.diskname }); return this.actionResult(res.data); }
     async filesCreateD71(p, options) { const res = await this.api.v1.filesCreateD71Update(encodeDevicePath(p), ":create_d71", { diskname: options?.diskname }); return this.actionResult(res.data); }
@@ -297,6 +341,12 @@ class C64uBackend {
     async modplayFile(pathStr) { const res = await this.api.v1.runnersModplayUpdate(":modplay", { file: pathStr }); return this.actionResult(res.data); }
 }
 export class ViceBackend {
+    static stopAllSupervisorsSync() {
+        for (const [, handle] of ViceBackend.supervisors) {
+            handle.stopSync();
+        }
+        ViceBackend.supervisors.clear();
+    }
     constructor(config) {
         this.type = "vice";
         this.debugEnabled = process.env.VICE_DEVICE_TEST_DEBUG === "1";
@@ -465,15 +515,16 @@ export class ViceBackend {
             return;
         }
         ViceBackend.cleanupRegistered = true;
-        const cleanupSync = () => {
-            for (const [, handle] of ViceBackend.supervisors) {
-                handle.stopSync();
-            }
-            ViceBackend.supervisors.clear();
-        };
+        const cleanupSync = stopManagedViceProcessesSync;
         process.once("exit", cleanupSync);
         for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
             process.once(signal, () => {
+                // When the MCP server installed its shutdown handler, it performs the
+                // async cleanup, calls stopManagedViceProcessesSync and exits itself;
+                // exactly one handler per signal may call process.exit.
+                if (signalDelegate) {
+                    return;
+                }
                 cleanupSync();
                 process.exit(signal === "SIGINT" ? 130 : 143);
             });
@@ -586,9 +637,12 @@ export class ViceBackend {
         await this.loadPrgAndFinish(buffer, async () => { });
         return { success: true };
     }
-    async loadPrgFile(_path) { throw unsupported("loadPrgFile"); }
+    async loadPrgFile(prgPath) {
+        const data = fs.readFileSync(resolveHostPath(prgPath, { purpose: "read" }));
+        return this.loadPrg(data);
+    }
     async runPrgFile(prgPath) {
-        const data = fs.readFileSync(prgPath);
+        const data = fs.readFileSync(resolveHostPath(prgPath, { purpose: "read" }));
         await this.injectPrg(data);
         return { success: true };
     }
@@ -785,6 +839,7 @@ export class ViceBackend {
         if (!VICE_DISK_IMAGE_EXTENSIONS.has(path.extname(imagePath).toLowerCase())) {
             throw new Error(`VICE can mount only disk images (${[...VICE_DISK_IMAGE_EXTENSIONS].join(", ")}): ${imagePath}`);
         }
+        imagePath = resolveHostPath(imagePath, { purpose: "read", maxBytes: DISK_IMAGE_MAX_READ_BYTES });
         if (!fs.existsSync(imagePath)) {
             throw new Error(`Disk image not found on the VICE host: ${imagePath}`);
         }
@@ -871,10 +926,7 @@ export class ViceBackend {
                     name: "VICE",
                     // Only resources that exist in VICE 3.10; checked against a running x64sc.
                     // VICE has no warp, drive-enable or attached-image resources.
-                    items: [
-                        "SoundVolume", "Drive8Type", "Drive9Type", "Drive10Type", "Drive11Type",
-                        "VICIIBorderMode", "VICIIFullscreen", "MachineVideoStandard", "SidModel",
-                    ],
+                    items: [...VICE_CONFIG_INVENTORY],
                 },
             ],
         };
@@ -892,12 +944,14 @@ export class ViceBackend {
                 return values;
             });
         }
+        assertAllowedViceResource(item);
         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) {
+        assertAllowedViceResource(item);
         let parsed = value;
         await this.withClient(async (client) => {
             const current = await client.resourceGet(item);
@@ -912,6 +966,7 @@ export class ViceBackend {
             for (const [category, items] of Object.entries(payload)) {
                 for (const [item, value] of Object.entries(items)) {
                     try {
+                        assertAllowedViceResource(item);
                         const current = await client.resourceGet(item);
                         const parsed = parseViceConfigValue(value, current.type, item);
                         await client.resourceSet(item, parsed);
@@ -950,6 +1005,10 @@ function parseViceConfigValue(value, type, item) {
     return parsed;
 }
 function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend`); err.code = "UNSUPPORTED"; return err; }
+/** Whole-device route suffix, or `/{category}:action` for one category (the generated client prefixes `/v1/configs`). */
+function configActionRoute(action, category) {
+    return category === undefined ? action : `/${encodeURIComponent(category)}${action}`;
+}
 /** Ultimate file APIs treat slash as a path separator. Encode each name once,
  * preserving leading and nested separators for firmware routing. */
 function encodeDevicePath(value) {
@@ -1189,15 +1248,11 @@ export async function createFacade(logger, options) {
     }
     // No configuration
     const probeBase = cfg.endpoints.c64u.baseUrl;
-    try {
-        const res = await axios.get(probeBase, { timeout: 1500 });
-        if (res.status >= 200 && res.status < 500) {
-            const backend = new C64uBackend(cfg.endpoints.c64u);
-            logger?.info?.("Active backend: c64u (fallback – hardware reachable)");
-            return { facade: backend, selected: "c64u", reason: "fallback (reachable)", details: { baseUrl: probeBase } };
-        }
+    if (await probeUltimateReachable(probeBase, 1500, cfg.endpoints.c64u.networkPassword)) {
+        const backend = new C64uBackend(cfg.endpoints.c64u);
+        logger?.info?.("Active backend: c64u (fallback – hardware reachable)");
+        return { facade: backend, selected: "c64u", reason: "fallback (reachable)", details: { baseUrl: probeBase } };
     }
-    catch { }
     const backend = new ViceBackend(cfg.vice ?? {});
     logger?.info?.("Active backend: vice (fallback – hardware unavailable)");
     const endpoint = backend.getEndpoint();

package/dist/diagnostics.js

@@ -36,7 +36,7 @@ export function writeDiagnosticEvent(event, details) {
         details: sanitize(details),
     };
     try {
-        fs.appendFileSync(current.info.filePath, `${JSON.stringify(record)}\n`, "utf8");
+        fs.appendFileSync(current.info.filePath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
     }
     catch (error) {
         safeStderrWrite(`[diagnostics] failed to append event ${event}: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -250,13 +250,73 @@ function ensureState(component) {
 }
 function createSessionInfo(component) {
     const directory = resolveDiagnosticsDirectory();
-    fs.mkdirSync(directory, { recursive: true });
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
     const startedAt = new Date().toISOString().replace(/[:.]/g, "-");
     const safeComponent = component.replace(/[^a-z0-9_-]+/gi, "-").replace(/^-+|-+$/g, "") || "runtime";
     const sessionId = `${startedAt}-${process.pid}`;
     const filePath = path.join(directory, `${sessionId}-${safeComponent}.ndjson`);
+    pruneDiagnosticsDirectory(directory, { keep: resolveDiagnosticsKeep(), currentFile: filePath });
     return { component: safeComponent, directory, filePath, sessionId };
 }
+const DEFAULT_DIAGNOSTICS_KEEP = 200;
+const DIAGNOSTICS_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const DIAGNOSTICS_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-\d+-[a-z0-9_-]+\.ndjson$/i;
+/** Reset the cached session so a test can start a new one. Not used by the server. */
+export function resetDiagnosticsStateForTesting() {
+    state = null;
+}
+function resolveDiagnosticsKeep() {
+    const raw = process.env.C64BRIDGE_DIAGNOSTICS_KEEP?.trim();
+    if (raw === undefined || raw === "") {
+        return DEFAULT_DIAGNOSTICS_KEEP;
+    }
+    if (!/^\d+$/.test(raw)) {
+        safeStderrWrite(`[diagnostics] ignoring invalid C64BRIDGE_DIAGNOSTICS_KEEP="${raw}"; using ${DEFAULT_DIAGNOSTICS_KEEP}\n`);
+        return DEFAULT_DIAGNOSTICS_KEEP;
+    }
+    return Number(raw);
+}
+/**
+ * Best-effort retention: delete regular diagnostics files (by naming pattern) beyond the newest `keep`
+ * or older than 30 days. Uses lstat so symlinks are never followed; never recurses.
+ */
+export function pruneDiagnosticsDirectory(directory, options) {
+    try {
+        const now = options.now ?? Date.now();
+        const candidates = [];
+        for (const name of fs.readdirSync(directory)) {
+            if (!DIAGNOSTICS_FILE_PATTERN.test(name))
+                continue;
+            const file = path.join(directory, name);
+            if (options.currentFile && path.resolve(file) === path.resolve(options.currentFile))
+                continue;
+            try {
+                const stat = fs.lstatSync(file);
+                if (stat.isFile())
+                    candidates.push({ file, mtimeMs: stat.mtimeMs });
+            }
+            catch {
+                // ignore entries that vanish or cannot be inspected
+            }
+        }
+        candidates.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.file < b.file ? 1 : -1));
+        // The current session's file counts toward the kept total.
+        const keepOthers = Math.max(0, options.keep - (options.currentFile ? 1 : 0));
+        candidates.forEach((entry, index) => {
+            if (index >= keepOthers || now - entry.mtimeMs > DIAGNOSTICS_MAX_AGE_MS) {
+                try {
+                    fs.unlinkSync(entry.file);
+                }
+                catch {
+                    // best effort
+                }
+            }
+        });
+    }
+    catch {
+        // best effort: an unreadable directory must not stop diagnostics
+    }
+}
 function resolveDiagnosticsDirectory() {
     const configured = process.env.C64BRIDGE_DIAGNOSTICS_DIR?.trim();
     if (configured) {

package/dist/hostPaths.js

@@ -0,0 +1,128 @@
+// Confinement of host file paths that originate from tool arguments.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ToolValidationError } from "./tools/errors.js";
+export const DEFAULT_MAX_READ_BYTES = 16 * 1024 * 1024;
+export const DISK_IMAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
+export const ALLOWED_DIRS_ENV = "C64BRIDGE_ALLOWED_DIRS";
+/** True when candidate equals root or lies inside it. Both must be absolute. */
+export function isWithin(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+/** Real path of the deepest existing ancestor, with the nonexistent remainder appended. */
+function realpathOfDeepest(target) {
+    const pending = [];
+    let current = target;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(current), ...pending.reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            let isLink = false;
+            try {
+                isLink = fs.lstatSync(current).isSymbolicLink();
+            }
+            catch { /* does not exist */ }
+            // A dangling symlink would be followed by a later write, so its target cannot be vetted.
+            if (isLink)
+                throw new ToolValidationError(`Host path is a dangling symbolic link: ${current}`, { path: current });
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.join(current, ...pending.reverse());
+            pending.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+function safeRealpath(p) {
+    try {
+        return realpathOfDeepest(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function homeDirectory() {
+    return process.env.HOME || os.homedir();
+}
+/** Allowed roots (real paths). Reads cwd, environment and home directory at call time. */
+export function allowedHostRoots() {
+    const roots = [];
+    const cwd = safeRealpath(process.cwd());
+    const home = safeRealpath(homeDirectory());
+    if (cwd !== home && cwd !== path.parse(cwd).root)
+        roots.push(cwd);
+    roots.push(safeRealpath(path.join(homeDirectory(), ".c64bridge")));
+    roots.push(safeRealpath(os.tmpdir()));
+    const extra = process.env[ALLOWED_DIRS_ENV];
+    if (extra) {
+        for (const entry of extra.split(path.delimiter)) {
+            const trimmed = entry.trim();
+            if (trimmed && trimmed !== "*")
+                roots.push(safeRealpath(trimmed));
+        }
+    }
+    return [...new Set(roots)];
+}
+/**
+ * Resolve a file name that the server appends to an already resolved directory.
+ * The final path is checked again: a symbolic link planted at that name in a
+ * shared directory (for example the temp directory) must not redirect the write
+ * outside the allowed roots.
+ */
+export function resolveHostChildPath(dir, ...names) {
+    return resolveHostPath(path.join(dir, ...names), { purpose: "write" });
+}
+/** Default output directory under the working directory, or under ~/.c64bridge when the working directory is not an allowed root. */
+export function defaultHostOutputDir(...names) {
+    try {
+        return resolveHostPath(path.join(process.cwd(), ...names), { purpose: "write" });
+    }
+    catch (error) {
+        if (!(error instanceof ToolValidationError))
+            throw error;
+        return resolveHostPath(path.join(homeDirectory(), ".c64bridge", ...names), { purpose: "write" });
+    }
+}
+function confinementDisabled() {
+    const extra = process.env[ALLOWED_DIRS_ENV];
+    return !!extra && extra.trim() === "*";
+}
+/**
+ * Resolve a tool-supplied path to an absolute real path inside the allowed roots.
+ * Throws ToolValidationError for paths outside the roots, dangling symlinks and oversized reads.
+ */
+export function resolveHostPath(input, options) {
+    if (typeof input !== "string" || input.length === 0 || input.includes("\0")) {
+        throw new ToolValidationError("Host path must be a non-empty string without NUL bytes.");
+    }
+    const resolved = path.resolve(input);
+    const disabled = !options.roots && confinementDisabled();
+    const real = disabled ? resolved : realpathOfDeepest(resolved);
+    if (!disabled) {
+        const roots = options.roots ? options.roots.map(safeRealpath) : allowedHostRoots();
+        if (!roots.some((root) => isWithin(root, real))) {
+            throw new ToolValidationError(`Host path is outside the allowed directories: ${resolved}. Allowed roots: ${roots.join(", ")}. `
+                + `Add directories with the ${ALLOWED_DIRS_ENV} environment variable (entries separated by "${path.delimiter}"; "*" disables confinement).`, { path: resolved, details: { allowedRoots: roots, env: ALLOWED_DIRS_ENV } });
+        }
+    }
+    if (options.purpose === "read") {
+        const limit = options.maxBytes ?? DEFAULT_MAX_READ_BYTES;
+        let size;
+        try {
+            size = fs.statSync(real).size;
+        }
+        catch {
+            size = undefined;
+        }
+        if (size !== undefined && size > limit) {
+            throw new ToolValidationError(`Host file is too large to read: ${resolved} is ${size} bytes, limit is ${limit} bytes.`, { path: resolved });
+        }
+    }
+    return real;
+}

package/dist/loggingHttpClient.js

@@ -13,7 +13,53 @@ function redactHeaders(headers) {
         sensitive.test(key) ? "***" : value,
     ]));
 }
-export function createLoggingHttpClient(config, logger = loggerFor("c64u")) {
+/**
+ * First-in first-out gate that lets one operation run at a time. The Ultimate
+ * firmware serves REST requests on a single thread, so every request to one
+ * device goes through one queue. A failed operation releases the gate like a
+ * successful one, so the queue cannot deadlock.
+ */
+export class RequestQueue {
+    constructor() {
+        this.tail = Promise.resolve();
+    }
+    /** The shared queue for one device base URL, so every client of that device (backends, fallback clients) waits in the same line. */
+    static forDevice(baseUrl) {
+        const key = baseUrl.replace(/\/+$/, "").toLowerCase();
+        let queue = RequestQueue.byDevice.get(key);
+        if (!queue) {
+            queue = new RequestQueue();
+            RequestQueue.byDevice.set(key, queue);
+        }
+        return queue;
+    }
+    /** Resolves when all earlier holders have released; call the returned function exactly once. */
+    async acquire() {
+        let release;
+        const held = new Promise((resolve) => { release = resolve; });
+        const previous = this.tail;
+        this.tail = previous.then(() => held);
+        await previous;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                release();
+            }
+        };
+    }
+    async run(operation) {
+        const release = await this.acquire();
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+}
+RequestQueue.byDevice = new Map();
+export function createLoggingHttpClient(config, logger = loggerFor("c64u"), queue) {
     const http = new HttpClient(config);
     registerSecret(readPasswordHeader(config?.headers));
     http.instance.interceptors.request.use((request) => {
@@ -30,6 +76,18 @@ export function createLoggingHttpClient(config, logger = loggerFor("c64u")) {
         request.__c64Meta = meta;
         return request;
     });
+    if (queue) {
+        // The generated client sends every request through `instance.request`, so
+        // the gate is taken around that call. Interceptors, request transforms and
+        // the adapter all run inside it: the start time is recorded after the wait,
+        // the request timeout (started by the adapter) does not include the wait,
+        // and the gate is released however the request settles, including a
+        // failure before the adapter is called (for example a body that cannot be
+        // serialised).
+        const instance = http.instance;
+        const sendRequest = instance.request.bind(instance);
+        instance.request = ((requestConfig) => queue.run(() => sendRequest(requestConfig)));
+    }
     http.instance.interceptors.response.use((response) => {
         handleResponse(response, logger);
         return response;