romdevtools 0.16.0 → 0.22.0

package/src/mcp/tools/toolchain.js

@@ -2,16 +2,36 @@ import { mkdir, mkdtemp, writeFile, readdir, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { TOOLCHAINS } from "../../toolchains/registry.js";
-import { buildForPlatform } from "../../toolchains/index.js";
+import { buildForPlatform, rankIssues } from "../../toolchains/index.js";
 import { resolveLinkerConfig } from "../../toolchains/cc65/preset-resolver.js";
+import { parseBuildLog } from "../../toolchains/parse-errors.js";
+import { inesHeaderSource, charsSource, nromFlatCfg } from "../../toolchains/cc65/ines.js";
 import { resolveCore } from "../../cores/registry.js";
 import { resetHost, getDisclosure } from "../state.js";
 import { PLATFORM_VIRTUAL_EXT } from "../../host/LibretroHost.js";
-import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
+import { imageContent, jsonContent, safeTool } from "../util.js";
 import { isPlaytestRunning } from "./playtest.js";
 import { buildSourceWithDebugCore } from "./symbols.js";
 import { log as serverLog } from "../log.js";
 
+// crt0 (the per-platform startup stub) is assembled BEHIND the user's build.
+// When it fails the agent gets a raw assembler log — route it through the same
+// parser build() uses so the error leads with the first file:line: message
+// (the issues[]-style surfacing), full log appended for fallback.
+function crt0AssemblyError(log) {
+  const issues = parseBuildLog(log ?? "");
+  const first = issues.find((i) => i.severity === "error") ?? issues[0];
+  const headline = first
+    ? `${first.file ? first.file + ":" : ""}${first.line ? first.line + ": " : ""}${first.message}`
+    : "no structured diagnostic found";
+  return new Error(
+    `crt0 (startup stub) assembly failed: ${headline}` +
+    (issues.length > 1 ? ` (+${issues.length - 1} more)` : "") +
+    `\nThis is the bundled startup code, not your source — if it's the only error, ` +
+    `report it. Full assembler log:\n${log ?? ""}`,
+  );
+}
+
 // Record a build outcome into the /log ring buffer so a failed build's stage +
 // error tail are diagnosable later (the request was already traced; this adds
 // the RESULT). On failure we keep a chunk of the build log; on success just the
@@ -25,6 +45,47 @@ function logBuildResult(verb, platform, result) {
   }
 }
 
+/**
+ * Apply the `inesHeader` NES NROM-rebuild convenience: synthesize the iNES HEADER
+ * segment (+ CHARS segment that .incbins the CHR blob when chrBanks>0) into the
+ * sources map and set a flat NROM linker .cfg. The agent supplies only the PRG
+ * disassembly + the CHR blob — no glue .s/.cfg, no hand-derived header bytes.
+ * Shared by build({output:'rom'|'run'}). See toolchains/cc65/ines.js.
+ *
+ * @param {{platform:string, inesHeader:any, sources:Record<string,string>|null|undefined, source:string|null|undefined, linkerConfig:string|undefined, mergedBinaryIncludes:Record<string,string>}} a
+ * @returns {{sources:Record<string,string>, source:null, linkerConfig:string}}
+ */
+function applyInesHeader({ platform, inesHeader, sources, source, linkerConfig, mergedBinaryIncludes }) {
+  if (platform !== "nes") {
+    throw new Error(`inesHeader is NES-only (iNES is the NES cartridge format); platform was '${platform}'.`);
+  }
+  if (linkerConfig) {
+    throw new Error("Pass either `inesHeader` (auto-generates the NROM .cfg) OR `linkerConfig`, not both.");
+  }
+  const chr = inesHeader.chrBanks ?? 0;
+  // A rebuild is always multi-source (PRG disassembly + synthesized header), so
+  // normalize a lone `source` into the sources map.
+  const out = sources == null
+    ? (source != null ? { "main.s": source } : {})
+    : { ...sources };
+  if (out["ines_header.s"] == null) out["ines_header.s"] = inesHeaderSource(inesHeader);
+  if (chr > 0) {
+    const binNames = Object.keys(mergedBinaryIncludes);
+    const chrName = inesHeader.chrIncbin ?? (binNames.length === 1 ? binNames[0] : undefined);
+    if (!chrName) {
+      throw new Error(
+        `inesHeader.chrBanks=${chr} needs the CHR-ROM blob: pass it via binaryIncludePaths ` +
+        `(e.g. {"chr.bin":"/path/chr.bin"}). With more than one binary include, set inesHeader.chrIncbin to its name.`
+      );
+    }
+    if (mergedBinaryIncludes[chrName] == null) {
+      throw new Error(`inesHeader.chrIncbin '${chrName}' is not among the binary includes (${binNames.join(", ") || "none"}).`);
+    }
+    if (out["ines_chars.s"] == null) out["ines_chars.s"] = charsSource(chrName);
+  }
+  return { sources: out, source: null, linkerConfig: nromFlatCfg(inesHeader) };
+}
+
 // One-shot "open playtest" hint state — per MCP session, set after the
 // hint has been delivered once so we don't keep nagging legitimate
 // headless flows (CI, automated tests, batch RE work). Keyed by the
@@ -205,7 +266,7 @@ export function installToolchainCore({ id }) {
 }
 
 export function registerToolchainTools(server, z, sessionKey) {
-  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
+  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, inesHeader, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
       // Reject conflicting inline vs path args — fail loud, not silent.
       if (source != null && sourcePath != null) {
         throw new Error("build({output:'rom'}): pass either `source` OR `sourcePath`, not both.");
@@ -252,6 +313,12 @@ export function registerToolchainTools(server, z, sessionKey) {
           mergedBinaryIncludes[name] = bytes.toString("base64");
         }
       }
+      // inesHeader — NES NROM rebuild convenience (see applyInesHeader).
+      if (inesHeader) {
+        ({ sources, source, linkerConfig } = applyInesHeader({
+          platform, inesHeader, sources, source, linkerConfig, mergedBinaryIncludes,
+        }));
+      }
       const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, linkerConfig);
       // Splice preset support sources (e.g. custom crt0) into the project.
       // User sources take precedence — never overwrite a source the agent
@@ -270,7 +337,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
         const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
         if (!asm.rel) {
-          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+          throw crt0AssemblyError(asm.log);
         }
         crt0Rel = asm.rel;
       }
@@ -352,7 +419,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         ...(result.stage ? { stage: result.stage } : {}),
         ...(result.sdkEditIgnored ? { sdkEditIgnored: result.sdkEditIgnored } : {}),
         ...(await logField(result.log, inline, logSibling, result.ok)),
-        issues: result.issues ?? [],
+        issues: rankIssues(result.issues ?? []),
         ...(showHint ? { hint: showHint } : {}),
       };
       // When a build failed on a specific TU (multi-source SDCC build),
@@ -397,7 +464,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       return jsonContent(payload);
   }
 
-  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
+  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, inesHeader, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
       const { buildForPlatform } = await import("../../toolchains/index.js");
       const resolved = resolveCore(platform);
       if (!resolved) throw new Error(`no core available for platform '${platform}'`);
@@ -470,6 +537,12 @@ export function registerToolchainTools(server, z, sessionKey) {
           mergedBinaryIncludes[name] = bytes.toString("base64");
         }
       }
+      // inesHeader — NES NROM rebuild convenience (see applyInesHeader).
+      if (inesHeader) {
+        ({ sources, source, linkerConfig } = applyInesHeader({
+          platform, inesHeader, sources, source, linkerConfig, mergedBinaryIncludes,
+        }));
+      }
       const { cfg: resolvedLinkerConfig2, supportSources: supportSources2 } = await resolveLinkerConfig(platform, linkerConfig);
       const mergedSources2 = sources
         ? { ...supportSources2, ...sources }
@@ -484,7 +557,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
         const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
         if (!asm.rel) {
-          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+          throw crt0AssemblyError(asm.log);
         }
         crt0Rel2 = asm.rel;
       }
@@ -515,7 +588,7 @@ export function registerToolchainTools(server, z, sessionKey) {
           toolchain: build.toolchain,
           exitCode: build.exitCode,
           ...(await logField(build.log, false, null)),
-          issues: build.issues ?? [],
+          issues: rankIssues(build.issues ?? []),
         });
       }
 
@@ -571,7 +644,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         // Surface lint/build issues even on successful runs so agents see
         // linter warnings BEFORE the next iteration (was: runSource silently
         // ran with warnings, agent missed them, hit the crash 100 functions later).
-        ...((build.issues ?? []).length > 0 ? { issues: build.issues } : {}),
+        ...((build.issues ?? []).length > 0 ? { issues: rankIssues(build.issues) } : {}),
         ...(hint ? { hint } : {}),
       };
 
@@ -616,6 +689,7 @@ export function registerToolchainTools(server, z, sessionKey) {
   server.tool(
     "build",
     "Compile/assemble source for a target platform; one tool keyed by `output`.\n" +
+    "ON FAILURE (ok:false): READ `issues[]` FIRST — it's the structured error list ({file,line,col,severity,message,stage}) and usually names the exact line to fix. Only fall back to the raw `log` if `issues[]` is empty. Don't guess or rebuild blindly before reading it.\n" +
     "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
     "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`).\n" +
     "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
@@ -639,7 +713,15 @@ export function registerToolchainTools(server, z, sessionKey) {
       codeLoc: z.coerce.number().int().optional().describe("SDCC — _CODE load address (default $0000; GB/GBC bundled crt0 wants 0x150)."),
       dataLoc: z.coerce.number().int().optional().describe("SDCC — _DATA (WRAM) load address (default $C000 on Z80). NOT read by output:'romWithDebug'."),
       options: z.array(z.string()).optional().describe("output:'rom' — extra toolchain CLI options."),
-      linkerConfig: z.string().optional().describe("ld65 linker config (cc65). NES preset 'chr-ram-runtime' (RECOMMENDED — full crt0 + iNES header + NMI w/ OAM DMA + `_shadow_oam` at $0200) or 'chr-ram' (bare nmi:rti stub), or full .cfg contents. Preset NAMES only resolve on output:'rom'/'run'; output:'romWithDebug' takes raw .cfg contents only."),
+      linkerConfig: z.string().optional().describe("ld65 linker config (cc65). NES presets: 'chr-ram-runtime' (RECOMMENDED for homebrew C — full crt0 + iNES header + NMI w/ OAM DMA + `_shadow_oam` at $0200), 'chr-ram' (bare nmi:rti stub), 'chr-rom' (cc65-C with FIXED CHR-ROM art — segment split + CHARS segment; supply CHR via binaryIncludePaths into a CHARS source + the header via `inesHeader`). Or full .cfg contents. Preset NAMES only resolve on output:'rom'/'run'; output:'romWithDebug' takes raw .cfg contents only. **For rebuilding a commercial NROM game from its disassembly, prefer `inesHeader` over a raw .cfg.**"),
+      inesHeader: z.object({
+        prgBanks: z.coerce.number().int().min(1).max(255).describe("16KB PRG-ROM banks (1 = NROM-128, 2 = NROM-256)."),
+        chrBanks: z.coerce.number().int().min(0).max(255).optional().describe("8KB CHR-ROM banks (0 = CHR-RAM, no CHARS segment). Default 0."),
+        mapper: z.coerce.number().int().min(0).max(255).optional().describe("iNES mapper number. Default 0 (NROM)."),
+        mirroring: z.enum(["horizontal", "vertical"]).optional().describe("Nametable mirroring. Default 'horizontal'."),
+        battery: z.boolean().optional().describe("PRG-RAM battery (flags6 bit 1). Default false."),
+        chrIncbin: z.string().optional().describe("Name of the binaryInclude holding the CHR-ROM blob to .incbin (only needed when chrBanks>0 AND there's more than one binary include; else the sole include is used)."),
+      }).optional().describe("NES iNES-header + NROM-rebuild convenience. Auto-emits the 16-byte iNES HEADER segment + (for chrBanks>0) a CHARS segment that .incbins the CHR blob (from binaryIncludePaths), and sets a flat NROM linker .cfg (HEADER+PRG+CHARS). The agent supplies ONLY the PRG disassembly source(s) + the CHR blob — no glue .s/.cfg files, no hand-derived header bytes. THE shape for rebuilding an NROM commercial game from `disasm({target:'project'})`. Mutually exclusive with `linkerConfig`."),
       runtime: z.string().optional().describe("GBA — runtime: 'libtonc' (default), 'libgba', or 'none'."),
       maxmod: z.boolean().optional().describe("GBA — link maxmod for music (libmm.a). You still call mmInit/mmStart + hook mmVBlank."),
       rebuildSdk: z.boolean().optional().describe("GBA + Genesis — rebuild the bundled SDK (libtonc/libgba/maxmod/SGDK) from vendored source instead of the prebuilt seed (~20-40s). Only if you edited SDK source (else an `sdkEditIgnored` warning fires)."),
@@ -729,6 +811,17 @@ export function projectBuildRecipe(platform, names) {
         if (/crt0.*\.s$/i.test(n) || /\.cfg$/i.test(n)) r.skip.add(n);
       }
     }
+  } else if (platform === "msx") {
+    // MSX ships msx_crt0.s — it MUST be passed AS the crt0 (replacing the stock
+    // SDCC z80 crt0.rel), NOT compiled as a plain source. The stock crt0 is a
+    // CP/M-style $0000 runtime with no MSX cartridge header; if it links, IT
+    // provides the $4010 entry (an SDCC gsinit stub = `nop nop nop ret`) and our
+    // msx_crt0.s _HEADER ("AB" + INIT pointer) gets dropped. The toolchain then
+    // synthesizes a header pointing INIT at $4010 = that stub, so the BIOS CALLs
+    // a no-op that returns immediately → "No cartridge found" (proven: real
+    // commercial ROMs boot in the same host; only our scaffolds failed). Routing
+    // msx_crt0.s through crt0 makes ITS header + init the cartridge entry.
+    if (has("msx_crt0.s")) { r.crt0File = "msx_crt0.s"; r.codeLoc = 0x4010; }
   } else if (platform === "sms" || platform === "gg") {
     // SMS/GG auto-inject their bundled crt0 inside buildForPlatform — so the
     // scaffold's own *_crt0.s would be a DUPLICATE. Skip it.
@@ -852,7 +945,7 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     const isSm83 = platform === "gb" || platform === "gbc";
     const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
     const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
-    if (!asm.rel) throw new Error(`crt0 assembly failed:\n${asm.log}`);
+    if (!asm.rel) throw crt0AssemblyError(asm.log);
     crt0Rel = asm.rel;
   }
 
@@ -891,6 +984,6 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     romLayout: describeRomLayout(platform, result.binary),
     ...(result.stage ? { stage: result.stage } : {}),
     ...(await logField(result.log, false, logSibling, result.ok)),
-    issues: result.issues ?? [],
+    issues: rankIssues(result.issues ?? []),
   });
 }

package/src/mcp/tools/watch-memory.js

@@ -12,7 +12,7 @@
 // touching this byte and what does the screen look like after," not a complete
 // CPU trace. Instruction-level tracing would need core-side breakpoint hooks.
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
 import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
@@ -21,6 +21,30 @@ import { MemoryRegionToRetro } from "../../host/types.js";
 import { resolveButtonAlias } from "./input.js";
 import { getCPUStateCore } from "./platform-tools.js";
 import { traceVramSourceCore } from "./trace-vram-source.js";
+import { resolveStatePath } from "./state.js";
+
+// Restore a savestate (in-memory slot `fromState` OR disk file `fromStatePath`)
+// before a trace, so on:'range'/'pc' run from a known moment. Returns a small
+// {slot|path} descriptor for the response, or null if neither was given.
+// Throws a clear error if both are given or the restore fails.
+async function maybeRestoreState(host, fromState, fromStatePath) {
+  if (fromState && fromStatePath) {
+    throw new Error("watch: provide `fromState` (slot) OR `fromStatePath` (file), not both.");
+  }
+  if (fromStatePath) {
+    const resolved = resolveStatePath(fromStatePath, host);
+    let blob;
+    try { blob = new Uint8Array(await readFile(resolved)); }
+    catch (e) { throw new Error(`watch: can't read fromStatePath '${resolved}': ${e.message}`); }
+    host.unserializeState(blob);
+    return { path: resolved };
+  }
+  if (fromState) {
+    host.loadState(fromState); // throws if the slot doesn't exist
+    return { slot: fromState };
+  }
+  return null;
+}
 
 // Let a human watching /livestream (or a playtest window) SEE what a
 // breakpoint/watch tool just did — the frozen breakpoint frame, the state when a
@@ -32,7 +56,7 @@ import { traceVramSourceCore } from "./trace-vram-source.js";
 // observer wrapper encodes it ASYNCHRONOUSLY, after the agent's response has
 // already gone out. The provider is stripped from the agent-visible result. The
 // frame is captured by reference now (correct frozen state) but rasterized later.
-function attachObserverFrame(json, host) {
+export function attachObserverFrame(json, host) {
   json._observerFrameProvider = () => {
     try {
       const shot = host.screenshot(); // { pngBase64, width, height }
@@ -73,9 +97,18 @@ export function makePressDriver(host, presses) {
   let applied = 0;          // how many scheduled presses actually got a frame
   let lastSet = null;       // last setInput payload we pushed (to avoid churn)
   const platform = host.status?.platform;
+  // When NO pressDuring schedule is given, the driver must NOT touch input at
+  // all — it leaves whatever persistent state input({op:'set'}) established in
+  // place, so a watch/breakpoint inherits the held pad exactly like
+  // frame({op:'step'}) does. (Previously applyForFrame(0) pushed an empty
+  // [{},{}] payload on the first frame, silently neutralizing a held Right+A —
+  // the v0.16.0 movement-analysis bug.) A non-empty schedule still OWNS the
+  // pad (deterministic capture): it drives the buttons and releases on finish.
+  const driven = presses.length > 0;
   return {
     applied: () => applied,
     applyForFrame(i) {
+      if (!driven) return;   // inherit persistent input({op:'set'}) state
       // Buttons whose [frame, frame+holdFrames) window covers frame i.
       const held = presses.filter((p) => i >= p.frame && i < p.frame + (p.holdFrames ?? 2));
       // Build a 2-port setInput payload from the held buttons.
@@ -90,6 +123,7 @@ export function makePressDriver(host, presses) {
       for (const p of held) { if (p.frame === i) applied++; }
     },
     finish() {
+      if (!driven) return;   // we never touched input; leave it as the caller set it
       if (lastSet !== null && lastSet !== "[{},{}]") host.setInput({ ports: [{}, {}] });
     },
   };
@@ -104,6 +138,61 @@ export function makePressDriver(host, presses) {
 // never disagree again.
 const MEMORY_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
 
+// Abort-guard for input-driven watchpoint runs: sample caller-named bytes each
+// frame; the FIRST one to change stops the run with {label,addr,before,after}.
+// Lets a derailed driven scenario (player died, scene flipped) return immediately
+// with WHY, instead of burning all maxFrames on a meaningless miss.
+function makeAbortGuard(host, abortIf) {
+  const specs = Array.isArray(abortIf) ? abortIf : [];
+  const watched = specs.map((s, _i) => {
+    const region = s.region ?? "system_ram";
+    const offset = s.offset ?? 0;
+    let before;
+    try { before = host.readMemory(region, offset, 1)[0]; } catch { before = null; }
+    const addr = "$" + (offset >>> 0).toString(16).toUpperCase();
+    return { region, offset, addr, label: s.label ?? `${region}${addr}`, before };
+  }).filter((w) => w.before != null);
+  return {
+    count: watched.length,
+    check() {
+      for (const w of watched) {
+        let now;
+        try { now = host.readMemory(w.region, w.offset, 1)[0]; } catch { continue; }
+        if (now !== w.before) {
+          return {
+            label: w.label, addr: w.addr,
+            before: "0x" + w.before.toString(16).padStart(2, "0").toUpperCase(),
+            after: "0x" + now.toString(16).padStart(2, "0").toUpperCase(),
+          };
+        }
+      }
+      return null;
+    },
+  };
+}
+
+// No-hit note for bpFindWriter. The full "two reasons" explainer (~100 tokens)
+// is useful ONCE; as a repeated payload it's pure overhead (v0.15.0 feedback
+// #2b). Emit the long form only on the first miss per MCP session, a one-liner
+// after.
+const _bpNoHitSeen = new Set();
+function noHitNote(sessionKey) {
+  const short = "No per-byte CPU write to that address within maxFrames. Either the event didn't fire " +
+    "(raise maxFrames / drive it with pressDuring; add abortIf to stop early if the scenario derails), " +
+    "OR the region is rebuilt as a BLOCK (OAM/display-list/VRAM bulk-copy or DMA) so no single instruction " +
+    "writes it — watch the SOURCE struct the copy reads from instead.";
+  if (_bpNoHitSeen.has(sessionKey)) return short;
+  _bpNoHitSeen.add(sessionKey);
+  return "No per-byte CPU write to that address within maxFrames. Two common reasons: " +
+    "(1) the event didn't fire — increase maxFrames or drive the game with pressDuring to trigger it " +
+    "(and pass `abortIf` to abort early + say why if a driven run derails, e.g. the player dies). " +
+    "(2) this region is rebuilt as a BLOCK rather than written field-by-field — sprite/OAM shadow tables, " +
+    "display lists, and VRAM are typically bulk-copied (memcpy/loop) or DMA'd from a SOURCE struct elsewhere, " +
+    "so no single instruction writes this exact byte. In that case the address you want is the SOURCE: watch " +
+    "the struct the copy reads from (find it with searchValue on the live value), or for graphics trace the " +
+    "DMA/copy source (Genesis VRAM DMA source is in VDP regs). 'Address is wrong' is usually case (2), not a bad address.";
+}
+
 function tryGetPC(host) {
   try {
     const platform = host.status?.platform;
@@ -420,7 +509,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
 
   // breakpoint({on:write|read|pc}) STOP-on-first. on:write precision:exact=bpFindWriter
   // (core watchpoint, true PC under IRQ), precision:sampled=bpRunUntilWrite (frame PC).
-  async function bpFindWriter({ address, maxFrames = 600, pressDuring }) {
+  async function bpFindWriter({ address, maxFrames = 600, pressDuring, abortIf }) {
       const host = getHost(sessionKey);
       if (!host.watchpointSupported || !host.watchpointSupported()) {
         return jsonContent({
@@ -432,26 +521,44 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       host.setWatchpoint(address, true);
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
       const pressDriver = makePressDriver(host, presses);
+      // Abort-guard: sample caller-named "still valid?" bytes each frame; if any
+      // changes, a driven run that DERAILED (player died → title screen, scene
+      // flipped, …) stops immediately instead of burning all maxFrames and
+      // returning a meaningless found:false. (v0.15.0 feedback #2.)
+      const guard = makeAbortGuard(host, abortIf);
       let result = null;
+      let aborted = null;
       for (let i = 0; i < maxFrames; i++) {
         pressDriver.applyForFrame(i);
         host.stepFrames(1);
         const w = host.getWatchpoint();
         if (w.hits > 0) { result = { ...w, framesStepped: i + 1 }; break; }
+        const ab = guard.check();
+        if (ab) { aborted = { ...ab, framesStepped: i + 1 }; break; }
       }
       pressDriver.finish();
       host.setWatchpoint(address, false); // disarm
+      if (aborted) {
+        return jsonContent({
+          found: false, aborted: true, abortedBy: aborted.label,
+          abortAddress: aborted.addr, before: aborted.before, after: aborted.after,
+          framesStepped: aborted.framesStepped,
+          ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
+          note: `Run aborted early: the watched abort byte ${aborted.label} (${aborted.addr}) changed ` +
+            `${aborted.before}→${aborted.after} at frame ${aborted.framesStepped}, so the driven scenario left the ` +
+            `expected state (e.g. player died / scene changed) before the write fired. The found:false is NOT a real ` +
+            `miss — fix the input plan or pick a different start state, then re-run.`,
+        });
+      }
       if (!result) {
         return jsonContent({
           found: false, address: "$" + address.toString(16).toUpperCase(), framesStepped: maxFrames,
           ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
-          note: "No per-byte CPU write to that address within maxFrames. Two common reasons: " +
-            "(1) the event didn't fire — increase maxFrames or drive the game with pressDuring to trigger it. " +
-            "(2) this region is rebuilt as a BLOCK rather than written field-by-field — sprite/OAM shadow tables, " +
-            "display lists, and VRAM are typically bulk-copied (memcpy/loop) or DMA'd from a SOURCE struct elsewhere, " +
-            "so no single instruction writes this exact byte. In that case the address you want is the SOURCE: watch " +
-            "the struct the copy reads from (find it with searchValue on the live value), or for graphics trace the " +
-            "DMA/copy source (Genesis VRAM DMA source is in VDP regs). 'Address is wrong' is usually case (2), not a bad address.",
+          ...(abortIf && abortIf.length ? { abortIfArmed: guard.count } : {}),
+          // One-line hint by default; the full "two reasons" explainer is verbose
+          // boilerplate as a repeated payload (v0.15.0 feedback #2b) — gated to the
+          // FIRST miss per session.
+          note: noHitNote(sessionKey),
         });
       }
       // When the core reports a PRG-ROM offset for the PC (fceumm/NES), it
@@ -654,7 +761,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         button: z.string(),
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition)."),
+      })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored); use it to drive the watched window itself."),
+      abortIf: z.array(z.object({
+        region: z.enum(MEMORY_REGIONS).optional().describe("memory region (default system_ram)"),
+        offset: z.number().int().min(0).describe("byte offset within the region"),
+        label: z.string().optional().describe("human name for this guard byte"),
+      })).optional().describe("on:'write' exact — ABORT GUARD for a pressDuring run: caller-named 'is this scenario still valid?' bytes (e.g. the area/scene id, the player object-active flag). If ANY changes mid-run the watchpoint stops IMMEDIATELY and returns {aborted:true, abortedBy, before, after} — so a driven scenario that derailed (player died → title screen) doesn't burn all maxFrames and return a meaningless found:false. Each is sampled once per frame (cheap)."),
     },
     safeTool(async (args) => {
       switch (args.on) {
@@ -821,13 +933,17 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
 
   // ── Range watch + coverage trace (item 2, discovery) ────────────────────────
 
-  async function wRange({ start, end, kind = "both", frames = 120, pressDuring, limit = 200 }) {
+  async function wRange({ start, end, kind = "both", frames = 120, pressDuring, limit = 200, fromState, fromStatePath }) {
       const host = getHost(sessionKey);
       if (!host.rangeWatchSupported || !host.rangeWatchSupported()) {
         return jsonContent({ notSupported: true, events: [],
           note: "This core build has no range watch (shipped on all 14 platforms as of 0.6.0 — update the core package). Use breakpoint({on:'write'/'read'}) for a single address." });
       }
       if (end < start) throw new Error("watch({on:'range'}): end must be >= start.");
+      // Optionally restore a savestate FIRST, so the trace runs from a known
+      // moment (the deterministic "jump to the boss fight, then see what writes
+      // HP" loop) instead of from wherever the live session happens to be.
+      const stateInfo = await maybeRestoreState(host, fromState, fromStatePath);
       // pressDuring is driven inside the frame loop; watchRange's host method owns
       // stepping, so for now apply presses up front if any (simple: hold for the run).
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
@@ -846,19 +962,21 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       return attachObserverFrame(jsonContent({
         range: "$" + start.toString(16).toUpperCase() + "..$" + end.toString(16).toUpperCase(),
         kind, total: r.total, returned: events.length, truncated: r.truncated,
+        ...(stateInfo ? { restoredFrom: stateInfo } : {}),
         distinctPCs, events,
         note: "distinctPCs is the actionable summary — each is a routine that touches this range; disasm({target:'rom'}) one to identify the renderer/reader. " +
           (r.truncated ? "TRUNCATED: more events than the buffer held — narrow `start..end` or `frames` for the full set." : ""),
       }), host);
   }
 
-  async function wLogPC({ start, end, frames = 120, pressDuring, limit = 512 }) {
+  async function wLogPC({ start, end, frames = 120, pressDuring, limit = 512, fromState, fromStatePath }) {
       const host = getHost(sessionKey);
       if (!host.rangeWatchSupported || !host.rangeWatchSupported()) {
         return jsonContent({ notSupported: true, pcs: [],
           note: "This core build has no coverage trace (shipped on all 14 platforms as of 0.6.0 — update the core package)." });
       }
       if (end < start) throw new Error("watch({on:'pc'}): end must be >= start.");
+      const stateInfo = await maybeRestoreState(host, fromState, fromStatePath);
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
       const pressDriver = makePressDriver(host, presses);
       if (presses.length) pressDriver.applyForFrame(0);
@@ -868,6 +986,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       return attachObserverFrame(jsonContent({
         window: "$" + start.toString(16).toUpperCase() + "..$" + end.toString(16).toUpperCase(),
         distinct: r.distinct, total: r.total, returned: pcs.length, truncated: r.truncated,
+        ...(stateInfo ? { restoredFrom: stateInfo } : {}),
         pcs,
         note: "Each PC is code that EXECUTED in this window. disasm({target:'rom'}) them to find the routine you're hunting. " +
           (r.truncated ? "TRUNCATED — narrow the window for the full distinct set." : ""),
@@ -880,8 +999,8 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "• on:'mem' — the power tool: answer 'what code is touching this RAM byte?' OR extract a frame-accurate event timeline (music-driver note onsets, physics arcs). Reports every frame that changed a watched byte as {frame,offset,before,after,pc}. " +
     "Extras: `ranges:[{region,offset,length,label}]` watches MANY disjoint regions in ONE pass (identical frames); `onChange:'reset'|'increase'|'decrease'|'any'` edge filter (reset = counter-reload = the note-onset signal); `valueFilter:{min,max}`; `format:'series'` = compact columnar value-vs-frame curve (~10× smaller for a ramp); `sampleEvery`; `groupByPC` (collapse by sampled PC); `cheatLabels` (auto-name addresses from the cheat DB); `outputPath` streams all events as NDJSON; `stopOnFirst` exits on the first match. " +
     "**CAVEAT: frame-level, not instruction-level (last value per frame); the sampled `pc` is a frame-boundary sample — for ISR-driven writes use breakpoint({on:'write', precision:'exact'}) for the real writer.**\n" +
-    "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs. (Ring-buffered: `truncated:true` if it overflows.)\n" +
-    "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs.\n" +
+    "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs. (Ring-buffered: `truncated:true` if it overflows.) `fromState`/`fromStatePath` restores a savestate FIRST so the trace runs from a known moment (jump to the boss, then see what writes HP) — deterministic + repeatable.\n" +
+    "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs. Also takes `fromState`/`fromStatePath` to trace from a restored moment.\n" +
     "• on:'dma' — GENESIS ONLY: trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — WHERE in ROM?', which on:'write' can't catch). `precision:'exact'` (default) logs every mem→VDP DMA with its VRAM DESTINATION + ROM SOURCE + length (filter by `vramDest`±`destWindow`; `dedupe` collapses the per-frame refresh; `sourceFilter:'rom-only'` drops RAM→VRAM noise; catches a same-frame second DMA). `precision:'sampled'` is the cheap frame-sampled source-register read (may miss two DMAs in one frame, dest-agnostic). On non-Genesis cores returns `notSupported`.",
     {
       on: z.enum(["mem", "range", "pc", "dma"])
@@ -921,7 +1040,9 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         button: z.string(),
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range, or uploads the graphic for on:'dma')."),
+      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range, or uploads the graphic for on:'dma'). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored)."),
+      fromState: z.string().optional().describe("on:'range'/'pc' — restore an in-memory savestate SLOT (from state({op:'save', name})) BEFORE tracing, so the log runs from a known moment (jump to the boss fight, then see what writes HP). Deterministic + repeatable."),
+      fromStatePath: z.string().optional().describe("on:'range'/'pc' — like fromState but restore from a savestate FILE on disk (state({op:'save', path})). Relative path resolves against the loaded ROM's dir."),
     },
     safeTool(async (args) => {
       switch (args.on) {

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -218,6 +218,40 @@ whole attract sequence each time. `input({op:'set'})`'s `requested` echo is what
 not proof the pad saw it — verify via the held-buttons RAM byte or a state
 transition.
 
+## 6b. Iterative measurement — boot to gameplay ONCE, reload per run
+
+When you run many measurements on the same starting state (frame-by-frame
+velocity tables, per-input timing, A/B trials), do NOT replay the
+`loadMedia → step to title → press start → step into the level` preamble every
+time — that intro is often hundreds of frames and 4+ calls, and you pay it on
+every iteration. Boot once, snapshot, and reload the snapshot per run:
+
+```
+loadMedia({platform, path, cheats})         // cheats survive the save state
+frame({op:'step', frames:180})              // title renders
+input({op:'press', button:'start'})
+frame({op:'step', frames:300})              // into gameplay
+state({op:'save', name:'ready'})            // <-- the reusable starting point
+
+// then per measurement:
+state({op:'load', name:'ready'})            // 1 call instead of the whole boot
+... drive + watch ...
+```
+
+A save state captures applied cheats and the exact RAM/PPU state, so every run
+starts byte-identical — *more* repeatable than re-booting, not just cheaper. A
+named slot (`name`) lives in memory for the session; a `path` persists to disk
+across sessions. If a task says "restart before each run", a state reload
+satisfies that intent far cheaper than a fresh `loadMedia`.
+
+**Driving input through a watched run:** a `watch`/`breakpoint` with NO
+`pressDuring` inherits whatever `input({op:'set'})` last held (same as
+`frame({op:'step'})`). But if you pass `pressDuring`, that schedule OWNS the pad
+for the whole run and a prior `input({op:'set'})` is ignored — so to hold a
+button *through* a watched window, put it in `pressDuring`, not a preceding
+`set`. (This is the documented contract; the schemas of `watch`/`breakpoint`
+and `input({op:'set'})` state it too.)
+
 ---
 
 ## Quick reference

package/src/platforms/atari2600/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Atari 2600 / VCS — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"atari2600", name:"mental_model"})`).
 

package/src/platforms/atari7800/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Atari 7800 — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"atari7800", name:"mental_model"})`)
 for the "what's going on" version — the 7800 is the architectural outlier