@henols/vice-mcp 1.0.0 → 1.1.0

package/resources/vice-broker.mjs

@@ -139,9 +139,6 @@ function resolveCeilingForRecord() {
     const n = Number(raw);
     return Number.isFinite(n) ? n : 16;
 }
-function resolveViceBinForHostState() {
-    return process.env.VICE_BIN ?? "x64sc";
-}
 /** Duplicates vice-broker-client.ts's readBrokerLiveness() classification
  * logic (never_started / stale / alive against BROKER_STALE_MS) rather than
  * importing it -- confirmed empirically (plan 02's own SUMMARY) that
@@ -218,10 +215,17 @@ function writeBrokerRecordFile(stateDir, record) {
  * caller-supplied `stdio`. Merging in the other order would silently
  * redirect a launch's output away from the per-instance log file the
  * epoch record names, breaking the per-instance forensic logs while
- * appearing to work. */
-function makeLoggingSpawn(logDir) {
+ * appearing to work.
+ *
+ * `viceBin` (Phase 60, LOC-02) names the ALREADY-resolved binary this launch
+ * is about to spawn -- the log filename's own stem, via `basename()`, rather
+ * than a fresh read of the emulator environment variable on its own.
+ * Optional, defaulting to the literal "x64sc" for a caller (a test) that
+ * supplies neither this nor a real resolution up its own call chain, so the
+ * filename shape is unchanged for it. */
+function makeLoggingSpawn(logDir, viceBin) {
     mkdirSync(logDir, { recursive: true });
-    const viceBinForLog = basename(process.env.VICE_BIN ?? "x64sc");
+    const viceBinForLog = basename(viceBin ?? "x64sc");
     const logName = `${viceBinForLog}-${Date.now()}.log`;
     const logFd = openSync(join(logDir, logName), "a");
     return {
@@ -291,13 +295,25 @@ function writeEpochForLaunch(record, logRelPath) {
  * always `undefined` in production right now; the parameter exists so that
  * adding one later cannot reintroduce exactly this divergence between a
  * launch's argv and its respawn's argv. */
-function superviseDepsFor(stateDir, state, backend, binmonHost) {
+/** Phase 60 (LOC-01/LOC-02): `viceBin` is now a REQUIRED-in-spirit fourth
+ * argument (kept optional only for source compatibility with a caller that
+ * has none to give) -- before this plan, a crash respawn's own
+ * SuperviseChildDeps.viceBin was silently left unset here, and
+ * broker-launch.mts's own launchSupervised() covered the gap by falling
+ * through to a fresh read of the emulator environment variable. That fallback is gone (see
+ * broker-launch.mts's own header for why); leaving this builder unchanged
+ * would have made a crash-respawned instance silently spawn the bare
+ * "x64sc" literal instead of the SAME binary a tools.json entry or
+ * VICE_BIN resolved for the launch it replaces -- exactly the
+ * disagreement LOC-02 exists to remove. */
+function superviseDepsFor(stateDir, state, backend, viceBin, binmonHost) {
     return {
         state,
         stateDir,
         epoch: { epochPathFor, instanceLogDirFor, nextEpochFor, writeEpochRecord },
         log: (line) => process.stderr.write(`${line}\n`),
         backend,
+        viceBin,
         binmonHost,
     };
 }
@@ -526,6 +542,10 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
     // verdict handleAcquire already uses for buildViceArgs() -- on stock the port
     // speaks the binary monitor, so an HTTP POST there can never succeed.
     const backend = deps.backend ?? "stock";
+    // Same threaded-down-once discipline as `backend` immediately above --
+    // this function never resolves it itself. See HandleAcquireDeps.viceBin's
+    // own doc comment.
+    const viceBin = deps.viceBin;
     const probe = deps.probe ?? ((port) => probeReady(port, { backend }));
     // Textually a verifiedKill( call site, not merely a reference -- reused
     // UNCHANGED from broker-kill.mts, never re-derived, and never replaced by
@@ -560,6 +580,11 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             // supervision deps below, so a crash-respawn of this instance can never
             // build a different backend's argv than the launch it replaces.
             backend,
+            // The SAME local `viceBin` const, threaded down unchanged -- see this
+            // function's own binding above and HandleAcquireDeps.viceBin's doc
+            // comment. `undefined` here is exactly what broker-launch.mts's own
+            // "x64sc"-literal default is for.
+            viceBin,
             allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
             // The profile the warm arm just
             // refused to compromise on reaches buildViceArgs() here, and is
@@ -572,9 +597,9 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             spawnFactory: deps.buildColdSpawnFactory ??
                 ((port) => {
                     const supervisorDir = join(stateDir, String(port));
-                    const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"));
+                    const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"), viceBin);
                     lastLogRelPath = logRelPath;
-                    return withCrashSupervision("acquire", port, spawn, superviseDepsFor(stateDir, state, backend));
+                    return withCrashSupervision("acquire", port, spawn, superviseDepsFor(stateDir, state, backend, viceBin));
                 }),
         });
         if (!result.ok) {
@@ -947,10 +972,38 @@ async function run(args) {
     // There is nothing left to detect -- the resolved
     // `backend` is always `"stock"`; what this call still does is resolve the
     // binary's own identity for the log line below and initialise the
-    // capability cache backend-detect.mts's own record depends on.
-    const backendResult = resolvedBackend({ supervisorDir: args.stateDir });
+    // capability cache backend-detect.mts's own record depends on. Phase 60
+    // (LOC-01/LOC-02): `toolsDir`/`projectRoot` are passed explicitly rather
+    // than left to backend-detect.mts's own supervisorDir-derived fallback
+    // (PD-03) -- this IS the one real call site with a genuine repoRoot to
+    // hand it, so there is no reason to make it guess. This is the ONE call
+    // in the whole real broker that ever reaches the tool-location seam; the
+    // resolved value below is threaded down through every real launch call
+    // site from here, never re-resolved per acquire.
+    const backendResult = resolvedBackend({
+        supervisorDir: args.stateDir,
+        toolsDir: join(args.repoRoot, ".c64-re-tools"),
+        projectRoot: args.repoRoot,
+    });
     const backend = backendResult.backend;
+    // The ONE value this process ever spawns as the emulator binary --
+    // resolved once, here, and threaded down through HandleAcquireDeps.viceBin
+    // (below) and onHostState's own `viceBin` field (task 2). Never re-read
+    // from resolvedBackend() a second time and never re-derived locally.
+    const resolvedViceBin = backendResult.binPath;
     process.stderr.write(`vice-broker: backend "${backend}" (binary: ${backendResult.binPath})\n`);
+    // Phase 60 gap closure (LOC-03, PD-13/T-60-15): written only when the
+    // tool-location seam refused a declared environment-variable override --
+    // `backendResult.locationRefusal` is `null` in every other case, including
+    // the PD-02 injected-override branch, which never reaches the seam at
+    // all. This is the ONE readable record a host operator has of "which
+    // binary did this broker refuse to substitute, and why" -- no throw here:
+    // this process's own uncaught-exception handlers kill the whole pool, and
+    // only one of this broker's callers (the emulator spawn itself) needed
+    // this value to be correct.
+    if (backendResult.locationRefusal !== null) {
+        process.stderr.write(`vice-broker: ${backendResult.locationRefusal}\n`);
+    }
     // THE BROKER mints/verifies the
     // Ghidra runs-root handle here -- after the unconditional startup reap
     // above, and BEFORE the control listener below accepts a single
@@ -989,6 +1042,20 @@ async function run(args) {
             token,
             onAcquire: (requestId, profile) => handleAcquire(requestId, args.stateDir, state, {
                 backend,
+                // The ONCE-resolved `resolvedViceBin` local from this function's
+                // own top (LOC-01/LOC-02) -- found missing here by Plan 60-05's
+                // own required full-suite baseline diff (broker-e2e.test.ts's
+                // "wired disconnect-while-queued" case): this real onAcquire
+                // wiring is the ONE production call site that turns a tools.json
+                // or VICE_BIN resolution into what the broker actually spawns,
+                // and it was never supplying `viceBin` at all -- every unit test
+                // calling handleAcquire() directly injects `viceBin` itself, so
+                // this gap was invisible until an end-to-end, real-process test
+                // exercised the genuine `run()` wiring. Without this, every real
+                // acquire silently fell through to broker-launch.mts's own
+                // "x64sc"-literal last-resort default, regardless of what
+                // tools.json or VICE_BIN named.
+                viceBin: resolvedViceBin,
                 // Threaded down to
                 // acquirePortAndLaunch()'s own gate (backend === "stock"); this
                 // callback does not re-read any environment variable itself.
@@ -1026,7 +1093,13 @@ async function run(args) {
                 pid: process.pid,
                 startedAt,
                 nodeVersion: process.version,
-                viceBin: resolveViceBinForHostState(),
+                // The SAME value THIS process just spawned (this function's own
+                // `resolvedViceBin` closure binding, above) -- the deleted
+                // per-host-state helper this file used to call here re-read the
+                // emulator environment variable fresh on every call, which could
+                // report a DIFFERENT binary than the one this broker actually
+                // launched -- exactly the disagreement LOC-02 exists to remove.
+                viceBin: resolvedViceBin,
                 maxInstances: resolveCeilingForRecord(),
                 basePort: resolveBasePort(),
                 // The verdict THIS process resolved once, at

package/stock-checkpoints.ts

@@ -14,8 +14,8 @@
 // and a re-set must be refused rather than silently doubling up. Separately,
 // a `stop:false` checkpoint emits a CHECKPOINT_INFO frame per hit
 // SYNCHRONOUSLY, from inside the emulator's CPU loop, over the blocking
-// monitor socket (docs/phase0-binmon-findings.md §1; mon_breakpoint.c:557-562
-// calls mon_breakpoint_event() before checking cp->stop) -- on a hot address
+// monitor socket -- confirmed directly from VICE's own source: mon_breakpoint.c:557-562
+// calls mon_breakpoint_event() before checking cp->stop -- so on a hot address
 // this can stall the emulator thread and deadlock this client. Both guards
 // are correctness-as-safety issues, not polish, so they belong in the same
 // module as the tools that create the hazard.

package/stock-connect.ts

@@ -67,8 +67,9 @@ export interface StockConnectBrokerControl {
 
 // ---------------------------------------------------------------------------
 // Capabilities -- BACK-04's version-gated answer set. Today this is just
-// CPUHISTORY_GET's three-way outcome (docs/phase0-binmon-findings.md §5,
-// D-10): 0x00 OK on the 3.10 fork, 0x83 INVALID_TYPE (opcode absent) on
+// CPUHISTORY_GET's three-way outcome, confirmed by probing both a stock
+// 3.9 build and the fork's 3.10-vintage build over the wire (D-10): 0x00 OK
+// on the 3.10 fork, 0x83 INVALID_TYPE (opcode absent) on
 // stock 3.9, 0x8f CMD_FAILURE (compiled without support) as the distinct
 // third case. A later plan adding a second version-gated opcode extends this
 // type, not a parallel mechanism.
@@ -327,12 +328,12 @@ async function safeDisconnect(client: ViceMonitorClient): Promise<void> {
 
 /**
  * CR-02 (code review 2026-08-13). THE load-bearing counterpart to every
- * command this handshake sends. docs/phase0-binmon-findings.md §4, read from
- * VICE's own source, is explicit: `monitor_check_binary()` calls
- * `monitor_startup_trap()` on ANY INBOUND BYTE (monitor_binary.c:281), and
- * that check runs every vsync -- so the bare `PING` (0x81) below halts the
- * emulated C64 within roughly one frame and emits `STOPPED` (0x62). `EXIT`
- * (0xaa) is the ONLY thing that resumes it.
+ * command this handshake sends. Confirmed by reading directly from VICE's
+ * own source rather than any external summary: `monitor_check_binary()`
+ * calls `monitor_startup_trap()` on ANY INBOUND BYTE (monitor_binary.c:281),
+ * and that check runs every vsync -- so the bare `PING` (0x81) below halts
+ * the emulated C64 within roughly one frame and emits `STOPPED` (0x62).
+ * `EXIT` (0xaa) is the ONLY thing that resumes it.
  *
  * Before this function existed, nothing in this tree ever sent 0xaa: the
  * first `vice_ping` on the stock backend froze the machine and left it frozen
@@ -431,8 +432,9 @@ export async function stockConnect({ host, port, targetId, brokerControl, deps =
     // Step 3: api_version assertion. A non-0x02 api_version rejects this
     // send() call directly with a StockFramingError naming the observed
     // value -- see this function's own header comment. NOTE (CR-02): this
-    // single byte HALTS the emulated machine (any inbound byte does --
-    // docs/phase0-binmon-findings.md §4); step 7's EXIT is what undoes it.
+    // single byte HALTS the emulated machine (any inbound byte does, per
+    // monitor_check_binary()'s own vsync-driven trap -- see the CR-02
+    // comment above for the full mechanism); step 7's EXIT is what undoes it.
     await client.send(CommandType.Ping);
 
     // Step 4: build identity.

package/stock-execution.ts

@@ -7,8 +7,10 @@
 // `handleExecutionUntilReturn` as `StockSessionHandler`s -- dispatch-table
 // and manifest wiring belong to plans 03-12/03-13, not here.
 //
-// WHY THIS FILE EXISTS: docs/phase0-binmon-findings.md §4 -- ANY inbound byte
-// halts the emulated machine (`monitor_startup_trap()` runs every vsync), so
+// WHY THIS FILE EXISTS: ANY inbound byte halts the emulated machine --
+// `monitor_check_binary()` calls `monitor_startup_trap()` on every byte the
+// monitor socket receives (`monitor_binary.c:281`), and that check runs
+// every vsync -- so
 // a bare PING (0x81) is the documented, side-effect-minimal way to trigger a
 // halt on demand, and EXIT (0xaa) is the ONLY thing that resumes it. D-05
 // means this client never sends an unrequested EXIT, which in turn means an

package/stock-memory-search.ts

@@ -2,8 +2,9 @@
 // stock-memory-search.ts
 //
 // vice_memory_search / vice_memory_compare -- the DERIV-01 pair. Both are
-// DERIVED tools: the binary monitor's confirmed command set
-// (docs/phase0-binmon-findings.md §5) has no MEMORY_SEARCH or MEMORY_COMPARE
+// DERIVED tools: the binary monitor's confirmed command set -- read directly
+// out of VICE's own monitor_binary.c and reproduced by probing every opcode
+// live against genuine stock VICE -- has no MEMORY_SEARCH or MEMORY_COMPARE
 // opcode at all, so both answers are computed CLIENT-SIDE from one bounded
 // MEM_GET read per range -- the same shape stock-disassemble.ts already
 // uses. Registered through withDerivedTool("...", { needsSession: true },

package/stock-protocol.ts

@@ -73,10 +73,13 @@ export const MAX_BODY_LEN = 4 * 1024 * 1024;
 export const MAX_BUFFERED_LEN = RESPONSE_HEADER_LEN + MAX_BODY_LEN + 64 * 1024;
 
 // ---------------------------------------------------------------------------
-// Command / response / error "enums" -- one-for-one with
-// docs/phase0-binmon-findings.md §5's normative set, which is a superset of
-// the vendor's own CommandType (missing RESOURCE_GET/SET, CPUHISTORY_GET,
-// and USERPORT_SET).
+// Command / response / error "enums" -- one-for-one with the wire format
+// empirically confirmed against genuine stock VICE's binary monitor (every
+// opcode probed live, request and response bytes captured and matched
+// against monitor_binary.c's own encoder). This set is a superset of the
+// vendor fork's own CommandType: it is missing RESOURCE_GET/SET,
+// CPUHISTORY_GET, and USERPORT_SET, which stock supports and the fork's
+// enum simply never grew to cover.
 //
 // Deviation from the plan's literal wording ("plain TypeScript enums, not
 // `const enum`"): a real TypeScript `enum` -- plain or const -- emits
@@ -375,9 +378,11 @@ export interface EncodeRequestHeaderOptions {
   body?: Buffer;
 }
 
-/** Build the normative 11-byte binary-monitor request header
- * (docs/phase0-binmon-findings.md §5) plus body: STX, api_version, uint32 LE
- * body length, uint32 LE request id, command type byte. */
+/** Build the normative 11-byte binary-monitor request header -- the exact
+ * byte layout read directly out of VICE's own monitor_binary.c request
+ * decoder and reproduced on the wire against a genuine stock instance --
+ * plus body: STX, api_version, uint32 LE body length, uint32 LE request id,
+ * command type byte. */
 export function encodeRequestHeader({ commandType, requestId, body = Buffer.alloc(0) }: EncodeRequestHeaderOptions): Buffer {
   const header = Buffer.alloc(REQUEST_HEADER_LEN);
   header[0] = VICE_STX;
@@ -403,7 +408,8 @@ export function encodeRequestHeader({ commandType, requestId, body = Buffer.allo
 // converted to a TypeScript options-object signature matching
 // encodeRequestHeader()'s own style above. The rest are derived fresh from
 // the official VICE manual (vice-emu.sourceforge.io/vice_13.html §13) and
-// docs/phase0-binmon-findings.md §5; every encoder whose runtime BEHAVIOUR
+// from the byte layout read directly out of VICE's own monitor_binary.c
+// request decoder; every encoder whose runtime BEHAVIOUR
 // (not wire shape) is unconfirmed against a real binary says so explicitly
 // in its own JSDoc as [ASSUMED], naming the RESEARCH.md Assumptions Log
 // row -- never silently claimed as verified.
@@ -455,7 +461,10 @@ export interface MemspaceBodyOptions {
 }
 
 /** The one-byte body shared by REGISTERS_GET (0x31) and REGISTERS_AVAILABLE
- * (0x83). [CITED docs/phase0-binmon-findings.md §5] */
+ * (0x83): a single memspace byte, confirmed against monitor_binary.c's own
+ * request decoder and by a live probe against genuine stock VICE that sent
+ * each memspace value and matched the returned register set to the
+ * expected bank. */
 export function memspaceBody({ memspace }: MemspaceBodyOptions = {}): Buffer {
   return Buffer.from([memspaceByte(memspace)]);
 }
@@ -474,7 +483,8 @@ export interface MemGetBodyOptions {
  * MEM_GET (0x01) request body -- ALWAYS EXACTLY 8 BYTES:
  * `sidefx(1) start(u16LE) end(u16LE) memspace(1) bank(u16LE)`.
  * [VERIFIED against probe-binmon.mjs:268-276, this repo's own
- * offline-tested reference; CITED docs/phase0-binmon-findings.md §5]
+ * offline-tested reference, and against the field layout read directly
+ * out of monitor_binary.c's own MEM_GET request decoder]
  *
  * The body is always 8 bytes -- never shorter -- because stock VICE's
  * `monitor_binary.c` handler dereferences every one of these fields before
@@ -510,7 +520,9 @@ export interface MemSetBodyOptions {
  * MEM_SET (0x02) request body -- the same 8-byte header as memGetBody(),
  * with `sidefx` forced to `0x00` (MEM_SET has no side-effect flag on the
  * wire), then `data` appended at offset 8.
- * [VERIFIED probe-binmon.mjs:278-287; CITED docs/phase0-binmon-findings.md §5]
+ * [VERIFIED probe-binmon.mjs:278-287, and against monitor_binary.c's own
+ * MEM_SET request decoder, which reads the identical 8-byte header before
+ * the variable-length data that follows it]
  */
 export function memSetBody({ start, end, memspace, bank = 0x0000, data }: MemSetBodyOptions): Buffer {
   requireU16("start", start);
@@ -540,7 +552,9 @@ export function memSetBody({ start, end, memspace, bank = 0x0000, data }: MemSet
  * CHECKPOINT_DELETE (0x13). Not an options object (matching
  * probe-binmon.mjs:314-318's own bare-number signature) since it has
  * nothing else to validate offline.
- * [VERIFIED probe-binmon.mjs:314-318; CITED docs/phase0-binmon-findings.md §5]
+ * [VERIFIED probe-binmon.mjs:314-318, and against monitor_binary.c's own
+ * CHECKPOINT_GET/CHECKPOINT_DELETE request decoder, which reads exactly
+ * this 4-byte checkpoint number and nothing else]
  */
 export function cpNumBody(checkpointNum: number): Buffer {
   requireU32("checkpointNum", checkpointNum);
@@ -568,7 +582,9 @@ export interface CheckpointSetBodyOptions {
  * CHECKPOINT_SET (0x12) request body -- 8 bytes, or 9 when `memspace` is
  * supplied: `start(u16LE) end(u16LE) stop(1) enabled(1) operation(1)
  * temporary(1) [memspace(1)]`.
- * [VERIFIED probe-binmon.mjs:290-309; CITED docs/phase0-binmon-findings.md §5]
+ * [VERIFIED probe-binmon.mjs:290-309, and against monitor_binary.c's own
+ * CHECKPOINT_SET request decoder, which only reads the ninth memspace byte
+ * when the declared body length says it is present]
  */
 export function checkpointSetBody({
   start,
@@ -606,7 +622,9 @@ export interface CheckpointToggleBodyOptions {
 }
 
 /** CHECKPOINT_TOGGLE (0x15) request body -- 5 bytes,
- * `checkpointNum(u32LE) enabled(1)`. [CITED docs/phase0-binmon-findings.md §5] */
+ * `checkpointNum(u32LE) enabled(1)`: read directly out of monitor_binary.c's
+ * own CHECKPOINT_TOGGLE request decoder, which reads exactly these five
+ * bytes and nothing else. */
 export function checkpointToggleBody({ checkpointNum, enabled }: CheckpointToggleBodyOptions): Buffer {
   requireU32("checkpointNum", checkpointNum);
   const body = Buffer.alloc(5);
@@ -624,7 +642,9 @@ export interface ConditionSetBodyOptions {
  * CONDITION_SET (0x22) request body -- `checkpointNum(u32LE) exprLen(1)
  * expr(ASCII, NOT NUL-terminated)`.
  * [VERIFIED probe-binmon.mjs:320-332, including its own >255-byte guard,
- * ported verbatim; CITED docs/phase0-binmon-findings.md §5]
+ * ported verbatim, and against monitor_binary.c's own CONDITION_SET request
+ * decoder, which reads exprLen as a single uint8 immediately before the
+ * expression bytes]
  *
  * This is the ONLY function in this tree that ever turns condition TEXT
  * into wire bytes -- its `expression` argument must always come from
@@ -685,7 +705,8 @@ export interface RegistersSetBodyOptions {
  * REGISTERS_SET (0x32) request body -- `memspace(1) count(u16LE)` then per
  * item `itemSize(1) regId(1) value(u16LE)`, with `itemSize` always `3`
  * (the byte count following the itemSize byte itself: 1 id byte + 2 value
- * bytes). [CITED docs/phase0-binmon-findings.md §5]
+ * bytes), matching the stride monitor_binary.c's own REGISTERS_SET request
+ * decoder walks each item with.
  *
  * This is the structural inverse of this file's `ResponseType.RegisterInfo`
  * parser case (below, in the response-parsing section -- grep `case
@@ -738,8 +759,11 @@ export interface AdvanceInstructionsBodyOptions {
 
 /**
  * ADVANCE_INSTRUCTIONS (0x71) request body -- 3 bytes, `stepOver(1)
- * count(u16LE)`. [CITED docs/phase0-binmon-findings.md §5; body SHAPE also
- * exercised, with stepOver=0 only, in probe-binmon.mjs's async-events check]
+ * count(u16LE)`, confirmed byte-for-byte against monitor_binary.c's own
+ * decoder and, for the stepOver=0 case, exercised live against genuine
+ * stock VICE by probe-binmon.mjs's async-events check (the check that
+ * proved STOPPED/RESUMED events arrive interleaved with the command
+ * response rather than only after it).
  *
  * `stepOver = true`'s runtime meaning (skip a `JSR`'s subroutine as one
  * step, matching the fork's own `stepOver` field name) was live-probed
@@ -767,8 +791,10 @@ export interface KeyboardFeedBodyOptions {
 }
 
 /**
- * KEYBOARD_FEED (0x72) request body -- `textLen(1) text(bytes)`.
- * [CITED docs/phase0-binmon-findings.md §5]
+ * KEYBOARD_FEED (0x72) request body -- `textLen(1) text(bytes)`, read
+ * directly out of monitor_binary.c's own KEYBOARD_FEED request decoder,
+ * which takes a one-byte length prefix followed by exactly that many raw
+ * bytes -- no PETSCII conversion happens on the wire side.
  */
 export function keyboardFeedBody({ petscii }: KeyboardFeedBodyOptions): Buffer {
   if (petscii.length === 0) {
@@ -789,8 +815,8 @@ export interface JoyportSetBodyOptions {
 }
 
 /**
- * JOYPORT_SET (0xa2) request body -- 4 bytes, `port(u16LE) value(u16LE)`.
- * [CITED docs/phase0-binmon-findings.md §5]
+ * JOYPORT_SET (0xa2) request body -- 4 bytes, `port(u16LE) value(u16LE)`,
+ * read directly out of monitor_binary.c's own JOYPORT_SET request decoder.
  *
  * The body SHAPE is cited; the BIT MEANING of `value` (which bit is
  * up/down/left/right/fire) is [ASSUMED] -- RESEARCH.md Assumptions Log row
@@ -817,8 +843,9 @@ export interface ResetBodyOptions {
 }
 
 /**
- * RESET (0xcc) request body -- 1 byte, `resetMode`.
- * [CITED docs/phase0-binmon-findings.md §5]
+ * RESET (0xcc) request body -- 1 byte, `resetMode`, read directly out of
+ * monitor_binary.c's own RESET request decoder, which reads exactly this
+ * one byte and nothing else.
  *
  * NOT the RESOURCE_SET (0x52) power-cycle hazard CLAUDE.md warns about
  * (`MachineVideoStandard`/`VICIIModel`/`MachinePowerFrequency`, the CUT
@@ -845,7 +872,9 @@ export interface AutostartBodyOptions {
 
 /**
  * AUTOSTART (0xdd) request body -- `runAfter(1) fileIndex(u16LE)
- * filenameLen(1) filename(ASCII)`. [CITED docs/phase0-binmon-findings.md §5]
+ * filenameLen(1) filename(ASCII)`, read directly out of monitor_binary.c's
+ * own AUTOSTART request decoder, which reads the filename length as the
+ * single byte immediately following the fixed runAfter/fileIndex fields.
  *
  * AUTOSTART has NO drive-unit field at all -- a caller cannot target units
  * 9-11 through this opcode (plan 03-10 owns the refusal for those units).
@@ -871,7 +900,9 @@ export interface DumpBodyOptions {
 
 /**
  * DUMP (0x41) request body -- `saveRoms(1) saveDisks(1) filenameLen(1)
- * filename(ASCII)`. [CITED docs/phase0-binmon-findings.md §5]
+ * filename(ASCII)`, read directly out of monitor_binary.c's own DUMP
+ * request decoder, which reads the two flag bytes before the filename
+ * length prefix.
  */
 export function dumpBody({ saveRoms, saveDisks, filename }: DumpBodyOptions): Buffer {
   const filenameBuf = requireAsciiFilename("dumpBody", filename);
@@ -887,8 +918,9 @@ export interface UndumpBodyOptions {
   filename: string;
 }
 
-/** UNDUMP (0x42) request body -- `filenameLen(1) filename(ASCII)`.
- * [CITED docs/phase0-binmon-findings.md §5] */
+/** UNDUMP (0x42) request body -- `filenameLen(1) filename(ASCII)`, read
+ * directly out of monitor_binary.c's own UNDUMP request decoder, which
+ * reads the filename length as the frame's very first byte. */
 export function undumpBody({ filename }: UndumpBodyOptions): Buffer {
   const filenameBuf = requireAsciiFilename("undumpBody", filename);
   const body = Buffer.alloc(1 + filenameBuf.length);

package/stock-registers.ts

@@ -12,7 +12,9 @@
 // vice_registers_set takes a register NAME (D-03: stock keeps the fork's
 // argument shape). VICE enumerates its own register ids through
 // REGISTERS_AVAILABLE, and those ids are NOT guaranteed identical across
-// builds (docs/phase0-binmon-findings.md) -- so a caller must resolve a
+// builds -- confirmed by reading VICE's own mon_register.c, which assigns
+// ids from a per-machine table that is never pinned to a fixed numbering
+// across ports -- so a caller must resolve a
 // name through the CONNECTED build's own answer, never a table this
 // module wrote down in advance. This file is the one seam that performs
 // that resolution, caches it per session (so every call after the first

package/text-protocol.ts

@@ -301,9 +301,12 @@ export const HAZARD_SUBJECT_PRG_RELPATHS = Object.freeze({
    * `exportAsmTree()` itself emitted (`scope_087a.a`) rather than in the
    * hand-written `modified` fixture family, reassembled through the same
    * single oracle against a pre-registered byte manifest committed at
-   * `fixtures/hazard-subject/exported-edit.manifest.json`. See
-   * `docs/phase50-exported-edit-findings.md` and
-   * `docs/phase50-exported-modifiability-transcript.md`. */
+   * `fixtures/hazard-subject/exported-edit.manifest.json`. Both the
+   * rebuild and the live-behaviour gate came back acknowledged: the
+   * reassembly reproduced the manifest byte-for-byte and both behaviour
+   * changes were independently confirmed to take effect in a running
+   * genuine stock VICE session via checkpoint-driven RAM captures, not
+   * just in the rebuilt bytes on disk. */
   "exported-edit": Object.freeze([
     "src",
     "mcp",

package/textmon-profile.ts

@@ -142,13 +142,18 @@ const RULES_LINE = "------------- ------ ------------- ------";
 
 /** VICE's own cold-profiler sentence, quoted byte-for-byte -- including its
  * embedded double quotes and its trailing period -- from
- * `text-protocol.ts`'s `TEXT_COMMAND_ALLOWLIST` doc comment and
- * `docs/phase42-text-format-drift-citations.md`'s Block 9. Unlike this
+ * `text-protocol.ts`'s `TEXT_COMMAND_ALLOWLIST` doc comment. Unlike this
  * module's siblings' source-traced strings, this one is MEASURED: observed
  * live against genuine stock `x64sc (VICE 3.9)`, 2026-09-09. `prof flat`
  * alone, on a freshly connected session that has never issued `prof on`,
  * returns exactly this sentence -- the profiler subsystem is compiled in
- * and the command itself is fine, it simply has nothing recorded yet. */
+ * and the command itself is fine, it simply has nothing recorded yet. This
+ * was a genuinely new live finding, present in neither committed fixture:
+ * VICE's flat profiler defaults OFF, and no production handler in this
+ * tree issues `prof on` before dialing `prof flat`, so `vice_profile_flat`
+ * as shipped cannot yet produce real profile rows against a freshly
+ * launched instance -- a real, separately-tracked gap this live run
+ * surfaced rather than silently absorbed. */
 export const PROFILING_NOT_STARTED_TEXT = 'No profiling data available. Start profiling with "prof on".';
 
 /** The narrow no-break space (U+202F) VICE uses as its thousands separator