@henols/vice-mcp 0.2.1 → 0.2.2

package/block-class.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// block-class.ts
+//
+// The ONE place that translates an annotation store's own block-type
+// vocabulary into a neutral block class. Nothing else in this tree may
+// compare a store block-type string, and nothing else may read a store block
+// listing on the census's behalf (SEAM-03).
+//
+// ---------------------------------------------------------------------------
+// WHY THIS FILE EXISTS
+// ---------------------------------------------------------------------------
+// `anno-coverage.ts` is the coverage instrument: it implements two Validated
+// requirements and measures how much of a binary has actually been reverse-
+// engineered. Its census is a pure function of the raw bytes and the seed set
+// the caller supplies -- deliberately, because deriving completeness from the
+// store's own block table measures the annotator's bookkeeping rather than
+// the annotation.
+//
+// Yet the census's ONLY tie to the external analyser this project rents its
+// annotation store from was four inline comparisons against that analyser's
+// Rust `Display` strings, spread across three code regions and reached from
+// two lookup call sites. Four string literals were the entire reason a
+// 2,292-line instrument looked like glue around somebody else's data model.
+// Any prefix-driven deletion of the rented substrate would have taken the
+// instrument with it.
+//
+// So the tie lives here, in one small module, behind one named function. A
+// later phase swaps THIS module -- the store's vocabulary changes, the census
+// does not. That is the whole point: the boundary is the module, never an
+// argument threaded through the census.
+//
+// The neutral classes are LOWERCASE. That lowercase-ness was once claimed as
+// a protection in its own right -- the argument being that a capitalised
+// store spelling could not accidentally agree with it, so a comparison site
+// left behind somewhere else would get a different answer and move a measured
+// number, loudly. THAT PREMISE IS NOW FALSE, and the loss is recorded here
+// rather than left to be rediscovered: this project's own
+// store's vocabulary is LOWERCASE, and two of its twelve members -- the code
+// spelling and the undefined spelling -- are string-identical to their
+// neutral classes. A left-behind raw comparison against the store's own
+// spelling therefore CAN accidentally agree now, silently, which is exactly
+// what the old rationale promised could not happen.
+//
+// Two guards replace it, and they are why the mapping below is still
+// defended. Neither is a claim in a header:
+//
+//   (a) the derived TOTAL cross-check in `block-class.test.ts`. It iterates
+//       the store's frozen twelve-member vocabulary from its single home and
+//       asserts the class this module returns for EVERY member, with its own
+//       non-vacuity assertions on the counts. It reddens the moment either
+//       side drifts; a spot check would not.
+//   (b) `anno-coverage.test.ts`'s zero-overlap substitutability proof. Its
+//       substituted vocabulary (`EXECUTABLE_EXTENT` and its two siblings)
+//       shares no string with EITHER accepted vocabulary, so a left-behind
+//       comparison site is still observable there -- which is why that
+//       vocabulary list is DERIVED from both, not hand-written at four
+//       entries.
+//
+// ---------------------------------------------------------------------------
+// WHAT NOT TO DO -- each of these is a specific, named trap
+// ---------------------------------------------------------------------------
+//   1. NEVER accept the census, the raw program bytes, a decoder, or a
+//      confidence grade as an argument here. `anno-coverage.ts` records a
+//      BYTES-VERSUS-STORE independence axis: one side classifies an address
+//      using only the raw bytes and the census, the other using only the
+//      store's own documentation, and NEITHER SIDE READS THE OTHER'S INPUT.
+//      That axis is the reason its reproducibility figure means anything.
+//      One extra argument here collapses it -- and it collapses QUIETLY: the
+//      independence test would keep passing while the claim it protects
+//      became void. The signature below is two arguments and must stay two.
+//   2. NEVER compare a store vocabulary string outside this module. A second
+//      comparison site is a second answer to "what class is this address",
+//      and the census must have exactly one.
+//   3. NEVER hold module-level mutable state. The lookup is a pure function
+//      of its two arguments, so interleaved or repeated calls cannot observe
+//      each other. There is nothing to reset and nothing to synchronise.
+//   4. NEVER import anything census-side, disassembler-side, transport-side
+//      or path-translation-side. This module's import list is EMPTY and a
+//      committed structural assertion in `block-class.test.ts` keeps it that
+//      way -- see trap 1 for why the emptiness is load-bearing rather than
+//      tidy.
+
+// ---------------------------------------------------------------------------
+// The neutral vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * The three neutral block classes every consumer speaks. Lowercase tokens.
+ *
+ * These tokens were once ALSO offered as a guard in their own right, on the
+ * ground that no store spelling could collide with them. Two of the store's
+ * twelve members now do collide, so that reading is gone -- see this file's
+ * header for the loss and for the two derived cross-checks that defend the
+ * mapping instead.
+ *
+ * Three-valued and no finer. The consumers compare this against a
+ * classification derived from completely different inputs, so a richer
+ * vocabulary would manufacture disagreement out of vocabulary drift rather
+ * than measure anything.
+ */
+export type BlockClass = "code" | "data" | "undefined";
+
+/**
+ * One entry of a store's block listing, exactly as the curated read tool
+ * returns it.
+ *
+ * `type` carries the STORE'S OWN vocabulary -- whatever spelling the
+ * annotation substrate happens to use for its block kinds. This module is
+ * the only place in the tree that interprets that field. A consumer that
+ * reads `.type` and compares it is re-opening the boundary this file exists
+ * to close.
+ */
+export interface BlockEntry {
+  start_address: number;
+  end_address: number;
+  /** The store's own block-kind spelling. Interpreted HERE and nowhere else. */
+  type: string;
+}
+
+/**
+ * The shape of a block classifier: given a store's block listing and an
+ * address, the neutral class covering that address, or `null` when no block
+ * covers it.
+ *
+ * Named as a type so a consumer can be handed a substitute implementation
+ * for a substitutability proof without that consumer ever naming a concrete
+ * store vocabulary.
+ */
+export type BlockClassifier = (blocks: readonly BlockEntry[], address: number) => BlockClass | null;
+
+/**
+ * The one production classifier.
+ *
+ * A linear scan, first-match-wins, with both range ends INCLUSIVE. A
+ * `null`/`undefined` hole in the array is skipped rather than thrown on --
+ * the listing arrives from a project file this process did not author. That
+ * premise applies to `blocks` ITSELF as well, so a non-array argument returns
+ * `null` here rather than throwing a `TypeError` out of the `for ... of`
+ * (IN-04). Both production callers already pre-guard with
+ * `Array.isArray(blocks) ? blocks : []`, so nothing is reachable today; the
+ * point is that the defence now lives in the module that DOCUMENTS the
+ * premise, instead of only in callers outside it.
+ *
+ * The mapping is total by construction over BOTH ACCEPTED VOCABULARIES: a
+ * code spelling from either becomes `"code"`, an undefined spelling from
+ * either becomes `"undefined"`, and EVERY other spelling becomes `"data"` --
+ * whether it belongs to one of the two vocabularies or to neither. That
+ * fallthrough is not a simplification; it is exactly what the two comparisons
+ * this function replaced did when read together, and it is what keeps an
+ * unrecognised spelling -- including one from a producer this module has
+ * never heard of -- from silently reading as code.
+ *
+ * The two arms are two VOCABULARIES that happen to differ in case, never one
+ * vocabulary compared case-insensitively. A case-insensitive or
+ * whitespace-trimming comparison here would silently accept a third spelling
+ * nobody chose; `block-class.test.ts` pins that it does not.
+ */
+export const blockClassAt: BlockClassifier = (blocks, address) => {
+  if (!Array.isArray(blocks)) return null;
+  for (const block of blocks) {
+    if (!block) continue;
+    if (address >= block.start_address && address <= block.end_address) {
+      // TWO ACCEPTED VOCABULARIES, one arm each, in the same order so the
+      // pairing reads at a glance. Deliberately NOT folded into a
+      // case-insensitive test -- see this function's doc comment.
+      //
+      // This project's own annotation store, whose twelve block types are
+      // lowercase and live in one frozen home the test cross-checks against:
+      if (block.type === "code") return "code";
+      if (block.type === "undefined") return "undefined";
+      // TRANSITIONAL -- the capitalised vocabulary, whose PRODUCER (the
+      // external analyser this project used to rent an annotation store from,
+      // whose Rust `Display` emitted these spellings) IS GONE AS OF PHASE 29,
+      // 2026-08-29. The trigger the previous comment named has therefore
+      // already fired, and the arm still stands. That is a decision, recorded
+      // here rather than left to be rediscovered as an inert branch:
+      //
+      //   WHY IT SURVIVES ITS OWN TRIGGER: every committed coverage fixture
+      //   under `fixtures/coverage/**/store.json` is still SPELLED in this
+      //   vocabulary ("Code", "Byte", "Undefined"). Deleting the two arms
+      //   below today reclassifies every fixture block as `data` -- silently,
+      //   because `data` is the total fallthrough and no error is raised
+      //   anywhere. The fixtures are the census's own controls, so that would
+      //   move the numbers the controls exist to pin.
+      //
+      //   THE NEW REMOVAL TRIGGER is therefore the FIXTURES being re-spelled
+      //   into the store's own lowercase vocabulary -- not the producer being
+      //   deleted, which has happened. Re-spell the fixtures (and their
+      //   generator) first, observe the census unchanged, then delete these
+      //   two lines.
+      //
+      //   FATE: carried as a Phase 32 guard-fate item ("every guard pinned to
+      //   the deleted subject has a recorded fate"), so the ledger picks this
+      //   arm up deliberately instead of finding it red or inert in CI.
+      if (block.type === "Code") return "code";
+      if (block.type === "Undefined") return "undefined";
+      return "data";
+    }
+  }
+  return null;
+};

package/build.ts

@@ -138,7 +138,7 @@ export interface BuildOptions {
  *    `renameSync()` per artifact, and `rename(2)` fails `EXDEV` across mounts.
  *    That is why the original implementation staged at `dirname(outDirAbs)`.
  * 2. **Outside any directory a test walks.** Staging at `dirname(outDirAbs)`
- *    put a transient `.build-tmp-*` inside `.claude/mcp/vice/`, and
+ *    put a transient `.build-tmp-*` inside `src/mcp/vice/`, and
  *    `vice-mcp-selector-docs.test.ts`'s `walkFiles()` recurses through every
  *    directory there except `node_modules` — so a concurrent walk descended
  *    into the staging dir and died `ENOENT` when the rename removed it. That

package/capability-registry.ts

@@ -280,7 +280,9 @@ export const CAPABILITY_REGISTRY: readonly CapabilityEntry[] = [
     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.",
+      "subset that never shipped on stock. Its advertised WarpMode resource is fork-only: stock " +
+      "has no runtime warp resource at all, and warp on stock is a launch-time flag, not a " +
+      "resource that can be toggled while running.",
   },
   {
     name: "vice_joystick_tap",

package/disasm-decoder.ts

@@ -1,24 +1,24 @@
 // disasm-decoder.ts
 //
 // The pure `decode(bytes, startAddress, opts) -> Instruction[]` function --
-// D-05's standalone module. Phase 5's backtrace (DERIV-02) and Phase 6's
-// 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. 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.
+// D-05's standalone module, kept import-free of `stock-*.ts`/`vice*.ts`/any
+// `node:` builtin so any future non-tool consumer (a decode call with no
+// socket in the picture) could depend on this one file without dragging in
+// transport code. Two originally-planned consumers never landed: Phase 5's
+// backtrace (DERIV-02) and a CPU-history decode (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
 // ---------------------------------------------------------------------------
-// `stock-disassemble.ts` (04-05) is the tool-facing consumer, but three other
-// consumers need decoding without a socket in the picture at all: the
-// renderer (04-04), Phase 5's backtrace and Phase 6's CPU-history decode.
-// Keeping decode() import-free of `stock-*.ts`/`vice*.ts`/any `node:`
-// builtin means all four can depend on this one file without dragging in
-// transport code.
+// `stock-disassemble.ts` (04-05) is the tool-facing consumer; the renderer
+// (04-04) is the only other one that exists. Two more were planned (Phase
+// 5's backtrace, DERIV-02, and a CPU-history decode, GAIN-01) but both
+// were cut from v0.2.0 scope on 2026-08-17 before being built. Keeping
+// decode() import-free of `stock-*.ts`/`vice*.ts`/any `node:` builtin means
+// both existing consumers can depend on this file without transport code.
 //
 // ---------------------------------------------------------------------------
 // WHAT NOT TO DO

package/disasm-opcodes.ts

@@ -43,7 +43,7 @@
 // Mnemonic naming: two deliberate departures from cc65's own spelling
 // ---------------------------------------------------------------------------
 // cc65 spells two illegal opcodes differently from ACME's verified
-// `!cpu 6510` mnemonic set (`.claude/skills/acme-build/SKILL.md`: `lax dcp
+// `!cpu 6510` mnemonic set (`src/skills/acme-build/SKILL.md`: `lax dcp
 // sax slo rla sre rra isc anc alr arr sbx las tas sha shx shy jam`). This
 // table follows ACME's names, not cc65's, at exactly these two opcodes, so
 // that `acmeExpressible` below can be computed by simple set membership
@@ -100,9 +100,9 @@
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS
 // ---------------------------------------------------------------------------
-// This is the one table the decoder (04-03), Phase 5's backtrace (DERIV-02)
-// and Phase 6's CPU-history decode (GAIN-01) all read instruction lengths
-// from. A wrong length here silently desynchronises every instruction after
+// This is the one table the decoder (04-03) and Phase 5's backtrace
+// (DERIV-02) read instruction lengths from. GAIN-01's CPU-history decode, a
+// third would-be consumer, was cut with the whole of Stock-Only Gains, 2026-08-17 (ROADMAP.md). A wrong length here silently desynchronises every instruction after
 // it in every one of those consumers (criterion 2's own wording) -- there is
 // no runtime check downstream that would catch a transcription typo on its
 // own; that is what `disasm-opcodes.test.ts`'s independent bit-pattern

package/disasm-renderer.ts

@@ -7,8 +7,8 @@
 // `stock-disassemble.ts` (04-05) wires the real symbol resolver in via
 // `RenderOptions.symbolFor`; this file never imports `stock-address.ts`
 // itself, so it stays importable by anything that only has an
-// `Instruction[]` in hand (Phase 5's backtrace, Phase 6's CPU-history decode
-// -- neither has a live symbol store).
+// `Instruction[]` in hand. Both originally-planned such consumers (Phase 5's
+// backtrace, a CPU-history decode) were cut from v0.2.0 scope on 2026-08-17.
 //
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS

package/hostpath.ts

@@ -28,7 +28,7 @@
 //      towards mechanism 1.
 //
 // Node >= 18. No dependencies, no network, nothing machine-specific: copy this
-// file into any devcontainer-based project's .claude/mcp/vice/ and it works.
+// file into any devcontainer-based project's src/mcp/vice/ and it works.
 //
 // HOSTING CHOICE (01.6.1-02, Criterion B / RESEARCH §3.4 Option B): this
 // module takes the workspace root as an ARGUMENT (an optional `workspaceRoot`

package/install-resources.ts

@@ -78,7 +78,7 @@ export interface PruneResourcesResult {
 export type ResourceStatus = "missing" | "present" | "diverged";
 
 /** This module directory's resources/ subdirectory -- a plain SIBLING of this
- * module (scripts/ was flattened away in the .claude/mcp/vice/ move), the
+ * module (scripts/ was flattened away in the src/mcp/vice/ move), the
  * tracked source of truth every deployed tools/ file is copied from. Getting
  * this hop wrong is silent and total: readdirSync() throws inside
  * resourceEntries(), but ensureResourcesInstalled() catches everything by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/vice-mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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": {
@@ -53,20 +53,26 @@
     "stock-run-until.ts",
     "stock-diagnose.ts",
     "stock-recycle.ts",
-    "r2000-launch.ts",
-    "r2000-project.ts",
-    "r2000-d64.ts",
-    "r2000-cli.ts",
-    "r2000-verify.ts",
-    "r2000-mcp-client.ts",
-    "r2000-tools.ts",
-    "r2000-symbols.ts",
-    "r2000-regbits-gen.ts",
-    "r2000-regbits.json",
-    "r2000-enum-gen.ts",
-    "r2000-acme-ident.ts",
-    "r2000-confidence.ts",
-    "r2000-memmap-render.ts",
+    "anno-d64.ts",
+    "anno-cli.ts",
+    "anno-symbols.ts",
+    "anno-regbits-gen.ts",
+    "anno-regbits.json",
+    "anno-enum-gen.ts",
+    "anno-acme-ident.ts",
+    "anno-confidence.ts",
+    "anno-memmap-render.ts",
+    "anno-export-asm.ts",
+    "anno-coverage.ts",
+    "block-class.ts",
+    "prg-image.ts",
+    "anno-types.ts",
+    "anno-index.ts",
+    "anno-store.ts",
+    "anno-tools.ts",
+    "anno-derive.ts",
+    "anno-details.ts",
+    "anno-register.ts",
     "resources",
     "tools-manifest.json",
     "tools-manifest.stock.json",
@@ -74,7 +80,7 @@
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -87,7 +93,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/henols/c64-re-tools.git",
-    "directory": ".claude/mcp/vice"
+    "directory": "src/mcp/vice"
   },
   "homepage": "https://github.com/henols/c64-re-tools#readme",
   "bugs": {

package/prg-image.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// prg-image.ts -- the ONE authoritative place in this repo holding pure C64
+// image byte-layout knowledge: how a `.prg` splits into a load address plus a
+// body, what load address a flat 64K RAM capture has, and how to invert a
+// gzip-then-base64 payload back into bytes. These are facts about C64 file
+// formats and about one payload encoding -- they depend on no external
+// analyser, no emulator, and no annotation store, so they belong in a module
+// none of those can take with them when it goes away.
+//
+// This module performs NO filesystem and NO network I/O: every function takes
+// bytes (or a base64 string) and returns values. Callers obtain and persist
+// the bytes themselves. That is the same claim `anno-project.ts` makes about
+// itself, and it must remain true of both files now that the split has
+// happened -- a structural test in `prg-image.test.ts` asserts it from this
+// module's own source rather than trusting this paragraph.
+//
+// WHY THIS FILE EXISTS SEPARATELY: these three functions used to live in
+// `anno-project.ts`, the module that builds a `.regen2000proj` file for the
+// the external analyser analyser. They were never about that analyser. One of them
+// is imported statically by the byte-coverage census (`anno-coverage.ts`), a
+// capability that must keep working independently of whether this repo still
+// drives that analyser at all -- so a census whose only route to a payload
+// decoder ran through analyser glue was one deletion away from breaking with
+// no announcement (SEAM-02). Extracting them under a name that carries no
+// analyser prefix removes that coupling outright instead of recording it as a
+// hazard to remember later. There is deliberately NO re-export left behind in
+// `anno-project.ts`: a compatibility shim would leave the coupling fully
+// intact while looking finished.
+//
+// THIS MODULE MUST BE LISTED IN `package.json`'s `files[]`. It is reachable
+// from the published entry point's import closure, and the STATIC route is
+// named here first because it is the stronger reachability claim: `anno-
+// tools.ts` -- the curated `anno_*` MCP tool surface -- imports `parsePrg` and
+// `flatImageOrigin` from here with a plain top-level import, and `vice-proxy.ts`
+// imports `anno-tools.ts` statically. `anno-coverage.ts` (the byte-coverage
+// census) imports `decodeRawData`, `parsePrg` and `flatImageOrigin` for the
+// same three facts on the CLI's route. `scripts/check-npm-packages.mjs` walks
+// that closure over `files[]` and fails the pack the moment a reachable module
+// sits outside the listed set, exactly as `anno-d64.ts`'s own header records
+// for the same reason.
+//
+// CORRECTED 2026-08-30 (WR-07, plan 29-16). This paragraph previously named
+// `anno-cli.ts` as importing `parsePrg` and `flatImageOrigin` and rested the
+// whole reachability claim on the DYNAMIC import that reaches that file. That
+// was doubly wrong: `anno-cli.ts` imported neither symbol (it imported
+// `decodeRawData` only), and it now imports nothing from here at all -- its
+// image decode delegates to `anno-coverage.ts`'s `loadProjectImage()`. A
+// stated reason for shipping a file has to be true or it is worse than absent.
+//
+// WHAT NOT TO DO:
+//   - Never give any function here a filesystem PATH parameter. They take byte
+//     arrays and a base64 string, which is precisely what keeps path traversal
+//     out of this module's threat surface entirely. Path resolution belongs to
+//     the CLI. For the same reason this module imports nothing from either of
+//     this repo's two host/container path-translation seams; that absence is
+//     asserted structurally by `hostpath-consumers.test.ts`, not merely stated
+//     here.
+//   - Never relax, reword or reorder either input refusal below. The concrete
+//     incident: a 4096-byte flat `.raw` capture fell through to the `.prg`
+//     parser, whose first two bytes become the load address, so a truncated
+//     capture silently "bootstrapped" with an origin read backwards out of its
+//     own payload bytes and exited zero -- every downstream address wrong, no
+//     diagnostic. The refusal message texts are a user-visible contract: both
+//     `anno-tools.ts`'s `loadImage()` and `anno-coverage.ts`'s
+//     `loadProjectImage()` prefix them with the caller's own image path, and
+//     tests on both routes match on their wording, so a reworded message
+//     breaks a test for a reason that looks unrelated. (Attribution corrected
+//     2026-08-30, WR-07: this line named `anno-cli.ts`, which prefixed them
+//     through a `bootstrap` verb deleted by D-14 on 2026-08-29.)
+//   - Never add the dispatch ORDER discipline here. Which check runs first for
+//     a given input extension belongs to the two loaders that own it --
+//     `anno-tools.ts`'s `loadImage()` for the MCP tool surface and
+//     `anno-coverage.ts`'s `loadProjectImage()` for the coverage verb. Both
+//     dispatch `.raw`/`.bin` by extension BEFORE any length check, so that
+//     `flatImageOrigin`'s named refusal is always reachable for those two
+//     extensions. Neither function below may start inferring what kind of
+//     image it was handed.
+
+import { gunzipSync } from "node:zlib";
+
+/**
+ * Parses a `.prg` file: a little-endian 2-byte load address followed by the
+ * payload bytes. This is the C64 program-file convention every C64 loader
+ * (and this project's own `acme-build` output) already follows.
+ */
+export function parsePrg(bytes: Uint8Array): { origin: number; body: Uint8Array } {
+  if (bytes.length < 3) {
+    throw new Error(
+      `parsePrg: input is ${bytes.length} byte(s) -- a .prg needs at least 3 bytes (2-byte load address plus at least 1 payload byte)`,
+    );
+  }
+  const origin = bytes[0]! | (bytes[1]! << 8);
+  const body = bytes.subarray(2);
+  return { origin, body };
+}
+
+/**
+ * Returns the load address (`0`) for a flat 64K RAM capture, and throws for
+ * anything else. Flat 64K is in scope because `ANNO-06` names it directly
+ * and it is exactly the shape `c64-ram-capture` already produces (D-03) --
+ * this function does not attempt to support any other flat-image size.
+ */
+export function flatImageOrigin(bytes: Uint8Array): number {
+  if (bytes.length !== 65536) {
+    throw new Error(
+      `flatImageOrigin: input is ${bytes.length} byte(s) -- a flat 64K capture must be exactly 65536 bytes`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * The inverse of a gzip-then-base64 payload encoding: base64-decode, then
+ * gunzip. Exported so tests can prove the payload round-trips exactly,
+ * rather than asserting against an opaque blob.
+ */
+export function decodeRawData(base64: string): Uint8Array {
+  return gunzipSync(Buffer.from(base64, "base64"));
+}

package/repo-root.ts

@@ -39,6 +39,19 @@
 // `scripts/` segment. Branch 4's hop count below moved from four levels to
 // three to match. Branches 1-3 are depth-independent (an env var check, then
 // a `.git` ancestor walk) and needed no change.
+//
+// FOURTH MOVE (phase 16-04, 2026-08-23): the module directory relocated
+// again, from `.claude/mcp/vice/` to `src/mcp/vice/` (packaging and repo
+// shape). `src`/`mcp`/`vice` is the same three path segments below the
+// repository root as the old `.claude`/`mcp`/`vice` shape -- this is
+// reviewed and confirmed, not assumed, from the segment count itself. Branch
+// 4's hop count was therefore reviewed and deliberately left unchanged: this
+// move relocates the same flat, three-segment shape elsewhere directly under
+// the root, which is a different move from nesting authored sources one
+// level deeper INSIDE this directory (which would make four, and IS what
+// branches 1-3's depth-independence and branch 4's fixed hop count would not
+// survive). See repo-root.test.ts's own standing caution for that
+// distinction, drawn explicitly there for the first time by this move.
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve, sep } from "node:path";
@@ -62,6 +75,8 @@ let warnedNoMarkerFound = false;
 export interface RepoRootOptions {
   from?: string;
   env?: NodeJS.ProcessEnv;
+  /** Test seam for the marker walk; production uses node:fs existsSync. */
+  exists?: (path: string) => boolean;
 }
 
 /**
@@ -84,7 +99,7 @@ function isInside(child: string, parent: string): boolean {
  *      Claude Code exports for the workspace it is driving. This is the ONLY
  *      branch that is correct when this module is consumed as an installed
  *      plugin: the MCP's own files then live under the plugin install dir
- *      (e.g. `~/.claude/plugins/<marketplace>/<plugin>/.claude/mcp/vice/`),
+ *      (e.g. `~/.claude/plugins/<marketplace>/<plugin>/src/mcp/vice/`),
  *      NOT inside the project the user is working in, so neither the
  *      `from`-relative `.git` walk (branch 2, which would find the plugin's
  *      OWN checkout) nor a CONTAINER_WORKSPACE_PATH containment check
@@ -108,13 +123,13 @@ function isInside(child: string, parent: string): boolean {
  *      be exactly the quiet-wrong-answer failure class this file exists to
  *      prevent, so this path emits a one-time stderr note naming both paths.
  *   4. Otherwise, three levels up from `from`, with a one-time stderr note.
- *      Last resort only -- three levels is what `<root>/.claude/mcp/<server>/`
+ *      Last resort only -- three levels is what `<root>/src/mcp/<server>/`
  *      implies. In this repo branch 4 never actually runs (there is always a
  *      `.git` ancestor), which is exactly why the paired synthetic test in
  *      repo-root.test.ts is the only thing that would catch a wrong hop
  *      count here.
  */
-export function repoRoot({ from = HERE, env = process.env }: RepoRootOptions = {}): string {
+export function repoRoot({ from = HERE, env = process.env, exists = existsSync }: RepoRootOptions = {}): string {
   // Branch 0 (plugin-consumption signal): Claude Code sets CLAUDE_PROJECT_DIR
   // to the root of the workspace it is driving. When this module runs as an
   // installed plugin its own files sit outside that workspace, so this is the
@@ -134,7 +149,7 @@ export function repoRoot({ from = HERE, env = process.env }: RepoRootOptions = {
 
   let dir = resolve(from);
   while (true) {
-    if (existsSync(join(dir, ".git"))) {
+    if (exists(join(dir, ".git"))) {
       return dir;
     }
     const parent = dirname(dir);
@@ -160,7 +175,7 @@ export function repoRoot({ from = HERE, env = process.env }: RepoRootOptions = {
     const fallback = resolve(from, "..", "..", "..");
     console.error(
       `warn: could not find a .git ancestor above ${from} and CONTAINER_WORKSPACE_PATH is not set -- ` +
-        `falling back to three levels up (${fallback}), the shape <root>/.claude/mcp/<server>/ implies. ` +
+        `falling back to three levels up (${fallback}), the shape <root>/src/mcp/<server>/ implies. ` +
         `This is a last resort; if it's wrong, set CONTAINER_WORKSPACE_PATH or run from inside a git repo.`
     );
   }

package/resources/broker-launch.mjs

@@ -101,10 +101,14 @@ let warnedRemoteMonitorBindWidened = false;
  * the binmon address already used -- one resolution, not two. When
  * `remoteMonitorPort` is omitted (undefined), the returned argv is
  * byte-identical to what this function always returned -- no
- * `-remotemonitor` at all. `-remotemonitoraddress`'s exact spelling is
- * `[ASSUMED]` by symmetry with `-binarymonitoraddress` (RESEARCH.md
- * Assumption A1) and is filed as probe debt under
- * `.planning/todos/pending/`. Widening THIS bind away from loopback emits
+ * `-remotemonitor` at all. `-remotemonitoraddress`'s exact spelling was
+ * live-probed against a real fork-3.10 binary and CONFIRMED (RESEARCH.md
+ * Assumption A1, closed by 13-PROBE-RESULTS.md §A1: the flag bound a real,
+ * accepting text-monitor listener, corroborated independently by
+ * `ss -ltnp`). Genuine stock 3.9 was not independently probed in that run --
+ * the spelling itself is a symmetrical CLI flag pair and is not
+ * version-sensitive, so this is recorded as a low-risk carry-forward rather
+ * than implied stock-3.9 coverage. Widening THIS bind away from loopback emits
  * its own one-time stderr note (`warnedRemoteMonitorBindWidened`), naming
  * the resolved address and stating that VICE's TEXT monitor accepts
  * arbitrary monitor commands and is unauthenticated -- Phase 3 dials

package/resources/vice-launcher.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# .claude/mcp/vice/resources/vice-launcher.sh
+# src/mcp/vice/resources/vice-launcher.sh
 #
 # HAND-AUTHORED -- not generated. It lives beside the generated vice-broker.mjs
 # purely because install-resources.mjs deploys the whole resources/ directory
@@ -38,7 +38,7 @@ SELF_DIR="$(cd "$(dirname "$SELF_PATH")" && pwd)"
 #
 # WHY THIS FUNCTION EXISTS AT ALL: a fixed `".."` hop (`REPO_ROOT="$(cd
 # "$(dirname "$SELF_PATH")/.." && pwd)"`) is wrong from this launcher's own
-# location, `.claude/mcp/vice/resources/` -- four levels below the repo root,
+# location, `src/mcp/vice/resources/` -- four levels below the repo root,
 # not one. NOTHING would error on a wrong fixed hop count: the script would
 # just read a permanently-empty `.vice-supervisor` state directory forever,
 # and restart detection would quietly stop working while every command kept
@@ -73,7 +73,7 @@ _REPO_ROOT_WARNED_NO_MARKER=0
 #      paths.
 #   4. Otherwise, a location-shaped last resort, also with a one-time stderr
 #      note: FOUR levels up when <absolute-dir>'s own directory is named
-#      `resources` (matching `<root>/.claude/mcp/vice/resources`),
+#      `resources` (matching `<root>/src/mcp/vice/resources`),
 #      ONE level up otherwise.
 resolve_repo_root() {
   local from="$1" dir parent base