c64bridge 1.0.0 → 1.0.2

package/dist/vice/viceClient.js

@@ -53,6 +53,8 @@ export class ViceClient {
     }
     rejectAllPending(reason) {
         for (const [, pending] of this.pending) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
             try {
                 pending.reject(reason);
             }
@@ -66,7 +68,7 @@ export class ViceClient {
         // Frame: [0]=0x02, [1]=0x02, [2..5]=len, [6]=respType, [7]=err, [8..11]=reqId, [12..]=body
         while (this.buffer.length >= 12) {
             if (this.buffer[0] !== 0x02 || this.buffer[1] !== 0x02) {
-                const idx = this.buffer.indexOf(0x02, 1);
+                const idx = this.buffer.indexOf(Buffer.from([0x02, 0x02]), 1);
                 this.buffer = idx === -1 ? Buffer.alloc(0) : this.buffer.subarray(idx);
                 continue;
             }
@@ -88,6 +90,8 @@ export class ViceClient {
                 continue;
             }
             if (err !== 0x00) {
+                if (pending.timer)
+                    clearTimeout(pending.timer);
                 pending.reject(new Error(`BM error 0x${err.toString(16)}`));
                 this.pending.delete(reqId);
                 continue;
@@ -98,6 +102,8 @@ export class ViceClient {
                         pending.onFrame(responseType, frame);
                     }
                     catch (error) {
+                        if (pending.timer)
+                            clearTimeout(pending.timer);
                         pending.reject(error);
                         this.pending.delete(reqId);
                     }
@@ -108,6 +114,8 @@ export class ViceClient {
                 continue;
             }
             pending.resolve(frame);
+            if (pending.timer)
+                clearTimeout(pending.timer);
             this.pending.delete(reqId);
         }
     }
@@ -115,7 +123,10 @@ export class ViceClient {
         if (!this.socket || this.socket.destroyed) {
             return Promise.reject(new Error("VICE monitor socket is not connected"));
         }
-        const reqId = this.nextReqId++;
+        if (this.nextReqId === 0xffffffff) { // Reserved for unsolicited events (see onData above); skip it on wraparound.
+            this.nextReqId = 0;
+        }
+        const reqId = this.nextReqId++ >>> 0;
         const payload = body ?? Buffer.alloc(0);
         const header = Buffer.alloc(11);
         header[0] = 0x02; // STX
@@ -126,12 +137,20 @@ export class ViceClient {
         const packet = Buffer.concat([header, payload]);
         const expectedCmd = options?.responseType ?? cmd;
         const promise = new Promise((resolve, reject) => {
-            this.pending.set(reqId, {
+            const pending = {
                 cmd: expectedCmd,
                 resolve,
                 reject,
                 onFrame: options?.onFrame,
-            });
+            };
+            const timeoutMs = options?.timeoutMs ?? (cmd === 0x84 ? 30000 : 10000);
+            pending.timer = setTimeout(() => {
+                if (!this.pending.delete(reqId))
+                    return;
+                reject(new Error(`VICE monitor request 0x${cmd.toString(16)} timed out after ${timeoutMs}ms`));
+                this.socket?.destroy();
+            }, timeoutMs);
+            this.pending.set(reqId, pending);
         });
         this.socket.write(packet);
         return promise;
@@ -178,6 +197,13 @@ export class ViceClient {
         const body = Buffer.concat([Buffer.from([bytes.length & 0xff]), bytes]);
         await this.send(0x72, body);
     }
+    /** Set the VICE joyport's active-low control byte (BM command 0xA2). */
+    async joyportSet(port, activeLowMask) {
+        const body = Buffer.alloc(4);
+        body.writeUInt16LE(port, 0);
+        body.writeUInt16LE(activeLowMask & 0xff, 2);
+        await this.send(0xA2, body);
+    }
     async checkpointGet(id) {
         const body = Buffer.alloc(4);
         body.writeUInt32LE(id >>> 0, 0);
@@ -189,8 +215,11 @@ export class ViceClient {
         const end = (options.end ?? options.start) & 0xffff;
         const stop = options.stopOnHit !== false;
         const enabled = options.enabled !== false;
-        const ops = options.operations ?? { execute: true };
-        const mask = (ops.load ? 0x01 : 0) | (ops.store ? 0x02 : 0) | (ops.execute === false ? 0 : 0x04);
+        const ops = options.operations;
+        const hasExplicitOperation = ops && (ops.load !== undefined || ops.store !== undefined || ops.execute !== undefined);
+        const mask = hasExplicitOperation
+            ? ((ops?.load ? 0x01 : 0) | (ops?.store ? 0x02 : 0) | (ops?.execute ? 0x04 : 0))
+            : 0x04;
         const temporary = options.temporary === true;
         const memspace = options.memspace ?? 0;
         const hasMemspace = options.memspace !== undefined;

package/doc/reviews/hardening/01-fable/prompt-handover.md

@@ -0,0 +1,125 @@
+# Hardening 01 — handover: finish the poll-truthfulness fix, then adversarially review and land the branch
+
+Repository: `/home/chris/dev/c64/c64bridge`
+Branch: `fix/hardening` (already pushed once as PR #143, previously brought to a green/merge-ready state)
+This file: `doc/reviews/hardening/01-fable/prompt-handover.md`
+
+This is a handover from a session that (1) got PR #143 to a fully green, merge-ready state addressing five Kilo Code review comments and raising patch coverage to ~96%, then (2) at the user's request, ran **real physical hardware tests** (C64U, Ultimate 64, Ultimate II+L) against the live MCP server, and (3) found a genuine, reproducible false-success bug during that testing. A fix is in progress but not finished, verified, or committed. You are picking this up cold — there is no prior conversation for you to recall.
+
+Do not consider this session's work "done" until Part 3's exit criteria are met. Do not claim completion while any part below remains unresolved.
+
+## Part 0 — Orient yourself first
+
+1. Read `AGENTS.md` in full.
+2. Read `doc/reviews/hardening/01-fable/review.md` and `doc/reviews/hardening/01-fable/prompt.md` for the original 35-finding hardening context (HARD01-001..035) — this branch already implements all of them, plus five follow-up fixes from a Kilo Code automated review round, plus coverage work. That prior work is committed (`git log --oneline` back to `cfb7e4a`). Nothing in that history needs redoing.
+3. Run `git status` and `git diff --stat` to see the exact uncommitted state you're inheriting (summarized precisely in Part 1 below — but verify it yourself, the working tree may have drifted).
+4. Check `gh pr view 143 --repo chrisgleissner/c64bridge` and `gh pr checks 143 --repo chrisgleissner/c64bridge` for the PR's current state. As of this handover, PR #143 is green and all prior review threads are resolved — the uncommitted work described below is a **new, additional** round on top of that.
+
+## Background: what real-hardware testing found
+
+The session tested the live MCP server against three genuinely separate physical devices (confirmed via distinct firmware `unique_id`s):
+
+- **C64U** — hostname `c64u`, product "C64 Ultimate", firmware 1.2.0.
+- **Ultimate 64 Elite** — hostname `u64`, firmware 3.15. Fully independent hardware (its own board), but uses the same `c64u` backend profile/config key as C64U (same REST API family). The c64bridge config format has exactly one `c64u` slot, and the running server caches whichever host was resolved into it the first time that backend is constructed in a process — editing `.c64bridge.json` and re-selecting the backend does **not** retarget an already-constructed facade. To test C64U and U64 as genuinely separate live connections, the session registered a second temporary MCP server entry, `c64bridge-u64`, in `.mcp.json`, pointed at a separate config file (`C64BRIDGE_CONFIG` env var) with `c64u.host = "u64"`. That second server entry is a legitimate, intentional part of the current uncommitted `.mcp.json` diff — keep it (or ask the user before removing it) rather than reverting it as accidental drift.
+- **Ultimate II+L (U2)** — hostname `u2`, firmware 3.15. Physically a cartridge plugged into the back of the C64U unit — separately networked (own IP), but shares the same underlying simulated C64 bus/CPU/screen as the C64U it's plugged into. **Never drive `c64u` and `u2` operations concurrently** — they are electrically the same target machine. U64 is fully independent and safe to run alongside either.
+
+Targeted verification (firmware `errors[]` truthfulness, drive-list shape, real ASM execution, `power_cycle` honesty) passed cleanly on **C64U and U64**. On **U2**, `upload_run_basic` / `upload_run_asm` reported `success: true, verified: true` while the program **never actually executed** — confirmed independently by bypassing the MCP client entirely and sending raw HTTP `POST /v1/runners:run_prg` requests directly to the device in both `application/octet-stream` and `multipart/form-data` encodings (matching the OpenAPI spec exactly). The U2 firmware returns `200 {"errors": []}` but memory at `$0801` never changes and the screen never advances past the boot banner. This was cross-checked against the *same* physical machine via the C64U side (which genuinely does execute, visible through the shared screen) — so it is a real gap in the U2 cartridge's own firmware implementation of the upload-and-run REST feature, **not** a client-side bug. That part needs no further code change; it's a hardware/firmware limitation to document, not fix.
+
+**What is a fixable bug**, independent of the U2 firmware issue: `pollBasicOutcome()` / `pollAsmOutcome()` in `src/tools/pollValidator.ts` were blindly reporting success whenever the literal text "RUN" or "ERROR" never appeared on screen within the poll window. Since `upload_run_basic` / `upload_run_asm` execute via the native REST `run_prg` endpoint (or a typed `SYS<entry>` command for ASM) rather than a user visibly typing `RUN`, this fallback was structurally unable to provide a real signal — it happened to look correct on C64U/U64 only because execution there also happens to produce visible screen text (a KERNAL LOAD/RUN echo) for unrelated reasons. On U2, where nothing executes at all, the same fallback silently laundered a real failure into a false `verified: true`. This is exactly the class of bug the original 35 HARD01 findings targeted, just not one of them by number — a natural HARD01-036 in spirit, though nothing in code should assume that ID is registered anywhere; use it only as a descriptive tag if useful (as already done in the new tests, see below).
+
+## Part 1 — Finish the in-progress fix (do this first)
+
+### 1a. Fix already applied to `src/tools/pollValidator.ts` — verify, don't redo
+
+- `pollBasicOutcome`: previously always fell through to `return { status: "ok", type: "BASIC" }` after the poll window if no BASIC error text was ever seen, regardless of whether `runDetected` was ever set. Now, if `runDetected` is still `false` after the full poll window, it returns `{ status: "error", type: "BASIC", message: "No execution activity detected: the firmware reported success, but the program does not appear to have run." }` instead.
+- `pollAsmOutcome`: previously returned `{ status: "ok", type: "ASM" }` immediately if `runDetected` was never set, **skipping** the hardware liveness check (screen-RAM CRC comparison) entirely. That early return is removed — execution now always falls through to the liveness check regardless of whether "RUN"/"ERROR" text was ever seen. Only the two log lines and a comment changed around this; the liveness-check logic itself (already correct, from the original HARD01-019/020 work) is untouched.
+
+Confirm this is still exactly what's in the working tree (`git diff src/tools/pollValidator.ts`) before proceeding — do not re-derive it from scratch, but do sanity-check it against the description above.
+
+### 1b. Test updates already applied — verify, don't redo
+
+`test/pollValidator.test.mjs`:
+- Two tests that previously *encoded the bug as correct behavior* — `"pollForProgramOutcome BASIC returns ok if RUN not detected"` and `"pollForProgramOutcome ASM returns ok if RUN not detected"` (both used a mock whose `readScreen()` always returns `"READY.\n"` forever, and asserted `status: "ok"`) — were renamed and fixed to assert the corrected behavior: `"HARD01-036 pollForProgramOutcome BASIC reports an error instead of blind success when RUN is never detected"` (asserts `status: "error"`, message matches `/does not appear to have run/i`) and `"HARD01-036 pollForProgramOutcome ASM reports crashed instead of blind success when RUN is never detected"` (asserts `status: "crashed"`, `reason: "no program-visible screen progression within window"`).
+- A new positive-case test was added, `"HARD01-036 pollForProgramOutcome ASM still detects real liveness even when RUN text never appears"`, confirming the fix doesn't regress the case where RUN/ERROR text never shows but screen RAM genuinely changes (must still report `ok`).
+
+`test/programRunnersModule.test.mjs`:
+- `"upload_run_basic verify true annotates metadata"`: mock's `readScreen()` previously always returned `"READY.\n"`; now returns `"READY.\n"` on the first call (the tool's own pre-poll screen check) and `"RUN\n"` thereafter (matching how a real backend's LOAD/RUN echo actually behaves), so the poll genuinely observes execution instead of relying on the old blind-success fallback.
+- `"upload_run_basic verify tolerates repeated screen read failures"`: mock's `readScreen()` previously threw on *every* call, and the test asserted success. That was itself an instance of the bug (permanent failure ≠ "tolerated" success). Now the mock throws only on the first 3 calls, then returns `"RUN\n"` — genuinely testing transient-failure tolerance, not permanent-failure-as-success.
+- `"upload_run_asm returns structured content on success"`: the mock previously had no `readScreen`/`readMemoryRaw` at all (relying on the old shortcut to skip verification entirely, even though `executeUploadRunAsm` calls `pollForProgramOutcome` unconditionally regardless of the `verify` flag). Now includes a minimal `readScreen` (`"RUN\n"`) and `readMemoryRaw` (returns a changing byte pattern) so the now-mandatory liveness check has something real to observe.
+- `"upload_run_asm verify treats repeated screen read failures as instant execution"` — this test's *name* literally described the bug as a feature. Renamed to `"upload_run_asm verify tolerates transient screen read failures and still verifies via liveness"` and its mock changed from permanent to transient (3) failures followed by success, mirroring the BASIC fix above.
+
+Confirm `test/pollValidator.test.mjs` and `test/programRunnersModule.test.mjs` diffs match this description; run `timeout 120 node scripts/run-tests.mjs test/pollValidator.test.mjs test/programRunnersModule.test.mjs test/groupedToolsShims.test.mjs` and confirm all green (96/96 in the second file, 22/22 in the first, as of last check).
+
+### 1c. Leftover test artifacts already cleaned up — verify, don't redo
+
+The hardware-testing session had left two untracked scratch files in the repo root — `.c64bridge.json` (containing `{"u2": {"host": "u2", "port": 80}}`) and `.c64bridge.u64.json`. These were interfering with `test/device.test.mjs`'s `"falls back to vice or c64u when no config"` test via `config.ts`'s "legacy package-adjacent config" fallback candidate (`dirname(import.meta.url of config.ts)/../.c64bridge.json`), which resolves relative to the *source file location*, not `process.cwd()` — so it bypasses that test's directory-isolation helper (`withConfigScenario`) entirely. Both files have already been deleted. Run `git status --porcelain` and confirm neither file is present; if either has reappeared (e.g. from a stray tool run), delete it again before running the full suite — it will cause spurious, hard-to-diagnose failures in `device.test.mjs` and possibly elsewhere.
+
+### 1d. NOT yet fixed — this is the actual remaining work
+
+`scripts/mockC64Server.mjs` was modified to make the C64U mock server's simulated `injectKeyboardQueue` path (used by `upload_run_asm`'s typed `SYS<entry>` trigger) produce *some* observable screen-RAM change, since the mock runs no real 6502 code and the now-mandatory liveness check in `pollAsmOutcome` needs something to observe. The current approach: `simulateKeyboardDrain()` (which already existed, to drain the KERNAL NDX counter) now also detects when the queued/typed text matches `/SYS\s*\d+/i` and, if so, starts a `setInterval` "heartbeat" that increments `state.memory[0x0400]` every 20ms for up to 50 ticks (~1 second), simulating an alive, still-running program.
+
+**This introduced a real regression**: the heartbeat is a background timer with no cleanup tied to test boundaries. Because `test/c64Client.test.mjs` shares one mock server/client instance across many sequential `t.test()` subtests (no `resetState()`/reset call between them), an *earlier* subtest in that file — `"HARD01-018 uploadAndRunAsm loads the assembled PRG..."` (around line 456) or `"HARD01-018 uploadAndRunAsm keeps a non-$0801 origin intact..."` (around line 475), both of which trigger a `SYS...` pattern — leaves a heartbeat ticking for up to a second. A *later*, unrelated subtest a few lines down, `"readMemory returns hex string with prefix"` (around line 506), which expects to read back the exact bytes (`$AA55`) written by the immediately-preceding `"writeMemory writes bytes to mock memory"` subtest, instead observes `$AB55` — the first byte has been incremented by exactly 1 by the still-running heartbeat from the earlier subtest. Confirmed via direct code inspection; not yet re-confirmed by test run after the last edit (the fix attempt was mid-flight when this handover was written — you may find it still fails, or fails intermittently depending on timing).
+
+**Fix this properly before doing anything else.** Suggested directions, roughly in order of robustness (pick one, don't feel obligated to preserve the current heartbeat mechanism if a cleaner design fits better):
+
+1. **Time-computed overlay instead of a live timer (recommended).** Instead of a `setInterval` that mutates `state.memory` in the background, record `state.heartbeat = { startedAt: Date.now(), durationMs, baseValue }` when a `SYS` command is detected, and have the `machine:readmem` handler (or wherever `$0400` reads are served) compute a *synthetic* byte value on read — e.g. `baseValue + Math.floor((Date.now() - startedAt) / 20) & 0xff` — only while `Date.now() - startedAt < durationMs`, otherwise return the real stored byte. This eliminates all background timers and the cross-test leakage entirely: nothing mutates `state.memory` asynchronously, so an unrelated `writeMemory`/`readMemory` pair immediately after a `SYS`-triggering subtest is unaffected (the overlay only applies to reads of that specific address, and only while a window is "active" for a specific triggering event — consider whether the overlay should apply narrowly enough that a real write to `$0400` by a later subtest correctly overrides/disables it, e.g. by clearing `state.heartbeat` on any explicit write to that address).
+2. **Track and clear timers explicitly.** Keep the `setInterval` approach, but store the active heartbeat handle in `state` (e.g. `state.activeHeartbeat`), clear any previous one before starting a new one, and clear it in `resetState()`. This only fully solves leakage across resets — it does **not** solve leakage between sequential subtests in the *same* file that never call reset (the actual failure mode observed), so this alone is likely insufficient without also auditing whether `t.test()` sequences in shared-client test files should call `mock.reset()` between subtests (check `test/c64Client.test.mjs`'s setup/teardown and `test/helpers/mcpTestHarness.mjs`'s `withSharedMcpClient` for whether that's feasible without breaking other assumptions).
+3. **Shrink the blast radius.** If you keep a live timer, drastically shorten its duration (a handful of ticks over ~40-60ms) so it's very unlikely to outlive the specific subtest that triggered it, while remaining long enough to intersect the poll windows used by tests that override `C64BRIDGE_POLL_MAX_MS`/`C64BRIDGE_POLL_INTERVAL_MS` (values as low as `maxMs: 50, intervalMs: 10` appear in the test suite — check the *smallest* configured poll window across all callers before picking a duration, not just the ones you happen to be looking at). This is the least robust option and only worth using if 1 and 2 both prove impractical.
+
+Whichever approach you take, the fix must satisfy **all** of:
+- `test/suites/mcpServerCallToolSuite.mjs`'s `"c64_program upload_run_asm assembles source and runs program"` test passes reliably (run it standalone at least 10 times in a loop to rule out flakiness, not just once).
+- `test/c64Client.test.mjs` passes with no cross-subtest interference (run the whole file standalone, and also as part of the full suite — the earlier failure only manifested in the full-suite/whole-file run, not a single-test run, so isolated single-test passes are not sufficient evidence).
+- No new timer/interval leaks the Node/Bun process past test completion (check for "open handle" warnings if your test runner surfaces them).
+- The underlying simulation stays scoped to the `SYS`-command pattern specifically — `injectKeyboardQueue` is also used by `src/tools/input.ts` for general `key`/`write_text` operations, and those must not trigger this heartbeat/overlay behavior.
+
+After fixing, `timeout 300 npm test` must show **0 failures** across the entire suite (as of last check before the mock-server regression, the count was 792 tests / 788 pass / 2 skip / 0 fail with the pollValidator fix alone, before the mock-server change was introduced — use that as your target, adjusting only for whatever new tests you may have added).
+
+### 1e. Full validation gate for Part 1
+
+Once the full suite is green, run the complete validation gate used earlier in this branch's history (see recent commits `ad93c5d`, `417ec89` for the pattern):
+
+```
+npx tsc -p tsconfig.json --noEmit
+npm test
+npm run test:vice:mock
+npm run build
+npm run check:package
+git diff --check
+```
+
+All must pass cleanly. `npm run build` regenerates `mcp/*.json` and `README.md` from source/schema — if those come out changed, that's expected only if you touched schemas; otherwise investigate rather than blindly committing a diff you don't understand.
+
+Also reconsider **patch coverage**: this branch has an established pattern (see commit `ad93c5d`'s message and `.mcp.json`-adjacent `codecov.yml`) of keeping patch coverage above ~94% by, among other things, moving standalone explanatory comments onto the code line they document as trailing comments (since this project's bun-based coverage tooling counts every comment/blank line in a diff hunk as an uncovered patch line). Apply the same discipline to your new diff if it introduces many multi-line comments in changed regions — it's cheap and keeps the codecov gate comfortably clear.
+
+## Part 2 — Adversarial review of the current branch
+
+Once Part 1 is fully green and validated (but not yet committed — or committed as a checkpoint if you prefer smaller commits, your call), perform a genuinely adversarial review of the **entire branch diff against `main`** (i.e. `git diff main...HEAD` plus your uncommitted changes) — not just the new pollValidator/mock-server work. This branch has already been through one automated review round (Kilo Code, five findings, all fixed) and one round of real-hardware testing (which is what surfaced the bug you just fixed) — the goal now is to find what *those* rounds missed, not to re-litigate what they already caught.
+
+Use whichever of these fits best; you have access to the same skills this session had available:
+- `/codex challenge` — adversarial mode specifically designed to try to break the code. Well-suited to this task by name; consider using it as a first pass.
+- `/review` or `/code-review` — structural pre-landing review (SQL safety, trust-boundary violations, conditional side effects, simplification opportunities).
+- Manual review, if you prefer full control or the automated tools are unavailable in your environment.
+
+Focus areas, in rough priority order:
+
+1. **The same bug class elsewhere.** The pollValidator bug was "assume success when a specific text signal never appears, without checking whether that signal was ever achievable for this code path." Grep the codebase for similar patterns — any other poller, verifier, or "wait for X then assume success" loop that has a fallback branch reachable when X structurally cannot occur for some valid code path. `src/tools/programRunners.ts`, `src/c64Client.ts`, and `src/device.ts` are the highest-yield places to look, given they're where the original HARD01-011/018/019/020/021 truthfulness fixes lived.
+2. **The mock-server fidelity gap you just fixed, generalized.** If `scripts/mockC64Server.mjs` didn't simulate keyboard-queue-triggered execution at all before your fix, ask whether other mock behaviors (in this file or `src/vice/mockServer.ts`) are similarly "accepts the request, does nothing, returns success" in ways that could mask a real truthfulness bug the same way the U2 firmware gap did. You don't need to fix speculative gaps, but flag anything concrete you find.
+3. **Standard security review**: command injection, path traversal (especially around `src/tools/meta/filesystem.ts`, `src/tools/storage.ts`, and anywhere device filesystem paths are constructed — HARD01-010's fix should already cover segment encoding, but re-verify it holds against the newest code), credential/secret handling (HARD01-024's redaction — re-verify it's applied everywhere new logging was added, if any), and any newly-introduced regex (the `SYS_COMMAND_PATTERN` you may still be touching in Part 1) for ReDoS risk given it's small and simple but worth a two-second glance.
+4. **Test-suite integrity**: any other test in the suite that, like the two `programRunnersModule.test.mjs` tests you fixed, encodes a *bug* as expected behavior rather than a genuine requirement. This is a real, demonstrated pattern in this codebase now (found twice in one session) — worth a deliberate second pass rather than assuming it was fully exhausted.
+5. **The `.mcp.json` `c64bridge-u64` addition**: confirm it doesn't leak the hardware hostname `u64` or any credentials into anything that shouldn't have it (it shouldn't — no password was configured for these devices — but verify), and that it's harmless if a reader without access to that hardware tries to use this repo (the server entry will simply fail to connect, not error out the whole MCP client setup — confirm this assumption is actually true rather than taking it on faith).
+
+## Part 3 — Fix all findings, then land the branch
+
+Fix everything Part 2 surfaces, following the same discipline as the rest of this branch: minimal, root-cause fixes; a regression test for anything that was a real bug; no speculative refactors. Re-run the full Part 1e validation gate after every batch of fixes.
+
+**Exit criteria — do not stop before all of these are true:**
+
+1. `git status` is clean except for intentional, understood changes.
+2. Full validation gate (Part 1e) passes with zero failures.
+3. Changes are committed with a clear message (follow this branch's existing commit style — see `git log --oneline` — imperative, `fix:`/`test:`-prefixed, explaining *why* not just *what*).
+4. Commits are pushed to `fix/hardening` on the `chrisgleissner/c64bridge` remote.
+5. `gh pr checks 143 --repo chrisgleissner/c64bridge` shows every check green, including `codecov/patch` and `codecov/project`.
+6. If your adversarial review or the push triggers new automated review comments (Kilo Code or otherwise) on PR #143, address every one — reply explaining the fix (or the reasoning if not applicable) and resolve the thread via the GitHub API, exactly as was done for the five Kilo Code findings earlier in this PR's history (see commit `ad93c5d` and its PR comment replies for the established pattern: reply via `gh api repos/chrisgleissner/c64bridge/pulls/143/comments/{id}/replies`, resolve via the GraphQL `resolveReviewThread` mutation).
+7. No unresolved review threads remain on PR #143.
+
+Only once all seven are true is this work complete. Report back with: a summary of what the mock-server fix ended up being, what the adversarial review found (if anything) and how it was fixed, confirmation of the exit criteria, and the final CI/PR status.

package/doc/reviews/hardening/01-fable/prompt.md

@@ -0,0 +1,98 @@
+# Hardening 01 implementation
+
+Repository: `/home/chris/dev/c64/c64bridge`
+
+Implement every confirmed finding in [review.md](./review.md): **HARD01-001 through HARD01-035**. This is an implementation task, not a second review. The review's executive-summary/count prose is stale in places; the findings index and detailed findings are authoritative. Do not omit a finding because it is P3, Medium confidence, or shares a file with another finding.
+
+## Outcome
+
+Deliver a coherent, production-safe hardening change that eliminates the false-success, wrong-target, lifecycle, input, file-system, SID, and packaging failures described in the review. Preserve the public MCP contract except where an existing success result is demonstrably false; in those cases, return a clear failure with actionable details. Add focused automated regression tests for every finding, update generated artifacts only when the source/contract change requires it, and leave the working tree with all relevant checks passing.
+
+Do not perform state-changing operations against real Ultimate hardware. Use unit tests, mock Ultimate HTTP servers, Binary Monitor stubs, and managed VICE only where the repository's existing test setup makes that safe and deterministic. Do not expose passwords or other secrets in logs, tests, fixtures, errors, or documentation.
+
+## Start correctly
+
+1. Read `AGENTS.md` and the entire adjacent `review.md` before editing. Follow the repository's `.github/skills/*/SKILL.md` instructions for any C64 execution workflow. In particular, read `c64://vice/binary-monitor-spec`/`doc/vice/vice-binary-monitor-spec.md` before changing VICE monitor framing or commands.
+2. Inspect the existing test conventions, package scripts, generated-artifact workflow, public MCP schemas, and call sites before changing result shapes or shared facade APIs.
+3. Keep changes narrow but solve root causes. Do not paper over a failure with logging, an unchecked cast, a longer timeout, or a test-only special case.
+4. Work in logical batches, but run targeted tests after each batch and the complete relevant suite before handoff. Do not claim hardware validation unless it was actually performed with explicit authorization.
+
+## Cross-cutting implementation rules
+
+- Treat Ultimate REST responses as unsuccessful when their JSON `errors` array is non-empty, even when HTTP status is 2xx. Preserve the firmware error strings in structured details. Missing `errors` remains compatible success.
+- Pin backend/facade identity for the full lifetime of a tool invocation and any spawned work. A backend switch may affect later invocations but must never retarget an operation already underway.
+- Never silently drop input, swallow a failed state-restoration operation, or report a physical action as verified when the required state cannot be observed. Report uncertainty/failure explicitly and include recovery guidance where useful.
+- Keep monitor queues and background work cancellable and recoverable. A timeout or shutdown must release subsequent work rather than permanently wedging a backend.
+- Use package-relative paths for assets shipped with the package and process-cwd paths only for deliberately user/project-local inputs. Use `fileURLToPath`, not raw URL pathnames.
+- Validate and contain all user-influenced host filesystem paths after resolution. Never rely solely on string prefix checks that permit sibling-prefix escapes; use `path.relative`/platform-aware containment.
+- Retain backward compatibility deliberately. If a formerly `void` method must signal a timeout, propagate an explicit typed result or error through every caller rather than silently discarding it.
+
+## Required fixes and acceptance criteria
+
+### HTTP transport, configuration, platform status, and package paths
+
+- **HARD01-001:** Make `--http [port]` real, or remove the dead parser/imports and the documented option together. Prefer wiring the existing parsed CLI options to a clearly factored transport-selection path using `StreamableHTTPServerTransport`; retain stdio as the default. Test that `--http 8080` selects/listens on the HTTP path and that default invocation selects stdio. Ensure MCP server/prompt registry wiring is actually used or remove the dead path.
+- **HARD01-004:** Capability probing must not cache a transient error as `unknown`. Cache confirmed availability/unavailability as appropriate, but evict/retry uncertain results. Test failure-once then success.
+- **HARD01-005, HARD01-006, HARD01-027:** Replace divergent configuration loading with one typed, authoritative loader and pass its parsed backend sections to all consumers/facade creation. Candidate precedence must match documented behavior: `C64BRIDGE_CONFIG`, then `process.cwd()/.c64bridge.json`, then home config, then defaults; retain a package-relative legacy fallback only if necessary and document its lower precedence. Resolve home via `os.homedir()` fallback and module paths through `fileURLToPath`. A malformed/unreadable candidate must produce a prominent redacted warning that identifies the file and problem, then continue to the next candidate/defaults rather than crashing or silently disagreeing. Test layered/contradictory configs, project-cwd config under an installed-style foreign package cwd, malformed config fallback, and identical host/port/password selection by startup and facade code.
+- **HARD01-016:** Establish an invocation-scoped backend snapshot/facade lease. Platform gating, all operations in a multi-step tool flow, verification, and background work must use that pinned facade. Make switching atomic with platform publication so no request is gated with one platform and sent to another. Avoid a global lock that deadlocks streams or long-running work; a reference-counted/read lease or a façade captured in tool context is preferable. Add a deterministic concurrent mock-facade test where a slow write/verify is interleaved with `c64_select_backend` and every write/read/resume step remains on the original backend.
+- **HARD01-025:** Resolve all shipped RAG data, docs, embeddings, AGENTS/prompt assets relative to the installed package/module root, not `process.cwd()`. If an override is supported, make it explicit and test it. Do not silently return an empty index merely because a bundled path was calculated incorrectly; surface a useful diagnostic when an expected bundled index cannot load. Test initialization from a foreign cwd.
+- **HARD01-031:** `c64://platform/status` must not block on a normal 10-second live REST probe. Return cached/static/not-yet-probed capability state quickly, or use a bounded short probe that cannot poison the cache. Test a never-resolving probe and assert a prompt resource result within the short bound.
+
+### Ultimate REST, input, physical-state safety, drive shape, and logging
+
+- **HARD01-002 and HARD01-003:** Rework C64U/U64 `power_cycle` to be fail-closed. Before sending final RETURN, positively determine from the menu screen's actual selection/highlight encoding that `POWER CYCLE` is selected; visible text anywhere on screen is insufficient. Confirm firmware color-matrix semantics from repository/device contract and abort on uncertainty. On every post-menu-open failure, make a safe, best-effort, idempotent attempt to close/escape the menu and return cleanup status in failure details. Never report a selected power cycle unless verification succeeds. Test different highlighted rows, all navigation-step failures, no final RETURN on mismatch, and cleanup attempts.
+- **HARD01-009:** Do not overwrite an undrained KERNAL queue. Make keyboard queue injection return a typed completion result or throw a typed timeout/error, then update every input tool call site to report partial/non-delivery accurately. Test a permanently nonzero NDX, assert no subsequent chunk overwrite, and assert the user-visible result is failure rather than success.
+- **HARD01-010:** Encode Ultimate device filesystem paths segment-by-segment so nested slash separators remain separators while special characters in segments are encoded exactly once. Cover leading slash and spaces in an HTTP request-capture test.
+- **HARD01-011:** Centralize `ActionResponse` error-array handling in the C64U/U2 backend; apply it to every action, configuration, drive, program, file, and playback method rather than hand-patching a few call sites. Nonempty `errors` must result in `success: false` and retain useful response details. Mock 200+errors for mount, run, and config operations and assert the MCP/tool layer reports failure.
+- **HARD01-017:** If write verification paused a machine and resume fails, do not let the original write success escape as a clean success. Return/throw a failure that records write/verification outcome, `machinePaused: true`, the resume failure, and clear recovery instructions; an appropriately bounded retry is acceptable. Test return and thrown resume failures.
+- **HARD01-023:** Normalize `drivesList` at the facade boundary into one documented internal shape (at least `id`, `power`, `image`, `type`, plus any needed raw details), for both VICE and Ultimate/U2. Decode the actual Ultimate `{ errors, drives: [{ id: info }] }` response rather than leaking it. Make `drive_mount_and_verify` use that normalized contract and verify the correct image-path/power fields. Test the real firmware-shaped mock response.
+- **HARD01-024:** Redact sensitive HTTP request/response diagnostic metadata case-insensitively before it reaches stderr or diagnostics persistence. At minimum mask `X-Password` and authorization/cookie-equivalent secrets. Test that a known test secret never appears while the header key/placeholder may remain useful for diagnosis.
+- **HARD01-034:** Align printer module runtime gates with advertised U2 capability: support `c64u` and `u2` if device-4 BASIC printing is actually supported by the stated contract, otherwise remove the advertised U2 feature and explain it. The likely intended fix is explicit `supportedPlatforms: ["c64u", "u2"]` on both relevant modules. Add capability/gating coverage.
+
+### VICE monitor, emulator lifecycle, input, and config
+
+- **HARD01-012:** Add per-request Binary Monitor response deadlines that reject, remove the pending request, and reset/destroy the unhealthy socket so the serialized monitor queue always releases. Use a considered timeout policy (normal versus large display transfer if needed), clear timers on response/error/close, and avoid unhandled rejections or request-ID reuse confusion. The parser must preserve framing correctness during resynchronization; do not scan arbitrary payload bytes as a new frame unless the protocol framing permits it. A stub server that accepts but never answers must prove bounded rejection and a subsequent operation must succeed after reconnect.
+- **HARD01-013:** Ensure managed VICE and Xvfb are stopped on normal exit and SIGINT/SIGTERM/SIGHUP. Since async work cannot complete in `exit`, expose/use a synchronous best-effort kill path there; signal handlers should coordinate bounded async shutdown where viable and then exit without recursive/double cleanup. Guard already-exited children. Add tests around registered handlers/child termination and, where reliable in CI, an integration check proving no managed child survives SIGTERM.
+- **HARD01-014:** Implement VICE Binary Monitor `0xA2` Joyport Set from the in-repo spec, including correctly encoded port and active-low control mask. Route VICE joystick press/release/tap through it; do not write CIA data-port registers to simulate input. Test exact BM bytes for press/release/tap and retain C64U physical-input behavior unchanged.
+- **HARD01-015:** Construct checkpoint masks so explicitly provided operations are exactly honored; default to execute only when no load/store/execute flag was requested. Test `{store:true}` serializes `0x02` and other combinations.
+- **HARD01-026:** Make VICE reset/reboot success contingent on `waitForBasicReady`'s required readiness signals. Return structured `success:false` with readiness diagnostics when it does not reach READY; update callers/tests accordingly.
+- **HARD01-035:** Stop coercing values solely because they look numeric. Determine VICE resource type from the monitor/resource API (or add an explicit value type where the public schema supports it) and send a string payload for numeric-looking string resources such as `"1541"`. Test both resource types and batched behavior.
+
+### Program execution, BASIC generation, and validation
+
+- **HARD01-007:** Generate valid Commodore BASIC V2 printer output for strings containing quotes. Do not use doubled quotes. Split expressions and emit `CHR$(34)` (while preserving all other literal characters), maintain line-length/chunking correctness, close the printer channel on normal/error paths where feasible, and ensure the tool does not claim completed printing merely because load/run started. Add generator/tokenizer-level coverage for quoted text and a VICE-facing regression if the suite supports it.
+- **HARD01-008:** Make the PETSCII screen program actually wait for a key without immediately falling through to `READY.`. Use a valid GET loop and preserve intended termination behavior. Test generated source and, if possible, rendered-screen behavior before a key press.
+- **HARD01-018:** Make `upload_run_asm` execute assembled code on every supported backend. Establish one robust contract for entry address and PRG layout: either emit a valid BASIC SYS stub for applicable loads while keeping labels/address accounting correct, or inject/run the PRG then explicitly `SYS` the assembled entry in a backend-safe manner. Do not point VICE BASIC pointers at arbitrary non-BASIC ML. Test the published `$0801` example by observing its intended memory/screen effect and test a non-$0801 origin does not corrupt BASIC workspace. Keep symbol and verification metadata truthful.
+- **HARD01-019 and HARD01-020:** Replace the ASM liveness heuristic so it neither treats free-running VIC/CIA values as activity nor reads side-effectful CIA ICRs on hardware. Prefer program-specific expected effects/explicit verification where supplied; any fallback must restrict reads to side-effect-free addresses, mask volatile registers, and honestly describe its confidence. Test a memory stream differing only at `$D012` as non-alive/crashed and assert hardware polling never overlaps `$DC0D`/`$DD0D` (or the I/O ranges whose reads have side effects).
+- **HARD01-021:** Detect BASIC runtime errors only using actual BASIC error syntax/patterns, not arbitrary occurrences of the word `ERROR`. Test `0 ERRORS FOUND` as successful and a canonical `?SYNTAX ERROR IN 20` as failure.
+
+### Background work, artifacts, and SID playback
+
+- **HARD01-022:** On reload, persisted tasks marked `running` must never remain zombie status. Either safely re-arm them once execution context is available or mark them `interrupted`/`stopped` with a restart explanation; choose and document one deterministic policy. Test persisted reload and task listing/state.
+- **HARD01-028:** Treat resolved `{ success:false }` operation results as failed task iterations, recording `lastError` and truthful status/failure counts. Decide whether retry continues; if it does, make the continued/retry status explicit. Test both thrown and returned failures.
+- **HARD01-029:** Reject unsafe `runId` and all artifact-derived filenames before writing. Resolve the output base and candidate then prove containment with `path.relative`; reject separators, traversal, absolute paths, empty normalized names, and unsafe range components. Test `../escape`, absolute/sibling-prefix escapes, and verify no out-of-tree file is created.
+- **HARD01-030:** Replace detached `music_generate` playback with tracked, cancellable work. Pin its facade/backend at creation, expose an existing-compatible stop/cancel path (integrate with the background task registry or a dedicated playback registry), stop/cancel on shutdown and before/when backend switches according to a documented policy, and do not monopolize VICE's queue beyond individual note operations. Preserve immediate scheduling response only if it truthfully says playback is scheduled/running rather than completed. Test that switching backends cannot redirect later notes and cancellation prevents future writes.
+- **HARD01-032:** Correct every SID frequency formula to the 24-bit phase accumulator: `round(hz * 16777216 / phi2)` with existing valid 16-bit clamp. Update both production implementations and knowledge/spec text, including PAL and NTSC handling. Test A4/PAL is approximately 7493 (`$1D45`) and that note-on writes low/high bytes correctly.
+- **HARD01-033:** Retrigger the SID envelope between generated notes by writing gate-low for an appropriate bounded interval before the next gate-high/note-on. Do not leave a permanently high gate except where an explicit legato contract asks for it. Test register-write sequence includes gate clearing between successive notes.
+
+## Test and validation gate
+
+At a minimum, add/extend automated tests that demonstrate every numbered acceptance criterion above. Group them sensibly (config/path, Ultimate mock HTTP, VICE BM stub/lifecycle, program generation/validation, background/SID), but name cases with the HARD01 IDs or titles so coverage is auditable. Run:
+
+1. formatter/linter/typecheck and the repository's normal test command;
+2. focused tests for every changed subsystem;
+3. package/build and generated-contract checks when applicable;
+4. a final `git diff --check` and review of all changed public schemas/docs/skills.
+
+If an existing test harness cannot safely perform a desired managed-VICE or device-level assertion, retain a deterministic stub/unit test and report the exact unperformed HIL validation as a limitation. Do not weaken a requirement merely because production hardware is unavailable.
+
+## Documentation and handoff
+
+Update docs, generated metadata, schemas, and `.github/skills` only where behavior, supported platform, failure/recovery behavior, or invocation semantics changed. In particular, keep `AGENTS.md`, README/developer docs, platform-status capabilities, and MCP descriptions consistent with the implementation. Do not edit `review.md` to hide findings.
+
+At handoff, provide:
+
+- a concise mapping of HARD01 IDs to the implemented change and tests;
+- commands run and their outcomes;
+- any intentionally deferred hardware-only validation, with reason;
+- an explicit statement that all 35 findings were implemented, or a precise list of any remaining IDs and the blocker. Do not claim completion while any HARD01-001..035 finding remains unresolved.