@henols/vice-mcp 0.1.11 → 0.2.0

package/backend-detect.mts

@@ -196,8 +196,33 @@ export interface BackendCacheRecord {
    * quad; only a live VICE_INFO reply over an established connection can. */
   versionQuad?: string;
   cpuHistoryAvailable?: boolean;
+  /** CR-01 (07-REVIEW.md re-review): the CLIENT-side schema version that
+   * produced `cpuHistoryAvailable`. The version quad answers "is this the
+   * same VICE build?"; it cannot answer "was the code that decided this
+   * capability the code running now?". Without this field a capability
+   * answer derived by a buggy parser was un-invalidatable by any code
+   * change -- only a VICE upgrade could clear it. A record whose value
+   * differs from CAPABILITY_SCHEMA_VERSION (including ABSENT, which is
+   * every record written before this field existed) reads back as `stale`.
+   * Bump CAPABILITY_SCHEMA_VERSION in the same commit as any change to how
+   * a capability is probed or decoded. */
+  capabilitySchema?: number;
 }
 
+/** The client-side capability-decision schema version stamped into every
+ * capability record this module writes (see BackendCacheRecord's own field
+ * comment). BUMP THIS whenever the client's capability probing or the
+ * decoding it depends on changes, so records decided by the older code are
+ * re-probed instead of trusted.
+ *
+ * History:
+ *   1 -- plan 02-08's original probe (implicit; never written to disk).
+ *   2 -- CR-01 fix: decode failures are no longer persisted at all, and the
+ *        CPUHISTORY_GET body layout was corrected (07-12). Every record
+ *        written before this constant existed lacks the field and is
+ *        therefore stale, which is exactly the intent. */
+export const CAPABILITY_SCHEMA_VERSION = 2;
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -243,6 +268,7 @@ function readCacheRecord(supervisorDir: string): BackendCacheRecord | null {
   };
   if (typeof parsed.versionQuad === "string") record.versionQuad = parsed.versionQuad;
   if (typeof parsed.cpuHistoryAvailable === "boolean") record.cpuHistoryAvailable = parsed.cpuHistoryAvailable;
+  if (typeof parsed.capabilitySchema === "number") record.capabilitySchema = parsed.capabilitySchema;
   return record;
 }
 
@@ -511,11 +537,23 @@ export function resolvedBackend(deps: ResolvedBackendDeps = {}): ResolvedBackend
 export interface CapabilityRecordResult {
   versionQuad?: string;
   cpuHistoryAvailable?: boolean;
-  /** True only when `observedVersionQuad` was given AND differs from the
-   * stored value -- the caller has just seen a DIFFERENT VICE build than
-   * whatever wrote this record (the binary was swapped since the last
-   * capability determination), so the stored answer cannot be trusted and
-   * must be re-determined rather than reused. */
+  /** The client-side schema version stamped on the record that was read
+   * (absent for any record written before CAPABILITY_SCHEMA_VERSION
+   * existed). Surfaced so a caller can log WHY a record was stale. */
+  capabilitySchema?: number;
+  /** True when the caller has just seen a DIFFERENT VICE build than
+   * whatever wrote this record (`observedVersionQuad` was given AND differs
+   * from the stored value -- the binary was swapped since the last
+   * capability determination), OR when the record's `capabilitySchema` is
+   * not the CAPABILITY_SCHEMA_VERSION this client decides capabilities
+   * with. Either way the stored answer cannot be trusted and must be
+   * re-determined rather than reused.
+   *
+   * CR-01 (07-REVIEW.md re-review) added the schema half: keying staleness
+   * on the version quad alone meant a capability answer decided by a buggy
+   * client parser survived every subsequent parser fix, and could only be
+   * cleared by upgrading VICE or hand-deleting a file under
+   * .vice-supervisor/ that nothing tells the user about. */
   stale: boolean;
 }
 
@@ -547,12 +585,20 @@ export function readCapabilityRecord(binPath: string, deps: CapabilityDeps = {})
   if (!existing || existing.resolvedPath !== resolvedPath) return null;
   if (existing.versionQuad === undefined && existing.cpuHistoryAvailable === undefined) return null;
 
-  const stale =
+  const versionMismatch =
     deps.observedVersionQuad !== undefined &&
     existing.versionQuad !== undefined &&
     existing.versionQuad !== deps.observedVersionQuad;
-
-  return { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+  // CR-01: a record decided by a different client-side capability schema is
+  // as untrustworthy as one decided against a different binary. Absent
+  // counts as a mismatch -- that is every record written before the field
+  // existed, i.e. every record a possibly-broken parser could have written.
+  const schemaMismatch = existing.capabilitySchema !== CAPABILITY_SCHEMA_VERSION;
+  const stale = versionMismatch || schemaMismatch;
+
+  const result: CapabilityRecordResult = { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+  if (existing.capabilitySchema !== undefined) result.capabilitySchema = existing.capabilitySchema;
+  return result;
 }
 
 /** Attaches `{ versionQuad, cpuHistoryAvailable }` to the EXISTING backend
@@ -591,5 +637,9 @@ export function writeCapabilityRecord(
     probedAt: existing.probedAt,
     versionQuad: capability.versionQuad,
     cpuHistoryAvailable: capability.cpuHistoryAvailable,
+    // CR-01: stamp WHICH client decided this, so a later parser change
+    // invalidates it. Never accept this from the caller -- it describes this
+    // module's own code, not anything the caller observed.
+    capabilitySchema: CAPABILITY_SCHEMA_VERSION,
   });
 }

package/capability-registry.ts

@@ -0,0 +1,388 @@
+// capability-registry.ts
+//
+// WHY THIS FILE EXISTS (BACK-05): today, a tool name the ACTIVE backend does
+// not advertise falls straight through vice-proxy.ts's CallToolRequestSchema
+// override to its generic `Unknown tool: ${name}` fallback -- the exact same
+// message a genuine typo gets. That is indistinguishable and unhelpful: a
+// caller cannot tell "you misspelled this" from "this tool exists, but only
+// on the other backend, for this specific reason." This module is the ONE
+// authoritative place holding that per-backend capability data -- names,
+// reason categories, reason text, and which backend actually provides each
+// one -- so a future call site (the runtime refusal wired in plan 08-02, the
+// generated support table in plan 08-03, the skill-text lint in plan 08-04)
+// reads exactly one source rather than re-deriving or hand-copying it.
+//
+// WHAT NOT TO DO: do not hand-maintain a second copy of this data anywhere
+// else in the repo (D-E; see CLAUDE.md's "re-deriving a cross-cutting seam
+// locally" anti-pattern). If a consumer needs this data in a different
+// shape, import CAPABILITY_REGISTRY and reshape it there -- never re-type
+// the 26 entries or their reasons from memory.
+//
+// SECURITY POSTURE: this module is a READ-ONLY MESSAGE-TEXT LOOKUP and is
+// NEVER an authorization boundary. DENY_LIST (vice.ts) remains the only
+// refusal in this tree that is a security control; that check runs first, at
+// every call site, and this module never overrides or duplicates it. Every
+// string held here is already public: it names only information already
+// published in docs/stock-vice-parity.md and this public repository -- no
+// credential, no secret, no host, no port, no path, and no tool name that is
+// not already present in one of the two shipped manifests
+// (tools-manifest.json, tools-manifest.stock.json).
+//
+// This is the exact shape vice.ts's DENY_LIST / denyListRefusalMessage()
+// already established: one exported readonly array, one exported
+// message-rendering function, keyed by hazard/reason shape rather than one
+// wording reused for every entry -- because telling a caller the wrong
+// reason shape for what is otherwise the same permanent refusal invites a
+// pointless retry (that function's own doc comment makes the identical
+// point).
+//
+// EXCLUDED, DELIBERATELY (see docs/stock-vice-parity.md and
+// 08-RESEARCH.md's "Capability Delta Registry"):
+//   - "vice_diagnose" and "vice_recycle" are NOT capability gaps: they are
+//     synthetic, proxy-local tools registered on BOTH backends by
+//     vice-proxy.ts's buildBackendAwareTool()/resolveAdvertisedToolDefinition()
+//     synthetic-registration call sites, never listed in either raw manifest
+//     JSON file. A naive set-difference over the two manifests misclassifies
+//     them as a divergence; they are not one, and including them here would
+//     be a factual error, not merely an omission.
+//   - "initialize", "notifications_initialized", "tools_call", "tools_list"
+//     are already refused by vice.ts's DENY_LIST, which runs strictly BEFORE
+//     any capability-registry lookup and owns a different hazard shape
+//     entirely (confused-deputy bypass, not a missing capability). They must
+//     keep being owned there, not duplicated here.
+//
+// This module imports nothing at runtime -- the only import is a type-only
+// import of ViceBackend, which is erased by Node's type-stripping -- so it
+// has no transport, no filesystem, and no process dependency of its own.
+import type { ViceBackend } from "./backend-detect.mts";
+
+/**
+ * Three reason categories, matching the distinctions the project's own docs
+ * already draw (docs/stock-vice-parity.md SS A/B):
+ *   - "hardware": no 1:1 opcode can ever exist because of a hardware or
+ *     firmware property (a write-only register, per-read recomputation, no
+ *     monitor command for a physical line). Permanent; nothing to build.
+ *   - "descoped": theoretically buildable client-side (an opcode or
+ *     equivalent already exists) but cut from v0.2.0 scope because no
+ *     shipped skill calls it.
+ *   - "stock-only-gain": the reverse direction -- stock has a native opcode
+ *     the fork's custom HTTP API never exposed an equivalent RPC for.
+ */
+export type CapabilityCategory = "hardware" | "descoped" | "stock-only-gain";
+
+/**
+ * One row of capability data. `providedBy` names the backend that DOES have
+ * the capability (never the backend refusing it). `reason` is one sentence
+ * of user-facing prose ending in a full stop -- no planning identifier
+ * (BACK-05, SKILL-01, DERIV-*, SHOT-*, GAIN-*, "Phase N") belongs in this
+ * field; those are internal routing annotations, not something a caller
+ * calling a tool by name should ever see. `alternative`, when present, names
+ * a concrete route that exists on the OTHER backend today -- omit it rather
+ * than inventing one where none exists.
+ */
+export interface CapabilityEntry {
+  name: string;
+  category: CapabilityCategory;
+  providedBy: ViceBackend;
+  reason: string;
+  alternative?: string;
+}
+
+const KEYBOARD_ALTERNATIVE =
+  "vice_keyboard_type / vice_keyboard_petscii inject text through the KERNAL keyboard buffer, " +
+  "and vice_joystick_set covers most in-game input -- but a program polling $DC00/$DC01 directly " +
+  "will not see buffer injection.";
+
+/**
+ * The 26-entry capability delta: every tool one backend advertises that the
+ * other genuinely does not, after excluding registration artifacts
+ * (vice_diagnose/vice_recycle) and DENY_LIST's own four meta-tools -- see
+ * the header comment above and 08-RESEARCH.md's "Capability Delta Registry"
+ * for the full accounting this array is derived from.
+ */
+export const CAPABILITY_REGISTRY: readonly CapabilityEntry[] = [
+  // --- hardware (6), providedBy: fork -------------------------------------
+  {
+    name: "vice_sid_get_state",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "SID's $D400-$D418 registers are write-only in hardware, and the binary monitor exposes " +
+      "no SID read command.",
+  },
+  {
+    name: "vice_keyboard_matrix",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "The binary monitor's KEYBOARD_FEED (0x72) only injects PETSCII buffer text; the emulator " +
+      "recomputes CIA port B from its own keyboard array on every read, so there is no wire " +
+      "command that can drive the raw matrix.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_restore",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "RESTORE pulses the NMI line directly; it is not part of the keyboard matrix, and " +
+      "KEYBOARD_FEED has no way to produce it.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_chord",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED injects a whole string at a time; it has no primitive for holding multiple " +
+      "keys down together for a span of frames.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_key_press",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
+      "individual key-down event.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+  {
+    name: "vice_keyboard_key_release",
+    category: "hardware",
+    providedBy: "fork",
+    reason:
+      "KEYBOARD_FEED has no hold/release primitive -- it injects a complete string, not an " +
+      "individual key-up event.",
+    alternative: KEYBOARD_ALTERNATIVE,
+  },
+
+  // --- descoped (18), providedBy: fork -------------------------------------
+  {
+    name: "vice_disk_detach",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "No detach opcode exists on the stock binary monitor; attaching a different disk image " +
+      "covers the same workflow.",
+  },
+  {
+    name: "vice_disk_read_sector",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Reading a sector would require parsing the .d64 file client-side rather than calling a " +
+      "live-drive opcode, and no shipped skill calls it.",
+  },
+  {
+    name: "vice_display_screenshot",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The client-side PNG encoder for the INDEXED8 framebuffer DISPLAY_GET returns was descoped " +
+      "because no shipped skill calls it.",
+  },
+  {
+    name: "vice_display_get_dimensions",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "Descoped alongside vice_display_screenshot -- no shipped skill calls it.",
+  },
+  {
+    name: "vice_backtrace",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls it.",
+  },
+  {
+    name: "vice_checkpoint_group_add",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_create",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_list",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_group_toggle",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls any checkpoint-group tool.",
+  },
+  {
+    name: "vice_checkpoint_set_ignore_count",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "No native wire ignore-count exists; the only implementation would require resuming the " +
+      "machine on every ignored hit, which the no-unrequested-resume policy forbids. " +
+      "CHECKPOINT_INFO's reply still reports an existing ignore count read-only.",
+  },
+  {
+    name: "vice_cia_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_vicii_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_sprite_set",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "The write half of a tool whose read half already ships on stock; no shipped skill calls " +
+      "the write half.",
+  },
+  {
+    name: "vice_memory_fill",
+    category: "descoped",
+    providedBy: "fork",
+    reason: "No shipped skill calls it.",
+  },
+  {
+    name: "vice_sid_set_state",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "SID writes work fine over MEM_SET at $D400-$D418 -- this is not a hardware loss, only " +
+      "reads are write-only in hardware. It is simply not implemented because no shipped skill " +
+      "calls it.",
+  },
+  {
+    name: "vice_machine_config_get",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
+      "subset that never shipped on stock.",
+  },
+  {
+    name: "vice_machine_config_set",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Full resource get/set access was descoped; the fork's tool is a hand-curated whitelist " +
+      "subset that never shipped on stock.",
+  },
+  {
+    name: "vice_joystick_tap",
+    category: "descoped",
+    providedBy: "fork",
+    reason:
+      "Requires running the machine for a measured hold-then-release interval, which depends on " +
+      "timing infrastructure; not yet built, and no shipped skill calls it.",
+  },
+
+  // --- stock-only-gain (2), providedBy: stock ------------------------------
+  {
+    name: "vice_execution_until_return",
+    category: "stock-only-gain",
+    providedBy: "stock",
+    reason: "The fork's custom HTTP API has no equivalent RPC; this is the native EXECUTE_UNTIL_RETURN opcode.",
+  },
+  {
+    name: "vice_registers_available",
+    category: "stock-only-gain",
+    providedBy: "stock",
+    reason: "The fork has no equivalent enumeration call; this is the native REGISTERS_AVAILABLE opcode.",
+  },
+];
+
+/**
+ * Plain name-keyed lookup over CAPABILITY_REGISTRY. `name` is untrusted
+ * `request.params.name` from the wire: it is used ONLY as an equality
+ * comparison value below. Never interpolate it into a path, a command, or
+ * anything executed.
+ */
+export function capabilityEntryFor(name: string): CapabilityEntry | undefined {
+  return CAPABILITY_REGISTRY.find((entry) => entry.name === name);
+}
+
+/**
+ * Renders the BACK-05 refusal for `name` on `activeBackend`, or `undefined`
+ * when there is nothing to refuse -- mirroring denyListRefusalMessage()'s
+ * keyed-by-hazard-shape contract (vice.ts).
+ *
+ * Returns `undefined` when:
+ *   - no registry entry exists for `name` (a genuinely unknown tool name --
+ *     a typo -- must still fall through to the generic "Unknown tool"
+ *     message at the call site, not this function's wording); or
+ *   - `entry.providedBy === activeBackend` (defensive: the active backend
+ *     already advertises this tool, so a miss here is a genuine
+ *     unknown-tool case, not a capability gap, and must not be
+ *     misclassified as one).
+ *
+ * Otherwise renders one of three wordings, selected by `entry.category`:
+ *   - "hardware": names the tool, states it is unrecoverable on
+ *     `activeBackend`, gives `entry.reason`, then names `entry.providedBy`
+ *     with the actionable `Set VICE_BACKEND=...`, then `entry.alternative`
+ *     when present. No "wait for a later phase" framing -- none is coming
+ *     for a hardware loss, but a stock route may still exist and must be
+ *     named here, since this is where the caller actually reads it.
+ *   - "descoped": names the tool, states it is not implemented on
+ *     `activeBackend`, gives `entry.reason`, then `entry.providedBy` and
+ *     `Set VICE_BACKEND=...`, then `entry.alternative` when present. The
+ *     literal token "unrecoverable" must NEVER appear in this wording: a
+ *     reader told "not supported" for both a hardware loss and a merely
+ *     unbuilt tool cannot tell which one is worth filing an issue about.
+ *   - "stock-only-gain": names the tool, states it is not implemented on the
+ *     fork backend specifically, gives `entry.reason`, then
+ *     `Set VICE_BACKEND=stock`.
+ */
+export function capabilityRefusalMessage(
+  name: string,
+  activeBackend: ViceBackend,
+): string | undefined {
+  const entry = capabilityEntryFor(name);
+  if (!entry) return undefined;
+  if (entry.providedBy === activeBackend) return undefined;
+
+  // `alternative` is rendered in EVERY branch that has one. It used to be
+  // read only inside the "descoped" branch, which made the field dead at
+  // runtime: all five entries that carry an alternative are category
+  // "hardware", and no "descoped" entry has one. The generated support
+  // table, the skill playbooks and README all printed the stock route while
+  // the runtime refusal -- the one surface BACK-05 exists for -- dropped it.
+  // Do not re-scope this back into a single branch.
+  const alt = entry.alternative ? ` ${entry.alternative}` : "";
+
+  if (entry.category === "hardware") {
+    return (
+      `${entry.name} is unrecoverable on the ${activeBackend} backend: ${entry.reason} ` +
+      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
+    );
+  }
+
+  if (entry.category === "descoped") {
+    return (
+      `${entry.name} is not implemented on the ${activeBackend} backend: ${entry.reason} ` +
+      `Use the ${entry.providedBy} backend instead (Set VICE_BACKEND=${entry.providedBy}).${alt}`
+    );
+  }
+
+  // category === "stock-only-gain": only reachable with activeBackend ===
+  // "fork" and entry.providedBy === "stock", since the same-backend guard
+  // above already excluded the activeBackend === "stock" case.
+  return (
+    `${entry.name} is not implemented on the fork backend: ${entry.reason} ` +
+    `Use the stock backend instead (Set VICE_BACKEND=stock).${alt}`
+  );
+}

package/disasm-decoder.ts

@@ -5,7 +5,10 @@
 // CPU-history decode (GAIN-01) import THIS file directly, never a tool
 // module, so a protocol import here would force those consumers to pull in
 // transport code they do not need. This module has no emulator, no
-// protocol, no network -- its only input is a byte array.
+// protocol, no network -- its only input is a byte array. Note: DERIV-02 and
+// GAIN-01 were both cut from v0.2.0 scope on 2026-08-17 -- see the
+// startAddress bound below, which is now defense-in-depth on a currently
+// unreachable path rather than a guard against a live in-process caller.
 //
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS RATHER THAN LIVING INSIDE THE TOOL HANDLER
@@ -30,6 +33,13 @@
 //   - Never add recursion or an unbounded loop -- the bound is what makes an
 //     attacker-controlled memory image safe to decode (04-RESEARCH.md
 //     Security Domain, T-04-03-01).
+//   - Never fold the `<= 0xffff` upper bound into `isNonNegativeSafeInteger()`
+//     or apply it to `opts.count`/`opts.end` -- those two stay unbounded by
+//     design (04-REVIEW.md IN-03: the loop is always bounded by
+//     `bytes.length`, so an absurd value degrades to "no effective limit",
+//     never a crash or hang). Bounding them would be a behaviour change
+//     dressed up as a consistency fix. The upper bound belongs only in the
+//     separate `isValidStartAddress()` guard below.
 
 import { OPCODES, type AddressingMode } from "./disasm-opcodes.ts";
 
@@ -94,6 +104,18 @@ function isNonNegativeSafeInteger(value: unknown): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
 
+/** True iff `value` is a valid `startAddress` -- a safe, non-negative integer
+ * that additionally fits in the C64's 16-bit address space (`<= 0xffff`).
+ * Deliberately separate from `isNonNegativeSafeInteger()` rather than an
+ * upper bound folded into it: `opts.count`/`opts.end` must stay unbounded
+ * (see the `WHAT NOT TO DO` block above and 04-REVIEW.md IN-03), so only
+ * `startAddress` gets this stricter narrowing. Mirrors `stock-address.ts`'s
+ * `inAddressRange()` without importing it -- D-05 keeps this module's only
+ * import to `./disasm-opcodes.ts`. */
+function isValidStartAddress(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= 0xffff;
+}
+
 /** Interprets `b` as an 8-bit two's-complement signed byte, per DISASM-04's
  * branch resolution rule: `signed8(b) = b < 0x80 ? b : b - 0x100`. */
 function signed8(b: number): number {
@@ -118,12 +140,14 @@ function buildNotes(flags: { truncated: boolean; pageWrap: boolean; illegal: boo
  * `startAddress`. Bounded by construction (T-04-03-01): a single `while`
  * loop over a byte cursor, every iteration consumes at least one byte, no
  * recursion anywhere in this file. Never throws -- malformed input (a
- * non-`Uint8Array` `bytes`, a negative or non-integer `startAddress`)
- * returns `[]`.
+ * non-`Uint8Array` `bytes`, a negative or non-integer `startAddress`, or a
+ * `startAddress` above `0xffff`, the top of the 16-bit address space)
+ * returns `[]` rather than wrapping the address into range and returning a
+ * plausible-looking but wrong listing.
  */
 export function decode(bytes: Uint8Array, startAddress: number, opts: DecodeOptions = {}): Instruction[] {
   if (!(bytes instanceof Uint8Array)) return [];
-  if (!isNonNegativeSafeInteger(startAddress)) return [];
+  if (!isValidStartAddress(startAddress)) return [];
 
   const options = isPlainObject(opts) ? opts : {};
   const count = isNonNegativeSafeInteger(options.count) ? options.count : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/vice-mcp",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "VICE emulator MCP server for C64 reverse-engineering: a stdio MCP server that proxies vice tools to a host VICE MCP server.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "vice-sync.ts",
     "vice-probe.ts",
     "vice-broker-client.ts",
+    "version.ts",
     "stock-protocol.ts",
     "stock-connect.ts",
     "containerpath.ts",
@@ -24,6 +25,7 @@
     "build.ts",
     "container-guard.mts",
     "backend-detect.mts",
+    "capability-registry.ts",
     "stock-dispatch.ts",
     "stock-derived.ts",
     "stock-handler.ts",
@@ -42,6 +44,15 @@
     "disasm-opcodes.ts",
     "disasm-decoder.ts",
     "disasm-renderer.ts",
+    "stock-memory-search.ts",
+    "stock-symbols.ts",
+    "stock-vicii.ts",
+    "stock-cia.ts",
+    "stock-sprites.ts",
+    "stock-timing.ts",
+    "stock-run-until.ts",
+    "stock-diagnose.ts",
+    "stock-recycle.ts",
     "resources",
     "tools-manifest.json",
     "tools-manifest.stock.json",

package/resources/backend-detect.mjs

@@ -122,6 +122,19 @@ export function probeBackend(binPath, deps = {}) {
     }
     return classifyHelpOutput(text);
 }
+/** The client-side capability-decision schema version stamped into every
+ * capability record this module writes (see BackendCacheRecord's own field
+ * comment). BUMP THIS whenever the client's capability probing or the
+ * decoding it depends on changes, so records decided by the older code are
+ * re-probed instead of trusted.
+ *
+ * History:
+ *   1 -- plan 02-08's original probe (implicit; never written to disk).
+ *   2 -- CR-01 fix: decode failures are no longer persisted at all, and the
+ *        CPUHISTORY_GET body layout was corrected (07-12). Every record
+ *        written before this constant existed lacks the field and is
+ *        therefore stale, which is exactly the intent. */
+export const CAPABILITY_SCHEMA_VERSION = 2;
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -168,6 +181,8 @@ function readCacheRecord(supervisorDir) {
         record.versionQuad = parsed.versionQuad;
     if (typeof parsed.cpuHistoryAvailable === "boolean")
         record.cpuHistoryAvailable = parsed.cpuHistoryAvailable;
+    if (typeof parsed.capabilitySchema === "number")
+        record.capabilitySchema = parsed.capabilitySchema;
     return record;
 }
 /** Tmp-sibling -> chmod 0600 -> content -> rename, the SAME atomic-write
@@ -354,10 +369,19 @@ export function readCapabilityRecord(binPath, deps = {}) {
         return null;
     if (existing.versionQuad === undefined && existing.cpuHistoryAvailable === undefined)
         return null;
-    const stale = deps.observedVersionQuad !== undefined &&
+    const versionMismatch = deps.observedVersionQuad !== undefined &&
         existing.versionQuad !== undefined &&
         existing.versionQuad !== deps.observedVersionQuad;
-    return { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+    // CR-01: a record decided by a different client-side capability schema is
+    // as untrustworthy as one decided against a different binary. Absent
+    // counts as a mismatch -- that is every record written before the field
+    // existed, i.e. every record a possibly-broken parser could have written.
+    const schemaMismatch = existing.capabilitySchema !== CAPABILITY_SCHEMA_VERSION;
+    const stale = versionMismatch || schemaMismatch;
+    const result = { versionQuad: existing.versionQuad, cpuHistoryAvailable: existing.cpuHistoryAvailable, stale };
+    if (existing.capabilitySchema !== undefined)
+        result.capabilitySchema = existing.capabilitySchema;
+    return result;
 }
 /** Attaches `{ versionQuad, cpuHistoryAvailable }` to the EXISTING backend
  * verdict already on record for `binPath`'s resolved identity -- a no-op,
@@ -392,5 +416,9 @@ export function writeCapabilityRecord(binPath, capability, deps = {}) {
         probedAt: existing.probedAt,
         versionQuad: capability.versionQuad,
         cpuHistoryAvailable: capability.cpuHistoryAvailable,
+        // CR-01: stamp WHICH client decided this, so a later parser change
+        // invalidates it. Never accept this from the caller -- it describes this
+        // module's own code, not anything the caller observed.
+        capabilitySchema: CAPABILITY_SCHEMA_VERSION,
     });
 }