romdevtools 0.27.0 → 0.29.0

package/src/mcp/tools/disasm.js

@@ -1105,6 +1105,7 @@ function absolutizeBuild(build, outputDir) {
       out[key] = m;
     }
   }
+  if (out.linkerConfigPath) out.linkerConfigPath = nodePath.join(outputDir, out.linkerConfigPath);
   return out;
 }
 
@@ -1148,12 +1149,16 @@ export function registerDisasmTools(server, z) {
     "`endAddress`/`untilReturn` for one routine, `dataRanges` to mark non-code, `bank` for a banked slot. " +
     "pce/msx are 'project'-only here — 'rom' doesn't map them yet.\n" +
     "'project' = turn a ROM into a complete re-buildable disassembly in one call across all systems; splits into " +
-    "regions, REASSEMBLES each and verifies BYTE-EXACT (`roundTripOk`); non-faithful lines fall back to `.byte` so " +
-    "it ALWAYS rebuilds; `readablePercent` reports instruction-vs-data. (SNES 65816 usually lands at the byte-exact " +
+    "regions (PER-BANK on every banked format: NES mappers, SNES LoROM, GB MBC, Sega-mapper SMS/GG, MSX megaROM, " +
+    "2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards), REASSEMBLES each and verifies BYTE-EXACT (`roundTripOk`); " +
+    "non-faithful lines fall back to `.byte` so it ALWAYS rebuilds; `readablePercent` reports instruction-vs-data. " +
+    "NES/C64/7800/Lynx/PCE ship a one-call `build()` rebuild in rebuild.json (flat AND banked); the rest ship a " +
+    "proven native recipe in BUILD.md. (SNES 65816 usually lands at the byte-exact " +
     "data-only floor — its `.a8/.i8` width state desyncs when instructions and pinned `.byte` mix.)\n" +
     "'references' = scan a ROM's code for operands matching a CPU `address` and classify each (call/jump/branch/" +
-    "read/write); also walks the vector table. LIMITATION: direct addressing only (indirect/computed jumps + " +
-    "cross-bank refs are missed).",
+    "read/write); also walks the vector table. Banked carts are scanned PER BANK (all of the formats above) — " +
+    "refs carry `prgBank` (NES) / `romBank` (everything else). LIMITATION: direct addressing only " +
+    "(indirect/computed jumps are missed).",
     {
       target: z.enum(["bytes", "rom", "project", "references"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = find refs to an address."),
       // shared
@@ -1314,9 +1319,26 @@ function planRegions(platform, data) {
     return regions;
   }
   if (platform === "sms" || platform === "gg") {
-    // Z80 mapped at $0000; one region for the whole ROM (Sega mapper banks
-    // beyond 48KB are rarer in homebrew — treat as flat for now).
-    regions.push({ name: "rom", file: "rom.asm", bytes: trimTrailingPad(data.slice(0)), startAddress: 0x0000, fileOffset: 0, label: "ROM ($0000)" });
+    // Z80 mapped at $0000. ≤48KB fits the three slots flat — one region.
+    // Bigger carts use the Sega mapper: 16KB banks, banks 0-1 fixed in slots
+    // 0-1 ($0000/$4000), banks 2+ page into slot 2 ($8000) — one region per
+    // bank so instructions never straddle a bank edge and every bank gets a
+    // correct base address.
+    if (data.length <= 0xC000) {
+      regions.push({ name: "rom", file: "rom.asm", bytes: trimTrailingPad(data.slice(0)), startAddress: 0x0000, fileOffset: 0, label: "ROM ($0000)" });
+      return regions;
+    }
+    const BANK = 0x4000;
+    for (let off = 0; off < data.length; off += BANK) {
+      const idx = off / BANK;
+      const org = idx === 0 ? 0x0000 : idx === 1 ? 0x4000 : 0x8000;
+      regions.push({
+        name: `bank${idx}`, file: `bank${idx}.asm`,
+        bytes: data.slice(off, off + BANK),
+        startAddress: org, fileOffset: off,
+        label: `Sega-mapper bank ${idx}${idx < 2 ? ` (fixed $${org.toString(16).toUpperCase()})` : " (slot 2, $8000)"}`,
+      });
+    }
     return regions;
   }
   if (platform === "genesis") {
@@ -1334,12 +1356,58 @@ function planRegions(platform, data) {
     return regions;
   }
   if (platform === "atari2600") {
-    regions.push({ name: "rom", file: "rom.asm", bytes: data.slice(0), startAddress: 0xF000, fileOffset: 0, label: "4KB cart @ $F000" });
+    // 4KB carts map flat at $F000. Banked carts (F8=8KB, F6=16KB, F4=32KB)
+    // page 4KB banks into the SAME $F000 window — one region per bank.
+    if (data.length <= 0x1000) {
+      regions.push({ name: "rom", file: "rom.asm", bytes: data.slice(0), startAddress: 0xF000, fileOffset: 0, label: "4KB cart @ $F000" });
+      return regions;
+    }
+    const BANK = 0x1000;
+    for (let off = 0; off < data.length; off += BANK) {
+      const idx = off / BANK;
+      regions.push({
+        name: `bank${idx}`, file: `bank${idx}.asm`,
+        bytes: data.slice(off, off + BANK),
+        startAddress: 0xF000, fileOffset: off,
+        label: `banked cart 4KB bank ${idx} @ $F000`,
+      });
+    }
     return regions;
   }
   if (platform === "atari7800") {
-    const org = 0x10000 - data.length; // cart maps to top of address space
-    regions.push({ name: "rom", file: "rom.asm", bytes: data.slice(0), startAddress: org & 0xFFFF, fileOffset: 0, label: `cart @ $${(org & 0xFFFF).toString(16)}` });
+    // ≤48KB carts map flat at the top of the address space. SuperGame banked
+    // carts (>48KB) page 16KB banks into $8000-$BFFF with the LAST bank fixed
+    // at $C000. A 128-byte .a78 header (magic "ATARI7800" at offset 1) is
+    // split into its own data region so the cart banks stay 16KB-aligned.
+    const hasA78 = data.length >= 17 &&
+      String.fromCharCode(...data.subarray(1, 10)) === "ATARI7800";
+    const base = hasA78 ? 128 : 0;
+    const cartLen = data.length - base;
+    if (cartLen <= 0xC000) {
+      const org = 0x10000 - data.length; // header kept in-region (proven flat path)
+      regions.push({ name: "rom", file: "rom.asm", bytes: data.slice(0), startAddress: org & 0xFFFF, fileOffset: 0, label: `cart @ $${(org & 0xFFFF).toString(16)}` });
+      return regions;
+    }
+    if (hasA78) {
+      regions.push({
+        name: "a78_header", file: "a78_header.asm", bytes: data.slice(0, 128), kind: "data",
+        startAddress: 0x0000, fileOffset: 0,
+        label: ".a78 header (128 B data)",
+      });
+    }
+    const BANK = 0x4000;
+    const nBanks = Math.ceil(cartLen / BANK);
+    for (let b = 0; b < nBanks; b++) {
+      const isFixedTop = b === nBanks - 1;
+      const org = isFixedTop ? 0xC000 : 0x8000;
+      const fileOffset = base + b * BANK;
+      regions.push({
+        name: `bank${b}`, file: `bank${b}.asm`,
+        bytes: data.slice(fileOffset, fileOffset + BANK),
+        startAddress: org, fileOffset,
+        label: `SuperGame bank ${b}${isFixedTop ? " (fixed $C000)" : " (switchable $8000)"}`,
+      });
+    }
     return regions;
   }
   if (platform === "lynx") {
@@ -1363,30 +1431,83 @@ function planRegions(platform, data) {
     return regions;
   }
   if (platform === "pce") {
-    // PC Engine HuCard: the HuC6280 (65C02-family) image. cc65 pce.cfg maps the
-    // reset/IRQ vectors at $FFF6+ and the program high; homebrew typically runs
-    // from the ROM mapped at the top of the address space. Disassemble the image
-    // as a flat region from the cart base — a HuCard has no header to strip.
-    const body = trimTrailingPad(data.slice(0));
-    const org = (0x10000 - body.length) & 0xffff; // cart maps to top of space
-    regions.push({
-      name: "rom", file: "rom.asm", bytes: body,
-      startAddress: org, fileOffset: 0,
-      label: `HuCard @ $${org.toString(16)} (HuC6280)`,
-    });
+    // PC Engine HuCard: the HuC6280 (65C02-family) image, banked in 8KB pages
+    // via the MPRs. A 512-byte copier header (len % 1024 == 512) is split into
+    // its own data region. NO trailing-pad trim — HuCard $FF padding is REAL
+    // cart bytes and trimming it made the old rebuild lossy (the planner's own
+    // notes flagged this as the fix needed).
+    //   ≤32KB: flat at the top of the address space (vectors at $FFF6+ land
+    //          correctly — the proven small-HuCard assumption).
+    //   >32KB: one region per 8KB page; page 0 at $E000 (where MPR7 maps it
+    //          at reset — the vectors live there), pages 1+ at $8000 (neutral
+    //          window; bank registers decide at runtime).
+    const hasCopier = (data.length % 1024) === 512;
+    const base = hasCopier ? 512 : 0;
+    if (hasCopier) {
+      regions.push({
+        name: "copier_header", file: "copier_header.asm", bytes: data.slice(0, 512), kind: "data",
+        startAddress: 0x0000, fileOffset: 0,
+        label: "512-byte copier header (data)",
+      });
+    }
+    const body = data.subarray(base);
+    if (body.length <= 0x8000) {
+      const org = (0x10000 - body.length) & 0xffff;
+      regions.push({
+        name: "rom", file: "rom.asm", bytes: body.slice(0),
+        startAddress: org, fileOffset: base,
+        label: `HuCard @ $${org.toString(16)} (HuC6280)`,
+      });
+      return regions;
+    }
+    const PAGE = 0x2000;
+    const nPages = Math.ceil(body.length / PAGE);
+    for (let b = 0; b < nPages; b++) {
+      const org = b === 0 ? 0xE000 : 0x8000;
+      regions.push({
+        name: `page${b}`, file: `page${b}.asm`,
+        bytes: body.slice(b * PAGE, (b + 1) * PAGE),
+        startAddress: org, fileOffset: base + b * PAGE,
+        label: `HuCard 8KB page ${b}${b === 0 ? " (reset MPR7 → $E000, vectors)" : " ($8000 ASSUMED — MPRs map pages at runtime)"}`,
+      });
+    }
     return regions;
   }
   if (platform === "msx") {
     // MSX cartridge maps at $4000-$BFFF; the 16-byte "AB" header at $4000 is
-    // data (magic + INIT/STATEMENT/DEVICE/TEXT pointers), code follows. Skip the
-    // header and disassemble the Z80 image from $4010.
+    // data (magic + INIT/STATEMENT/DEVICE/TEXT pointers), code follows.
+    //   ≤32KB: skip the header, one flat region from $4010.
+    //   >32KB (megaROM): 16KB banks via an ASCII16-style mapper — bank 0 at
+    //   $4000 (header split out as a data region), banks 1+ at $8000.
     const hdr = data.length >= 2 && data[0] === 0x41 && data[1] === 0x42;
     const base = hdr ? 16 : 0;
-    regions.push({
-      name: "rom", file: "rom.asm", bytes: trimTrailingPad(data.slice(base)),
-      startAddress: 0x4000 + base, fileOffset: base,
-      label: `cart @ $${(0x4000 + base).toString(16)} (Z80)`,
-    });
+    if (data.length <= 0x8000 + base) {
+      regions.push({
+        name: "rom", file: "rom.asm", bytes: trimTrailingPad(data.slice(base)),
+        startAddress: 0x4000 + base, fileOffset: base,
+        label: `cart @ $${(0x4000 + base).toString(16)} (Z80)`,
+      });
+      return regions;
+    }
+    if (hdr) {
+      regions.push({
+        name: "ab_header", file: "ab_header.asm", bytes: data.slice(0, 16), kind: "data",
+        startAddress: 0x4000, fileOffset: 0,
+        label: `"AB" cartridge header (16 B data @ $4000)`,
+      });
+    }
+    const BANK = 0x4000;
+    const nBanks = Math.ceil(data.length / BANK);
+    for (let b = 0; b < nBanks; b++) {
+      const skip = b === 0 ? base : 0;
+      const org = b === 0 ? 0x4000 + base : 0x8000;
+      regions.push({
+        name: `bank${b}`, file: `bank${b}.asm`,
+        bytes: data.slice(b * BANK + skip, (b + 1) * BANK),
+        startAddress: org, fileOffset: b * BANK + skip,
+        label: `megaROM 16KB bank ${b}${b === 0 ? ` ($${org.toString(16)})` : " ($8000 ASSUMED — mapper pages at runtime)"}`,
+      });
+    }
     return regions;
   }
   if (platform === "gba") {

package/src/mcp/tools/find-references.js

@@ -7,7 +7,7 @@
 // though they're not "instructions" per se.
 
 import { readFile } from "node:fs/promises";
-import { mapSnesAddress, mapAtari2600Address, mapAtari7800Address, mapC64Address } from "./disasm.js";
+import { mapAtari2600Address, mapC64Address } from "./disasm.js";
 
 /**
  * Classify a referring instruction by its mnemonic.
@@ -75,8 +75,9 @@ function scanAsmForReferences(asm, targetAddr, sourceLabels) {
     // Match: any `$XXXX` (or `$XX:XXXX`) in operand that resolves to target,
     // OR the LXXXX auto-label for the target address, OR a named label.
     let matched = false;
-    for (const m of operand.matchAll(/\$([0-9A-Fa-f]+)\b/g)) {
-      const v = parseInt(m[1], 16);
+    for (const m of operand.matchAll(/(#?)\$([0-9A-Fa-f]+)\b/g)) {
+      if (m[1] === "#") continue;   /* immediate (`lda #$02`) — a value, not an address */
+      const v = parseInt(m[2], 16);
       if (v === targetAddr || v === (targetAddr & 0xFFFF)) { matched = true; break; }
     }
     if (!matched && autoLabelRe.test(operand)) matched = true;
@@ -231,54 +232,163 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     throw new Error(`findReferences: could not detect platform for '${path}'. Pass platform explicitly.`);
   }
 
-  // Disassemble the whole code area.
+  // Disassemble the whole code area. Flat platforms produce one asm blob;
+  // BANKED carts (NES mappers, SNES LoROM, GB MBC, Sega mapper, MSX megaROM,
+  // 2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards) produce one segment PER
+  // BANK (segments[]) — a flat-blob disasm mis-addresses everything past the
+  // first bank and lets instructions straddle bank edges, which corrupts the
+  // decode stream (the 0.27.0 refsFound:0 bug, fixed for NES first and now
+  // applied to every banked platform). Refs from a segment carry a bank tag.
   let asm;
+  /** @type {{asm: string, bank: number}[] | null} */
+  let segments = null;
+  // Bound the per-bank da65/objdump fan-out on huge carts. 64 banks covers
+  // 1MB (16KB banks) / 512KB (8KB pages) — beyond that we scan the first 64
+  // and SAY SO in notes rather than silently truncating.
+  const SEGMENT_CAP = 64;
+  let segmentsCapped = 0;
   if (resolved === "nes") {
     const prgSize = data[4] * 16384;
-    const startAddress = prgSize === 16384 ? 0xC000 : 0x8000;
-    const bytes = data.slice(16, 16 + prgSize);
     const { runDa65 } = await import("../../toolchains/cc65/da65.js");
-    const r = await runDa65({ bytes, startAddress, cpu: "6502", options: ["--comments", "4"] });
-    asm = r.asm;
+    if (prgSize <= 32768) {
+      const startAddress = prgSize === 16384 ? 0xC000 : 0x8000;
+      const bytes = data.slice(16, 16 + prgSize);
+      const r = await runDa65({ bytes, startAddress, cpu: "6502", options: ["--comments", "4"] });
+      asm = r.asm;
+    } else {
+      // Banked PRG (>32KB, e.g. UxROM/MMC1/MMC3): the old code disassembled
+      // the whole PRG as ONE flat blob at $8000, which mis-addresses every
+      // bank past the first — a 128KB mapper-2 scan returned refsFound:0
+      // for bytes referenced in dozens of places (0.27.0 feedback #3).
+      // Disassemble each 16KB bank separately: switchable banks at $8000,
+      // the (conventionally fixed) last bank at $C000; tag refs with the
+      // bank index.
+      const banks = Math.floor(prgSize / 16384);
+      segments = [];
+      for (let b = 0; b < banks; b++) {
+        const bytes = data.slice(16 + b * 16384, 16 + (b + 1) * 16384);
+        const startAddress = b === banks - 1 ? 0xC000 : 0x8000;
+        const r = await runDa65({ bytes, startAddress, cpu: "6502", options: ["--comments", "4"] });
+        segments.push({ asm: r.asm, bank: b });
+      }
+    }
   } else if (resolved === "snes") {
-    const mapped = mapSnesAddress(data, 0x008000, 0x8000, mapper);
-    const startAddress = 0x008000;
+    // LoROM: 32KB banks each mapped at $xx:8000. The old code disassembled
+    // ONLY the first 32KB bank — a 1MB cart's other 31 banks were invisible.
+    // Scan every 32KB bank at $8000 (absolute 16-bit operands are bank-window
+    // addresses on LoROM), tagged with the bank index.
+    const hasHeader = (data.length % 1024) === 512;
+    const body = hasHeader ? data.subarray(512) : data;
     const { runDa65 } = await import("../../toolchains/cc65/da65.js");
-    const r = await runDa65({
-      bytes: mapped.bytes, startAddress, cpu: "65816",
-      options: ["--comments", "4"],
-      info: `RANGE { START $${(startAddress & 0xFFFF).toString(16).toUpperCase()}; END $${((startAddress + mapped.bytes.length - 1) & 0xFFFF).toString(16).toUpperCase()}; TYPE Code; ADDRMODE "MX"; };\n`,
-    });
-    asm = r.asm;
+    const BANK = 0x8000;
+    const nBanks = Math.ceil(body.length / BANK);
+    const scanBanks = Math.min(nBanks, SEGMENT_CAP);
+    segmentsCapped = nBanks - scanBanks;
+    if (nBanks <= 1) {
+      const r = await runDa65({
+        bytes: body.slice(0, BANK), startAddress: 0x008000, cpu: "65816",
+        options: ["--comments", "4"],
+        info: `RANGE { START $8000; END $${(0x8000 + Math.min(body.length, BANK) - 1).toString(16).toUpperCase()}; TYPE Code; ADDRMODE "MX"; };\n`,
+      });
+      asm = r.asm;
+    } else {
+      segments = [];
+      for (let b = 0; b < scanBanks; b++) {
+        const bytes = body.slice(b * BANK, (b + 1) * BANK);
+        const r = await runDa65({
+          bytes, startAddress: 0x008000, cpu: "65816",
+          options: ["--comments", "4"],
+          info: `RANGE { START $8000; END $${(0x8000 + bytes.length - 1).toString(16).toUpperCase()}; TYPE Code; ADDRMODE "MX"; };\n`,
+        });
+        segments.push({ asm: r.asm, bank: b });
+      }
+    }
   } else if (resolved === "sms" || resolved === "gg") {
-    // SMS: disasm slot 0+1 ($0000-$7FFF, fixed in the sega mapper).
-    // Slot 2 ($8000-$BFFF) is banked — skip cross-bank scanning for now.
-    // Native binutils z80 objdump.
-    const bytes = data.slice(0, Math.min(data.length, 0x8000));
+    // Sega mapper: slots 0+1 ($0000-$7FFF) hold banks 0-1; slot 2 ($8000-
+    // $BFFF) pages in banks 2+. The old code scanned only the first 32KB —
+    // every bank past 1 was invisible. Scan bank 0 @ $0000, bank 1 @ $4000,
+    // banks 2+ @ $8000 (their pageable window), tagged with the bank index.
     const { runObjdump } = await import("../../toolchains/objdump.js");
-    asm = (await runObjdump({ bytes, arch: "z80", startAddress: 0x0000 })).asm;
+    if (data.length <= 0x8000) {
+      asm = (await runObjdump({ bytes: data.slice(0), arch: "z80", startAddress: 0x0000 })).asm;
+    } else {
+      const BANK = 0x4000;
+      const nBanks = Math.ceil(data.length / BANK);
+      const scanBanks = Math.min(nBanks, SEGMENT_CAP);
+      segmentsCapped = nBanks - scanBanks;
+      segments = [];
+      for (let b = 0; b < scanBanks; b++) {
+        const bytes = data.slice(b * BANK, (b + 1) * BANK);
+        const startAddress = b === 0 ? 0x0000 : b === 1 ? 0x4000 : 0x8000;
+        segments.push({ asm: (await runObjdump({ bytes, arch: "z80", startAddress })).asm, bank: b });
+      }
+    }
   } else if (resolved === "gb" || resolved === "gbc") {
-    // GB: bank 0 + bank 1 default ($0000-$7FFF). SM83 via binutils' gbz80
-    // machine. Higher banks need disassembleRom + bank.
-    const bytes = data.slice(0, Math.min(data.length, 0x8000));
+    // MBC banking: bank 0 fixed at $0000, banks 1+ page into $4000-$7FFF.
+    // The old code scanned only the first 32KB (banks 0-1) — a 128KB MBC1
+    // cart's other 6 banks were invisible. Scan every 16KB bank (bank 0 @
+    // $0000, banks 1+ @ $4000), tagged with the bank index.
     const { runObjdump } = await import("../../toolchains/objdump.js");
-    asm = (await runObjdump({ bytes, arch: "gbz80", startAddress: 0x0000 })).asm;
+    if (data.length <= 0x8000) {
+      asm = (await runObjdump({ bytes: data.slice(0), arch: "gbz80", startAddress: 0x0000 })).asm;
+    } else {
+      const BANK = 0x4000;
+      const nBanks = Math.ceil(data.length / BANK);
+      const scanBanks = Math.min(nBanks, SEGMENT_CAP);
+      segmentsCapped = nBanks - scanBanks;
+      segments = [];
+      for (let b = 0; b < scanBanks; b++) {
+        const bytes = data.slice(b * BANK, (b + 1) * BANK);
+        const startAddress = b === 0 ? 0x0000 : 0x4000;
+        segments.push({ asm: (await runObjdump({ bytes, arch: "gbz80", startAddress })).asm, bank: b });
+      }
+    }
   } else if (resolved === "atari2600") {
-    // 2600 cart maps to $F000-$FFFF (top of 4 KB bank). For larger
-    // banked carts we scan the last 4 KB which is what's typically
-    // resident at boot.
-    const mapped = mapAtari2600Address(data, 0xF000, 0x1000, 0);
+    // 2600 cart maps to $F000-$FFFF. Banked carts (F8=8KB, F6=16KB, F4=32KB,
+    // …) page 4KB banks into the SAME $F000 window. The old code scanned only
+    // the boot bank — fixed: scan every 4KB bank at $F000, tagged.
     const { runDa65 } = await import("../../toolchains/cc65/da65.js");
-    const r = await runDa65({ bytes: mapped.bytes, startAddress: 0xF000, cpu: "6502", options: ["--comments", "4"] });
-    asm = r.asm;
+    if (data.length <= 0x1000) {
+      const mapped = mapAtari2600Address(data, 0xF000, 0x1000, 0);
+      const r = await runDa65({ bytes: mapped.bytes, startAddress: 0xF000, cpu: "6502", options: ["--comments", "4"] });
+      asm = r.asm;
+    } else {
+      const BANK = 0x1000;
+      const nBanks = Math.ceil(data.length / BANK);
+      segments = [];
+      for (let b = 0; b < nBanks; b++) {
+        const bytes = data.slice(b * BANK, (b + 1) * BANK);
+        const r = await runDa65({ bytes, startAddress: 0xF000, cpu: "6502", options: ["--comments", "4"] });
+        segments.push({ asm: r.asm, bank: b });
+      }
+    }
   } else if (resolved === "atari7800") {
-    // 7800 cart maps to $4000-$FFFF; agents typically focus on the top
-    // 16 KB ($C000-$FFFF) where reset+main code lives.
-    const start = 0xC000;
-    const mapped = mapAtari7800Address(data, start, 0x10000 - start, 0);
+    // 7800: flat carts (≤48KB) map at the top of the address space — scan the
+    // WHOLE cart (the old code scanned only $C000-$FFFF, hiding code at
+    // $4000-$BFFF on 32/48KB carts). SuperGame banked carts (>48KB) page
+    // 16KB banks into $8000-$BFFF with the last bank fixed at $C000 — scan
+    // per-bank, tagged. A 128-byte .a78 header is stripped if present.
+    const hasA78 = data.length >= 17 &&
+      String.fromCharCode(...data.subarray(1, 10)) === "ATARI7800";
+    const cart = hasA78 ? data.subarray(128) : data;
     const { runDa65 } = await import("../../toolchains/cc65/da65.js");
-    const r = await runDa65({ bytes: mapped.bytes, startAddress: start, cpu: "6502", options: ["--comments", "4"] });
-    asm = r.asm;
+    if (cart.length <= 0xC000) {
+      const start = (0x10000 - cart.length) & 0xFFFF;
+      const r = await runDa65({ bytes: cart.slice(0), startAddress: start, cpu: "6502", options: ["--comments", "4"] });
+      asm = r.asm;
+    } else {
+      const BANK = 0x4000;
+      const nBanks = Math.ceil(cart.length / BANK);
+      const scanBanks = Math.min(nBanks, SEGMENT_CAP);
+      segmentsCapped = nBanks - scanBanks;
+      segments = [];
+      for (let b = 0; b < scanBanks; b++) {
+        const bytes = cart.slice(b * BANK, (b + 1) * BANK);
+        const startAddress = b === nBanks - 1 ? 0xC000 : 0x8000;
+        const r = await runDa65({ bytes, startAddress, cpu: "6502", options: ["--comments", "4"] });
+        segments.push({ asm: r.asm, bank: b });
+      }
+    }
   } else if (resolved === "c64") {
     // c64 .prg: 2-byte load addr + code. Disasm from the load addr through
     // EOF. For typical BASIC-stub programs that's $0801 + a few KB.
@@ -308,21 +418,58 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     const { runObjdump } = await import("../../toolchains/objdump.js");
     asm = (await runObjdump({ bytes, arch: "m68k", startAddress: start })).asm;
   } else if (resolved === "pce") {
-    // PC Engine HuCard: HuC6280 (65C02 superset). da65 has an explicit huc6280
-    // CPU mode. The cart maps to the top of the address space (no header).
-    const body = data.slice(0);
-    const start = (0x10000 - body.length) & 0xffff;
+    // PC Engine HuCard: HuC6280 (65C02 superset), 8KB pages mapped via the
+    // MPRs. ≤32KB images map flat at the top of the address space (the old
+    // assumption — correct there). Bigger HuCards are banked: the old code
+    // computed a WRAPPED start address (garbage for >64KB) — fixed: scan
+    // every 8KB page, page 0 at $E000 (where MPR7 maps it at reset — the
+    // vectors live there), pages 1+ at $8000 (a neutral MPR4 window; the
+    // base only affects branch-target/auto-label matching, absolute operands
+    // match regardless). A 512-byte copier header is stripped if present.
+    const hasCopier = (data.length % 1024) === 512;
+    const body = hasCopier ? data.subarray(512) : data;
     const { runDa65 } = await import("../../toolchains/cc65/da65.js");
-    const r = await runDa65({ bytes: body, startAddress: start, cpu: "huc6280", options: ["--comments", "4"] });
-    asm = r.asm;
+    if (body.length <= 0x8000) {
+      const start = (0x10000 - body.length) & 0xffff;
+      const r = await runDa65({ bytes: body.slice(0), startAddress: start, cpu: "huc6280", options: ["--comments", "4"] });
+      asm = r.asm;
+    } else {
+      const PAGE = 0x2000;
+      const nPages = Math.ceil(body.length / PAGE);
+      const scanPages = Math.min(nPages, SEGMENT_CAP);
+      segmentsCapped = nPages - scanPages;
+      segments = [];
+      for (let b = 0; b < scanPages; b++) {
+        const bytes = body.slice(b * PAGE, (b + 1) * PAGE);
+        const startAddress = b === 0 ? 0xE000 : 0x8000;
+        const r = await runDa65({ bytes, startAddress, cpu: "huc6280", options: ["--comments", "4"] });
+        segments.push({ asm: r.asm, bank: b });
+      }
+    }
   } else if (resolved === "msx") {
-    // MSX cartridge maps at $4000-$BFFF; skip the 16-byte "AB" header, then
-    // disassemble the Z80 image from $4010.
+    // MSX cartridge maps at $4000-$BFFF. MegaROMs (>32KB) page 16KB banks via
+    // an ASCII16-style mapper — the old code scanned only the first 32KB.
+    // Scan bank 0 at $4000 (its fixed home, header skipped) and banks 1+ at
+    // $8000 (the conventional second window), tagged with the bank index.
     const hdr = data.length >= 2 && data[0] === 0x41 && data[1] === 0x42;
     const base = hdr ? 16 : 0;
-    const bytes = data.slice(base, Math.min(data.length, base + 0x8000));
     const { runObjdump } = await import("../../toolchains/objdump.js");
-    asm = (await runObjdump({ bytes, arch: "z80", startAddress: 0x4000 + base })).asm;
+    if (data.length <= 0x8000 + base) {
+      const bytes = data.slice(base, Math.min(data.length, base + 0x8000));
+      asm = (await runObjdump({ bytes, arch: "z80", startAddress: 0x4000 + base })).asm;
+    } else {
+      const BANK = 0x4000;
+      const nBanks = Math.ceil(data.length / BANK);
+      const scanBanks = Math.min(nBanks, SEGMENT_CAP);
+      segmentsCapped = nBanks - scanBanks;
+      segments = [];
+      for (let b = 0; b < scanBanks; b++) {
+        const skip = b === 0 ? base : 0;
+        const bytes = data.slice(b * BANK + skip, (b + 1) * BANK);
+        const startAddress = b === 0 ? 0x4000 + base : 0x8000;
+        segments.push({ asm: (await runObjdump({ bytes, arch: "z80", startAddress })).asm, bank: b });
+      }
+    }
   } else if (resolved === "gba") {
     // GBA = ARM7TDMI, ROM maps flat at 0x08000000. Disassemble as ARM (the
     // default; Thumb regions need disassembleRom with thumb:true). Native
@@ -339,7 +486,20 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     throw new Error(`findReferences: platform '${resolved}' not supported yet.`);
   }
 
-  const refs = scanAsmForReferences(asm, address, []);
+  let refs;
+  if (segments) {
+    refs = [];
+    // NES refs keep the shipped `prgBank` tag; other banked platforms use the
+    // platform-neutral `romBank`.
+    const bankKey = resolved === "nes" ? "prgBank" : "romBank";
+    for (const seg of segments) {
+      for (const r of scanAsmForReferences(seg.asm, address, [])) {
+        refs.push({ ...r, [bankKey]: seg.bank });
+      }
+    }
+  } else {
+    refs = scanAsmForReferences(asm, address, []);
+  }
   // Add vector-table refs.
   if (resolved === "nes") {
     refs.push(...nesVectorRefs(data, address));
@@ -363,9 +523,14 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     truncated: refs.length > maxRefsReturned
       ? `${refs.length - maxRefsReturned} additional references not returned (raise maxRefsReturned).`
       : undefined,
-    notes: refs.length === 0
-      ? `No references found. Address $${address.toString(16).toUpperCase()} may be unreached, or an indirect/computed jump target.`
-      : undefined,
+    notes: [
+      refs.length === 0
+        ? `No references found. Address $${address.toString(16).toUpperCase()} may be unreached, or an indirect/computed jump target.`
+        : null,
+      segmentsCapped > 0
+        ? `Scan covered the first ${SEGMENT_CAP} banks only — ${segmentsCapped} additional bank(s) were NOT scanned (very large cart).`
+        : null,
+    ].filter(Boolean).join(" ") || undefined,
   };
 }
 

package/src/mcp/tools/frame.js

@@ -8,6 +8,7 @@ import { imageContent, jsonContent, safeTool } from "../util.js";
 import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
 import { stepInstructionCore, attachObserverFrame } from "./watch-memory.js";
 import { getRenderingContextCore } from "./rendering-context.js";
+import { humanCoDriveWarning } from "./playtest.js";
 
 // Normalize each platform's render-context into a CONSERVATIVE renderEnabled
 // (true | false | null). null = "can't tell from the registers" — verify never
@@ -244,11 +245,17 @@ export function registerFrameTools(server, z, sessionKey) {
   async function doStep({ frames }) {
       const host = getHost(sessionKey);
       const n = host.stepFrames(frames);
-      return jsonContent({
+      // Surface a co-drive conflict the moment the agent steps: a human
+      // actively playing in the playtest window means this step raced their
+      // real-time loop. Field only appears when the conflict is real.
+      const coDrive = humanCoDriveWarning(sessionKey);
+      // Livestream: the post-step frame (throttled to 1/2s per tool by the bus).
+      return attachObserverFrame(jsonContent({
         framesRun: n,
         frameCount: host.status.frameCount,
         framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight },
-      });
+        ...(coDrive ? { humanCoDriveWarning: coDrive } : {}),
+      }), host, `step ×${n}`);
   }
 
   // Contract: an image goes to disk (path) OR comes back inline (inline:true).
@@ -371,16 +378,17 @@ export function registerFrameTools(server, z, sessionKey) {
       const host = getHost(sessionKey);
       host.stepFrames(frames);
       const shot = host.screenshot();
+      const coDrive = humanCoDriveWarning(sessionKey);
       if (!inline) {
         await writeFile(outPath, Buffer.from(shot.pngBase64, "base64"));
-        const json = jsonContent({ path: outPath, frameCount: host.status.frameCount, width: shot.width, height: shot.height });
+        const json = jsonContent({ path: outPath, frameCount: host.status.frameCount, width: shot.width, height: shot.height, ...(coDrive ? { humanCoDriveWarning: coDrive } : {}) });
         json._observerImages = [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }];
         return json;
       }
       return {
         content: [
           imageContent(shot.pngBase64),
-          { type: "text", text: `stepped ${frames} → frame ${host.status.frameCount} (${shot.width}x${shot.height})` },
+          { type: "text", text: `stepped ${frames} → frame ${host.status.frameCount} (${shot.width}x${shot.height})${coDrive ? `\nWARNING: ${coDrive}` : ""}` },
         ],
       };
   }
@@ -393,7 +401,7 @@ export function registerFrameTools(server, z, sessionKey) {
     "level with 7200; prefer ONE big call.\n" +
     "'screenshot': capture the latest frame. `format:'png'` (default, exact colors) or `'ascii'` (lossy chafa text " +
     "render for agents that can't view images). `overlayBoxes` (png) draws a box per visible sprite (SNES+NES only); " +
-    "`scale` (png) resamples nearest-neighbor BOTH ways: 0<scale<1 DOWNscales (~75% fewer image tokens at 0.5), integer scale≥2 UPscales so tiny handheld targets read inline (e.g. scale:4 → GB 160x144 becomes 640x576); ascii cols/rows/symbols/colors knobs in the param hints. " +
+"`scale` (png) resamples nearest-neighbor: 0<scale<1 DOWNscales (~75% fewer image tokens at 0.5 — the useful direction, for cheap 'did it change?' checks). integer scale≥2 UPscales (pixel-duplication, e.g. scale:4 → GB 160x144 → 640x576) — but this adds NO detail (it's the same pixels enlarged) and costs MORE image tokens; the native frame already has every pixel. Prefer scale:1 (default, native). Only upscale if YOUR client renders tiny images too small to be useful AND can't zoom — and know that VLM encoders resize to a fixed resolution anyway, so it may not change what the model sees (and can slightly degrade it). ascii cols/rows/symbols/colors knobs in the param hints. " +
     "**CHEAP VERIFY: for a binary pass/fail check (theme changed? sprite present? HUD ticked?) prefer scale:0.5 or " +
     "format:'ascii' — BETTER, read the byte directly: symbols({op:'resolve', name}) → memory({op:'read'}) is a 1-byte " +
     "assertion that costs zero image tokens.**\n" +
@@ -417,7 +425,7 @@ export function registerFrameTools(server, z, sessionKey) {
       path: z.string().optional().describe("op=screenshot/stepAndShot: absolute path to write to (required unless inline:true)."),
       inline: z.boolean().default(false).describe("op=screenshot/stepAndShot: return the image in the response instead of writing to disk."),
       overlayBoxes: z.boolean().default(false).describe("op=screenshot png: draw a colored bounding box per visible sprite (SNES+NES only)."),
-      scale: z.number().gt(0).max(16).refine((s) => s <= 1 || Number.isInteger(s), { message: "scale must be 0<scale≤1 (downscale) or an integer ≥2 (upscale)" }).optional().describe("op=screenshot png: nearest-neighbor resample factor. 0<scale<1 DOWNscales (0.5 ≈ 75% fewer image tokens for cheap 'did it change?' checks); scale≥2 (integer) UPscales (nearest-neighbor — keeps pixel-art crisp) so tiny handheld targets are legible inline, e.g. scale:4 makes a GB 160x144 shot 640x576. scale=1/unset = native resolution."),
+      scale: z.number().gt(0).max(16).refine((s) => s <= 1 || Number.isInteger(s), { message: "scale must be 0<scale≤1 (downscale) or an integer ≥2 (upscale)" }).optional().describe("op=screenshot png: nearest-neighbor resample factor. DEFAULT (unset/1) = NATIVE resolution — perfect pixels, the accurate representation; use this. 0<scale<1 DOWNscales (0.5 ≈ 75% fewer image tokens — useful for cheap 'did it change?' checks). integer scale≥2 UPscales by pixel-duplication (e.g. scale:4 → GB 160x144 → 640x576): it adds NO information (same pixels enlarged), costs MORE image tokens, and since VLM encoders resize to their own fixed resolution it may not change what the model sees and can slightly degrade it. Only for clients that render tiny images too small to use and can't zoom."),
       cols: z.number().int().min(4).max(640).optional().describe("op=screenshot ascii: terminal columns (default fb_width/16)."),
       rows: z.number().int().min(4).max(480).optional().describe("op=screenshot ascii: terminal rows (default fb_height/16)."),
       symbols: z.enum(["ascii", "halfblock", "block", "quad", "sextant"]).default("ascii").describe("op=screenshot ascii: chafa symbol set."),