romdevtools 0.24.0 → 0.26.0

package/AGENTS.md

@@ -148,10 +148,12 @@ worry about ground truth:
 
 1. **`scaffold({op:'project', platform, template, name, path})`** — drops a
    complete, self-contained project tree on disk (main.c + the
-   runtime files it needs + your `vendor/` library source for
-   reference + README + .gitignore). Build with `build({output:'run'})` against
-   the project's files; the bundled examples ARE the reference
-   implementation.
+   runtime files it needs + the vendored library source for
+   reference + README + .gitignore). The response lists only the files you EDIT
+   (`files`) + a `vendorFileCount`; pass `verbose:true` for the full manifest.
+   Build the whole dir in one call with `build({output:'project', path,
+   outputPath})` (toolchain/crt0/linker inferred — no manifest); the bundled
+   examples ARE the reference implementation.
 2. **`scaffold({op:'game', platform, genre})`** — same but picks a known-good
    genre scaffold (shmup / platformer / puzzle / sports / racing).
 3. **`scaffold({op:'snippets', platform, mode})`** (mode `list`/`get`/`getAll`)

package/CHANGELOG.md

@@ -4,6 +4,109 @@ 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.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. (Item 1+2
+  of the report, collapsed: the snapshot is taken in the same call that detects the
+  hit, so there's no freeze-durability race and no extra round trip.)
+- **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)
+Follow-up to the 0.24.0 C64 keyboard work: an agent RE'ing C64 Uridium could now
+press keys, but couldn't (a) script a keyboard+joystick startup TIMELINE in one
+call, or (b) tell whether a non-responsive key reached VICE at all. Both added — no
+core rebuild (the `c64_cia1_regs` region + key matrix already existed):
+- **`recordSession` `inputScript[].keys`** — hold C64 keyboard keys from a frame
+  until the next entry, interleaved with joystick `ports`, in one deterministic
+  timeline (e.g. `{atFrame:0,keys:['f1']},{atFrame:30,ports:[{b:true}]},
+  {atFrame:60,keys:['run/stop']},{atFrame:90,keys:[]}`). `ports` is now optional
+  (a step may set just keys). Unknown keys are **rejected with a clear error**, not
+  silently ignored.
+- **`input({op:'pressKey', verify:true})`** — also samples CIA1 **`$DC00`/`$DC01`**
+  (the keyboard/joystick scan ports the KERNAL reads) **before / during (key held)
+  / after**, plus matrix coords + active joyport. Lets you distinguish "my key
+  never reached VICE" (`before==during`) from "VICE saw it but the game ignored it"
+  (they differ, no reaction) when a C64 game doesn't respond.
+
+### Changed — `scaffold` no longer echoes the vendored toolchain manifest
+`scaffold({op:'project'|'game'})` used to return a flat `files[]` of EVERY written
+file — including the toolchain copies (35 of 44 entries on NES, **173 of 264 on
+GBA**, ~270 on SGDK Genesis) that an agent never touches. Across a matrix run (one
+game × every genre × every platform) that was ~100 KB of pure vendored-path lists
+in context with zero decision value. Now the response is a compact receipt:
+- `files` — only the project-**OWNED** files you edit (main source, runtime, crt0,
+  cfg, README).
+- `fileCount` (total written) + `vendorFileCount` (the summarized vendored copies,
+  on disk if you ever need them).
+- `verbose:true` restores the full flat list as `allFiles`.
+
+"Owned" is classified by what a file **is**, not just a `vendor/` prefix — so it
+correctly excludes the SDK header trees the GBA (libtonc `include/`+`sysinclude/`)
+and Genesis (SGDK `include/`) toolchains drop OUTSIDE `vendor/`, plus prebuilt
+`crt*.o` / `*.a` / `*.lib`. (The initial fix used a `vendor/`-prefix denylist and
+missed exactly those two SDK platforms — caught + fixed via a 0.24.0 matrix-run
+report. GBA dropped 173→9 owned, Genesis 82→13.) Mirrors the `inline`/`outputPath`
+choose-your-payload pattern the snippets op already had.
+
+### Changed — scaffold README + `nextStep` lead with `build({output:'project'})`
+The generated project README and the scaffold's `nextStep` now lead with the
+one-call **`build({output:'project', platform, path, outputPath})`** form (infers
+toolchain/crt0/linker from the directory — no `sourcesPaths`/`includePaths`/
+`linkerConfig` to hand-specify), and demote the verbose `output:'run'` + manifest
+form to a collapsed "compiling edited loose source" alternative. The project-dir
+build was already the easier path; now it's the one a fresh agent copies first.
+
+### Fixed — SMS shmup + Atari 7800 sports scaffolds rendered with wrong colors
+Both built and booted but looked broken (a 0.24.0 matrix report flagged them):
+- **SMS shmup** rendered the starfield as blue/**GREEN** striped bands. The BG
+  palette had colour 1 = `0x08`, which in SMS 2-2-2 BGR is green (G bits), not the
+  "deep space blue" the comment claimed. Fixed to a pure-blue depth gradient
+  (`0x10/0x20/0x30`) — the bands now read as space, dominant colour went green
+  `#00aa00` → blue `#0000ad`.
+- **Atari 7800 sports** rendered a near-black playfield that looked dead. Two MARIA
+  colour-byte bugs: the court walls used `0x48` (hue 4 = RED → **pink**, not the
+  intended blue) and the court floor was `0x00` (black, indistinguishable from a
+  blank screen). Fixed to blue walls (`0x8A`, hue 8) + a dark-green court floor
+  (`0xB4`) — now reads as an actual court (dominant black → green `#008221`).
+
+Both verified by screenshot + `frame({op:'verify'})`. (These were colour-value
+bugs in the scaffold templates, not the render pipeline.)
+
+### Removed — `catalog({op:'whatsNew'})` + the old→new tool rename table
+`whatsNew` returned a 125-entry map of pre-1.0 renamed tool names (plus, until now,
+~1.4k tokens of inlined CHANGELOG prose) so an agent resuming an old handoff could
+re-map a tool that had moved. The pre-1.0 consolidation is long settled — the old
+names are git history, and no running agent carries them — so maintaining a
+forever-growing rename record (and risking it landing in context) wasn't worth it.
+Dropped the op, the `tool-manifest.js` map, and its tests. An agent that hits an
+unknown tool name now just reads the current surface (`catalog({op:'categories'})`
+or the tool list); full release notes remain in CHANGELOG.md for humans.
+
 ## 0.24.0
 
 ### Added — C64 keyboard + joyport input (VICE core patch)

package/examples/atari7800/templates/sports.c

@@ -180,11 +180,15 @@ void main(void) {
   p1y = 110; p2y = 110;
   serve_ball(0);
 
-  BACKGRND = 0x00;   /* black court */
+  /* MARIA color byte = (hue<<4)|lum. Court = dark green so the play area
+   * reads as an actual field (0x00 black looked like a blank/dead screen);
+   * walls = blue. NB: 0x48 is hue 4 = RED-magenta (renders PINK), not blue —
+   * blue is hue 8/9, so the walls use 0x8A. */
+  BACKGRND = 0xB4;   /* dark green court floor (hue 11) */
   P0C1     = 0x0F;   /* white paddles + ball */
   P0C2     = 0x0F;
   P0C3     = 0x0F;
-  P1C1     = 0x48;   /* court walls (blue) */
+  P1C1     = 0x8A;   /* court walls — BLUE (hue 8); was 0x48 = pink */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/sms/templates/shmup.c

@@ -30,8 +30,11 @@ extern void sms_sat_upload(void);
 #define T_ENEMY  2
 
 static const uint8_t palette[32] = {
-  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white */
-  0x10,0x08,0x20,0x3F, 0x00,0x00,0x00,0x00,
+  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white.
+   * SMS CRAM is 2-2-2 BGR (bits --BB GGRR), so PURE blue uses only the B bits:
+   * 0x10=dark, 0x20=medium, 0x30=bright. (The old 0x08 for colour 1 was G=2 =
+   * GREEN, which made the alternating starfield bands render blue/GREEN striped.) */
+  0x10,0x20,0x30,0x3F, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   /* Sprite palette: white, yellow, red */
   0x00,0x3F,0x0F,0x03, 0x00,0x00,0x00,0x00,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.24.0",
+  "version": "0.26.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

@@ -928,6 +928,86 @@ export class LibretroHost {
     return { key: String(key).toLowerCase(), row, col, frames: Math.max(1, frames | 0) };
   }
 
+  /**
+   * Press a C64 key like pressC64Key, but sample the machine-visible input
+   * state (CIA1 $DC00/$DC01 — the keyboard/joystick scan ports) BEFORE,
+   * DURING (key held), and AFTER (released). Lets an RE agent tell apart
+   * "my key never reached VICE" from "VICE saw it but the game didn't scan
+   * it this frame". No core change — reads the already-exposed c64_cia1_regs
+   * region ($DC00..$DC0F).
+   * @param {string} key
+   * @param {number} frames  frames to hold (sampled at the midpoint)
+   * @returns {object} matrix coords + held flag + per-phase CIA snapshots
+   */
+  pressC64KeyVerify(key, frames = 4) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const pos = C64_KEY_MATRIX[String(key).toLowerCase()];
+    if (!pos) {
+      throw new Error(`unknown C64 key '${key}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`);
+    }
+    const [row, col] = pos;
+    const held = Math.max(1, frames | 0);
+    // $DC00 = CIA1 PRA (port A — joystick 2 + keyboard col select),
+    // $DC01 = CIA1 PRB (port B — joystick 1 + keyboard row read).
+    const cia = () => {
+      try {
+        const r = this.readMemory("c64_cia1_regs", 0, 2);
+        return { DC00: r[0], DC01: r[1] };
+      } catch { return null; }
+    };
+    const before = cia();
+    mod._romdev_key_matrix(row, col, 1);          // press
+    this.stepFrames(Math.ceil(held / 2));
+    const during = cia();                          // key still held
+    this.stepFrames(Math.max(1, held - Math.ceil(held / 2)));
+    mod._romdev_key_matrix(row, col, 0);          // release
+    this.stepFrames(1);
+    const after = cia();
+    return {
+      key: String(key).toLowerCase(),
+      row, col,
+      frames: held,
+      joyport: this.getC64JoyPort?.() ?? null,
+      autoReleased: true,
+      cia1: { before, during, after },
+      note: "CIA1 $DC00 (port A) / $DC01 (port B) are the keyboard/joystick scan ports the KERNAL reads. `during` is sampled with the key held; if before==during the key never moved the matrix line (didn't reach VICE); if they differ but the game didn't react, it scanned a different key/port or that screen ignores it.",
+    };
+  }
+
+  /**
+   * Set the SET of C64 keyboard keys held down (for scripted timelines like
+   * recordSession). Diffs against the currently-held set: presses newly-added
+   * keys' matrix lines, releases removed ones. Pass [] to release all. Does NOT
+   * step frames — the caller's loop owns stepping. Unknown keys throw.
+   * @param {string[]} keys
+   * @returns {{held: string[], matrix: Array<[number,number]>}}
+   */
+  setC64HeldKeys(keys) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const want = new Set((keys ?? []).map((k) => String(k).toLowerCase()));
+    for (const k of want) {
+      if (!C64_KEY_MATRIX[k]) {
+        throw new Error(`unknown C64 key '${k}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`);
+      }
+    }
+    const have = this._c64HeldKeys ?? (this._c64HeldKeys = new Set());
+    // release keys no longer wanted
+    for (const k of have) {
+      if (!want.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 0); have.delete(k); }
+    }
+    // press newly-added keys
+    for (const k of want) {
+      if (!have.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 1); have.add(k); }
+    }
+    return { held: [...have], matrix: [...have].map((k) => C64_KEY_MATRIX[k]) };
+  }
+
   /**
    * Feed a PETSCII string into the C64 kernal keyboard buffer (for typing
    * LOAD/RUN/filenames). `\r` (or `\n`) becomes RETURN. Non-blocking — the
@@ -1104,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() {
@@ -1139,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],
@@ -1153,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/index.js

@@ -58,13 +58,11 @@ import { registerCheatTools } from "./cheats.js";
 import { createDisclosure } from "../disclosure.js";
 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
+// Package version — surfaced by catalog({op:'status'}) 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.)
@@ -76,42 +74,6 @@ const PKG_VERSION = (() => {
   }
 })();
 
-// 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
-// renamed tool in ONE read. Pre-1.0 the surface is consolidated freely with NO
-// deprecated aliases (see the consolidation), which is exactly why this exists.
-async function buildWhatsNew() {
-  // old name → "newTool({axis:'oldOpName'})". The op value is best-effort: most
-  // absorbed tools become an op whose name is a shortened form, so we surface the
-  // axis + the new tool and let the tool's own description give the exact op enum.
-  const renames = {};
-  for (const [newTool, entry] of Object.entries(MERGE_MAP)) {
-    if (entry.unchanged) continue;
-    for (const old of entry.absorbs ?? []) {
-      renames[old] = { nowOn: newTool, axis: entry.axis };
-    }
-  }
-  // Recent CHANGELOG entries (top of the file = newest). Best-effort: if the file
-  // isn't packaged in some install, return the rename table alone.
-  let changelog = null;
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    // src/mcp/tools/ → package root is three up.
-    const text = await readFile(join(here, "..", "..", "..", "CHANGELOG.md"), "utf8");
-    // Keep the two most recent version sections.
-    const sections = text.split(/^## /m);
-    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'}).",
-    ...(changelog ? { changelog } : { changelogNote: "CHANGELOG.md not bundled in this install." }),
-  };
-}
-
 /**
  * Categories for progressive disclosure. Each entry's `register` is the
  * existing per-module registration function — we don't rewrite the
@@ -225,16 +187,12 @@ export function registerTools(server, z, sessionKey) {
     "catalog",
     "Orient yourself, keyed by `op`.\n" +
     "• op:'categories' (default) — the catalog of tool categories, each {name, description, useWhen[], loaded}. This server registers EVERY tool at session start, so this is just a map grouped by purpose for orientation, NOT a gate — you do NOT need to load anything before calling a tool.\n" +
-    "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.\n" +
-    "• 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:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.",
     {
-      op: z.enum(["categories", "status", "whatsNew"]).default("categories")
-        .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."),
+      op: z.enum(["categories", "status"]).default("categories")
+        .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)."),
     },
     safeTool(async ({ op = "categories" }) => {
-      if (op === "whatsNew") {
-        return jsonContent(await buildWhatsNew());
-      }
       if (op === "status") {
         const host = getHostOrNull(sessionKey);
         const cats = disclosure.listCategories();

package/src/mcp/tools/input.js

@@ -228,6 +228,7 @@ export function registerInputTools(server, z, sessionKey) {
       key: z.string().optional().describe("op=pressKey (C64): key name — f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, ctrl, cbm, home, down, right, lshift, rshift."),
       text: z.string().optional().describe("op=typeText (C64): string fed into the keyboard buffer; \\r / \\n become RETURN. e.g. 'LOAD\"*\",8,1\\rRUN\\r'."),
       joyport: z.number().int().min(1).max(2).optional().describe("op=joyport (C64): set the active joystick port (1 or 2). Omit to just GET the current port. Default is 2 (most C64 games)."),
+      verify: z.boolean().default(false).describe("op=pressKey (C64): also sample CIA1 $DC00/$DC01 (the keyboard/joystick scan ports the KERNAL reads) BEFORE / DURING (key held) / AFTER, plus matrix coords + active joyport. Use to tell apart 'my key never reached VICE' (before==during) from 'VICE saw it but the game ignored it' (they differ but no reaction) when a C64 game doesn't respond to a key."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -256,6 +257,10 @@ export function registerInputTools(server, z, sessionKey) {
         case "pressKey": {
           if (!args.key) throw new Error("input({op:'pressKey'}): `key` is required (C64 keyboard key, e.g. 'f1', 'return', 'run/stop').");
           const host = getHost(sessionKey);
+          if (args.verify) {
+            const v = host.pressC64KeyVerify(args.key, args.frames ?? 4);
+            return jsonContent({ pressedKey: v.key, matrix: [v.row, v.col], frames: v.frames, joyport: v.joyport, autoReleased: v.autoReleased, cia1: v.cia1, frameCount: host.status.frameCount, note: v.note });
+          }
           const r = host.pressC64Key(args.key, args.frames ?? 4);
           return jsonContent({ pressedKey: r.key, matrix: [r.row, r.col], frames: r.frames, frameCount: host.status.frameCount });
         }

package/src/mcp/tools/project.js

@@ -1422,7 +1422,7 @@ async function copyDirRecursive(fs, path, srcDir, dstDir, writtenFiles, dstPrefi
  *   handler returns: {path, platform, template, files, sourceFile,
  *   toolchain, nextStep}.
  */
-export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false }) {
+export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false, verbose = false }) {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");
   const { fileURLToPath } = await import("node:url");
@@ -1768,7 +1768,12 @@ 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 \`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`;
+  // Lead with the project-dir build — ONE call, no manifest. The verbose
+  // output:'run' + sourcesPaths form (buildBlock) is the "editing loose
+  // source" variant, shown second.
+  const projectBuildBlock =
+    "```js\nbuild({\n  output: \"project\",\n  platform: \"" + platform + "\",\n  path: \"" + projPath + "\",\n  outputPath: \"" + name + romExt + "\",\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\nThe whole project directory builds in ONE call — romdev infers the toolchain, crt0, and linker from the directory, so you don't pass a file manifest:\n\n${projectBuildBlock}\n\nAdd \`output:"run"\` instead of \`"project"\` to also load + run + screenshot in the same round trip. Re-run the exact same call after every edit.\n\n<details>\n<summary>Alternative: build from a hand-specified source manifest (when compiling edited loose source, not a project dir)</summary>\n\n${buildBlock}\n</details>\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Re-run the \`build({output:"project"|"run", path})\` call above to see your changes — it builds + (for run) 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");
 
@@ -1828,19 +1833,46 @@ Compiles **C89**, not C99/C11. Stick to:
     }
   }
 
+  // Split the manifest: project-OWNED files (main.c, runtime helpers, crt0,
+  // cfg, README…) are the only ones an agent touches; the rest are internal
+  // toolchain copies on disk that never enter a decision. Echoing all of
+  // them — 35/44 on NES (vendor/cc65/libsrc/*), 173/264 on GBA (libtonc
+  // include/+sysinclude/), ~270 on SGDK Genesis — was pure context noise
+  // across a matrix run. Default to a compact receipt (owned list + a
+  // not-owned COUNT); `verbose:true` restores the full flat list.
+  //
+  // Classify NON-owned by what it actually is, NOT just a `vendor/` prefix:
+  // the cc65 path lands under vendor/, but the GBA/Genesis SDKs drop their
+  // header trees at include/ + sysinclude/ (no vendor/ prefix) and prebuilt
+  // crt objects/archives at the root — none of which an agent edits. (R: the
+  // original `!startsWith('vendor/')` denylist missed exactly these two SDK
+  // platforms — same bug class as the original fix, second location.)
+  const isVendored = (f) =>
+    f.startsWith("vendor/") ||                    // cc65 libsrc, pvsneslib, sgdk src
+    f.startsWith("include/") ||                   // SDK header trees (libtonc/libgba/SGDK/maxmod)
+    f.startsWith("sysinclude/") ||                // libgba/libtonc system headers
+    /^crt[a-z0-9]*\.o$/i.test(f) ||               // prebuilt crt objects (crti/crtn/crtbegin/crtend)
+    /\.(a|lib)$/i.test(f);                         // prebuilt static archives
+  const ownedFiles = writtenFiles.filter((f) => !isVendored(f));
+  const vendorFileCount = writtenFiles.length - ownedFiles.length;
   return {
     path: projPath,
     platform,
     template: hasTemplates ? (template ?? "default") : null,
-    files: writtenFiles,
+    // The files you actually edit. Vendored toolchain copies are summarized,
+    // not listed — they're on disk under vendor/ if you ever need them.
+    files: ownedFiles,
+    fileCount: writtenFiles.length,
+    vendorFileCount,
+    ...(verbose ? { allFiles: writtenFiles } : {}),
     snippetsCopied: withSnippets ? snippetFiles : null,
     sourceFile: path.join(projPath, mainFilename),
     toolchain: lang,
-    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.`,
+    nextStep: `Build the scaffold AS-IS in one call: build({output:"project", platform:"${platform}", path:"${projPath}", outputPath:"<game>.<ext>"}) — it infers the toolchain/crt0/linker from the directory, no sourcesPaths/includePaths/linkerConfig needed. Then edit ${mainFilename} and re-run the same call. (build({output:"run", ...}) with a hand-specified sourcesPaths manifest is the alternative when you're compiling edited loose source instead of a project dir.)`,
   };
 }
 
-async function createGameCore({ platform, genre, name, path: projPath, title, overwrite }) {
+async function createGameCore({ platform, genre, name, path: projPath, title, overwrite, verbose = false }) {
       // The five canonical genres. A genre is available on a platform iff
       // TEMPLATES[platform] has a matching template entry — we DERIVE
       // availability from TEMPLATES rather than maintain a parallel table,
@@ -1887,7 +1919,7 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
       // Genre id IS the template id (they're 1:1 by construction).
       const templateId = genre;
       const result = await createProjectImpl({
-        platform, template: templateId, name, path: projPath, title, overwrite,
+        platform, template: templateId, name, path: projPath, title, overwrite, verbose,
       });
       return { ...result, genre, template: templateId };
 }
@@ -1917,6 +1949,7 @@ export function registerProjectTools(server, z) {
       // project
       template: z.string().optional().describe("op=project: template id ('default' | 'hello_sprite' | 'tile_engine' on NES/GB/GBC; 'default' elsewhere)."),
       withSnippets: z.boolean().default(false).describe("op=project: also drop every vetted snippet alongside main (= scaffold copySnippets after)."),
+      verbose: z.boolean().default(false).describe("op=project/game: echo the FULL flat file manifest (incl. vendor/** toolchain copies) as `allFiles`. Default false — the response lists only project-OWNED files you edit (`files`) plus a `vendorFileCount`, since the vendored toolchain copies are on disk and never need echoing (they're 35 of 44 entries on NES, ~270 on SGDK Genesis). Set true only if you specifically need every path in the response."),
       // game
       genre: z.string().optional().describe("op=game: 'shmup' | 'platformer' | 'puzzle' | 'sports' | 'racing'."),
       // snippets

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."),
@@ -44,11 +44,12 @@ export function registerRecordTools(server, z, sessionKey) {
         .array(
           z.object({
             atFrame: z.number().int().min(0),
-            ports: z.array(inputShape).max(2),
+            ports: z.array(inputShape).max(2).optional(),
+            keys: z.array(z.string()).optional().describe("C64-ONLY: C64 keyboard keys held from this frame until the next entry (f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, …). [] releases all held keys. Unknown keys are rejected with a clear error. Lets you script a keyboard+joystick startup timeline (e.g. {atFrame:0,keys:['f1']},{atFrame:30,ports:[{b:true}]},{atFrame:90,keys:['run/stop']}) in one call."),
           }),
         )
         .optional()
-        .describe("Per-frame input changes. Each entry sets the input at `atFrame` and holds it until the next entry."),
+        .describe("Per-frame input changes. Each entry sets the input at `atFrame` (joystick `ports` and/or C64 `keys`) and holds it until the next entry. Either field is optional — a step may set just keys, just ports, or both."),
       memorySamples: z
         .array(
           z.object({
@@ -61,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;
@@ -99,7 +104,12 @@ export function registerRecordTools(server, z, sessionKey) {
       while (elapsed < frames) {
         // Apply any scripted inputs whose atFrame ≤ current frame.
         while (scriptIdx < script.length && script[scriptIdx].atFrame <= elapsed) {
-          host.setInput({ ports: script[scriptIdx].ports });
+          const entry = script[scriptIdx];
+          if (entry.ports) host.setInput({ ports: entry.ports });
+          // C64 keyboard keys held from this entry until the next. Pass [] to
+          // release all. Only valid on a C64/VICE host (setC64HeldKeys throws
+          // otherwise — surfaced as a clear error, not a silent no-op).
+          if (entry.keys !== undefined) host.setC64HeldKeys(entry.keys);
           scriptIdx++;
         }
         const batch = Math.min(sampleEvery, frames - elapsed);
@@ -114,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);
           }
@@ -150,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
@@ -167,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

@@ -666,19 +666,30 @@ 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;
       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 a source pointer in a 16-bit reg pair, read the two ZP bytes via memory({op:'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 } : {}),
         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 +752,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."),

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 */ }
         });

package/src/platforms/c64/MENTAL_MODEL.md

@@ -134,6 +134,26 @@ key:
 A typical C64 RE startup: load → step to the title → `pressKey f1` (1 player) →
 `set {b:true}` (fire to start) → step → you're in gameplay → `state({op:'save'})`.
 
+**Script the whole startup in one call.** `recordSession`'s `inputScript` takes
+C64 `keys` alongside joystick `ports` — held from each entry until the next — so a
+key+joystick startup is one deterministic timeline instead of many calls:
+```js
+recordSession({ frames:600, sampleEvery:60, outputDir:'…', inputScript:[
+  { atFrame:0,  keys:['f1'] },        // 1 player
+  { atFrame:30, ports:[{ b:true }] }, // fire (port 2)
+  { atFrame:90, keys:['run/stop'] },  // start
+  { atFrame:120, keys:[] } ] })       // release
+```
+A step may set just `keys`, just `ports`, or both; `keys:[]` releases all. An
+unknown key is rejected with a clear error (not a silent no-op).
+
+**When a key seems ignored, probe it.** `input({op:'pressKey', key:'run/stop',
+verify:true})` returns the matrix coords, active joyport, and a CIA1 snapshot
+(`$DC00`/`$DC01`) **before / during (held) / after**. `before==during` ⇒ the key
+never moved the matrix line (didn't reach VICE); they differ but the game didn't
+react ⇒ it scanned a different key/port, or that screen (crack/doc/trainer)
+ignores it. This is how you tell a romdev problem from a game-flow problem.
+
 **Controller-alone (playtest):** a human in `playtest` needs no keyboard — the
 pad's spare buttons map to the C64 keys (X=Space, L2=Run/Stop, R2=Return,
 right-stick=F1/F3/F5/F7, top face=F1; d-pad+Fire=joystick). The same mapping

package/src/mcp/tool-manifest.js

@@ -1,92 +0,0 @@
-// Tool manifest — the SINGLE SOURCE OF TRUTH for the consolidated tool surface.
-//
-// The 132→34 consolidation (see internal CONSOLIDATION_PLAN) merges narrow tools
-// into domain tools with a typed operation axis. This manifest records, for each
-// consolidated tool, the OLD tools it absorbs and the axis it routes on — so:
-//   1. a coverage-gate test can assert every old tool name maps to exactly one
-//      new tool (no capability silently dropped, no dupe);
-//   2. a tool-count budget test can fail the build if the surface regrows;
-//   3. docs + the rename map for downstream agents derive from one place.
-//
-// GOVERNANCE: a new capability is a new PARAMETER/op-value on an existing tool by
-// default — NOT a new top-level tool. Adding an entry here is a deliberate act the
-// budget test surfaces at PR time.
-//
-// Each MERGE_MAP entry: newTool → { absorbs:[...oldNames], axis:'op'|'as'|... }.
-// `absorbs: []` + `unchanged:true` means the tool kept its name (no merge).
-// This map grows one domain at a time as each consolidated tool lands.
-
-export const MERGE_MAP = {
-  // ── files (generic disk I/O) ──
-  files: { absorbs: ["writeAsset", "readAsset", "listAssets"], axis: "op" },
-  // ── cheats (DB lookup/search + apply/clear + make) ──
-  cheats: { absorbs: ["gameCheats", "searchCheats", "applyCheat", "clearCheats", "makeCheat"], axis: "op" },
-  // ── text (custom-font learn/encode/find for romhacking) ──
-  text: { absorbs: ["learnFontMap", "encodeTextForRom", "findEncodedText"], axis: "op" },
-  // ── symbols (name↔addr, memory map, PC→symbol). buildSourceWithDebug stays for `build`. ──
-  symbols: { absorbs: ["resolveSymbol", "lookupAddress", "getMemoryMap", "listSymbols", "addressToSymbol"], axis: "op" },
-  // ── disasm (raw bytes / ROM / project / references) ──
-  disasm: { absorbs: ["disassemble", "disassembleRom", "disassembleProject", "findReferences"], axis: "target" },
-  // ── state (save/load/list/export/dump/diff; diffState moved here from memory.js) ──
-  state: { absorbs: ["saveState", "loadState", "listStates", "exportState", "dumpState", "diffState"], axis: "op" },
-  // ── input (set/press/sequence/navigate/layout; getInputLayout folded in) ──
-  input: { absorbs: ["setInput", "pressButton", "inputSequence", "navigate", "getInputLayout"], axis: "op" },
-  // ── platform (list/resolve/toolchains/docs/doc; spans platforms.js+platform-docs.js+toolchain.js) ──
-  platform: { absorbs: ["listPlatforms", "resolvePlatform", "listToolchains", "installToolchain", "listPlatformDocs", "getPlatformDoc"], axis: "op" },
-  // ── host (unload/shutdown/reset/pause/resume FSM; loadMedia + getStatus stay separate) ──
-  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 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" },
-  // ── palette (live/platformMaster/lospec; spans platform-tools.js + lospec.js) ──
-  palette: { absorbs: ["inspectPalette", "getPlatformPalettePng", "getLospecPalette"], axis: "source" },
-  // ── audioDebug (inspect/record; getAudioState from platform-tools.js, recordAudio from audio.js; pcmToBrr/wavToXgm2Pcm stay) ──
-  audioDebug: { absorbs: ["getAudioState", "recordAudio"], axis: "op" },
-  // ── sprites (inspect OAM + meta-sprite pipeline; inspectSprites from platform-tools.js, rest from metasprite-tools.js; validateGenesisTiles stays for encodeArt) ──
-  sprites: { absorbs: ["inspectSprites", "groupVisibleSprites", "previewVisibleSprites", "captureMetaSprite", "renderMetaSpritePreview", "emitMetaSpriteRenderer", "extractSpriteFromScreenshot"], axis: "op" },
-  // ── background (tilemap/render-state; inspectBackgroundMap from platform-tools.js, getRenderingContext from rendering-context.js, whichTilesAreRendered from which-tiles.js) ──
-  background: { absorbs: ["inspectBackgroundMap", "getRenderingContext", "whichTilesAreRendered"], axis: "view" },
-  // ── tiles (decode/render tile bytes; inspectPatternTiles from platform-tools.js, getTile/tileFingerprints/tilesAscii from tile-inspect.js, extractSpriteSheet from rom-id.js, previewTileArt from preview-tile.js) ──
-  tiles: { absorbs: ["inspectPatternTiles", "getTile", "tileFingerprints", "tilesAscii", "extractSpriteSheet", "previewTileArt"], axis: "op" },
-  // ── encodeArt (PNG→native art; convertImageToTiles+imageToTilemap from platform-tools.js, quantizePngForPlatform+cropSpriteSheet from sprite-pipeline.js, validateGenesisTiles from metasprite-tools.js) ──
-  encodeArt: { absorbs: ["convertImageToTiles", "imageToTilemap", "quantizePngForPlatform", "cropSpriteSheet", "validateGenesisTiles"], axis: "stage" },
-  // ── importArt (editor-file/ROM → native tiles; load* from art-loaders.js, crossPlatformSpriteImport from sprite-pipeline.js as from:'rom') ──
-  importArt: { absorbs: ["loadAsepriteSheet", "loadGifAnimation", "loadSpriteSheet", "loadTilemap", "crossPlatformSpriteImport"], axis: "from" },
-  // ── memory (read/write/search; all 8 from memory.js) ──
-  memory: { absorbs: ["readMemory", "writeMemory", "readCartRom", "snapshotMemory", "diffMemory", "classifyRegion", "searchValue", "searchNext"], axis: "op" },
-  // ── cpu (read/drive; getCPUState from platform-tools.js, setRegister/callSubroutine/decompressWith from watch-memory.js) ──
-  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; 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 (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. ──
-  playtest: { absorbs: ["playtestStop", "playtestStatus", "playtestFramebuffer"], axis: "op" },
-  // ── encodeAudio (external clip → native sample format; pcmToBrr + wavToXgm2Pcm from audio.js) ──
-  encodeAudio: { absorbs: ["pcmToBrr", "wavToXgm2Pcm"], axis: "target" },
-};
-
-/** Every OLD tool name that the consolidation removes (absorbed into a new tool). */
-export function absorbedToolNames() {
-  const names = [];
-  for (const entry of Object.values(MERGE_MAP)) {
-    if (entry.absorbs) names.push(...entry.absorbs);
-  }
-  return names;
-}
-
-/** The consolidated (new) tool names this manifest defines. */
-export function consolidatedToolNames() {
-  return Object.keys(MERGE_MAP);
-}