romdevtools 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.27.0
+
+### Added — `breakpoint(on:'pc', captureMemory:[…])` reads named RAM at the hit
+Completes item 2 of the NES Rygar report. 0.26.0 shipped `registersAtHit` (the
+break-instant register file) but not the memory half. Now `breakpoint(on:'pc')`
+takes `captureMemory:[{region,offset,length,label}]` and returns those reads inline
+as `capturedMemory`, so register + RAM inspection at a PC collapses into ONE call —
+no follow-up `cpu`/`memory` round trips. `registersAtHit` is the true break instant
+(core snapshot); `capturedMemory` reflects the routine's RAM side effects for the
+hit frame (stable + what RE needs), documented as such.
+
+## 0.26.0
+
+### Fixed — NES `breakpoint(on:'pc')` now returns reliable break-instant registers
+An agent RE'ing NES Rygar found that after a `pc` breakpoint hit, a follow-up
+`cpu({op:'read'})` returned the **idle-loop PC**, not the breakpoint instruction —
+the documented "break, then read the live register file" workflow gave end-of-frame
+state. Root cause: fceumm drains the cycle budget on hit but `retro_run` still
+finishes the frame, so the live X6502 registers are clobbered before the host reads
+them (the schema's "CPU is FROZEN at this instruction" was wrong for NES).
+- **fceumm core rebuild** (romdev-core-fceumm 0.8.0): the PC-break handler now
+  SNAPSHOTS A/X/Y/P/S at the hit instant, exposed via `romdev_pcbreak_get`.
+- **`breakpoint(on:'pc')` returns `registersAtHit`** — the reliable break-instant
+  register file. The schema + hit note now steer to it and explicitly warn that a
+  live `cpu({op:'read'})` after a hit is end-of-frame state on fceumm. (The
+  `captureMemory` companion that reads named RAM inline at the hit landed in 0.27.0.)
+- **NES `cpu({op:'read'})` core-internal fields relabeled** (item 3): `DB`,
+  `IRQlow`, `tcount`, `count` are fceumm internals (data-bus latch / IRQ bitmask /
+  cycle counters), not 6502 registers — moved out of `registers` into a labeled
+  `coreInternal` object so they're not misread as CPU state.
+
+### Added — `/livestream` shows the SYSTEM (platform) on every tool call + frame
+A human watching `/livestream` on a multi-agent server saw the session id + tool
+name, but not WHICH console each call/frame belonged to. Every observer event now
+carries `platform` (the session host's loaded system — nes, genesis, …), surfaced
+as a badge on the log row and the frame card. Wired on BOTH transports (the MCP
+observer middleware and the REST tool registry), resolved AFTER the handler runs so
+a `loadMedia` / `build({output:'run'})` that sets the platform mid-call labels its
+own frame correctly. Null until a ROM is loaded.
+
 ## 0.25.0
 
 ### Added — C64 input scripting + verification (RE startup-flow telemetry)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -51,7 +51,7 @@
     "omggif": "^1.0.10",
     "pngjs": "^7.0.0",
     "romdev-core-bluemsx": "0.4.0",
-    "romdev-core-fceumm": "0.7.0",
+    "romdev-core-fceumm": "0.8.0",
     "romdev-core-gambatte": "0.7.0",
     "romdev-core-geargrafx": "0.5.0",
     "romdev-core-gpgx": "0.10.0",

package/src/host/LibretroHost.js

@@ -1184,11 +1184,14 @@ export class LibretroHost {
   }
 
   // ── PC breakpoint + read watchpoint + single-step (core-side, exact) ────────
-  // Symmetric to the write watchpoint. The PC breakpoint freezes the CPU at the
-  // target instruction mid-frame (the core's execute loop bails on hit); the
-  // read watchpoint records the PC that READ an address. Both require a core
-  // patched with the romdev_pcbreak_*/romdev_readwatch_* exports (Genesis today;
-  // other cores as they're patched). Capability is feature-detected per core.
+  // Symmetric to the write watchpoint. On PC hit the core's execute loop drains
+  // the cycle budget and bails, but retro_run still finishes the frame — so the
+  // LIVE register file is end-of-frame state by the time the host reads it. Cores
+  // that snapshot the registers AT the hit (NES/fceumm: getPCBreak().registersAtHit)
+  // give the reliable break-instant regs; others expose only lastPC + the RAM side
+  // effects. The read watchpoint records the PC that READ an address. All require a
+  // core patched with the romdev_pcbreak_*/romdev_readwatch_* exports. Capability
+  // (and reg-snapshot availability) is feature-detected per core.
 
   /** True when this core build exposes the PC breakpoint + single-step. */
   pcBreakSupported() {
@@ -1219,13 +1222,22 @@ export class LibretroHost {
     if (typeof mod._romdev_pcbreak_get !== "function") {
       throw new Error("this core build does not expose the PC breakpoint.");
     }
-    const ptr = mod._malloc(24); // up to 6 × uint32 (older cores write 5)
+    const ptr = mod._malloc(44); // up to 11 × uint32 (newer fceumm writes 11: +A/X/Y/P/S snapshot)
     try {
-      // Pre-seed slot 5 (watchdog) so a 5-element older core leaves it 0.
-      new Uint32Array(mod.HEAPU8.buffer, ptr, 6).fill(0);
+      // Pre-seed all 11 slots. The reg-snapshot slots (6-10) default to
+      // 0xFFFFFFFF = "no snapshot" so a core that only writes 6 (Genesis et al.)
+      // leaves them as "unavailable" rather than 0 (a valid register value).
+      const seed = new Uint32Array(mod.HEAPU8.buffer, ptr, 11);
+      seed.fill(0); seed[6] = seed[7] = seed[8] = seed[9] = seed[10] = 0xFFFFFFFF;
       mod._romdev_pcbreak_get(ptr, clearHit ? 1 : 0);
-      const u = new Uint32Array(mod.HEAPU8.buffer, ptr, 6);
+      const u = new Uint32Array(mod.HEAPU8.buffer, ptr, 11);
       const lastPC = u[3];
+      // Register snapshot at the hit instant (fceumm). 0xFFFFFFFF = not captured
+      // (older core, or no hit yet). When present, these are the RELIABLE
+      // break-instant regs — the live X6502 regs are clobbered by end-of-frame.
+      const snap = (u[6] === 0xFFFFFFFF && u[7] === 0xFFFFFFFF)
+        ? null
+        : { A: u[6] & 0xFF, X: u[7] & 0xFF, Y: u[8] & 0xFF, P: u[9] & 0xFF, S: u[10] & 0xFF };
       return {
         enabled: !!u[0],
         address: u[1],
@@ -1233,6 +1245,7 @@ export class LibretroHost {
         lastPC: lastPC === 0xFFFFFFFF ? null : lastPC,
         hits: u[4],
         watchdog: !!u[5], // the run was force-stopped by the instruction watchdog
+        registersAtHit: snap,
       };
     } finally {
       mod._free(ptr);

package/src/host/cpu-state.js

@@ -157,7 +157,18 @@ function decode6502(bytes) {
   // 6502 P flags: N V - B D I Z C  (bit 5 unused / always reads 1)
   return formatCpuState({
     pc: PC,
-    registers: { A, X, Y, S, P, DB, IRQlow, tcount, count },
+    // Only the architectural 6502 registers go in `registers`. fceumm also
+    // exposes core-internal latches/counters (data-bus latch, pending-IRQ
+    // bitmask, cycle counters) — those are NOT 6502 state and were easy to
+    // misread, so they live under `coreInternal`, clearly labeled.
+    registers: { A, X, Y, S, P },
+    coreInternal: {
+      DB,       // data-bus latch (last value on the bus) — emulator-internal
+      IRQlow,   // pending-IRQ source bitmask — emulator-internal
+      tcount,   // temporary cycle counter — emulator-internal
+      count,    // cycles remaining in the current slice — emulator-internal
+      note: "fceumm core-internal values, NOT architectural 6502 registers — don't read these as CPU state.",
+    },
     flags: {
       N: !!(P & 0x80),
       V: !!(P & 0x40),

package/src/http/tool-registry.js

@@ -18,6 +18,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";
+import { getHostOrNull } from "../mcp/state.js";
 
 /**
  * Build a tool registry for a given session key. Each entry's handler closes
@@ -94,11 +95,17 @@ export async function runTool(tool, args, sessionKey) {
   // /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).
+  // Which console this session's host currently has loaded — shown on every
+  // livestream event so a human watching a multi-agent server sees the SYSTEM
+  // (nes, genesis, …) alongside the tool, not just the session id. Best-effort.
+  let platform = null;
+  try { platform = getHostOrNull(sessionKey)?.status?.platform ?? null; } catch { /* none yet */ }
   const emit = (extra) => {
     try {
       observer.push({
         type: "call",
         sessionKey: sessionKey ?? "http",
+        platform,
         ts: startedAt,
         tool: tool.name,
         args: summarizeForLog(a),
@@ -122,6 +129,10 @@ export async function runTool(tool, args, sessionKey) {
   }
   try {
     const r = await tool.handler(a, {});
+    // Re-resolve the platform AFTER the handler: a call like loadMedia /
+    // build({output:'run'}) sets it during the call, so the post-call value
+    // correctly labels this call's event + frame (the pre-call value was null).
+    try { platform = getHostOrNull(sessionKey)?.status?.platform ?? platform; } catch { /* keep */ }
     // Unwrap the MCP content envelope to plain JSON for HTTP clients.
     if (r && r.isError) {
       const text = r.content?.[0]?.text ?? "tool error";
@@ -148,7 +159,11 @@ export async function runTool(tool, args, sessionKey) {
       setImmediate(() => {
         try {
           const img = frameProvider();
-          if (img) observer.push({ type: "call_frame", sessionKey: sessionKey ?? "http", ts: startedAt, tool: tool.name, images: [img] });
+          // re-resolve platform: a call like loadMedia sets it DURING the call, so
+          // the post-call value is the most accurate for the frame's system label.
+          let framePlatform = platform;
+          try { framePlatform = getHostOrNull(sessionKey)?.status?.platform ?? platform; } catch { /* keep */ }
+          if (img) observer.push({ type: "call_frame", sessionKey: sessionKey ?? "http", platform: framePlatform, ts: startedAt, tool: tool.name, images: [img] });
         } catch { /* livestream is best-effort; never affects the caller */ }
       });
     }

package/src/mcp/tools/record.js

@@ -34,7 +34,7 @@ export function registerRecordTools(server, z, sessionKey) {
   server.tool(
     "recordSession",
     "Run the loaded ROM for N frames, sampling screenshots and/or memory every sampleEvery frames. Returns a timeline the agent can analyze. Inputs are either held for the whole session (holdInputs) or scripted as {atFrame, ports} entries each held until the next (inputScript). " +
-    "Screenshots (includeScreenshots, default true): pass outputDir to write frame-<n>.png per sample (timeline gets screenshotPath), OR inline:true to embed screenshotBase64 per entry — one is required. Set includeScreenshots:false for memory-only runs. " +
+    "Screenshots (includeScreenshots, default true): every sampled frame ALWAYS streams to the human's /livestream (over REST or MCP, no flag needed). For the AGENT's response: pass outputDir to also write frame-<n>.png per sample (timeline gets screenshotPath), or inline:true to embed screenshotBase64 per entry (opt-in — NOT default, so image bytes don't flood your context). With neither, frames still go to /livestream and the response stays compact (just the timeline). Set includeScreenshots:false to skip capture entirely (memory-only runs). " +
     "Memory (memorySamples): accepts the full readMemory region set incl. hardware registers (nes_apu_regs, etc.); hex appears per-sample in the timeline. For dense sampling (sampleEvery:1 over a long loop, e.g. APU regs across a music loop) add memoryOutputPath to stream rows to NDJSON on disk and keep the hex OUT of context — the response returns a compact summary {path, rows, regions, valueRanges} instead.",
     {
       frames: z.number().int().min(1).max(36000).default(300).describe("Total frames to run."),
@@ -62,18 +62,22 @@ export function registerRecordTools(server, z, sessionKey) {
         .optional()
         .describe("Memory regions to sample at each capture point. Accepts the full readMemory region set (incl. nes_apu_regs and other hardware registers). Tip: sampleEvery:1 + memoryOutputPath gives a per-frame telemetry stream (e.g. APU registers over a music loop) without flooding context with hex."),
       includeScreenshots: z.boolean().default(true).describe("If false, skip PNG capture (just memory samples)."),
-      outputDir: z.string().optional().describe("Directory to write per-sample PNGs (frame-<n>.png). Required when includeScreenshots is true unless inline:true."),
-      inline: z.boolean().default(false).describe("If true, embed screenshotBase64 in each timeline entry instead of writing PNGs to disk. Default false — then outputDir is required when includeScreenshots is true."),
+      outputDir: z.string().optional().describe("OPTIONAL. If set, also write per-sample PNGs (frame-<n>.png) to this dir; the timeline gets each one's `screenshotPath`. Captured frames stream to /livestream regardless; outputDir just additionally persists them to disk for the agent."),
+      inline: z.boolean().default(false).describe("OPT-IN base64. If true, embed screenshotBase64 in each timeline entry. Default false — frames go to /livestream + (if outputDir) disk, but image BYTES are NOT put in your response context unless you ask. Only set this if you genuinely need the base64 inline."),
       memoryOutputPath: z.string().optional().describe("If set, write per-sample memory to this path as newline-delimited JSON (one row per sample) and OMIT the bulky per-sample `memory` from the timeline — returns a compact summary {path, rows, regions, valueRanges} instead. Use for dense sampling (sampleEvery:1 over a long loop) so ~200KB of hex never enters context."),
     },
-    safeTool(async ({ frames, sampleEvery, holdInputs, inputScript, memorySamples, includeScreenshots, outputDir, inline, memoryOutputPath }) => {
+    safeTool(async ({ frames, sampleEvery, holdInputs, inputScript, memorySamples, includeScreenshots = true, outputDir, inline = false, memoryOutputPath }) => {
       const host = getHost(sessionKey);
-      if (includeScreenshots && !inline && !outputDir) {
-        throw new Error("recordSession: includeScreenshots is true — pass outputDir (writes frame-<n>.png per sample, returns screenshotPath) or inline:true (embeds screenshotBase64 in each entry). Or set includeScreenshots:false for memory-only sampling.");
-      }
-      if (includeScreenshots && !inline && outputDir) {
+      // No outputDir/inline requirement anymore: captured frames ALWAYS stream to
+      // the human's /livestream (observer sideband). outputDir additionally writes
+      // PNGs to disk; inline additionally embeds base64 in the RESPONSE (opt-in, so
+      // we never flood agent context by default). Bare call = frames go to the
+      // human, nothing bulky comes back to the agent.
+      if (includeScreenshots && outputDir) {
         await mkdir(outputDir, { recursive: true });
       }
+      // Frames pushed to the /livestream observer this run (every captured sample).
+      const observerFrames = [];
       // Sort input script by frame.
       const script = (inputScript ?? []).slice().sort((a, b) => a.atFrame - b.atFrame);
       let scriptIdx = 0;
@@ -120,13 +124,22 @@ export function registerRecordTools(server, z, sessionKey) {
           try {
             const shot = host.screenshot();
             sample.framebuffer = { width: shot.width, height: shot.height };
-            if (inline) {
-              sample.screenshotBase64 = shot.pngBase64;
-            } else {
+            // ALWAYS push the frame to the human's /livestream (observer sideband),
+            // independent of how the AGENT wants it returned and independent of the
+            // transport (REST or MCP — both consume _observerImages). The human
+            // watching does not depend on the agent passing inline/outputDir.
+            observerFrames.push({ kind: "image", mimeType: "image/png", base64: shot.pngBase64 });
+            // The agent's RESPONSE: a path if outputDir was given, else nothing.
+            // Base64 goes into the response ONLY when explicitly inline:true — we do
+            // NOT dump image bytes into context by default.
+            if (outputDir) {
               const framePath = path.join(outputDir, `frame-${sample.frame}.png`);
               await writeFile(framePath, Buffer.from(shot.pngBase64, "base64"));
               sample.screenshotPath = framePath;
             }
+            if (inline) {
+              sample.screenshotBase64 = shot.pngBase64;
+            }
           } catch (e) {
             sample.screenshotError = String(e?.message ?? e);
           }
@@ -156,10 +169,19 @@ export function registerRecordTools(server, z, sessionKey) {
         timeline.push(sample);
       }
 
+      // Attach the captured frames as a /livestream observer sideband (top-level
+      // sibling of `content`, NOT inside the JSON text — same pattern as frame.js,
+      // so the observer middleware forwards them and they never bloat the response
+      // text). The wrapper (MCP + REST both) strips _observerImages before reply.
+      const withObserver = (result) => {
+        if (observerFrames.length) Object.assign(result, { _observerImages: observerFrames });
+        return result;
+      };
+
       if (streamMemory) {
         await mkdir(path.dirname(memoryOutputPath), { recursive: true });
         await writeFile(memoryOutputPath, memRows.map((r) => JSON.stringify(r)).join("\n") + "\n");
-        return jsonContent({
+        return withObserver(jsonContent({
           framesRun: elapsed,
           samples: timeline.length,
           // Timeline retains screenshot paths + framebuffer dims but NOT the
@@ -173,14 +195,14 @@ export function registerRecordTools(server, z, sessionKey) {
             valueRanges,
             note: "Per-sample memory written to disk (one JSON object per row: {frame, elapsed, <label>:hex,...}). valueRanges shows each label's first-byte min/max so you can tell at a glance which watched bytes actually changed.",
           },
-        });
+        }));
       }
 
-      return jsonContent({
+      return withObserver(jsonContent({
         framesRun: elapsed,
         samples: timeline.length,
         timeline,
-      });
+      }));
     }),
   );
 }

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

@@ -633,7 +633,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       });
   }
 
-  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring }) {
+  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring, captureMemory }) {
       const host = getHost(sessionKey);
       if (!host.pcBreakSupported || !host.pcBreakSupported()) {
         return jsonContent({
@@ -666,19 +666,54 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
             "to reach the right game state), or the address isn't an instruction boundary (a mid-instruction address never matches REG_PC).",
         }), host);
       }
+      // Snapshot the registers AT the hit BEFORE clearing (last already holds the
+      // hit state; read it without clearing so registersAtHit survives).
+      const atHit = last.registersAtHit ?? host.getPCBreak(false).registersAtHit ?? null;
+      // captureMemory: read the requested regions AT the hit (before we clear/step),
+      // returned inline so break→read RAM collapses into ONE call. NOTE: registers
+      // are the true break instant (core snapshot); these RAM reads are taken now —
+      // i.e. after the hit frame finished — so on run-to-frame-end cores (fceumm)
+      // they reflect the routine's RAM SIDE EFFECTS for that frame (which is what
+      // RE wants: "what did this routine touch"), not necessarily the exact byte
+      // mid-instruction. Stable + reliable; that's the property the report leaned on.
+      let capturedMemory = null;
+      if (Array.isArray(captureMemory) && captureMemory.length) {
+        capturedMemory = {};
+        for (const m of captureMemory) {
+          const label = m.label ?? `${m.region}+${m.offset}`;
+          try {
+            const bytes = host.readMemory(m.region, m.offset, m.length ?? 1);
+            capturedMemory[label] = {
+              region: m.region, offset: m.offset, length: m.length ?? 1,
+              hex: Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""),
+            };
+          } catch (e) {
+            capturedMemory[label] = { region: m.region, offset: m.offset, error: String(e?.message ?? e) };
+          }
+        }
+      }
       const fin = host.getPCBreak(true); // clear hit
+      // registersAtHit (NES/fceumm and any core that snapshots regs on hit) is the
+      // RELIABLE break-instant register file. The LIVE register file (a follow-up
+      // cpu({op:'read'})) is NOT reliable on fceumm: the core drains the cycle
+      // budget on hit but retro_run still finishes the frame, so the live regs are
+      // end-of-frame state. Prefer registersAtHit; only fall back to a live read on
+      // cores that don't snapshot.
+      const frozenNote = atHit
+        ? "registersAtHit holds the register file CAPTURED AT this instruction (A/X/Y/P/S) — use THESE, not a follow-up cpu({op:'read'}), which on NES/fceumm returns end-of-frame state, not the break instant. For RAM at the hit, pass captureMemory:[{region,offset,length}] to get it inline (capturedMemory) in THIS call instead of a follow-up read. frame({op:'stepInstruction'}) to single-step from here."
+        : "This core does not snapshot registers at the hit. cpu({op:'read'}) reflects the CPU state now; on cores that run-to-frame-end (fceumm) that is NOT the break instant — prefer the RAM side effects (memory({op:'read'})) over the live register file.";
       return attachObserverFrame(jsonContent({
         hit: true,
         address: "$" + address.toString(16).toUpperCase(),
         pc: last.lastPC != null ? "$" + last.lastPC.toString(16).toUpperCase() : null,
         pcRaw: last.lastPC,
+        ...(atHit ? { registersAtHit: atHit } : {}),
+        ...(capturedMemory ? { capturedMemory } : {}),
         frame: host.status.frameCount,
         framesRun,
         hits: fin.hits,
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
-        note: "CPU is FROZEN at this instruction. Call cpu({op:'read'}) to read all registers at this exact " +
-          "moment (the value you want — e.g. an address register holding a source pointer — is live now), then memory({op:'read'/'readCart'}) " +
-          "at that pointer. frame({op:'stepInstruction'}) to single-step, or frame({op:'step'})/host({op:'resume'}) to continue.",
+        note: frozenNote,
       }), host);
   }
 
@@ -741,14 +776,16 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "interrupted main-thread PC (an idle loop), a LIE. Use 'exact' when you need the real writer.**\n" +
     "• on:'read' — break when the CPU READS `address` (the read-side mirror of on:'write' exact): the EXACT instruction PC that " +
     "read the byte. Finds who CONSUMES a value. Does NOT freeze mid-frame — records the PC and finishes the frame.\n" +
-    "• on:'pc' — break when the PC reaches `address`, freezing the CPU EXACTLY at that instruction (a real execution breakpoint). " +
-    "**The RE primitive for 'read the register at this instruction': break, then cpu({op:'read'}) the live register file** " +
-    "(e.g. break at a decoder's `move.b (a0),d0` and read A0 = the source address). After a hit the CPU stays FROZEN mid-frame — " +
-    "inspect, then frame({op:'step'/'stepInstruction'}) to continue. (on:'read'/'write' finish the frame; on:'pc' freezes.)\n" +
-    "All supported on every CPU core; out-of-date core packages return notSupported.",
+    "• on:'pc' — break when the PC reaches `address` (a real execution breakpoint). " +
+    "**The RE primitive for 'read the register at this instruction': break, then use the `registersAtHit` SNAPSHOT in the hit response** " +
+    "(e.g. break at a decoder's load and read the index reg = the source offset). IMPORTANT: `registersAtHit` is the register file captured AT the break instant — " +
+    "use it, NOT a follow-up cpu({op:'read'}). On some cores (notably NES/fceumm) the core drains the cycle budget on hit but the frame still finishes, " +
+    "so a live cpu read afterward returns END-OF-FRAME registers, not the break instant. `registersAtHit` sidesteps that. The break PC is reported as `pc`/`pcRaw`; " +
+    "the RAM side effects are also reliable via memory({op:'read'}). frame({op:'stepInstruction'}) to single-step from the break. (on:'read'/'write' finish the frame.)\n" +
+    "All supported on every CPU core; `registersAtHit` is present on cores that snapshot regs (NES today); out-of-date core packages return notSupported.",
     {
       on: z.enum(["write", "read", "pc"])
-        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address (freezes mid-instruction)."),
+        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant A/X/Y/P/S on NES) + the break PC; use registersAtHit, not a follow-up cpu read (which is end-of-frame state on fceumm)."),
       precision: z.enum(["exact", "sampled"]).default("exact")
         .describe("on:'write' ONLY. exact=core watchpoint, the real writing instruction PC even under interrupts (uses `address`). sampled=cheap frame-boundary PC (uses region/offset/length) — NOT the writer under IRQ. Ignored for on:read/pc (always exact)."),
       address: z.number().int().min(0).optional().describe("on:'write' exact / on:'read' / on:'pc' — CPU address to break on (write target, read target, or instruction boundary). Required for those."),
@@ -767,6 +804,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         offset: z.number().int().min(0).describe("byte offset within the region"),
         label: z.string().optional().describe("human name for this guard byte"),
       })).optional().describe("on:'write' exact — ABORT GUARD for a pressDuring run: caller-named 'is this scenario still valid?' bytes (e.g. the area/scene id, the player object-active flag). If ANY changes mid-run the watchpoint stops IMMEDIATELY and returns {aborted:true, abortedBy, before, after} — so a driven scenario that derailed (player died → title screen) doesn't burn all maxFrames and return a meaningless found:false. Each is sampled once per frame (cheap)."),
+      captureMemory: z.array(z.object({
+        region: z.enum(MEMORY_REGIONS).describe("memory region to read"),
+        offset: z.number().int().min(0).describe("byte offset within the region"),
+        length: z.number().int().min(1).max(256).default(1).describe("bytes to read"),
+        label: z.string().optional().describe("human name for this read (else 'region+offset')"),
+      })).optional().describe("on:'pc' — read these memory regions AT the hit and return them inline as `capturedMemory` (collapses break→read-RAM into ONE call, the token win). Pair with `registersAtHit` to get the routine's register + RAM state in a single round trip (e.g. capture the ZP pointer bytes a decoder just wrote). NOTE: registersAtHit is the true break instant (core snapshot); these RAM reads are taken after the hit frame finishes, so on run-to-frame-end cores (fceumm) they're the routine's RAM side effects for that frame — stable + reliable, which is exactly what RE needs."),
     },
     safeTool(async (args) => {
       switch (args.on) {

package/src/observer/livestream.html

@@ -148,6 +148,7 @@
     font-size: 11px; color: #888;
   }
   .log-row .ts { color: #666; }
+  .log-row .plat { color: #0d1117; background: #80cbc4; font-weight: 600; border-radius: 3px; padding: 0 5px; text-transform: uppercase; font-size: 10px; letter-spacing: .3px; }
   .log-row .tool { color: #ffeb3b; font-weight: 600; }
   .log-row .dur { color: #999; margin-left: auto; }
   .log-row .summary {
@@ -304,7 +305,7 @@
           // One latest image per "tool" (kind = tool name); ev.tool
           // identifies which inspect call produced it.
           s.latestByKind[ev.tool] = { ts: ev.ts, base64: img.base64,
-                                      mimeType: img.mimeType, tool: ev.tool };
+                                      mimeType: img.mimeType, tool: ev.tool, platform: ev.platform ?? null };
         }
       }
       // screenshotAscii pushes both the PNG (above) AND the raw ANSI
@@ -414,7 +415,8 @@
       const card = document.createElement("div");
       card.className = "image-card";
       const dt = new Date(img.ts).toLocaleTimeString();
-      card.innerHTML = `<div class="meta"><span>${img.tool}</span><span>${dt}</span></div>`;
+      const platBadge = img.platform ? `<span class="plat">${escapeHtml(img.platform)}</span> ` : "";
+      card.innerHTML = `<div class="meta"><span>${platBadge}${escapeHtml(img.tool)}</span><span>${dt}</span></div>`;
       const el = document.createElement("img");
       el.src = `data:${img.mimeType};base64,${img.base64}`;
       el.alt = img.tool;
@@ -563,6 +565,7 @@
     const head = document.createElement("div");
     head.className = "head";
     head.innerHTML = `<span class="ts">${dt}</span>`
+      + (ev.platform ? `<span class="plat">${escapeHtml(ev.platform)}</span>` : "")
       + `<span class="tool">${escapeHtml(ev.tool)}</span>`
       + `<span class="dur">${ev.durationMs}ms</span>`;
     row.appendChild(head);

package/src/observer/tool-wrap.js

@@ -6,9 +6,18 @@
 // Idempotent per server instance — installs once, repeats are no-ops.
 
 import { observer, extractImages, summarizeForLog } from "./bus.js";
+import { getHostOrNull } from "../mcp/state.js";
 
 const INSTALLED = Symbol.for("romdev.observer-installed");
 
+// The platform/system the session's host currently has loaded (nes, genesis, …),
+// or null if no ROM is loaded yet. Surfaced on every livestream event so a human
+// watching a multi-agent server sees WHICH console each tool call / frame belongs
+// to, not just the session id + tool name. Best-effort: never throws.
+function sessionPlatform(sessionKey) {
+  try { return getHostOrNull(sessionKey)?.status?.platform ?? null; } catch { return null; }
+}
+
 /**
  * Install tool-call instrumentation on an MCP server.
  *
@@ -42,12 +51,14 @@ export function installObserverMiddleware(server, sessionKey) {
       // log isn't dominated by base64 / huge source strings, but keep
       // top-level property names intact.
       const argsSummary = summarizeForLog(args);
+      const platform = sessionPlatform(sessionKey); // which console this call drives
       let event;
       let frameProvider = null; // deferred framebuffer thunk (encoded async below)
       if (thrown) {
         event = {
           type: "call",
           sessionKey,
+          platform,
           ts: startedAt,
           tool: name,
           args: argsSummary,
@@ -93,6 +104,7 @@ export function installObserverMiddleware(server, sessionKey) {
         event = {
           type: "call",
           sessionKey,
+          platform,
           ts: startedAt,
           tool: name,
           args: argsSummary,
@@ -119,7 +131,7 @@ export function installObserverMiddleware(server, sessionKey) {
           try {
             const img = frameProvider();
             if (img) {
-              observer.push({ type: "call_frame", sessionKey, ts: startedAt, tool: name, images: [img] });
+              observer.push({ type: "call_frame", sessionKey, platform, ts: startedAt, tool: name, images: [img] });
             }
           } catch { /* livestream is best-effort; never affects the agent */ }
         });