@henols/vice-mcp 0.2.1 → 0.2.2

package/stock-address.ts

@@ -23,8 +23,8 @@
 //     hex by default" rule belongs to the checkpoint-condition emitter, not
 //     this parser. Do not conflate the two.
 //   - Never implement symbol resolution in Phase 3. setSymbolResolver() is
-//     a deliberately empty extension point until Phase 5's DERIV-04 symbol
-//     store installs a real one; the default here stays `null`.
+//     the one extension point for it: it starts `null` and stays that way
+//     until stock-symbols.ts's `vice_symbols_load` installs a real resolver.
 //   - Never add a second resolver holder. `nameFor` (address -> name,
 //     DISASM-06's first consumer, Phase 4) and `resolve` (name -> address,
 //     Phase 3) live on the SAME `SymbolResolver` object, read from the SAME
@@ -46,9 +46,9 @@ export interface SymbolResolver {
 // -- no symbol resolution happens until a later phase installs one.
 let symbolResolver: SymbolResolver | null = null;
 
-/** The deliberately-empty extension point Phase 5's DERIV-04 symbol store
- * fills. Passing `null` (the Phase 3 default) restores the "no symbol table
- * loaded" refusal. */
+/** The extension point stock-symbols.ts's `vice_symbols_load` fills at
+ * runtime. Passing `null` (the default before any load) restores the "no
+ * symbol table loaded" refusal. */
 export function setSymbolResolver(resolver: SymbolResolver | null): void {
   symbolResolver = resolver;
 }

package/stock-cia.ts

@@ -23,7 +23,7 @@
 // field naming the sharing address.
 //
 // Bit-field names below were transcribed ONCE from
-// `.claude/skills/c64-memory-mapping/memmap.json`'s entries for $DC00,
+// `src/skills/c64-memory-mapping/memmap.json`'s entries for $DC00,
 // $DC01, $DC02, $DC03, $DC08-$DC0F, $DD00, $DD01 and $DD0D, and
 // cross-checked at write time -- the same "committed literal, cross-checked
 // once, no automated drift check" posture Phase 4's D-06 already accepted
@@ -36,7 +36,7 @@
 //   - This is NOT a keyboard-matrix read. $DC00/$DC01 expose only the
 //     current column selection and row result; the full matrix is
 //     `vice_keyboard_matrix`, which is provably unrecoverable on stock
-//     (`docs/stock-vice-parity.md` SS A item 2) and is Phase 8's business.
+//     (`docs/stock-vice-parity.md` SS A item 2) -- the wire protocol has no matrix command, and `KEYBOARD_FEED` (0x72) injects buffer text only.
 //   - WR-02 (2026-08-17): the port A/B joystick bits share their PINS with
 //     the keyboard matrix's column-select ($DC00) and row-read ($DC01), and
 //     a stock read halts the machine at an arbitrary PC -- often inside the

package/stock-condition.ts

@@ -35,10 +35,10 @@
 //     last gate before the wire and re-validates every literal and every
 //     kind itself, even though parseConditionString() and conditionFromJson()
 //     also validate on the way in.
-//   - Phase 6's GAIN-06 extends this AST with raster semantics (finer-grained
-//     raster/cycle conditions) rather than replacing it or adding a second,
-//     parallel condition-building path. Any future raster work grows this
-//     module's types, it does not fork them.
+//   - GAIN-06's raster-semantics extension (finer-grained raster/cycle
+//     conditions) was cut with the whole of Stock-Only Gains, 2026-08-17
+//     (see docs/stock-vice-parity.md's dated cut record). Widening this AST
+//     is unclaimed scope with no owner -- grow these types, never fork them.
 //
 // This module has no handlers and no dispatch entries -- a later plan
 // consumes emitCondition()'s output as the only thing a condition-set
@@ -545,9 +545,9 @@ function parseSingleComparison(text: string, originalExpr: string): ConditionNod
  * conditionFromJson() produces and returns it; it never emits text itself,
  * so emitCondition() remains the only producer of wire text.
  *
- * Accepted input, deliberately narrow (widening this grammar is Phase 6's
- * GAIN-06 decision, not a maintenance liberty -- do not implement a general
- * expression parser):
+ * Accepted input, deliberately narrow (GAIN-06's plan to widen this grammar
+ * was cut along with Stock-Only Gains, 2026-08-17; widening it is unclaimed
+ * scope with no owner -- do not implement a general expression parser):
  *   - a single comparison, with or without surrounding parentheses:
  *     "A == $42", "(PC == $c000)", "SP <= $ff", "RL == $64"
  *   - a conjunction/disjunction where EVERY comparison is individually

package/stock-connect.ts

@@ -534,7 +534,7 @@ export async function stockReconnect(session: StockConnectSession, { lastToolCal
 
   if (baselineEpoch === null || currentEpoch === null || currentEpoch !== baselineEpoch) {
     throw new MachineRestartedError(
-      `stockConnect: reconnect to target ${session.targetId} could not prove machine identity across the reconnect ` +
+      `stockReconnect: reconnect to target ${session.targetId} could not prove machine identity across the reconnect ` +
         `(baseline epoch ${String(baselineEpoch)}, current epoch ${String(currentEpoch)})`,
       { baselineEpoch, currentEpoch, where: "stock-connect.ts:stockReconnect", lastToolCall },
     );

package/stock-dispatch.ts

@@ -28,6 +28,7 @@ import { resolve, join } from "node:path";
 
 import type { ViceBackend } from "./backend-detect.mts";
 import type { ToolInfo } from "./vice.ts";
+import { capabilityRefusalMessage } from "./capability-registry.ts";
 import { type HeldLease } from "./vice-broker-client.ts";
 import { stockConnect, stockDisconnect, stockReconnect, type StockConnectSession, type StockConnectDeps } from "./stock-connect.ts";
 import {
@@ -591,7 +592,22 @@ export function withDerivedTool(
  * comment on why). Built through stockAnswer() so the answer now also
  * carries `runState` (D-06: every stock answer, and `vice_ping` is a stock
  * answer) alongside every field that was already there.
+ *
+ * 2026-08-19 finding (closed Phase 15 plan 15-09): `resolvedBinaryPath` is a
+ * ONE-TIME, MCP-server-process-startup `$PATH` probe (see vice-proxy.ts's
+ * `ACTIVE_BACKEND` comment) -- it is independent of which binary the broker
+ * actually leased for THIS request. `resolvedBinaryPathScope` below is an
+ * additive, backward-compatible sibling field (the existing field name and
+ * shape are unchanged) that carries that qualification into the answer
+ * itself, so a caller reading the response -- not just this source comment --
+ * learns not to treat the path as this request's authoritative binary
+ * identity.
  */
+const RESOLVED_BINARY_PATH_SCOPE =
+  "one-time MCP-server-process-startup PATH probe; NOT the binary the broker leased for this " +
+  "request -- for the authoritative per-instance binary, read the broker's own launch record " +
+  "(epoch.json's vice_bin field)";
+
 const handlePing: StockSessionHandler = async (_args, session, deps) => {
   return stockAnswer(session.client, {
     status: "ok",
@@ -602,6 +618,9 @@ const handlePing: StockSessionHandler = async (_args, session, deps) => {
     // it, an agent reading `"x64sc"` cannot tell "this is where the binary is"
     // from "this is what we were told to look for, and we could not find it".
     resolvedBinaryPathIsResolved: deps.resolvedBinaryPathIsResolved ?? false,
+    // 2026-08-19 finding: names what resolvedBinaryPath actually is (a
+    // startup-time probe) and where to look instead for a per-request answer.
+    resolvedBinaryPathScope: RESOLVED_BINARY_PATH_SCOPE,
     capabilities: session.capabilities,
   });
 };
@@ -611,11 +630,11 @@ const handlePing: StockSessionHandler = async (_args, session, deps) => {
  * not an oversight (Task 2, plan 03-12):
  *   - `vice_checkpoint_set_ignore_count` (D-15)
  *   - `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_detach` (CUT from scope 2026-08-17 -- docs/stock-vice-parity.md's dated cut record)
+ *   - `vice_joystick_tap` (permanently excluded -- stock-input.ts's own header)
  *   - `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)
+ *   - `vice_machine_config_get` / `vice_machine_config_set` (CUT from scope 2026-08-17 along with the whole of Stock-Only Gains -- docs/stock-vice-parity.md's dated cut record)
  * `dispatchStock()`'s miss branch already refuses any of these by name,
  * without reading `deps` -- there is nothing else to add for them here.
  */
@@ -732,9 +751,20 @@ export function stockHandlerFor(name: string): StockHandler | undefined {
 export async function dispatchStock(name: string, args: Record<string, unknown>, deps: StockDispatchDeps): Promise<StockToolResult> {
   const handler = stockHandlerFor(name);
   if (!handler) {
+    // WR-13: route through capability-registry.ts's ONE authoritative
+    // refusal renderer rather than a second, locally-composed wording --
+    // that renderer knows which backend ACTUALLY provides each name
+    // (avoiding the false "the fork backend provides this tool" claim for a
+    // stock-only-gain name) and never uses "wait for a later phase" framing
+    // for a hardware loss. Fall back to an internal-inconsistency message
+    // ONLY when the registry has no entry at all for `name` -- meaning the
+    // tool is advertised on the stock manifest (so it reached this branch)
+    // but stockHandlerFor() has no dispatch entry AND capability-registry.ts
+    // has no divergence entry either: a bug to report, not a capability gap.
     return isErrorText(
-      `${name} is not implemented by the stock backend -- the fork backend provides this tool. ` +
-        `Set VICE_BACKEND=fork to use it there, or wait for a later phase to extend the stock dispatch table.`,
+      capabilityRefusalMessage(name, "stock") ??
+        `${name} is advertised on the stock backend's manifest but has no handler in the stock ` +
+          `dispatch table -- this is an internal inconsistency, not a capability gap; please file an issue.`,
     );
   }
   return handler(args, deps);

package/stock-execution.ts

@@ -224,9 +224,11 @@ export const handleExecutionRun: StockSessionHandler = async (args, session) =>
  * the derived run state is "unknown" (D-07, via refuseIfUnknown()).
  *
  * `stepOver: true`'s runtime semantic (skip a JSR's subroutine as one step)
- * is [ASSUMED] -- RESEARCH.md Assumptions Log row A2 -- never probed against
- * a real JSR. See `.planning/todos/pending/2026-08-14-probe-phase3-assumed-wire-details.md`
- * for the outstanding probe debt. This is NOT claimed as verified here.
+ * was live-probed against a real JSR on fork VICE 3.10 and CONFIRMED
+ * (RESEARCH.md Assumptions Log row A2, closed by 13-PROBE-RESULTS.md §A2):
+ * the post-step PC landed at JSR+3, matching a full subroutine skip, and
+ * the result was reproduced identically across two independent live
+ * sessions.
  */
 export const handleExecutionStep: StockSessionHandler = async (args, session) => {
   const unexpected = refuseUnexpectedArgs(args, ["count", "stepOver"], "vice_execution_step");

package/stock-input.ts

@@ -25,10 +25,10 @@
 //     resumes explicitly, on its own schedule.
 //   - Never add vice_joystick_tap. A tap needs the machine to RUN for a
 //     measured interval -- an unrequested EXIT (forbidden by D-05) plus a
-//     frame/cycle measurement that does not exist on stock until Phase 7's
-//     timing route lands (docs/stock-vice-parity.md section A item 7).
-//     vice_joystick_set (hold/release/centre) satisfies DIRECT-07's
-//     joystick half in the meantime.
+//     frame/cycle measurement stock's wire protocol has no route for at
+//     all (docs/stock-vice-parity.md section A item 7). This exclusion is
+//     permanent, not pending: vice_joystick_set (hold/release/centre)
+//     satisfies DIRECT-07's joystick half instead.
 //   - Never construct an ok-answer outside stockAnswer(). Every successful
 //     result below is built through it, never a bare
 //     `{ content: [...], isError: false }` literal.
@@ -187,11 +187,11 @@ function isValidDirection(value: string): value is JoystickDirection {
  * the fork's exact names and documented string-or-array shape.
  *
  * vice_joystick_tap is deliberately absent from this module (and the whole
- * stock manifest) -- a tap needs the machine to run for a measured
- * interval, which is an unrequested EXIT (forbidden by D-05) plus a
- * frame/cycle measurement stock does not have until Phase 7's timing route
- * lands (docs/stock-vice-parity.md section A item 7). Do not approximate it
- * with a sleep; do not implement it here.
+ * stock manifest), permanently -- a tap needs the machine to run for a
+ * measured interval, which is an unrequested EXIT (forbidden by D-05) plus
+ * a frame/cycle measurement stock's wire protocol has no route for at all
+ * (docs/stock-vice-parity.md section A item 7). Do not approximate it with
+ * a sleep; do not implement it here.
  */
 export const handleJoystickSet: StockSessionHandler = async (args, session) => {
   if (!isPlainObject(args)) {

package/stock-machine.ts

@@ -12,17 +12,17 @@
 // WHAT NOT TO DO:
 //   - Never gate or deny vice_machine_reset's hard mode. CLAUDE.md's
 //     power-cycle warning is about RESOURCE_SET (0x52) writes to
-//     MachineVideoStandard/VICIIModel/MachinePowerFrequency -- Phase 6
-//     territory, a DIFFERENT opcode entirely. RESET (0xcc) is a distinct
+//     MachineVideoStandard/VICIIModel/MachinePowerFrequency -- the CUT
+//     vice_machine_config_get/set pair's resources (docs/stock-vice-parity.md), a DIFFERENT opcode entirely. RESET (0xcc) is a distinct
 //     command, and an agent-requested hard reset via RESET is exactly what
 //     DIRECT-06 asks for. It needs no deny-list (RESEARCH.md Pitfall 1).
 //   - Never look for a per-unit disk-attach route mid-implementation.
 //     AUTOSTART (0xdd) has NO drive-unit field on the wire at all -- this is
 //     a protocol gap, not a code bug you can fix by looking harder
 //     (RESEARCH.md Pitfall 2).
-//   - Never add a disk-detach handler here. D-13 ships that tool in Phase 7
-//     through the text monitor -- grep-gated to zero occurrences of its name
-//     in this file's own acceptance criteria.
+//   - Never add a disk-detach handler here. D-13's vice_disk_detach was
+//     CUT from scope 2026-08-17 (docs/stock-vice-parity.md) -- grep-gated
+//     to zero occurrences of its name in this file's own acceptance criteria.
 //   - Never build a host path outside stock-paths.ts. Every filename this
 //     file sends through the wire goes through that same one wrapper --
 //     grep-gated to zero direct hostPath()/hostPathCandidates() calls here.
@@ -150,7 +150,18 @@ export const handleAutostart: StockSessionHandler = async (args, session) => {
  * at all, so an agent told "attached to unit 9" when the image landed on
  * unit 8 would debug the wrong drive. See docs/stock-vice-parity.md's D-14
  * entry.
+ *
+ * The returned `approximation` string names BOTH real side effects Phase 13
+ * plan 13-03's live A5 probe observed against real fork VICE 3.10: a full
+ * machine reset AND a program load, not "attach without disturbing machine
+ * state." Exported so the pinning test derives its expectation from this
+ * constant rather than re-typing the sentence, so the two cannot drift. See
+ * `.planning/phases/13-external-verification/13-PROBE-RESULTS.md` § A5.
  */
+export const DISK_ATTACH_APPROXIMATION =
+  "AUTOSTART (D-14): performs a full machine reset and loads a program from the image; " +
+  "unlike vice_autostart it does not issue a final run step, as far as observed.";
+
 export const handleDiskAttach: StockSessionHandler = async (args, session) => {
   const a = isPlainObject(args) ? args : {};
 
@@ -182,7 +193,7 @@ export const handleDiskAttach: StockSessionHandler = async (args, session) => {
       unit: 8,
       path: containerPath,
       sentPath,
-      approximation: "AUTOSTART with the run flag clear (D-14)",
+      approximation: DISK_ATTACH_APPROXIMATION,
     });
   } catch (err) {
     return convertWireError("vice_disk_attach", err);

package/stock-protocol.ts

@@ -720,12 +720,15 @@ export function registersSetBody({ memspace, items }: RegistersSetBodyOptions):
 
 // ---------------------------------------------------------------------------
 // Execution and machine-control body encoders (Phase 3, Task 2). Every
-// body layout below is [CITED] against the official VICE manual (§13) but
-// has NOT been exercised against a real binary in this environment -- each
-// JSDoc says so explicitly, and where RESEARCH.md's Assumptions Log flags a
-// behavioural (not wire-shape) assumption, the JSDoc names the row (A2, A3,
-// A5) and points at .planning/todos/pending/ for the probe debt. None of
-// these are claimed as verified.
+// body layout below is [CITED] against the official VICE manual (§13);
+// each encoder's own JSDoc states whether its behavioural (not wire-shape)
+// claim has since been live-probed. RESEARCH.md Assumptions Log row A2 was
+// closed CONFIRMED by 13-PROBE-RESULTS.md. Two rows below are still
+// unconfirmed -- A3 stayed INCONCLUSIVE (no observable signal either way)
+// and A5 was CONTRADICTED (still pending its correction) -- and each of
+// those two encoders' own JSDoc, below, still carries its own [ASSUMED]
+// naming that row and pointing at .planning/todos/pending/ for the
+// remaining probe debt.
 // ---------------------------------------------------------------------------
 
 export interface AdvanceInstructionsBodyOptions {
@@ -739,9 +742,11 @@ export interface AdvanceInstructionsBodyOptions {
  * exercised, with stepOver=0 only, in probe-binmon.mjs's async-events check]
  *
  * `stepOver = true`'s runtime meaning (skip a `JSR`'s subroutine as one
- * step, matching the fork's own `stepOver` field name) is [ASSUMED] --
- * RESEARCH.md Assumptions Log row A2 -- never probed against a real `JSR`.
- * See `.planning/todos/pending/` for the outstanding probe debt.
+ * step, matching the fork's own `stepOver` field name) was live-probed
+ * against a real `JSR` on fork VICE 3.10 and CONFIRMED (RESEARCH.md
+ * Assumptions Log row A2, closed by 13-PROBE-RESULTS.md §A2): the post-step
+ * PC landed at JSR+3, reproduced identically across two independent live
+ * sessions.
  */
 export function advanceInstructionsBody({ stepOver = false, count = 1 }: AdvanceInstructionsBodyOptions = {}): Buffer {
   if (!Number.isInteger(count) || count < 1 || count > 0xffff) {
@@ -816,8 +821,8 @@ export interface ResetBodyOptions {
  * [CITED docs/phase0-binmon-findings.md §5]
  *
  * NOT the RESOURCE_SET (0x52) power-cycle hazard CLAUDE.md warns about
- * (`MachineVideoStandard`/`VICIIModel`/`MachinePowerFrequency`, Phase 6
- * territory) -- this is a distinct opcode, and an agent-requested hard
+ * (`MachineVideoStandard`/`VICIIModel`/`MachinePowerFrequency`, the CUT
+ * vice_machine_config_get/set pair's resources) -- a distinct opcode, and an agent-requested hard
  * reset via RESET is exactly what DIRECT-06 asks for. It needs no
  * deny-list. This is RESEARCH.md's Pitfall 1; this comment is what stops a
  * later reviewer from "fixing" it by adding one.

package/stock-registers.ts

@@ -68,12 +68,19 @@ export interface RegisterCatalog {
 /** The one module-level catalog map, keyed on the session object itself --
  * NOT on session.client -- so a fresh stockReconnect() (which returns a
  * brand-new session) is indistinguishable from "never fetched" and simply
- * fetches again, with no manual invalidation path required anywhere. */
+ * fetches again, with no manual invalidation path required anywhere.
+ *
+ * Caches the in-flight PROMISE, not the resolved catalog (15-04, IN-02):
+ * two handlers racing on a fresh session both read `catalogs.get(session)`
+ * before either write lands, so caching only the resolved value let both
+ * send their own REGISTERS_AVAILABLE. Caching the promise means the second
+ * caller awaits the SAME in-flight request. A rejected promise is evicted
+ * (see registerCatalogFor()) so a failed fetch is retried, never memoised. */
 // Single-line by design: the ONLY line in this file naming the garbage-
 // collectable, session-keyed map primitive directly (grep-gated -- see
 // this plan's own acceptance criteria). Every other reference goes
 // through this factory, never a second construction call site.
-function freshCatalogMap(): WeakMap<StockConnectSession, RegisterCatalog> { return new WeakMap<StockConnectSession, RegisterCatalog>(); }
+function freshCatalogMap(): WeakMap<StockConnectSession, Promise<RegisterCatalog>> { return new WeakMap<StockConnectSession, Promise<RegisterCatalog>>(); }
 
 let catalogs = freshCatalogMap();
 
@@ -86,15 +93,22 @@ export function resetRegisterCatalogsForTest(): void {
 
 /**
  * Resolves `session`'s register catalog, fetching it through
- * REGISTERS_AVAILABLE (0x83) exactly once and caching the result on the
- * session object. Every subsequent call for the SAME session object
- * returns the cached catalog with no further wire traffic.
+ * REGISTERS_AVAILABLE (0x83) exactly once and caching the IN-FLIGHT
+ * PROMISE on the session object -- not just the resolved value, so two
+ * concurrent callers on a fresh session (before either fetch has
+ * resolved) share the SAME REGISTERS_AVAILABLE round trip rather than
+ * each sending their own (15-04, IN-02). Every subsequent call for the
+ * SAME session object returns the same promise (and, once it settles,
+ * the same resolved catalog) with no further wire traffic.
  *
  * Refuses (throws a plain Error, converted by the caller through
  * convertWireError()) an empty enumeration rather than caching it: a
  * build that enumerates zero registers cannot support
  * vice_registers_set, and that failure must be visible on every call,
- * never silently cached as "zero registers, nothing to resolve".
+ * never silently cached as "zero registers, nothing to resolve". A
+ * rejected fetch, whether from an empty enumeration or a wire error, is
+ * evicted from the cache before this function returns, so the NEXT call retries instead
+ * of permanently memoising the failure.
  */
 export async function registerCatalogFor(session: StockConnectSession): Promise<RegisterCatalog> {
   const existing = catalogs.get(session);
@@ -102,30 +116,41 @@ export async function registerCatalogFor(session: StockConnectSession): Promise<
     return existing;
   }
 
-  const response = await session.client.send(CommandType.RegistersAvailable, memspaceBody({ memspace: 0x00 }));
-  if (response.type !== "registers_available") {
-    throw new Error(`registerCatalogFor: expected a registers_available reply, got "${response.type}"`);
-  }
-  if (response.registers.length === 0) {
-    throw new Error(
-      "registerCatalogFor: the connected VICE build enumerated zero registers via REGISTERS_AVAILABLE -- " +
-        "it cannot support vice_registers_set, and this failure must be named rather than cached as an empty catalog",
-    );
-  }
+  const pending = (async (): Promise<RegisterCatalog> => {
+    const response = await session.client.send(CommandType.RegistersAvailable, memspaceBody({ memspace: 0x00 }));
+    if (response.type !== "registers_available") {
+      throw new Error(`registerCatalogFor: expected a registers_available reply, got "${response.type}"`);
+    }
+    if (response.registers.length === 0) {
+      throw new Error(
+        "registerCatalogFor: the connected VICE build enumerated zero registers via REGISTERS_AVAILABLE -- " +
+          "it cannot support vice_registers_set, and this failure must be named rather than cached as an empty catalog",
+      );
+    }
 
-  const byName = new Map<string, { id: number; sizeBits: number; name: string }>();
-  const byId = new Map<number, { sizeBits: number; name: string }>();
-  for (const reg of response.registers) {
-    // reg.size is stock-protocol.ts's own field name for the wire's size
-    // byte (its parser is unchanged by this plan); this module renames it
-    // to sizeBits at the point it enters the catalog so every downstream
-    // reader sees the unit named in the type.
-    byName.set(reg.name.toUpperCase(), { id: reg.id, sizeBits: reg.size, name: reg.name });
-    byId.set(reg.id, { sizeBits: reg.size, name: reg.name });
-  }
-  const catalog: RegisterCatalog = { byName, byId };
-  catalogs.set(session, catalog);
-  return catalog;
+    const byName = new Map<string, { id: number; sizeBits: number; name: string }>();
+    const byId = new Map<number, { sizeBits: number; name: string }>();
+    for (const reg of response.registers) {
+      // reg.size is stock-protocol.ts's own field name for the wire's size
+      // byte (its parser is unchanged by this plan); this module renames it
+      // to sizeBits at the point it enters the catalog so every downstream
+      // reader sees the unit named in the type.
+      byName.set(reg.name.toUpperCase(), { id: reg.id, sizeBits: reg.size, name: reg.name });
+      byId.set(reg.id, { sizeBits: reg.size, name: reg.name });
+    }
+    return { byName, byId };
+  })();
+
+  catalogs.set(session, pending);
+  // Evict on rejection so a failed fetch is retried by the next call
+  // rather than memoised forever -- only if no newer promise has already
+  // replaced this one for the same session.
+  pending.catch(() => {
+    if (catalogs.get(session) === pending) {
+      catalogs.delete(session);
+    }
+  });
+  return pending;
 }
 
 // ---------------------------------------------------------------------------

package/stock-sprites.ts

@@ -12,14 +12,14 @@
 // PROVENANCE (required reading before touching the four geometry
 // functions below): vicBank(), vicBankBase(), screenBase() and
 // spriteDataAddress() are PORTED, NOT RE-DERIVED, from
-// .claude/skills/c64-ram-capture/scripts/dump-artifacts.mjs's own
+// src/skills/c64-ram-capture/scripts/dump-artifacts.mjs's own
 // vicBank()/screenBase()/spriteDataAddresses map, which carries a
 // committed, verified fixture: dd00_raw=193 (0xC1), d018_raw=49 (0x31) ->
 // screen_base=35840. stock-sprites.test.ts re-asserts the SAME fixture as
 // its own cross-check -- do not change any of the four expressions without
 // also updating that committed fixture's provenance. The skill's
-// JavaScript is copied here, never imported at runtime -- .claude/skills/
-// is a different package, absent from .claude/mcp/vice's files[], so a
+// JavaScript is copied here, never imported at runtime -- src/skills/
+// is a different package, absent from src/mcp/vice's files[], so a
 // runtime cross-package import would be missing from the published
 // tarball.
 //

package/stock-symbols.ts

@@ -26,15 +26,15 @@
 // The confirmed input format is a VICE label file, one `al C:xxxx .Name`
 // line per symbol, verified against ACME's `--vicelabels` output via
 // acme-build/scripts/acme.mjs's own parser (curateLabels(),
-// `/^al\s+C:[0-9a-f]+\s+\.(\S+)/i`). VERIFIED (Phase 9, R2000-16(c)):
-// regenerator2000 0.9.20's `--export_lbl` was run against the
+// `/^al\s+C:[0-9a-f]+\s+\.(\S+)/i`). VERIFIED (Phase 9, ANNO-16(c)):
+// the external analyser 0.9.20's `--export_lbl` was run against the
 // probe-illegal.prg-derived fixture and emitted `al C:0810 .init_screen`,
 // which matches this module's own VICE_LABEL_LINE_RE
 // (`/^al\s+C:([0-9a-fA-F]{1,4})\s+\.(\S+)/`) exactly. This claim is SCOPED to
-// regenerator2000 0.9.20 and that fixture -- not to all inputs forever (the
+// the external analyser 0.9.20 and that fixture -- not to all inputs forever (the
 // same scoping caveat ROADMAP.md applies to Phase 9's criterion 3(3) `pass`).
 // The parser below still SKIPS unrecognised lines rather than refusing the
-// whole file: a future regenerator2000 version, a hand-edited label file, or
+// whole file: a future analyser version, a hand-edited label file, or
 // a different exporter entirely can still produce lines this format should
 // tolerate rather than reject outright.
 //
@@ -82,8 +82,8 @@ const VICE_LABEL_LINE_RE = /^al\s+C:([0-9a-fA-F]{1,4})\s+\.(\S+)/;
 
 /** T-05-02-03: three independent resource ceilings, each refusing with both
  * the observed value and the limit named. `MAX_LABEL_FILE_BYTES` is exported
- * (11-08, Rule A20) so `r2000-symbols.ts`'s `exportLabels()`/`importLabels()`
- * can apply the SAME byte ceiling to a regenerator2000-produced/-consumed
+ * (11-08, Rule A20) so `anno-symbols.ts`'s `exportLabels()`/`importLabels()`
+ * can apply the SAME byte ceiling to an external-analyser-produced/-consumed
  * `.lbl` file before ever calling `parseViceLabelFile()` below -- never a
  * second hand-copied number. */
 export const MAX_LABEL_FILE_BYTES = 2 * 1024 * 1024;
@@ -201,9 +201,9 @@ function resolveLabelFilePath(pathArg: unknown): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Exported (11-08, Rule A20) so `r2000-symbols.ts` can validate a
- * regenerator2000-produced `.lbl` file (or check a caller-supplied one
- * BEFORE it is ever handed to a spawned regenerator2000 child) through THIS
+ * Exported (11-08, Rule A20) so `anno-symbols.ts` can validate a
+ * external-analyser-produced `.lbl` file (or check a caller-supplied one
+ * BEFORE it is ever handed to a spawned analyser child) through THIS
  * parser -- the ONE `al C:xxxx .Name` reader in this repo -- rather than
  * adding a second copy of `VICE_LABEL_LINE_RE`. Ceiling violations
  * (`MAX_LABEL_FILE_LINES`/`MAX_SYMBOLS`) throw `StockSymbolsError` exactly as

package/stock-timing.ts

@@ -21,7 +21,7 @@
 //   - Never assign `cycles: 0` or `cycles: null` for an unmeasurable
 //     bracket. `measurable: false` with a `reason` and NO `cycles` key at
 //     all is the only honest shape -- see the incident this rule exists to
-//     prevent: `.claude/skills/c64-program-recon/references/observation-hazards.md`'s
+//     prevent: `src/skills/c64-program-recon/references/observation-hazards.md`'s
 //     record of the fork's stopwatch reading 258,504,308 cycles and being
 //     trusted as fact.
 //   - Never hardcode a register id for LIN/CYC/PC. `registerCatalogFor()`

package/stock-vicii.ts

@@ -61,7 +61,7 @@
 //
 // FIELD-NAME PROVENANCE (Assumption A4's mitigation): every bit-field name
 // below was transcribed once from
-// .claude/skills/c64-memory-mapping/memmap.json's own entries for $D011
+// src/skills/c64-memory-mapping/memmap.json's own entries for $D011
 // (Screen control register #1 / VIC Control Register), $D012 (raster line),
 // $D016 (Screen control register #2 / VIC Control Register), $D018 (Memory
 // setup register / VIC Memory Control Register), $D019 (Interrupt status

package/version.ts

@@ -1,7 +1,7 @@
 // The ONE authoritative implementation of this project's version-resolution
 // algorithm (D-5). Before this file existed the repo carried FOUR
 // hand-maintained version strings and none of them were true:
-// `.claude/mcp/vice/package.json` and `installer/package.json` were stale
+// `src/mcp/vice/package.json` and `installer/package.json` were stale
 // placeholders CI never touched between releases, `.claude-plugin/plugin.json`
 // was bumped by NO automation at all, and `vice-proxy.ts`'s own
 // `PROXY_VERSION` literal -- advertised to every MCP client over