romdevtools 0.13.0 → 0.14.0

package/src/http/tool-registry.js

@@ -4,7 +4,7 @@
 // The MCP path registers 34 tools via registerTools(server, z, sessionKey),
 // where `server` is an McpServer and each handler closes over `sessionKey` for
 // per-session host isolation. The HTTP surfaces (POST /tool/{name},
-// /romdev-skill.md, /openapi.json, /documentation) want the EXACT same handlers,
+// /skills/romdev/SKILL.md, /openapi.json, /documentation) want the EXACT same handlers,
 // schemas, and clean-error behavior — just reached over plain HTTP.
 //
 // Rather than duplicate anything, we run the same registration against a minimal
@@ -17,6 +17,7 @@
 import { z } from "zod";
 import { registerTools } from "../mcp/tools/index.js";
 import { withClearToolErrors } from "../mcp/util.js";
+import { observer, summarizeForLog, extractImages } from "../observer/bus.js";
 
 /**
  * Build a tool registry for a given session key. Each entry's handler closes
@@ -86,8 +87,27 @@ export function buildToolRegistry(sessionKey) {
  * @param {object} args  the request body
  * @returns {Promise<{ok:true, result:any}|{ok:false, error:string}>}
  */
-export async function runTool(tool, args) {
+export async function runTool(tool, args, sessionKey) {
   const a = args ?? {};
+  const startedAt = Date.now();
+  // Emit the SAME `call` event the MCP path's observer middleware emits, so the
+  // /livestream view updates for HTTP/skill tool calls too (the MCP path wraps
+  // server.tool with installObserverMiddleware; the HTTP path runs handlers
+  // directly, so we emit here — the single HTTP execution chokepoint).
+  const emit = (extra) => {
+    try {
+      observer.push({
+        type: "call",
+        sessionKey: sessionKey ?? "http",
+        ts: startedAt,
+        tool: tool.name,
+        args: summarizeForLog(a),
+        durationMs: Date.now() - startedAt,
+        ...extra,
+      });
+    } catch { /* never let the observer kill a tool call */ }
+  };
+
   // Parse against the strict schema if we have a built zod object.
   const schema = tool.inputSchema;
   if (schema && typeof schema === "object" && "_def" in schema && typeof schema.safeParse === "function") {
@@ -96,6 +116,7 @@ export async function runTool(tool, args) {
       // surface the friendly first-issue message (withClearToolErrors / global map)
       const issue = parsed.error?.issues?.[0];
       const msg = (issue && issue.message) || "invalid arguments";
+      emit({ ok: false, error: msg });
       return { ok: false, error: msg };
     }
   }
@@ -104,22 +125,68 @@ export async function runTool(tool, args) {
     // Unwrap the MCP content envelope to plain JSON for HTTP clients.
     if (r && r.isError) {
       const text = r.content?.[0]?.text ?? "tool error";
+      emit({ ok: false, error: text });
       return { ok: false, error: text };
     }
+    const images = extractImages(r);
     const text = r?.content?.[0]?.text;
     if (typeof text === "string") {
       // most tools return jsonContent(...) → text is JSON; parse it back so the
       // HTTP response is real JSON, not a JSON-string-in-a-field.
-      try { return { ok: true, result: JSON.parse(text) }; }
-      catch { return { ok: true, result: { text } }; }
+      let parsed;
+      try { parsed = JSON.parse(text); } catch { parsed = { text }; }
+      // TRANSPORT-UNIFORM FAILURE MAPPING: a tool can signal failure either by
+      // throwing (→ isError above) OR by RETURNING a failure-shaped result
+      // ({ok:false} / {error} / {opened:false} / {applied:false} ...). On REST,
+      // a 200 with a failure in the body is invisible — the caller sees success
+      // and never reads the body. So we detect a failure-shaped result here and
+      // map it to ok:false (→ HTTP 400) for EVERY tool, no per-tool special-
+      // casing. (`notSupported`/`matched:false` are NOT failures — see below.)
+      if (looksLikeFailure(parsed)) {
+        const err = parsed.error ?? parsed.message ?? "tool reported failure";
+        emit({ ok: false, error: err });
+        return { ok: false, error: err, result: parsed };
+      }
+      emit({ ok: true, result: summarizeForLog(parsed), ...(images.length ? { images } : {}) });
+      return { ok: true, result: parsed };
     }
     // image / multi-part content: hand back the raw content array.
-    return { ok: true, result: r?.content ? { content: r.content } : (r ?? {}) };
+    const result = r?.content ? { content: r.content } : (r ?? {});
+    emit({ ok: true, result: summarizeForLog(result), ...(images.length ? { images } : {}) });
+    return { ok: true, result };
   } catch (e) {
+    emit({ ok: false, error: e?.message ?? String(e) });
     return { ok: false, error: e?.message ?? String(e) };
   }
 }
 
+// A RETURNED result is a FAILURE (→ non-2xx) when it carries an explicit failure
+// signal: a `false` on a verb-status flag, or a top-level `error` string. This is
+// the single rule that makes every tool behave the same on the transport — a tool
+// can fail by throwing or by returning one of these, and either way the caller
+// gets a non-2xx it can't ignore.
+//
+// NOT failures (these are valid ANSWERS / STATE, stay 2xx):
+//   • notSupported:true — the feature genuinely isn't on this platform/core
+//   • matched:false / found:false / hit:false — a lookup whose answer is "no"
+//   • looksLikeGraphic:false — a classification result
+//   • loaded:false / paused:false — STATE fields (is a ROM loaded? is it paused?),
+//     not "the action failed". This is why the flag list is DELIBERATELY narrow:
+//     only generic verdict flags + a couple of unambiguous action verbs. Anything
+//     else that wants to signal failure must do it with a top-level `error` string
+//     (or throw) — both of which are unambiguous.
+const FAILURE_FLAGS = ["ok", "success", "opened", "applied"];
+function looksLikeFailure(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+  // A top-level error string is unambiguous.
+  if (typeof parsed.error === "string" && parsed.error) return true;
+  // A generic verdict / unambiguous-action flag explicitly set to false.
+  for (const f of FAILURE_FLAGS) {
+    if (parsed[f] === false) return true;
+  }
+  return false;
+}
+
 /**
  * Convert a tool's stored inputSchema (a strict zod object, or a raw shape if
  * the stamp didn't take) to a JSON Schema (zod v4 native). Used by the OpenAPI

package/src/mcp/server.js

@@ -57,7 +57,7 @@ const PKG_VERSION = (() => {
 // AGENTS.md is the CHANNEL-NEUTRAL body (workflow knowledge, footguns, per-platform
 // docs) — it must not contain "how to connect / how to call" prose, because that
 // differs per delivery channel. The MCP channel prepends mcpPreamble ("call the
-// MCP tools…", never mentions HTTP routes); the skill channel (GET /romdev-skill.md)
+// MCP tools…", never mentions HTTP routes); the skill channel (GET /skills/romdev/SKILL.md)
 // prepends skillPreamble ("POST /tool/{name}…", never mentions MCP). Both live in
 // src/http/skill-doc.js so neither leaks into the other surface.
 async function loadAgentsBody() {
@@ -351,7 +351,7 @@ async function main() {
   });
 
   // ── HTTP tool surface (the non-MCP way to drive romdev) ───────────────────
-  // POST /tool/:name + /openapi.json + /documentation + /romdev-skill.md, all
+  // POST /tool/:name + /openapi.json + /documentation + /skills/romdev/SKILL.md, all
   // generated from the same tool registry the MCP path uses. Same Express app,
   // same localhost trust, per-agent dynamic sessions. Lets MCP-wary users (or
   // agents that prefer the Agent Skills standard) use romdev with near-zero
@@ -410,10 +410,11 @@ async function main() {
     process.exit(1);
   });
   httpServer.on("listening", () => {
-    log.info(`romdev listening on http://${bannerHost}:${port}/mcp`);
     log.info("");
-    log.info(`prefer a skill?  save:  http://${bannerHost}:${port}/romdev-skill.md`);
-    log.info(`browse/try the tools:   http://${bannerHost}:${port}/documentation`);
+    log.info(`romdev (v${PKG_VERSION}) listening on http://${bannerHost}:${port}/mcp`);
+    log.info("");
+    log.info(`prefer a skill?  save:  http://${bannerHost}:${port}/skills/romdev/SKILL.md`);
+    log.info("");
     log.info(`optional observer:      http://${bannerHost}:${port}/livestream`);
     log.info("");
     log.info("connect your coding agent: https://github.com/monteslu/romdev#connect");

package/src/mcp/state.js

@@ -23,12 +23,14 @@ export function getHost(sessionKey) {
   if (!host) {
     throw new Error(
       "No ROM loaded in this session — call loadMedia({path}) first. " +
-      "If you WERE mid-session and just got reconnected (the server restarted, " +
-      "or your session expired and your client re-initialized): the emulator " +
-      "state is held in server memory only, so it did not survive — just " +
-      "re-run loadMedia({path}) with the ROM you were working on (it's still on " +
-      "disk) to pick back up. Re-applying any in-progress changes means " +
-      "rebuilding/reloading; a fresh boot is the recovery point.",
+      "If you DID loadMedia and still see this, your calls are landing in DIFFERENT " +
+      "sessions: over plain HTTP/skill you must send the SAME `x-romdev-session` " +
+      "header on every call (pick one stable id and reuse it) — a new/missing id is " +
+      "a fresh empty session each time. " +
+      "If you WERE mid-session and just got reconnected (the server restarted or " +
+      "your session expired): emulator state is held in server memory only, so it " +
+      "did not survive — re-run loadMedia({path}) with your ROM (still on disk) to " +
+      "pick back up. A fresh boot is the recovery point.",
     );
   }
   return host;

package/src/mcp/tool-manifest.js

@@ -37,7 +37,7 @@ export const MERGE_MAP = {
   host: { absorbs: ["unloadMedia", "shutdown", "reset", "pause", "resume"], axis: "op" },
   // ── frame (step/screenshot/stepAndShot/stepInstruction; stepInstruction folded from watch-memory.js) ──
   frame: { absorbs: ["stepFrames", "screenshot", "stepAndScreenshot", "stepInstruction"], axis: "op" },
-  // ── scaffold (project/game + snippets; patchGbHeader stays standalone in project.js) ──
+  // ── scaffold (project/game + snippets; patchGbHeader folded into romPatch op:'gbHeader') ──
   scaffold: { absorbs: ["createProject", "createGame", "starterSnippets", "copyStarterSnippets"], axis: "op" },
   // ── cart (identify/extract/wrap; identifyRom from rom-id.js, rest from cart-parts.js) ──
   cart: { absorbs: ["identifyRom", "extractCart", "wrapRomFromParts"], axis: "op" },
@@ -61,14 +61,14 @@ export const MERGE_MAP = {
   cpu: { absorbs: ["getCPUState", "setRegister", "callSubroutine", "decompressWith"], axis: "op" },
   // ── breakpoint (STOP-on-first; all 4 from watch-memory.js) ──
   breakpoint: { absorbs: ["findWriter", "runUntilWrite", "runUntilPC", "runUntilRead"], axis: "on" },
-  // ── watch (LOG-ALL; all 3 from watch-memory.js) ──
-  watch: { absorbs: ["watchMemory", "watchRange", "logPCRange"], axis: "on" },
-  // ── dmaTrace (Genesis VDP-DMA; watchDma from watch-memory.js, traceVramSource from trace-vram-source.js) ──
-  dmaTrace: { absorbs: ["watchDma", "traceVramSource"], axis: "precision" },
+  // ── watch (LOG-ALL; watchMemory/watchRange/logPCRange + Genesis VDP-DMA trace
+  //    on:'dma' from watchDma/traceVramSource — all from watch-memory.js +
+  //    trace-vram-source.js. dmaTrace was folded in as watch({on:'dma'}).) ──
+  watch: { absorbs: ["watchMemory", "watchRange", "logPCRange", "watchDma", "traceVramSource"], axis: "on" },
   // ── build (compile/run; buildSource/buildProject/runSource from toolchain.js, buildSourceWithDebug from symbols.js). ENTRY-TIER. ──
   build: { absorbs: ["buildSource", "buildSourceWithDebug", "buildProject", "runSource"], axis: "output" },
-  // ── romPatch (8-op ROM-hack toolkit; patchFile/patchRom from rom-id.js, spliceCHR from splice-chr.js, relocateBlock/makeStoredBlock/findPointerTo from reinject.js, findFreeSpace from free-space.js, diffRoms from diff-roms.js) ──
-  romPatch: { absorbs: ["patchFile", "patchRom", "spliceCHR", "relocateBlock", "makeStoredBlock", "findFreeSpace", "findPointerTo", "diffRoms"], axis: "op" },
+  // ── romPatch (9-op ROM-hack toolkit; patchFile/patchRom from rom-id.js, spliceCHR from splice-chr.js, relocateBlock/makeStoredBlock/findPointerTo from reinject.js, findFreeSpace from free-space.js, diffRoms from diff-roms.js, patchGbHeader as op:'gbHeader') ──
+  romPatch: { absorbs: ["patchFile", "patchRom", "spliceCHR", "relocateBlock", "makeStoredBlock", "findFreeSpace", "findPointerTo", "diffRoms", "patchGbHeader"], axis: "op" },
   // ── catalog (orient; listCategories + getStatus, both entry-tier in index.js) ──
   catalog: { absorbs: ["listCategories", "getStatus"], axis: "op" },
   // ── playtest (show-a-human window FSM; all 4 from playtest.js). ENTRY-TIER. ──

package/src/mcp/tools/cheats.js

@@ -294,8 +294,9 @@ export function registerCheatTools(server, z, sessionKey) {
     "Cheat lookup / search / apply / create for the loaded ROM. `op`: " +
     "'lookup' (THIS game's known cheats from the bundled DB — returns labeled RAM addresses + Game Genie/ROM code " +
     "sites, so it answers 'which byte holds X?' for free); " +
-    "'search' (fuzzy-find a game by NAME when you don't have the exact No-Intro title — returns game names + cheat " +
-    "counts, then lookup the chosen one); " +
+    "'search' (fuzzy-find a game by NAME when you don't have the exact No-Intro title — searches ALL platforms by " +
+    "default and each match reports its own `platform`, so you don't need to know the console; pass `platform` only " +
+    "to scope it. Returns game names + cheat counts; then lookup the chosen one with its platform); " +
     "'apply' (enable a cheat on the LOADED game — pass a raw `code` or a `desc` from lookup); " +
     "'clear' (remove all active cheats); 'make' (CREATE a shareable code from an address+value). " +
     "TRUST: lookup matches by NAME/fuzzy similarity, NOT a verified CRC — a PROBABLE match. Labels are usually " +
@@ -322,7 +323,7 @@ export function registerCheatTools(server, z, sessionKey) {
       index: z.number().int().min(0).optional().describe("op=apply: cheat slot (default: next free slot). Reuse a slot to replace it."),
       enabled: z.boolean().default(true).describe("op=apply: false disables the slot instead of enabling."),
       // make / search / lookup share `platform`
-      platform: z.enum([...MAKE_CHEAT_PLATFORMS]).optional().describe("op=lookup: override platform detection. op=search/make: REQUIRED — the target platform (all 14 tier-1)."),
+      platform: z.enum([...MAKE_CHEAT_PLATFORMS]).optional().describe("op=lookup: override platform detection. op=search: OPTIONAL — omit to search ALL platforms (each match returns its own `platform`); pass one only to scope the search. op=make: REQUIRED — the target platform (all 14 tier-1)."),
       address: z.number().int().min(0).optional().describe("op=make: address to cheat (RAM addr, or the ROM addr to patch)."),
       value: z.number().int().min(0).max(255).optional().describe("op=make: replacement byte (0-255). Provide value OR values."),
       values: z.array(z.number().int().min(0).max(255)).min(1).max(64).optional().describe("op=make: batch — a code per value at the same address. Returns variants[]."),

package/src/mcp/tools/index.js

@@ -60,9 +60,22 @@ import { jsonContent, safeTool, withClearToolErrors } from "../util.js";
 import { getHostOrNull, setDisclosure } from "../state.js";
 import { MERGE_MAP } from "../tool-manifest.js";
 import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
+// Package version — surfaced by catalog({op:'status'|'whatsNew'}) so an agent can
+// check the running romdev version with a plain TOOL CALL (works over MCP AND the
+// HTTP/skill surface), e.g. to detect a saved skill is stale. (GET /healthz also
+// reports it for non-tool HTTP clients.)
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "package.json"), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
 // catalog({op:'whatsNew'}): the recent CHANGELOG + an old→new RENAME TABLE
 // derived from MERGE_MAP (the single source of truth for the consolidation), so
 // an agent resuming a handoff written against an older server can re-map every
@@ -91,6 +104,7 @@ async function buildWhatsNew() {
     changelog = sections.slice(0, 3).join("## ").trim();
   } catch { /* changelog not present in this install */ }
   return {
+    romdevVersion: PKG_VERSION,
     note: "Pre-1.0 the tool surface is consolidated freely with NO deprecated aliases. If a tool name from an older handoff is missing, it's almost certainly now an `op` (or other axis) on a domain tool — find it below, then read that tool's description for the exact op enum and params.",
     renameTable: renames,
     axisLegend: "Every domain tool is keyed by ONE axis: op (most), output (build), on (breakpoint), target (disasm), view (background), source (palette), stage (encodeArt), from (importArt). The value names the operation, e.g. romPatch({op:'findPointer'}).",
@@ -215,7 +229,7 @@ export function registerTools(server, z, sessionKey) {
     "• op:'whatsNew' — the recent CHANGELOG + an OLD→NEW tool RENAME TABLE. Call this FIRST if you're resuming work from a handoff written against an older server: pre-1.0 the surface is consolidated freely (no deprecated aliases), so a name you remember may now be an `op` on a domain tool. This maps them in one read instead of probing each tool.",
     {
       op: z.enum(["categories", "status", "whatsNew"]).default("categories")
-        .describe("categories=tool-category catalog; status=live session snapshot (host/platform/frameCount/media); whatsNew=recent CHANGELOG + old→new tool rename table."),
+        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale); whatsNew=recent CHANGELOG + old→new tool rename table."),
     },
     safeTool(async ({ op = "categories" }) => {
       if (op === "whatsNew") {
@@ -228,6 +242,7 @@ export function registerTools(server, z, sessionKey) {
           ? { ...host.getStatus() }
           : { loaded: false, hint: "no host yet; call loadMedia (in category 'run') to load a ROM" };
         return jsonContent({
+          romdevVersion: PKG_VERSION,
           ...base,
           loadedCategories: cats.filter((c) => c.loaded).map((c) => c.name),
           unloadedCategories: cats.filter((c) => !c.loaded).map((c) => c.name),
@@ -235,6 +250,7 @@ export function registerTools(server, z, sessionKey) {
       }
       const categories = disclosure.listCategories();
       return jsonContent({
+        romdevVersion: PKG_VERSION,
         categories,
         note: "Every tool registers at session init — this catalog is just a map grouped by purpose, NOT a gate. Call any tool by name directly.",
         humanInTheLoopHint: "Iterate INTERNALLY on screenshots first (build({output:'run'}) returns one inline; frame({op:'screenshot'/'stepAndShot'}) re-shoots the live host) — don't open a window to debug. Once the game actually boots and shows the feature you're working on, call playtest({}) so your human can watch and play it live. Opening a window on a black screen or a crash just wastes the human's attention — show them something that works.",
@@ -327,7 +343,7 @@ const TOOL_OWNER = {
   playtest: "show",
   // advanced category
   runUntil: "advanced",
-  watch: "advanced", breakpoint: "advanced", dmaTrace: "advanced",
+  watch: "advanced", breakpoint: "advanced",
   recordSession: "advanced",
   // entry tier itself
   catalog: "entry",

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

@@ -9,7 +9,6 @@
 // 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,
@@ -1583,9 +1582,9 @@ Compiles **C89**, not C99/C11. Stick to:
       "  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).";
+      "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(", ")} },`
@@ -1890,50 +1889,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