romdevtools 0.13.0 → 0.15.0

package/src/mcp/tools/toolchain.js

@@ -293,7 +293,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         codeLoc,
         dataLoc,
       });
-      logBuildResult("buildSource", platform, result);
+      logBuildResult("build:rom", platform, result);
       // lint:"strict" — if any lint warning fired, fail the build with
       // stage:"lint" so the agent must fix patterns before iterating.
       // We mutate the result rather than re-running because the lint
@@ -396,11 +396,40 @@ 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, 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, 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}'`);
 
+      // PROJECT-DIR run: `build({output:'run', path})` with no explicit sources →
+      // read the scaffolded dir via the per-platform recipe (same as
+      // output:'project'), then run it. This is the documented "iterate on a dir"
+      // happy path; without it, output:'run' + path errored ("requires source").
+      const noExplicitSources = source == null && sourcePath == null && sources == null && sourcesPaths == null;
+      if (projPath && noExplicitSources) {
+        const r = await readProjectDir(projPath, platform);
+        includes = { ...(includes ?? {}), ...r.includes };
+        binaryIncludes = { ...(binaryIncludes ?? {}), ...r.binaryIncludes };
+        if (r.crt0 != null) crt0 = r.crt0;
+        if (r.codeLoc != null) codeLoc = r.codeLoc;
+        if (r.linkerConfig != null && linkerConfig == null) linkerConfig = r.linkerConfig;
+        if (r.runtime != null && runtime == null) runtime = r.runtime;
+        if (r.maxmod != null && maxmod == null) maxmod = r.maxmod;
+        // Single-source toolchains (dasm/atari2600, vasm/asm) need `source`, not
+        // a `sources` map. Collapse a lone source so those targets build via the
+        // dir path too. (resolveLinkerConfig support-sources, if any, force the
+        // map form below.)
+        const srcNames = Object.keys(r.sources);
+        if (srcNames.length === 1 && r.crt0 == null && r.linkerConfig == null) {
+          // Leave `source` null and set sourcePath — runSourceImpl reads it +
+          // derives sourceName (extension) for language inference. Single-source
+          // targets (dasm/vasm) require this form, not a `sources` map.
+          sourcePath = path.join(projPath, srcNames[0]);
+        } else {
+          sources = r.sources;
+        }
+      }
+
       if (source != null && sourcePath != null) {
         throw new Error("build({output:'run'}): pass either `source` OR `sourcePath`, not both.");
       }
@@ -474,7 +503,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         codeLoc,
         dataLoc,
       });
-      logBuildResult("runSource", platform, build);
+      logBuildResult("build:run", platform, build);
       if (!build.ok || !build.binary) {
         // runSource builds in-memory (no ROM path), so a large failure log
         // has nowhere to land — gate it to a tail + size rather than dumping
@@ -521,10 +550,10 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (!isPlaytestRunning(sessionKey) && !playtestHintGiven.has(sessionKey)) {
         playtestHintGiven.add(sessionKey);
         hint = "No playtest window is open. If a human is watching, consider " +
-               "`loadCategory({category:\"show\"})` then `playtest()` so they can " +
-               "play this ROM live while you keep iterating with runSource " +
-               "(rebuilds update the live game in place). Skip if this session " +
-               "is headless (CI / batch / automated).";
+               "`playtest({op:\"open\"})` so they can play this ROM live while you " +
+               "keep iterating with build({output:\"run\"}) (rebuilds update the " +
+               "live game in place). Skip if this session is headless " +
+               "(CI / batch / automated).";
       }
 
       const summary = {
@@ -648,13 +677,107 @@ export function registerToolchainTools(server, z, sessionKey) {
  * a jsonContent payload (the router calls it via safeTool, which turns a throw —
  * e.g. no entry point — into an {isError:true} result).
  */
-export async function buildProjectCore({ path: projPath, platform, outputPath }) {
+/**
+ * Per-platform recipe for building a SCAFFOLDED project directory. Given the
+ * platform + the list of filenames present, decide which file (if any) is a crt0
+ * that must be routed via `crt0`/`codeLoc` (not linked as a plain TU), which
+ * linker preset to apply, which SDK runtime to select, and which files to SKIP
+ * (preset-supplied crt0s, SDK intermediates). This is the single source of truth
+ * that makes `build({output:'project'|'run', path})` match what the scaffold
+ * README's hand-written build call does.
+ * @param {string} platform
+ * @param {string[]} names  filenames present in the project dir
+ */
+export function projectBuildRecipe(platform, names) {
+  const has = (n) => names.includes(n);
+  /** @type {{crt0File:string|null, codeLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
+  const r = { crt0File: null, codeLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
+
+  // Reference/upstream sources ship for grepping, not compiling (e.g. GB
+  // music_demo's hUGEDriver.upstream.asm — the .c port is what builds). Skip
+  // any *.upstream.* on every platform.
+  for (const n of names) if (/\.upstream\./i.test(n)) r.skip.add(n);
+
+  if (platform === "gb" || platform === "gbc") {
+    // GB/GBC ship gb_crt0.s — it MUST go via crt0+codeLoc:0x150, never as a
+    // source (SDCC emits its own gsinit → "Multiple definition of gsinit").
+    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; }
+  } else if (platform === "nes") {
+    // A SCAFFOLDED NES project ships nes_runtime.c + a crt0 + a .cfg and needs
+    // the chr-ram-runtime preset (it defines the OAM/CHARS segments + a NMI with
+    // OAM-DMA; without it: "Missing memory area 'OAM'"). The preset SUPPLIES its
+    // own crt0 + expects nes_runtime.c, so skip the scaffold's crt0/.cfg (the
+    // preset replaces them). A BARE hand-rolled NES dir (no scaffold crt0/.cfg)
+    // is left alone — forcing the preset there would demand runtime symbols it
+    // doesn't have. Detect "scaffolded" by the presence of a crt0 or .cfg.
+    const looksScaffolded = names.some((n) => /crt0.*\.s$/i.test(n) || /\.cfg$/i.test(n));
+    if (looksScaffolded) {
+      r.linkerConfig = "chr-ram-runtime";
+      for (const n of names) {
+        if (/crt0.*\.s$/i.test(n) || /\.cfg$/i.test(n)) r.skip.add(n);
+      }
+    }
+  } 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.
+    for (const n of names) if (/_crt0\.s$/i.test(n)) r.skip.add(n);
+  } else if (platform === "genesis" || platform === "megadrive" || platform === "md") {
+    // SGDK supplies sega startup + rom header. The scaffold dir may contain
+    // generated intermediates (sega.s, sega.preprocessed.s, rom_header.*, and an
+    // out/ build dir) that must NOT be recompiled — sega.preprocessed.s refs a
+    // missing out/rom_header.bin and aborts the build.
+    for (const n of names) {
+      if (/^sega(\.preprocessed)?\.s$/i.test(n) || /^rom_header\./i.test(n) || /\.preprocessed\.s$/i.test(n)) r.skip.add(n);
+    }
+  } else if (platform === "snes") {
+    const asmEntry = has("main.asm") && !has("main.c"); // asar asm template
+    if (asmEntry) {
+      // SNES asar asm template: main.asm `.include`s its siblings
+      // (lorom_header/reset_init/cgram_upload.asm). asar takes ONE source +
+      // resolves .include from the includes mount — so route non-main .asm as
+      // includes, leaving main.asm the single source.
+      for (const n of names) {
+        if (/\.asm$/i.test(n) && n !== "main.asm") r.includeAsC.add(n);
+      }
+    } else {
+      // SNES (PVSnesLib/tcc) C scaffolds combine C via `#include "snes_sfx.c"`
+      // from main.c — a single TU. A non-main .c is an INCLUDE (tcc must find it
+      // for the #include), NOT a separate source TU (which would double-define).
+      // (data.asm / snes_sfx_data.asm stay real wla sources, compiled + linked.)
+      for (const n of names) {
+        if (/\.c$/i.test(n) && n !== "main.c") r.includeAsC.add(n);
+      }
+    }
+    // The SPC700 audio driver sources (spc_driver.asm, apu_blob.asm) are 65816-
+    // INCOMPATIBLE SPC700 asm used OFFLINE to regenerate apu_blob.bin — the
+    // scaffold already ships the built .bin (incbin'd by snes_sfx_data.asm).
+    // Compiling them as 65816 sources fails ("Cannot process spc700"). Skip them.
+    for (const n of names) {
+      if (n === "spc_driver.asm" || n === "apu_blob.asm") r.skip.add(n);
+    }
+  } else if (platform === "gba") {
+    // GBA: default runtime is libtonc; a soundbank.bin means the maxmod path.
+    // The libgba-vs-libtonc choice needs the source CONTENT (which header it
+    // includes), so buildProjectCore refines r.runtime after reading main.c.
+    r.runtime = "libtonc";
+    if (has("soundbank.bin")) r.maxmod = true;
+  }
+  return r;
+}
+
+/**
+ * Read a scaffolded project DIRECTORY into the build inputs, applying the
+ * per-platform recipe (crt0 routing, linker preset, runtime, skip-list) and
+ * the GBA runtime content-sniff. The SINGLE source of truth shared by
+ * build({output:'project'}) and build({output:'run', path}) — so the two paths
+ * can never drift. Returns crt0 as RAW source text (callers assemble it).
+ * @param {string} projPath
+ * @param {string} platform
+ */
+export async function readProjectDir(projPath, platform) {
   const entries = await readdir(projPath, { withFileTypes: true });
   const files = entries.filter((e) => e.isFile());
 
-  // Entry point: a C project uses main.c (SGDK/Genesis, GBA, cc65/SDCC C); an
-  // asm project uses main.s / main.asm. Pick whichever exists — so the SAME
-  // dir-build works for C/SGDK Genesis projects, not just asm/cc65.
   const hasC = files.some((f) => f.name === "main.c");
   const hasAsm = files.some((f) => f.name === "main.s" || f.name === "main.asm");
   if (!hasC && !hasAsm) {
@@ -664,40 +787,81 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     );
   }
 
-  // Every .c/.s/.asm is its own translation unit (linked together — cc65 routes
-  // .c→cc65 + .s→ca65; SDCC/SGDK/GBA compile every .c). Every .h/.inc is an
-  // include (NOT a TU). Binary assets become binaryIncludes so .incbin survives.
+  // Per-platform PROJECT RECIPE — see projectBuildRecipe. Globbing every file as
+  // a source is what broke GB (gsinit double-def), NES (no OAM/CHARS), Genesis
+  // (sega.preprocessed.s). The recipe routes crt0 / preset / runtime / skips so
+  // the dir build matches the hand-written build({output:'run'}) call.
+  const recipe = projectBuildRecipe(platform, files.map((f) => f.name));
+
   /** @type {Record<string,string>} */ const sources = {};
   /** @type {Record<string,string>} */ const includes = {};
   /** @type {Record<string,string>} */ const binaryIncludes = {};
+  let crt0 = null;
   for (const f of files) {
     const n = f.name;
+    if (recipe.skip.has(n)) continue;
+    if (recipe.crt0File === n) { crt0 = await readFile(path.join(projPath, n), "utf-8"); continue; }
+    // includeAsC: a .c that's `#include`d by another TU (e.g. SNES main.c
+    // includes snes_sfx.c) — make it an include, NOT a separate source TU.
+    if (recipe.includeAsC.has(n)) { includes[n] = await readFile(path.join(projPath, n), "utf-8"); continue; }
     if (/\.(c|s|asm)$/i.test(n))    sources[n] = await readFile(path.join(projPath, n), "utf-8");
     else if (/\.(h|inc)$/i.test(n)) includes[n] = await readFile(path.join(projPath, n), "utf-8");
-    else if (/\.(bin|chr|pcm|brr|vgm|xgm|nsf|raw|pal)$/i.test(n)) {
+    else if (/\.(bin|chr|pcm|brr|vgm|vgz|xgm|xgc|xgm2|esf|tfi|eif|nsf|raw|pal|map|tmx|spc|wav|gbs)$/i.test(n)) {
+      // Any binary asset an .incbin might reference. (.xgc = compiled XGM2 blob,
+      // .vgz/.esf/etc = music driver inputs.) Missing one = "file not found: X".
       binaryIncludes[n] = (await readFile(path.join(projPath, n))).toString("base64");
     }
   }
 
-  // Route through resolveLinkerConfig like build({output:'rom'}) so cc65 presets
-  // + support sources still apply for a dir-built cc65 project.
-  const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, undefined);
+  // GBA runtime refinement: libgba if the entry includes <gba.h>, else the
+  // libtonc default the recipe set.
+  let runtime = recipe.runtime;
+  if (platform === "gba" && sources["main.c"] && /#\s*include\s*[<"]gba\.h[>"]/.test(sources["main.c"])) {
+    runtime = "libgba";
+  }
+
+  return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
+}
+
+export async function buildProjectCore({ path: projPath, platform, outputPath }) {
+  const { sources, includes, binaryIncludes, crt0, codeLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
+
+  // Linker preset: the recipe names it (e.g. NES 'chr-ram-runtime', which ships
+  // the OAM/CHARS segments + its own crt0). resolveLinkerConfig also returns any
+  // preset support sources (the preset crt0) — those merge into the sources.
+  const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, linkerConfig);
   const mergedSources = Object.keys(supportSources).length ? { ...supportSources, ...sources } : sources;
 
+  // Assemble a routed crt0 (SDCC sm83/z80) into a .rel, exactly like the
+  // output:'rom'/'run' path — passing it as `crt0` (NOT a source TU) is what
+  // avoids the gsinit double-definition on GB/GBC.
+  let crt0Rel;
+  if (crt0) {
+    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}`);
+    crt0Rel = asm.rel;
+  }
+
   // Single-source toolchains (dasm/atari2600, vasm/asm) take `source`, not the
   // multi-TU `sources` map. When the dir has exactly one source file and no
   // preset support sources, pass it as `source` so those targets still build
   // (the original asm-only buildProject behavior).
   const srcNames = Object.keys(sources);
-  const singleSource = srcNames.length === 1 && Object.keys(supportSources).length === 0;
+  const singleSource = srcNames.length === 1 && Object.keys(supportSources).length === 0 && !crt0Rel;
   const result = await buildForPlatform({
     platform,
+    runtime,
+    maxmod,
     ...(singleSource
       ? { source: sources[srcNames[0]], sourceName: srcNames[0] }
       : { sources: mergedSources }),
     includes: Object.keys(includes).length ? includes : undefined,
     binaryIncludes: Object.keys(binaryIncludes).length ? binaryIncludes : undefined,
     linkerConfig: resolvedLinkerConfig,
+    crt0: crt0Rel,
+    codeLoc,
   });
   if (outputPath && result.binary) {
     await mkdir(path.dirname(outputPath), { recursive: true });

package/src/mcp/tools/trace-vram-source.js

@@ -19,7 +19,7 @@ import { jsonContent } from "../util.js";
 import { decodeDMASource } from "../../platforms/genesis/vdp.js";
 import { makePressDriver } from "./watch-memory.js";
 
-// traceVramSource → dmaTrace({precision:'sampled'}) (router in watch-memory.js).
+// traceVramSource → watch({on:'dma', precision:'sampled'}) (router in watch-memory.js).
 // Exported core; the router passes its own sessionKey.
 export async function traceVramSourceCore({ frames = 120, pressDuring, romPreviewBytes = 16, minLengthBytes = 0, sessionKey }) {
       const host = getHost(sessionKey);
@@ -76,6 +76,6 @@ export async function traceVramSourceCore({ frames = 120, pressDuring, romPrevie
       });
 }
 
-// traceVramSource is registered as dmaTrace({precision:'sampled'}) by the
-// `dmaTrace` router in watch-memory.js (which imports traceVramSourceCore).
+// traceVramSource is reached via watch({on:'dma', precision:'sampled'}) by the
+// `watch` tool in watch-memory.js (which imports traceVramSourceCore).
 export function registerTraceVramSourceTools() {}

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

@@ -881,10 +881,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "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.",
+    "• 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:'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"])
-        .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]."),
+      on: z.enum(["mem", "range", "pc", "dma"])
+        .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]; dma=Genesis-only mem→VDP DMA source/dest trace."),
       // on:'mem'
       region: z.enum(MEMORY_REGIONS).optional().describe("on:'mem' single-range — the region to watch (same canonical set memory uses, incl. nes_apu_regs, genesis_ym2612, c64_sid_regs). Omit when using `ranges`."),
       offset: z.number().int().min(0).default(0).describe("on:'mem' single-range — first byte of the watched range."),
@@ -907,12 +908,20 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       frames: z.number().int().min(1).max(1_000_000).default(600).describe("Frames to run while logging (default 600). on:'range'/'pc' windows are usually short (~120) — pass a smaller value to keep the ring buffer from overflowing."),
       limit: z.number().int().min(1).max(4000).default(200).describe("on:'range'/'pc' — max events/PCs returned (default 200; full count is in `total`)."),
       outputPath: z.string().optional().describe("on:'mem' — stream every filter-passing event to this path as NDJSON + return a compact summary. Use for long watches so the full log never enters your context."),
+      // on:'dma' (Genesis VDP DMA trace)
+      precision: z.enum(["exact", "sampled"]).default("exact").describe("on:'dma' — exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic)."),
+      vramDest: z.number().int().min(0).optional().describe("on:'dma' precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
+      destWindow: z.number().int().min(0).default(0x40).describe("on:'dma' precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
+      dedupe: z.boolean().default(true).describe("on:'dma' precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
+      sourceFilter: z.enum(["all", "rom-only", "ram-only"]).default("all").describe("on:'dma' precision:'exact' — 'rom-only' drops the RAM→VRAM per-frame refresh noise; 'ram-only' keeps only it."),
+      romPreviewBytes: z.number().int().min(0).max(64).default(0).describe("on:'dma' — bytes of the ROM source to preview per DMA (exact default 0; sampled default 16)."),
+      minLengthBytes: z.number().int().min(0).max(65536).default(0).describe("on:'dma' precision:'sampled' — ignore DMAs shorter than this many bytes (filters tiny scroll/sprite updates so graphic uploads stand out)."),
       pressDuring: z.array(z.object({
         frame: z.number().int().min(0),
         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)."),
+      })).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')."),
     },
     safeTool(async (args) => {
       switch (args.on) {
@@ -925,19 +934,27 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           if (args.start == null || args.end == null) throw new Error("watch({on:'pc'}): `start` and `end` are required.");
           return await wLogPC({ ...args, frames: args.frames ?? 120, limit: args.limit ?? 512 });
         }
+        case "dma": {
+          const a = { ...args, frames: args.frames ?? 120, limit: args.limit ?? 200 };
+          if (a.precision === "sampled") {
+            return await traceVramSourceCore({ ...a, romPreviewBytes: a.romPreviewBytes || 16, sessionKey });
+          }
+          return await dmaExact(a);
+        }
         default: throw new Error(`watch: unknown on '${args.on}'`);
       }
     }),
   );
 
-  // ── dmaTrace (item 3, Genesis only) ─────────────────────────────────────────
+  // ── watch({on:'dma'}) helpers (Genesis only) ────────────────────────────────
   // precision:exact = dmaExact (watchDma, per-DMA core log), precision:sampled =
-  // traceVramSourceCore (frame-sampled, dest-agnostic).
+  // traceVramSourceCore (frame-sampled, dest-agnostic). Routed by the `watch`
+  // tool's switch (case 'dma'); folded in from the old standalone dmaTrace tool.
   async function dmaExact({ frames = 120, vramDest, destWindow = 0x40, dedupe = true, sourceFilter = "all", pressDuring, romPreviewBytes = 0, limit = 200 }) {
       const host = getHost(sessionKey);
       if (!host.dmaWatchSupported || !host.dmaWatchSupported()) {
         return jsonContent({ notSupported: true, dmas: [],
-          note: "dmaTrace is Genesis-only (VDP DMA). On other platforms use breakpoint({on:'write'}) (CPU writes) or the platform's source tracer." });
+          note: "watch({on:'dma'}) is Genesis-only (VDP DMA). On other platforms use breakpoint({on:'write'}) (CPU writes) or the platform's source tracer." });
       }
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
       const pressDriver = makePressDriver(host, presses);
@@ -994,43 +1011,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           (totalDistinct > limit ? `Showing ${out.length}/${totalDistinct} distinct — raise limit or narrow vramDest.` : ""),
       }), host);
   }
-
-  server.tool(
-    "dmaTrace",
-    "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 breakpoint({on:'write'}) can't catch). Keyed by `precision`.\n" +
-    "• precision:'exact' (default) — log every mem→VDP DMA with its VRAM DESTINATION, ROM SOURCE, length, and code. " +
-    "Filter by `vramDest` (±`destWindow`) to find the exact source of a specific tile. `dedupe` collapses the per-frame " +
-    "refresh (7000 events → a handful); `sourceFilter:'rom-only'` drops the RAM→VRAM sprite/scroll noise. " +
-    "**Catches a second DMA in the same frame that the sampled mode misses.**\n" +
-    "• precision:'sampled' — the cheap frame-sampled tracer: reads the VDP DMA source registers ($15-$17) once per frame " +
-    "and logs each DISTINCT mem→VRAM source as a ROM byte offset. **HONEST LIMIT: two DMAs in the SAME frame may show only " +
-    "one source — narrow the window around when the graphic appears. dest-agnostic (no vramDest filter).**",
-    {
-      precision: z.enum(["exact", "sampled"]).default("exact")
-        .describe("exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic)."),
-      frames: z.number().int().min(1).max(6000).default(120).describe("Frames to step while tracing (default 120 ≈ 2s)."),
-      pressDuring: z.array(z.object({
-        frame: z.number().int().min(0),
-        button: z.string(),
-        port: z.number().int().min(0).max(3).default(0),
-        holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Drive input to the screen that uploads the graphic."),
-      romPreviewBytes: z.number().int().min(0).max(64).default(0).describe("Bytes of the ROM source to preview per DMA (exact default 0; sampled default 16)."),
-      // precision:'exact' only
-      vramDest: z.number().int().min(0).optional().describe("precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
-      destWindow: z.number().int().min(0).default(0x40).describe("precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
-      dedupe: z.boolean().default(true).describe("precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
-      sourceFilter: z.enum(["all", "rom-only", "ram-only"]).default("all").describe("precision:'exact' — 'rom-only' drops the RAM→VRAM per-frame refresh noise; 'ram-only' keeps only it."),
-      limit: z.number().int().min(1).max(2000).default(200).describe("precision:'exact' — max DMA entries to return (after dedupe/filter)."),
-      // precision:'sampled' only
-      minLengthBytes: z.number().int().min(0).max(65536).default(0).describe("precision:'sampled' — ignore DMAs shorter than this many bytes (filters tiny scroll/sprite updates so graphic uploads stand out)."),
-    },
-    safeTool(async (args) => {
-      if (args.precision === "sampled") {
-        return await traceVramSourceCore({ ...args, romPreviewBytes: args.romPreviewBytes || 16, sessionKey });
-      }
-      return await dmaExact(args);
-    }),
-  );
+  // dmaExact + traceVramSourceCore are reached via watch({on:'dma'}) above —
+  // dmaTrace was folded into `watch` (it's a log-all VDP-DMA trace, same family
+  // as on:'mem'/'range'/'pc'), so there's no separate top-level tool.
 }

package/src/observer/livestream.html

@@ -20,9 +20,19 @@
   }
   header h1 { margin: 0; font-size: 14px; font-weight: 600; }
   #version { font-size: 11px; font-weight: 400; color: #888; }
-  #status { font-size: 11px; color: #888; }
+  header a.doclink {
+    font-size: 11px; color: #6cb6ff; text-decoration: none;
+    border: 1px solid #2a3f55; border-radius: 3px; padding: 2px 7px;
+  }
+  header a.doclink:hover { background: #14202e; text-decoration: underline; }
+  #status { font-size: 11px; color: #888; margin-left: auto; }
   #status.connected { color: #4caf50; }
   #status.disconnected { color: #f44336; }
+  #log-session {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 12px; color: #6cb6ff; padding: 2px 0 8px;
+    word-break: break-all;
+  }
   #tabs {
     display: flex; flex-wrap: wrap; gap: 4px;
     padding: 6px 12px; background: #111; border-bottom: 1px solid #333;
@@ -172,6 +182,7 @@
 <body>
 <header>
   <h1>romdev /livestream <span id="version">__ROMDEV_VERSION__</span></h1>
+  <a class="doclink" href="/documentation" target="_blank" rel="noopener">API docs ↗</a>
   <span id="status" class="disconnected">disconnected</span>
 </header>
 <div id="tabs"></div>
@@ -183,6 +194,7 @@
   </div>
   <div id="log-pane">
     <h2>Activity log</h2>
+    <div id="log-session"></div>
     <div id="log-list"></div>
   </div>
 </div>
@@ -195,6 +207,7 @@
   const tabsEl = document.getElementById("tabs");
   const imageListEl = document.getElementById("image-list");
   const logListEl = document.getElementById("log-list");
+  const logSessionEl = document.getElementById("log-session");
   const emptyEl = document.getElementById("empty");
 
   // Per-session state.
@@ -345,10 +358,22 @@
       tab.className = "tab" + (k === activeSessionKey ? " active" : "")
         + (!s.connected ? " disconnected" : "");
       tab.onclick = () => selectTab(k);
-      tab.innerHTML = `<span>${k.slice(0, 8)}</span>`
-        + (s.unseen > 0 && k !== activeSessionKey
-            ? ` <span class="badge">${s.unseen}</span>` : "");
-      if (!s.connected) tab.title = "session closed";
+      // Show the FULL session id — agents pick descriptive ids (e.g.
+      // "scaffold-nes-platformer") and truncating to 8 chars collapsed distinct
+      // tasks into identical-looking tabs ("scaffold" × N). Cap very long ids in
+      // the middle so the meaningful head+tail both show; full id in the tooltip.
+      const label = k.length > 28 ? k.slice(0, 18) + "…" + k.slice(-8) : k;
+      const labelSpan = document.createElement("span");
+      labelSpan.textContent = label;
+      tab.appendChild(labelSpan);
+      if (s.unseen > 0 && k !== activeSessionKey) {
+        const badge = document.createElement("span");
+        badge.className = "badge";
+        badge.textContent = String(s.unseen);
+        tab.appendChild(document.createTextNode(" "));
+        tab.appendChild(badge);
+      }
+      tab.title = s.connected ? k : `${k} (session closed)`;
       tabsEl.appendChild(tab);
     }
   }
@@ -498,6 +523,17 @@
 
   function renderLog() {
     logListEl.innerHTML = "";
+    // Full session id above the log — the tab label can be middle-truncated, so
+    // this is the one place that always shows the EXACT id you're looking at.
+    if (logSessionEl) {
+      if (activeSessionKey) {
+        logSessionEl.textContent = "session: " + activeSessionKey;
+        logSessionEl.style.display = "";
+      } else {
+        logSessionEl.textContent = "";
+        logSessionEl.style.display = "none";
+      }
+    }
     if (!activeSessionKey) return;
     const s = sessions.get(activeSessionKey);
     // Newest first — easier to scan when working live.

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -56,7 +56,7 @@ font-rendered from an ASCII string. Patching the ASCII string then does nothing.
    string. Do not patch any ASCII string you found; it isn't the source.
 2. If it IS font-rendered, find the string with `text({op:'find'})` /
    `text({op:'encode'})` and patch that.
-3. To find where a graphic/text was sourced from: on **Genesis**, `dmaTrace({precision:'sampled'})`
+3. To find where a graphic/text was sourced from: on **Genesis**, `watch({on:'dma', precision:'sampled'})`
    — drive to the screen that shows the graphic, and it reports the ROM offset(s)
    the tiles were DMA'd from (decoded from the VDP DMA registers). Edit the tile
    bitmaps at that offset, not any string. (Elsewhere: if `breakpoint({on:'write'})` on the VRAM
@@ -198,8 +198,8 @@ Breakpoints are great once you KNOW the address. To FIND it:
 - **`watch({on:'pc', start, end, frames})`** — coverage trace: every DISTINCT PC that
   EXECUTED in an address window. "What code runs in this bank during the scoreboard
   draw?" → `disasm({target:'rom'})` the PCs it returns.
-- **`dmaTrace({precision:'exact', vramDest})`** (Genesis) — which DMA wrote the tile at a VRAM dest,
-  and the ROM SOURCE it came from. The targeted version of `dmaTrace({precision:'sampled'})`; the
+- **`watch({on:'dma', precision:'exact', vramDest})`** (Genesis) — which DMA wrote the tile at a VRAM dest,
+  and the ROM SOURCE it came from. The targeted version of `watch({on:'dma', precision:'sampled'})`; the
   way to catch a DMA'd (not CPU-written) name/portrait bitmap `breakpoint({on:'write'})` can't see.
 
 ---
@@ -238,8 +238,8 @@ transition.
 | Re-inject edited bytes the game accepts | `romPatch({op:'makeStored'})` (verbatim-expand block) → `romPatch({op:'findFree'})` → `romPatch({op:'relocate'})` |
 | Find the pointer that loads an asset | `romPatch({op:'findPointer', romOffset})` |
 | FIND the unknown routine touching X | `watch({on:'range', start,end})` (all hits) / `watch({on:'pc'})` (coverage) |
-| Which DMA wrote a VRAM tile + its source (Genesis) | `dmaTrace({precision:'exact', vramDest})` |
-| Where did a VRAM graphic come from (Genesis) | `dmaTrace({precision:'sampled'})` (ROM offset of the DMA source) |
+| Which DMA wrote a VRAM tile + its source (Genesis) | `watch({on:'dma', precision:'exact', vramDest})` |
+| Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |
 | Free RAM map for a known game | `cheats({op:'lookup'})` / `cheats({op:'search'})` |
 | Safe patch | `romPatch({op:'write'})`/`romPatch({op:'writeMany'})` with `expect` |

package/src/platforms/gb/MENTAL_MODEL.md

@@ -20,7 +20,7 @@ check these first. All five have shipped fixes in the bundled runtime
    classic white-screen: a stray $FF pad there trips CGB mode on a DMG
    ROM so BGP/OBP* writes are ignored. Because the build sets it from the
    platform you chose, a freshly built ROM is correct with **no manual
-   step**. Call `patchGbHeader` only to fix up an existing/external ROM
+   step**. Call `romPatch({op:'gbHeader'})` only to fix up an existing/external ROM
    or override a field (title, cart type, ROM/RAM size, CGB flag).
 
 2. **OAM shadow buffer must be page-aligned.** OAM DMA copies 160 bytes
@@ -122,7 +122,7 @@ running a CGB-aware ROM, the DMG registers are ignored.
 You normally don't touch this byte by hand: `build({output:'rom'})` / `build({output:'run'})`
 set it from the platform you build for ($00 for `platform:"gb"`, $80/$C0
 for `platform:"gbc"`). To force a value, set it in your `gb_crt0.s`
-header section, or call `patchGbHeader({path, cgb:true})` on the built
+header section, or call `romPatch({op:'gbHeader', path, cgb:true})` on the built
 ROM (it auto-detects the `.gbc` extension; the standalone
 `patch-header.js` script does the same).
 
@@ -201,7 +201,7 @@ Build calls explicitly reference these files via `sourcesPaths` /
 `includePaths` / `crt0Path` + `codeLoc: 0x150`. `build({output:'rom'})` /
 `build({output:'run'})` then fix up the cart header automatically (logo, checksums,
 CGB flag), so the ROM loads under gambatte with no extra step. Use
-`patchGbHeader({path})` (MCP tool) or `node patch-header.js <rom>` (CLI)
+`romPatch({op:'gbHeader', path})` (romdev tool) or `node patch-header.js <rom>` (CLI)
 only on a ROM the build pipeline didn't produce. See your project's
 README for the exact incantation.
 

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -92,7 +92,7 @@ the cross-platform note: [[sdcc-uint8-loop-bound-trap]].
    `platform:"gb"` and it stays $00 (DMG). So if colors are wrong, first
    check you didn't build this as a `.gb` ROM — rebuild with
    `platform:"gbc"`. (To force a value on an existing ROM: set it in your
-   `gb_crt0.s` header section, run `patchGbHeader({path:"out.gbc"})`, or
+   `gb_crt0.s` header section, run `romPatch({op:'gbHeader', path:"out.gbc"})`, or
    run `node patch-header.js out.gbc`.) Verify:
    ```sh
    xxd -s 0x143 -l 1 out.gbc      # expect: 80

package/src/platforms/gb/UPSTREAM_SOURCES.md

@@ -36,7 +36,7 @@ upstream README. Songs are exported from hUGETracker
 - "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
   `gb_runtime.c` `oam_dma_copy` implementation
 - "BGP write does nothing" → check $0143 (CGB flag) via
-  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+  `romPatch({op:'gbHeader'})` + Pan Docs § "The Cartridge Header"
 - "How does hUGEDriver process a song row?" → `hUGEDriver.c`
   `hUGE_dosound` body — fully readable
 - "Why is gambatte refusing my ROM?" → check the header, then

package/src/platforms/gb/lib/c/README.md

@@ -23,12 +23,12 @@ run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
 header checksum at $014D, global checksum at $014E, cartridge-type /
 RAM-size bytes, and the CGB flag at $0143 ($00 for `.gb`, $80/$C0 for
 `.gbc`). A freshly built ROM boots on hardware and strict cores with
-**no extra step** — you do not call `patchGbHeader` after a normal build.
+**no extra step** — you do not call `romPatch({op:'gbHeader'})` after a normal build.
 
 Reach for header tooling only when working with a ROM the build pipeline
 didn't produce, or to override a field:
 
-- `patchGbHeader({path: "out.gb"})` — MCP tool.
+- `romPatch({op:'gbHeader', path: "out.gb"})` — romdev tool.
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into

package/src/platforms/gb/lib/c/SDCC_GOTCHAS.md

@@ -110,7 +110,7 @@ If you need to write a custom VRAM block-copy:
 
 This is independent of the R26 OAM-alignment fix (`shadow_oam __at
 (0xC100)`) and the header CGB-flag fix (now applied automatically by
-`build({output:'rom'})` / `build({output:'run'})`, not a manual `patchGbHeader` step). All
+`build({output:'rom'})` / `build({output:'run'})`, not a manual `romPatch({op:'gbHeader'})` step). All
 three are silent-failure bugs that look like "did my changes even
 land?" and need different fixes.