romdevtools 0.13.0 → 0.15.0

package/src/mcp/tools/playtest.js

@@ -7,6 +7,7 @@ import { writeFile } from "node:fs/promises";
 
 import { getHost, getHostOrNull } from "../state.js";
 import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
+import { log } from "../log.js";
 
 // Playtest windows are PER SESSION: the MCP server is multi-session (one server
 // serves several agents at once), and the same user can have 2-3 different games
@@ -104,14 +105,13 @@ export function isPlaytestRunning(sessionKey) {
 export function registerPlaytestTools(server, z, sessionKey) {
   // op:'open' — open (or reuse) the SDL window for this session.
   async function ptOpen({ scale = 3, title, aspect = "tv" }) {
-      // No preflight display checks. We just attempt to open the SDL window and
-      // report whatever SDL says — env-var guessing (DISPLAY/WAYLAND_DISPLAY)
-      // is Linux-only and wrong on macOS/Windows, where those vars are never
-      // set even with a full GUI session. SDL's createWindow already knows
-      // whether it can draw on any platform; the try/catch below surfaces the
-      // real error.
       const host = getHost(sessionKey);
       const loadedMediaPath = host.status?.mediaPath ?? null;
+      // No env-var preflight here — the GROUND-TRUTH "is there a real display?"
+      // check lives in loadSdl() (it asks SDL which video driver it selected and
+      // throws sdlKind:"no-display" if it's offscreen/dummy). That's cross-
+      // platform and doesn't false-bark on valid offscreen setups like Xvfb.
+      // The try/catch below surfaces it (and the binary errors) uniformly.
       if (reconcileSession(sessionKey)) {
         // THIS session already has a window open. We don't open a second one for
         // the same session — it shares this session's live host — so report the
@@ -153,44 +153,55 @@ export function registerPlaytestTools(server, z, sessionKey) {
           "stepFrames / pressButton) still works against the live ROM — only " +
           "the interactive window is affected.";
 
-        if (kind === "missing-binary" || kind === "install-failed") {
+        // A failed window-open is a REAL FAILURE — THROW it, don't return a soft
+        // {opened:false} object. Returning success-shaped JSON made the failure
+        // invisible on the REST/skill surface (HTTP 200 = "it worked"), so an
+        // agent driving the routes would report "window's up!" while no window
+        // exists. Thrown → safeTool tags isError → runTool maps it to HTTP 400
+        // (REST) and a tool error (MCP). We also log to the server console so a
+        // human watching the terminal sees it even if the agent buries the error.
+        let reason, message;
+        if (kind === "no-display") {
+          // GROUND TRUTH: SDL came up on the offscreen/dummy driver — there is no
+          // physical screen to show the window on (it would render + play audio
+          // but be invisible). loadSdl()'s message already says exactly this + the
+          // fix; pass it straight through.
+          reason = "no-display";
+          message = (e?.message ?? String(e)) + headlessNote;
+        } else if (kind === "missing-binary" || kind === "install-failed") {
           // Native-addon problem, NOT a display problem.
           const fix = e?.fixCmd
             ? `Run: ${e.fixCmd} (then restart the server). `
             : "Reinstall @kmamal/sdl so its prebuilt binary is fetched. ";
-          return jsonContent({
-            opened: false,
-            reason: "sdl-binary-missing",
-            platform: process.platform,
-            message:
-              "The playtest window couldn't open because the @kmamal/sdl native " +
-              "binary isn't installed: " + (e?.message ?? String(e)) + ". " +
-              (kind === "install-failed"
-                ? "An automatic install was attempted but failed (often a network/proxy block on the GitHub release download). "
-                : "(This is common under `npx romdevtools` — npm skips @kmamal/sdl's install script that fetches the binary; the server tried to self-heal but the binary is still absent.) ") +
-              fix + "This is a one-time native-addon fix, NOT a display/desktop " +
-              "issue." + headlessNote,
-            fixCommand: e?.fixCmd ?? null,
-            loadedMediaPath,
-          });
-        }
-
-        // A genuine SDL init / display failure (e.g. no video device, no
-        // desktop session). NOW the desktop-session advice is the right call.
-        return jsonContent({
-          opened: false,
-          reason: "sdl-error",
-          platform: process.platform,
-          message:
+          reason = "sdl-binary-missing";
+          message =
+            "The playtest window couldn't open because the @kmamal/sdl native " +
+            "binary isn't installed: " + (e?.message ?? String(e)) + ". " +
+            (kind === "install-failed"
+              ? "An automatic install was attempted but failed (often a network/proxy block on the GitHub release download). "
+              : "(This is common under `npx romdevtools` — npm skips @kmamal/sdl's install script that fetches the binary; the server tried to self-heal but the binary is still absent.) ") +
+            fix + "This is a one-time native-addon fix, NOT a display/desktop " +
+            "issue." + headlessNote;
+        } else {
+          // A genuine SDL init / display failure (no video device / no desktop
+          // session). The desktop-session advice is the right call here.
+          reason = "sdl-error";
+          message =
             "Couldn't open the SDL playtest window: " + (e?.message ?? String(e)) +
             ". SDL initialized but couldn't get a display. This usually means the " +
             "server has no access to a logged-in desktop session — e.g. it was " +
             "spawned as an MCP subprocess by your agent host, or runs over plain " +
             "SSH/headless. The reliable fix: run the server yourself in a terminal " +
             "inside your desktop session, then connect your agent to it." +
-            headlessNote + " You can also open the built ROM in any standalone emulator.",
-          loadedMediaPath,
-        });
+            headlessNote + " You can also open the built ROM in any standalone emulator.";
+        }
+        // Server-console breadcrumb (stderr) so a human at the terminal sees the
+        // failure regardless of whether the agent relays the tool error.
+        log.error(`playtest: window failed to open (${reason}) — ${e?.fixCmd ? "fix: " + e.fixCmd : message.slice(0, 120)}`);
+        const err = new Error(message);
+        err.reason = reason;
+        if (e?.fixCmd) err.fixCommand = e.fixCmd;
+        throw err;
       }
       // Detach so process doesn't hang on the closed promise. Only clear THIS
       // session's slot, and only if it still points at this same session (a
@@ -284,7 +295,9 @@ export function registerPlaytestTools(server, z, sessionKey) {
         });
       }
       if (!inline && !outPath) {
-        return jsonContent({ ok: false, error: "pass `path` (where to write the PNG) or `inline:true`." });
+        // Usage error → throw so REST returns 400 (not a 200 with ok:false the
+        // caller might ignore).
+        throw new Error("playtest framebuffer: pass `path` (where to write the PNG) or `inline:true`.");
       }
       const frame = sessions.get(sessionKey).captureFrame();
       if (!frame) {

package/src/mcp/tools/project.js

@@ -3,13 +3,12 @@
 // Policy (2026-05-25): no auto-injection at build time. createProject copies
 // every file the template depends on (runtime, headers, crt0, linker .cfg)
 // into the project directory. The project is then self-contained — any
-// `buildSource` / `runSource` call points at the project's own files via
+// `build({output:'run'})` call points at the project's own files via
 // sources/sourcesPaths/includePaths/crt0/linkerConfig args. If you take
 // the project elsewhere and rebuild with cc65/sdcc directly, every byte
 // that compiles is in the directory.
 
 import { readFile, writeFile } from "node:fs/promises";
-import { patchGbHeader } from "../../platforms/gb/lib/c/patch-header.js";
 import { jsonContent, safeTool } from "../util.js";
 import { starterSnippetsCore, copyStarterSnippetsCore } from "./snippets.js";
 
@@ -320,7 +319,7 @@ TEMPLATES.gbc = {
   default: {
     main: "templates/default.c", runtime: GBC_RUNTIME,
     lang: GBC_LANG, ext: ".gbc",
-    describe: "Minimal GBC starter. Same shape as the GB default but ROM extension .gbc — patchGbHeader sets $0143=$80 so gambatte boots in CGB mode.",
+    describe: "Minimal GBC starter. Same shape as the GB default but ROM extension .gbc — the GB-header patch sets $0143=$80 so gambatte boots in CGB mode.",
   },
   hello_sprite: {
     main: "templates/hello_sprite.c", runtime: GBC_RUNTIME,
@@ -1087,7 +1086,7 @@ TEMPLATES.gba = {
     runtimeDirs: GBA_LIBTONC_RUNTIME_DIRS,
     lang: GBA_TONC_LANG,
     ext: ".gba",
-    describe: "Idiomatic Tonc-tutorial GBA C starter. #include <tonc.h>, TTE (Tonc Text Engine) draws 'Hello, Tonc!' on BG0 in MODE_0. Matches what every published GBA C tutorial at gbadev.net teaches. libtonc is compiled from its vendored source by the build (a fast prebuilt seed by default; pass rebuildSdk:true if you edit the SDK source) — the project gets the headers + gba_crt0 + linker script. Build with buildSource({platform:'gba', language:'c'}) — defaults to runtime:'libtonc'.",
+    describe: "Idiomatic Tonc-tutorial GBA C starter. #include <tonc.h>, TTE (Tonc Text Engine) draws 'Hello, Tonc!' on BG0 in MODE_0. Matches what every published GBA C tutorial at gbadev.net teaches. libtonc is compiled from its vendored source by the build (a fast prebuilt seed by default; pass rebuildSdk:true if you edit the SDK source) — the project gets the headers + gba_crt0 + linker script. Build with build({output:'run', platform:'gba', language:'c'}) — defaults to runtime:'libtonc'.",
   },
   tonc_hello_sprite: {
     main: "templates/tonc_hello_sprite.c",
@@ -1145,10 +1144,10 @@ TEMPLATES.gba = {
     runtimeDirs: GBA_LIBGBA_RUNTIME_DIRS,
     lang: GBA_LIBGBA_LANG,
     ext: ".gba",
-    describe: "Alternate GBA C starter using devkitPro's libgba SDK. MODE_3 framebuffer + red pixel. Pass runtime:'libgba' to buildSource — or just use the Tonc path (gba_hello_tonc) which is better aligned with what published tutorials teach.",
+    describe: "Alternate GBA C starter using devkitPro's libgba SDK. MODE_3 framebuffer + red pixel. Pass runtime:'libgba' to build({output:'run'}) — or just use the Tonc path (gba_hello_tonc) which is better aligned with what published tutorials teach.",
   },
   // R34: maxmod music demo. Ships a hand-authored CC0 chiptune.xm +
-  // its pre-built soundbank.bin. buildSource must be called with
+  // its pre-built soundbank.bin. build({output:'run'}) must be called with
   // `maxmod: true` AND binaryIncludes:{ "soundbank.bin": <bytes> } —
   // the buildGbaC layer auto-emits a `.incbin "soundbank.bin"` asm
   // stub exposing the soundbank under the global symbol soundbank_bin.
@@ -1174,7 +1173,7 @@ TEMPLATES.gba = {
     ext: ".gba",
     maxmod: true,
     binaryIncludes: ["soundbank.bin"],
-    describe: "Maxmod music demo (Tonc + libmm). Plays a CC0 chiptune.xm soundbank via mmInitDefault + mmStart + mmFrame, with START toggling pause. Pass `maxmod:true` AND `binaryIncludes:{\"soundbank.bin\": <bytes>}` to buildSource. The .xm source + generator script + pre-built soundbank.bin all ship in the project — edit and re-run mmutil to swap the tune.",
+    describe: "Maxmod music demo (Tonc + libmm). Plays a CC0 chiptune.xm soundbank via mmInitDefault + mmStart + mmFrame, with START toggling pause. Pass `maxmod:true` AND `binaryIncludes:{\"soundbank.bin\": <bytes>}` to build({output:'run'}). The .xm source + generator script + pre-built soundbank.bin all ship in the project — edit and re-run mmutil to swap the tune.",
   },
 };
 
@@ -1559,11 +1558,11 @@ Compiles **C89**, not C99/C11. Stick to:
     const incLines = runtimeHeaders.length > 0
       ? runtimeHeaders.map((h) => `    "${h.dst}":  "${h.dst}",`).join("\n")
       : "";
-    buildBlock = "```js\nrunSource({\n  platform: \"" + platform + "\",\n  sourcesPaths: {\n" + srcLines + "\n  },\n" + (incLines ? "  includePaths: {\n" + incLines + "\n  },\n" : "") + "  linkerConfig: /* contents of " + tmpl.linkerConfig.dst + " */,\n  frames: 60,\n})\n```";
+    buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"" + platform + "\",\n  sourcesPaths: {\n" + srcLines + "\n  },\n" + (incLines ? "  includePaths: {\n" + incLines + "\n  },\n" : "") + "  linkerConfig: /* contents of " + tmpl.linkerConfig.dst + " */,\n  frames: 240,\n})\n```";
   } else if (isSdccSm83) {
-    // GB / GBC (SDCC sm83). runSource BUILDS + RUNS + SCREENSHOTS in one
-    // call AND auto-fixes the cartridge header (Nintendo logo, header +
-    // global checksums, CGB flag on .gbc) — no manual patchGbHeader step.
+    // GB / GBC (SDCC sm83). build({output:'run'}) BUILDS + RUNS + SCREENSHOTS
+    // in one call AND auto-fixes the cartridge header (Nintendo logo, header +
+    // global checksums, CGB flag on .gbc) — no manual header-patch step.
     // Derive sources/includes from the template's runtime list so extra
     // .c files (e.g. music_demo's hUGEDriver) are listed too.
     const runtimeCs = (tmpl?.runtime ?? []).filter((r) => /\.c$/i.test(r.dst));
@@ -1574,7 +1573,7 @@ Compiles **C89**, not C99/C11. Stick to:
       ? runtimeHeaders.map((h) => `    "${h.dst}": "${h.dst}",`).join("\n")
       : "";
     buildBlock =
-      "```js\nrunSource({\n" +
+      "```js\nbuild({\n  output: \"run\",\n" +
       "  platform: \"" + platform + "\",\n" +
       "  sourcesPaths: {\n" + srcLines + "\n  },\n" +
       (incLines ? "  includePaths: {\n" + incLines + "\n  },\n" : "") +
@@ -1582,20 +1581,20 @@ Compiles **C89**, not C99/C11. Stick to:
       "  codeLoc: 0x150,\n" +
       "  frames: 60,\n" +
       "})\n```\n\n" +
-      "`runSource` auto-fixes the GB/GBC cartridge header (logo, checksums, " +
-      "CGB flag) — you do **not** call `patchGbHeader` for a freshly built " +
-      "ROM. Use `patchGbHeader` only to fix up an existing/external ROM on " +
-      "disk or to override header fields (title, cart type, ROM/RAM size).";
+      "`build({output:\"run\"})` auto-fixes the GB/GBC cartridge header (logo, checksums, " +
+      "CGB flag) — you do **not** call a header patch for a freshly built " +
+      "ROM. Use `romPatch({op:'gbHeader'})` only to fix up an existing/external " +
+      "ROM on disk or to override header fields (title, cart type, ROM/RAM size).";
   } else if (isSdccZ80) {
     const inc = runtimeHeaders.length > 0
       ? `\n  includePaths: { ${runtimeHeaders.map((h) => `"${h.dst}": "${h.dst}"`).join(", ")} },`
       : "";
-    buildBlock = "```js\nrunSource({\n  platform: \"" + platform + "\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 60,\n})\n```";
+    buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"" + platform + "\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 240,\n})\n```";
   } else if (platform === "c64") {
     const inc = runtimeHeaders.length > 0
       ? `\n  includePaths: { ${runtimeHeaders.map((h) => `"${h.dst}": "${h.dst}"`).join(", ")} },`
       : "";
-    buildBlock = "```js\nrunSource({\n  platform: \"c64\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 60,\n})\n```";
+    buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"c64\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 240,\n})\n```";
   } else if (platform === "snes" && /\.c$/i.test(mainFilename)) {
     // R19b: SNES C-mode template (PVSnesLib runtime auto-linked). Multi-file
     // build with sibling .asm providing data symbols (tilfont/palfont).
@@ -1632,7 +1631,7 @@ Compiles **C89**, not C99/C11. Stick to:
       .join("\n");
 
     buildBlock =
-      "```js\nrunSource({\n" +
+      "```js\nbuild({\n  output: \"run\",\n" +
       "  platform: \"snes\",\n" +
       "  language: \"c\",\n" +
       "  sourcesPaths: {\n" + sourceLines + "\n  },\n" +
@@ -1673,12 +1672,12 @@ Compiles **C89**, not C99/C11. Stick to:
       const incLine = runtimeHs.length > 0
         ? `\n  includePaths: {\n${runtimeHs.map((r) => `    "${r.dst}": "${r.dst}",`).join("\n")}\n  },`
         : "";
-      buildBlock = "```js\nrunSource({\n  platform: \"" + platform + "\",\n  language: \"c\",\n  sourcesPaths: {\n" + srcLines + "\n  }," + incLine + "\n  frames: 60,\n})\n```";
+      buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"" + platform + "\",\n  language: \"c\",\n  sourcesPaths: {\n" + srcLines + "\n  }," + incLine + "\n  frames: 240,\n})\n```";
     } else {
       const inc = runtimeAsmIncludes.length > 0
         ? `\n  includePaths: { ${runtimeAsmIncludes.map((r) => `"${r.dst}": "${r.dst}"`).join(", ")} },`
         : "";
-      buildBlock = "```js\nrunSource({\n  platform: \"" + platform + "\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 60,\n})\n```";
+      buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"" + platform + "\",\n  sourcePath: \"" + mainFilename + "\"," + inc + "\n  frames: 240,\n})\n```";
     }
   } else if (platform === "gba") {
     // GBA libtonc / libgba runtimes ship gba_sfx.{h,c} as a tiny DMG-APU
@@ -1693,12 +1692,12 @@ Compiles **C89**, not C99/C11. Stick to:
       const incLine = runtimeHs.length > 0
         ? `\n  includePaths: {\n${runtimeHs.map((r) => `    "${r.dst}": "${r.dst}",`).join("\n")}\n  },`
         : "";
-      buildBlock = "```js\nrunSource({\n  platform: \"gba\",\n  language: \"c\",\n  sourcesPaths: {\n" + srcLines + "\n  }," + incLine + "\n  frames: 60,\n})\n```";
+      buildBlock = "```js\nbuild({\n  output: \"run\",\n  platform: \"gba\",\n  language: \"c\",\n  sourcesPaths: {\n" + srcLines + "\n  }," + incLine + "\n  frames: 240,\n})\n```";
     } else {
-      buildBlock = "```js\nrunSource({ platform: \"gba\", language: \"c\", sourcePath: \"" + mainFilename + "\", frames: 60 })\n```";
+      buildBlock = "```js\nbuild({ output: \"run\", platform: \"gba\", language: \"c\", sourcePath: \"" + mainFilename + "\", frames: 240 })\n```";
     }
   } else {
-    buildBlock = "```js\nrunSource({ platform: \"" + platform + "\", sourcePath: \"" + mainFilename + "\", frames: 60 })\n```";
+    buildBlock = "```js\nbuild({ output: \"run\", platform: \"" + platform + "\", sourcePath: \"" + mainFilename + "\", frames: 240 })\n```";
   }
 
   let filesSection = `## Files\n\n- \`${mainFilename}\` — your game's entry point.\n`;
@@ -1715,7 +1714,7 @@ Compiles **C89**, not C99/C11. Stick to:
   }
   filesSection += `\nEvery byte that compiles into your ROM is in this directory. If you move the repo somewhere else, you don't need to install anything from romdev to rebuild it — the compiler binaries are the only external dependency.\n\n`;
 
-  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\n${buildBlock}\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Call \`runSource\` to see your changes. It builds + loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`readMemory\`, \`inspectSprites\`, \`inspectPalette\`, \`inspectBackgroundMap({render:true})\`.\n- Open a playtest window for human eyes: \`loadCategory({category:"show"}); playtest({});\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
+  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\n${buildBlock}\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Call \`build({output:"run", ...})\` to see your changes. It builds + loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`memory({op:"read"})\`, \`sprites({op:"inspect"})\`, \`palette({source:"live"})\`, \`background({view:"rendered"})\`.\n- Open a playtest window for human eyes: \`playtest({op:"open"})\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
   await fs.writeFile(path.join(projPath, "README.md"), readme, "utf-8");
   writtenFiles.push("README.md");
 
@@ -1784,7 +1783,7 @@ Compiles **C89**, not C99/C11. Stick to:
     snippetsCopied: withSnippets ? snippetFiles : null,
     sourceFile: path.join(projPath, mainFilename),
     toolchain: lang,
-    nextStep: `Edit ${path.join(projPath, mainFilename)} and call runSource with sourcesPaths/includePaths pointing at the project's files. Everything you need is in the directory — nothing is hidden.`,
+    nextStep: `Edit ${path.join(projPath, mainFilename)} and call build({output:"run", ...}) with sourcesPaths/includePaths pointing at the project's files (see the README's "Build + run" block for the exact call). Everything you need is in the directory — nothing is hidden.`,
   };
 }
 
@@ -1811,10 +1810,21 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
         ? CANONICAL_GENRES.filter((g) => platformTemplates[g])
         : [];
       if (availableGenres.length === 0) {
+        // Point at the real, working project templates each genre-less
+        // platform actually ships, so the agent has a concrete next step
+        // instead of a bare "default".
+        const PROJECT_TEMPLATE_HINTS = {
+          msx: "default, sprite_move, music_sfx, catch_game",
+          pce: "default, sprite_move, music_sfx, catch_game",
+          atari2600: "default, single_screen, paddle, mini_invaders, music_demo",
+        };
+        const hint = PROJECT_TEMPLATE_HINTS[platform];
         throw new Error(
           `createGame: no genre scaffolds for platform '${platform}' yet. ` +
           `Supported platforms: ${genrePlatforms.join(", ") || "(none)"}. ` +
-          `For other platforms, use createProject({platform, template:"default"}) and build up from there.`
+          (hint
+            ? `For ${platform}, use createProject({platform:"${platform}", template:"..."}) with one of: ${hint}.`
+            : `For other platforms, use createProject({platform, template:"default"}) and build up from there.`)
         );
       }
       if (!availableGenres.includes(genre)) {
@@ -1890,50 +1900,6 @@ export function registerProjectTools(server, z) {
     }),
   );
 
-  server.tool(
-    "patchGbHeader",
-    "Use this to write a complete, valid GB/GBC cartridge header into a ROM: Nintendo boot logo, EVERY " +
-    "header byte ($0134-$014C — title, CGB flag, cart type, ROM/RAM size, etc.) with ROM-only defaults, " +
-    "plus the header + global checksums. SDCC-path equivalent of `rgbfix -v -p 0`. Fills ALL bytes " +
-    "deliberately: leaving the CGB flag as the linker's $FF pad makes gambatte enter CGB mode and ignore " +
-    "DMG palette writes → white screen. Also shipped as `patch-header.js` in every GB/GBC project for use " +
-    "outside MCP.",
-    {
-      path: z.string().describe("Absolute path to the .gb / .gbc ROM file. Patched in place unless outputPath is given."),
-      outputPath: z.string().optional().describe("If given, write the patched ROM here instead of overwriting."),
-      cgb: z.boolean().optional().describe("If true, sets the CGB flag at $0143 to $80 (CGB-aware + DMG-compatible). If omitted, auto-detects from .gbc extension; default for plain .gb is false (DMG-only)."),
-      title: z.string().optional().describe("Cartridge title, up to 11 chars at $0134..$013E. Uppercased + zero-padded. Default = zero-fill."),
-      cartType: z.number().int().min(0).max(0xFF).optional().describe("Cart-type byte at $0147. Default $00 (ROM-only). Common alternatives: $01=MBC1, $03=MBC1+RAM+BAT, $11=MBC3, $13=MBC3+RAM+BAT, $19=MBC5."),
-      romSize: z.number().int().min(0).max(0xFF).optional().describe("ROM-size byte at $0148. Default $00 (32 KB / 2 banks). 1=64KB, 2=128KB, 3=256KB, 4=512KB, 5=1MB, 6=2MB, 7=4MB."),
-      ramSize: z.number().int().min(0).max(0xFF).optional().describe("RAM-size byte at $0149. Default $00 (none). $02=8KB, $03=32KB. Only meaningful with battery-backed MBC."),
-      destination: z.number().int().min(0).max(0xFF).optional().describe("Destination at $014A. Default $01 (non-Japan). $00 = Japan."),
-    },
-    safeTool(async ({ path: inPath, outputPath, cgb, title, cartType, romSize, ramSize, destination }) => {
-      const rom = new Uint8Array(await readFile(inPath));
-      const cgbFlag = cgb ?? (/\.gbc$/i.test(inPath) || (outputPath && /\.gbc$/i.test(outputPath)));
-      patchGbHeader(rom, { cgb: cgbFlag, title, cartType, romSize, ramSize, destination });
-      const outPath = outputPath ?? inPath;
-      await writeFile(outPath, rom);
-      return jsonContent({
-        path: outPath,
-        bytes: rom.length,
-        cgb: !!cgbFlag,
-        patched: [
-          "nintendo_logo@$0104..$0133",
-          "title@$0134..$013E",
-          `cgb_flag@$0143=${cgbFlag ? "$80" : "$00"}`,
-          "licensee@$0144..$0145=$00$00",
-          "sgb_flag@$0146=$00",
-          `cart_type@$0147=$${(cartType ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
-          `rom_size@$0148=$${(romSize ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
-          `ram_size@$0149=$${(ramSize ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
-          `destination@$014A=$${(destination ?? 1).toString(16).padStart(2, "0").toUpperCase()}`,
-          "old_licensee@$014B=$33",
-          "rom_version@$014C=$00",
-          "header_checksum@$014D",
-          "global_checksum@$014E..$014F",
-        ],
-      });
-    }),
-  );
+  // patchGbHeader was folded into romPatch({op:'gbHeader'}) (rom-id.js) — it's a
+  // ROM-file patch op, same family as romPatch's other ops, not a scaffold tool.
 }

package/src/mcp/tools/rom-id.js

@@ -30,6 +30,41 @@ export async function patchRomCore({ input, output, writes, allowExpand }) {
   return await patchRomFile({ input, output, writes, allowExpand });
 }
 
+// romPatch({op:'gbHeader'}) — write a complete valid GB/GBC cartridge header
+// (logo + every header byte + header/global checksums) into a ROM file. Folded
+// in from the old standalone patchGbHeader tool. Also shipped as patch-header.js
+// in every GB/GBC project for use outside romdev.
+export async function gbHeaderCore({ path: inPath, outputPath, cgb, title, cartType, romSize, ramSize, destination }) {
+  if (!inPath) throw new Error("romPatch({op:'gbHeader'}): `path` (the .gb/.gbc ROM) is required.");
+  const { readFile, writeFile } = await import("node:fs/promises");
+  const { patchGbHeader } = await import("../../platforms/gb/lib/c/patch-header.js");
+  const rom = new Uint8Array(await readFile(inPath));
+  const cgbFlag = cgb ?? (/\.gbc$/i.test(inPath) || (outputPath && /\.gbc$/i.test(outputPath)));
+  patchGbHeader(rom, { cgb: cgbFlag, title, cartType, romSize, ramSize, destination });
+  const outPath = outputPath ?? inPath;
+  await writeFile(outPath, rom);
+  return {
+    path: outPath,
+    bytes: rom.length,
+    cgb: !!cgbFlag,
+    patched: [
+      "nintendo_logo@$0104..$0133",
+      "title@$0134..$013E",
+      `cgb_flag@$0143=${cgbFlag ? "$80" : "$00"}`,
+      "licensee@$0144..$0145=$00$00",
+      "sgb_flag@$0146=$00",
+      `cart_type@$0147=$${(cartType ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
+      `rom_size@$0148=$${(romSize ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
+      `ram_size@$0149=$${(ramSize ?? 0).toString(16).padStart(2, "0").toUpperCase()}`,
+      `destination@$014A=$${(destination ?? 1).toString(16).padStart(2, "0").toUpperCase()}`,
+      "old_licensee@$014B=$33",
+      "rom_version@$014C=$00",
+      "header_checksum@$014D",
+      "global_checksum@$014E..$014F",
+    ],
+  };
+}
+
 export function registerRomIdTools(server, z, sessionKey) {
   // identifyRom folded into `cart`; patchFile/patchRom/spliceCHR/relocate/etc.
   // folded into the `romPatch` tool (router below).
@@ -48,7 +83,8 @@ export function registerRomIdTools(server, z, sessionKey) {
     "makeStored → {rawHex|rawBytes, format, interleave?}; " +
     "findFree → {minLength, fillBytes?, start?, end?, maxRunsReturned?}; " +
     "findPointer → {romOffset, mapper?, widths?, suppressShadows?, maxHitsReturned?}; " +
-    "diff → {a, b, maxChangesReturned?}.\n" +
+    "diff → {a, b, maxChangesReturned?}; " +
+    "gbHeader → {path, outputPath?, cgb?, title?, cartType?, romSize?, ramSize?, destination?}.\n" +
     "• op:'write' — write N bytes into any binary file at `offset` (the generic splicer: PRG patches, CHR splices, SNES tile/sample injection). `allowExpand` grows the file — default OFF; most hacks must NOT change size or headers/mapper break. `outputPath` else writes in place.\n" +
     "• op:'writeMany' — apply a LIST of {offset, hex|base64} `writes` from `input` ROM to `output`.\n" +
     "• op:'spliceCHR' — inject a PNG's tiles into a CHR region.\n" +
@@ -56,10 +92,11 @@ export function registerRomIdTools(server, z, sessionKey) {
     "• op:'makeStored' — wrap raw bytes so the game's OWN decompressor expands them VERBATIM (edit tiles → makeStored → write, no compressor needed). `format` (raw/lz77-literal/lz2-direct/sega-rle/konami-rle/packbits/kosinski-literal; invalid → returns the platform's list). ALWAYS verify via cpu({op:'call'}) on the game's decompressor.\n" +
     "• op:'findFree' — find a run of free space to relocate into (`fillBytes` defaults to [0xFF, 0x00]).\n" +
     "• op:'findPointer' — find every pointer in the ROM that references `romOffset` (platform-correct encoding), the missing piece for redirecting a loader. `mapper` overrides SNES detection. On wide systems (Genesis/GBA) a 32-bit hit's low bytes also match the narrower form one byte over — those tail SHADOWS are suppressed by default (count in `shadowsSuppressed`); pass `suppressShadows:false` for raw, or `widths:[4]` to search only 32-bit forms. On banked 8-bit systems a 16-bit pointer is page-ambiguous — correlate with the bank-set instruction.\n" +
-    "• op:'diff' — diff two ROMs (`a`, `b`) → the changed byte ranges.",
+    "• op:'diff' — diff two ROMs (`a`, `b`) → the changed byte ranges.\n" +
+    "• op:'gbHeader' — GAME BOY / GBC ONLY: write a complete, valid GB/GBC cartridge header into a ROM at `path` — Nintendo boot logo, every header byte ($0134-$014C: title, CGB flag, cart type, ROM/RAM size, …) with ROM-only defaults, plus the header + global checksums. The SDCC-path equivalent of `rgbfix -v -p 0`, for fixing up an externally built / hand-assembled GB ROM. (A normal build({output:'rom'/'run'}) already does this — you do NOT call gbHeader on a freshly built ROM.) Leaving the CGB flag as the linker's $FF pad makes gambatte enter CGB mode and white-screen, so this fills it deliberately.",
     {
-      op: z.enum(["write", "writeMany", "spliceCHR", "relocate", "makeStored", "findFree", "findPointer", "diff"])
-        .describe("write=N bytes at an offset; writeMany=a list of writes; spliceCHR=PNG tiles into CHR; relocate=write a block to free space + repoint; makeStored=wrap bytes for the game's decompressor; findFree=find free space; findPointer=find pointers to an offset; diff=diff two ROMs."),
+      op: z.enum(["write", "writeMany", "spliceCHR", "relocate", "makeStored", "findFree", "findPointer", "diff", "gbHeader"])
+        .describe("write=N bytes at an offset; writeMany=a list of writes; spliceCHR=PNG tiles into CHR; relocate=write a block to free space + repoint; makeStored=wrap bytes for the game's decompressor; findFree=find free space; findPointer=find pointers to an offset; diff=diff two ROMs; gbHeader=write a valid GB/GBC cartridge header + checksums."),
       path: z.string().optional().describe("op:write/spliceCHR/relocate/findFree/findPointer — absolute path to the ROM/file."),
       platform: z.enum(PLATFORMS).optional().describe("op:findPointer/relocate/makeStored/spliceCHR/diff — platform (inferred from extension except makeStored, which requires it)."),
       offset: z.number().int().min(0).optional().describe("op:write — file offset to write at (NOT a CPU address)."),
@@ -112,6 +149,13 @@ export function registerRomIdTools(server, z, sessionKey) {
       a: z.string().optional().describe("op:diff — path to ROM A."),
       b: z.string().optional().describe("op:diff — path to ROM B."),
       maxChangesReturned: z.number().int().min(1).max(2048).default(256).describe("op:diff — cap the change ranges returned."),
+      // gbHeader (path + outputPath reuse the spine fields above)
+      cgb: z.boolean().optional().describe("op:gbHeader — if true, sets the CGB flag at $0143 to $80 (CGB-aware + DMG-compatible). If omitted, auto-detects from a .gbc extension; default for plain .gb is false (DMG-only)."),
+      title: z.string().optional().describe("op:gbHeader — cartridge title, up to 11 chars at $0134..$013E. Uppercased + zero-padded. Default = zero-fill."),
+      cartType: z.number().int().min(0).max(0xFF).optional().describe("op:gbHeader — cart-type byte at $0147. Default $00 (ROM-only). Common: $01=MBC1, $03=MBC1+RAM+BAT, $11=MBC3, $13=MBC3+RAM+BAT, $19=MBC5."),
+      romSize: z.number().int().min(0).max(0xFF).optional().describe("op:gbHeader — ROM-size byte at $0148. Default $00 (32 KB / 2 banks). 1=64KB, 2=128KB, 3=256KB, 4=512KB, 5=1MB, 6=2MB, 7=4MB."),
+      ramSize: z.number().int().min(0).max(0xFF).optional().describe("op:gbHeader — RAM-size byte at $0149. Default $00 (none). $02=8KB, $03=32KB. Only meaningful with battery-backed MBC."),
+      destination: z.number().int().min(0).max(0xFF).optional().describe("op:gbHeader — destination at $014A. Default $01 (non-Japan). $00 = Japan."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -135,6 +179,7 @@ export function registerRomIdTools(server, z, sessionKey) {
           if (!args.a || !args.b) throw new Error("romPatch({op:'diff'}): `a` and `b` (the two ROM paths) are required.");
           return jsonContent(await diffRomsCore({ ...args, aPath: args.a, bPath: args.b }));
         }
+        case "gbHeader":    return jsonContent(await gbHeaderCore(args));
         default: throw new Error(`romPatch: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/tile-inspect.js

@@ -254,7 +254,7 @@ export function registerTileInspectTools(server, z, sessionKey) {
       tilePath: z.string().optional().describe("op:preview — path to a tile dump (raw) or iNES ROM (NES auto-locates CHR)."),
       fromEmulator: z.boolean().optional().describe("op:preview — read tiles from the running emulator's live VRAM (tileStart/tileCount pick the range). Genesis byte-swap handled. Mutually exclusive with tileBytes/tilePath."),
       tileStart: z.number().int().min(0).optional().describe("op:preview — starting tile index in the source."),
-      byteOffset: z.number().int().min(0).optional().describe("op:preview — start at a raw BYTE offset instead of a tile index (pass a dmaTrace / disasm-references source directly). WARNS on misalignment. Takes precedence over tileStart."),
+      byteOffset: z.number().int().min(0).optional().describe("op:preview — start at a raw BYTE offset instead of a tile index (pass a watch({on:'dma'}) / disasm-references source directly). WARNS on misalignment. Takes precedence over tileStart."),
       palette: z.array(z.any()).optional().describe("op:preview — explicit palette (NES: 4 master indices; others: RGB triples or indices)."),
       palettePath: z.string().optional().describe("op:preview — raw palette dump from disk."),
       // shared output