romdevtools 0.27.0 → 0.29.0

package/src/host/LibretroHost.js

@@ -43,6 +43,12 @@ const PLATFORM_CORE_OPTIONS = {
   // `… - C-BIOS` machine tree ships in romdev-core-bluemsx/bios and is mirrored
   // into the wasm FS as the system dir (see loadMedia + resolveSystemDir).
   msx: { bluemsx_msxtype: "MSX2+ - C-BIOS" },
+  // geargrafx ships with the TurboTap disabled, which makes port-1 input
+  // unreachable in-game (every pad scan slot mirrors pad 0). Enabling it
+  // costs nothing for 1P games (slot 0 still reads pad 0) and routes the
+  // host's port-1 input to pad slot 2 — PCE 2P works (probed 2026-06-10
+  // during the ZENITH BARRAGE gold round).
+  pce: { geargrafx_turbotap: "Enabled" },
   // VICE mounts a .d64/.tap/.crt but, with autostart off, just sits at the BASIC
   // `READY.` prompt — the agent would see a blue boot screen, not the game. Force
   // autostart so a disk/tape image runs the first program automatically (same as
@@ -57,6 +63,19 @@ const PLATFORM_CORE_OPTIONS = {
     // files back into the .d64 (VICE updates the in-FS image in place). Without
     // this a game's SAVE silently fails / errors — defeating disk-save support.
     vice_floppy_write_protection: "disabled",
+    // TWO live C64 control ports so 2P games see player 2. The VICE core drives
+    // ONE control port per RetroPad by default (every retro port → cur_port);
+    // the per-port split only happens with the userport adapter, where the
+    // mapper does vice_port = cur_port + retro_port. With joyport=1 + a userport
+    // adapter that gives retro0→control-port-1, retro1→control-port-2 — BOTH
+    // standard ports live. Our games read P1 on control port 2 ($DC00) and P2
+    // on port 1 ($DC01); the host swaps the two retro ports below
+    // (portInputToMask C64 path) so host port 0 = P1 (control port 2) and host
+    // port 1 = P2 (control port 1), matching the universal "port 0 = player 1"
+    // convention. Verified: drives both paddles independently in 2P, 1P-vs-CPU
+    // still reachable. (Both options ship in the wasm — no core rebuild.)
+    vice_joyport: "1",
+    vice_userport_joytype: "HIT",
   },
 };
 
@@ -415,6 +434,9 @@ export class LibretroHost {
 
     // Configure controller port 0 as joypad (some cores default to NONE).
     mod._retro_set_controller_port_device(0, RETRO_DEVICE_JOYPAD);
+    // Port 1 too — needed for 2P. The C64/VICE 2P path (two live control ports)
+    // only reads RetroPad port 1 when it's registered as a joypad device.
+    mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
 
     // ---- Settle the framebuffer to the ROM's chosen geometry ----
     //
@@ -623,7 +645,14 @@ export class LibretroHost {
       this._applyC64ButtonKeys(input.ports[0] || {});
     }
     for (let port = 0; port < this.state.inputPorts.length; port++) {
-      const portInput = this._c64StripKeyButtons(input.ports[port], platform);
+      // C64 2P port swap: with joyport=1 + userport the VICE mapper binds
+      // RetroPad 0 → C64 control port 1 and RetroPad 1 → control port 2. But
+      // our games read player 1 on control port 2 ($DC00) and player 2 on
+      // control port 1 ($DC01). So feed host port 0's input to RetroPad slot 1
+      // (→ control port 2 = P1) and host port 1's to slot 0 (→ port 1 = P2),
+      // restoring the universal "host port 0 = player 1" convention.
+      const srcPort = platform === "c64" ? (port ^ 1) : port;
+      const portInput = this._c64StripKeyButtons(input.ports[srcPort], platform);
       this.state.inputPorts[port][0] = portInputToMask(portInput, platform);
     }
   }
@@ -776,6 +805,18 @@ export class LibretroHost {
     return mod._retro_get_memory_size(id) || 0;
   }
 
+  /** gpgx stores 68k work RAM as 16-bit words in host-LE order — the CPU's
+   *  byte at $FF0000+A physically lives at work_ram[A^1] (core/macros.h
+   *  READ_BYTE/WRITE_BYTE on little-endian builds). Normalize the system_ram
+   *  region to CPU byte order here so offset X IS the byte the 68k sees at
+   *  $FF0000+X — otherwise every byte-granular tool (search, diff, write,
+   *  classify) is off-by-XOR-1 vs disassembly addresses and cheat-DB maps
+   *  (self-consistent within raw-only loops, which is why it hid; poisonous
+   *  the moment an address crosses to/from the CPU view). */
+  _byteSwapRegion(region) {
+    return region === "system_ram" && this.status.platform === "genesis";
+  }
+
   readMemory(region, offset, length) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
@@ -786,6 +827,12 @@ export class LibretroHost {
     if (offset < 0 || offset + length > size) {
       throw new RangeError(`read out of bounds: offset=${offset} len=${length} size=${size}`);
     }
+    if (this._byteSwapRegion(region)) {
+      const heap = mod.HEAPU8;
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = heap[ptr + ((offset + i) ^ 1)];
+      return out;
+    }
     return new Uint8Array(mod.HEAPU8.buffer, ptr + offset, length).slice();
   }
 
@@ -804,6 +851,11 @@ export class LibretroHost {
     if (offset < 0 || offset + bytes.length > size) {
       throw new RangeError(`write out of bounds: offset=${offset} len=${bytes.length} size=${size}`);
     }
+    if (this._byteSwapRegion(region)) {
+      const heap = mod.HEAPU8;
+      for (let i = 0; i < bytes.length; i++) heap[ptr + ((offset + i) ^ 1)] = bytes[i];
+      return;
+    }
     mod.HEAPU8.set(bytes, ptr + offset);
   }
 
@@ -1072,7 +1124,36 @@ export class LibretroHost {
       this.reset();
       return false;
     }
+    // Battery semantics: SAVE_RAM survives a power-cycle on a battery cart.
+    // Carry it across the reload (the reload itself zeroes it).
+    let sram = null;
+    try {
+      const size = this.regionSize("save_ram");
+      if (size > 0) sram = Uint8Array.from(this.readMemory("save_ram", 0, size));
+    } catch { /* no save_ram region on this core/cart — nothing to carry */ }
     await this.loadMedia(this._loadArgs);
+    if (sram && sram.some((b) => b !== 0)) {
+      // Restore like a frontend restores the .srm: bytes in place BEFORE the
+      // game's boot code reads them. Some cores size SAVE_RAM lazily (gpgx
+      // scans for the last non-empty byte → size 0 on a fresh boot), so fall
+      // back to the raw region pointer when the sized path refuses.
+      let restored = false;
+      try {
+        if (this.regionSize("save_ram") >= sram.length) {
+          this.writeMemory("save_ram", 0, sram);
+          restored = true;
+        }
+      } catch { /* sized path unavailable */ }
+      if (!restored) {
+        try {
+          const ptr = this.mod._retro_get_memory_data(0); // RETRO_MEMORY_SAVE_RAM
+          if (ptr) { this.mod.HEAPU8.set(sram, ptr); restored = true; }
+        } catch { /* no save buffer on this core/cart */ }
+      }
+      // loadMedia's settle frames may already have run the game's
+      // hi-score load against empty SRAM — soft-reset so boot re-reads.
+      if (restored) { try { this.reset(); } catch { /* keep the loaded state */ } }
+    }
     return true;
   }
 
@@ -1263,6 +1344,161 @@ export class LibretroHost {
     return !!(this.mod && typeof this.mod._romdev_watchdog_set === "function");
   }
 
+  /** True when this core build exposes the at-hit register snapshot (gpgx). */
+  regSnapSupported() {
+    return !!(this.mod && typeof this.mod._romdev_regsnap_get === "function");
+  }
+
+  /**
+   * Read the at-hit register snapshot: the FULL register file frozen by the
+   * core hook at the instant a pc-break / watchdog / write-watch / read-watch
+   * fired. The live register file keeps running after a hit (per-scanline CPU
+   * scheduling / next-frame re-entry), so post-hit register reads drift —
+   * this snapshot is the truth. Shipped by ALL patched cores (all 14
+   * platforms). Returns { kind, named } or null when no hit has been
+   * snapshotted (or the core build predates the export). kind:
+   * 1=pc-break/step, 2=watchdog, 3=write-watch, 4=read-watch. `named` keys
+   * follow each CPU's own register file; `pc` is always the EXECUTING
+   * instruction (ARM: its pipeline PC, the same convention breakpoint
+   * addresses use). Pass clear to reset the kind.
+   */
+  getRegSnapshot(clear = false) {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_regsnap_get !== "function") return null;
+    const ptr = mod._malloc(21 * 4);
+    try {
+      mod._romdev_regsnap_get(ptr, clear ? 1 : 0);
+      const u = new Uint32Array(mod.HEAPU8.buffer, ptr, 21);
+      const kind = u[0];
+      if (!kind) return null;
+      const r = Array.from(u.subarray(2, 2 + Math.min(u[1] >>> 0, 19)));
+      const platform = this.status.platform;
+      const h2 = (v) => "$" + (v & 0xFF).toString(16).toUpperCase();
+      const h4 = (v) => "$" + (v & 0xFFFF).toString(16).toUpperCase();
+      const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase();
+      let named;
+      if (platform === "genesis") {
+        // m68k regId order: D0-7, A0-7, PC(instr start), SR, SP.
+        named = {};
+        for (let i = 0; i < 8; i++) named["d" + i] = hx(r[i]);
+        for (let i = 0; i < 8; i++) named["a" + i] = hx(r[8 + i]);
+        named.pc = hx(r[16]);
+        named.sr = h4(r[17]);
+        named.sp = hx(r[18]);
+      } else if (platform === "gba") {
+        // ARM regId order: r0-r15 raw, CPSR at 16, instr pipeline PC at 17, SP at 18.
+        named = {};
+        for (let i = 0; i < 16; i++) named["r" + i] = hx(r[i]);
+        named.cpsr = hx(r[16]);
+        named.pc = hx(r[17]);   // EXECUTING instruction's pipeline PC (pc-break convention)
+        named.sp = hx(r[18]);
+      } else if (platform === "snes") {
+        // 65816 regId order: A, X, Y, P, S, DB, D, …, PBPC(instr start).
+        named = {
+          a: h4(r[0]), x: h4(r[1]), y: h4(r[2]), p: h4(r[3]), s: h4(r[4]),
+          db: h2(r[5]), d: h4(r[6]), pc: hx(r[16]),
+        };
+      } else if (platform === "gb" || platform === "gbc") {
+        named = {
+          a: h2(r[0]), f: h2(r[1]), b: h2(r[2]), c: h2(r[3]),
+          d: h2(r[4]), e: h2(r[5]), h: h2(r[6]), l: h2(r[7]),
+          pc: h4(r[16]), sp: h4(r[18]),
+        };
+      } else if (platform === "sms" || platform === "gg" || platform === "msx") {
+        named = {
+          a: h2(r[0]), f: h2(r[1]), b: h2(r[2]), c: h2(r[3]),
+          d: h2(r[4]), e: h2(r[5]), h: h2(r[6]), l: h2(r[7]),
+          ix: h4(r[8]), iy: h4(r[9]), pc: h4(r[16]), sp: h4(r[18]),
+        };
+      } else {
+        // 6502 family (nes, atari2600, atari7800, c64, lynx, pce/huc6280):
+        // regId order A, X, Y, P, S, …, PC(instr start).
+        named = {
+          a: h2(r[0]), x: h2(r[1]), y: h2(r[2]), p: h2(r[3]), s: h2(r[4]),
+          pc: h4(r[16]),
+        };
+      }
+      return { kind, named };
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** True when this core build exposes the pure-CPU run (gpgx). */
+  runPureSupported() {
+    return !!(this.mod && typeof this.mod._romdev_run_pure === "function");
+  }
+
+  /** True when this core build exposes the interrupt block (the pure-call
+   *  primitive on cores without a separable CPU loop). */
+  irqBlockSupported() {
+    return !!(this.mod && typeof this.mod._romdev_irqblock_set === "function");
+  }
+
+  /** Suppress (or restore) interrupt DELIVERY to the active CPU. While
+   *  blocked, pending IRQ/NMI lines stay pending and no game handler can run
+   *  — the mechanism behind pure calls on cores whose CPU/video loops are
+   *  interleaved (everything except gpgx, which steps the CPU alone). */
+  setIrqBlock(on) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_irqblock_set !== "function") {
+      throw new Error("this core build does not expose the interrupt block (rebuild with romdev_irqblock_set).");
+    }
+    mod._romdev_irqblock_set(on ? 1 : 0);
+  }
+
+  /** True when a pure call is possible on this platform by ANY mechanism:
+   *  a separable CPU run (gpgx), an interrupt block, or hardware with no
+   *  interrupts at all (the 2600's 6507 has no IRQ/NMI lines wired — every
+   *  call is inherently pure). */
+  pureCallSupported() {
+    return this.runPureSupported() || this.irqBlockSupported() || this.status.platform === "atari2600";
+  }
+
+  /** True when this core build exposes the VRAM-port copy trace (port-based
+   *  video memory: NES/SNES/PCE/MSX/SMS/GG/Genesis). Direct-mapped platforms
+   *  answer the same question through watchRange on the CPU-visible VRAM. */
+  vramWatchSupported() {
+    const mod = this.mod;
+    return !!(mod && typeof mod._romdev_vramwatch_set === "function" && typeof mod._romdev_vramwatch_get === "function");
+  }
+
+  /**
+   * Run `frames` frames logging every data-port write landing in the VRAM
+   * address window [lo,hi] — {vramAddr, pc, value} per event, pc being the
+   * EXECUTING instruction (during DMA on SNES, the instruction that triggered
+   * it). The "where does this graphic come from?" primitive for port-based
+   * video memory. Returns { events, total, stored, truncated }.
+   */
+  watchVram(lo, hi, frames, perFrame) {
+    const mod = this._needMod();
+    this._needMedia();
+    if (!this.vramWatchSupported()) throw new Error("VRAM copy trace not supported by this core.");
+    mod._romdev_vramwatch_set(lo >>> 0, hi >>> 0, 1);
+    try {
+      this._runFramesExclusive(perFrame ?? (() => false), frames);
+    } finally {
+      // drained below; disarm after
+    }
+    const CAP = 1024;
+    const outPtr = mod._malloc(CAP * 3 * 4);
+    const out2Ptr = mod._malloc(8);
+    try {
+      const n = mod._romdev_vramwatch_get(outPtr, CAP, out2Ptr);
+      const u = new Uint32Array(mod.HEAPU8.buffer, outPtr, n * 3);
+      const u2 = new Uint32Array(mod.HEAPU8.buffer, out2Ptr, 2);
+      const events = [];
+      for (let i = 0; i < n; i++) {
+        events.push({ vramAddr: u[i * 3], pc: u[i * 3 + 1], value: u[i * 3 + 2] & 0xFF });
+      }
+      return { events, total: u2[0], stored: u2[1], truncated: u2[0] > u2[1] };
+    } finally {
+      mod._free(outPtr);
+      mod._free(out2Ptr);
+      mod._romdev_vramwatch_set(0, 0, 0);
+    }
+  }
+
   /** Arm/disarm the read watchpoint on a CPU address. */
   setReadWatch(address, enabled = true) {
     const mod = this._needMod();
@@ -1488,6 +1724,13 @@ export class LibretroHost {
     const {
       pc, regs = {}, spReg = prof.spReg, pcReg = prof.pcReg, sentinelPC = prof.defaultSentinel,
       sentinelBytes = prof.retBytes, maxFrames = 600, sandbox = true, capture,
+      // pure: step ONLY the active CPU (no frame machinery — VDP lines, co-CPU,
+      // interrupt raising). Without it, each "frame" of the call runs the
+      // game's OWN per-frame logic concurrently (VBlank handlers via RAM
+      // vectors etc.), which can stomp the buffer the driven routine is
+      // writing — a real session diffed a CORRECT codec reimplementation
+      // against that poisoned output for hours. gpgx (Genesis/SMS/GG) only.
+      pure = false,
       // presetMemory: [{addr, bytes}] CPU-space writes applied before the call
       // (codecs that read a global from RAM — a dest stride, a mode flag, etc).
       presetMemory = [],
@@ -1523,6 +1766,7 @@ export class LibretroHost {
 
     const snapshot = sandbox ? this.serializeState() : null;
     let captured, returned = false, framesRun = 0, watchdogTripped = false, stoppedAtPC = false;
+    let pureMode = null;
     try {
       // Apply pre-call memory writes (CPU-space).
       for (const m of presetMemory) {
@@ -1575,19 +1819,67 @@ export class LibretroHost {
       const target = (stopAtPC !== undefined ? stopAtPC : sentinelPC) >>> 0;
       this.setPCBreak(target, true, false);
       let finalState = null;
+      let irqBlocked = false;
       try {
-        framesRun = this._runFramesExclusive(() => {
-          const st = this.getPCBreak(false);
-          if (st.hit) {
-            finalState = st;
-            if (st.watchdog) watchdogTripped = true;
-            else if (stopAtPC !== undefined) stoppedAtPC = true;
-            else returned = true;
-            return true;
+        if (pure && this.runPureSupported()) {
+          // STRONGEST pure mode (gpgx): step ONLY the CPU — no frame machinery
+          // at all. Mask m68k interrupts so a PENDING VINT raised before the
+          // call can't redirect entry (no NEW interrupts are raised — the
+          // system loop never runs). The sandbox restore (or the game's own
+          // RTE discipline) makes the IPL change invisible afterward.
+          pureMode = "cpu-only";
+          if (this.status.platform === "genesis") {
+            this.setReg(17, (this.getReg(17) | 0x0700) & 0xFFFF);
           }
-          return false;
-        }, maxFrames);
+          // Drive the CPU in cycle chunks, checking the sentinel/watchdog
+          // between chunks. The watchdog bounds total instructions; the chunk
+          // cap is only a backstop against a watchdog-less older core.
+          const CHUNK_CYCLES = 1_000_000;
+          const maxChunks = 512;
+          for (let i = 0; i < maxChunks; i++) {
+            this.mod._romdev_run_pure(CHUNK_CYCLES);
+            const st = this.getPCBreak(false);
+            if (st.hit) {
+              finalState = st;
+              if (st.watchdog) watchdogTripped = true;
+              else if (stopAtPC !== undefined) stoppedAtPC = true;
+              else returned = true;
+              break;
+            }
+          }
+        } else {
+          if (pure) {
+            // INTERRUPT-BLOCKED pure mode (every other core): the frame
+            // machinery still runs (video/timers advance — harmless, they
+            // don't write game RAM), but interrupt DELIVERY is suppressed, so
+            // no game handler can execute. The only running game code is the
+            // routine we called — the same guarantee that matters for the
+            // output buffer. The 2600's 6507 has no interrupt lines at all,
+            // so every call there is pure by hardware.
+            if (this.irqBlockSupported()) {
+              this.setIrqBlock(true);
+              irqBlocked = true;
+              pureMode = "irq-blocked";
+            } else if (this.status.platform === "atari2600") {
+              pureMode = "no-interrupts";
+            } else {
+              throw new Error("cpu({op:'call', pure:true}) not supported by this core build (needs the romdev_irqblock_set export — update the core package).");
+            }
+          }
+          framesRun = this._runFramesExclusive(() => {
+            const st = this.getPCBreak(false);
+            if (st.hit) {
+              finalState = st;
+              if (st.watchdog) watchdogTripped = true;
+              else if (stopAtPC !== undefined) stoppedAtPC = true;
+              else returned = true;
+              return true;
+            }
+            return false;
+          }, maxFrames);
+        }
       } finally {
+        if (irqBlocked) { try { this.setIrqBlock(false); } catch { /* core gone */ } }
         this.setPCBreak(0, false, false);
         this.setWatchdog(0);
         if (!finalState) finalState = this.getPCBreak(true); else this.getPCBreak(true);
@@ -1607,6 +1899,7 @@ export class LibretroHost {
     const fin = this._lastCallResult || {};
     return {
       returned, framesRun,
+      ...(pure ? { pure: true, pureMode } : {}),
       ...(watchdogTripped ? { watchdog: true, reason: "watchdog: hit the instruction budget (likely a runaway loop — wrong A0/regs, a needed preset, or legitimately huge; raise maxInstructions or check the entry setup)" } : {}),
       ...(stoppedAtPC ? { stoppedAtPC: "$" + (stopAtPC >>> 0).toString(16).toUpperCase() } : {}),
       ...(fin.finalPC != null ? { finalPC: "$" + fin.finalPC.toString(16).toUpperCase(), finalPCRaw: fin.finalPC } : {}),

package/src/http/tool-registry.js

@@ -17,7 +17,7 @@
 import { z } from "zod";
 import { registerTools } from "../mcp/tools/index.js";
 import { withClearToolErrors } from "../mcp/util.js";
-import { observer, summarizeForLog, extractImages } from "../observer/bus.js";
+import { observer, summarizeForLog, extractImages, pushObserverFrame } from "../observer/bus.js";
 import { getHostOrNull } from "../mcp/state.js";
 
 /**
@@ -151,21 +151,21 @@ export async function runTool(tool, args, sessionKey) {
     // Strip both from the caller-visible result before it's serialized.
     let sidebandImages = [];
     let frameProvider = null;
+    let frameCaption = null;
     if (r && typeof r === "object") {
       if (Array.isArray(r._observerImages)) { sidebandImages = r._observerImages; delete r._observerImages; }
       if (typeof r._observerFrameProvider === "function") { frameProvider = r._observerFrameProvider; delete r._observerFrameProvider; }
+      if (typeof r._observerFrameCaption === "string") { frameCaption = r._observerFrameCaption; delete r._observerFrameCaption; }
     }
     if (frameProvider) {
-      setImmediate(() => {
-        try {
-          const img = frameProvider();
-          // 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 */ }
-      });
+      // Throttled to one per 2s per (session, tool), trailing-edge — same
+      // policy as the MCP path (bus.js pushObserverFrame). Platform is
+      // re-resolved at emit time (loadMedia sets it DURING the call).
+      pushObserverFrame({
+        sessionKey, tool: tool.name, ts: startedAt, platform,
+        resolvePlatform: () => { try { return getHostOrNull(sessionKey)?.status?.platform ?? platform; } catch { return platform; } },
+        ...(frameCaption ? { caption: frameCaption } : {}),
+      }, frameProvider);
     }
     const inlineImages = extractImages(r);
     const images = inlineImages.length > 0 ? inlineImages : sidebandImages;

package/src/mcp/server.js

@@ -418,6 +418,12 @@ async function main() {
     log.info(`optional observer:      http://${bannerHost}:${port}/livestream`);
     log.info("");
     log.info("connect your coding agent: https://github.com/monteslu/romdev#connect");
+    // One conditional line so an agent knows the constraint BEFORE promising a
+    // playtest window to a human (the op itself still errors with the full fix).
+    if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+      log.info("");
+      log.info("note: no display detected (headless) — playtest({op:'open'}) is unavailable; all other tools work.");
+    }
   });
   const extraServers = [];
   for (const h of bindHosts.slice(1)) {

package/src/mcp/tools/cheats.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
+import { attachObserverFrame } from "./watch-memory.js";
 import { lookupCheats, searchCheatGames } from "../../cheats/lookup.js";
 import { encodeForDevice, nativeDevicesFor, decodeCode } from "../../cheats/gamegenie.js";
 
@@ -334,7 +335,7 @@ export function registerCheatTools(server, z, sessionKey) {
       switch (args.op) {
         case "lookup": return jsonContent(await cheatsLookupCore(args));
         case "search": return jsonContent(await cheatsSearchCore(args));
-        case "apply":  return jsonContent(await cheatsApplyCore(args, sessionKey));
+        case "apply":  return attachObserverFrame(jsonContent(await cheatsApplyCore(args, sessionKey)), getHost(sessionKey), "cheat applied");
         case "clear":  return jsonContent(await cheatsClearCore(args, sessionKey));
         case "make":   return jsonContent(await cheatsMakeCore(args));
         default: throw new Error(`cheats: unknown op '${args.op}'`);