romdevtools 0.40.2 → 0.42.0

package/src/analysis/rizin.js

@@ -77,7 +77,7 @@ export const RIZIN_ARCH = {
  * @returns {Promise<{exitCode:number, output:string, log:string, crash?:object}>}
  */
 export async function runRizin(opts) {
-  const { romPath, romBytes, commands, arch, bits, baddr, writeable } = opts;
+  const { romPath, romBytes, commands, arch, bits, baddr, writeable, timeoutMs } = opts;
   if (!commands) throw new Error("runRizin: commands required");
   const bytes = romBytes ?? new Uint8Array(await readFile(romPath));
 
@@ -102,6 +102,11 @@ export async function runRizin(opts) {
   const res = await runIsolated({
     gluePath: rizinGluePath(),
     argv,
+    // A5: per-call timeout so a hung analysis (whole-ROM `aaa` on a multi-MB ROM)
+    // can't wedge the shared worker pool — on timeout the worker is killed +
+    // recycled and this call returns a clean { timedOut, log } result. Default
+    // 60s; callers can override (a scoped `af @ addr` pass is near-instant).
+    timeoutMs: timeoutMs ?? 60000,
     inputFiles: [{
       vfsPath: "/work/rom.bin",
       encoding: "base64",
@@ -109,6 +114,13 @@ export async function runRizin(opts) {
     }],
     outputFiles: [{ vfsPath: OUT, encoding: "utf8" }],
   });
+  // Surface a timeout as a thrown error so JSON callers get a clear signal
+  // (runRizinJson already wraps crashes; this makes the timeout explicit).
+  if (res.timedOut) {
+    const e = new Error(res.log?.trim() || "rizin analysis timed out");
+    /** @type {any} */ (e).timedOut = true;
+    throw e;
+  }
   return { ...res, output: res.outputs?.[OUT] ?? "" };
 }
 

package/src/cheats/gamegenie.js

@@ -444,9 +444,21 @@ export function decodeWithDevice(code, platform) {
   return { ...decoded, device };
 }
 
-/** Format a raw ADDR:VAL[:COMPARE] code from decoded parts (hex, no 0x). */
+/** Format a raw ADDR:VAL[:COMPARE] code from decoded parts (hex, no 0x).
+ *  The ADDRESS is padded to a minimum of 4 hex digits. This is NOT cosmetic:
+ *  libretro cheat parsers (verified on fceumm) treat a short `AA:VV` RAM code as
+ *  inert — it parses but never binds (`apply` then falsely reports success). A
+ *  zero-page address like $32 must be emitted as `0032:09` to actually poke; the
+ *  2-digit `32:09` is silently dropped. ROM addresses ($8000+) are already 4+
+ *  digits, so padding only fixes the low-RAM case and never changes a working
+ *  code. The VALUE stays 2 digits (`0009` 4-digit values also break the parser).
+ *  Addresses wider than 16 bits (e.g. Genesis $FFxxxx work RAM) keep their full
+ *  width, rounded up to an even number of digits. */
 export function encodeRaw({ address, value, compare }) {
-  const addrHex = (address >>> 0).toString(16).toUpperCase();
+  const rawHex = (address >>> 0).toString(16).toUpperCase();
+  // pad to >=4 digits, and to an even digit count so it's a whole number of bytes
+  const width = Math.max(4, rawHex.length + (rawHex.length & 1));
+  const addrHex = rawHex.padStart(width, "0");
   const valHex = (value & 0xFF).toString(16).toUpperCase().padStart(2, "0");
   return compare != null
     ? `${addrHex}:${valHex}:${(compare & 0xFF).toString(16).toUpperCase().padStart(2, "0")}`

package/src/cores/capabilities.js

@@ -0,0 +1,218 @@
+// capabilities.js — the platform CAPABILITY CONTRACT.
+//
+// One declarative entry per platform stating, in machine-readable form, what
+// romdev's platform-sensitive tools can do on it. This is the SOURCE OF TRUTH
+// the BUILDING.md `deep`/`shallow` legend used to encode as prose — now data,
+// enforced by test/capability-conformance.test.js (declared MUST exactly match
+// actual tool behavior; mismatch fails CI).
+//
+// Why it exists: the 14 tier-1 platforms are near-uniform, but the next-gen tier
+// (N64/PS1/Dreamcast/PSP/DS) breaks that — 3D rendering, MIPS/SH-4 CPUs, GPU-FBO
+// screenshots, ops that are meaningless on a polygon renderer. A declared
+// contract + a uniform "unsupported" signal lets agents discover what a system
+// can do BEFORE calling, and keeps the matrix honest as platforms diverge.
+//
+// Fields (keep MINIMAL — only what the contract / discovery / conformance use):
+//   cpuFamily       primary CPU family (forward-looking; "6502","z80","sm83",
+//                   "m68k","arm","65816","huc6280" today; "mips","sh4" later)
+//   renderingKind   "tile" | "framebuffer" | "3d" | "none" — how the screen is
+//                   produced. The current 14 are all "tile". Drives whether
+//                   tile/nametable inspection ops even make sense.
+//   introspection   "deep" | "shallow" — the BUILDING.md legend, as data.
+//   ops.*           boolean per platform-sensitive op (see OP_KEYS below).
+//   decompileQuality "excellent"|"good"|"medium"|"rough" (from the RE engine).
+//   cpus            { main, secondary[] } — what getCPUState({op:'read'}) decodes.
+//   audioChips      chip ids audioDebug({op:'inspect'}) decodes ([] = no chip).
+//   memoryRegions   exact region ids memory({op}) accepts beyond the generic set.
+
+/** The platform-sensitive op keys the contract tracks. Universal tools (build's
+ * file plumbing, encodeAudio, catalog, files, ...) are NOT here — they don't
+ * vary by platform. */
+export const OP_KEYS = /** @type {const} */ ([
+  "build",              // buildSource for this platform
+  "run",                // loadMedia + a real core
+  "screenshot",         // frame({op:'screenshot'})
+  "inspectSprites",     // sprites({op:'inspect'})
+  "inspectPalette",     // palette({source:'live'})
+  "inspectBackground",  // background({view:'renderState'/'map'})
+  "renderingContext",   // background({view:'renderState'}) decode
+  "cpuState",           // cpu({op:'read'}) main CPU
+  "audioDebug",         // audioDebug({op:'inspect'})
+  "cart",               // cart({op:'extract'/'wrap'})
+  "disasm",             // disasm({target:'rom'/'project'/'references'})
+  "decompile",          // disasm({target:'decompile'}) — RE engine, all 14
+]);
+
+// Generic regions every running core exposes (libretro RETRO_MEMORY_*).
+const GENERIC_REGIONS = ["system_ram", "save_ram", "video_ram", "rtc"];
+
+/** @typedef {{ cpuFamily:string, renderingKind:"tile"|"framebuffer"|"3d"|"none",
+ *   introspection:"deep"|"shallow", ops:Record<string,boolean>,
+ *   decompileQuality:string, cpus:{main:string, secondary:string[]},
+ *   audioChips:string[], memoryRegions:string[] }} Capability */
+
+const tileDeep = ({ ops: opsOverride = {}, ...rest } = {}) => ({
+  renderingKind: "tile", introspection: "deep",
+  ...rest,
+  ops: {
+    build: true, run: true, screenshot: true,
+    inspectSprites: true, inspectPalette: true, inspectBackground: true,
+    renderingContext: true, cpuState: true, audioDebug: true,
+    cart: true, disasm: true, decompile: true,
+    ...opsOverride,
+  },
+});
+
+/** @type {Record<string, Capability>} */
+export const CAPABILITIES = {
+  nes: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: ["nes"],
+    memoryRegions: [...GENERIC_REGIONS, "nes_nametables", "nes_palette", "nes_oam",
+      "nes_chr", "nes_apu_regs", "nes_cpu_regs", "nes_ppu_regs"],
+    ...tileDeep(),
+  },
+  snes: {
+    cpuFamily: "65816", decompileQuality: "medium",
+    cpus: { main: "65816", secondary: ["spc700"] },
+    audioChips: ["dsp"],
+    memoryRegions: [...GENERIC_REGIONS, "snes_oam", "snes_cgram", "snes_aram", "snes_fillram"],
+    ...tileDeep(),
+  },
+  genesis: {
+    cpuFamily: "m68k", decompileQuality: "excellent",
+    cpus: { main: "m68k", secondary: [] }, // z80 not yet decoded
+    audioChips: ["ym2612", "psg"],
+    memoryRegions: [...GENERIC_REGIONS, "genesis_cram", "genesis_vsram", "genesis_vdp_regs",
+      "genesis_z80_ram", "genesis_m68k", "genesis_ym2612", "genesis_psg"],
+    ...tileDeep(),
+  },
+  sms: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "z80", secondary: [] },
+    audioChips: ["psg"],
+    memoryRegions: [...GENERIC_REGIONS, "sms_vram", "sms_cram", "sms_vdp_regs", "sms_z80_regs"],
+    ...tileDeep(),
+  },
+  gg: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "z80", secondary: [] },
+    audioChips: ["psg"],
+    memoryRegions: [...GENERIC_REGIONS, "gg_vram", "gg_cram"],
+    ...tileDeep(),
+  },
+  gb: {
+    cpuFamily: "sm83", decompileQuality: "good",
+    cpus: { main: "sm83", secondary: [] },
+    audioChips: ["gb"],
+    memoryRegions: [...GENERIC_REGIONS, "gb_vram", "gb_oam", "gb_io", "gb_hram",
+      "gb_bgpdata", "gb_objpdata", "gb_cpu_regs"],
+    ...tileDeep(),
+  },
+  gbc: {
+    cpuFamily: "sm83", decompileQuality: "good",
+    cpus: { main: "sm83", secondary: [] },
+    audioChips: ["gb"],
+    memoryRegions: [...GENERIC_REGIONS, "gb_vram", "gb_oam", "gb_io", "gb_hram",
+      "gb_bgpdata", "gb_objpdata", "gb_cpu_regs"],
+    ...tileDeep(),
+  },
+  gba: {
+    cpuFamily: "arm", decompileQuality: "excellent",
+    cpus: { main: "arm", secondary: [] },
+    audioChips: ["gba"],
+    memoryRegions: [...GENERIC_REGIONS, "gba_cpu_regs", "gba_io_regs", "gba_palette", "gba_oam"],
+    // GBA: the patched mgba regions give MORE than BUILDING.md's old "shallow"
+    // prose implied — inspectSprites/Palette + renderingContext + cpuState +
+    // audioDebug are all wired (per the tool Supported lists). cart extract/wrap
+    // and inspectBackgroundMap are NOT.
+    renderingKind: "tile", introspection: "shallow",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  atari2600: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: [], // TIA tone, no dedicated sound chip audioDebug decodes
+    memoryRegions: [...GENERIC_REGIONS, "a26_tia_regs", "a26_cpu_regs"],
+    ...tileDeep({ ops: { audioDebug: false, inspectSprites: true, inspectBackground: false } }),
+  },
+  atari7800: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: [], // TIA; no audioDebug decode
+    memoryRegions: [...GENERIC_REGIONS, "a78_cpu_regs"],
+    ...tileDeep({ ops: { audioDebug: false, inspectBackground: false } }),
+  },
+  c64: {
+    cpuFamily: "6502", decompileQuality: "rough",
+    cpus: { main: "6502", secondary: [] },
+    audioChips: ["sid"],
+    memoryRegions: [...GENERIC_REGIONS, "c64_color_ram", "c64_vic_regs", "c64_sid_regs",
+      "c64_cia1_regs", "c64_cia2_regs", "c64_cpu_regs"],
+    // C64 has no inspectBackgroundMap branch (character-mode screen is read via
+    // raw VIC regions, not a snapshotter).
+    ...tileDeep({ ops: { inspectBackground: false } }),
+  },
+  lynx: {
+    cpuFamily: "65c02", decompileQuality: "rough",
+    cpus: { main: "65c02", secondary: [] },
+    audioChips: ["mikey"],
+    memoryRegions: [...GENERIC_REGIONS, "lynx_cpu_regs", "lynx_hw_regs"],
+    // Lynx: sprites return the SCB list head (no fixed OAM) — counts as wired.
+    // shallow per BUILDING.md (generic introspection + sfx/music templates).
+    renderingKind: "tile", introspection: "shallow",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  pce: {
+    cpuFamily: "huc6280", decompileQuality: "medium",
+    cpus: { main: "", secondary: [] }, // getCPUState main NOT wired for pce
+    audioChips: ["pce"],
+    memoryRegions: [...GENERIC_REGIONS, "pce_vdc_vram", "pce_vdc_satb", "pce_vdc_regs",
+      "pce_vce_palette", "pce_cpu_regs", "pce_psg_regs"],
+    renderingKind: "tile", introspection: "deep",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: false, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  msx: {
+    cpuFamily: "z80", decompileQuality: "good",
+    cpus: { main: "", secondary: [] }, // getCPUState main NOT wired for msx
+    audioChips: ["ay8910"],
+    memoryRegions: [...GENERIC_REGIONS, "msx_vram", "msx_vdp_regs", "msx_vdp_status",
+      "msx_palette", "msx_cpu_regs", "msx_psg_regs"],
+    renderingKind: "tile", introspection: "deep",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: true, inspectPalette: true, inspectBackground: false,
+      renderingContext: true, cpuState: false, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+};
+
+/** All platform ids in the contract. */
+export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES);
+
+/** Does `platform` support `op`? Unknown platform/op → false. */
+export function supports(platform, op) {
+  return Boolean(CAPABILITIES[platform]?.ops?.[op]);
+}
+
+/** The full capability entry for a platform (or null). */
+export function capabilitiesFor(platform) {
+  return CAPABILITIES[platform] ?? null;
+}

package/src/cores/registry.js

@@ -1,8 +1,12 @@
-// Core registry. Maps platform IDs to bundled libretro WASM cores.
+// Core registry. Maps platform IDs to their libretro WASM core.
 //
-// All v1 cores ship inside the npm package under src/cores/wasm/. Resolution
-// is a simple path lookup — there is no fetcher because there is nothing to
-// fetch.
+// The shipped core wasm lives in the per-platform binary packages
+// (romdev-core-* / romdev-platform-*) — NOT in this package. `resolveCore`
+// resolves each platform from the `pkg` named in its CORES entry. The local
+// `src/cores/wasm/` dir is a gitignored BUILD-STAGING area: `scripts/build-*.sh`
+// emit there, and it serves as a dev fallback when you're working in-tree
+// without the satellite packages built. It is empty in a fresh clone and does
+// NOT ship in the npm tarball.
 
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -11,81 +15,69 @@ import path from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-/** Directory holding all bundled `.js` + `.wasm` libretro core pairs. */
+/** Build-staging dir for `.js` + `.wasm` core pairs (gitignored; dev fallback
+ *  only — the shipped wasm resolves from the satellite packages). */
 export const CORES_DIR = path.resolve(__dirname, "wasm");
 
 /**
  * @typedef {Object} CoreInfo
  * @property {string} platform     short platform id ("nes", "gb", ...)
  * @property {string} coreName     filename stem (matches `<coreName>_libretro.js`)
+ * @property {string} pkg          binary package that SHIPS this core's wasm.
+ *   `romdev-core-*` = a standalone core (often shared: gpgx serves genesis/sms/
+ *   gg, gambatte serves gb/gbc). `romdev-platform-*` = a core bundled WITH the
+ *   dedicated toolchain nothing else uses (snes9x+asar+wla, mGBA+arm-gcc,
+ *   stella+dasm) — they ship together because only that platform needs them.
  * @property {string} displayName
  * @property {string} [aka]        comma-separated synonyms accepted in resolvers
  */
 
 /**
+ * The single source of truth for every platform's core: its filename stem, the
+ * package that ships it, and display metadata — all in one record so there's no
+ * second map to keep in sync.
  * @type {Record<string, CoreInfo>}
  */
 export const CORES = {
-  nes: { platform: "nes", coreName: "fceumm", displayName: "Nintendo Entertainment System (fceumm)" },
-  gb: { platform: "gb", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
-  gbc: { platform: "gbc", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
-  atari2600: { platform: "atari2600", coreName: "stella2014", displayName: "Atari 2600 (Stella)" },
-  atari7800: { platform: "atari7800", coreName: "prosystem", displayName: "Atari 7800 (ProSystem)" },
-  lynx: { platform: "lynx", coreName: "handy", displayName: "Atari Lynx (Handy)" },
-  sms: { platform: "sms", coreName: "genesis_plus_gx", displayName: "Sega Master System (Genesis Plus GX)" },
-  gg: { platform: "gg", coreName: "genesis_plus_gx", displayName: "Sega Game Gear (Genesis Plus GX)" },
-  genesis: { platform: "genesis", coreName: "genesis_plus_gx", displayName: "Sega Genesis / Mega Drive (Genesis Plus GX)" },
-  snes: { platform: "snes", coreName: "snes9x", displayName: "SNES (snes9x)" },
-  gba: { platform: "gba", coreName: "mgba", displayName: "Game Boy Advance (mGBA)" },
-  c64: { platform: "c64", coreName: "vice_x64", displayName: "Commodore 64 (VICE x64)" },
-  pce: { platform: "pce", coreName: "geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
-  msx: { platform: "msx", coreName: "bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
+  nes: { platform: "nes", coreName: "fceumm", pkg: "romdev-core-fceumm", displayName: "Nintendo Entertainment System (fceumm)" },
+  gb: { platform: "gb", coreName: "gambatte", pkg: "romdev-core-gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  gbc: { platform: "gbc", coreName: "gambatte", pkg: "romdev-core-gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  atari2600: { platform: "atari2600", coreName: "stella2014", pkg: "romdev-platform-atari2600", displayName: "Atari 2600 (Stella)" },
+  atari7800: { platform: "atari7800", coreName: "prosystem", pkg: "romdev-core-prosystem", displayName: "Atari 7800 (ProSystem)" },
+  lynx: { platform: "lynx", coreName: "handy", pkg: "romdev-core-handy", displayName: "Atari Lynx (Handy)" },
+  sms: { platform: "sms", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Master System (Genesis Plus GX)" },
+  gg: { platform: "gg", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Game Gear (Genesis Plus GX)" },
+  genesis: { platform: "genesis", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Genesis / Mega Drive (Genesis Plus GX)" },
+  snes: { platform: "snes", coreName: "snes9x", pkg: "romdev-platform-snes", displayName: "SNES (snes9x)" },
+  gba: { platform: "gba", coreName: "mgba", pkg: "romdev-platform-gba", displayName: "Game Boy Advance (mGBA)" },
+  c64: { platform: "c64", coreName: "vice_x64", pkg: "romdev-core-vice", displayName: "Commodore 64 (VICE x64)" },
+  pce: { platform: "pce", coreName: "geargrafx", pkg: "romdev-core-geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
+  msx: { platform: "msx", coreName: "bluemsx", pkg: "romdev-core-bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
 };
 
-/**
- * Resolve a platform id to absolute paths for its core.
- * Returns null if the core isn't bundled.
- * @param {string} platform
- * @returns {{ platform: string, coreName: string, displayName: string, jsPath: string, wasmPath: string } | null}
- */
-// Platform → the @romdev binary package that ships its core wasm. Resolution
-// tries the package first (the shipped layout), then falls back to a local
-// src/cores/wasm copy (transition / dev). Add a row here as each platform's
-// package is carved out; platforms not listed still resolve locally.
-const CORE_PACKAGES = {
-  atari2600: "romdev-platform-atari2600",
-  nes: "romdev-core-fceumm",
-  gb: "romdev-core-gambatte",
-  gbc: "romdev-core-gambatte",
-  genesis: "romdev-core-gpgx",
-  sms: "romdev-core-gpgx",
-  gg: "romdev-core-gpgx",
-  c64: "romdev-core-vice",
-  lynx: "romdev-core-handy",
-  atari7800: "romdev-core-prosystem",
-  snes: "romdev-platform-snes",
-  gba: "romdev-platform-gba",
-  pce: "romdev-core-geargrafx",
-  msx: "romdev-core-bluemsx",
-};
-
-/** Try to get {jsPath,wasmPath} for a core from its @romdev package. */
-function resolveCoreFromPackage(platform, coreName) {
-  const pkg = CORE_PACKAGES[platform];
+/** Try to get {jsPath,wasmPath} for a core from its binary package. */
+function resolveCoreFromPackage(pkg, coreName) {
   if (!pkg) return null;
   try {
     const dir = path.dirname(fileURLToPath(import.meta.resolve(pkg)));
     const jsPath = path.join(dir, "wasm", `${coreName}_libretro.js`);
     const wasmPath = path.join(dir, "wasm", `${coreName}_libretro.wasm`);
     if (existsSync(jsPath) && existsSync(wasmPath)) return { jsPath, wasmPath };
-  } catch { /* package not resolvable — fall through to local */ }
+  } catch { /* package not resolvable — fall through to the dev-staging dir */ }
   return null;
 }
 
+/**
+ * Resolve a platform id to absolute paths for its core. Tries the binary
+ * package first (the shipped layout), then the gitignored `src/cores/wasm/`
+ * build-staging dir (in-tree dev fallback). Returns null if neither has it.
+ * @param {string} platform
+ * @returns {{ platform: string, coreName: string, pkg: string, displayName: string, jsPath: string, wasmPath: string } | null}
+ */
 export function resolveCore(platform) {
   const info = CORES[platform];
   if (!info) return null;
-  const fromPkg = resolveCoreFromPackage(platform, info.coreName);
+  const fromPkg = resolveCoreFromPackage(info.pkg, info.coreName);
   if (fromPkg) return { ...info, ...fromPkg };
   const jsPath = path.join(CORES_DIR, `${info.coreName}_libretro.js`);
   const wasmPath = path.join(CORES_DIR, `${info.coreName}_libretro.wasm`);

package/src/mcp/state.js

@@ -10,10 +10,41 @@
 // layer is responsible for calling clearHost(key) on session close.
 
 import { LibretroHost } from "../host/index.js";
+import path from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
 
 /** @type {Map<string, LibretroHost>} */
 const hosts = new Map();
 
+/**
+ * Disk path for a playtest session's rolling auto-checkpoint (eviction
+ * survivability). Deterministic per (session, rom) so the eviction-recovery hint
+ * can name it WITHOUT any bookkeeping. Next to the ROM when it's a real on-disk
+ * file; else a stable per-session file under the OS temp dir. (v0.41.0 feedback
+ * note 125904.) Shared by the playtest tool (writer) and getHost (recovery hint).
+ * @param {string} sessionKey
+ * @param {string|null} mediaPath
+ */
+export function playtestCheckpointPath(sessionKey, mediaPath) {
+  const safeSession = String(sessionKey).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 40);
+  if (mediaPath && !mediaPath.startsWith("<") && path.isAbsolute(mediaPath)) {
+    const dir = path.dirname(mediaPath);
+    const base = path.basename(mediaPath, path.extname(mediaPath));
+    return path.join(dir, `${base}.playtest-autosave.state`);
+  }
+  return path.join(os.tmpdir(), `romdev-playtest-${safeSession}.autosave.state`);
+}
+
+// Secondary host slot ("B") per session. The primary slot above is what every
+// tool uses by default; slot B exists for the ONE workflow that needs two cores
+// live at once: side-by-side comparison (e.g. an original ROM vs. its port).
+// loadMedia({slot:'b'}) loads here; frame({op:'sideBySide'}) captures both. It
+// is entirely opt-in — a session that never loads slot B pays nothing, and the
+// per-session teardown below clears both slots together.
+/** @type {Map<string, LibretroHost>} */
+const hostsB = new Map();
+
 // What this session last loaded, kept OUTSIDE the host map so it SURVIVES a
 // host eviction (server restart / session reconnect / unload). The host itself
 // is gone in those cases, so the "No ROM loaded" error has nothing to read —
@@ -47,11 +78,18 @@ export function getHost(sessionKey) {
       const recall = prev.path
         ? `loadMedia({ platform: "${prev.platform}", path: "${prev.path}" })`
         : `loadMedia({ platform: "${prev.platform}", base64: ... })  (your ROM came from base64 — re-supply the bytes)`;
+      // If a playtest window was open, a rolling auto-checkpoint may be on disk —
+      // restoring it recovers the human's MANUAL progress, not just a fresh boot.
+      const ckpt = playtestCheckpointPath(sessionKey, prev.path ?? null);
+      const ckptHint = existsSync(ckpt)
+        ? `\nA playtest auto-checkpoint is on disk (your last ~15s of play): after the load above, run\n  state({ op: "load", path: "${ckpt}" })\nto restore the human's progress instead of replaying from boot.`
+        : "";
       throw new Error(
         "No ROM loaded in this session — the host was evicted (the server restarted, " +
         "your session reconnected, or the media was unloaded). Emulator state lives in " +
         "server memory only, so it did not survive. RECOVER by re-running your last load:\n  " +
         recall +
+        ckptHint +
         "\nThen replay any boot/navigate steps to get back to where you were. " +
         "(If instead you expected a DIFFERENT session, you may be sending an inconsistent " +
         "`x-romdev-session` header — reuse one stable id on every call.)",
@@ -100,11 +138,57 @@ export function clearHost(sessionKey) {
     try { existing.unloadMedia(); } catch {}
   }
   hosts.delete(sessionKey);
+  // A session shutdown tears down BOTH slots — slot B is part of the same
+  // session's footprint and must not outlive it.
+  clearHostB(sessionKey);
+}
+
+// --- Secondary host slot ("B") ----------------------------------------------
+// Same lifecycle helpers as the primary, scoped to the hostsB map. getHostB
+// throws a slot-specific error (no recovery breadcrumb — slot B is transient
+// scratch for a comparison, not the session's main ROM).
+
+/** @param {string} sessionKey @returns {LibretroHost} */
+export function getHostB(sessionKey) {
+  const host = hostsB.get(sessionKey);
+  if (!host) {
+    throw new Error(
+      "No ROM loaded in comparison slot B for this session — load one with " +
+      "loadMedia({ slot: 'b', platform, path }). Slot B is the second core used " +
+      "by frame({op:'sideBySide'}); it is not the session's primary ROM.",
+    );
+  }
+  return host;
+}
+
+/** @param {string} sessionKey */
+export function getHostBOrNull(sessionKey) {
+  return hostsB.get(sessionKey) ?? null;
+}
+
+/** @param {string} sessionKey @returns {LibretroHost} */
+export function resetHostB(sessionKey) {
+  const existing = hostsB.get(sessionKey);
+  if (existing && existing.status.loaded) {
+    try { existing.unloadMedia(); } catch {}
+  }
+  const fresh = new LibretroHost();
+  hostsB.set(sessionKey, fresh);
+  return fresh;
 }
 
-/** Test-only: number of live hosts. */
+/** @param {string} sessionKey */
+export function clearHostB(sessionKey) {
+  const existing = hostsB.get(sessionKey);
+  if (existing && existing.status.loaded) {
+    try { existing.unloadMedia(); } catch {}
+  }
+  hostsB.delete(sessionKey);
+}
+
+/** Test-only: number of live hosts (both slots). */
 export function _liveHostCount() {
-  return hosts.size;
+  return hosts.size + hostsB.size;
 }
 
 /** Test-only: inject a (possibly fake) host for a session key. */
@@ -112,6 +196,11 @@ export function _setHostForTest(sessionKey, host) {
   hosts.set(sessionKey, host);
 }
 
+/** Test-only: inject a (possibly fake) host into comparison slot B. */
+export function _setHostBForTest(sessionKey, host) {
+  hostsB.set(sessionKey, host);
+}
+
 // Shared reference to the per-session disclosure manager, so tool
 // handlers outside index.js (toolchain.js, etc.) can call consumeHint()
 // to emit session-scoped one-shot nudges (e.g. "loadCategory('show') to

package/src/mcp/tools/cheats.js

@@ -4,7 +4,7 @@ import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { attachObserverFrame } from "./watch-memory.js";
 import { lookupCheats, searchCheatGames } from "../../cheats/lookup.js";
-import { encodeForDevice, nativeDevicesFor, decodeCode } from "../../cheats/gamegenie.js";
+import { encodeForDevice, nativeDevicesFor, decodeCode, encodeRaw } from "../../cheats/gamegenie.js";
 
 // Per-platform cheat address space (for makeCheat validation). A Game Genie
 // letter code can only address these ranges; out-of-range → raw ADDR:VAL only.
@@ -57,6 +57,15 @@ export function resolveCheatCodeForApply(rawCode, platform) {
       else appliedAs = "rom-unencodable";
     } else if (decoded) {
       appliedAs = "ram";
+      // Normalize the raw RAM code so a short hand-typed `AA:VV` (e.g. "32:09")
+      // is re-emitted in the binding width ("0032:09"). The libretro parser
+      // (verified on fceumm) silently DROPS an under-padded RAM address — it
+      // parses but never pokes — so passing the user's short string through
+      // verbatim is the inert-cheat footgun. encodeRaw pads the address to the
+      // width the core honors. (No-op for already-padded codes.)
+      const norm = encodeRaw(decoded);
+      if (norm !== rawCode) reencodedFrom = rawCode;
+      code = norm;
     }
   }
   return { code, appliedAs, reencodedFrom };