romdevtools 0.27.0 → 0.29.0

package/src/mcp/tools/index.js

@@ -24,7 +24,7 @@ import { registerInputTools } from "./input.js";
 import { registerStateTools } from "./state.js";
 import { registerMemoryTools } from "./memory.js";
 import { registerToolchainTools } from "./toolchain.js";
-import { registerPlaytestTools } from "./playtest.js";
+import { registerPlaytestTools, getPlaytestHumanStatus } from "./playtest.js";
 import { registerPlatformTools as registerPlatformSpecificTools } from "./platform-tools.js";
 import { registerPlatformTools } from "./platforms.js";
 import { registerSymbolTools } from "./symbols.js";
@@ -87,7 +87,7 @@ const CATEGORIES = [
   {
     name: "platforms",
     description: "Discover supported platforms, their cores, toolchains, and language matrices.",
-    useWhen: ["scaffolding a new project", "checking which platforms are available", "looking up a platform's default language"],
+    useWhen: ["before forking an example for a new game", "checking which platforms are available", "looking up a platform's default language"],
     register: (s, z, k) => registerPlatformTools(s, z, k), // listPlatforms, resolvePlatform
   },
   {
@@ -138,8 +138,8 @@ const CATEGORIES = [
   },
   {
     name: "project",
-    description: "Project scaffolding + starter snippets per platform.",
-    useWhen: ["starting a new game from scratch", "looking up canonical patterns like NMI handler, OAM DMA, joypad read"],
+    description: "The example-game library (fork/list/show) + starter snippets per platform.",
+    useWhen: ["starting a new game (ALWAYS fork the nearest example — never a blank file)", "looking up canonical patterns like NMI handler, OAM DMA, joypad read"],
     register: (s, z, k) => { registerProjectTools(s, z, k); registerSnippetTools(s, z, k); registerPlatformDocsTools(s, z); },
   },
   {
@@ -199,9 +199,23 @@ export function registerTools(server, z, sessionKey) {
         const base = host
           ? { ...host.getStatus() }
           : { loaded: false, hint: "no host yet; call loadMedia (in category 'run') to load a ROM" };
+        // Human co-drive signals: an agent re-grounding mid-session needs to
+        // know a human is playing in a playtest window BEFORE it fights them
+        // for input/stepping (pause, or use a second session).
+        const human = getPlaytestHumanStatus(sessionKey);
         return jsonContent({
           romdevVersion: PKG_VERSION,
           ...base,
+          playtestWindowOpen: human.windowOpen,
+          ...(human.windowOpen
+            ? {
+                humanInputActive: human.humanInputActive,
+                ...(human.framesSinceHumanInput != null ? { framesSinceHumanInput: human.framesSinceHumanInput } : {}),
+                ...(human.humanInputActive
+                  ? { humanInputNote: "A human is ACTIVELY playing in the playtest window — their input overwrites yours each tick and real-time stepping races yours. host({op:'pause'}) to inspect, or use a second session (different x-romdev-session) for deterministic work." }
+                  : {}),
+              }
+            : {}),
           loadedCategories: cats.filter((c) => c.loaded).map((c) => c.name),
           unloadedCategories: cats.filter((c) => !c.loaded).map((c) => c.name),
         });

package/src/mcp/tools/input.js

@@ -1,6 +1,17 @@
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { getInputLayoutCore } from "./input-layout.js";
+import { humanCoDriveWarning } from "./playtest.js";
+import { attachObserverFrame } from "./watch-memory.js";
+
+// Spreadable co-drive conflict marker for every input-driving op: while a
+// human is actively playing in this session's playtest window, their input
+// overwrites the agent's each tick — so the agent must be TOLD its press/set
+// may not take. Empty (no field) when there's no conflict.
+function coDriveFields(sessionKey) {
+  const warning = humanCoDriveWarning(sessionKey);
+  return warning ? { humanCoDriveWarning: warning } : {};
+}
 
 // Resolve a platform-native button alias to the libretro button the host
 // understands. Genesis pads have A/B/C (+ X/Y/Z on 6-button) which libretro
@@ -103,6 +114,7 @@ function inputSetCore({ ports }, sessionKey) {
         ...(ignoredButtons.length
           ? { ignoredButtons, ignoredNote: `Ignored ${ignoredButtons.length} unknown button name(s) — not pressed. Valid: ${[...KNOWN_BUTTONS].join(", ")}.` }
           : {}),
+        ...coDriveFields(sessionKey),
       };
 }
 
@@ -110,6 +122,13 @@ function inputSetCore({ ports }, sessionKey) {
 function inputPressCore({ button, frames = 2, port: p = 0 }, sessionKey) {
       const host = getHost(sessionKey);
       const resolved = resolveButtonAlias(button, host.status.platform);
+      // GUARANTEE a released->pressed EDGE. If the button is already held
+      // (a prior input({op:'set'}) or an overlapping schedule), the game's
+      // newpress detector never fires and the press silently does nothing —
+      // the "one-shot press didn't pause the game" report (0.27.0 #7).
+      // One released frame first makes the edge unconditional.
+      host.setInput({ ports: [{}, {}] });
+      host.stepFrames(1);
       const pressed = { ports: [{}, {}] };
       pressed.ports[p][resolved] = true;
       host.setInput(pressed);
@@ -121,8 +140,10 @@ function inputPressCore({ button, frames = 2, port: p = 0 }, sessionKey) {
         ...(resolved !== button ? { resolvedTo: resolved } : {}),
         frames,
         releaseFrames: 1,
-        framesStepped: frames + 1,
+        preReleaseFrames: 1,
+        framesStepped: frames + 2,
         frameCount: host.status.frameCount,
+        ...coDriveFields(sessionKey),
       };
 }
 
@@ -135,7 +156,7 @@ function inputSequenceCore({ steps }, sessionKey) {
         host.stepFrames(step.frames);
         total += step.frames;
       }
-      return { stepsRun: steps.length, framesRun: total, frameCount: host.status.frameCount };
+      return { stepsRun: steps.length, framesRun: total, frameCount: host.status.frameCount, ...coDriveFields(sessionKey) };
 }
 
 /** op:'navigate' — drive menus by advancing on SCREEN CHANGE; reports consumed per step. */
@@ -178,6 +199,7 @@ function inputNavigateCore({ steps }, sessionKey) {
         framesRun: totalFrames,
         frameCount: host.status.frameCount,
         ...(dropped ? { droppedPresses: dropped, note: `${dropped} step(s) had consumed:false — the screen never changed after the press (wrong screen / press dropped / game polls input on a specific frame). Re-run those steps, increase holdFrames, or reach the screen via state save/load.` } : {}),
+        ...coDriveFields(sessionKey),
       };
 }
 
@@ -199,7 +221,9 @@ export function registerInputTools(server, z, sessionKey) {
     "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" +
+    "'press': press one named `button` for `frames` then release (port 0 default). Runs ONE released frame " +
+    "first so edge-triggered handlers (START pause, menu confirm) always see a fresh newpress even if the " +
+    "button was already held by a prior set.\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?, " +
     "settleFrames?}]`; reports `consumed` per step (false = the screen never reacted: wrong screen / press dropped / " +
@@ -234,21 +258,21 @@ export function registerInputTools(server, z, sessionKey) {
       switch (args.op) {
         case "set": {
           if (!args.ports) throw new Error("input({op:'set'}): `ports` is required.");
-          return jsonContent(inputSetCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputSetCore(args, sessionKey)), getHost(sessionKey), "input set");
         }
         case "press": {
           if (!args.button) throw new Error("input({op:'press'}): `button` is required.");
-          return jsonContent(inputPressCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputPressCore(args, sessionKey)), getHost(sessionKey), `press ${args.button}`);
         }
         case "sequence": {
           if (!args.steps) throw new Error("input({op:'sequence'}): `steps` is required.");
-          return jsonContent(inputSequenceCore(args, sessionKey));
+          return attachObserverFrame(jsonContent(inputSequenceCore(args, sessionKey)), getHost(sessionKey), "input sequence");
         }
         case "navigate": {
           if (!args.steps) throw new Error("input({op:'navigate'}): `steps` is required.");
           // Fill per-step defaults the old navigate schema provided.
           const steps = args.steps.map((s) => ({ holdFrames: 2, maxWaitFrames: 120, settleFrames: 2, ...s }));
-          return jsonContent(inputNavigateCore({ steps }, sessionKey));
+          return attachObserverFrame(jsonContent(inputNavigateCore({ steps }, sessionKey)), getHost(sessionKey), "navigate");
         }
         case "layout": {
           if (!args.platform) throw new Error("input({op:'layout'}): `platform` is required.");

package/src/mcp/tools/lifecycle.js

@@ -2,6 +2,7 @@ import { resolveCore } from "../../cores/registry.js";
 import { clearHost, getHost, getHostOrNull, rememberLastMedia, resetHost } from "../state.js";
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
+import { attachObserverFrame } from "./watch-memory.js";
 
 const MEDIA_KINDS = ["cartridge", "disk", "tape", "program"];
 
@@ -58,7 +59,8 @@ export function registerLifecycleTools(server, z, sessionKey) {
     // on dimensions, so we omit it until a frame has been stepped and point the
     // caller at stepFrames instead.
     const framebufferKnown = host.status.frameCount > 0;
-    return jsonContent({
+    // Livestream: show what just loaded (the boot frame).
+    return attachObserverFrame(jsonContent({
       loaded: true,
       platform,
       core: resolved.coreName,
@@ -68,7 +70,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
         ? { framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight } }
         : { framebufferNote: "Framebuffer dimensions are unknown until the core runs — call stepFrames first, then getStatus (the pre-boot default does not match the real output resolution)." }),
       ...(appliedCheats ? { cheats: appliedCheats } : {}),
-    });
+    }), host, `loaded ${host.status.mediaPath ? host.status.mediaPath.split("/").pop() : platform}`);
   }
 
   server.tool(
@@ -125,10 +127,10 @@ export function registerLifecycleTools(server, z, sessionKey) {
           const host = getHost(sessionKey);
           if (hard) {
             const reloaded = await host.hardReset();
-            return textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)");
+            return attachObserverFrame(textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)"), host, "reset (hard)");
           }
           host.reset();
-          return textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)");
+          return attachObserverFrame(textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)"), host, "reset");
         }
         case "pause":
           getHost(sessionKey).pause();

package/src/mcp/tools/memory.js

@@ -81,7 +81,7 @@ function genericEndianness(platform) {
 // Each function is the body of one former narrow tool, verbatim. The `memory`
 // router dispatches on `op`. They share the module-scope helpers below.
 
-async function memRead(sessionKey, { region, offset = 0, length, offsets, outputPath, inline }) {
+async function memRead(sessionKey, { region, offset = 0, length, offsets, outputPath, inline, echo }) {
       const host = getHost(sessionKey);
       const info0 = REGION_INFO[region] ?? {};
       const endianness0 = info0.endianness ?? genericEndianness(host.status.platform);
@@ -112,7 +112,7 @@ async function memRead(sessionKey, { region, offset = 0, length, offsets, output
       // agent doesn't have to figure byte order out empirically. For
       // generic regions (system_ram etc) fall back to the loaded
       // platform's CPU endianness.
-      const info = REGION_INFO[region] ?? {};
+      const info = REGION_INFO[region] ?? {};   /* (restored — a careless replace-all removed it) */
       const endianness = info.endianness ?? genericEndianness(host.status.platform);
       // Genesis VRAM is stored by genesis-plus-gx as 16-bit words in HOST
       // (little-endian) byte order, so these raw bytes have each word's two
@@ -121,6 +121,12 @@ async function memRead(sessionKey, { region, offset = 0, length, offsets, output
       // correct.) Use getTile (logicalPixels:true, the default) to decode tiles
       // in render order instead of un-swapping by hand.
       let note = info.note ?? null;
+      if (region === "system_ram" && host.status.platform === "genesis") {
+        note = (note ? note + " " : "") +
+          "GENESIS: normalized to CPU byte order — offset X IS the byte the 68k sees at $FF0000+X " +
+          "(the host un-swaps gpgx's word-swapped storage), so offsets line up with disassembly " +
+          "addresses and cheat-DB maps. Words are big-endian, as the meta says.";
+      }
       if (region === "video_ram" && host.status.platform === "genesis") {
         note = (note ? note + " " : "") +
           "GENESIS: these are RAW host-LE bytes — each 16-bit VRAM word's two bytes are SWAPPED " +
@@ -142,12 +148,14 @@ async function memRead(sessionKey, { region, offset = 0, length, offsets, output
         return jsonContent({ ...meta, path, bytes: written });
       }
       // Small read WITH an explicit outputPath: honor it — write the raw bytes
-      // to disk AND still return the hex inline (small, useful). The intent of
-      // passing outputPath is unambiguous; silently ignoring it broke the
-      // "snapshot RAM to a file, then diff two files" workflow.
+      // to disk AND (by default) still return the hex inline. Pass echo:false
+      // to get just {path, bytes}: a 2KB RAM dump's ~4KB hex echo was the
+      // largest avoidable token cost in a real RE session (0.27.0 feedback #4)
+      // when the whole point of outputPath was keeping it out of context.
       const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
       if (outputPath) {
         const { path, bytes: written } = writeOutput(bytes, { outputPath, what: `readMemory(${region})` });
+        if (echo === false) return jsonContent({ ...meta, path, bytes: written });
         return jsonContent({ ...meta, path, bytes: written, hex });
       }
       return jsonContent({ ...meta, hex });
@@ -185,7 +193,7 @@ async function memWrite(sessionKey, { region, offset = 0, hex, base64, data, byt
       return textContent(`wrote ${buf.length} bytes to ${region}+${offset}`);
 }
 
-async function memReadCart(sessionKey, { offset = 0, length = 16, outputPath, inline }) {
+async function memReadCart(sessionKey, { offset = 0, length = 16, outputPath, inline, echo }) {
       const host = getHost(sessionKey);
       const rom = host.getCartRom();
       if (offset >= rom.bytes.length) {
@@ -210,6 +218,7 @@ async function memReadCart(sessionKey, { offset = 0, length = 16, outputPath, in
       const hex = Array.from(slice, (b) => b.toString(16).padStart(2, "0")).join("");
       if (outputPath) {
         const { path, bytes: written } = writeOutput(slice, { outputPath, what: "readCartRom" });
+        if (echo === false) return jsonContent({ ...meta, path, bytes: written });
         return jsonContent({ ...meta, path, bytes: written, hex });
       }
       return jsonContent({ ...meta, hex });
@@ -223,15 +232,83 @@ async function memSnapshot(sessionKey, { region, name = "default", offset = 0, l
       return jsonContent({ region, name, offset, length: bytes.length, note: "Baseline captured — trigger your event, then memory({op:'diff', region, name}) for the changed bytes." });
 }
 
-async function memDiff(sessionKey, { region, name = "default", view = "summary", maxChanges = 4096, maxClusters = 64, gap = 4 }) {
+// ── diffRuns — A/B scenario diff: THE input→RAM mapping primitive ─────────
+// Runs the SAME starting state twice (savestate restore in between) under two
+// different held inputs, then diffs the two post-run memories. Replaces the
+// hand-rolled save → hold A → step → dump → restore → hold B → step → dump →
+// client-side python diff loop (~6 calls + a 4KB context hit) with ONE call
+// (0.27.0 feedback #6). The emulator is left at the END OF RUN B.
+async function memDiffRuns(sessionKey, { region, frames = 60, portsA, portsB, offset = 0, length, minDelta, maxClusters = 64, gap = 4 }) {
+      const host = getHost(sessionKey);
+      const baseline = host.serializeState();
+      let bufA, bufB;
+      try {
+        host.setInput({ ports: portsA ?? [{}] });
+        host.stepFrames(frames);
+        bufA = host.readMemory(region, offset, length ?? regionLength(host, region, offset));
+      } finally {
+        host.unserializeState(baseline);
+      }
+      host.setInput({ ports: portsB ?? [{}] });
+      host.stepFrames(frames);
+      bufB = host.readMemory(region, offset, bufA.length);
+      host.setInput({ ports: [{}] });
+
+      const divergent = [];
+      for (let i = 0; i < Math.min(bufA.length, bufB.length); i++) {
+        if (bufA[i] === bufB[i]) continue;
+        if (minDelta != null && Math.abs(bufB[i] - bufA[i]) < minDelta) continue;
+        divergent.push(offset + i);
+      }
+      const { clusters, stride } = clusterChanges(divergent, { gap });
+      const out = clusters.slice(0, maxClusters).map((c) => {
+        const entry = {
+          start: "0x" + c.startDec.toString(16).toUpperCase(),
+          end: "0x" + c.endDec.toString(16).toUpperCase(),
+          span: c.endDec - c.startDec + 1,
+          bytes: c.bytes,
+        };
+        if (c.endDec - c.startDec + 1 <= 8) {
+          let a = "", b = "";
+          for (let addr = c.startDec; addr <= c.endDec; addr++) {
+            a += bufA[addr - offset].toString(16).padStart(2, "0");
+            b += bufB[addr - offset].toString(16).padStart(2, "0");
+          }
+          entry.runA = a;
+          entry.runB = b;
+        }
+        return entry;
+      });
+      return jsonContent({
+        region, frames, offset, length: bufA.length,
+        portsA: portsA ?? [{}], portsB: portsB ?? [{}],
+        divergentCount: divergent.length,
+        clusterCount: clusters.length,
+        clusters: out,
+        ...(stride !== null ? { stride: "0x" + stride.toString(16) } : {}),
+        ...(clusters.length > out.length ? { truncated: true } : {}),
+        note: divergent.length === 0
+          ? "No divergent bytes — the two inputs produced identical memory after " + frames + " frames. Try more frames, or inputs the game actually distinguishes in this state."
+          : "Each cluster diverges between the two runs; runA/runB are the post-run bytes (small clusters only). The byte that tracks your input is usually the small cluster whose runA-vs-runB delta matches the expected movement. Emulator is left at the END OF RUN B.",
+      });
+}
+
+async function memDiff(sessionKey, { region, name = "default", view = "summary", maxChanges = 4096, maxClusters = 64, gap = 4, minDelta }) {
       const host = getHost(sessionKey);
       const snap = memSnapshots(sessionKey).get(snapKey(region, name));
       if (!snap) throw new Error(`memory({op:'diff'}): no snapshot named '${name}' for region '${region}'. Call memory({op:'snapshot', region, name}) first.`);
       const now = host.readMemory(region, snap.offset, snap.bytes.length);
 
-      // Collect changed offsets once.
+      // Collect changed offsets once. minDelta filters OUT small wiggles
+      // (|after - before| < minDelta) so "find the position byte amid OAM/RNG
+      // churn" is one cheap call instead of a raw dump + client-side filtering
+      // (0.27.0 feedback #5).
       const changedOffsets = [];
-      for (let i = 0; i < snap.bytes.length; i++) if (snap.bytes[i] !== now[i]) changedOffsets.push(i);
+      for (let i = 0; i < snap.bytes.length; i++) {
+        if (snap.bytes[i] === now[i]) continue;
+        if (minDelta != null && Math.abs(now[i] - snap.bytes[i]) < minDelta) continue;
+        changedOffsets.push(i);
+      }
       const changedCount = changedOffsets.length;
 
       if (view === "raw") {
@@ -253,12 +330,29 @@ async function memDiff(sessionKey, { region, name = "default", view = "summary",
       const strideNote = stride !== null
         ? `${clusters.length} change-islands evenly spaced at stride 0x${stride.toString(16)} — likely a struct/entity ARRAY (each island = one record's changed fields).`
         : null;
-      const out = clusters.slice(0, maxClusters).map((c) => ({
-        start: "0x" + c.startDec.toString(16).toUpperCase(),
-        end: "0x" + c.endDec.toString(16).toUpperCase(),
-        span: c.endDec - c.startDec + 1,
-        bytes: c.bytes,
-      }));
+      // Per-cluster before/after for SMALL clusters (≤8 bytes): the summary
+      // view used to give only ranges, forcing a fall back to view:'raw' to
+      // see the values (0.27.0 feedback #5). Large clusters stay range-only.
+      const out = clusters.slice(0, maxClusters).map((c) => {
+        const entry = {
+          start: "0x" + c.startDec.toString(16).toUpperCase(),
+          end: "0x" + c.endDec.toString(16).toUpperCase(),
+          span: c.endDec - c.startDec + 1,
+          bytes: c.bytes,
+        };
+        const span = c.endDec - c.startDec + 1;
+        if (span <= 8) {
+          let before = "", after = "";
+          for (let a = c.startDec; a <= c.endDec; a++) {
+            const i = a - snap.offset;
+            before += snap.bytes[i].toString(16).padStart(2, "0");
+            after += now[i].toString(16).padStart(2, "0");
+          }
+          entry.before = before;
+          entry.after = after;
+        }
+        return entry;
+      });
       return jsonContent({
         region, name, view, baseOffset: snap.offset, length: snap.bytes.length,
         changedCount, clusterCount: clusters.length,
@@ -289,26 +383,91 @@ async function memClassify(sessionKey, { region = "system_ram", offset = 0, leng
 //    value changes with op:'searchNext' (compare:'eq'|'changed'|'unchanged'|'gt'|'lt'|'inc'|'dec').
 //    The candidate list lives per session (keyed by `name`); each narrow reads
 //    the region fresh and keeps only candidates that still satisfy the compare.
-async function memSearch(sessionKey, { value, size = 1, region = "system_ram", name = "default", maxCandidates = 64 }) {
+/**
+ * Decode one candidate value at `i` under the search's representation.
+ *   raw    — `size`-byte unsigned int, region endianness.
+ *   bcd    — `size` bytes of packed BCD (2 decimal digits per byte, region
+ *            endianness): bytes [0x25,0x01] (LE) = 125. Returns null when any
+ *            nibble is >9 (not a BCD value).
+ *   digits — `digitLen` consecutive bytes, one DECIMAL DIGIT per byte, most
+ *            significant first (HUD order), each offset by the candidate's
+ *            constant tile base `k` (0 for raw digits, 0x30 for ASCII, or the
+ *            game's digit-tile index). Returns null when any byte fails to
+ *            decode as k+0..9.
+ * @returns {number|null}
+ */
+function decodeAt(buf, i, s, k = 0) {
+  if (s.as === "digits") {
+    if (i + s.digitLen > buf.length) return null;
+    let v = 0;
+    for (let j = 0; j < s.digitLen; j++) {
+      const d = buf[i + j] - k;
+      if (d < 0 || d > 9) return null;
+      v = v * 10 + d;
+    }
+    return v;
+  }
+  if (i + s.size > buf.length) return null;
+  const u = readUint(buf, i, s.size, s.little);
+  if (s.as === "bcd") {
+    const hex = u.toString(16);
+    if (!/^[0-9]+$/.test(hex)) return null;   // a nibble >9 → not BCD
+    return parseInt(hex, 10);
+  }
+  return u;
+}
+
+async function memSearch(sessionKey, { value, size = 1, as = "raw", region = "system_ram", name = "default", maxCandidates = 64 }) {
       const host = getHost(sessionKey);
       const info = REGION_INFO[region] ?? {};
       const little = (info.endianness ?? genericEndianness(host.status.platform)) !== "big";
       const buf = host.readMemory(region, 0, regionLength(host, region, 0));
-      const read = (i) => readUint(buf, i, size, little);
+      const digitStr = String(value >>> 0);
+      const s = { region, size, little, as, digitLen: digitStr.length };
       const candidates = [];
-      for (let i = 0; i + size <= buf.length; i++) {
-        if (read(i) === (value >>> 0)) candidates.push(i);
+      /** digits mode: per-candidate constant tile-base offset (addr → k). */
+      const kMap = as === "digits" ? new Map() : null;
+      if (as === "digits") {
+        // One byte per decimal digit, MSD first, all offset by a constant k
+        // (HUD digits are usually tile indices: k=0 raw, k=0x30 ASCII, or the
+        // font's digit base). k is derived per candidate from the first digit.
+        // Single-digit values would match EVERY byte with a free k, so they
+        // only accept the common bases.
+        const digits = Array.from(digitStr, (c) => c.charCodeAt(0) - 0x30);
+        const SINGLE_DIGIT_BASES = [0x00, 0x30];
+        for (let i = 0; i + digits.length <= buf.length; i++) {
+          const k = buf[i] - digits[0];
+          if (k < 0 || k > 255 - 9) continue;
+          if (digits.length === 1 && !SINGLE_DIGIT_BASES.includes(k)) continue;
+          let ok = true;
+          for (let j = 1; j < digits.length; j++) {
+            if (buf[i + j] !== digits[j] + k) { ok = false; break; }
+          }
+          if (ok) { candidates.push(i); kMap.set(i, k); }
+        }
+      } else {
+        for (let i = 0; i + size <= buf.length; i++) {
+          if (decodeAt(buf, i, s) === (value >>> 0)) candidates.push(i);
+        }
       }
-      searchSessions(sessionKey).set(name, { region, size, little, addrs: Uint32Array.from(candidates) });
+      // Baseline EVERY candidate at seed time so relative compares
+      // ('inc'/'dec'/'changed'/'unchanged') work as the FIRST narrow. Pre-fix,
+      // the baseline only existed after a value-based round — the first
+      // relative searchNext silently returned 0 candidates (a real session
+      // burned rounds on this; it was documented as a footgun instead of fixed).
+      const prevMap = new Map();
+      for (const a of candidates) prevMap.set(a, value >>> 0);
+      searchSessions(sessionKey).set(name, { ...s, addrs: Uint32Array.from(candidates), prev: prevMap, kMap });
       return jsonContent({
-        searchId: name, region, size,
+        searchId: name, region, size, as,
         count: candidates.length,
-        candidates: candidates.slice(0, maxCandidates).map((a) => "0x" + a.toString(16)),
+        candidates: candidates.slice(0, maxCandidates).map((a) =>
+          "0x" + a.toString(16) + (kMap && kMap.get(a) ? ` (digitBase 0x${kMap.get(a).toString(16)})` : "")),
         note: candidates.length === 0
-          ? "0 matches — wrong size? (try size:2 for a score). Or the value isn't in this region (try a different region) or is stored offset/encoded."
+          ? "0 matches — wrong size? (try size:2 for a score). Stored ≠ displayed is common: lives are often displayed−1 (re-seed with value-1), scores ÷10. Try as:'bcd' (packed BCD) or as:'digits' (one byte per on-screen digit, any constant tile base) — or a different region."
           : candidates.length === 1
           ? "1 candidate — likely THE address. Confirm with memory({op:'write', region, offset, hex}) and watch the screen."
-          : "Make the value change in-game, then memory({op:'searchNext', name, compare:'eq', value:<new>}) to narrow. Repeat until 1-2 remain.",
+          : "Change the value in-game, then memory({op:'searchNext', name, compare:'eq', value:<new>}) to narrow — or compare:'inc'/'dec'/'changed' right away (baselines are recorded at seed). Repeat until 1-2 remain.",
       });
 }
 
@@ -320,21 +479,21 @@ async function memSearchNext(sessionKey, { compare, value, name = "default", max
         throw new Error(`searchNext: compare '${compare}' needs a \`value\` (the number now on screen).`);
       }
       const buf = host.readMemory(s.region, 0, regionLength(host, s.region, 0));
-      const read = (i) => readUint(buf, i, s.size, s.little);
+      const read = (a) => decodeAt(buf, a, s, s.kMap ? s.kMap.get(a) ?? 0 : 0);
       const v = (value ?? 0) >>> 0;
       const kept = [];
       for (const a of s.addrs) {
-        const cur = read(a);
+        const cur = read(a);                       // null = no longer decodes (bcd/digits)
         const prev = s.prev ? s.prev.get(a) : undefined;
         let ok = false;
         switch (compare) {
           case "eq":        ok = cur === v; break;
-          case "gt":        ok = cur > v; break;
-          case "lt":        ok = cur < v; break;
+          case "gt":        ok = cur !== null && cur > v; break;
+          case "lt":        ok = cur !== null && cur < v; break;
           case "changed":   ok = prev !== undefined && cur !== prev; break;
           case "unchanged": ok = prev !== undefined && cur === prev; break;
-          case "inc":       ok = prev !== undefined && cur > prev; break;
-          case "dec":       ok = prev !== undefined && cur < prev; break;
+          case "inc":       ok = cur !== null && prev !== undefined && cur > prev; break;
+          case "dec":       ok = cur !== null && prev !== undefined && cur < prev; break;
         }
         if (ok) kept.push(a);
       }
@@ -348,9 +507,9 @@ async function memSearchNext(sessionKey, { compare, value, name = "default", max
         searchId: name, compare, count: kept.length,
         candidates: kept.slice(0, maxCandidates).map((a) => "0x" + a.toString(16) + "=" + read(a)),
         note: kept.length === 0
-          ? "0 left — narrowed too far (wrong op, or the value moved between reads). Re-seed with searchValue."
+          ? "0 left — narrowed too far (wrong op, or the value moved between reads — e.g. the scene changed/player died mid-step; screenshot before blaming the compare). Re-seed with memory({op:'search'})."
           : kept.length <= 2
-          ? "Down to 1-2 — confirm: writeMemory({region, offset, bytes}) and watch the screen change."
+          ? "Down to 1-2 — confirm: memory({op:'write', region, offset, hex:'..'}) and watch the screen change."
           : "Still multiple — change the value again and memory({op:'searchNext'}) to keep narrowing.",
       });
 }
@@ -374,7 +533,7 @@ export function registerMemoryTools(server, z, sessionKey) {
     "snapshot → {region, name, offset?, length?}; " +
     "diff → {region, name, view?}; " +
     "classify → {region?, offset?, length?}; " +
-    "search → {value, size?, region?}; " +
+    "search → {value, size?, as?, region?}; " +
     "searchNext → {compare, value?}.\n" +
     `• op:'read' — bytes as a \`hex\` string. ≤${INLINE_HEX_LIMIT}B come back inline; >${INLINE_HEX_LIMIT}B need \`outputPath\` (RAW bytes written → {path,bytes}) or \`inline:true\`. BATCH: \`offsets\` (addresses or {offset,length}) reads many non-contiguous spots in ONE call → reads:[{offset,length,hex}]. (Genesis video_ram is raw host-LE word-swapped — not a direct tile map; use tiles({op:'pixels'}).)\n` +
     "• op:'write' — pass payload as `hex` (e.g. 'deadbeef') OR `base64` — **NOT `data`, `bytes`, or an array (those are REJECTED with guidance).** hex for byte patterns, base64 for binary blobs.\n" +
@@ -382,11 +541,11 @@ export function registerMemoryTools(server, z, sessionKey) {
     "• op:'snapshot' — capture a baseline of `region` (server RAM, keyed by `name`) to later diff. The 'which bytes did THIS event touch?' workflow: snapshot → trigger event → op:'diff'.\n" +
     "• op:'diff' — compare a region against a snapshot baseline → the CHANGED bytes. DEFAULT `view:'summary'` is a CLUSTERED summary (+ stride detection — '4 islands at stride 0x80' = a struct array) so a churny gameplay diff doesn't flood context; `view:'raw'` = the per-byte before/after list.\n" +
     "• op:'classify' — heuristically classify the bytes at an offset BEFORE you trust a 'found table'. **Kills the classic trap: a run that 'matches' your stats is often ASCII TEXT (bytes 82/79/68 = 'ROD' from a taunt string) or code.** Returns looksLike/printableRatio/entropy/asciiPreview/confidence.\n" +
-    "• op:'search' — seed the iterative RAM value search (Cheat Engine / RetroArch style): all addresses currently holding `value` (`size` 1/2/4 bytes, region's endianness). The primitive for 'the screen shows X, find its RAM address' — better than snapshot+diff for this.\n" +
-    "• op:'searchNext' — narrow the active candidate list against CURRENT memory. `compare`: 'eq'/'gt'/'lt' (need `value`), 'changed'/'unchanged'/'inc'/'dec' (vs the previous read). Repeat until 1-2 remain, then confirm with op:'write'.",
+    "• op:'search' — seed the iterative RAM value search (Cheat Engine / RetroArch style): all addresses currently holding `value` (`size` 1/2/4 bytes, region's endianness). The primitive for 'the screen shows X, find its RAM address' — better than snapshot+diff for this. STORED ≠ DISPLAYED is common — `as:'bcd'` (packed BCD scores) and `as:'digits'` (one byte per on-screen digit at ANY constant tile base, auto-detected per candidate) search those representations directly; for displayed−1 lives or ÷10 scores just seed the transformed number.\n" +
+    "• op:'searchNext' — narrow the active candidate list against CURRENT memory. `compare`: 'eq'/'gt'/'lt' (need `value`), 'changed'/'unchanged'/'inc'/'dec' (vs the previous read — usable as the FIRST narrow too; baselines are recorded at seed). Comparisons happen in the seed's `as` representation. Repeat until 1-2 remain, then confirm with op:'write'. (For values an INPUT drives — position, velocity — op:'diffRuns' is usually one call instead of a narrowing loop.)",
     {
-      op: z.enum(["read", "write", "readCart", "snapshot", "diff", "classify", "search", "searchNext"])
-        .describe("read=bytes→hex; write=hex/base64→region; readCart=loaded cart ROM image; snapshot=capture a baseline; diff=changed bytes vs a baseline; classify=what kind of data is here; search=seed a value search; searchNext=narrow it."),
+      op: z.enum(["read", "write", "readCart", "snapshot", "diff", "diffRuns", "classify", "search", "searchNext"])
+        .describe("read=bytes→hex; write=hex/base64→region; readCart=loaded cart ROM image; snapshot=capture a baseline; diff=changed bytes vs a baseline; diffRuns=run the SAME start state twice under two different held inputs and return only the DIVERGENT bytes (THE input→RAM mapping primitive — replaces save/run/dump/restore/run/dump/python-diff); classify=what kind of data is here; search=seed a value search; searchNext=narrow it."),
       region: z.enum(REGIONS).optional().describe("Memory region. Required for read/write/snapshot/diff; defaults to system_ram for classify/search. (readCart targets the cart ROM image, not a region.)"),
       offset: z.number().int().min(0).default(0).describe("Byte offset within the region (read/write/snapshot/classify) or the cart ROM image (readCart)."),
       length: z.number().int().min(1).max(1 << 20).optional().describe("Bytes to read (max 1MB). op:read default 1; op:readCart default 16; op:snapshot default = whole region from offset; op:classify default 256."),
@@ -403,14 +562,20 @@ export function registerMemoryTools(server, z, sessionKey) {
       maxChanges: z.number().int().min(1).max(65536).default(4096).describe("op:diff raw view — cap the per-byte list (changedCount is the true total)."),
       maxClusters: z.number().int().min(1).max(4096).default(64).describe("op:diff summary view — cap the cluster list (clusterCount is the true total)."),
       gap: z.number().int().min(1).max(256).default(4).describe("op:diff summary view — merge changed bytes within this many bytes into one cluster (default 4)."),
+      minDelta: z.number().int().min(1).max(255).optional().describe("op:diff — ignore changes where |after-before| < minDelta (filters RNG/counter wiggle so a position byte that moved by the entity's speed stands out)."),
+      frames: z.number().int().min(1).max(100000).default(60).describe("op:diffRuns — frames to run EACH scenario from the same start state."),
+      portsA: z.array(z.record(z.string(), z.boolean())).max(2).optional().describe("op:diffRuns — held input for run A (e.g. [{right:true}]). Default released."),
+      portsB: z.array(z.record(z.string(), z.boolean())).max(2).optional().describe("op:diffRuns — held input for run B. Default released — A-vs-idle is the classic 'which byte does this input drive?' probe."),
       // search / searchNext
       value: z.number().int().optional().describe("op:search — the value the screen shows now. op:searchNext — required for compare 'eq'/'gt'/'lt'."),
-      size: z.number().int().min(1).max(4).default(1).describe("op:search — value width in bytes: 1 (stats/lives), 2 (scores/timers), 4 (big counters)."),
-      compare: z.enum(["eq", "changed", "unchanged", "inc", "dec", "gt", "lt"]).optional().describe("op:searchNext — eq=now equals `value`; changed/unchanged vs the last read; inc/dec=went up/down; gt/lt=now >/< `value`."),
+      size: z.number().int().min(1).max(4).default(1).describe("op:search — value width in bytes: 1 (stats/lives), 2 (scores/timers), 4 (big counters). Ignored for as:'digits' (width = the value's digit count)."),
+      as: z.enum(["raw", "bcd", "digits"]).default("raw").describe("op:search — value representation: 'raw' (binary int, region endianness), 'bcd' (packed BCD, 2 decimal digits/byte — common for NES scores), 'digits' (one byte per ON-SCREEN digit, MSD first, any constant tile base — HUD/tile-index score buffers; the matched base is reported per candidate). searchNext compares in the SAME representation automatically."),
+      compare: z.enum(["eq", "changed", "unchanged", "inc", "dec", "gt", "lt"]).optional().describe("op:searchNext — eq=now equals `value`; changed/unchanged vs the last read; inc/dec=went up/down. All of these work as the FIRST narrow too (baselines are recorded at seed). gt/lt=now >/< `value`."),
       maxCandidates: z.number().int().min(1).max(8192).default(64).describe("op:search/searchNext — cap the candidates RETURNED (the full list is kept server-side; `count` is the true total)."),
       // shared output
       outputPath: z.string().optional().describe(`op:read/readCart — write RAW bytes here. Required for reads >${INLINE_HEX_LIMIT}B unless inline. Small reads honor it too (writes file AND returns hex), so 'dump to disk then diff two files' works at any size. (Ignored with offsets.)`),
       inline: z.boolean().default(false).describe(`op:read/readCart — for reads >${INLINE_HEX_LIMIT}B, return the hex in the response instead of writing to disk.`),
+      echo: z.boolean().default(true).describe("op:read/readCart with outputPath — false = return only {path, bytes} with NO inline hex (keeps a 2-4KB dump out of context; the raw bytes are in the file)."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -424,6 +589,10 @@ export function registerMemoryTools(server, z, sessionKey) {
           if (!args.region) throw new Error("memory({op:'snapshot'}): `region` is required.");
           return await memSnapshot(sessionKey, args);
         }
+        case "diffRuns": {
+          if (!args.region) throw new Error("memory({op:'diffRuns'}): `region` is required.");
+          return await memDiffRuns(sessionKey, args);
+        }
         case "diff": {
           if (!args.region) throw new Error("memory({op:'diff'}): `region` is required.");
           return await memDiff(sessionKey, args);

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

@@ -69,7 +69,7 @@ export async function listPlatformDocsCore({ platform }) {
         platform,
         docs,
         note: docs.length === 0
-          ? `No docs shipped for '${platform}' yet. Try a different platform or scaffold for boilerplate. (For RE/patching workflow, see platform({op:'doc', platform:'romhacking', name:'playbook'}).)`
+          ? `No docs shipped for '${platform}' yet. Try a different platform, or fork an example game (examples({op:'fork'})) for boilerplate. (For RE/patching workflow, see platform({op:'doc', platform:'romhacking', name:'playbook'}).)`
           : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model' or 'troubleshooting'. For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
       };
 }