romdevtools 0.26.0 → 0.28.0

package/AGENTS.md

@@ -4,7 +4,7 @@ This is romdev's GENERIC orientation — read it once. The platform-specific det
 
 ## What this server does
 
-Drives the full homebrew ROM dev loop for 14 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace which ROM offset a Genesis graphic was DMA'd from (`watch({on:'dma', precision:'sampled'})`), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
+Drives the full homebrew ROM dev loop for 14 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace where an on-screen graphic comes from (`watch({on:'copy'})` on all 14 — writer PC per VRAM write; `watch({on:'dma'})` for Genesis DMA sources), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
 
 You drive the work. The human is a director — they may want a game, a ROM disassembly, a tool-assisted reverse-engineering session, or anything else this server can do.
 
@@ -40,6 +40,8 @@ A couple of optional features load a native Node addon (most notably the `playte
 
 If a human is sitting next to you during this session — and that's most sessions in practice — open the playtest window as soon as your first build succeeds. `playtest()` opens a native SDL window that runs your ROM live and accepts USB gamepads (hot-plugged controllers are picked up automatically). It returns **immediately** — the render loop runs in the background, so you keep calling other tools while the human plays. Every other MCP tool keeps working against that same running ROM, and **`build({output:'run'})`/`loadMedia` rebuilds update the window in place** — the window follows your latest build, no relaunch and no crash on rebuild. A human sitting next to you should be **playing the game** while you iterate, not watching screenshots scroll past.
 
+**Co-driving is detected for you.** While the human is actively pressing (pad or keyboard), the window's input wins over yours and its real-time loop races your frame-stepping — and you'll KNOW: `frame`/`input` responses carry a `humanCoDriveWarning` while they pressed within the last ~2s, and `catalog({op:'status'})` / `playtest({op:'status'})` expose `humanInputActive`. When the human is idle the window leaves your `input({op:'set'})` alone. For deterministic stepping while they play, either `host({op:'pause'})` (the window keeps rendering, frozen) or use a SECOND session (a different `x-romdev-session` header = a fully isolated emulator).
+
 ```
 playtest()                       // opens the SDL window (returns immediately). op:'open' is the default;
                                  // playtest({op:'stop'|'status'|'framebuffer'}) close / check / capture-what-the-human-sees
@@ -63,8 +65,8 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 - `run` — load ROMs, step frames, screenshot (works for existing ROMs you didn't compile)
 - `input` — drive controllers, look up hardware bit layouts. `navigate` walks menus by advancing on SCREEN CHANGE (not fixed frames) and reports whether each press was consumed — the fast, reliable way to script a UI.
 - `state` — savestates and forensic state inspection (`state({op:'save'})`, `state({op:'load'})`, `state({op:'export'})` a slot to disk without touching the live host, `state({op:'list'})`, `state({op:'dump'})`)
-- `memory` — read/write VRAM/OAM/CGRAM/ARAM and other regions (all 14 platforms). `memory({op:'read'})` takes `offsets:[…]` to batch scattered reads in one call. **`memory({op:'search'})`/`memory({op:'searchNext'})`** = the Cheat-Engine value-search loop ("find the address of X, narrow as X changes"). **`memory({op:'readCart'})`** reads the loaded cart image to confirm a patch is live. **`memory({op:'classify'})`** says whether bytes look like ASCII/code/tile-data (kills the "found table that's really a string" trap). `memory({op:'snapshot'})` + `memory({op:'diff'})` answer "which bytes changed across this event?" (diff defaults to a clustered summary with stride detection); `state({op:'diff'})` is the coarse whole-machine version.
-- `debug` — **`frame({op:'verify'})`** (NO-VISION render-health: one call answers "is the game actually rendering / alive?" on all 14 — fuses a framebuffer pixel scan with the per-platform render-enable/NMI decode; `{verified:true|false|null, issues[], pixels, render}`, frame-0-guarded so it never cries wolf on boot), `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14), **`watch({on:'dma', precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
+- `memory` — read/write VRAM/OAM/CGRAM/ARAM and other regions (all 14 platforms). `memory({op:'read'})` takes `offsets:[…]` to batch scattered reads in one call. **`memory({op:'search'})`/`memory({op:'searchNext'})`** = the Cheat-Engine value-search loop ("find the address of X, narrow as X changes") — relative compares (`inc`/`dec`/`changed`) work as the FIRST narrow (baselines recorded at seed), and `as:'bcd'`/`as:'digits'` search packed-BCD scores and digit-per-byte HUD buffers (any constant tile base) when stored ≠ displayed. **`memory({op:'readCart'})`** reads the loaded cart image to confirm a patch is live. **`memory({op:'classify'})`** says whether bytes look like ASCII/code/tile-data (kills the "found table that's really a string" trap). `memory({op:'snapshot'})` + `memory({op:'diff'})` answer "which bytes changed across this event?" (diff defaults to a clustered summary with stride detection; small clusters carry before/after hex, `minDelta` filters churn); **`memory({op:'diffRuns', portsA, portsB?})`** answers "which byte does this INPUT drive?" in one call (same start state run twice under two inputs, only the divergent bytes return); `state({op:'diff'})` is the coarse whole-machine version. Reads routed to disk take `echo:false` to skip the inline hex.
+- `debug` — **`frame({op:'verify'})`** (NO-VISION render-health: one call answers "is the game actually rendering / alive?" on all 14 — fuses a framebuffer pixel scan with the per-platform render-enable/NMI decode; `{verified:true|false|null, issues[], pixels, render}`, frame-0-guarded so it never cries wolf on boot), `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14; EVERY hit on EVERY platform carries `registersAtHit` — the register file frozen at the hit instant, the only honest read since live regs drift after a hit — and the CPU stays frozen until the hit is cleared), **`watch({on:'dma', precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`watch({on:'copy'})`** (ALL 14: every write landing in a VRAM window logged with the EXECUTING instruction's PC — the generic 'which routine uploads this graphic?'; port-based video memory hooked in-core incl. the SNES DMA path, CPU-mapped VRAM via the range log), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy; banked carts — NES mappers, SNES LoROM, GB MBC, Sega mapper, MSX megaROM, 2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards — are split and reference-scanned PER BANK, refs tagged `prgBank`/`romBank`), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
 - `assets` — convert PNGs to tiles (`encodeArt`/`importArt`), WAVs to BRR, identify ROMs (`cart({op:'identify'})`), plus the hacking toolkit (`romPatch({op})` — write/writeMany/spliceCHR/relocate/makeStored/findFree/findPointer/diff, `assembleSnippet`, `cart({op:'extract'})`, `cart({op:'wrap'})`)
 - `project` — starter snippets per platform
 - `show` — `playtest({op})`: `op:'open'` opens the live SDL window for a human, `op:'stop'` closes it, `op:'status'` reports liveness, `op:'framebuffer'` captures exactly what the human's window shows

package/CHANGELOG.md

@@ -4,6 +4,326 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.28.0
+
+The reverse-engineering release: the three RE primitives — break-instant
+`registersAtHit`, interference-free `pure` CPU calls, and the
+`watch({on:'copy'})` graphics source-trace — now work on ALL 14 platforms
+(every emulator core rebuilt; upstream pins unchanged, everything carried by
+the patches in `scripts/patches/`). Plus the full scaffold overhaul from real
+RetroDECK playtesting, banked-cart parity for disasm/rebuild, the value-search
+upgrades, and the playtest co-drive detection. Details per section below.
+
+
+### Added — pure calls + the generic copy trace on ALL 14 platforms (primitives #2 and #3)
+The other two primitives from the all-platforms RE proposal, completing the
+set (registersAtHit was #1):
+- **`cpu({op:'call', pure:true})` works everywhere.** The guarantee is the
+  same on every platform — the game's own NMI/IRQ/VBlank logic CANNOT run
+  during the call and stomp the routine's output buffer — with the mechanism
+  reported as `pureMode`: Genesis/SMS/GG step ONLY the CPU (`'cpu-only'`,
+  the gpgx separable-loop path); every other core suppresses interrupt
+  DELIVERY for the duration (`'irq-blocked'` via a new `romdev_irqblock_set`
+  export — pending lines stay pending, video/timers advance harmlessly, no
+  game handler executes); the 2600's 6507 has no interrupt lines at all
+  (`'no-interrupts'`). Proven live on NES: NMI delivery verified firing,
+  then silent under the block, then a planted routine pure-called
+  end-to-end with its write landing.
+- **`watch({on:'copy'})` — the generic "where does this graphic come
+  from?".** Logs every write landing in a VRAM/dest address window with the
+  EXECUTING instruction's PC. Port-based video memory is hooked INSIDE the
+  cores — NES $2007, SNES $2118/19 (BOTH CPU port writes and the DMA path —
+  the PC is the DMA-triggering instruction), PCE VWR, MSX VDP data port,
+  SMS/GG/Genesis VDP data port (the CPU-port complement of the Genesis DMA
+  watch). Direct-mapped platforms (GB/GBC, GBA, C64, Lynx, 7800) route
+  through the CPU-address range log automatically. Follow a hit with
+  breakpoint({on:'pc', address: pc}) for registersAtHit at the uploader.
+- Cores rebuilt again (same pins; the scripts/patches/ diffs carry
+  everything — all 11 verified to apply clean to pristine checkouts).
+- `test/pure-copy-primitives.test.js`: the 13-core irq-block/run-pure
+  feature matrix, NES NMI-delivery proof + end-to-end pure call, MSX
+  block-safety, and copy traces on NES (port), SNES (port+DMA), GB (mapped).
+
+### Fixed/Added — registersAtHit + freeze-after-hit on ALL 14 platforms (every core rebuilt)
+The gpgx round's break-instant fixes, extended to every other core — the same
+three guarantees now hold across the whole platform matrix:
+- **`registersAtHit` everywhere** — every breakpoint hit (pc-break, watchdog,
+  write-watch, read-watch) on every platform freezes the FULL register file at
+  the hit instant inside the core hook, exported via `romdev_regsnap_get` and
+  surfaced in the breakpoint hit response. Per-CPU register sets: 6502 family
+  (NES/2600/7800/C64/Lynx/PCE) A/X/Y/P/S/PC; 65816 (SNES) +DB/D; sm83 (GB/GBC)
+  A/F/B/C/D/E/H/L/SP; Z80 (SMS/GG/MSX) +IX/IY; m68k (Genesis) D0-7/A0-7/SR;
+  ARM7 (GBA) r0-r15/CPSR. NES previously snapshotted pc-breaks only — its
+  write/read hits now snapshot too.
+- **Freeze-after-hit everywhere** — once a hit fires, the CPU run loop stays
+  frozen (across re-entries and frames) until the host clears the hit, so even
+  live register reads agree with the snapshot. Previously each core resumed on
+  the next loop re-entry and the registers drifted.
+- **Executing-instruction PC everywhere** — write/read watchpoints and range
+  logs report the EXECUTING instruction's first byte, latched at dispatch
+  (sm83/Z80/65816/6502 PCs advance past operands mid-instruction — the same
+  off-by-one class the gpgx round fixed for m68k; GBA reports the pipeline PC,
+  matching its breakpoint-address convention).
+- Cores rebuilt: fceumm, snes9x, gambatte, mGBA, handy, vice, stella2014,
+  prosystem, geargrafx, bluemsx (pins unchanged; the romdev patches in
+  scripts/patches/ carry all of it — the whole stack reproduces from a clean
+  clone). `cpu({op:'call', pure:true})` remains gpgx-only (the other systems'
+  CPU/video loops are not separable without deeper core surgery); their calls
+  carry the ⚠ frame-logic caveat instead.
+- `test/regsnap-all-cores.test.js`: live single-step snapshot + freeze proof
+  on 10 platforms (plus the existing gpgx suite for Genesis/SMS/GG).
+
+### Fixed/Added — gpgx core round (the NBA-Jam-both-consoles feedback): break-instant truth on Genesis/SMS/GG
+The first core rebuild in this release (gpgx only; pins unchanged, patch extended).
+- **`registersAtHit` on Genesis/SMS/GG** — `breakpoint({on:'pc'|'write'|'read'})`
+  hits now carry the FULL register file (m68k d0-d7/a0-a7/pc/sr/sp; z80
+  a/f/b/c/d/e/h/l/ix/iy/pc/sp) frozen by the core AT the hit instant. gpgx
+  schedules CPUs per scanline, so the live register file used to drift
+  hundreds of instructions past a hit before the host could read it — the
+  "wrong-pointer chases" that cost a real RE session ~2h. On a pc-break the
+  CPU now also stays FROZEN for the remainder of the frame (and across
+  frames until the hit is cleared), so even live reads agree.
+- **Write/read watchpoint PC is the EXECUTING instruction** — the hooks now
+  record the instruction's first-byte address latched at dispatch, not the
+  post-prefetch PC (the orb-at-$2A7216-reported-as-$2A721C off-by-one).
+  `breakpoint({on:'write'})` also renames `value`→`valueByte` (it's the one
+  byte that landed, not the operand) and explains its `hits` semantics.
+- **`cpu({op:'call', pure:true})`** — steps ONLY the active CPU (new
+  `romdev_run_pure` export): no VDP line processing, no co-CPU, no interrupts
+  raised — so the game's own VBlank logic can NOT run "concurrently" and
+  stomp the driven routine's output buffer (a real session diffed a correct
+  codec reimplementation against that poisoned output for ~1.5h). Non-pure
+  calls that spanned frames now carry a loud ⚠ caveat naming the risk and
+  the fix.
+- **Genesis `system_ram` normalized to CPU byte order** — gpgx stores 68k
+  work RAM host-LE word-swapped (`work_ram[A^1]`); the raw layout leaked
+  through every byte-granular tool. Self-consistent within search→write
+  loops (which is why it hid — even a test had the swapped bytes baked in as
+  the expected value), but off-by-XOR-1 the moment an offset crossed to/from
+  disassembly addresses or cheat-DB maps. Offset X now IS the byte the 68k
+  sees at $FF0000+X; words read big-endian as documented. This also fixes
+  `cpu({op:'call'})` sentinel pushes / `presetMemory` writes for any non-zero
+  sentinel address (the default $0 sentinel was swap-invariant, hiding it).
+- breakpoint hit responses normalize `hits` (a watchdog stop no longer
+  reports the contradictory `hit:true, hits:0`).
+- Docs: the held-input menu trick (when a `pressDuring` schedule never
+  registers on a menu screen, hold via `input({op:'set'})` and omit
+  pressDuring — runs inherit held input) is now in the breakpoint/watch tool
+  docs; the server banner prints a one-line headless note when no display is
+  available (so an agent knows before promising a playtest window).
+- `test/gpgx-registers-at-hit.test.js`: live-core coverage for all of it,
+  including a per-platform Genesis memory-read smoke (the earlier
+  "info is not defined" regression was invisible to a fake-host-only suite).
+
+
+### Fixed/Added — value-search upgrades (from the locate-value skill review)
+- **Relative compares work as the FIRST `searchNext`.** `op:'search'` now
+  baselines every candidate at seed time, so `compare:'inc'/'dec'/'changed'/
+  'unchanged'` no longer silently return 0 candidates on the first narrow
+  (the footgun a real session burned rounds on and a skill had to document —
+  the "do one eq round first" workaround is obsolete).
+- **Representation-aware search** — `memory({op:'search', as:'bcd'|'digits'})`
+  for the stored≠displayed cases: `'bcd'` matches packed-BCD values (2 decimal
+  digits/byte, region endianness — classic NES scores); `'digits'` matches one
+  byte per ON-SCREEN digit at ANY constant tile base (HUD digit/tile-index
+  buffers; the base is auto-detected per candidate and reported; single-digit
+  seeds only accept base 0/0x30 to avoid matching everything). `searchNext`
+  narrows in the seed's representation automatically, including numeric
+  `inc`/`dec` on decoded values. Works on all platforms/regions (endianness
+  per region, big-endian m68k included).
+- **search/searchNext response notes fixed** — they recommended the dead
+  `searchValue` name and a `writeMemory({bytes})` form that op:'write'
+  REJECTS; now they name the live ops with a `hex` payload, mention the
+  scene-changed-mid-step empty-round trap, and point input-driven values at
+  `diffRuns`. Same stale-name fix in two `watch` tool notes.
+- `test/search-representations.test.js` covers all of it.
+
+
+### Added — banked-cart parity across ALL platforms (per-bank references + rebuild glue)
+The 0.27.0 feedback round fixed per-bank reference scanning and one-call banked
+rebuild glue for NES only. Every other banked-cart platform now gets the same
+treatment:
+- **`disasm({target:'references'})` scans EVERY bank on every banked format** —
+  SNES multi-bank LoROM (was: only the first 32KB bank), GB/GBC MBC and SMS/GG
+  Sega-mapper and MSX megaROM (was: only the first 32KB), Atari 2600 F8/F6/F4
+  (was: only the boot bank), Atari 7800 (was: only the top 16KB — flat carts now
+  scan the WHOLE image, SuperGame carts per-bank), and >32KB HuCards (was: a
+  wrapped, garbage start address). Non-NES refs carry a `romBank` tag (NES keeps
+  `prgBank`). Very large carts scan the first 64 banks and SAY SO in `notes`.
+- **`disasm({target:'project'})` splits every banked format per-bank** so
+  instructions never straddle a bank edge: Sega-mapper SMS/GG (16KB banks),
+  MSX megaROMs (16KB banks + the "AB" header as its own data region), banked
+  2600 (4KB banks), 7800 SuperGame (16KB banks + the .a78 header split out),
+  >32KB HuCards (8KB pages + optional copier header split out).
+- **Atari 7800 SuperGame and PC Engine HuCards (flat AND banked) get one-call
+  byte-identical `build()` rebuilds** — their asm toolchain is cc65/ca65, the
+  same match that made NES one-call. NES-style glue: HEADER segment carrying
+  the original header bytes, per-bank segment wrappers, generated multi-bank
+  `.cfg` via `linkerConfigPath`. **PCE was previously the one honestly-LOSSY
+  case** (planRegions trimmed real $FF padding and didn't strip copier
+  headers) — both fixed, `verifiable:true` now.
+- **SMS/GG, MSX, and 2600 banked carts get per-bank native rebuild recipes**
+  (their `build()` is SDCC/DASM — can't consume the disasm syntax): per-bank
+  wrappers + cfg blobs (2600), bank-by-bank `as`/`objcopy`/`dd`/`cat` recipes
+  in `BUILD.md` (SMS/GG/MSX), all byte-exact.
+- Proven by `test/banked-parity.test.js`: synthetic banked carts on 7 platforms;
+  byte-identical one-call rebuilds verified end-to-end for 7800 SuperGame,
+  banked PCE, and flat-PCE-with-real-padding.
+
+
+### Fixed — scaffold overhaul from real RetroDECK/Bazzite playtesting (all 14 platforms)
+A full human playtest of every genre scaffold on real hardware surfaced clusters
+of repeated logic errors. The big ones:
+- **SMS/GG: every `build({output:'project'})` ROM black-screened** — the project
+  recipe skipped the dir's `*_crt0.s` believing `buildForPlatform` auto-injects
+  the bundled crt0 (it doesn't; only the rom/run handlers do), so SDCC's stock
+  z80 crt0 linked instead and `main()` never ran. Also: the bundled crt0's reset
+  block was 9 bytes (overflowed into the `.org 0x0008` RST slot, corrupting
+  `jp gsinit`), `_CODE` linked at `$0000` ON TOP of the vector table, and `.gg`
+  ROMs got an SMS region nibble (`$4C`) that flips Genesis-Plus-GX into SMS-compat
+  mode. Project builds now route/fall back to the bundled crt0, `_CODE` sits at
+  `$0100`, GG ROMs get region `$7C`, ROMs pad to 32KB before the TMR SEGA header,
+  and a regression test pins the boot byte + header. The SMS scaffold now ships
+  `sms_crt0.s` like GG/MSX.
+- **"All enemies spawn on the left"** (18 shmup/racing templates): spawn X/lane
+  came from `spawn_timer`, which the caller resets to 0 immediately before
+  `spawn()` — a constant. Each template now has a Galois-LFSR `rand8()`.
+- **Puzzle genre**: the gbc template is now the polished falling-jewel reference
+  game (4-direction matches, gravity + cascade chains, magic piece, SFX + music,
+  collect/flush vblank rendering, dataLoc `$C200` via the gb/gbc project recipe);
+  the DMG gb template is rebuilt around the same core; and the
+  mark/clear/gravity/cascade core is ported to all 10 other platforms (PCE: H+V
+  in its 8KB boot bank). Replaces a horizontal-only scan that missed vertical/
+  diagonal matches, half-cleared 4+ runs, and never dropped survivors.
+- **Atari 2600**: SWCHA ASL carry-chains clobbered A between shifts (pressing
+  RIGHT also "pressed" LEFT — the stuck-to-the-left-edge bug) in three templates;
+  the platformer's terminal-velocity clamp caught POSITIVE velocities (unsigned
+  CMP), killing every jump within one frame; sports' paddle axis was inverted vs
+  the kernel's Y convention and RESBL was never strobed (the ball NEVER moved
+  horizontally — per-frame div-15 + HMBL positioning added); racing re-randomizes
+  both lanes on crash; shmup aliens reaching the cannon reset the wave.
+- **Atari 7800**: the SWCHA joystick bit defines were exactly REVERSED on every
+  template (up/down steered left/right; sports' left/right moved the paddle
+  vertically). Plus speed tuning (platformer movement + jump, puzzle fall rate,
+  sports serve).
+- **Platformers**: GBA fell through every platform (the `blocked_below` gate
+  only matched a 1px window at 20px/frame fall speeds); SNES platforms are now
+  visibly drawn on the scrolled text layer (were invisible collision rects);
+  Lynx landing uses a crossing test (exact-equality check tunnelled); C64
+  `render_view` rewritten ~20x faster (a per-CELL platform scan + 16-bit modulo
+  cost ~2s per 8px scroll step at 1MHz — froze the game and ate jump presses);
+  NES player is red (was sky-blue on sky-blue) and moves 2px/frame; GB/GBC jump
+  height tamed.
+- **GBA sports "never starts"**: `tte_printf` (broken in this libtonc — the
+  documented GBA-1 issue) ran every frame and crashed with an undefined-
+  instruction exception on iteration 1. Replaced with the `tte_write` digit path
+  the other templates already use.
+- **SNES**: each genre now gets a distinct backdrop tint (every scaffold shipped
+  the same blue checkered wallpaper).
+- **Sound everywhere**: every scaffold now has a continuous background-music
+  loop plus audible SFX, verified per platform by recording + RMS analysis.
+  Genesis/Lynx tick a melody inside `sfx_update()` (no template wiring; Lynx
+  voices 64→100), NES adds a triangle-channel melody to `nes_runtime`, PCE a
+  ch5 melody with corrected volume (the 5-bit field is ~-1.5dB/step from 31 —
+  the old 13 was -27dB, near-silence; the shmup SFX are maxed), and the SMS/GG
+  3-voice tracker that already shipped is now actually STARTED by all 11
+  templates. **MSX root cause**: `msx_crt0.s` had the same `_INITIALIZER`-in-RAM
+  bug fixed for SMS/GG (every `static x = N` booted 0) plus a BIOS-KEYINT
+  PSGADDR-latch race (PSG writes now DI/EI-guarded) — both fixed; this likely
+  also explains the reported MSX sprite flakiness.
+- **GB/GBC sports scanline tear**: the OAM DMA now fires at the vblank leading
+  edge (45 staged `oam_set` calls used to push it a third of the frame into
+  active display — the "horizontal line a 3rd of the way down" glitch).
+- Misc per-genre polish: PCE gameplay speeds, C64 racing clears the BASIC
+  startup text, C64 sports court widened to the 9-bit sprite range, MSX/Lynx
+  sports contrast, GBA puzzle well border.
+- **Verification**: all 69 existing platform×genre scaffolds were swept —
+  scaffold → project build → boot → render-health green, all 14 platforms
+  respond to input, and each platform's audio was captured and RMS-checked.
+  (Atari 2600 has no puzzle genre by design.)
+
+### Fixed/Added — the 0.27.0 Zanac RE feedback round (banked-NES rebuilds, A/B diff, token cuts)
+- **Banked NES `disasm({target:'project'})` now emits COMPLETE, working rebuild
+  glue** (the headline ask): a `HEADER` segment with the original 16 iNES bytes,
+  a per-bank `PRGn` segment wrapper for every bank, a multi-bank `nes_rebuild.cfg`
+  (switchable banks at `$8000`, fixed top bank at `$C000`, CHR wired when
+  present), and a `rebuild.json` `build()` call referencing all of it. Proven
+  byte-identical on a synthetic 4-bank mapper-2 ROM fed straight back to
+  `build()` — what previously took an hour of hand-written segments + cfg is
+  now zero glue. (NROM keeps the existing proven `inesHeader` one-call path.)
+- **`build({linkerConfigPath})`** reads the `.cfg` from disk so a large
+  multi-bank config never streams through context (and `rebuild.json` uses it).
+- **`disasm({target:'references'})` scans every PRG bank on banked NES** —
+  the old flat-blob-at-`$8000` disassembly returned `refsFound:0` on >32KB
+  ROMs. Refs now carry a `prgBank` tag, and `#$nn` immediates no longer count
+  as references (they're values, not addresses).
+- **`memory({op:'diffRuns'})`** — the A/B input-diff primitive: runs the same
+  start state twice under two different held inputs (savestate restore in
+  between) and returns only the divergent bytes, with run-A/run-B values for
+  small clusters. Replaces the save/run/dump/restore/run/dump/python-diff loop
+  (~6 calls + a 4KB context hit) with one call; live-verified isolating an NES
+  player-X byte.
+- **`memory({op:'read'/'readCart', outputPath, echo:false})`** returns just
+  `{path, bytes}` — no more ~4KB hex echo on a 2KB dump that was explicitly
+  routed to disk.
+- **`memory({op:'diff'})`**: summary clusters ≤8 bytes now include
+  `before`/`after` hex (no more falling back to `view:'raw'` for the values),
+  and `minDelta` filters RNG/counter wiggle.
+- **`input({op:'press'})` guarantees a released→pressed edge** (one released
+  frame first), so edge-triggered handlers (START pause) can't miss the press
+  when the button was already held.
+- **`breakpoint({on:'pc'})` misses now diagnose**: report `pcNow`, stop
+  suggesting `pressDuring` when input WAS supplied (wrong-address is then the
+  likely story), and point at `watch({on:'pc'})` coverage tracing.
+
+### Added — human co-drive detection: agents now KNOW when a human is playing in the playtest window
+The long-standing confusion ("they get confused when I try to play while they're
+coding") had a real mechanism: the playtest window shares the session's ONE
+emulator host with the agent, and its 60fps tick wrote the human's pad state —
+including all-zeros when nobody was pressing — over the agent's `input({op:'set'})`
+every frame. The agent had no signal a human was co-driving and no warning that
+its input was being clobbered. Now:
+- **The window only writes input while the human is actually pressing** (pad,
+  keyboard, or rewind-scrub), plus one release write after they let go. An idle
+  window no longer silently clobbers the agent's held input. The human still wins
+  the instant they press.
+- **The window tracks human activity** ("pressed within the last ~2 s" ≈ 120
+  ticks) and exposes it: `catalog({op:'status'})` reports `playtestWindowOpen` +
+  `humanInputActive` (+ `framesSinceHumanInput`), and `playtest({op:'status'})`
+  reports the same.
+- **`frame({op:'step'/'stepAndShot'})` and `input(set/press/sequence/navigate)`
+  responses carry a `humanCoDriveWarning`** while the human is actively playing,
+  telling the agent the conflict is happening NOW and pointing at the escape
+  hatches: `host({op:'pause'})` to inspect frozen, or a second session
+  (different `x-romdev-session` = fully isolated emulator) for deterministic work.
+- The playtest tool's FOOTGUN doc now describes the real contract (real-time
+  stepping always races; input only clobbered while the human presses).
+
+### Changed — `screenshot` scale docs: native is the accurate default, upscale adds no detail
+The `scale` param's docs oversold integer UPscaling as making tiny handheld shots
+"legible." That was misleading: nearest-neighbor upscale just duplicates pixels —
+it adds **no information** the native frame doesn't already have, costs more image
+tokens, and since VLM vision encoders resize every input to their own fixed
+resolution it may not change what the model sees (and can slightly degrade it via a
+bicubic downscale of stretched pixels). Reworded the param + tool description to
+lead with **native (`scale:1`, the default) = perfect pixels = the accurate
+representation**, keep the genuinely-useful DOWNscale (`<1`, fewer tokens for
+"did it change?" checks), and frame upscale honestly as a last resort for clients
+that can't zoom a small image. (No behavior change — `scale` was already opt-in and
+defaulted to native; this is the docs telling the truth about it.)
+(Committed during the 0.27.0 cycle but AFTER 0.27.0 published — ships in 0.28.0.)
+
+## 0.27.0
+
+### Added — `breakpoint(on:'pc', captureMemory:[…])` reads named RAM at the hit
+Completes item 2 of the NES Rygar report. 0.26.0 shipped `registersAtHit` (the
+break-instant register file) but not the memory half. Now `breakpoint(on:'pc')`
+takes `captureMemory:[{region,offset,length,label}]` and returns those reads inline
+as `capturedMemory`, so register + RAM inspection at a PC collapses into ONE call —
+no follow-up `cpu`/`memory` round trips. `registersAtHit` is the true break instant
+(core snapshot); `capturedMemory` reflects the routine's RAM side effects for the
+hit frame (stable + what RE needs), documented as such.
+
 ## 0.26.0
 
 ### Fixed — NES `breakpoint(on:'pc')` now returns reliable break-instant registers
@@ -17,9 +337,8 @@ them (the schema's "CPU is FROZEN at this instruction" was wrong for NES).
   SNAPSHOTS A/X/Y/P/S at the hit instant, exposed via `romdev_pcbreak_get`.
 - **`breakpoint(on:'pc')` returns `registersAtHit`** — the reliable break-instant
   register file. The schema + hit note now steer to it and explicitly warn that a
-  live `cpu({op:'read'})` after a hit is end-of-frame state on fceumm. (Item 1+2
-  of the report, collapsed: the snapshot is taken in the same call that detects the
-  hit, so there's no freeze-durability race and no extra round trip.)
+  live `cpu({op:'read'})` after a hit is end-of-frame state on fceumm. (The
+  `captureMemory` companion that reads named RAM inline at the hit landed in 0.27.0.)
 - **NES `cpu({op:'read'})` core-internal fields relabeled** (item 3): `DB`,
   `IRQlow`, `tcount`, `count` are fceumm internals (data-bus latch / IRQ bitmask /
   cycle counters), not 6502 registers — moved out of `registers` into a labeled

package/README.md

@@ -45,7 +45,7 @@ claude mcp add --transport http romdev http://127.0.0.1:7331/mcp
 
 It's a standard **streamable-HTTP** MCP server at `http://127.0.0.1:7331/mcp`. For opencode, Codex CLI, and other clients, see **[Connect](https://github.com/monteslu/romdev#connect)** in the repository README. An optional human observer (live tool-call view) is at `/livestream`.
 
-Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instructions — the workflow guide for the full tool surface. Or just connect your agent and call `catalog({op:'categories'})` to explore the tools live (and `catalog({op:'whatsNew'})` for the recent CHANGELOG + a rename table if you're resuming work against an older version).
+Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instructions — the workflow guide for the full tool surface. Or just connect your agent and call `catalog({op:'categories'})` to explore the tools live, and `catalog({op:'status'})` for the running version + session snapshot.
 
 ## Prefer not to use MCP? Use HTTP or a Skill
 

package/examples/README.md

@@ -21,7 +21,7 @@ Each example fits the convention:
 | genesis      | `genesis/main.s`     | vasm68k   |                                      |
 | gb           | `gb/main.c` (default) or `gb/main.asm` (`language:"asm"`) | sdcc sm83 port (C, default) / rgbds (asm) | C example cycles the BG palette every 32 frames. Asm example shows yellow 'H' on light BG, scrollable with A. SDCC GB hardware-register headers under `src/platforms/gb/lib/c/gb_hardware.h`. |
 | gbc          | `gbc/main.asm`       | rgbds (asm) / sdcc sm83 (C) | The bundled example is an asm CGB-color demo (yellow 'H' on a true-blue BG, only possible on GBC). C is also supported via SDCC sm83 — same as GB. |
-| sms          | `sms/main.c` (or `sms/templates/*.c`) | sdcc | Pair with `src/platforms/sms/lib/c/sms_crt0.s` (passed via `crt0` arg) — boots into a real cartridge with vector table + SP=$DFF0 + IM 1. Yellow 'H' on blue, scrollable with P1-B1. The 9 templates under `sms/templates/` (default, hello_sprite, tile_engine, shmup, shmup_2p, platformer, puzzle, sports, racing, music_demo) all use this crt0 — `scaffold({op:'project'})` copies it in automatically. |
+| sms          | `sms/main.c` (or `sms/templates/*.c`) | sdcc | Pair with `src/platforms/sms/lib/c/sms_crt0.s` (passed via `crt0` arg) — boots into a real cartridge with vector table + SP=$DFF0 + IM 1. Yellow 'H' on blue, scrollable with P1-B1. The 10 templates under `sms/templates/` (default, hello_sprite, tile_engine, shmup, shmup_2p, platformer, puzzle, sports, racing, music_demo) all use this crt0 — `scaffold({op:'project'})` copies it in automatically. |
 | gg           | `gg/templates/default.c` (or any other template) | sdcc | R53: GG now ships `src/platforms/gg/lib/c/gg_crt0.s` (byte-identical to SMS's). Real visible-and-runnable default: VDP Mode 4 init + palette + yellow 'H' centered in the 160×144 visible viewport + B1 scroll loop. The 9 templates (default, hello_sprite, tile_engine, shmup, platformer, puzzle, sports, racing, music_demo) all link the GG runtime + crt0 via `scaffold({op:'project', platform:"gg"})`. |
 | gba          | `gba/templates/*.c`  | arm-none-eabi-gcc | Default runtime = **libtonc** (`#include <tonc.h>`). 9 scaffolds incl. `tonc_hello`, `tonc_hello_sprite`, the 5 genre scaffolds, and `maxmod_demo` (music). Pass `runtime:"libgba"` for the devkitPro API, `runtime:"none"` for bare newlib. **Always call `irq_init(NULL); irq_add(II_VBLANK, NULL);` before `VBlankIntrWait()`** — otherwise the BIOS halts forever. |
 | pce          | `pce/<template>/main.c` | cc65 (HuC6280) | HuCard homebrew, no BIOS. Ships a direct-register VDC/PSG helper lib (`pce.h` + `pce.lib`) — cc65 has no PCE sprite/sound library. Templates: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre scaffolds (shmup/platformer/puzzle/sports/racing). **`#include <stdint.h>`** for int8/16/32_t — `pce.h` only typedefs u8/u16. Genre scaffolds fill the BAT (32×32 virtual screen); the platformer smooth-scrolls via the VDC BXR register. |

package/examples/atari2600/templates/platformer.asm

@@ -162,17 +162,21 @@ MAIN:
   LDA FRAME
   AND #$01
   BNE .skipmove
+  ; SWCHA is active-LOW; RE-LOAD per direction (the old ASL carry-chain
+  ; clobbered A with LDA P_X between shifts → RIGHT also triggered LEFT
+  ; and the moves cancelled — the player couldn't move).
   LDA SWCHA
-  ASL                  ; bit7 = Right
-  BCS .nr
+  AND #$80             ; bit7 = Right (0 = pressed)
+  BNE .nr
   LDA P_X
   CMP #140
   BCS .nr
   INC P_X
   INC P_X
 .nr:
-  ASL                  ; bit6 = Left
-  BCS .nl
+  LDA SWCHA
+  AND #$40             ; bit6 = Left (0 = pressed)
+  BNE .nl
   LDA P_X
   CMP #16
   BCC .nl
@@ -212,12 +216,17 @@ MAIN:
   LDA ON_GND
   BNE .skipgrav
   DEC P_VY             ; gravity: velocity drifts toward falling each frame
-  ; clamp terminal fall speed to -8 px/frame (P_VY is signed; -8 = $F8).
+  ; Clamp terminal FALL speed to -8 px/frame — but ONLY while falling.
+  ; The old unsigned compare (CMP #$F8 / BCS keep) also caught every
+  ; POSITIVE velocity (5 < $F8 unsigned!), so the instant you jumped the
+  ; clamp slammed P_VY from +6 to -8: the whole "jump" rose 0 frames,
+  ; fell 8px and re-landed within ONE frame — jump sfx played, screen
+  ; blipped, player never left the ground.
   LDA P_VY
-  CMP #$F8             ; if P_VY (unsigned) < $F8 AND it's negative → too fast
-  BCS .vyok            ; >= $F8 (covers -8..-1 and 0..127) → keep
-  ; here P_VY is in $80..$F7 = -128..-9 → clamp to -8
-  LDA #$F8
+  BPL .vyok            ; rising (positive) → terminal clamp doesn't apply
+  CMP #$F8
+  BCS .vyok            ; -8..-1 → within terminal speed, keep
+  LDA #$F8             ; -128..-9 → clamp to -8
   STA P_VY
 .vyok:
   ; P_Y += P_VY  (signed add: sign-extend P_VY into the add)

package/examples/atari2600/templates/racing.asm

@@ -165,17 +165,23 @@ MAIN:
   LDA FRAME
   AND #$01
   BNE .skipmove
+  ; SWCHA is active-LOW (0 = pressed). RE-LOAD it for each direction —
+  ; the old ASL carry-chain clobbered A with LDA P_X between shifts, so
+  ; the second ASL shifted P_X instead of SWCHA: pressing RIGHT also
+  ; "pressed" LEFT (P_X < $80 -> carry clear) and the moves cancelled.
+  ; That was the "ship/car stuck to the left edge" bug.
   LDA SWCHA
-  ASL                  ; bit7 = P0 Right
-  BCS .nr
+  AND #$80             ; bit7 = P0 Right (0 = pressed)
+  BNE .nr
   LDA P_X
   CMP #128
   BCS .nr
   INC P_X
   INC P_X
 .nr:
-  ASL                  ; bit6 = P0 Left
-  BCS .nl
+  LDA SWCHA
+  AND #$40             ; bit6 = P0 Left (0 = pressed)
+  BNE .nl
   LDA P_X
   CMP #28
   BCC .nl
@@ -270,6 +276,21 @@ MAIN:
   STA E1_Y
   LDA #182
   STA E2_Y
+  ; Re-randomize BOTH lanes on crash (FRAME-derived). The old code only
+  ; reset Y, so after a crash the enemy kept its old X — crash into it
+  ; once near the left edge and it respawned in the same column forever
+  ; ("enemy car stuck to the left edge").
+  LDA FRAME
+  AND #$3F
+  CLC
+  ADC #40
+  STA E1_X
+  LDA FRAME
+  EOR #$2A
+  AND #$3F
+  CLC
+  ADC #44
+  STA E2_X
   LDA #$08             ; noisy crash
   STA AUDC0
   LDA #$1F

package/examples/atari2600/templates/shmup.asm

@@ -131,17 +131,23 @@ MAIN:
   LDA FRAME
   AND #$01
   BNE .skipmove
+  ; SWCHA is active-LOW (0 = pressed). RE-LOAD it for each direction —
+  ; the old ASL carry-chain clobbered A with LDA P_X between shifts, so
+  ; the second ASL shifted P_X instead of SWCHA: pressing RIGHT also
+  ; "pressed" LEFT (P_X < $80 -> carry clear) and the moves cancelled.
+  ; That was the "ship/car stuck to the left edge" bug.
   LDA SWCHA
-  ASL                  ; bit7 = P0 Right
-  BCS .nr
+  AND #$80             ; bit7 = P0 Right (0 = pressed)
+  BNE .nr
   LDA P_X
   CMP #140
   BCS .nr
   INC P_X
   INC P_X
 .nr:
-  ASL                  ; bit6 = P0 Left
-  BCS .nl
+  LDA SWCHA
+  AND #$40             ; bit6 = P0 Left (0 = pressed)
+  BNE .nl
   LDA P_X
   CMP #10
   BCC .nl
@@ -220,10 +226,29 @@ MAIN:
   STA ALIEN_DIR
   LDA ALIEN_Y
   CMP #30
-  BCC .noMarch         ; already near the bottom — don't go further
+  BCC .invaded         ; reached the cannon's row — the aliens GOT YOU
   SEC
   SBC #6
   STA ALIEN_Y
+  JMP .noMarch
+.invaded:
+  ; Game over: the old code just CLAMPED here, so the aliens sat on top
+  ; of the cannon doing nothing ("gets hit by aliens which don't kill
+  ; it"). Now: harsh buzz + the wave resets to the top, like a life lost.
+  LDA #40
+  STA ALIEN_X
+  LDA #60
+  STA ALIEN_Y
+  LDA #1
+  STA ALIEN_DIR
+  LDA #$08             ; noise
+  STA AUDC0
+  LDA #$1F
+  STA AUDF0
+  LDA #$0E
+  STA AUDV0
+  LDA #20
+  STA SFX_LEFT
 .noMarch:
 
   ; sfx countdown