romdevtools 0.16.0 → 0.22.0

package/src/mcp/tools/disasm.js

@@ -208,7 +208,6 @@ function nesVectors(data) {
  */
 function snesVectors(data) {
   const copierOff = (data.length % 0x8000 === 0x200) ? 0x200 : 0;
-  const loMapper = data[copierOff + 0x7FC0 + 0x15];
   const hiMapper = data[copierOff + 0xFFC0 + 0x15];
   const isLo = !(hiMapper === 0x21 || hiMapper === 0x31);
   const headerBase = copierOff + (isLo ? 0x7FC0 : 0xFFC0);
@@ -513,7 +512,7 @@ export function mapGenesisAddress(data, cpuAddr, length) {
  *   48 KB: $4000-$FFFF (rare)
  *   144 KB SuperGame: bank-switched at $8000-$BFFF + fixed at $C000
  */
-export function mapAtari7800Address(data, cpuAddr, length, bank = 0) {
+export function mapAtari7800Address(data, cpuAddr, length, _bank = 0) {
   // Detect header. "ATARI7800" magic at offset 1.
   const hasHeader =
     data.length > 128 &&
@@ -557,7 +556,7 @@ export function mapAtari7800Address(data, cpuAddr, length, bank = 0) {
  * docs); not implemented here — pass `bank` instead and call with the raw
  * binary if you're hand-mapping.
  */
-export function mapC64Address(data, cpuAddr, length, bank = 0) {
+export function mapC64Address(data, cpuAddr, length, _bank = 0) {
   // Detect .prg by reading the load address and seeing if it makes sense.
   // (Anything is a valid load addr in theory, so we just trust the first
   // 2 bytes here.)
@@ -1013,7 +1012,7 @@ async function disassembleRomCore(args) {
 }
 
 async function disassembleProjectCore({ path: romPath, outputDir, platform }) {
-      const { reassembleForPlatform } = await import("../../toolchains/common/reassemble.js");
+      const { reassembleForPlatform, CPU_FAMILY } = await import("../../toolchains/common/reassemble.js");
       const data = new Uint8Array(await readFile(romPath));
       const resolved = platform ?? sniffPlatformFromPath(romPath);
       if (!resolved) throw new Error(`disassembleProject: could not detect platform from '${romPath}'. Pass platform explicitly.`);
@@ -1029,7 +1028,7 @@ async function disassembleProjectCore({ path: romPath, outputDir, platform }) {
         // Known-data regions (e.g. the GBA cartridge header) are emitted as a
         // clean `.byte` dump — byte-exact by construction, NOT a failed disasm.
         const r = reg.kind === "data"
-          ? { ok: true, readablePercent: 0, source: dataRegionSource(reg.bytes, reg.startAddress), note: "data region (not code)" }
+          ? { ok: true, readablePercent: 0, source: dataRegionSource(reg.bytes, reg.startAddress, CPU_FAMILY[resolved]), note: "data region (not code)" }
           : await reassembleForPlatform({ platform: resolved, bytes: reg.bytes, startAddress: reg.startAddress });
         const header = `; ${reg.label} — ${reg.bytes.length} bytes @ $${reg.startAddress.toString(16).toUpperCase()} ` +
           `(file 0x${reg.fileOffset.toString(16).toUpperCase()}), ${resolved}\n` +
@@ -1046,6 +1045,32 @@ async function disassembleProjectCore({ path: romPath, outputDir, platform }) {
 
       const allOk = out.every((r) => r.roundTripOk);
       const avgReadable = Math.round(out.reduce((s, r) => s + r.readablePercent, 0) / out.length);
+
+      // Make the project TURNKEY: write the rebuild glue (data blobs, the exact
+      // build() call, and human-readable instructions) so it rebuilds without
+      // hand-wiring a header/CHR-blob/linker .cfg. See disasm-rebuild.js.
+      const { planRebuild } = await import("./disasm-rebuild.js");
+      const plan = planRebuild(resolved, data, regions);
+      const writtenBlobs = [];
+      for (const [name, bytes] of Object.entries(plan.blobs)) {
+        await writeFile(nodePath.join(outputDir, name), bytes);
+        writtenBlobs.push({ file: name, bytes: bytes.length });
+      }
+      // Absolutize the bare filenames in the build call so the recipe is
+      // copy-pasteable as-is.
+      const absBuild = plan.build ? absolutizeBuild(plan.build, outputDir) : null;
+      if (absBuild) {
+        await writeFile(
+          nodePath.join(outputDir, "rebuild.json"),
+          JSON.stringify(absBuild, null, 2) + "\n"
+        );
+      }
+      const buildMd = renderBuildMd({
+        platform: resolved, romPath, regions: out, blobs: writtenBlobs,
+        build: absBuild, verifiable: plan.verifiable, notes: plan.notes, allOk,
+      });
+      await writeFile(nodePath.join(outputDir, "BUILD.md"), buildMd);
+
       return jsonContent({
         ok: allOk,
         path: romPath,
@@ -1053,12 +1078,64 @@ async function disassembleProjectCore({ path: romPath, outputDir, platform }) {
         regions: out,
         roundTrip: { regions: out.length, allByteExact: allOk, failed: out.filter((r) => !r.roundTripOk).map((r) => r.region) },
         readablePercentAvg: avgReadable,
+        rebuild: {
+          blobs: writtenBlobs,
+          buildCall: absBuild,        // the exact build({...}) args to reproduce the ROM
+          verifiable: plan.verifiable, // true = expected byte-identical via that call
+          buildDoc: "BUILD.md",
+          notes: plan.notes,
+        },
         note: allOk
-          ? `All ${out.length} region(s) round-trip BYTE-EXACT (avg ${avgReadable}% disassembled as instructions, the rest as .byte data). Edit the .asm files and rebuild.`
+          ? `All ${out.length} region(s) round-trip BYTE-EXACT (avg ${avgReadable}% disassembled as instructions, the rest as .byte data). ` +
+            (absBuild
+              ? `Rebuild it with the build() call in rebuild.json / BUILD.md` +
+                (plan.verifiable ? " — expected byte-identical." : " (see notes — may need linker tweaks).")
+              : `See BUILD.md for how to rebuild.`)
           : `Some regions did NOT round-trip byte-exact — see regions[].note.`,
       });
 }
 
+/** Rewrite a planRebuild build()'s bare *Paths filenames to absolute paths. */
+function absolutizeBuild(build, outputDir) {
+  const out = { ...build };
+  for (const key of ["sourcesPaths", "binaryIncludePaths", "includePaths"]) {
+    if (out[key]) {
+      const m = {};
+      for (const [virt, file] of Object.entries(out[key])) m[virt] = nodePath.join(outputDir, file);
+      out[key] = m;
+    }
+  }
+  return out;
+}
+
+/** Human + agent readable rebuild instructions for a disassembled project. */
+function renderBuildMd({ platform, romPath, regions, blobs, build, verifiable, notes, allOk }) {
+  const lines = [];
+  lines.push(`# Rebuilding this ${platform} project`, "");
+  lines.push(`Disassembled from \`${nodePath.basename(romPath)}\` by \`disasm({target:'project'})\`.`, "");
+  lines.push("## Files", "");
+  for (const r of regions) {
+    lines.push(`- \`${r.file}\` — ${r.region}${r.kind === "data" ? " (data)" : ""}, byte-exact${r.roundTripOk === false ? " ⚠ round-trip FAILED" : ""}.`);
+  }
+  for (const b of blobs) lines.push(`- \`${b.file}\` — ${b.bytes} bytes of binary data (extracted from the ROM; do not hand-edit).`);
+  lines.push("- `rebuild.json` — the exact `build()` args below, with absolute paths.", "");
+  if (build) {
+    lines.push("## Rebuild", "");
+    if (verifiable) {
+      lines.push("This rebuilds **byte-identical** to the source ROM. Call:", "");
+    } else {
+      lines.push("Rebuild call (see Notes — may need linker adjustments for an exact match):", "");
+    }
+    lines.push("```json", JSON.stringify(build, null, 2), "```", "");
+    lines.push("Pass these as the arguments to the `build` tool. The same JSON is in `rebuild.json`.", "");
+  } else {
+    lines.push("## Rebuild", "", "No automatic rebuild recipe for this platform yet. " + notes, "");
+  }
+  if (notes) lines.push("## Notes", "", notes, "");
+  if (!allOk) lines.push("> ⚠ Some regions did not round-trip byte-exact — edit those `.asm` files before rebuilding.", "");
+  return lines.join("\n") + "\n";
+}
+
 export function registerDisasmTools(server, z) {
   server.tool(
     "disasm",
@@ -1137,12 +1214,23 @@ function trimTrailingPad(bytes) {
 
 /** Emit a known-data region as a clean, byte-exact `.byte` dump (GAS/cc65 both
  *  accept `.byte` with `.org`). 16 bytes per line, with the address in a comment. */
-function dataRegionSource(bytes, startAddress) {
-  const rows = [`\t.org $${startAddress.toString(16).toUpperCase()}`];
+// Emit a byte-exact `.byte` dump for a known-DATA region (e.g. a cartridge
+// header). The syntax must match the platform's reassembler: ca65/vasm
+// (6502/65816) take `$`-prefixed hex and a bare `.org $...`; GNU `as`
+// (z80/sm83/m68k/arm) take `0x` hex and reject a `$` operand (`$2E` reads as an
+// undefined symbol → the link fails). `family` comes from CPU_FAMILY; default to
+// the ca65 form for the 6502 platforms that have used this path historically.
+function dataRegionSource(bytes, startAddress, family = "6502") {
+  const gnu = family === "z80" || family === "sm83" || family === "m68k" || family === "arm";
+  const hex = (b) => (gnu ? "0x" : "$") + b.toString(16).padStart(2, "0").toUpperCase();
+  const org = gnu
+    ? `\t.org 0x${startAddress.toString(16).toUpperCase()}`
+    : `\t.org $${startAddress.toString(16).toUpperCase()}`;
+  const rows = [org];
   for (let i = 0; i < bytes.length; i += 16) {
     const slice = Array.from(bytes.slice(i, i + 16));
     rows.push(
-      "\t.byte " + slice.map((b) => "$" + b.toString(16).padStart(2, "0").toUpperCase()).join(",") +
+      "\t.byte " + slice.map(hex).join(",") +
       `\t; ${(startAddress + i).toString(16).toUpperCase().padStart(6, "0")}`
     );
   }

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

@@ -7,8 +7,7 @@
 // though they're not "instructions" per se.
 
 import { readFile } from "node:fs/promises";
-import { jsonContent, safeTool } from "../util.js";
-import { mapNesAddress, mapSnesAddress, mapAtari2600Address, mapAtari7800Address, mapC64Address } from "./disasm.js";
+import { mapSnesAddress, mapAtari2600Address, mapAtari7800Address, mapC64Address } from "./disasm.js";
 
 /**
  * Classify a referring instruction by its mnemonic.

package/src/mcp/tools/font-map.js

@@ -16,7 +16,7 @@
 // in findEncodedText (NES/GB/GBC bank-aware, Genesis flat; SNES is mapper-
 // dependent and left to fileOffset).
 
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { jsonContent, safeTool } from "../util.js";
 import { getHost } from "../state.js";
 

package/src/mcp/tools/frame.js

@@ -5,7 +5,140 @@ import { PNG } from "pngjs";
 import { getHost } from "../state.js";
 import { imageContent, jsonContent, safeTool } from "../util.js";
 import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
-import { stepInstructionCore } from "./watch-memory.js";
+import { stepInstructionCore, attachObserverFrame } from "./watch-memory.js";
+import { getRenderingContextCore } from "./rendering-context.js";
+
+// Normalize each platform's render-context into a CONSERVATIVE renderEnabled
+// (true | false | null). null = "can't tell from the registers" — verify never
+// asserts renderDisabled on null, so a platform we can't decode just relies on
+// the pixel check. This is the cross-platform contract for frame({op:'verify'}).
+function pickRenderFlags(ctx) {
+  const p = ctx.platform;
+  try {
+    if (p === "nes") {
+      const m = ctx.nes && ctx.nes.ppumask;
+      if (!m) return { renderEnabled: null };
+      return { renderEnabled: !!(m.bgVisible || m.spritesVisible) };
+    }
+    if (p === "snes") {
+      const s = ctx.snes;
+      if (!s || !s.ppuRegistersAvailable) return { renderEnabled: null }; // regs not live yet
+      if (s.forcedBlank) return { renderEnabled: false };
+      if (s.brightness === 0) return { renderEnabled: false };
+      return { renderEnabled: true };
+    }
+    if (p === "genesis" || p === "megadrive" || p === "md") {
+      return { renderEnabled: ctx.displayEnabled == null ? null : !!ctx.displayEnabled };
+    }
+    if (p === "sms" || p === "gg") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    if (p === "gb" || p === "gbc") {
+      const l = ctx.gb && ctx.gb.lcdc ? ctx.gb.lcdc : ctx.lcdc;
+      if (!l) return { renderEnabled: null };
+      return { renderEnabled: !!l.lcdEnable };
+    }
+    if (p === "gba") {
+      if (ctx.forcedBlank) return { renderEnabled: false };
+      const anyBg = Array.isArray(ctx.displayBg) && ctx.displayBg.some(Boolean);
+      return { renderEnabled: !!(anyBg || ctx.displayObj) };
+    }
+    if (p === "pce") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    if (p === "msx") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    // atari2600 / atari7800 / lynx: no single reliable display-enable bit — let
+    // the pixel check carry it; don't false-assert.
+    return { renderEnabled: null };
+  } catch {
+    return { renderEnabled: null };
+  }
+}
+
+/**
+ * Dominant-color fraction at/above which a screen reads as "blank" to a
+ * human even though *something* technically rendered. Set to 0.92 (one color
+ * filling >=92% of the screen) — empirically the perceptual threshold where a
+ * backdrop-with-a-lone-sprite still looks empty. Below this, there's enough
+ * on-screen content that a person sees a populated frame. (Truly one/two-color
+ * frames are caught separately by the distinctColors<=1 blankScreen check.)
+ */
+const NEARLY_BLANK_DOMINANT = 0.92;
+
+/**
+ * The cross-platform render-health computation behind frame({op:'verify'}).
+ * Exported so tests can drive it per platform without the MCP wrapper.
+ * @returns plain object {verified, frame, platform, pixels, render, issues?, note}
+ */
+export async function computeVerify(host, frames, sessionKey) {
+  const platform = host.status.platform;
+  if (frames && frames > 0) host.stepFrames(frames);
+  const frameCount = host.status.frameCount;
+
+  // --- pixel content check (platform-agnostic) ---
+  const { width, height, rgba } = host.screenshotRgba();
+  const counts = new Map();
+  const total = width * height;
+  for (let i = 0; i + 3 < rgba.length; i += 4) {
+    const key = (rgba[i] << 16) | (rgba[i + 1] << 8) | rgba[i + 2];
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  let topColor = 0, topCount = 0;
+  for (const [c, n] of counts) if (n > topCount) { topCount = n; topColor = c; }
+  const distinctColors = counts.size;
+  const dominantFraction = total ? topCount / total : 1;
+  const nonDominant = total - topCount;
+  const pixels = {
+    width, height,
+    distinctColors,
+    dominantColor: "#" + topColor.toString(16).padStart(6, "0"),
+    dominantPct: Math.round(dominantFraction * 1000) / 10,
+    nonDominantPixels: nonDominant,
+  };
+
+  // --- render-enable / NMI verdict (reused, per-platform) ---
+  let render;
+  try {
+    const ctx = await getRenderingContextCore({ platform, area: "all", sessionKey });
+    render = { summary: ctx.summary || [], ...pickRenderFlags(ctx) };
+  } catch (e) {
+    render = { summary: [`(render-context decode unavailable for '${platform}': ${e.message})`], renderEnabled: null };
+  }
+
+  // --- frame-0 guard: report raw, no verdict (never cry wolf on boot) ---
+  if (frameCount === 0) {
+    return {
+      verified: null, unsettled: true, frame: 0, platform,
+      note: "No frame has been stepped yet — render state is the pre-boot default and not meaningful. " +
+        "Step frames first (frame({op:'step'}) or pass `frames`), then verify.",
+      pixels, render,
+    };
+  }
+
+  // --- fuse into a verdict + issues[] ---
+  const issues = [];
+  if (distinctColors <= 1) {
+    issues.push({ check: "blankScreen", detail: `the entire framebuffer is one color (${pixels.dominantColor}) — nothing is being drawn.` });
+  } else if (dominantFraction >= NEARLY_BLANK_DOMINANT) {
+    issues.push({ check: "nearlyBlank", detail: `${pixels.dominantPct}% of the screen is a single color (${pixels.dominantColor}); only ${nonDominant} px differ — a backdrop with almost no content reads as blank to a human even though something rendered. Add visible content (a tilemap/background, more sprites) until <${Math.round(NEARLY_BLANK_DOMINANT * 100)}% is one color.` });
+  }
+  if (render && render.renderEnabled === false) {
+    issues.push({ check: "renderDisabled", detail: `display output is disabled per the ${platform} registers: ${render.summary[0] || "see render.summary"}.` });
+  }
+
+  const ok = issues.length === 0;
+  return {
+    verified: ok,
+    frame: frameCount,
+    platform,
+    ...(ok
+      ? { note: `Frame ${frameCount}: rendering looks alive (${distinctColors} colors, ${Math.round((100 - pixels.dominantPct) * 10) / 10}% of the screen is non-backdrop).` }
+      : { issues, note: "Rendering looks broken — see issues[]. For per-platform thresholds + the full checklist, getPlatformDoc({platform, doc:'mental_model'})." }),
+    pixels, render,
+  };
+}
 
 // Get the platform's visible sprites in the generic shape, or null if
 // not supported. Drives the screenshot overlay AND any future agents
@@ -231,6 +364,29 @@ export function registerFrameTools(server, z, sessionKey) {
       return shootPng({ path: outPath, inline, overlayBoxes, scale });
   }
 
+  // op:'verify' — one-call "did the game actually render / is it alive?" health
+  // check for agents debugging WITHOUT vision. Fuses two independent signals:
+  //   1. the render-enable/NMI verdict from getRenderingContext (per-platform
+  //      register decode — already correct, reused not re-derived), and
+  //   2. a pixel-level content check on the live framebuffer (is the screen
+  //      actually showing more than one flat color?).
+  // Frame-0 guard: before any frame is stepped, report the raw condition WITHOUT
+  // an editorial verdict (so the header never "cries wolf" on boot).
+  async function doVerify({ frames }) {
+    const host = getHost(sessionKey);
+    if (!host.status.platform || !host.status.loaded) {
+      throw new Error("frame({op:'verify'}): no media loaded — loadMedia or build({output:'run'}) first.");
+    }
+    const json = jsonContent(await computeVerify(host, frames, sessionKey));
+    // verify's whole job is "look at the screen" — so push the exact frame it
+    // judged to the human's /livestream. Deferred provider: the PNG encode
+    // happens async after the agent's (JSON-only) response goes out, at zero
+    // cost to the agent. computeVerify already stepped the frames, so the
+    // host's current framebuffer IS the verified frame.
+    attachObserverFrame(json, host);
+    return json;
+  }
+
   async function doStepAndShot({ frames, path: outPath, inline }) {
       requireImageTarget(outPath, inline, "frame({op:'stepAndShot'})");
       const host = getHost(sessionKey);
@@ -252,7 +408,7 @@ export function registerFrameTools(server, z, sessionKey) {
 
   server.tool(
     "frame",
-    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'stepInstruction'.\n" +
+    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'stepInstruction' | 'verify'.\n" +
     "'step': advance N `frames` as fast as possible — NO pacing/audio/vsync. Cores run at WASM speed, so frames:3600 " +
     "(1 min of game time) finishes in ~5-30ms, cheaper than a screenshot. Don't be timid — skip a title with 300, a " +
     "level with 7200; prefer ONE big call.\n" +
@@ -265,10 +421,18 @@ export function registerFrameTools(server, z, sessionKey) {
     "'stepAndShot': step + screenshot in ONE round-trip — the drive-then-look loop. (No overlayBoxes/scale here — png only.)\n" +
     "'stepInstruction': execute exactly ONE CPU instruction and stop (finer than 'step'); freezes the CPU one " +
     "instruction later and returns { pc }. Pair with cpu({op:'read'}) to watch registers change while tracing a routine.\n" +
+    "'verify': one-call 'is the game actually rendering / alive?' health check WITHOUT vision — for the spiral where an " +
+    "agent can't see the screen and doesn't know if a black frame means broken. Pass `frames` to boot-then-check in one " +
+    "call. Fuses (1) a pixel-content scan of the live framebuffer (distinctColors, dominant-color %) and (2) the " +
+    "per-platform render-ENABLE/NMI decode (reused from the rendering-context decoder — works on all 14 platforms). " +
+    "Returns {verified:true|false|null, issues[], pixels, render}. verified:null + unsettled when no frame has been " +
+    "stepped yet (it won't cry wolf on boot — step first). issues[] flags blankScreen/nearlyBlank/renderDisabled. " +
+    "renderDisabled is only raised when the registers SAY so (never on an undecodable platform). Pass/fail with no " +
+    "image tokens; for WHAT to fix, getPlatformDoc({platform, doc:'mental_model'}).\n" +
     "IMAGE CONTRACT (screenshot/stepAndShot): the image goes to `path` (default, returns {path}) OR inline:true — " +
     "you MUST pass one. Keeps PNGs out of context unless asked.",
     {
-      op: z.enum(["step", "screenshot", "stepAndShot", "stepInstruction"]).describe("step frames; capture a screenshot; step+capture in one call; or single-step one CPU instruction."),
+      op: z.enum(["step", "screenshot", "stepAndShot", "stepInstruction", "verify"]).describe("step frames; capture a screenshot; step+capture in one call; single-step one CPU instruction; or verify the game is actually rendering/alive (no vision needed)."),
       frames: z.number().int().min(1).max(1_000_000).default(1).describe("op=step/stepAndShot: frames to advance (1-1,000,000). 36000 (10 min) usually completes in <1s — don't be conservative."),
       format: z.enum(["png", "ascii"]).default("png").describe("op=screenshot: 'png' (default, real image) or 'ascii' (lossy text render)."),
       path: z.string().optional().describe("op=screenshot/stepAndShot: absolute path to write to (required unless inline:true)."),
@@ -286,6 +450,7 @@ export function registerFrameTools(server, z, sessionKey) {
         case "screenshot":      return doScreenshot(args);
         case "stepAndShot":     return doStepAndShot(args);
         case "stepInstruction": return await stepInstructionCore(sessionKey);
+        case "verify":          return await doVerify(args);
         default: throw new Error(`frame: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/index.js

@@ -304,52 +304,3 @@ export function registerTools(server, z, sessionKey) {
   }
 }
 
-// ---- helper: which category owns a tool name? ----
-// Used so describeTool's error message can name the category to load.
-// Maintained by hand for now; if categories explode we can derive this
-// by registering each category into a dummy server and comparing diffs.
-const TOOL_OWNER = {
-  // platforms category
-  platform: "platforms",
-  // run category
-  loadMedia: "run", host: "run",
-  frame: "run",
-  // input category
-  input: "input",
-  // state category
-  state: "state",
-  // memory category
-  memory: "memory",
-  // debug category
-  tiles: "debug", sprites: "debug",
-  background: "debug", encodeArt: "assets",
-  cpu: "debug", audioDebug: "debug",
-  symbols: "debug",
-  disasm: "debug",
-  cheats: "debug",
-  inspectTile: "debug",
-  // assets category
-  encodeAudio: "assets",
-  cart: "assets",
-  listRoms: "assets", romPatch: "assets", validateRom: "assets",
-  assembleSnippet: "assets",
-
-  text: "assets",
-  importArt: "assets",
-  palette: "debug",
-  // project category
-  scaffold: "project",
-  // show category (was: advanced)
-  playtest: "show",
-  // advanced category
-  runUntil: "advanced",
-  watch: "advanced", breakpoint: "advanced",
-  recordSession: "advanced",
-  // entry tier itself
-  catalog: "entry",
-  build: "entry", listRunnableFormats: "entry",
-};
-
-function ownerCategoryOf(name) {
-  return TOOL_OWNER[name] ?? null;
-}

package/src/mcp/tools/input-layout.js

@@ -3,7 +3,6 @@
 // know exactly what each bit/id means.
 
 import { FACE_BUTTON_MAP } from "../../host/types.js";
-import { jsonContent, safeTool } from "../util.js";
 
 const HARDWARE_LAYOUTS = {
   nes: {

package/src/mcp/tools/input.js

@@ -65,18 +65,45 @@ function buttonShape(z) {
       start: z.boolean().optional(),
       select: z.boolean().optional(),
     })
+    // passthrough (not the zod default of stripping) so a TYPO'd button name
+    // ({jump:true}, {aa:true}) survives into the handler and can be reported as
+    // ignored — instead of being silently dropped, leaving the agent believing
+    // it pressed something it didn't.
+    .passthrough()
     .describe(
       "Per-port controller state. Prefer the spatial face-button names (north/east/south/west) for cross-platform code — they map to the physical button in that compass position on each platform's controller (e.g. on NES east=A, on SNES east=A, on Genesis east=C). Raw libretro names (a/b/x/y/l/r/...) also work if you need direct control. Omitted buttons are released.",
     );
 }
 
+// Every button key portInputToMask + the spatial resolver actually honor.
+// Anything else in a `ports` object is a typo and gets reported, not pressed.
+const KNOWN_BUTTONS = new Set([
+  "up", "down", "left", "right",
+  "north", "east", "south", "west",
+  "a", "b", "x", "y", "l", "r", "l2", "r2", "l3", "r3", "start", "select",
+]);
+
 // ── *Core functions for the `input` tool ──
 
 /** op:'set' — set held controller state (persists until changed). */
 function inputSetCore({ ports }, sessionKey) {
+      // Flag any key that isn't a real button BEFORE we set input — a typo
+      // ({jump:true}) would otherwise resolve to nothing and press silently.
+      const ignoredButtons = [];
+      ports.forEach((p, port) => {
+        for (const k of Object.keys(p)) {
+          if (p[k] === true && !KNOWN_BUTTONS.has(k)) ignoredButtons.push({ port, name: k });
+        }
+      });
       getHost(sessionKey).setInput({ ports });
-      const requested = ports.map((p) => Object.keys(p).filter((k) => p[k] === true));
-      return { inputSet: true, requested };
+      const requested = ports.map((p) => Object.keys(p).filter((k) => p[k] === true && KNOWN_BUTTONS.has(k)));
+      return {
+        inputSet: true,
+        requested,
+        ...(ignoredButtons.length
+          ? { ignoredButtons, ignoredNote: `Ignored ${ignoredButtons.length} unknown button name(s) — not pressed. Valid: ${[...KNOWN_BUTTONS].join(", ")}.` }
+          : {}),
+      };
 }
 
 /** op:'press' — press one named button N frames then release (port 0 default). */
@@ -168,7 +195,10 @@ export function registerInputTools(server, z, sessionKey) {
   server.tool(
     "input",
     "Drive the controller. `op`: 'set' | 'press' | 'sequence' | 'navigate' | 'layout'.\n" +
-    "'set': hold controller state (persists until changed) via `ports:[{a:true,...},{...}]`.\n" +
+    "'set': hold controller state (persists until changed) via `ports:[{a:true,...},{...}]`. " +
+    "The held state is honored by frame({op:'step'}) AND by watch/breakpoint runs that have NO `pressDuring` " +
+    "schedule (they inherit it). If a watch/breakpoint IS given `pressDuring`, that schedule OWNS the pad for " +
+    "the run and this set state is ignored — so drive a watched window with `pressDuring`, not a prior `set`.\n" +
     "'press': press one named `button` for `frames` then release (port 0 default).\n" +
     "'sequence': scripted frame-by-frame `steps:[{input:{ports}, frames}]` for replays/tests.\n" +
     "'navigate': walk a menu by advancing on SCREEN CHANGE — `steps:[{button, holdFrames?, maxWaitFrames?, " +

package/src/mcp/tools/lifecycle.js

@@ -1,6 +1,5 @@
 import { resolveCore } from "../../cores/registry.js";
-import { defaultMediaKind } from "../../host/index.js";
-import { clearHost, getHost, getHostOrNull, resetHost } from "../state.js";
+import { clearHost, getHost, getHostOrNull, rememberLastMedia, resetHost } from "../state.js";
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
 
@@ -19,7 +18,10 @@ export function registerLifecycleTools(server, z, sessionKey) {
     await host.loadMedia({
       platform,
       ...(bytes ? { bytes, virtualName } : { path }),
-      mediaKind: mediaKind ?? defaultMediaKind(platform),
+      // Only force a mediaKind when the caller picked one; otherwise let the host
+      // derive it from the file extension (a C64 .d64 → "disk", .tap → "tape",
+      // .prg → "program") so status reports the kind honestly.
+      ...(mediaKind ? { mediaKind } : {}),
     });
 
     // Pre-seed cheats BEFORE the first frame — so a boot-time cheat (e.g. a Game
@@ -42,6 +44,13 @@ export function registerLifecycleTools(server, z, sessionKey) {
         }
       });
     }
+    // Remember what we loaded so a later host eviction (restart/reconnect) can
+    // tell the agent the exact loadMedia call to recover with. Survives reset.
+    rememberLastMedia(sessionKey, {
+      platform,
+      ...(bytes ? { fromBase64: true } : { path: host.status.mediaPath ?? path }),
+    });
+
     // Framebuffer dimensions are NOT known until the core has run at least one
     // frame — before that, fbWidth/fbHeight hold a pre-boot default (e.g.
     // 256×192 on Genesis) that does NOT match the real output resolution
@@ -101,7 +110,12 @@ export function registerLifecycleTools(server, z, sessionKey) {
       switch (op) {
         case "unload": {
           const host = getHostOrNull(sessionKey);
-          if (host) host.unloadMedia();
+          if (!host || !host.status.loaded) {
+            // Don't claim success when there was nothing loaded — that masks a
+            // session/state mix-up (the agent thinks it unloaded media it never had).
+            return textContent("nothing to unload — no media is loaded in this session");
+          }
+          host.unloadMedia();
           return textContent("unloaded");
         }
         case "shutdown":

package/src/mcp/tools/lospec.js

@@ -4,7 +4,6 @@
 // per-palette overrides.
 
 import { jsonContent, safeTool } from "../util.js";
-import { resolveIntent } from "../../platforms/common/intent.js";
 import { inspectPaletteCore, getPlatformMasterPaletteCore } from "./platform-tools.js";
 
 /** lospec.com hosts each palette at https://lospec.com/palette-list/<id>.json. */
@@ -61,24 +60,6 @@ async function fetchLospecPalette(id) {
   };
 }
 
-/**
- * Snap each color in `palette` to the nearest entry in `master`.
- * Used when the caller wants a lospec palette but the platform has a
- * fixed hardware palette (NES 2C02 master, etc.).
- */
-function snapToMaster(palette, master) {
-  return palette.map(([r, g, b]) => {
-    let best = master[0];
-    let bestD = Infinity;
-    for (const [mr, mg, mb] of master) {
-      const dr = r - mr, dg = g - mg, db = b - mb;
-      const d = dr * dr + dg * dg + db * db;
-      if (d < bestD) { bestD = d; best = [mr, mg, mb]; }
-    }
-    return best;
-  });
-}
-
 /**
  * Programmatic equivalent of the MCP tool. Exported for tests.
  *

package/src/mcp/tools/platform-docs.js

@@ -16,7 +16,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { readFile, stat } from "node:fs/promises";
 
-import { jsonContent, safeTool, textContent } from "../util.js";
+import { jsonContent } from "../util.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/src/mcp/tools/platform-tools.js

@@ -6,7 +6,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { getHost } from "../state.js";
-import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
+import { imageContent, jsonContent } from "../util.js";
 
 // Consolidation: several handlers in this big shared file are extracted as
 // *Core functions that the consolidated domain tools (palette/tiles/background/
@@ -37,10 +37,10 @@ import { getNesApuState } from "../../host/nes-apu-state.js";
 import { decodeGenesisPSG, decodeGenesisYM2612 } from "../../host/gpgx-state.js";
 import { decodeGbApu, decodeGbaApu } from "../../host/gb-apu-state.js";
 import { decodeC64Sid } from "../../host/c64-sid-state.js";
-import { decodeLynxMikey, decodeLynxPalette, decodeLynxRenderingContext } from "../../host/lynx-mikey-state.js";
+import { decodeLynxMikey, decodeLynxPalette } from "../../host/lynx-mikey-state.js";
 import { getPcePsgState } from "../../host/pce-psg-state.js";
 import { getMsxAyState } from "../../host/msx-ay-state.js";
-import { decodeGbaSprites, decodeGbaPalette, decodeGbaRenderingContext } from "../../host/gba-video-state.js";
+import { decodeGbaSprites, decodeGbaPalette } from "../../host/gba-video-state.js";
 
 /** Resolve the platform to inspect: explicit arg → currently loaded host. */
 function resolvePlatform(host, requested) {
@@ -119,7 +119,7 @@ export function registerPlatformTools(server, z, sessionKey) {
         // SMS tiles live in VRAM at runtime — the cart has no fixed CHR
         // region. Render all 448 tiles (the entire 16KB VRAM mapped to
         // tiles), using the live first-BG-palette so colors look right.
-        const { snapshotPatternTiles, snapshotPalette } = await import("../../platforms/sms/vdp.js");
+        const { snapshotPalette } = await import("../../platforms/sms/vdp.js");
         const { colors } = snapshotPalette(host, p);
         // Use BG palette (entries 0..15) for rendering.
         const bgPal = colors.slice(0, 16).map((c) => [c.r, c.g, c.b]);