c64bridge 1.0.7 → 1.1.0

package/dist/tools/meta/graphics.js

@@ -3,7 +3,9 @@ import { jsonResult } from "../responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { normalizeErrorDetails } from "./util.js";
 import { promises as fs } from "node:fs";
-import { dirname, resolve as resolvePath } from "node:path";
+import { dirname } from "node:path";
+import { resolveHostChildPath, resolveHostPath } from "../../hostPaths.js";
+import { acquireOwnedPause, resumeWarning } from "../pauseGuard.js";
 function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id ?? ctx.client?.type;
     return platformId !== "vice";
@@ -214,14 +216,14 @@ export const tools = [
                     throw new ToolValidationError("Stride must be at least 63 bytes to avoid overlapping sprites", { path: "$.stride" });
                 }
                 const canPause = pauseDuringRead && supportsMachinePause(ctx);
-                const pauseResume = canPause
-                    ? await ctx.client.pause()
-                    : { success: true };
-                if (canPause && !pauseResume.success) {
-                    throw new ToolExecutionError("Pause failed before sprite scan", { details: normalizeErrorDetails(pauseResume.details) });
+                const owned = await acquireOwnedPause(ctx.client, canPause);
+                const pinned = owned.facade;
+                if (canPause && !owned.result.success) {
+                    throw new ToolExecutionError("Pause failed before sprite scan", { details: normalizeErrorDetails(owned.result.details) });
                 }
+                let released = false;
                 try {
-                    const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(length));
+                    const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(length), pinned);
                     if (!read.success || typeof read.data !== "string") {
                         throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(read.details) });
                     }
@@ -251,16 +253,25 @@ export const tools = [
                     }
                     let outputFiles = [];
                     if (parsed.outputDir && sprites.length > 0) {
-                        const resolvedDir = resolvePath(String(parsed.outputDir));
+                        const resolvedDir = resolveHostPath(String(parsed.outputDir), { purpose: "write" });
                         await fs.mkdir(resolvedDir, { recursive: true });
                         outputFiles = await Promise.all(sprites.map(async (sprite) => {
-                            const filePath = resolvePath(resolvedDir, `sprite_${sprite.address.replace("$", "").toLowerCase()}.spr`);
+                            const filePath = resolveHostChildPath(resolvedDir, `sprite_${sprite.address.replace("$", "").toLowerCase()}.spr`);
                             await fs.mkdir(dirname(filePath), { recursive: true });
                             await fs.writeFile(filePath, Buffer.from(hexClean(sprite.bytesHex), "hex"));
                             sprite.filePath = filePath;
                             return { path: filePath, address: sprite.address };
                         }));
                     }
+                    let warnings;
+                    if (canPause) {
+                        released = true;
+                        const result = await owned.release();
+                        if (!result.success) {
+                            warnings = [resumeWarning(result.details)];
+                            ctx.logger.warn("C64 resume reported failure after sprite scan", { details: result.details });
+                        }
+                    }
                     return jsonResult({
                         scanned: {
                             address: `$${formatAddressHex(startAddress)}`,
@@ -271,11 +282,14 @@ export const tools = [
                         },
                         sprites,
                         outputFiles,
+                        ...(warnings ? { warnings } : {}),
                     }, { success: true });
                 }
                 finally {
-                    if (canPause) {
-                        await ctx.client.resume();
+                    if (canPause && !released) {
+                        const result = await owned.release();
+                        if (!result.success)
+                            ctx.logger.warn("C64 resume reported failure after sprite scan", { details: result.details });
                     }
                 }
             }
@@ -333,18 +347,18 @@ export const tools = [
                     scanLocations.push(...commonLocations);
                 }
                 const canPause = pauseDuringRead && supportsMachinePause(ctx);
-                const pauseResume = canPause
-                    ? await ctx.client.pause()
-                    : { success: true };
-                if (canPause && !pauseResume.success) {
-                    throw new ToolExecutionError("Pause failed before charset scan", { details: normalizeErrorDetails(pauseResume.details) });
+                const owned = await acquireOwnedPause(ctx.client, canPause);
+                const pinned = owned.facade;
+                if (canPause && !owned.result.success) {
+                    throw new ToolExecutionError("Pause failed before charset scan", { details: normalizeErrorDetails(owned.result.details) });
                 }
+                let released = false;
                 try {
                     const candidates = [];
                     for (const startAddress of scanLocations) {
                         if (startAddress + charsetSize - 1 > 0xFFFF)
                             continue;
-                        const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(charsetSize));
+                        const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(charsetSize), pinned);
                         if (!read.success || typeof read.data !== "string") {
                             continue; // Skip this location if read fails
                         }
@@ -357,11 +371,22 @@ export const tools = [
                             candidates.push({ ...analysis, bytes });
                         }
                     }
+                    // Resume as soon as the reads are done, so a failure can be reported in the result.
+                    let warnings;
+                    if (canPause) {
+                        released = true;
+                        const result = await owned.release();
+                        if (!result.success) {
+                            warnings = [resumeWarning(result.details)];
+                            ctx.logger.warn("C64 resume reported failure after charset scan", { details: result.details });
+                        }
+                    }
                     if (candidates.length === 0) {
                         return jsonResult({
                             found: false,
                             scanned: scanLocations.length,
                             message: "No valid charsets found matching criteria",
+                            ...(warnings ? { warnings } : {}),
                         }, { success: true });
                     }
                     // Sort by non-empty chars descending, then by entropy descending
@@ -374,7 +399,7 @@ export const tools = [
                     const bestCandidate = candidates[0];
                     let outputFile = null;
                     if (parsed.outputPath && bestCandidate.bytes) {
-                        const resolvedPath = resolvePath(String(parsed.outputPath));
+                        const resolvedPath = resolveHostPath(String(parsed.outputPath), { purpose: "write" });
                         await fs.mkdir(dirname(resolvedPath), { recursive: true });
                         await fs.writeFile(resolvedPath, Buffer.from(bestCandidate.bytes));
                         outputFile = { path: resolvedPath, address: bestCandidate.address };
@@ -386,11 +411,14 @@ export const tools = [
                         candidates: candidates.length,
                         outputFile,
                         paused: canPause,
+                        ...(warnings ? { warnings } : {}),
                     }, { success: true });
                 }
                 finally {
-                    if (canPause) {
-                        await ctx.client.resume();
+                    if (canPause && !released) {
+                        const result = await owned.release();
+                        if (!result.success)
+                            ctx.logger.warn("C64 resume reported failure after charset scan", { details: result.details });
                     }
                 }
             }

package/dist/tools/meta/memory.js

@@ -2,10 +2,12 @@ import { objectSchema, stringSchema, numberSchema, optionalSchema, booleanSchema
 import { jsonResult } from "../responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.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 { createHash } from "node:crypto";
 import { normalizeErrorDetails } from "./util.js";
 import { stripHexByteSeparators } from "../hex.js";
+import { acquireOwnedPause, resumeWarning } from "../pauseGuard.js";
 function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id ?? ctx.client?.type;
     return platformId !== "vice";
@@ -94,16 +96,17 @@ export const tools = [
                 const readLen = Math.max(writeBytes.length, verifyLen);
                 const canPause = supportsMachinePause(ctx);
                 let paused = false;
+                const owned = await acquireOwnedPause(ctx.client, canPause);
+                const pinned = owned.facade;
                 if (canPause) {
-                    const pauseResult = await ctx.client.pause();
-                    if (!pauseResult.success) {
-                        throw new ToolExecutionError("C64 backend reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
+                    if (!owned.result.success) {
+                        throw new ToolExecutionError("C64 backend reported failure while pausing", { details: normalizeErrorDetails(owned.result.details) });
                     }
                     paused = true;
                 }
                 let preReadHex;
                 try {
-                    const pre = await ctx.client.readMemory(parsed.address, String(Math.max(1, readLen)));
+                    const pre = await ctx.client.readMemory(parsed.address, String(Math.max(1, readLen)), pinned);
                     if (!pre.success) {
                         throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(pre.details) });
                     }
@@ -123,11 +126,11 @@ export const tools = [
                             throw new ToolExecutionError("Verification failed before write", { details: { mismatches: errors, address: parsed.address } });
                         }
                     }
-                    const write = await ctx.client.writeMemory(parsed.address, bytesToHex(writeBytes));
+                    const write = await ctx.client.writeMemory(parsed.address, bytesToHex(writeBytes), pinned);
                     if (!write.success) {
                         throw new ToolExecutionError("C64 backend reported failure while writing memory", { details: normalizeErrorDetails(write.details) });
                     }
-                    const post = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeBytes.length)));
+                    const post = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeBytes.length)), pinned);
                     if (!post.success) {
                         throw new ToolExecutionError("C64 backend reported failure while reading back memory", { details: normalizeErrorDetails(post.details) });
                     }
@@ -145,17 +148,29 @@ export const tools = [
                     if (diffs.length > 0) {
                         throw new ToolExecutionError("Post-write verification failed", { details: { address: parsed.address, diffs } });
                     }
+                    let warnings;
+                    if (paused) {
+                        paused = false; // released here, so the finally block must not release again
+                        const released = await owned.release();
+                        if (!released.success) {
+                            warnings = [resumeWarning(released.details)];
+                            ctx.logger.warn("C64 resume reported failure after verified write", { details: released.details });
+                        }
+                    }
                     return jsonResult({
                         address: parsed.address,
                         wrote: bytesToHex(writeBytes),
                         preRead: preReadHex,
                         postRead: post.data ?? "",
                         paused,
+                        ...(warnings ? { warnings } : {}),
                     }, { success: true });
                 }
                 finally {
                     if (paused) {
-                        await ctx.client.resume();
+                        const released = await owned.release();
+                        if (!released.success)
+                            ctx.logger.warn("C64 resume reported failure after verified write", { details: released.details });
                     }
                 }
             }
@@ -179,18 +194,18 @@ export const tools = [
                 const length = parsed.length;
                 const chunk = Math.min(Math.max(1, parsed.chunkSize ?? 512), 4096);
                 const pause = parsed.pauseDuringRead !== false;
-                const outputPath = resolvePath(String(parsed.outputPath));
+                const outputPath = resolveHostPath(String(parsed.outputPath), { purpose: "write" });
                 const outDir = dirname(outputPath);
                 await fs.mkdir(outDir, { recursive: true });
                 const canPause = pause && supportsMachinePause(ctx);
-                if (canPause) {
-                    const res = await ctx.client.pause();
-                    if (!res.success) {
-                        throw new ToolExecutionError("Pause failed before dump", { details: normalizeErrorDetails(res.details) });
-                    }
+                const owned = await acquireOwnedPause(ctx.client, canPause);
+                const pinned = owned.facade;
+                if (canPause && !owned.result.success) {
+                    throw new ToolExecutionError("Pause failed before dump", { details: normalizeErrorDetails(owned.result.details) });
                 }
                 const buf = Buffer.allocUnsafe(length);
                 let offset = 0;
+                let released = false;
                 try {
                     while (offset < length) {
                         const remaining = length - offset;
@@ -205,7 +220,7 @@ export const tools = [
                         while (!success && attempts <= (parsed.retries ?? 1)) {
                             attempts += 1;
                             try {
-                                const r = await ctx.client.readMemory(`$${formatAddressHex(addr)}`, String(take));
+                                const r = await ctx.client.readMemory(`$${formatAddressHex(addr)}`, String(take), pinned);
                                 if (!r.success || typeof r.data !== "string") {
                                     throw new ToolExecutionError("Firmware returned failure for chunk", { details: normalizeErrorDetails(r.details) });
                                 }
@@ -243,12 +258,23 @@ export const tools = [
                         paused: canPause,
                         createdAt: new Date().toISOString(),
                     };
-                    await fs.writeFile(`${outputPath}.json`, JSON.stringify(manifest, null, 2), "utf8");
-                    return jsonResult({ manifest }, { success: true });
+                    await fs.writeFile(resolveHostPath(`${outputPath}.json`, { purpose: "write" }), JSON.stringify(manifest, null, 2), "utf8");
+                    let warnings;
+                    if (canPause) {
+                        released = true;
+                        const result = await owned.release();
+                        if (!result.success) {
+                            warnings = [resumeWarning(result.details)];
+                            ctx.logger.warn("C64 resume reported failure after dump", { details: result.details });
+                        }
+                    }
+                    return jsonResult({ manifest, ...(warnings ? { warnings } : {}) }, { success: true });
                 }
                 finally {
-                    if (canPause) {
-                        await ctx.client.resume();
+                    if (canPause && !released) {
+                        const result = await owned.release();
+                        if (!result.success)
+                            ctx.logger.warn("C64 resume reported failure after dump", { details: result.details });
                     }
                 }
             }

package/dist/tools/meta/program.js

@@ -5,6 +5,7 @@ import { measureSidSilence } from "../audio.js";
 import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
+import { defaultHostOutputDir, resolveHostChildPath, resolveHostPath } from "../../hostPaths.js";
 import { sleep, formatTimestampSpec } from "./util.js";
 import { getTasksHomeDir } from "./background.js";
 import { Jimp } from "jimp";
@@ -325,7 +326,9 @@ export const tools = [
                 const captureScreenshot = visibleViceFastPath ? false : parsed.captureScreenshot !== false;
                 const restoreActiveBackend = parsed.restoreActiveBackend !== false;
                 const outputPath = (captureScreenshot && requestedBackends.some((backend) => backend !== "u2")) || parsed.outputPath
-                    ? resolvePath(String(parsed.outputPath ?? joinPath(process.cwd(), "artifacts", "greetings", `run_${Date.now()}`)))
+                    ? (parsed.outputPath
+                        ? resolveHostPath(String(parsed.outputPath), { purpose: "write" })
+                        : defaultHostOutputDir("artifacts", "greetings", `run_${Date.now()}`))
                     : undefined;
                 const timeoutMs = parsed.timeoutMs ?? 1500;
                 const pollIntervalMs = parsed.pollIntervalMs ?? 100;
@@ -434,7 +437,7 @@ export const tools = [
                                 await timedStep("persist_screenshot", async () => {
                                     screenshotAnalysis = analyseCapturedFrame(frame);
                                     screenshotPath = outputPath
-                                        ? resolvePath(joinPath(outputPath, `${backend}.png`))
+                                        ? resolveHostChildPath(outputPath, `${backend}.png`)
                                         : undefined;
                                     if (screenshotPath) {
                                         await writeCapturedFramePng(frame, screenshotPath);
@@ -514,7 +517,7 @@ export const tools = [
                     ...(restoreError ? { restoreError } : {}),
                 };
                 if (outputPath) {
-                    const reportPath = resolvePath(joinPath(outputPath, "results.json"));
+                    const reportPath = resolveHostChildPath(outputPath, "results.json");
                     await fs.writeFile(reportPath, JSON.stringify(payload, null, 2), "utf8");
                     payload.outputPath = outputPath;
                     payload.reportPath = reportPath;
@@ -571,7 +574,7 @@ export const tools = [
                 }
                 // Prepare output directory
                 const outputPath = parsed.outputPath
-                    ? resolvePath(String(parsed.outputPath))
+                    ? resolveHostPath(String(parsed.outputPath), { purpose: "write" })
                     : resolvePath(joinPath(getTasksHomeDir(), `shuffle_${Date.now()}`));
                 await fs.mkdir(outputPath, { recursive: true });
                 const results = [];
@@ -619,7 +622,7 @@ export const tools = [
                     });
                 }
                 // Write log
-                const logPath = resolvePath(joinPath(outputPath, "shuffle.json"));
+                const logPath = resolveHostChildPath(outputPath, "shuffle.json");
                 await fs.writeFile(logPath, JSON.stringify({ programs: results, summary: { total: results.length, errors: results.filter(r => r.error).length } }, null, 2), "utf8");
                 return jsonResult({ outputPath, programs: results.length, errors: results.filter(r => r.error).length, logPath }, { success: true });
             }
@@ -660,7 +663,7 @@ export const tools = [
                 const durationMs = parsed.durationMs ?? 2000;
                 const resetDelayMs = parsed.resetDelayMs ?? 100;
                 const outputPath = parsed.outputPath
-                    ? resolvePath(String(parsed.outputPath))
+                    ? resolveHostPath(String(parsed.outputPath), { purpose: "write" })
                     : resolvePath(joinPath(getTasksHomeDir(), `batch_${Date.now()}`));
                 await fs.mkdir(outputPath, { recursive: true });
                 const results = [];
@@ -768,7 +771,7 @@ export const tools = [
                     }
                 }
                 // Write junit-like report
-                const reportPath = resolvePath(joinPath(outputPath, "results.json"));
+                const reportPath = resolveHostChildPath(outputPath, "results.json");
                 const summary = {
                     total: results.length,
                     passed: results.filter(r => r.status === "pass").length,

package/dist/tools/meta/screen.js

@@ -1,18 +1,120 @@
 import { objectSchema, stringSchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { sleep } from "./util.js";
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+export const MAX_PATTERN_LENGTH = 200;
+export const MAX_WAIT_TIMEOUT_MS = 120000;
+export const MIN_POLL_INTERVAL_MS = 20;
+/**
+ * Checks a user regular expression before it runs on the event loop. A pattern
+ * such as (a+)+$ takes exponential time on a screen of identical characters, so
+ * quantified groups that contain a quantifier are rejected, as are
+ * backreferences (also a source of super-linear matching).
+ */
+export function assertSafeScreenPattern(pattern) {
+    const path = "$.pattern";
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw new ToolValidationError(`Pattern is ${pattern.length} characters; the limit is ${MAX_PATTERN_LENGTH}`, { path });
+    }
+    // One entry per open group: whether it contains a quantifier.
+    const groups = [];
+    let inClass = false;
+    let previousWasGroupWithQuantifier = false;
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const isQuantifier = !inClass && (char === "*" || char === "+" || char === "?" || (char === "{" && /^\{\d+(,\d*)?\}/.test(pattern.slice(index))));
+        if (char === "\\") {
+            const next = pattern[index + 1] ?? "";
+            if (!inClass && (/[1-9]/.test(next) || (next === "k" && pattern[index + 2] === "<"))) {
+                throw new ToolValidationError("Backreferences are not supported in screen patterns", { path });
+            }
+            index += 1;
+            previousWasGroupWithQuantifier = false;
+            continue;
+        }
+        if (inClass) {
+            if (char === "]")
+                inClass = false;
+            continue;
+        }
+        if (char === "[") {
+            inClass = true;
+            previousWasGroupWithQuantifier = false;
+            continue;
+        }
+        if (char === "(") {
+            groups.push(false);
+            previousWasGroupWithQuantifier = false;
+            continue;
+        }
+        if (char === ")") {
+            previousWasGroupWithQuantifier = groups.pop() ?? false;
+            continue;
+        }
+        if (isQuantifier) {
+            // "(?" opens a group modifier, and a "?" after another quantifier makes it lazy; neither is a repeat.
+            const opensModifier = char === "?" && pattern[index - 1] === "(";
+            const isLazyMarker = char === "?" && "*+?}".includes(pattern[index - 1] ?? "");
+            if (!opensModifier && !isLazyMarker) {
+                if (previousWasGroupWithQuantifier) {
+                    throw new ToolValidationError("Nested quantifiers (a repeated group that itself contains a repeat) are not supported in screen patterns", { path });
+                }
+                if (groups.length > 0)
+                    groups[groups.length - 1] = true;
+            }
+            previousWasGroupWithQuantifier = false;
+            continue;
+        }
+        previousWasGroupWithQuantifier = false;
+    }
+}
+export function compileScreenPattern(pattern, isRegex, caseInsensitive) {
+    const flags = caseInsensitive ? "i" : undefined;
+    if (!isRegex) {
+        return new RegExp(escapeRegex(pattern), flags);
+    }
+    assertSafeScreenPattern(pattern);
+    try {
+        return new RegExp(pattern, flags);
+    }
+    catch (error) {
+        throw new ToolValidationError(`Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`, { path: "$.pattern" });
+    }
+}
+/** Polls the screen until the pattern matches or the timeout elapses. Does not throw on timeout. */
+export async function waitForScreenText(client, options) {
+    const timeoutMs = Math.min(options.timeoutMs ?? 3000, MAX_WAIT_TIMEOUT_MS);
+    const intervalMs = Math.max(options.intervalMs ?? 100, MIN_POLL_INTERVAL_MS);
+    const regex = compileScreenPattern(options.pattern, options.isRegex ?? false, options.caseInsensitive ?? true);
+    const start = Date.now();
+    let lastScreen;
+    while (Date.now() - start < timeoutMs) {
+        const screen = await client.readScreen();
+        lastScreen = screen;
+        const match = screen.match(regex);
+        if (match && match.index !== undefined) {
+            return {
+                matched: true,
+                match: { index: match.index, length: match[0]?.length ?? 0, text: match[0] ?? "" },
+                elapsedMs: Date.now() - start,
+                screen,
+            };
+        }
+        await sleep(intervalMs);
+    }
+    return { matched: false, elapsedMs: Date.now() - start, screen: lastScreen };
+}
 const waitForScreenTextArgsSchema = objectSchema({
     description: "Poll screen until text or regex matches, or timeout elapses.",
     properties: {
-        pattern: stringSchema({ description: "Substring or regex to find", minLength: 1 }),
+        pattern: stringSchema({ description: "Substring or regex to find (at most 200 characters; regex with nested quantifiers or backreferences is rejected)", minLength: 1, maxLength: 200 }),
         isRegex: optionalSchema(booleanSchema({ description: "Interpret pattern as regular expression", default: false }), false),
         caseInsensitive: optionalSchema(booleanSchema({ description: "Case-insensitive search", default: true }), true),
-        timeoutMs: optionalSchema(numberSchema({ description: "Overall timeout in milliseconds", integer: true, minimum: 1, default: 3000 }), 3000),
-        intervalMs: optionalSchema(numberSchema({ description: "Poll interval in milliseconds", integer: true, minimum: 1, default: 100 }), 100),
+        timeoutMs: optionalSchema(numberSchema({ description: "Overall timeout in milliseconds (1-120000)", integer: true, minimum: 1, maximum: 120000, default: 3000 }), 3000),
+        intervalMs: optionalSchema(numberSchema({ description: "Poll interval in milliseconds (at least 20)", integer: true, minimum: 20, default: 100 }), 100),
     },
     required: ["pattern"],
     additionalProperties: false,
@@ -28,28 +130,17 @@ export const tools = [
         async execute(args, ctx) {
             try {
                 const parsed = waitForScreenTextArgsSchema.parse(args ?? {});
-                const start = Date.now();
-                const flags = parsed.caseInsensitive ? "i" : undefined;
-                const regex = parsed.isRegex
-                    ? new RegExp(parsed.pattern, flags)
-                    : new RegExp(escapeRegex(parsed.pattern), flags);
-                while (Date.now() - start < (parsed.timeoutMs ?? 3000)) {
-                    const screen = await ctx.client.readScreen();
-                    const match = screen.match(regex);
-                    if (match && match.index !== undefined) {
-                        return jsonResult({
-                            matched: true,
-                            match: {
-                                index: match.index,
-                                length: match[0]?.length ?? 0,
-                                text: match[0] ?? "",
-                            },
-                            elapsedMs: Date.now() - start,
-                        }, { success: true });
-                    }
-                    await sleep(Math.max(1, parsed.intervalMs ?? 100));
+                const result = await waitForScreenText(ctx.client, parsed);
+                if (result.matched) {
+                    return jsonResult({
+                        matched: true,
+                        match: result.match,
+                        elapsedMs: result.elapsedMs,
+                    }, { success: true });
                 }
-                throw new ToolExecutionError("Timeout waiting for screen text", { details: { pattern: parsed.pattern, timeoutMs: parsed.timeoutMs } });
+                throw new ToolExecutionError("Timeout waiting for screen text", {
+                    details: { pattern: parsed.pattern, timeoutMs: parsed.timeoutMs, elapsedMs: result.elapsedMs, screen: result.screen ?? null },
+                });
             }
             catch (error) {
                 if (error instanceof ToolError)

package/dist/tools/pauseGuard.js

@@ -0,0 +1,23 @@
+export async function acquireOwnedPause(client, enabled = true) {
+    const c = client;
+    const facade = typeof c.pinFacade === "function" ? await c.pinFacade() : undefined;
+    if (!enabled)
+        return { facade, result: { success: true }, release: async () => ({ success: true }) };
+    const result = typeof c.acquirePause === "function" ? await c.acquirePause(facade) : await c.pause(facade);
+    return {
+        facade,
+        result,
+        async release() {
+            try {
+                return typeof c.releasePause === "function" ? await c.releasePause(facade) : await c.resume(facade);
+            }
+            catch (error) {
+                return { success: false, details: { message: error instanceof Error ? error.message : String(error) } };
+            }
+        },
+    };
+}
+export function resumeWarning(details) {
+    const text = details && typeof details === "object" && "message" in details ? String(details.message) : "";
+    return `The machine could not be resumed after the operation${text ? ` (${text})` : ""}; call c64_system with op 'resume'.`;
+}