@henols/vice-mcp 0.1.12 → 0.2.0

package/stock-dispatch.ts

@@ -27,6 +27,7 @@
 import { resolve, join } from "node:path";
 
 import type { ViceBackend } from "./backend-detect.mts";
+import type { ToolInfo } from "./vice.ts";
 import { type HeldLease } from "./vice-broker-client.ts";
 import { stockConnect, stockDisconnect, stockReconnect, type StockConnectSession, type StockConnectDeps } from "./stock-connect.ts";
 import {
@@ -61,6 +62,15 @@ import { handleExecutionPause, handleExecutionRun, handleExecutionStep, handleEx
 import { handleMachineReset, handleAutostart, handleDiskAttach, handleSnapshotSave, handleSnapshotLoad } from "./stock-machine.ts";
 import { handleKeyboardType, handleKeyboardPetscii, handleJoystickSet } from "./stock-input.ts";
 import { handleDisassemble } from "./stock-disassemble.ts";
+import { handleMemorySearch, handleMemoryCompare } from "./stock-memory-search.ts";
+import { handleSymbolsLoad, handleSymbolsLookup } from "./stock-symbols.ts";
+import { handleViciiGetState } from "./stock-vicii.ts";
+import { handleCiaGetState } from "./stock-cia.ts";
+import { handleSpriteGet, handleSpriteInspect } from "./stock-sprites.ts";
+import { handleCyclesStopwatch, forgetTimingForOtherTargets } from "./stock-timing.ts";
+import { handleRunUntil } from "./stock-run-until.ts";
+import { handleDiagnoseStock } from "./stock-diagnose.ts";
+import { handleRecycleStock } from "./stock-recycle.ts";
 
 // Re-exported so Phase 2's existing import surface (and its 921-line test
 // file) keeps working unchanged -- these four names used to be DEFINED
@@ -92,6 +102,53 @@ export function manifestPathForBackend(backend: ViceBackend, hereDir: string, en
   return backend === "stock" ? join(hereDir, "tools-manifest.stock.json") : join(hereDir, "tools-manifest.json");
 }
 
+/**
+ * resolveAdvertisedToolDefinition() -- WR-07's fix. `tools` in vice-proxy.ts
+ * is a name-keyed record: whichever assignment to a given key runs LAST
+ * wins, and vice-proxy.ts's own registration order used to assign
+ * RECYCLE_TOOL/DIAGNOSE_TOOL's literal (fork-worded) definitions
+ * UNCONDITIONALLY, on both backends, straight after the backend-aware
+ * manifest loop had already populated the same keys correctly. So on the
+ * stock backend, `tools/list` served the fork's five-verdict vocabulary --
+ * including `stale_read_path`, which stock cannot produce (D-03) -- and
+ * omitted `monitor_held_elsewhere`, which stock can, even though the
+ * corrected stock manifest entry sat right there in
+ * tools-manifest.stock.json, unread. This function is the ONE place that
+ * decision is now made, so the manifest loop's own per-tool selection and
+ * the two synthetic tools' registration agree.
+ *
+ * Behaviour:
+ *   - `backend === "fork"`: always returns `syntheticDef` unchanged, no
+ *     matter what `manifestTools` contains. The fork's advertised surface
+ *     is frozen at v0.1.x and this function must never be able to alter it.
+ *   - `backend === "stock"`: returns the `manifestTools` entry whose `name`
+ *     equals `syntheticDef.name`, if one exists. Falls back to
+ *     `syntheticDef` when no match exists -- `readManifestTools()`'s own
+ *     malformed/unreadable-manifest fallbacks answer `[]`, and in that case
+ *     the proxy must still advertise a WORKING tool rather than none at all
+ *     (T-07-16-02).
+ *   - NEVER merges fields from the two definitions. Picking one whole
+ *     definition keeps `description`, `inputSchema` and `outputSchema`
+ *     internally consistent; a field-by-field merge could pair a fork
+ *     description with a stock `outputSchema`, or the reverse.
+ *
+ * Declared as a `function`, not a `const` arrow, per this module tree's own
+ * standing rule: stock-dispatch.ts <-> stock-diagnose.ts <-> stock-recycle.ts
+ * form a runtime import cycle, and the phase already reproduced a live
+ * `ReferenceError` from a `const` handler export sitting in that cycle.
+ */
+export function resolveAdvertisedToolDefinition(
+  syntheticDef: ToolInfo,
+  backend: ViceBackend,
+  manifestTools: ToolInfo[],
+): ToolInfo {
+  if (backend === "fork") {
+    return syntheticDef;
+  }
+  const manifestEntry = manifestTools.find((t) => t.name === syntheticDef.name);
+  return manifestEntry ?? syntheticDef;
+}
+
 // ---------------------------------------------------------------------------
 // ensureStockSession() -- the lease-to-session seam (Task 2).
 // ---------------------------------------------------------------------------
@@ -332,6 +389,13 @@ export async function ensureStockSession(deps: StockDispatchDeps): Promise<Ensur
   // all. The reuse and reconnect branches return before this line, so a
   // reconnect to the SAME machine never evicts anything.
   forgetConditionsForOtherTargets(session.targetId);
+  // WR-14 (07-REVIEW.md): stock-timing.ts's two targetId-keyed caches (the
+  // video-standard cache and the stopwatch baseline store) are evicted from the
+  // SAME line, for the same reasons, so the registries can never drift apart on
+  // when they forget. Both are strong Maps deliberately -- they must survive a
+  // stockReconnect() to the same machine -- so without this they grow one entry
+  // per distinct instance for the life of the process.
+  forgetTimingForOtherTargets(session.targetId);
   return { ok: true, session };
 }
 
@@ -549,7 +613,7 @@ const handlePing: StockSessionHandler = async (_args, session, deps) => {
  *   - `vice_snapshot_list` (D-16 -- deleted from both manifests)
  *   - `vice_disk_detach` (D-13 -- Phase 7, via the text monitor)
  *   - `vice_joystick_tap` (needs a resume plus Phase 7's timing route)
- *   - `vice_disk_read_sector` (Phase 5)
+ *   - `vice_disk_read_sector` (CUT from scope 2026-08-17 -- no skill calls it; see ROADMAP.md "Cut from scope (v0.2.0, 2026-08-17)" and docs/stock-vice-parity.md item 6)
  *   - `vice_sid_get_state` and the low-level keyboard family (hard losses)
  *   - `vice_machine_config_get` / `vice_machine_config_set` (Phase 6)
  * `dispatchStock()`'s miss branch already refuses any of these by name,
@@ -606,6 +670,43 @@ const STOCK_DISPATCH_TABLE: Record<string, StockHandler> = {
 
   // derived (DERIV-07, DISASM-01)
   vice_disassemble: withDerivedTool("vice_disassemble", { needsSession: true }, handleDisassemble),
+
+  // derived (DERIV-01)
+  vice_memory_search: withDerivedTool("vice_memory_search", { needsSession: true }, handleMemorySearch),
+  vice_memory_compare: withDerivedTool("vice_memory_compare", { needsSession: true }, handleMemoryCompare),
+
+  // derived (DERIV-04) -- needsSession:false: pure client-side state, never touches the wire
+  vice_symbols_load: withDerivedTool("vice_symbols_load", { needsSession: false }, handleSymbolsLoad),
+  vice_symbols_lookup: withDerivedTool("vice_symbols_lookup", { needsSession: false }, handleSymbolsLookup),
+
+  // derived (DERIV-05)
+  vice_vicii_get_state: withDerivedTool("vice_vicii_get_state", { needsSession: true }, handleViciiGetState),
+  vice_cia_get_state: withDerivedTool("vice_cia_get_state", { needsSession: true }, handleCiaGetState),
+
+  // derived (DERIV-06)
+  vice_sprite_get: withDerivedTool("vice_sprite_get", { needsSession: true }, handleSpriteGet),
+  vice_sprite_inspect: withDerivedTool("vice_sprite_inspect", { needsSession: true }, handleSpriteInspect),
+
+  // derived (TIME-01)
+  vice_cycles_stopwatch: withDerivedTool("vice_cycles_stopwatch", { needsSession: true }, handleCyclesStopwatch),
+
+  // derived (TIME-02)
+  vice_run_until: withDerivedTool("vice_run_until", { needsSession: true }, handleRunUntil),
+
+  // derived (TIME-04) -- the two proxy-local synthetic tools (RECYCLE_TOOL/
+  // DIAGNOSE_TOOL in vice-proxy.ts), backend-routed to dispatchStock() by
+  // buildBackendAwareTool() rather than served from the fork's HTTP
+  // transport. Deliberate asymmetry, documented at this call site (see also
+  // DerivedPureHandler's amended doc comment in stock-derived.ts):
+  // vice_diagnose uses needsSession:false because its own handler acquires
+  // the session itself (inside its own try/catch) so it can convert a
+  // thrown MonitorOwnershipError into the monitor_held_elsewhere VERDICT
+  // rather than let withDerivedTool()'s preamble turn it into refusal text
+  // -- the exact generic error string that verdict exists to replace.
+  // vice_recycle keeps needsSession:true: it needs a live session to gather
+  // evidence and has no verdict vocabulary of its own to preserve.
+  vice_diagnose: withDerivedTool("vice_diagnose", { needsSession: false }, handleDiagnoseStock),
+  vice_recycle: withDerivedTool("vice_recycle", { needsSession: true }, handleRecycleStock),
 };
 
 /** Looks up the table entry for `name` -- `undefined` on a miss, never a
@@ -624,9 +725,9 @@ export function stockHandlerFor(name: string): StockHandler | undefined {
  * naming the fork as the backend that does -- WITHOUT reading `deps` at all
  * (no lease is ever requested for a tool that does not exist on this
  * backend). There is no third branch, and in particular NO fall-through to
- * forwardToVice() anywhere in this file or anything it calls -- that is
- * D-09's whole point, grep-gated to zero occurrences of that name in this
- * file's own code lines.
+ * the fork's HTTP-forwarding path anywhere in this file or anything it calls
+ * -- that is D-09's whole point, grep-gated to zero occurrences of that
+ * function's name in this file's own code lines.
  */
 export async function dispatchStock(name: string, args: Record<string, unknown>, deps: StockDispatchDeps): Promise<StockToolResult> {
   const handler = stockHandlerFor(name);

package/stock-handler.ts

@@ -21,6 +21,9 @@
 //   - Never build a `{ content: [...], isError: false }` literal outside
 //     stockAnswer() -- that is exactly how an answer ships without
 //     `runState`, which D-06 requires on EVERY stock tool answer.
+//   - Never construct a session-free derived answer as a bare literal
+//     either -- a `needsSession: false` handler calls derivedAnswer(), a
+//     sessioned handler calls stockAnswer(), and there is no third shape.
 //   - Never write a third error converter. convertHandshakeError() (moved
 //     here, unchanged, from stock-dispatch.ts) is the ONE conversion for a
 //     failed ensureStockSession()/stockConnect(); convertWireError() (new
@@ -173,3 +176,29 @@ export function stockAnswer(client: ViceMonitorClient, payload: Record<string, u
   const runState = runStateFor(client);
   return { content: [{ type: "text", text: JSON.stringify({ ...payload, runState }) }], isError: false };
 }
+
+// ---------------------------------------------------------------------------
+// derivedAnswer() -- new here (Phase 5, 05-02, D-05-06). The ONE place a
+// SESSION-FREE (`withDerivedTool(..., { needsSession: false }, ...)`) derived
+// tool's successful answer is constructed. `runState: "unknown"` is the
+// honest value here, not a placeholder: a session-free handler never opens a
+// monitor connection, so the emulator's run state was genuinely never
+// observed -- "unknown" is already documented (docs/stock-vice-parity.md
+// §A.7) as "the honest post-connect value and is not a failure". This
+// function exists so the standing D-06 gate in stock-dispatch.test.ts
+// ("every stock entry's outputSchema declares a required runState enum of
+// [running, stopped, unknown]") needs no exemption list for the two DERIV-04
+// symbol tools (`vice_symbols_load`/`vice_symbols_lookup`) -- currently the
+// only `needsSession: false` tools in the milestone, and this function's
+// only consumer (stock-symbols.ts).
+//
+// Unlike stockAnswer(), this function takes NO client argument at all --
+// there is no session to read a run state from, which is the whole point.
+// `runState` is stamped LAST, so a `runState` key already present in
+// `payload` is overwritten -- matching stockAnswer()'s own "a handler may
+// never supply its own" rule.
+// ---------------------------------------------------------------------------
+
+export function derivedAnswer(payload: Record<string, unknown>): StockOkResult {
+  return { content: [{ type: "text", text: JSON.stringify({ ...payload, runState: "unknown" }) }], isError: false };
+}

package/stock-memory-search.ts

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+// stock-memory-search.ts
+//
+// vice_memory_search / vice_memory_compare -- the DERIV-01 pair. Both are
+// DERIVED tools: the binary monitor's confirmed command set
+// (docs/phase0-binmon-findings.md §5) has no MEMORY_SEARCH or MEMORY_COMPARE
+// opcode at all, so both answers are computed CLIENT-SIDE from one bounded
+// MEM_GET read per range -- the same shape stock-disassemble.ts already
+// uses. Registered through withDerivedTool("...", { needsSession: true },
+// ...) in stock-dispatch.ts, never withStockSession() (D-01/D-03).
+//
+// WHAT NOT TO DO:
+//   - Never import hostpath.ts or vice-proxy.ts, and never call the
+//     fork-forwarding function's rewriteArguments() -- hostpath-consumers.test.ts
+//     gates this file's absence from the closed host-path consumer set
+//     (D-02). Neither tool takes a path argument at all.
+//   - Never issue an unrequested resume (Phase 3 D-05) -- these handlers
+//     send MEM_GET and nothing else. `runState` on the answer (via
+//     stockAnswer()) reports the halt honestly.
+//   - Never turn the MEM_GET body's side-effect flag on -- searching or
+//     comparing across $D000-$DFFF must never clear a pending VIC-II IRQ
+//     flag or otherwise mutate emulator state as a side effect of reading
+//     it. `sidefx` is hardcoded `false` at every call site below with no
+//     argument to override it.
+//   - Never build the answer outside stockAnswer() (D-06) -- that is
+//     exactly how an answer ships without `runState`.
+//   - Never re-derive address/byte-count parsing locally (D-04) --
+//     stock-address.ts's parseAddress()/parseByteCount() are the only seam.
+//   - Never implement `vice_memory_compare`'s `mode:'snapshot'` as a
+//     destructive snapshot restore or a `.vsf` parser (D-05-01) -- it is
+//     refused by name, before any MEM_GET is sent.
+//   - WR-06 (2026-08-17): never pass a LITERAL bank id to memGetBody() here
+//     again. All three MEM_GETs used to hardcode `bank: 0x0000`. Unlike the
+//     chip-state readers (which must refuse rather than default -- see
+//     stock-memory.ts's CR-01 note), the CPU view IS a defensible default for
+//     a general memory search; the defect was that it was INVISIBLE and
+//     UNCHANGEABLE. An agent could not search RAM under ROM or under I/O, and
+//     a search across $D000-$DFFF returned registers or the RAM underneath
+//     depending on the halted program's `$01` with the answer looking
+//     identical either way. Both tools now take the same optional `bank`
+//     argument vice_memory_read has (a stock-only OPTIONAL extra, which D-03
+//     permits and vice_memory_read's own `sideEffects` already precedents),
+//     resolve it through stock-memory.ts's ONE resolveBank() seam, and REPORT
+//     the view they actually read on the answer.
+import { CommandType, memGetBody } from "./stock-protocol.ts";
+import { parseAddress, parseByteCount } from "./stock-address.ts";
+import { resolveBank } from "./stock-memory.ts";
+import { convertWireError, isErrorText, stockAnswer, type StockSessionHandler, type StockErrorResult } from "./stock-handler.ts";
+
+/** True iff `value` is a well-formed, generic JSON object -- not null, not
+ * an array. Matches this module tree's own isPlainObject() convention
+ * (stock-memory.ts, stock-disassemble.ts et al.) -- a small private copy,
+ * not a shared import. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The fork's own documented `max_results`/`max_differences` bounds, quoted
+ * verbatim from its description: default 100, refused above 10000. */
+const DEFAULT_MAX_RESULTS = 100;
+const MAX_MAX_RESULTS = 10000;
+
+/** A hard ceiling on client-side scan cost, independent of the
+ * pattern-longer-than-range-searched refusal below. */
+const MAX_PATTERN_BYTES = 0x1000;
+
+/**
+ * Validates `input` as a non-empty array of integers 0..255, mirroring
+ * vice_memory_write's own `data` array validation loop verbatim in
+ * structure (stock-memory.ts). Used for both `pattern` and `mask`. Returns
+ * the validated `number[]` on success, or a ready-to-return
+ * `StockErrorResult` on failure -- callers `return`-propagate the error
+ * branch directly.
+ */
+function parseByteArray(toolName: string, what: string, input: unknown): number[] | StockErrorResult {
+  if (!Array.isArray(input)) {
+    return isErrorText(`${toolName}: ${what} must be a non-empty array of integers 0..255, got ${typeof input}`);
+  }
+  if (input.length === 0) {
+    return isErrorText(`${toolName}: ${what} must not be empty`);
+  }
+  const values: number[] = [];
+  for (let index = 0; index < input.length; index += 1) {
+    const value: unknown = input[index];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 0xff) {
+      return isErrorText(`${toolName}: ${what}[${index}] must be an integer 0..255, got ${JSON.stringify(value)}`);
+    }
+    values.push(value);
+  }
+  return values;
+}
+
+/** Narrows a `parseByteArray()` result to its error branch. */
+function isByteArrayError(result: number[] | StockErrorResult): result is StockErrorResult {
+  return !Array.isArray(result);
+}
+
+/**
+ * WR-06: the plain-language description of the memory VIEW an answer's bytes
+ * were read through, reported on every answer so a caller can audit it
+ * instead of inferring it. Rendered from the SAME resolution the MEM_GET body
+ * carried -- never from the raw argument, which may have been omitted.
+ */
+function bankViewFor(resolution: { id: number; name?: string }): string {
+  if (resolution.name !== undefined) {
+    return (
+      `read through the emulator's own "${resolution.name}" bank (wire id ${resolution.id}), as requested -- ` +
+      `not the CPU view, so $00/$01 banking does not affect these bytes`
+    );
+  }
+  return (
+    `read through wire bank ${resolution.id}, the CPU view (no bank argument was given) -- it follows $00/$01 ` +
+    `banking, so a range crossing $A000-$BFFF, $D000-$DFFF or $E000-$FFFF returns whatever the halted program ` +
+    `has banked in there right now. Pass bank:"ram" (or "io", "rom") to read a specific view instead; ` +
+    `vice_memory_banks lists the names this emulator reports.`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// vice_memory_search
+// ---------------------------------------------------------------------------
+
+export const handleMemorySearch: StockSessionHandler = async (args, session, _deps) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_memory_search: arguments must be an object");
+  }
+
+  // --------------------------------------------------------- start/end (both required)
+
+  let start: number, end: number;
+  try {
+    start = parseAddress(args.start, { what: "start" });
+    end = parseAddress(args.end, { what: "end" });
+  } catch (err) {
+    return isErrorText(`vice_memory_search: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (end < start) {
+    return isErrorText(`vice_memory_search: end (0x${end.toString(16)}) must be >= start (0x${start.toString(16)})`);
+  }
+
+  // --------------------------------------------------------- pattern (required)
+
+  const patternResult = parseByteArray("vice_memory_search", "pattern", args.pattern);
+  if (isByteArrayError(patternResult)) {
+    return patternResult;
+  }
+  const pattern = patternResult;
+
+  if (pattern.length > MAX_PATTERN_BYTES) {
+    return isErrorText(`vice_memory_search: pattern is ${pattern.length} byte(s), which exceeds the maximum of ${MAX_PATTERN_BYTES}`);
+  }
+  const searched = end - start + 1;
+  if (pattern.length > searched) {
+    return isErrorText(
+      `vice_memory_search: pattern is ${pattern.length} byte(s), longer than the ${searched} byte(s) searched (0x${start.toString(16)}-0x${end.toString(16)}) -- it can never match`,
+    );
+  }
+
+  // --------------------------------------------------------- mask (optional)
+
+  let mask: number[] | undefined;
+  if (args.mask !== undefined) {
+    const maskResult = parseByteArray("vice_memory_search", "mask", args.mask);
+    if (isByteArrayError(maskResult)) {
+      return maskResult;
+    }
+    mask = maskResult;
+    if (mask.length !== pattern.length) {
+      return isErrorText(
+        `vice_memory_search: mask is ${mask.length} byte(s) but pattern is ${pattern.length} byte(s) -- mask is never padded or truncated to fit, the lengths must match exactly`,
+      );
+    }
+  }
+
+  // --------------------------------------------------------- max_results (optional, default 100, max 10000)
+
+  let maxResults = DEFAULT_MAX_RESULTS;
+  if (args.max_results !== undefined) {
+    try {
+      maxResults = parseByteCount(args.max_results, { max: MAX_MAX_RESULTS, what: "max_results" });
+    } catch (err) {
+      return isErrorText(`vice_memory_search: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // --------------------------------------------------------- bank (optional, WR-06: defaults to the CPU view, but visibly and changeably)
+
+  const bankResolution = await resolveBank("vice_memory_search", args.bank, session);
+  if (!bankResolution.ok) {
+    return bankResolution.result;
+  }
+
+  // --------------------------------------------------------- bounded memory read (Phase 3 D-05: halts, never resumes)
+
+  const body = memGetBody({ sidefx: false, start, end, memspace: 0x00, bank: bankResolution.id });
+
+  let response;
+  try {
+    response = await session.client.send(CommandType.MemoryGet, body);
+  } catch (err) {
+    return convertWireError("vice_memory_search", err);
+  }
+
+  if (response.type !== "memory_get") {
+    return isErrorText(
+      `vice_memory_search: the binary monitor replied with an unexpected response type ("${response.type}"), expected "memory_get"`,
+    );
+  }
+  if (response.bytes.length !== searched) {
+    return isErrorText(
+      `vice_memory_search: expected ${searched} byte(s), got ${response.bytes.length} -- a short read is a wrong answer, not a partial success`,
+    );
+  }
+
+  // --------------------------------------------------------- client-side scan (overlapping matches, bounded)
+
+  const bytes = response.bytes;
+  const matches: number[] = [];
+  let truncated = false;
+  for (let offset = 0; offset <= bytes.length - pattern.length; offset += 1) {
+    let isMatch = true;
+    for (let index = 0; index < pattern.length; index += 1) {
+      const actual = bytes[offset + index]!;
+      if (mask !== undefined) {
+        const maskByte = mask[index]!;
+        if ((actual & maskByte) !== (pattern[index]! & maskByte)) {
+          isMatch = false;
+          break;
+        }
+      } else if (actual !== pattern[index]) {
+        isMatch = false;
+        break;
+      }
+    }
+    if (isMatch) {
+      matches.push(start + offset);
+      if (matches.length === maxResults) {
+        truncated = true;
+        break;
+      }
+    }
+  }
+
+  const payload: Record<string, unknown> = {
+    start,
+    end,
+    searched,
+    pattern,
+    ...(mask !== undefined ? { mask } : {}),
+    maxResults,
+    matches,
+    count: matches.length,
+    truncated,
+    // WR-06: the same shape vice_memory_read reports -- {id,name} when a name
+    // was resolved, the bare wire id otherwise -- plus a plain-language
+    // `bankView` so the answer says which view produced these bytes.
+    bank: bankResolution.name !== undefined ? { id: bankResolution.id, name: bankResolution.name } : bankResolution.id,
+    bankView: bankViewFor(bankResolution),
+  };
+
+  return stockAnswer(session.client, payload);
+};
+
+// ---------------------------------------------------------------------------
+// vice_memory_compare -- mode 'ranges' only. mode 'snapshot' is refused by
+// name (D-05-01): there is no memory-only snapshot producer tool on either
+// backend (vice_snapshot_save writes a whole-machine .vsf), so serving it
+// would mean either destructively restoring the machine to read memory out
+// of it, or parsing an unverified binary snapshot format. Neither is
+// implemented; the refusal fires before any MEM_GET is sent.
+// ---------------------------------------------------------------------------
+
+export const handleMemoryCompare: StockSessionHandler = async (args, session, _deps) => {
+  if (!isPlainObject(args)) {
+    return isErrorText("vice_memory_compare: arguments must be an object");
+  }
+
+  // --------------------------------------------------------- mode (required)
+
+  if (typeof args.mode !== "string") {
+    return isErrorText(`vice_memory_compare: mode must be a string, got ${typeof args.mode}`);
+  }
+
+  if (args.mode === "snapshot") {
+    return isErrorText(
+      "vice_memory_compare: mode:'snapshot' is not implemented on the stock backend -- there is no memory-only " +
+        "snapshot producer tool on either backend (vice_snapshot_save writes a whole-machine .vsf), so serving it " +
+        "would mean either destructively restoring the machine to read memory out of it, or parsing an unverified " +
+        "binary snapshot format. Use mode:'ranges' to compare two live ranges captured at different points in " +
+        "time, or use the c64-ram-capture skill's own full-image diff.",
+    );
+  }
+
+  if (args.mode !== "ranges") {
+    return isErrorText(`vice_memory_compare: mode must be "ranges" or "snapshot", got ${JSON.stringify(args.mode)}`);
+  }
+
+  // --------------------------------------------------------- range1_start/range1_end/range2_start (all required in mode:'ranges')
+
+  if (args.range1_start === undefined) {
+    return isErrorText("vice_memory_compare: range1_start is required when mode is 'ranges'");
+  }
+  if (args.range1_end === undefined) {
+    return isErrorText("vice_memory_compare: range1_end is required when mode is 'ranges'");
+  }
+  if (args.range2_start === undefined) {
+    return isErrorText("vice_memory_compare: range2_start is required when mode is 'ranges'");
+  }
+
+  let range1Start: number, range1End: number, range2Start: number;
+  try {
+    range1Start = parseAddress(args.range1_start, { what: "range1_start" });
+    range1End = parseAddress(args.range1_end, { what: "range1_end" });
+    range2Start = parseAddress(args.range2_start, { what: "range2_start" });
+  } catch (err) {
+    return isErrorText(`vice_memory_compare: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (range1End < range1Start) {
+    return isErrorText(
+      `vice_memory_compare: range1_end (0x${range1End.toString(16)}) must be >= range1_start (0x${range1Start.toString(16)})`,
+    );
+  }
+
+  // --------------------------------------------------------- range2_end is DERIVED from range1's length -- never accepted as an argument
+
+  const length = range1End - range1Start + 1;
+  const range2End = range2Start + length - 1;
+  if (range2End > 0xffff) {
+    return isErrorText(
+      `vice_memory_compare: range2_start (0x${range2Start.toString(16)}) + range1's length (${length}) would put range2_end at ` +
+        `0x${range2End.toString(16)}, which exceeds the 16-bit address space -- range 2 takes range 1's length, there is no range2_end argument`,
+    );
+  }
+
+  // --------------------------------------------------------- max_differences (optional, default 100, max 10000)
+
+  let maxDifferences = DEFAULT_MAX_RESULTS;
+  if (args.max_differences !== undefined) {
+    try {
+      maxDifferences = parseByteCount(args.max_differences, { max: MAX_MAX_RESULTS, what: "max_differences" });
+    } catch (err) {
+      return isErrorText(`vice_memory_compare: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // snapshot_name, start and end are declared on the manifest for D-03 input
+  // compatibility only (see plan_decision_D-05-01) -- they belong solely to
+  // the refused mode:'snapshot' path and are deliberately ignored here.
+
+  // --------------------------------------------------------- bank (optional, WR-06)
+  //
+  // ONE bank for BOTH ranges: the tool compares two ranges in one halted
+  // machine, so comparing them through two different views would be comparing
+  // two different questions. A caller who wants that reads twice.
+
+  const bankResolution = await resolveBank("vice_memory_compare", args.bank, session);
+  if (!bankResolution.ok) {
+    return bankResolution.result;
+  }
+
+  // --------------------------------------------------------- two sequential MEM_GET reads, both sidefx:false
+  //
+  // The machine is already halted by the first read (Phase 3 D-05), so the
+  // two reads are consistent with each other for a stopped machine; neither
+  // issues a resume between them.
+
+  const body1 = memGetBody({ sidefx: false, start: range1Start, end: range1End, memspace: 0x00, bank: bankResolution.id });
+  let response1;
+  try {
+    response1 = await session.client.send(CommandType.MemoryGet, body1);
+  } catch (err) {
+    return convertWireError("vice_memory_compare", err);
+  }
+  if (response1.type !== "memory_get") {
+    return isErrorText(
+      `vice_memory_compare: the binary monitor replied with an unexpected response type ("${response1.type}") for range 1, expected "memory_get"`,
+    );
+  }
+  if (response1.bytes.length !== length) {
+    return isErrorText(
+      `vice_memory_compare: expected ${length} byte(s) for range 1, got ${response1.bytes.length} -- a short read is a wrong answer, not a partial success`,
+    );
+  }
+
+  const body2 = memGetBody({ sidefx: false, start: range2Start, end: range2End, memspace: 0x00, bank: bankResolution.id });
+  let response2;
+  try {
+    response2 = await session.client.send(CommandType.MemoryGet, body2);
+  } catch (err) {
+    return convertWireError("vice_memory_compare", err);
+  }
+  if (response2.type !== "memory_get") {
+    return isErrorText(
+      `vice_memory_compare: the binary monitor replied with an unexpected response type ("${response2.type}") for range 2, expected "memory_get"`,
+    );
+  }
+  if (response2.bytes.length !== length) {
+    return isErrorText(
+      `vice_memory_compare: expected ${length} byte(s) for range 2, got ${response2.bytes.length} -- a short read is a wrong answer, not a partial success`,
+    );
+  }
+
+  // --------------------------------------------------------- diff, bounded at max_differences
+
+  const bytes1 = response1.bytes;
+  const bytes2 = response2.bytes;
+  const differences: { offset: number; address1: number; address2: number; value1: number; value2: number }[] = [];
+  let truncated = false;
+  for (let offset = 0; offset < length; offset += 1) {
+    const value1 = bytes1[offset]!;
+    const value2 = bytes2[offset]!;
+    if (value1 !== value2) {
+      differences.push({ offset, address1: range1Start + offset, address2: range2Start + offset, value1, value2 });
+      if (differences.length === maxDifferences) {
+        truncated = true;
+        break;
+      }
+    }
+  }
+
+  const payload: Record<string, unknown> = {
+    mode: "ranges",
+    range1Start,
+    range1End,
+    range2Start,
+    range2End,
+    length,
+    maxDifferences,
+    differences,
+    count: differences.length,
+    truncated,
+    identical: differences.length === 0 && !truncated,
+    // WR-06: one bank for both ranges, reported as vice_memory_read reports
+    // it, plus the plain-language view description.
+    bank: bankResolution.name !== undefined ? { id: bankResolution.id, name: bankResolution.name } : bankResolution.id,
+    bankView: bankViewFor(bankResolution),
+  };
+
+  return stockAnswer(session.client, payload);
+};