c64bridge 1.0.7 → 1.1.0

package/README.md

@@ -378,6 +378,54 @@ The screenshots below are available for the two backends that provide frame capt
 | U2-family | Frame capture unavailable (no firmware streaming). |
 | VICE | ![VICE backend switch example](doc/img/backend-switch/hello-vice.png) |
 
+### Host File Access
+
+Tool arguments that name a file or directory on the machine running C64 Bridge (memory dumps, configuration snapshots, sprite and charset exports, run artifacts, symbol files, and VICE PRG or disk image paths) are confined to a set of allowed directories:
+
+- the working directory of the server, unless it is the user's home directory or `/`
+- `~/.c64bridge`
+- the system temporary directory (`os.tmpdir()`)
+
+Paths are resolved to their real location before the check, so `..` segments and symbolic links cannot leave these directories. A rejected path produces a validation error that lists the allowed directories, and nothing is written. Files read through these arguments are limited to 16 MiB (64 MiB for disk images).
+
+Set `C64BRIDGE_ALLOWED_DIRS` to add directories. Separate entries with the platform path delimiter (`:` on Linux and macOS, `;` on Windows). The single value `*` disables the confinement.
+
+```json
+"env": { "C64BRIDGE_ALLOWED_DIRS": "/home/you/c64:/home/you/disks" }
+```
+
+Earlier versions accepted any path. Clients that pass paths outside these directories must now add them through `C64BRIDGE_ALLOWED_DIRS`.
+
+### Access Mode
+
+Every operation has an effect: `read` (no change), `write` (changes machine or emulator state that a reset undoes, or writes a host file) or `destructive` (survives a reset or interrupts availability, for example power off, power cycle, reboot, flash save, load or reset to defaults, drive ROM load, disk image creation, debug register write, and config restore with `applyToFlash`). `tools/list` publishes MCP annotations derived from these effects, and each operation line in a tool description names its effect when it is not `read`.
+
+Set `C64BRIDGE_ACCESS` to restrict what a client may call:
+
+- `full` (default): all operations are allowed.
+- `no-destructive`: `destructive` operations are rejected.
+- `read-only`: only `read` operations are allowed.
+
+The variable is read on every call. An unknown value is treated as `read-only` and logged to stderr once. A rejected call returns a validation error that names the operation, its effect and the active mode. `c64_batch` checks each command separately, and `c64_system` `start_task` checks the effect of its task operation when the task starts. `c64://platform/status` shows the active mode.
+
+After `c64_system` `poweroff` on C64U/U64, power must be restored at the outlet. The machine starts by itself only if automatic startup on power restoration is enabled in its configuration.
+
+```json
+"env": { "C64BRIDGE_ACCESS": "no-destructive" }
+```
+
+### Operator Environment Variables
+
+These variables are read by the server itself and are set in the `env` block of the MCP client configuration. `C64BRIDGE_ALLOWED_DIRS` and `C64BRIDGE_ACCESS` are described above.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `C64BRIDGE_ALLOWED_DIRS` | unset | Additional directories for host file paths in tool arguments. Separate entries with the platform path delimiter; `*` disables the confinement. |
+| `C64BRIDGE_ACCESS` | `full` | `full`, `no-destructive` or `read-only`. Limits which operations a client may call. |
+| `C64BRIDGE_HTTP_TOKEN` | unset | When set, the optional HTTP transport (`--http`) requires `Authorization: Bearer <token>`. The transport accepts only loopback `Host` and `Origin` headers regardless of this setting. |
+| `C64BRIDGE_DIAGNOSTICS_KEEP` | `200` | Number of diagnostics files kept in the diagnostics directory. At startup the server deletes older files beyond this count and files older than 30 days. An invalid value is ignored with a warning on stderr. Diagnostics files are created with mode 0600 in a directory created with mode 0700. |
+| `C64BRIDGE_VERBOSE_SCHEMA` | unset | Set to `1` to include the full per-operation schemas in `tools/list`. By default they are omitted to keep the listing small. |
+
 ## VS Code MCP Setup
 
 This section covers the GitHub Copilot integration that ships with VS Code. For the Claude Code VS Code plugin, see [Claude Code](#claude-code) — it reads `.mcp.json`, not `.vscode/mcp.json`.
@@ -524,12 +572,17 @@ Every runtime environment variable documented in `mcp.json` can be set in your M
 | --- | --- | --- | --- |
 | `C64_MODE` | c64u | — | Select active backend (c64u/U64 hardware, u2/U2-family cartridge, or vice emulator) |
 | `C64_TASK_STATE_FILE` | auto | — | Override the path used to persist MCP background-task state |
+| `C64BRIDGE_ACCESS` | full | — | Access mode limiting which operations may be called (full, no-destructive, read-only) |
+| `C64BRIDGE_ALLOWED_DIRS` |  | — | Additional directories allowed for host file paths in tool arguments, separated by the path delimiter; * disables the check |
 | `C64BRIDGE_CONFIG` | ~/.c64bridge.json | config path | Path to configuration JSON |
 | `C64BRIDGE_DIAGNOSTICS_DIR` | ~/.c64bridge/diagnostics | — | Override the directory where persistent MCP diagnostics files are written |
+| `C64BRIDGE_DIAGNOSTICS_KEEP` | 200 | — | Number of diagnostics files kept at startup; files older than 30 days are always removed |
 | `C64BRIDGE_DISABLE_DIAGNOSTICS` | 0 | — | Set to 1 to disable persistent diagnostics logging |
+| `C64BRIDGE_HTTP_TOKEN` |  | — | Bearer token required by the optional HTTP transport (--http) |
 | `C64BRIDGE_POLL_INTERVAL_MS` | 200 | — | Interval between screen polls during program-output validation in normal runtime mode |
 | `C64BRIDGE_POLL_MAX_MS` | 2000 | — | Maximum time to poll for program-output validation before timing out in normal runtime mode |
 | `C64BRIDGE_POLL_STABILIZE_MS` | 100 | — | Extra settle time after a successful poll match before considering output stable |
+| `C64BRIDGE_VERBOSE_SCHEMA` |  | — | Set to 1 to include full per-operation schemas in tools/list |
 | `LOG_LEVEL` | info | — | Logger verbosity (debug, info, warn, error) |
 
 #### C64 Ultimate
@@ -715,16 +768,16 @@ Grouped entry point for configuration reads/writes, diagnostics, and snapshots.
 
 | Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
 | --- | --- | --- | --- | --- | --- | --- |
-| `batch_update` | Apply multiple configuration updates in a single request. | — | — | ✅ | ✅ | ✅ |
+| `batch_update` | Apply multiple configuration updates in a single request. Pass `updates` as {category: {item: value}}; categories as top-level keys are still accepted at runtime. | — | `updates` | ✅ | ✅ | ✅ |
 | `diff` | Compare the current configuration with a snapshot. | `path` | — | ✅ | ✅ | ✅ |
 | `get` | Read a configuration category or specific item. | `category` | `item`, `includeSecretValues=false` | ✅ | ✅ | ✅ |
 | `info` | Retrieve Ultimate hardware information and status. | — | — | ✅ | ✅ | ✅ |
 | `list` | List configuration categories reported by the firmware. | — | — | ✅ | ✅ | ✅ |
-| `load_flash` | Load configuration from flash storage. | — | — | ✅ | ✅ |  |
+| `load_flash` | Load configuration from flash storage. | — | `category` | ✅ | ✅ |  |
 | `read_debugreg` | Read the Ultimate debug register ($D7FF). | — | — | ✅ |  |  |
-| `reset_defaults` | Reset firmware configuration to factory defaults. | — | — | ✅ | ✅ |  |
+| `reset_defaults` | Reset firmware configuration to factory defaults. | — | `category` | ✅ | ✅ |  |
 | `restore` | Restore configuration from a snapshot file. | `path` | `applyToFlash=false` | ✅ | ✅ | ✅ |
-| `save_flash` | Persist the current configuration to flash storage. | — | — | ✅ | ✅ |  |
+| `save_flash` | Persist the current configuration to flash storage. | — | `category` | ✅ | ✅ |  |
 | `set` | Write a configuration value in the selected category. | `category`, `item`, `value` | — | ✅ | ✅ | ✅ |
 | `shuffle` | Discover PRG/CRT files and run each with optional screen capture. | — | `root="/"`, `extensions=["prg","crt"]`, `durationMs=5000`, `captureScreen=true`, `maxPrograms=10`, `outputPath`, `resetDelayMs=100` | ✅ | ✅ |  |
 | `snapshot` | Snapshot configuration to disk for later restore or diff. | `path` | — | ✅ | ✅ | ✅ |
@@ -762,6 +815,7 @@ Grouped entry point for disk mounts, listings, image creation, and program disco
 | `create_image` | Create a blank disk image of the specified format. | `format`, `path` | `diskname`, `tracks` | ✅ | ✅ |  |
 | `file_info` | Inspect metadata for a file on the Ultimate filesystem. | `path` | — | ✅ | ✅ |  |
 | `find_and_run` | Search for a PRG/CRT by name substring and run the first match. | `nameContains` | `root="/"`, `extensions`, `caseInsensitive=true`, `sort="discovered"`, `waitMs=0`, `captureCandidates=10` | ✅ | ✅ |  |
+| `find_paths` | Search Ultimate storage for paths whose names contain a substring, without running anything. | `nameContains` | `root="/"`, `extensions`, `maxResults=100`, `caseInsensitive=true` | ✅ | ✅ |  |
 | `list_drives` | List Ultimate drive slots and their mounted images. | — | — | ✅ | ✅ | ✅ |
 | `mount` | Mount a disk image with optional verification and retries. Supports verification. | `drive`, `image` | `type`, `attachmentMode`, `driveMode`, `verify=false`, `powerOnIfNeeded=true`, `resetAfterMount=true`, `maxRetries=2`, `retryDelayMs=500` | ✅ | ✅ | ✅ |
 | `unmount` | Remove the mounted image from an Ultimate drive slot. | `drive` | — | ✅ | ✅ |  |
@@ -796,7 +850,7 @@ Grouped entry point for frame capture and graphics rendering workflows.
 
 | Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
 | --- | --- | --- | --- | --- | --- | --- |
-| `capture_frame` | Capture one or more complete video frames from the active backend. | — | `count=1`, `includePixels=true`, `encoding="base64"` | ✅ |  | ✅ |
+| `capture_frame` | Capture one or more complete video frames from the active backend. | — | `count=1`, `includePixels=false`, `format`, `encoding="base64"` | ✅ |  | ✅ |
 | `get_display_state` | Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical. | — | — | ✅ | ✅ | ✅ |
 | `render_bitmap` | Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it. | `imagePath`, `format` | `bitmapAddress=8192`, `screenAddress=1024`, `borderColor=0`, `backgroundColor=0`, `preserveAspect=true` | ✅ | ✅ | ✅ |
 | `render_petscii_art` | Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64. | — | `prompt`, `text`, `maxWidth`, `maxHeight`, `borderColor`, `backgroundColor`, `foregroundColor`, `dryRun=false`, `bitmap` | ✅ | ✅ | ✅ |
@@ -810,7 +864,7 @@ Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.
 | Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
 | --- | --- | --- | --- | --- | --- | --- |
 | `joystick` | Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. | `port`, `controls`, `action` | `durationMs=80` | ✅ |  | ✅ |
-| `key` | Tap a single key or hold it for a duration. | `key` | `durationMs=0`, `count=1` | ✅ | ✅ | ✅ |
+| `key` | Press a single key one or more times, optionally with a delay between presses. | `key` | `durationMs=0`, `count=1` | ✅ | ✅ | ✅ |
 | `keyboard` | Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). | `inputs`, `transition` | — | ✅ |  |  |
 | `release_all` | Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). | — | — | ✅ |  |  |
 | `state` | Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). | — | — | ✅ |  |  |
@@ -826,7 +880,8 @@ Grouped entry point for memory I/O, screen reads, and screen polling.
 | `copy_memory` | Copy a RAM region to another address. | `source`, `dest`, `length` | — | ✅ | ✅ | ✅ |
 | `disassemble` | Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE. | `address` | `length=64`, `instructionCount` | ✅ | ✅ | ✅ |
 | `fill_memory` | Fill a memory range with a repeating byte pattern. | `address`, `length`, `pattern` | — | ✅ | ✅ | ✅ |
-| `read` | Read a range of bytes and return a hex dump with address metadata. | `address` | `length=256` | ✅ | ✅ | ✅ |
+| `list_basic` | List the BASIC program in memory as text: reads the $2B-$2E pointers, walks the line links and detokenises. Works on C64U/U64, U2-family hardware, and VICE. | — | — | ✅ | ✅ | ✅ |
+| `read` | Read a range of bytes and return a hex dump with address metadata. | `address` | `length=256`, `format="hex"` | ✅ | ✅ | ✅ |
 | `read_screen` | Return the current 40x25 text screen converted to ASCII. | — | — | ✅ | ✅ | ✅ |
 | `save_memory` | Dump a memory range to a local file, with an optional PRG load-address header. | `startAddress`, `endAddress`, `filePath` | `asPrg=true` | ✅ | ✅ | ✅ |
 | `search_memory` | Search for a byte pattern within a memory range and return matching addresses. | `startAddress`, `endAddress`, `pattern` | `maxResults=10` | ✅ | ✅ | ✅ |
@@ -852,11 +907,11 @@ Grouped entry point for program upload, execution, and batch workflows.
 | `batch_run` | Run multiple PRG/CRT programs with post-run assertions. | `programs` | `continueOnError=false`, `durationMs=2000`, `outputPath`, `resetDelayMs=100` | ✅ | ✅ | ✅ |
 | `bundle_run` | Capture screen, memory, and debug registers into an artifact bundle. | `runId`, `outputPath` | `captureScreen=true`, `memoryRanges`, `captureDebugReg` | ✅ | ✅ | ✅ |
 | `cross_platform_greeting` | Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results. Supports verification. | — | `platforms`, `messageTemplate="HAVE A GREAT DAY, {PLATFORM}!"`, `verify=true`, `captureScreenshot=true`, `outputPath`, `restoreActiveBackend=true`, `timeoutMs=1500`, `pollIntervalMs=100` | ✅ | ✅ | ✅ |
-| `load_prg` | Load a PRG from Ultimate storage without executing it. | `path` | `symbolsFile` | ✅ | ✅ |  |
+| `load_prg` | Load a PRG from Ultimate storage without executing it. | `path` | `symbolsFile` | ✅ | ✅ | ✅ |
 | `run_crt` | Mount and run a CRT cartridge image. | `path` | — | ✅ | ✅ |  |
 | `run_prg` | Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE. | `path` | `symbolsFile` | ✅ | ✅ | ✅ |
 | `upload_run_asm` | Assemble 6502/6510 source, upload the PRG, and execute it. Supports verification. | `program` | `verify=false` | ✅ | ✅ | ✅ |
-| `upload_run_basic` | Upload Commodore BASIC v2 source and execute it immediately. Supports verification. | `program` | `verify=false` | ✅ | ✅ | ✅ |
+| `upload_run_basic` | Upload Commodore BASIC v2 source and execute it immediately. Supports verification. | `program` | `verify=false`, `autoFix=true` | ✅ | ✅ | ✅ |
 
 #### c64_rag
 
@@ -902,7 +957,7 @@ Grouped entry point for starting and stopping Ultimate streaming sessions.
 
 | Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
 | --- | --- | --- | --- | --- | --- | --- |
-| `start` | Start an Ultimate streaming session toward a host:port target. | `stream`, `target` | — | ✅ |  |  |
+| `start` | Start an Ultimate streaming session. The device sends an unencrypted UDP stream to the target (IPv4 address or hostname, optional :port). | `stream`, `target` | — | ✅ |  |  |
 | `stop` | Stop an active Ultimate streaming session. | `stream` | — | ✅ |  |  |
 
 #### c64_system
@@ -915,11 +970,11 @@ Grouped entry point for power, reset, menu, and background task control.
 | `menu` | Toggle the Ultimate menu button for navigation. | — | — | ✅ | ✅ |  |
 | `pause` | Pause the machine until resumed. | — | — | ✅ | ✅ |  |
 | `performance_report` | Summarize diagnostics spans and tool latencies from the current or latest MCP session. | — | `scope="current"`, `includeTimeline=true`, `maxEntries=25` | ✅ | ✅ | ✅ |
-| `power_cycle` | Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST. | — | — | ✅ | ✅ | ✅ |
-| `poweroff` | Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. | — | — | ✅ |  | ✅ |
+| `power_cycle` | Return the active backend to a fresh state. C64U/U64 Tool Menu verification requires machine:menu_screen (a C64U firmware version that provides it, or U64 3.15+); U2-family reboots through REST. | — | `waitForReady=false`, `readyTimeoutMs=15000` | ✅ | ✅ | ✅ |
+| `poweroff` | Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. On C64U/U64 the machine cannot be restarted by software afterwards: power must be restored at the outlet, and it starts by itself only if automatic startup on power restoration is enabled. | — | — | ✅ |  | ✅ |
 | `read_menu_screen` | Read the active Ultimate menu's raw character and colour matrix through machine:menu_screen (a C64U firmware version that provides it, or U64/U2 3.15+). | — | — | ✅ | ✅ |  |
-| `reboot` | Trigger a firmware reboot to recover from faults. | — | — | ✅ | ✅ | ✅ |
-| `reset` | Issue a soft reset without cutting power. | — | — | ✅ | ✅ | ✅ |
+| `reboot` | Trigger a firmware reboot to recover from faults. | — | `waitForReady=false`, `readyTimeoutMs=15000` | ✅ | ✅ | ✅ |
+| `reset` | Issue a soft reset without cutting power. | — | `waitForReady=false`, `readyTimeoutMs=15000` | ✅ | ✅ | ✅ |
 | `resume` | Resume CPU execution after a pause. | — | — | ✅ | ✅ |  |
 | `start_task` | Start a named background task that runs on an interval. | `name`, `operation` | `arguments={}`, `intervalMs=1000`, `maxIterations` | ✅ | ✅ | ✅ |
 | `stop_all_tasks` | Stop every running background task and persist state. | — | — | ✅ | ✅ | ✅ |

package/data/assembly/assembly-spec.md

@@ -483,6 +483,8 @@ FF ISC ABSX U 7 - M←M+1; A←A-M-(1-C); set(C,Z,N,V)
 - Data: `.byte expr[,…]`, `.word expr[,…]`  
 - Symbols: `name = expr` / `.equ name, expr`  
 - Alignment/fill (assembler‑specific): `.align n`, `.fill count, value`
+- Text: `.text "str"` / `.ascii "str"` convert ASCII to PETSCII for the default upper-case/graphics set: `a`-`z` and `A`-`Z` both become codes `$41`-`$5A`, `\n` becomes RETURN (`$0D`), other ASCII characters (digits, punctuation, space) are unchanged, and characters above `$7F` are an error.
+- `.equ` accepts both `name .equ expr` and `.equ name, expr`; `.fill count[, value]` and `.align n[, fill]` default the fill byte to 0.
 
 ## Tips and Tricks
 

package/dist/c64Client.js

@@ -8,6 +8,7 @@ See <https://www.gnu.org/licenses/> for details.
 import { Buffer } from "node:buffer";
 import { execFile } from "node:child_process";
 import { createSocket } from "node:dgram";
+import { lookup } from "node:dns/promises";
 import { networkInterfaces } from "node:os";
 import axios from "axios";
 import { basicToPrg } from "./tools/translation/basicTokenizer.js";
@@ -16,9 +17,11 @@ import { stripHexByteSeparators } from "./tools/hex.js";
 import { SIDWAVE_PLAY_ADDRESS } from "./sidwaveCompiler.js";
 import { petsciiToAscii, screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
+import { assertNotBareHex, parseNumericLiteral } from "./numericArg.js";
+import { ToolValidationError } from "./tools/errors.js";
 import { createAllFacades, createFacade, } from "./device.js";
 import { Api } from "../generated/c64/index.js";
-import { createLoggingHttpClient } from "./loggingHttpClient.js";
+import { createLoggingHttpClient, RequestQueue } from "./loggingHttpClient.js";
 import { withDiagnosticSpan, writeDiagnosticEvent } from "./diagnostics.js";
 import { analyzeStereoStream, normalizeAudioDuration, recordAndAnalyzeAudio, } from "./audio/record_and_analyze_audio.js";
 import { C64U_NTSC_AUDIO_SAMPLE_RATE, C64U_PAL_AUDIO_SAMPLE_RATE, collectCompleteVideoFrames, parseAudioPacket, parseVideoPacket, } from "./streamCapture.js";
@@ -34,6 +37,10 @@ export class KeyboardQueueDrainTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "::1" || h.startsWith("127.");
+}
 /** JOYPORT_ID_IO_SIMULATION in joyport.h (the same in VICE 3.9 and 3.10). */
 const VICE_JOYPORT_IO_SIMULATION = 37;
 const C64U_SYSTEM_MODE_CATEGORY = "U64 Specific Settings";
@@ -190,9 +197,19 @@ export class C64Client {
         /** VICE joyport device ids to restore when a joystick press ends. */
         this.viceJoyportSavedDevice = new Map();
         this.activeType = "c64u";
+        /**
+         * Pause bookkeeping per facade. Tools that pause for their own purpose
+         * (acquirePause/releasePause) share one device pause: it is sent when the
+         * owned depth goes 0 -> 1 and the machine is not already explicitly paused,
+         * and the device resume is sent only when the depth returns to 0 and no
+         * explicit `c64_system pause` is in effect. An explicit pause is cleared
+         * only by an explicit resume.
+         */
+        this.pauseStates = new WeakMap();
         this.baseUrl = baseUrl;
         const headers = options.networkPassword ? { "X-Password": options.networkPassword } : undefined;
-        this.http = createLoggingHttpClient({ baseURL: baseUrl, timeout: 10000, headers });
+        // Shares the device queue with the C64U backend: the fallback REST calls made through this client must not overlap its requests.
+        this.http = createLoggingHttpClient({ baseURL: baseUrl, timeout: 10000, headers }, undefined, RequestQueue.forDevice(baseUrl));
         this.api = new Api(this.http);
         const forceC64uFacade = options.forceC64uFacade ?? true;
         if (forceC64uFacade) {
@@ -659,15 +676,44 @@ export class C64Client {
         }
     }
     async readScreen() {
+        return (await this.readScreenDetailed()).text;
+    }
+    /**
+     * Reads the text screen where the VIC-II currently shows it: the screen
+     * base comes from $D018 bits 4-7 and the VIC bank from $DD00 bits 0-1, and
+     * $D018 bit 1 selects the lower-case character set. Reads of both registers
+     * that fail, or that both return $00 (not a usable VIC state), fall back to
+     * the default $0400 and the upper-case set.
+     */
+    async readScreenDetailed() {
         return withDiagnosticSpan("client", "read_screen", {}, async () => {
-            const bytes = await this.readMemoryRaw(0x0400, 0x03e8);
-            return screenCodesToAscii(bytes, { columns: 40, rows: 25 });
+            let baseAddress = 0x0400;
+            let charset = "upper";
+            let registers;
+            try {
+                const d018 = (await this.readMemoryRaw(0xd018, 1))[0];
+                const dd00 = (await this.readMemoryRaw(0xdd00, 1))[0];
+                if (d018 !== undefined && dd00 !== undefined && !(d018 === 0 && dd00 === 0)) {
+                    registers = { d018, dd00 };
+                    baseAddress = (3 - (dd00 & 0x03)) * 0x4000 + ((d018 >> 4) & 0x0f) * 0x0400;
+                    charset = (d018 & 0x02) !== 0 ? "lower" : "upper";
+                }
+            }
+            catch {
+                // Keep the defaults when the VIC registers cannot be read.
+            }
+            const length = Math.min(0x03e8, 0x10000 - baseAddress);
+            const bytes = await this.readMemoryRaw(baseAddress, length);
+            const text = screenCodesToAscii(bytes, { columns: 40, rows: 25, charset });
+            return { text, baseAddress, charset, ...(registers ? { registers } : {}) };
         });
     }
     async reset() {
         try {
             const facade = await this.facadePromise;
             const res = await facade.reset();
+            if (res.success)
+                this.clearExplicitPause(facade);
             return { success: res.success, details: res.details };
         }
         catch (error) {
@@ -678,6 +724,8 @@ export class C64Client {
         try {
             const facade = await this.facadePromise;
             const res = await facade.reboot();
+            if (res.success)
+                this.clearExplicitPause(facade);
             return { success: res.success, details: res.details };
         }
         catch (error) {
@@ -906,21 +954,127 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    pauseStateFor(facade) {
+        let state = this.pauseStates.get(facade);
+        if (!state) {
+            state = { depth: 0, explicit: false };
+            this.pauseStates.set(facade, state);
+        }
+        return state;
+    }
+    /** Owned pause for one tool call. Pass the facade pinned at call start; pair with releasePause. A failed result holds no pause and needs no release. */
+    async acquirePause(pinnedFacade) {
+        try {
+            const facade = pinnedFacade ?? await this.facadePromise;
+            const state = this.pauseStateFor(facade);
+            state.depth += 1;
+            if (state.depth === 1 && !state.explicit) {
+                const pending = facade.pause().catch((error) => ({ success: false, details: this.normaliseError(error) }));
+                state.devicePause = pending;
+            }
+            const result = state.devicePause ? await state.devicePause : { success: true };
+            if (!result.success) {
+                state.depth -= 1;
+                if (state.depth === 0)
+                    state.devicePause = undefined;
+                return result;
+            }
+            return result;
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
+    }
+    /** Release one owned pause. The device resume is sent only by the last release and not while an explicit pause is in effect. */
+    async releasePause(pinnedFacade) {
+        try {
+            const facade = pinnedFacade ?? await this.facadePromise;
+            const state = this.pauseStateFor(facade);
+            if (state.depth === 0)
+                return { success: true, details: { resumed: false, reason: "no owned pause" } };
+            state.depth -= 1;
+            if (state.depth > 0)
+                return { success: true, details: { resumed: false, reason: "pause still held by another call" } };
+            state.devicePause = undefined;
+            if (state.explicit)
+                return { success: true, details: { resumed: false, reason: "machine was paused explicitly" } };
+            return await facade.resume();
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
+    }
+    /** `c64_system pause`: stays in effect until an explicit resume, whatever tools acquire or release meanwhile. */
+    async explicitPause(pinnedFacade) {
+        try {
+            const facade = pinnedFacade ?? await this.facadePromise;
+            const state = this.pauseStateFor(facade);
+            if (state.depth > 0 && !state.explicit) {
+                state.explicit = true; // the device is already paused by a running tool call
+                return { success: true, details: { alreadyPaused: true } };
+            }
+            const result = await facade.pause();
+            if (result.success)
+                state.explicit = true;
+            return result;
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
+    }
+    /** `c64_system resume`: clears the explicit pause. While a tool call still holds an owned pause, the device resume is left to its release. */
+    async explicitResume(pinnedFacade) {
+        try {
+            const facade = pinnedFacade ?? await this.facadePromise;
+            const state = this.pauseStateFor(facade);
+            state.explicit = false;
+            if (state.depth > 0)
+                return { success: true, details: { resumed: false, reason: "a running tool call still holds a pause; it resumes the machine when it finishes" } };
+            return await facade.resume();
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
+    }
     async poweroff() {
         try {
             const facade = await this.facadePromise;
-            return await facade.poweroff();
+            const result = await facade.poweroff();
+            if (result.success)
+                this.clearExplicitPause(facade);
+            return result;
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    /**
+     * A reset, reboot, power-off or power cycle restarts the CPU, so an explicit
+     * `c64_system pause` no longer holds. Without clearing the flag, later tool
+     * calls would skip their own pause and read or write a running machine.
+     */
+    clearExplicitPause(facade) {
+        this.pauseStateFor(facade).explicit = false;
+    }
     /**
      * Start from a clean machine state. C64U/U64 firmware exposes this only in
      * the Tool Menu; U2-family firmware uses its equivalent REST reboot and
      * VICE is restarted when it is managed by c64bridge.
      */
     async powerCycle() {
+        let facade;
+        try {
+            facade = await this.facadePromise;
+        }
+        catch {
+            facade = undefined;
+        }
+        const result = await this.powerCycleActiveBackend();
+        if (result.success && facade)
+            this.clearExplicitPause(facade);
+        return result;
+    }
+    async powerCycleActiveBackend() {
         let menuOpened = false;
         let cleanup;
         let pinnedFacade;
@@ -1212,28 +1366,28 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async configLoadFromFlash() {
+    async configLoadFromFlash(category) {
         try {
             const facade = await this.facadePromise;
-            return await facade.configLoadFromFlash();
+            return await facade.configLoadFromFlash(category);
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async configSaveToFlash() {
+    async configSaveToFlash(category) {
         try {
             const facade = await this.facadePromise;
-            return await facade.configSaveToFlash();
+            return await facade.configSaveToFlash(category);
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async configResetToDefault() {
+    async configResetToDefault(category) {
         try {
             const facade = await this.facadePromise;
-            return await facade.configResetToDefault();
+            return await facade.configResetToDefault(category);
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
@@ -1328,10 +1482,28 @@ export class C64Client {
             return { backend: "c64u", frames };
         }
         const host = new URL(this.baseUrl).hostname;
-        const bindAddress = await this.resolveLocalCaptureAddress(host);
+        const { bindAddress, acceptsSource } = await this.resolveCaptureEndpoint(host);
         const socket = createSocket("udp4");
         const packets = [];
         let stopError = null;
+        let captureFailed = false;
+        let stopped = false;
+        // Stops the stream once. A failure is reported as a warning (success path)
+        // or as a diagnostic (failure path); it never replaces the capture outcome.
+        const stopOneShotVideoStream = async () => {
+            if (stopped)
+                return {};
+            stopped = true;
+            try {
+                await this.ensureStreamSuccess(await facade.streamStop("video"), "stop video stream");
+                return {};
+            }
+            catch (error) {
+                stopError = error instanceof Error ? error : new Error(String(error));
+                writeDiagnosticEvent("video_capture_stop_failed", { error: this.normaliseError(stopError) });
+                return { warnings: [`Video stream stop failed after the capture: ${stopError.message}`] };
+            }
+        };
         try {
             await this.bindCaptureSocket(socket, bindAddress);
             const target = this.socketEndpoint(socket, bindAddress);
@@ -1341,7 +1513,9 @@ export class C64Client {
                 const timer = setTimeout(() => {
                     reject(new Error(`Timed out after ${timeoutMs}ms while capturing ${count} video frame(s)`));
                 }, timeoutMs);
-                socket.on("message", (msg) => {
+                socket.on("message", (msg, rinfo) => {
+                    if (!acceptsSource(rinfo.address))
+                        return;
                     try {
                         const packet = this.parseVideoPacketOrNull(Buffer.from(msg));
                         if (!packet) {
@@ -1364,19 +1538,18 @@ export class C64Client {
                     reject(error);
                 });
             });
-            return { backend: "c64u", frames };
+            return { backend: "c64u", frames, ...(await stopOneShotVideoStream()) };
+        }
+        catch (error) {
+            captureFailed = true;
+            throw error;
         }
         finally {
-            try {
-                await this.ensureStreamSuccess(await facade.streamStop("video"), "stop video stream");
-            }
-            catch (error) {
-                stopError = error instanceof Error ? error : new Error(String(error));
+            if (captureFailed) {
+                // Keep the capture error; the stop failure is only a diagnostic.
+                await stopOneShotVideoStream();
             }
             socket.close();
-            if (stopError) {
-                throw stopError;
-            }
         }
     }
     async ensureC64uVideoCaptureSession(facade) {
@@ -1393,7 +1566,7 @@ export class C64Client {
         }
         await this.stopC64uVideoCaptureSession();
         const host = new URL(this.baseUrl).hostname;
-        const bindAddress = await this.resolveLocalCaptureAddress(host);
+        const { bindAddress, acceptsSource } = await this.resolveCaptureEndpoint(host);
         const socket = createSocket("udp4");
         await this.bindCaptureSocket(socket, bindAddress);
         const target = this.socketEndpoint(socket, bindAddress);
@@ -1408,8 +1581,8 @@ export class C64Client {
             closed: false,
             error: null,
         };
-        socket.on("message", (msg) => {
-            if (session.closed) {
+        socket.on("message", (msg, rinfo) => {
+            if (session.closed || !acceptsSource(rinfo.address)) {
                 return;
             }
             const packet = this.parseVideoPacketOrNull(Buffer.from(msg));
@@ -1561,7 +1734,7 @@ export class C64Client {
     }
     async captureC64uAudioSamples(facade, samplePairs, options) {
         const host = new URL(this.baseUrl).hostname;
-        const bindAddress = await this.resolveLocalCaptureAddress(host);
+        const { bindAddress, acceptsSource } = await this.resolveCaptureEndpoint(host);
         const socket = createSocket("udp4");
         const chunks = [];
         let collectedValues = 0;
@@ -1574,7 +1747,9 @@ export class C64Client {
         let failed = false;
         // The firmware can emit UDP before its REST response reaches us. Listen
         // before starting, and cap collection even while start/config/stop requests are pending.
-        const onMessage = (msg) => {
+        const onMessage = (msg, rinfo) => {
+            if (!acceptsSource(rinfo.address))
+                return;
             if (captureSettled || captureError || collectedValues >= neededValues)
                 return;
             try {
@@ -1678,7 +1853,31 @@ export class C64Client {
         }
         return C64U_PAL_AUDIO_SAMPLE_RATE;
     }
-    async resolveLocalCaptureAddress(remoteHost) {
+    /**
+     * Local address to bind the capture socket to, and a filter that accepts UDP
+     * packets only from the device. The device host is resolved once here. A
+     * device on loopback (the mock) is reached and heard on loopback.
+     */
+    async resolveCaptureEndpoint(remoteHost) {
+        const loopback = isLoopbackHost(remoteHost);
+        let deviceAddresses;
+        try {
+            const resolved = await lookup(remoteHost, { all: true, family: 4 });
+            deviceAddresses = resolved.map((entry) => entry.address);
+        }
+        catch (error) {
+            if (!loopback) {
+                throw new Error(`Cannot resolve the device host '${remoteHost}' to an IPv4 address for stream capture: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            deviceAddresses = ["127.0.0.1"];
+        }
+        const deviceIsLoopback = loopback || deviceAddresses.every((address) => address.startsWith("127."));
+        const acceptsSource = (address) => deviceIsLoopback
+            ? address.startsWith("127.")
+            : deviceAddresses.includes(address.replace(/^::ffff:/i, ""));
+        return { bindAddress: await this.resolveLocalCaptureAddress(remoteHost, deviceIsLoopback), acceptsSource };
+    }
+    async resolveLocalCaptureAddress(remoteHost, deviceIsLoopback = isLoopbackHost(remoteHost)) {
         const socket = createSocket("udp4");
         try {
             await new Promise((resolve, reject) => {
@@ -1694,12 +1893,16 @@ export class C64Client {
             }
         }
         catch {
-            // Fall back below.
+            // Handled below.
         }
         finally {
             socket.close();
         }
-        return "127.0.0.1";
+        // Falling back to loopback would tell the device to stream to itself, and
+        // the caller would only see a capture timeout.
+        if (deviceIsLoopback)
+            return "127.0.0.1";
+        throw new Error(`Cannot find a local network address that reaches the device at ${remoteHost}; the stream target must be an address the device can send to. Check the network route to the device.`);
     }
     async bindCaptureSocket(socket, bindAddress) {
         await new Promise((resolve, reject) => {
@@ -2177,38 +2380,13 @@ export class C64Client {
         if (typeof value !== "string") {
             throw new Error("Expected string input");
         }
-        const trimmed = value.trim();
-        if (trimmed.length === 0) {
+        if (value.trim().length === 0) {
             throw new Error("Empty numeric value");
         }
-        const lower = trimmed.toLowerCase();
-        let radix = 10;
-        let literal = lower;
-        let pattern;
-        if (lower.startsWith("$")) {
-            radix = 16;
-            literal = lower.slice(1);
-            pattern = /^[0-9a-f]+$/;
-        }
-        else if (lower.startsWith("0x")) {
-            radix = 16;
-            literal = lower.slice(2);
-            pattern = /^[0-9a-f]+$/;
-        }
-        else if (lower.startsWith("%")) {
-            radix = 2;
-            literal = lower.slice(1);
-            pattern = /^[01]+$/;
-        }
-        else {
-            pattern = /^[0-9]+$/;
-        }
-        if (!pattern.test(literal)) {
-            throw new Error(`Unable to parse numeric value "${value}"`);
-        }
-        const parsed = Number.parseInt(literal, radix);
-        if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
-            throw new Error(`Unable to parse numeric value "${value}"`);
+        const parsed = parseNumericLiteral(value);
+        if (parsed === undefined) {
+            assertNotBareHex(value);
+            throw new ToolValidationError(`Unable to parse numeric value "${value}"`);
         }
         return parsed;
     }