c64bridge 1.0.6 → 1.1.0

package/dist/tools/meta/background.js

@@ -1,12 +1,37 @@
+// Background task management meta tools
+import { assertAccess, taskOperationEffect } from "../access.js";
 import { objectSchema, stringSchema, numberSchema, optionalSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
 import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { promises as fs } from "node:fs";
-import { dirname, resolve as resolvePath, join as joinPath } from "node:path";
+import { dirname, resolve as resolvePath, join as joinPath, sep } from "node:path";
 import os from "node:os";
 import { addMilliseconds } from "date-fns";
+import { screenCodesToAscii } from "../../petscii.js";
+import { loggerFor } from "../../logger.js";
 import { formatTimestampSpec, parseTimestampSpec } from "./util.js";
 const TASKS = new Map();
+const logger = loggerFor("background");
+export const MIN_INTERVAL_MS = 100;
+export const MAX_RUNNING_TASKS = 16;
+export const MAX_ITERATIONS_LIMIT = 100000;
+const MAX_LOG_BYTES = 256 * 1024;
+// Operations runOperation implements, including the *_memory aliases.
+const SUPPORTED_OPERATIONS = ["read", "write", "read_screen", "menu_button", "read_memory", "write_memory"];
+const MAX_STORED_RESULT_CHARS = 4096;
+function summariseResult(result) {
+    let text;
+    try {
+        text = JSON.stringify(result) ?? "null";
+    }
+    catch {
+        return String(result).slice(0, MAX_STORED_RESULT_CHARS);
+    }
+    if (text.length <= MAX_STORED_RESULT_CHARS) {
+        return JSON.parse(text);
+    }
+    return { truncated: true, preview: text.slice(0, MAX_STORED_RESULT_CHARS) };
+}
 function normaliseOperation(op) {
     switch (op) {
         case "read_memory":
@@ -32,8 +57,10 @@ function toPersistedTask(t) {
         updatedAt: formatTimestampSpec(t.updatedAt),
         stoppedAt: t.stoppedAt ? formatTimestampSpec(t.stoppedAt) : null,
         lastError: t.lastError ?? null,
+        lastResult: t.lastResult ?? null,
         nextRunAt: t.nextRunAt ? formatTimestampSpec(t.nextRunAt) : null,
         folder: t.folder,
+        backendId: t.backendId ?? null,
     };
 }
 function fromPersistedTask(p) {
@@ -51,8 +78,10 @@ function fromPersistedTask(p) {
         updatedAt: parseTimestampSpec(p.updatedAt) ?? new Date(),
         stoppedAt: parseTimestampSpec(p.stoppedAt ?? null),
         lastError: p.lastError ?? null,
+        lastResult: p.lastResult ?? null,
         nextRunAt: parseTimestampSpec(p.nextRunAt ?? null),
         folder: p.folder,
+        backendId: p.backendId ?? null,
         _timer: null,
     };
 }
@@ -73,36 +102,84 @@ function getBackgroundTaskFolderRelative(id) {
     return `tasks/background/${id}`;
 }
 function getBackgroundTaskFolderAbsolute(id) {
-    return resolvePath(joinPath(getTasksHomeDir(), getBackgroundTaskFolderRelative(id)));
+    const base = resolvePath(joinPath(getTasksHomeDir(), "tasks", "background"));
+    const folder = resolvePath(joinPath(getTasksHomeDir(), getBackgroundTaskFolderRelative(id)));
+    // The task name is schema-restricted to one path segment; this also guards ids read from a state file.
+    if (!folder.startsWith(base + sep)) {
+        throw new ToolValidationError("Task folder must stay inside the background task directory", { path: "$.name" });
+    }
+    return folder;
 }
-let TASKS_LOADED = false;
-async function ensureTasksLoaded() {
-    if (TASKS_LOADED)
-        return;
-    TASKS_LOADED = true;
+let tasksLoadedPromise = null;
+// Every caller awaits the same load, so a concurrent first call never sees an empty registry.
+function ensureTasksLoaded() {
+    if (!tasksLoadedPromise) {
+        tasksLoadedPromise = loadTasks();
+    }
+    return tasksLoadedPromise;
+}
+async function moveCorruptStateAside(path, reason) {
+    const target = `${path}.corrupt-${new Date().toISOString().replace(/[:.]/g, "-")}`;
     try {
-        const text = await fs.readFile(getTaskStateFilePath(), "utf8");
-        const parsed = JSON.parse(text);
-        if (parsed && Array.isArray(parsed.tasks)) {
-            for (const pt of parsed.tasks) {
-                const t = fromPersistedTask(pt);
-                if (t.status === "running") {
-                    t.status = "stopped";
-                    t.stoppedAt = new Date();
-                    t.updatedAt = new Date();
-                    t.lastError = "Interrupted by MCP server restart; start the task again to resume monitoring.";
-                    t.nextRunAt = null;
-                }
-                TASKS.set(t.name, t);
-            }
-        }
+        await fs.rename(path, target);
+        logger.error(`Background task state file is unreadable (${reason}); moved it to ${target} and starting with an empty registry`);
+    }
+    catch (error) {
+        logger.error(`Background task state file is unreadable (${reason}) and could not be moved aside: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function loadTasks() {
+    const path = getTaskStateFilePath();
+    let text;
+    try {
+        text = await fs.readFile(path, "utf8");
     }
     catch (error) {
         if (error?.code === "ENOENT") {
-            const path = getTaskStateFilePath();
             await fs.mkdir(dirname(path), { recursive: true });
-            await fs.writeFile(path, JSON.stringify({ tasks: [] }, null, 2), "utf8");
+            await writeFileAtomic(path, JSON.stringify({ tasks: [] }, null, 2));
+        }
+        else {
+            logger.error(`Unable to read background task state file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        await moveCorruptStateAside(path, error instanceof Error ? error.message : String(error));
+        return;
+    }
+    if (!parsed || !Array.isArray(parsed.tasks)) {
+        await moveCorruptStateAside(path, "missing tasks array");
+        return;
+    }
+    for (const pt of parsed.tasks) {
+        const t = fromPersistedTask(pt);
+        if (t.status === "running") {
+            t.status = "stopped";
+            t.stoppedAt = new Date();
+            t.updatedAt = new Date();
+            t.lastError = "Interrupted by MCP server restart; start the task again to resume monitoring.";
+            t.nextRunAt = null;
         }
+        TASKS.set(t.name, t);
+    }
+}
+let tempFileCounter = 0;
+// Write to a temporary file in the same directory, then rename, so readers never see a partial file.
+async function writeFileAtomic(path, data) {
+    tempFileCounter += 1;
+    const temp = `${path}.${process.pid}.${tempFileCounter}.tmp`;
+    try {
+        await fs.writeFile(temp, data, "utf8");
+        await fs.rename(temp, path);
+    }
+    catch (error) {
+        await fs.rm(temp, { force: true }).catch(() => { });
+        throw error;
     }
 }
 async function writeTaskJson(task) {
@@ -111,7 +188,7 @@ async function writeTaskJson(task) {
     const pt = toPersistedTask(task);
     const data = { ...pt, resultPath: resultRelative };
     await fs.mkdir(folderAbs, { recursive: true });
-    await fs.writeFile(resolvePath(folderAbs, "task.json"), JSON.stringify(data, null, 2), "utf8");
+    await writeFileAtomic(resolvePath(folderAbs, "task.json"), JSON.stringify(data, null, 2));
 }
 async function ensureResultAndLog(task) {
     const folderAbs = getBackgroundTaskFolderAbsolute(task.id);
@@ -130,7 +207,7 @@ async function ensureResultAndLog(task) {
             status: task.status,
             iterations: task.iterations,
         };
-        await fs.writeFile(resultPath, JSON.stringify(initial, null, 2), "utf8");
+        await writeFileAtomic(resultPath, JSON.stringify(initial, null, 2));
     }
     try {
         await fs.access(logPath);
@@ -143,40 +220,74 @@ async function appendTaskLog(task, message) {
     const logPath = resolvePath(getBackgroundTaskFolderAbsolute(task.id), "log.txt");
     const ts = formatTimestampSpec(task.updatedAt ?? task.startedAt ?? new Date());
     await fs.appendFile(logPath, `[${ts}] ${message}\n`, "utf8");
+    await capTaskLog(logPath);
 }
-async function persistTasks() {
+// Keep only the last MAX_LOG_BYTES of log.txt once it grows beyond that.
+async function capTaskLog(logPath) {
+    const stats = await fs.stat(logPath);
+    if (stats.size <= MAX_LOG_BYTES)
+        return;
+    const handle = await fs.open(logPath, "r");
     try {
-        const path = getTaskStateFilePath();
-        await fs.mkdir(dirname(path), { recursive: true });
-        const data = Array.from(TASKS.values()).map((t) => toPersistedTask(t));
-        await fs.writeFile(path, JSON.stringify({ tasks: data }, null, 2), "utf8");
-        // Keep per-task files up to date
-        for (const t of TASKS.values()) {
-            await writeTaskJson(t);
-            await ensureResultAndLog(t);
+        const buffer = Buffer.alloc(MAX_LOG_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, MAX_LOG_BYTES, stats.size - MAX_LOG_BYTES);
+        let kept = buffer.subarray(0, bytesRead);
+        const firstNewline = kept.indexOf(0x0a);
+        if (firstNewline >= 0 && firstNewline < kept.length - 1) {
+            kept = kept.subarray(firstNewline + 1); // drop the partial first line
         }
+        await writeFileAtomic(logPath, kept.toString("utf8"));
     }
-    catch {
-        // ignore
+    finally {
+        await handle.close();
     }
 }
-function runOperation(op, args, ctx) {
-    switch (normaliseOperation(op)) {
+// Persistence is serialised so two writers never rename over each other.
+let persistChain = Promise.resolve();
+function persistTasks(changedTasks = []) {
+    const run = persistChain.then(async () => {
+        try {
+            const path = getTaskStateFilePath();
+            await fs.mkdir(dirname(path), { recursive: true });
+            const data = Array.from(TASKS.values()).map((t) => toPersistedTask(t));
+            await writeFileAtomic(path, JSON.stringify({ tasks: data }, null, 2));
+            // Only the changed tasks get their per-task files rewritten.
+            for (const t of changedTasks) {
+                await writeTaskJson(t);
+                await ensureResultAndLog(t);
+            }
+        }
+        catch (error) {
+            logger.warn(`Unable to persist background task state: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    persistChain = run;
+    return run;
+}
+function runOperation(task, ctx) {
+    const args = task.args;
+    const facade = task._facade;
+    switch (normaliseOperation(task.operation)) {
         case "read": {
             const address = String(args.address ?? "$0400");
             const length = String(args.length ?? "16");
-            return ctx.client.readMemory(address, length);
+            return ctx.client.readMemory(address, length, facade);
         }
         case "write": {
             const address = String(args.address ?? "$0400");
             const bytes = String(args.bytes ?? "$00");
-            return ctx.client.writeMemory(address, bytes);
+            return ctx.client.writeMemory(address, bytes, facade);
         }
         case "read_screen": {
+            if (facade) {
+                return ctx.client
+                    .readMemoryRaw(0x0400, 0x03e8, facade)
+                    .then((bytes) => screenCodesToAscii(bytes, { columns: 40, rows: 25 }));
+            }
             return ctx.client.readScreen();
         }
         case "menu_button": {
-            return ctx.client.menuButton();
+            return facade ? facade.menuButton() : ctx.client.menuButton();
         }
         default:
             return Promise.resolve({ success: true });
@@ -191,33 +302,41 @@ function scheduleNextRun(task, ctx) {
         if (task.status !== "running")
             return;
         try {
-            const result = await runOperation(task.operation, task.args, ctx);
+            const result = await runOperation(task, ctx);
+            // A stop that arrived while the operation was in flight wins: never turn it into completed/error.
+            if (task.status !== "running")
+                return;
             if (result && typeof result === "object" && "success" in result && result.success === false) {
                 throw new Error(`Operation returned failure: ${JSON.stringify(result.details ?? result)}`);
             }
             task.iterations += 1;
+            task.lastResult = summariseResult(result);
             task.updatedAt = new Date();
             if (task.maxIterations && task.iterations >= task.maxIterations) {
                 task.status = "completed";
                 task.stoppedAt = new Date();
                 task._timer = null;
                 await appendTaskLog(task, `completed iterations=${task.iterations}`);
-                await persistTasks();
+                await persistTasks([task]);
                 return;
             }
             await appendTaskLog(task, `iteration=${task.iterations}`);
-            await persistTasks();
+            await persistTasks([task]);
             scheduleNextRun(task, ctx);
         }
         catch (err) {
+            if (task.status !== "running")
+                return;
             task.status = "error";
             task.lastError = err instanceof Error ? err.message : String(err);
             task.stoppedAt = new Date();
             task._timer = null;
             await appendTaskLog(task, `error: ${task.lastError}`);
-            await persistTasks();
+            await persistTasks([task]);
         }
     }, delay);
+    // A pending task timer must never keep the process alive on its own.
+    task._timer.unref?.();
 }
 function stopTask(task) {
     if (task._timer) {
@@ -227,6 +346,30 @@ function stopTask(task) {
     task.status = task.status === "completed" ? task.status : "stopped";
     task.stoppedAt = new Date();
 }
+/** Stops every running task (used at process shutdown) and persists the state. */
+export async function stopAllBackgroundTasks() {
+    const stopped = [];
+    for (const task of TASKS.values()) {
+        if (task.status === "running") {
+            stopTask(task);
+            stopped.push(task);
+        }
+    }
+    await persistTasks(stopped);
+}
+function validateTaskOperation(operation, args) {
+    if (!SUPPORTED_OPERATIONS.includes(operation)) {
+        throw new ToolValidationError(`Unsupported background task operation '${operation}'. Allowed operations: ${SUPPORTED_OPERATIONS.join(", ")}.`, { path: "$.operation" });
+    }
+    if (normaliseOperation(operation) === "write") {
+        for (const key of ["address", "bytes"]) {
+            const value = args[key];
+            if (value === undefined || value === null || String(value).trim() === "") {
+                throw new ToolValidationError(`Background task operation 'write' requires arguments.${key}.`, { path: `$.arguments.${key}` });
+            }
+        }
+    }
+}
 const noArgsSchema = objectSchema({ description: "No arguments", properties: {}, additionalProperties: false });
 const startBackgroundTaskArgsSchema = objectSchema({
     description: "Start a named background task that invokes a simple operation at fixed intervals.",
@@ -237,10 +380,10 @@ const startBackgroundTaskArgsSchema = objectSchema({
             minLength: 1,
             pattern: /^[A-Za-z0-9_][A-Za-z0-9_. -]*$/,
         }),
-        operation: stringSchema({ description: "Operation name (e.g., read, read_screen)", minLength: 1 }),
+        operation: stringSchema({ description: "Operation name: read, write, read_screen or menu_button (read_memory and write_memory are aliases). write requires arguments.address and arguments.bytes.", 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),
-        maxIterations: optionalSchema(numberSchema({ description: "Maximum number of iterations (omit for indefinite)", integer: true, minimum: 1 }), undefined),
+        intervalMs: optionalSchema(numberSchema({ description: `Interval milliseconds (minimum ${MIN_INTERVAL_MS})`, integer: true, minimum: MIN_INTERVAL_MS, default: 1000 }), 1000),
+        maxIterations: optionalSchema(numberSchema({ description: `Maximum number of iterations (1 to ${MAX_ITERATIONS_LIMIT}; omit for indefinite)`, integer: true, minimum: 1, maximum: MAX_ITERATIONS_LIMIT }), undefined),
     },
     required: ["name", "operation"],
     additionalProperties: false,
@@ -264,11 +407,18 @@ export const tools = [
             try {
                 await ensureTasksLoaded();
                 const parsed = startBackgroundTaskArgsSchema.parse(args ?? {});
+                validateTaskOperation(parsed.operation, parsed.arguments ?? {});
+                // The effect of the task operation is checked once, at start; a running task is not re-checked.
+                assertAccess("c64_system", "start_task", taskOperationEffect(parsed.operation));
                 const now = new Date();
                 const existing = TASKS.get(parsed.name);
                 if (existing && existing.status === "running") {
                     throw new ToolValidationError("Task with this name is already running", { path: "$.name" });
                 }
+                const runningCount = Array.from(TASKS.values()).filter((t) => t.status === "running").length;
+                if (runningCount >= MAX_RUNNING_TASKS) {
+                    throw new ToolValidationError(`Too many running background tasks (limit ${MAX_RUNNING_TASKS}); stop one first.`, { path: "$.name" });
+                }
                 // Determine next global counter by scanning existing registry entries
                 const allTasks = Array.from(TASKS.values());
                 const currentMax = allTasks.reduce((max, t) => {
@@ -278,6 +428,9 @@ export const tools = [
                 }, 0);
                 const newCounter = String(currentMax + 1).padStart(4, "0");
                 const newId = `${newCounter}_${parsed.name}`;
+                // Pin the facade now: a later c64_select_backend must not retarget a running task.
+                const pinnedFacade = ctx.client.pinFacade ? await ctx.client.pinFacade() : undefined;
+                const backendId = pinnedFacade?.type ?? (ctx.client.getActiveBackendType ? await ctx.client.getActiveBackendType() : null);
                 const task = {
                     id: existing && existing.status !== "running" ? existing.id : newId,
                     name: parsed.name,
@@ -294,7 +447,9 @@ export const tools = [
                     lastError: null,
                     nextRunAt: null,
                     folder: getBackgroundTaskFolderRelative(existing && existing.status !== "running" ? existing.id : newId),
+                    backendId,
                     _timer: null,
+                    _facade: pinnedFacade,
                 };
                 TASKS.set(task.name, task);
                 // Ensure per-task structure and seed files
@@ -303,8 +458,8 @@ export const tools = [
                 await ensureResultAndLog(task);
                 await appendTaskLog(task, "started");
                 scheduleNextRun(task, ctx);
-                await persistTasks();
-                return jsonResult({ started: true, task: { id: task.id, name: task.name, operation: task.operation, intervalMs: task.intervalMs, maxIterations: task.maxIterations ?? null, folder: task.folder } }, { success: true });
+                await persistTasks([task]);
+                return jsonResult({ started: true, task: { id: task.id, name: task.name, operation: task.operation, backendId: task.backendId ?? null, intervalMs: task.intervalMs, maxIterations: task.maxIterations ?? null, folder: task.folder } }, { success: true });
             }
             catch (error) {
                 if (error instanceof ToolError)
@@ -330,7 +485,7 @@ export const tools = [
                 }
                 stopTask(task);
                 await appendTaskLog(task, "stopped");
-                await persistTasks();
+                await persistTasks([task]);
                 return jsonResult({ stopped: true, name: task.name, status: task.status }, { success: true });
             }
             catch (error) {
@@ -354,6 +509,7 @@ export const tools = [
                     id: t.id,
                     name: t.name,
                     type: t.type,
+                    backendId: t.backendId ?? null,
                     status: t.status,
                     iterations: t.iterations,
                     intervalMs: t.intervalMs,
@@ -363,6 +519,7 @@ export const tools = [
                     updatedAt: formatTimestampSpec(t.updatedAt),
                     stoppedAt: t.stoppedAt ? formatTimestampSpec(t.stoppedAt) : null,
                     lastError: t.lastError ?? null,
+                    lastResult: t.lastResult ?? null,
                     folder: t.folder,
                 }));
                 return jsonResult({ tasks }, { success: true, count: tasks.length });
@@ -384,12 +541,17 @@ export const tools = [
             try {
                 await ensureTasksLoaded();
                 stopAllBackgroundTasksArgsSchema.parse(args ?? {});
+                const stoppedTasks = [];
                 for (const task of TASKS.values()) {
+                    // Tasks that already finished or were stopped are left as they are.
+                    if (task.status !== "running")
+                        continue;
                     stopTask(task);
+                    stoppedTasks.push(task);
                     await appendTaskLog(task, "stopped");
                 }
-                await persistTasks();
-                return jsonResult({ stoppedAll: true, count: TASKS.size }, { success: true });
+                await persistTasks(stoppedTasks);
+                return jsonResult({ stoppedAll: true, count: stoppedTasks.length, totalTasks: TASKS.size }, { success: true });
             }
             catch (error) {
                 if (error instanceof ToolError)

package/dist/tools/meta/compilation.js

@@ -3,6 +3,7 @@ import { jsonResult } from "../responses.js";
 import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
+import { resolveHostChildPath, resolveHostPath } from "../../hostPaths.js";
 import { sleep } from "./util.js";
 import { getTasksHomeDir } from "./background.js";
 const compileRunVerifyCycleArgsSchema = objectSchema({
@@ -46,7 +47,7 @@ export const tools = [
                 const verifyAudio = parsed.verifyAudio ?? false;
                 const durationMs = parsed.durationMs ?? 2000;
                 const outputPath = parsed.outputPath
-                    ? resolvePath(String(parsed.outputPath))
+                    ? resolveHostPath(String(parsed.outputPath), { purpose: "write" })
                     : resolvePath(joinPath(getTasksHomeDir(), `cycle_${Date.now()}`));
                 await fs.mkdir(outputPath, { recursive: true });
                 const runId = `cycle_${Date.now()}`;
@@ -80,12 +81,12 @@ export const tools = [
                         verificationMessage = verified ? "Screen verification passed" : `Screen does not contain "${verifyScreen}"`;
                     }
                     // Archive artifacts
-                    const sourcePath = resolvePath(joinPath(outputPath, `source.${sourceType}`));
+                    const sourcePath = resolveHostChildPath(outputPath, `source.${sourceType}`);
                     await fs.writeFile(sourcePath, source, "utf8");
-                    const screenPath = resolvePath(joinPath(outputPath, "screen.txt"));
+                    const screenPath = resolveHostChildPath(outputPath, "screen.txt");
                     const screen = await ctx.client.readScreen();
                     await fs.writeFile(screenPath, screen, "utf8");
-                    const manifestPath = resolvePath(joinPath(outputPath, "manifest.json"));
+                    const manifestPath = resolveHostChildPath(outputPath, "manifest.json");
                     const manifest = {
                         runId,
                         sourceType,
@@ -104,7 +105,7 @@ export const tools = [
                 }
                 catch (e) {
                     const error = e instanceof Error ? e.message : String(e);
-                    const manifestPath = resolvePath(joinPath(outputPath, "manifest.json"));
+                    const manifestPath = resolveHostChildPath(outputPath, "manifest.json");
                     const manifest = {
                         runId,
                         sourceType,

package/dist/tools/meta/config.js

@@ -3,19 +3,31 @@ import { jsonResult } from "../responses.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";
+import { dirname } from "node:path";
+import { resolveHostPath } from "../../hostPaths.js";
+import { captureConfigSnapshot, stripRedactedSecrets, validateSnapshotCategories } from "./configInventory.js";
 import { normalizeErrorDetails } from "./util.js";
 const configSnapshotAndRestoreArgsSchema = objectSchema({
     description: "Snapshot or restore full device configuration. Snapshot writes versioned JSON.",
     properties: {
         action: stringSchema({ description: "One of: snapshot|restore|diff", enum: ["snapshot", "restore", "diff"] }),
         path: stringSchema({ description: "Snapshot file path", minLength: 1 }),
+        includeSecretValues: optionalSchema(booleanSchema({ description: "Snapshot and diff only: store credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text in the snapshot file. Default false: they are written as ***, and restore skips them.", 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,
 });
+// JSON.parse errors can quote the start of the file, so only the path is reported.
+async function readSnapshotFile(path) {
+    const text = await fs.readFile(path, "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ToolValidationError(`Snapshot file is not valid JSON: ${path}`, { path: "$.path" });
+    }
+}
 export const tools = [
     {
         name: "config_snapshot_and_restore",
@@ -31,13 +43,13 @@ export const tools = [
                 if (action === "restore" && parsed.applyToFlash && platform === "vice") {
                     throw new ToolUnsupportedPlatformError("config_save_to_flash", platform, ["c64u", "u2"]);
                 }
-                const path = resolvePath(String(parsed.path));
+                const path = resolveHostPath(String(parsed.path), { purpose: action === "snapshot" ? "write" : "read" });
                 if (action === "snapshot") {
                     await fs.mkdir(dirname(path), { recursive: true });
                     const [version, info, snapshotData] = await Promise.all([
                         ctx.client.version(),
                         ctx.client.info(),
-                        captureConfigSnapshot(ctx.client),
+                        captureConfigSnapshot(ctx.client, { includeSecretValues: parsed.includeSecretValues === true }),
                     ]);
                     const snapshot = {
                         createdAt: new Date().toISOString(),
@@ -54,14 +66,13 @@ export const tools = [
                     }, { success: true });
                 }
                 if (action === "restore") {
-                    const text = await fs.readFile(path, "utf8");
-                    const snapshot = JSON.parse(text);
+                    const snapshot = await readSnapshotFile(path);
                     if (!snapshot || typeof snapshot !== "object") {
                         throw new ToolValidationError("Invalid snapshot file", { path: "$.path" });
                     }
                     let payload;
                     try {
-                        payload = validateSnapshotCategories(snapshot.categories);
+                        payload = stripRedactedSecrets(validateSnapshotCategories(snapshot.categories));
                     }
                     catch {
                         throw new ToolValidationError("Invalid snapshot file", { path: "$.path" });
@@ -78,10 +89,9 @@ export const tools = [
                     }
                     return jsonResult({ restored: true, categories: Object.keys(payload).length }, { success: true });
                 }
-                const text = await fs.readFile(path, "utf8");
-                const snapshot = JSON.parse(text);
+                const snapshot = await readSnapshotFile(path);
                 const snapCats = validateSnapshotCategories(snapshot.categories ?? {});
-                const current = (await captureConfigSnapshot(ctx.client)).categories;
+                const current = (await captureConfigSnapshot(ctx.client, { includeSecretValues: parsed.includeSecretValues === true })).categories;
                 const diff = {};
                 for (const [cat, snapVal] of Object.entries(snapCats)) {
                     const curVal = current[cat];

package/dist/tools/meta/configInventory.js

@@ -1,3 +1,4 @@
+import { isSensitiveConfigItem, redactConfigValue, REDACTED_PLACEHOLDER } from "../../redact.js";
 export function normalizeConfigInventory(details) {
     const categories = details?.categories;
     if (!Array.isArray(categories)) {
@@ -55,12 +56,15 @@ export function normalizeConfigInventory(details) {
     }
     return inventory;
 }
-export async function captureConfigSnapshot(client) {
+export async function captureConfigSnapshot(client, options = {}) {
     const inventory = normalizeConfigInventory(await client.configsList());
     const categories = {};
     for (const entry of inventory) {
         try {
-            const value = normalizeSnapshotValue(await client.configGet(entry.category, entry.item), entry);
+            const normalized = normalizeSnapshotValue(await client.configGet(entry.category, entry.item), entry);
+            const value = options.includeSecretValues
+                ? normalized
+                : redactConfigValue(normalized, entry.category, entry.item);
             setSnapshotValue(categories, entry, value);
         }
         catch (error) {
@@ -71,6 +75,25 @@ export async function captureConfigSnapshot(client) {
     }
     return { inventory, categories };
 }
+/**
+ * Drops redacted credential placeholders from a snapshot payload before it is
+ * written back, so restoring a default snapshot never sets a password to `***`.
+ */
+export function stripRedactedSecrets(categories) {
+    const strip = (category, value) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return value;
+        const kept = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === REDACTED_PLACEHOLDER && isSensitiveConfigItem(category, key))
+                continue;
+            // Per-item snapshot entries keep the firmware wrapper: { category: { item: value } }.
+            kept[key] = strip(entry !== null && typeof entry === "object" && !Array.isArray(entry) ? key : category, entry);
+        }
+        return kept;
+    };
+    return Object.fromEntries(Object.entries(categories).map(([category, items]) => [category, strip(category, items)]));
+}
 export function validateSnapshotCategories(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("Snapshot categories payload must be an object");

package/dist/tools/meta/diagnostics.js

@@ -74,7 +74,8 @@ export const tools = [
                     version,
                     info,
                 };
-                return jsonResult(report, { success: report.isHealthy });
+                const result = jsonResult(report, { success: report.isHealthy });
+                return report.isHealthy ? result : { ...result, isError: true };
             }
             catch (error) {
                 if (error instanceof ToolError)