romdevtools 0.16.0 → 0.21.0

package/src/mcp/tools/toolchain.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { TOOLCHAINS } from "../../toolchains/registry.js";
 import { buildForPlatform } from "../../toolchains/index.js";
 import { resolveLinkerConfig } from "../../toolchains/cc65/preset-resolver.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";
@@ -25,6 +26,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 +247,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 +294,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
@@ -397,7 +445,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 +518,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 }
@@ -639,7 +693,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 +791,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.

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 }
@@ -104,6 +128,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 +499,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 +511,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
@@ -655,6 +752,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         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)."),
+      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 +923,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 +952,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 +976,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 +989,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"])
@@ -922,6 +1031,8 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         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')."),
+      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/c64/MENTAL_MODEL.md

@@ -145,6 +145,48 @@ stub that does a `SYS` to the C entry point.
 For game ROMs you typically just let the user load the .prg into the
 emulator and the rest takes care of itself.
 
+## Disk images (.d64) — loading real games & distributing yours
+
+A bare `.prg` is fine for dev iteration, but the real C64 world — the new
+Commodore 64 Ultimate / C64C Ultimate FPGA hardware and the homebrew/demo
+scene — ships and loads games as **`.d64` disk images** (and `.crt` carts /
+`.tap` tapes). romdev handles them:
+
+- **Load & run a disk/cart/tape:** `loadMedia({platform:'c64', path:'game.d64'})`
+  (also `.t64 .tap .crt .g64`). VICE attaches it to drive 8 and **autostarts**
+  it (equivalent to `LOAD"*",8,1 : RUN`) under warp — give it a few hundred
+  frames to finish the emulated 1541 load, then it's running. `mediaKind` in
+  status reports `disk` / `tape` / `cartridge` / `program` so you know what you
+  loaded.
+- **Distribute YOUR game as a disk:** build your `.prg` as usual, then
+  `cart({op:'packDisk', prgPath:'game.prg'})` → an autostart-able `game.d64`
+  in the exact format the Ultimate hardware and the scene load. (`cart({op:
+  'extract', path:'x.d64'})` lists a disk's files; add `name:` to pull one out.)
+
+## Disk SAVES (the C64 save medium)
+
+The C64 has no battery SRAM — games save by **writing files to the floppy**. The
+disk IS the save, so romdev exposes the LIVE mounted `.d64` for save/restore
+(the C64 analogue of SRAM `exportSram`/`importSram`):
+
+- **Snapshot the disk** (captures any files the game wrote): `state({op:
+  'exportDisk', path:'save.d64'})`. Re-load it later with `loadMedia` (autostarts)
+  or push it back into a running session with `state({op:'importDisk', path})`.
+- **Inject a save file** a player made elsewhere, straight into the running disk:
+  `state({op:'putDiskFile', path:'progress.prg', name:'PROGRESS'})` writes one PRG
+  file via the drive. Read it back with `exportDisk` or `cart({op:'extract'})`.
+
+These work on the standard 35-track 1541 `.d64` (174848 bytes).
+
+**A game's OWN in-emulator `SAVE` works too.** When a running program does a
+KERNAL `SAVE` to drive 8, VICE commits it into the live disk image (true-drive
+GCR write-back) — so after the game saves, `state({op:'exportDisk', path})`
+captures a `.d64` that includes the new file, and you can re-load it later to
+resume. (The on-disk filename is stored in PETSCII; romdev's reader decodes it.)
+So the normal flow is just: run the game, let it save, `exportDisk` to persist.
+`putDiskFile`/`importDisk` are for *injecting* a save from outside (a save a
+player made elsewhere), not a requirement for the game's own saves.
+
 ## Frame heartbeat
 
 The C64 has no dedicated vblank interrupt by default. Two approaches:
@@ -166,7 +208,9 @@ When you call `build({output:'rom', platform:"c64", language:"c"})`:
 3. ld65 links + the bundled c64.cfg → `.prg` with a 2-byte load-address
    header.
 
-Loadable via vice_x64 (`loadMedia`).
+Loadable via vice_x64 (`loadMedia`). To ship it the way the scene/hardware
+loads games, wrap the `.prg` into a `.d64`: `cart({op:'packDisk', prgPath})`
+(see "Disk images" above).
 
 ## Horizontal scrolling (for side-scrollers)