romdevtools 0.40.2 → 0.42.0

package/src/mcp/tools/watch-memory.js

@@ -17,11 +17,87 @@ import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { getCPUState } from "../../host/cpu-state.js";
-import { MemoryRegionToRetro } from "../../host/types.js";
 import { resolveButtonAlias } from "./input.js";
 import { getCPUStateCore } from "./platform-tools.js";
 import { traceVramSourceCore } from "./trace-vram-source.js";
 import { resolveStatePath } from "./state.js";
+import { buildBacktrace } from "../../analysis/backtrace.js";
+import { mapNesAddress } from "./disasm.js";
+import { MemoryRegionToRetro } from "../../host/types.js";
+
+/**
+ * Build the decoded call stack for a breakpoint hit: who called the routine the
+ * PC is in. Uses the captured register snapshot's stack pointer + the stack RAM.
+ * Returns null when unavailable (unsupported ISA / no regs) — never throws.
+ * @param {import("../../host/index.js").LibretroHost} host
+ * @param {Object|null} regs   the `named` register snapshot (has the stack ptr)
+ */
+function backtraceForHit(host, regs) {
+  if (!regs) return null;
+  const platform = host.status?.platform;
+
+  // 6502: validate the $20 (JSR) opcode at each candidate caller PC by mapping the
+  // CPU address to a ROM byte. NES uses the cart image + the mapper.
+  let readByteAt = null;
+  if (platform === "nes") {
+    try {
+      const cart = host.getCartRom();
+      readByteAt = (cpuAddr) => {
+        try {
+          const { bytes } = mapNesAddress(cart.raw, cpuAddr, 1);
+          return bytes && bytes.length ? bytes[0] : null;
+        } catch { return null; }
+      };
+    } catch { /* no cart / mapping — frames stay best-effort */ }
+  }
+
+  // Z80/SM83 + m68k stacks live in WORK RAM at the SP (not a fixed page). Read the
+  // stack via system_ram using the platform's CPU-addr→RAM mask (the same mapping
+  // the callSubroutine watchdog uses). Best-effort: return null on any read miss.
+  const ramMask = platform === "genesis" ? 0xffff
+    : (platform === "gb" || platform === "gbc" || platform === "sms" || platform === "gg" || platform === "msx") ? 0x1fff
+      : 0xffff;
+  const readRamByte = (cpuAddr) => {
+    try {
+      const b = host.readMemory("system_ram", cpuAddr & ramMask, 1);
+      return b && b.length ? b[0] : null;
+    } catch { return null; }
+  };
+  const readCpuWord = (cpuAddr) => {
+    const lo = readRamByte(cpuAddr); const hi = readRamByte(cpuAddr + 1);
+    return (lo == null || hi == null) ? null : (lo | (hi << 8));
+  };
+  const readCpuLongBE = (cpuAddr) => {
+    const b0 = readRamByte(cpuAddr), b1 = readRamByte(cpuAddr + 1), b2 = readRamByte(cpuAddr + 2), b3 = readRamByte(cpuAddr + 3);
+    return (b0 == null || b1 == null || b2 == null || b3 == null) ? null : ((b0 << 24) | (b1 << 16) | (b2 << 8) | b3) >>> 0;
+  };
+
+  const bt = buildBacktrace({
+    platform,
+    regs,
+    readMemory: (region, off, len) => host.readMemory(region, off, len),
+    readByteAt,
+    readCpuWord,
+    readCpuLongBE,
+  });
+  if (!bt || !bt.frames.length) return null;
+  const pad = bt.isa === "m68k" ? 6 : 4; // 24-bit m68k addresses print wider
+  const isaNote = {
+    "6502": "confident=true means the byte before the return target is a JSR ($20).",
+    sm83: "confident=true means the return address lands in a plausible code range (SM83 call frames are 2-byte LE; the call's own length isn't recovered, so callerPc IS the return address).",
+    z80: "confident=true means the return address lands in a plausible code range (Z80 call frames are 2-byte LE; callerPc IS the return address).",
+    m68k: "confident=true means the return longword is even + in-range (m68k jsr/bsr push a 4-byte BE return; callerPc IS the return address).",
+  }[bt.isa] || "";
+  return {
+    isa: bt.isa,
+    frames: bt.frames.map((f) => ({
+      callerPc: "$" + f.callerPc.toString(16).toUpperCase().padStart(pad, "0"),
+      returnAddr: "$" + f.returnAddr.toString(16).toUpperCase().padStart(pad, "0"),
+      confident: f.confident,
+    })),
+    note: `callStack[0] is the immediate caller (the call that reached this routine), decoded from the stack at the break instant. ${isaNote} Generated server-side — no hand stack-walking.`,
+  };
+}
 
 // Restore a savestate (in-memory slot `fromState` OR disk file `fromStatePath`)
 // before a trace, so on:'range'/'pc' run from a known moment. Returns a small
@@ -130,13 +206,11 @@ export function makePressDriver(host, presses) {
   };
 }
 
-// Single source of truth: the same canonical region vocabulary readMemory
-// uses (host/types.js). Previously this was a hand-maintained list that had
-// drifted — it carried DEAD Genesis `md_*` names (which throw on read) and
-// was MISSING nes_apu_regs / genesis_* / c64_*, so you couldn't watch the
-// hardware-register regions readMemory could already read. Deriving from the
-// host map means new regions flow through automatically and the two tools can
-// never disagree again.
+// Single source of truth: the same canonical region vocabulary readMemory uses
+// (host/types.js). Derived from the host map so new regions flow through
+// automatically and the two tools never disagree. Used by the ONE primary
+// `on:'mem'` region enum (kept discoverable on purpose); every SECONDARY region
+// sub-param uses the lean regionStr string instead (0.28.0/0.30.0 feedback #5).
 const MEMORY_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
 
 // A region param that does NOT inline the full ~62-value enum into the JSON
@@ -624,6 +698,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         hits: result.hits,
         framesStepped: result.framesStepped,
         ...(wpRegs ? { registersAtHit: wpRegs } : {}),
+        ...((() => { const bt = backtraceForHit(host, wpRegs); return bt ? { callStack: bt } : {}; })()),
         ...(bankInfo ? bankInfo : {}),
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
         note: "pc is the EXACT writing instruction (captured in the CPU write path), not a frame sample. " +
@@ -782,6 +857,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         pc: last.lastPC != null ? "$" + last.lastPC.toString(16).toUpperCase() : null,
         pcRaw: last.lastPC,
         ...(atHit ? { registersAtHit: atHit } : {}),
+        ...((() => { const bt = backtraceForHit(host, atHit); return bt ? { callStack: bt } : {}; })()),
         ...(capturedMemory ? { capturedMemory } : {}),
         frame: host.status.frameCount,
         framesRun,
@@ -793,6 +869,138 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       }), host);
   }
 
+  // A4: Computed-jumptable recovery via the LIVE emulator. Static analysis follows
+  // direct addressing only, so a `JMP (table,X)` / RTS-trick dispatcher collapses
+  // to "Could not recover jumptable" — and those dispatchers (game-state machines,
+  // script/event VMs, battle engines) are the routines you most want to read. We
+  // resolve them dynamically: break at the dispatcher, single-step THROUGH the
+  // indirect transfer, and record the PC it actually lands on. Run across many
+  // frames/inputs to accumulate the distinct target set — the real switch arms.
+  //
+  // No standalone tool (IDA/Ghidra/Binary Ninja) can do this: they have no live
+  // emulator to observe the computed target. The observed set can be fed back as
+  // analysis hints (Rizin ahi/aho) so `decompile`/`cfg` recover the switch.
+  async function bpResolveJumptable({ address, maxFrames = 1200, maxTargets = 64, stepLimit = 48, jumpThreshold = 5, pressDuring, fromState, fromStatePath }) {
+      const host = getHost(sessionKey);
+      if (!host.pcBreakSupported || !host.pcBreakSupported()) {
+        return jsonContent({
+          ok: false, notSupported: true, address: "$" + address.toString(16).toUpperCase(),
+          note: "This core build has no PC breakpoint / single-step (shipped on all 14 platforms as of 0.5.0 — update the core package if you see this).",
+        });
+      }
+      const restored = await maybeRestoreState(host, fromState, fromStatePath);
+      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      const pressDriver = makePressDriver(host, presses);
+
+      // We separate COMPUTED targets from FIXED trampolines by what VARIES. As we
+      // single-step out of the dispatcher, normal flow is sequential (next PC =
+      // prev + 1..4 on a 6502, wider on ARM); a computed JMP (table,X) / RTS-trick
+      // makes the PC LEAP (delta > jumpThreshold or backward). But a real dispatch
+      // path contains FIXED leaps too — cc65 lowers an indirect call to
+      // JSR<callax>; JMP(ptr), so the trampoline addresses leap identically on
+      // every hit. The handler ARM is the leap destination that DIFFERS hit-to-
+      // hit. So: per hit, collect the set of leap destinations; across all hits,
+      // a destination seen on EVERY hit is a fixed trampoline (drop it), and one
+      // seen on only SOME hits is a real computed arm (keep it). leapSeen counts
+      // how many hits each destination appeared in; perHitLeaps holds the firstFrame
+      // + a sample fromPC for the keepers.
+      const leapSeen = new Map();   // destPC -> hitCount
+      const leapMeta = new Map();   // destPC -> { firstFrame, fromPC }
+      let dispatcherHits = 0, framesRun = 0;
+
+      try {
+        for (let i = 0; i < maxFrames && leapMeta.size < maxTargets * 4; i++) {
+          pressDriver.applyForFrame(i);
+          host.setPCBreak(address, true, false);
+          host.stepFrames(1);
+          framesRun++;
+          let st = host.getPCBreak(false);
+          if (!st.hit) { host.setPCBreak(0, false, false); continue; }
+
+          const fromPC = st.lastPC ?? address;
+          host.getPCBreak(true); // clear the hit so the next arm is clean
+          // Walk forward; collect the destination of EVERY control-flow leap in
+          // this hit (deduped within the hit), plus the PC it leapt FROM.
+          const seenThisHit = new Set();
+          let prev = fromPC, prevLeapFrom = fromPC;
+          for (let s = 0; s < stepLimit; s++) {
+            const step = host.stepInstruction(); // { pc } AFTER one instr
+            const pc = step.pc;
+            if (pc == null) break;
+            const delta = pc - prev;
+            if (delta < 0 || delta > jumpThreshold) {
+              if (!seenThisHit.has(pc)) {
+                seenThisHit.add(pc);
+                if (!leapMeta.has(pc)) leapMeta.set(pc, { firstFrame: framesRun, fromPC: prevLeapFrom });
+              }
+              prevLeapFrom = prev;
+            }
+            prev = pc;
+          }
+          for (const pc of seenThisHit) leapSeen.set(pc, (leapSeen.get(pc) ?? 0) + 1);
+          dispatcherHits++;
+        }
+      } finally {
+        pressDriver.finish();
+        host.setPCBreak(0, false, false); // disarm
+        if (host.getRegSnapshot) host.getRegSnapshot(true); // consume any stale snapshot
+      }
+
+      const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase();
+      // Classify each leap destination. A COMPUTED arm VARIES across hits — it was
+      // reached on some hits but not all (leapSeen < dispatcherHits). A FIXED
+      // trampoline (cc65 callax, the post-handler return path) leaps identically
+      // EVERY hit (leapSeen == dispatcherHits). Keep the variers as targets.
+      const allLeaps = [...leapMeta.entries()].map(([pc, m]) => ({
+        pc, hits: leapSeen.get(pc) ?? 0, firstFrame: m.firstFrame, fromPC: m.fromPC,
+      }));
+      let arms = allLeaps.filter((l) => l.hits < dispatcherHits);
+      // Fallback: if NOTHING varied (the dispatcher only ever took one path under
+      // this input — a single observed arm), report the non-trampoline leaps as
+      // candidate targets rather than nothing. With only one hit, everything has
+      // hits==1==dispatcherHits, so report all leaps as candidates.
+      let singleArm = false;
+      if (!arms.length && allLeaps.length) { arms = allLeaps; singleArm = true; }
+
+      const sorted = arms
+        .slice(0, maxTargets)
+        .map((l) => ({ target: hx(l.pc), targetRaw: l.pc, hits: l.hits, firstFrame: l.firstFrame, fromPC: hx(l.fromPC) }))
+        .sort((a, b) => b.hits - a.hits || a.targetRaw - b.targetRaw);
+
+      if (!sorted.length) {
+        const drove = presses.length > 0;
+        return attachObserverFrame(jsonContent({
+          ok: true, resolved: false,
+          address: hx(address), framesRun, dispatcherHits,
+          ...(restored ? { restoredFrom: restored } : {}),
+          ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
+          note: dispatcherHits === 0
+            ? (drove
+              ? "The dispatcher at this address never executed within maxFrames EVEN WITH the scheduled input — likely the WRONG address (a different routine dispatches), or not an instruction boundary. Confirm with breakpoint({on:'pc'}) that the PC reaches it at all."
+              : "The dispatcher never executed — drive the game to the state that runs it (pressDuring / fromState), or increase maxFrames. Confirm reachability with breakpoint({on:'pc'}).")
+            : "The dispatcher executed but no control-flow LEAP was observed in the next " + stepLimit + " instructions — so this address isn't (or isn't reaching) a computed jump. Confirm it's the indirect-jump instruction, or raise stepLimit if the dispatch does heavy setup first.",
+        }), host);
+      }
+
+      return attachObserverFrame(jsonContent({
+        ok: true, resolved: true,
+        address: hx(address),
+        targets: sorted,
+        distinctTargets: sorted.length,
+        dispatcherHits, framesRun,
+        ...(singleArm ? { singleArmObserved: true } : {}),
+        ...(arms.length > maxTargets ? { truncated: true, truncatedAt: maxTargets } : {}),
+        ...(restored ? { restoredFrom: restored } : {}),
+        ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
+        note: (singleArm
+            ? "Only ONE dispatch path ran under this input, so targets are the candidate leap destinations (couldn't separate the computed arm from fixed trampolines without a second arm to compare). Drive MORE game states (pressDuring / fromState) so the dispatcher takes different arms — then the varying one is isolated as the real target. "
+            : "targets are the COMPUTED jump destinations that VARIED across dispatches — the real switch arms a static decompiler can't see (fixed trampolines were filtered out). ") +
+          "Each is a routine the dispatcher branches to; decompile({address: target}) / disasm({target:'rom', startAddress: target}) to read them. " +
+          "hits = how many dispatches took that arm under this input; drive more states to surface rarer arms. " +
+          "This is the live-emulator advantage: no static-only tool can recover these.",
+      }), host);
+  }
+
   async function bpRunUntilRead({ address, maxFrames = 600, pressDuring }) {
       const host = getHost(sessionKey);
       if (!host.readWatchSupported || !host.readWatchSupported()) {
@@ -862,11 +1070,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "use it, NOT a follow-up cpu({op:'read'}). On some cores (notably NES/fceumm) the core drains the cycle budget on hit but the frame still finishes, " +
     "so a live cpu read afterward returns END-OF-FRAME registers, not the break instant. `registersAtHit` sidesteps that. The break PC is reported as `pc`/`pcRaw`; " +
     "the RAM side effects are also reliable via memory({op:'read'}). frame({op:'stepInstruction'}) to single-step from the break. (on:'read'/'write' finish the frame.)\n" +
+    "• on:'jumptable' — **RESOLVE a computed-jump dispatcher the static decompiler can't follow.** Game-state machines, script/event VMs, and battle engines dispatch through `JMP (table,X)` / RTS-trick tables; `decompile`/`cfg` collapse them to `(*_IRQ)()` + 'Could not recover jumptable'. Break at the dispatcher `address`, single-step THROUGH the indirect transfer, and record the PC it lands on — repeated across frames/inputs to accumulate the DISTINCT target set (the real switch arms), ranked by hit count. Drive more game states (pressDuring / fromState) to surface rarer arms. Returns `{targets:[{target,hits,fromPC}], distinctTargets}`. **No static-only tool (IDA/Ghidra/Binary Ninja) can do this — it needs a live emulator in the loop, which is romdev's edge.** Feed the targets to decompile({address:target}) to read each arm.\n" +
     "All supported on every CPU core. **Every hit carries `registersAtHit` — the FULL register file frozen by the core AT the hit instant, on ALL 14 platforms and all three `on` kinds.** Use it instead of a follow-up cpu({op:'read'}): the live registers keep moving after a hit (per-scanline CPU scheduling / frame completion), so a post-hit read drifts — chasing pointer registers read that way burned a real session for hours. The hit `pc` is the EXECUTING instruction's first byte (mid-instruction hooks no longer report the operand-advanced PC). Out-of-date core packages return notSupported.\n" +
     "MENU-SCREEN INPUT TRICK: if a pressDuring schedule never registers (some menu screens poll input in a way scheduled taps miss), HOLD the button instead: input({op:'set', buttons:{...}}) BEFORE this call and OMIT pressDuring — the run inherits the held state, the menu sees the edge, and the breakpoint catches the event.",
     {
-      on: z.enum(["write", "read", "pc"])
-        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant register file, all 14 platforms) + the break PC; use registersAtHit, not a follow-up cpu read (end-of-frame state)."),
+      on: z.enum(["write", "read", "pc", "jumptable"])
+        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant register file, all 14 platforms) + the break PC; jumptable=RESOLVE a computed-jump dispatcher (JMP (tbl,X) / RTS-trick) by breaking at `address`, single-stepping THROUGH the indirect transfer, and recording every COMPUTED target PC live across frames/inputs — the switch arms a static decompiler reports as 'Could not recover jumptable'. (use registersAtHit, not a follow-up cpu read.)"),
       precision: z.enum(["exact", "sampled"]).default("exact")
         .describe("on:'write' ONLY. exact=core watchpoint, the real writing instruction PC even under interrupts (uses `address`). sampled=cheap frame-boundary PC (uses region/offset/length) — NOT the writer under IRQ. Ignored for on:read/pc (always exact)."),
       address: z.number().int().min(0).optional().describe("on:'write' exact / on:'read' / on:'pc' — CPU address to break on (write target, read target, or instruction boundary). Required for those."),
@@ -893,6 +1102,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         length: z.number().int().min(1).max(256).default(1).describe("bytes to read"),
         label: z.string().optional().describe("human name for this read (else 'region+offset')"),
       })).optional().describe("on:'pc' — read these memory regions AT the hit and return them inline as `capturedMemory` (collapses break→read-RAM into ONE call, the token win). Pair with `registersAtHit` to get the routine's register + RAM state in a single round trip (e.g. capture the ZP pointer bytes a decoder just wrote). NOTE: registersAtHit is the true break instant (core snapshot); these RAM reads are taken after the hit frame finishes, so on run-to-frame-end cores (fceumm) they're the routine's RAM side effects for that frame — stable + reliable, which is exactly what RE needs."),
+      maxTargets: z.number().int().min(1).max(1024).default(64).describe("on:'jumptable' — stop once this many DISTINCT computed targets have been observed (the run also ends at maxFrames). Sets `truncated:true` if reached."),
+      stepLimit: z.number().int().min(1).max(256).default(48).describe("on:'jumptable' — instructions to single-step after each dispatcher hit while collecting control-flow leaps. Must be deep enough to REACH the handler: a compiler-lowered indirect call (cc65 JSR<callax>; JMP(ptr)) runs the table load + trampoline + the indirect jump before the handler is entered — ~30 instructions here, so the default is 48. Too low and you only capture the fixed trampolines (the real arms never appear); raise it if a dispatch does heavy setup before the indirect jump."),
+      jumpThreshold: z.number().int().min(1).max(64).default(5).describe("on:'jumptable' — a single-step whose PC delta exceeds this many bytes (or goes backward) counts as a control-flow LEAP (a taken jump/branch/call), vs sequential instruction flow. 5 suits 6502/Z80/SM83 (max ~3-byte instructions); raise for wider ISAs (ARM/m68k) so multi-byte sequential instructions aren't misread as leaps."),
+      fromState: z.number().int().min(0).optional().describe("on:'jumptable'/'pc' (via the trace path) — restore this in-memory savestate SLOT before running, so the dispatcher is resolved from a known, repeatable moment (e.g. inside the battle/menu the dispatcher drives). Mutually exclusive with fromStatePath."),
+      fromStatePath: z.string().optional().describe("on:'jumptable' — restore this savestate FILE before running (the disk equivalent of fromState). Mutually exclusive with fromState."),
     },
     safeTool(async (args) => {
       switch (args.on) {
@@ -912,6 +1126,10 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           if (args.address == null) throw new Error("breakpoint({on:'pc'}): `address` is required.");
           return await bpRunUntilPC(args);
         }
+        case "jumptable": {
+          if (args.address == null) throw new Error("breakpoint({on:'jumptable'}): `address` is required (the computed-jump dispatcher).");
+          return await bpResolveJumptable(args);
+        }
         default: throw new Error(`breakpoint: unknown on '${args.on}'`);
       }
     }),
@@ -1150,7 +1368,9 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     {
       on: z.enum(["mem", "range", "pc", "dma", "copy"])
         .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]; dma=Genesis-only mem→VDP DMA source/dest trace; copy=log every write landing in a VRAM address window with the EXECUTING instruction's PC (all 14 platforms — the generic 'where does this graphic come from?')."),
-      // on:'mem'
+      // on:'mem' — the ONE primary region enum kept on purpose (0.30.0 design):
+      // where region IS the choice, the discoverable canonical list stays in the
+      // schema. The secondary region sub-params use the lean regionStr instead.
       region: z.enum(MEMORY_REGIONS).optional().describe("on:'mem' single-range — the region to watch (same canonical set memory uses, incl. nes_apu_regs, genesis_ym2612, c64_sid_regs). Omit when using `ranges`."),
       offset: z.number().int().min(0).default(0).describe("on:'mem' single-range — first byte of the watched range."),
       length: z.number().int().min(1).max(4096).default(1).describe("on:'mem' single-range — bytes to watch (default 1)."),

package/src/mcp/util.js

@@ -62,12 +62,49 @@ export function imageContent(pngBase64) {
 
 /** Wrap an Error as a tool error result. */
 export function errorContent(err) {
+  // UnsupportedError carries the structured capability-contract fields so an
+  // agent can branch on `unsupported: true` instead of string-matching the
+  // message. We surface BOTH a clean sentence and the structured fields.
+  if (err && err.name === "UnsupportedError") {
+    const text = err.message + (err.alternative ? ` (try: ${err.alternative})` : "");
+    return {
+      isError: true,
+      unsupported: true,
+      platform: err.platform,
+      op: err.op,
+      reason: err.reason ?? null,
+      alternative: err.alternative ?? null,
+      content: [{ type: "text", text }],
+    };
+  }
   return {
     isError: true,
     content: [{ type: "text", text: String(err?.message ?? err) }],
   };
 }
 
+/**
+ * The single, uniform "this platform doesn't support this op" signal. Throws a
+ * typed UnsupportedError that safeTool → errorContent formats consistently
+ * (and that programmatic callers / the conformance test can catch + inspect).
+ * Replaces the ad-hoc "not supported"/"not yet wired" throws.
+ *
+ * @param {string} platform
+ * @param {string} op        a capability op key (see cores/capabilities.js OP_KEYS)
+ * @param {{reason?:string, alternative?:string}} [opts]
+ * @returns {never}
+ */
+export function unsupported(platform, op, { reason, alternative } = {}) {
+  const base = `'${op}' is not supported on platform '${platform}'`;
+  const err = new Error(reason ? `${base}: ${reason}` : base + ".");
+  err.name = "UnsupportedError";
+  err.platform = platform;
+  err.op = op;
+  err.reason = reason ?? null;
+  err.alternative = alternative ?? null;
+  throw err;
+}
+
 /**
  * Wrap a tool implementation so any thrown error becomes a structured tool
  * error rather than a transport-layer exception.
@@ -175,15 +212,60 @@ export function withClearToolErrors(server, z) {
   return server;
 }
 
+// ── Hex-string coercion on address-like params ─────────────────────
+// JSON forbids `0x…` number literals, so an agent that pastes an address as hex
+// (`{address: 0xC06C}`) gets a HARD parse error, and even valid JSON can't carry
+// hex. We accept the STRING forms `"0x…"`, `"$…"`, and decimal strings on
+// address-like params and coerce them to a number BEFORE validation, so the
+// natural thing an agent reaches for just works. (Reported repeatedly in v0.41.0
+// feedback as the #1 first-try-fail.)
+//
+// Matched by KEY NAME (not schema introspection — robust across zod versions).
+// DELIBERATELY NARROW: only names that are unambiguously a numeric address/offset
+// across the toolset. Names like `start`/`end`/`from`/`to`/`target`/`compare` are
+// EXCLUDED because they're also booleans (the START button) or enums (`compare:'eq'`,
+// `from:'aseprite'`); the coercer passes non-hex strings through, but not wrapping
+// them at all keeps those schemas pristine. Address-suffixed forms (`startAddress`,
+// `endAddress`) DO match and cover the range-bound case.
+const ADDR_KEY_RE = /^(address|cpuAddress|addr|offset|pc|compare|startAddress|endAddress|baseAddress|targetAddress|fromAddress|toAddress|romOffset|prgOffset|vramAddr)$/i;
+
+/** Coerce `"0x1A"` / `"$1A"` / `"26"` → number; pass through numbers/undefined/
+ *  non-hex strings unchanged (so a non-numeric value still hits the real schema
+ *  error). Exported for unit tests. */
+export function coerceHexNumber(v) {
+  if (typeof v !== "string") return v;
+  const s = v.trim();
+  if (/^[$]([0-9a-fA-F]+)$/.test(s)) return parseInt(s.slice(1), 16);
+  if (/^0x[0-9a-fA-F]+$/i.test(s)) return parseInt(s, 16);
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  return v; // leave anything else for the inner schema to reject
+}
+
 /**
  * Build a `.strict()` z.object from a tool's shape whose validation issues each
  * render as a clear sentence (unknown-key "did you mean", enum options, missing
  * required, wrong type). Used by withClearToolErrors to replace the stored schema.
+ * Also wraps address-like params with hex-string coercion (see coerceHexNumber).
  * @param {any} z
  * @param {Record<string, any>} shape
  * @param {string} toolName
  */
 function strictFriendlyObject(z, shape, toolName) {
+  // Wrap address-like fields with a hex-string→number preprocessor. z.preprocess
+  // runs the coercion first, then the field's own schema (number().int()…)
+  // validates the result — so descriptions, optionality, and ranges are preserved.
+  const coercedShape = {};
+  for (const [key, schema] of Object.entries(shape)) {
+    if (ADDR_KEY_RE.test(key)) {
+      // z.preprocess drops the wrapper's .description (which tools/list needs),
+      // so re-attach the field's own description to the wrapped schema.
+      const wrapped = z.preprocess(coerceHexNumber, schema);
+      coercedShape[key] = schema.description ? wrapped.describe(schema.description) : wrapped;
+    } else {
+      coercedShape[key] = schema;
+    }
+  }
+  shape = coercedShape;
   const validKeys = Object.keys(shape);
   const errorMap = (issue) => {
     switch (issue.code) {

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -334,14 +334,27 @@ what touches an address). The **Rizin/Ghidra analysis engine** carves the progra
   scan misses. Use it to answer "what calls this routine / reads this table?"
 - **`disasm({target:'decompile', path, address})`** — Ghidra **C-like pseudocode**
   for a function. Read it to UNDERSTAND a routine fast; it is NOT the edit path
-  (use `target:'project'`, §7b, to change and rebuild). Quality tracks the CPU —
-  see the `qualityNote` it returns: excellent on ARM (GBA) / 68000 (Genesis),
-  good on SM83 (GB) / Z80 (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE),
-  rough on the 6502 family (carry-flag idioms and 16-bit-math-on-8-bit decompile
-  to noise — read the disassembly there, or let an LLM fold the pseudocode).
+  (use `target:'project'`, §7b, to change and rebuild). Hardware-register MMIO is
+  NAMED (`PPUMASK` not `*0x2001`) and on the 6502 family SLEIGH clutter is folded
+  to readable C99 (`uint8_t`, `zp_FD`) — see the `/* hw registers: … */` /
+  `/* 6502 fold: … */` legends. Quality tracks the CPU — see the `qualityNote` it
+  returns: excellent on ARM (GBA) / 68000 (Genesis), good on SM83 (GB) / Z80
+  (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE), rough on the 6502 family
+  (carry-flag idioms and 16-bit-math-on-8-bit decompile to noise — read the
+  disassembly there, or let an LLM fold the residual pseudocode).
+- **`breakpoint({on:'jumptable', address})`** — when a routine decompiles to
+  `(*_IRQ)()` + "Could not recover jumptable" (the computed-jump dispatchers —
+  state machines, script/battle VMs — that static analysis structurally can't
+  follow), RESOLVE it live: this breaks at the dispatcher in the running emulator,
+  single-steps through the indirect `JMP (table,X)` / RTS-trick, and returns the
+  COMPUTED targets it actually lands on. Drive more game states (`pressDuring` /
+  `fromState`) to surface rarer arms. `disasm({target:'resolveJumptable'})` is the
+  static-side alias. No static-only tool can do this — it's romdev's live-emulator
+  edge.
 
 **The loop:** `symbols({op:'analyze'})` or `disasm({target:'functions'})` to carve →
-`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate → then the
+`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate (→
+`breakpoint({on:'jumptable'})` when it dispatches through a computed jump) → then the
 dynamic tools (memory search, `breakpoint({on:'write'})`, `watch`) to CONFIRM and
 label which carved function owns the value you care about. Static narrows the
 search space; dynamic proves it.
@@ -422,8 +435,9 @@ Once you know WHAT to change, the write loop is a handful of calls — no custom
   and >32KB HuCards (refs carry `romBank`) — so a hit in bank 12 of a 128KB cart shows up,
   not just the first bank. Zero-page direct + indexed operands match, and `#$nn` immediates
   are excluded (values, not addresses). Limitation: direct addressing only —
-  indirect/computed jumps aren't detected (use the runtime `watch`/`breakpoint` tools in
-  §5/§5d for those).
+  indirect/computed jumps aren't detected statically; resolve those LIVE with
+  `breakpoint({on:'jumptable', address})` (runs the emulator to record the computed
+  targets), or the other runtime `watch`/`breakpoint` tools in §5/§5d.
 - **`cart({op:'extract', path, outputDir})`** — split a ROM into standard parts (NES header/
   prg/chr; SNES copier_header+rom+internal header; Genesis vectors/header/body; GB boot/
   header/body) + a `manifest.json` (mapper, mirroring…). **`cart({op:'wrap'})`** is the inverse:
@@ -528,6 +542,7 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 | Re-inject edited bytes the game accepts | `romPatch({op:'makeStored'})` (verbatim-expand block) → `romPatch({op:'findFree'})` → `romPatch({op:'relocate'})` |
 | Find the pointer that loads an asset | `romPatch({op:'findPointer', romOffset})` |
 | FIND the unknown routine touching X | `watch({on:'range', start,end})` (all hits) / `watch({on:'pc'})` (coverage) |
+| Resolve a computed-jump dispatcher (decompiles to `(*_IRQ)()`) | `breakpoint({on:'jumptable', address})` (live — records the real switch arms) |
 | Which DMA wrote a VRAM tile + its source (Genesis) | `watch({on:'dma', precision:'exact', vramDest})` |
 | Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |