c64bridge 1.0.7 → 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,7 +3,8 @@ 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 { dirname } from "node:path";
+import { resolveHostPath } from "../../hostPaths.js";
 import { captureConfigSnapshot, stripRedactedSecrets, validateSnapshotCategories } from "./configInventory.js";
 import { normalizeErrorDetails } from "./util.js";
 const configSnapshotAndRestoreArgsSchema = objectSchema({
@@ -17,6 +18,16 @@ const configSnapshotAndRestoreArgsSchema = objectSchema({
     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",
@@ -32,7 +43,7 @@ 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([
@@ -55,8 +66,7 @@ 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" });
                     }
@@ -79,8 +89,7 @@ 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, { includeSecretValues: parsed.includeSecretValues === true })).categories;
                 const diff = {};

package/dist/tools/meta/filesystem.js

@@ -14,7 +14,7 @@ const findPathsByNameArgsSchema = objectSchema({
         root: optionalSchema(stringSchema({ description: "Root path to search (host)" }), "/"),
         nameContains: stringSchema({ description: "Substring to match", minLength: 1 }),
         extensions: optionalSchema(arraySchema(stringSchema({ description: "Extension filter without dot", minLength: 1 }))),
-        maxResults: optionalSchema(numberSchema({ description: "Maximum results", integer: true, minimum: 1, default: 50 }), 50),
+        maxResults: optionalSchema(numberSchema({ description: "Maximum results", integer: true, minimum: 1, maximum: 1000, default: 100 }), 100),
         caseInsensitive: optionalSchema(booleanSchema({ description: "Case-insensitive name match", default: true }), true),
     },
     required: ["nameContains"],
@@ -321,12 +321,10 @@ function extensionKey(path) {
     const raw = extractExtension(path);
     return { raw, normalised: raw.length > 0 ? raw : "(none)" };
 }
-function buildSearchPattern(root, extension) {
-    const trimmed = root === "/" ? "/" : root.replace(/\/+$/, "");
-    if (trimmed === "/") {
-        return extension ? `/**/*.${extension}` : `/**/*`;
-    }
-    return extension ? `${trimmed}/**/*.${extension}` : `${trimmed}/**/*`;
+function buildSearchPattern(root, extension, nameContains) {
+    const trimmed = root.replace(/\/+$/, "");
+    const name = nameContains ? `*${nameContains}*` : "*";
+    return extension ? `${trimmed}/**/${name}.${extension}` : `${trimmed}/**/${name}`;
 }
 export const tools = [
     {
@@ -342,8 +340,9 @@ export const tools = [
                 const needle = parsed.caseInsensitive ? parsed.nameContains.toLowerCase() : parsed.nameContains;
                 const exts = (parsed.extensions ?? []);
                 const patterns = exts.length > 0
-                    ? exts.map((e) => `${root}/**/*${parsed.nameContains}*.${e}`)
-                    : [`${root}/**/*${parsed.nameContains}*`];
+                    ? exts.map((e) => buildSearchPattern(root, e, parsed.nameContains))
+                    : [buildSearchPattern(root, undefined, parsed.nameContains)];
+                const limit = parsed.maxResults ?? 100;
                 const seen = new Set();
                 const results = [];
                 for (const pattern of patterns) {
@@ -356,7 +355,7 @@ export const tools = [
                             if (name.includes(needle) && !seen.has(p)) {
                                 seen.add(p);
                                 results.push(p);
-                                if (results.length >= (parsed.maxResults ?? 50))
+                                if (results.length >= (limit + 1))
                                     break;
                             }
                         }
@@ -369,15 +368,18 @@ export const tools = [
                             if (name.includes(needle) && !seen.has(p)) {
                                 seen.add(p);
                                 results.push(p);
-                                if (results.length >= (parsed.maxResults ?? 50))
+                                if (results.length >= (limit + 1))
                                     break;
                             }
                         }
                     }
-                    if (results.length >= (parsed.maxResults ?? 50))
+                    if (results.length >= (limit + 1))
                         break;
                 }
-                return jsonResult({ root, pattern: parsed.nameContains, results }, { success: true, count: results.length });
+                const truncated = results.length > limit;
+                if (truncated)
+                    results.length = limit;
+                return jsonResult({ root, pattern: parsed.nameContains, results, truncated }, { success: true, count: results.length, truncated });
             }
             catch (error) {
                 if (error instanceof ToolError)
@@ -530,7 +532,7 @@ export const tools = [
                 const seen = new Set();
                 const candidates = [];
                 for (const ext of extensions) {
-                    const pattern = `${root}/**/*${needle}*.${ext}`;
+                    const pattern = buildSearchPattern(root, ext, needle);
                     try {
                         const info = await ctx.client.filesInfo(pattern);
                         const paths = extractPaths(info);