@henols/vice-mcp 0.1.11 → 0.2.0

package/resources/broker-launch.mjs

@@ -26,8 +26,9 @@
 // deliberately-killed instance, and writes the per-instance boot/crash log
 // D-23 preserves at the exact path shape the retiring bash supervisor used.
 import { spawn as nodeSpawn } from "node:child_process";
-import { mkdirSync, openSync, closeSync, existsSync } from "node:fs";
+import { mkdirSync, mkdtempSync, openSync, closeSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
+import { tmpdir } from "node:os";
 // Module-level: this file, not the caller, owns the single boolean --
 // synchronous check, synchronous set, released in a finally, with no
 // `await` between the check and the set.
@@ -124,7 +125,31 @@ export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv,
                 `reach it; the default of 127.0.0.1 is the safe posture for a host-native install, widen only ` +
                 `when the MCP server itself runs in a container that must reach the host emulator\n`);
         }
-        const args = ["-binarymonitor", "-binarymonitoraddress", `ip4://${host}:${port}`];
+        // Audit item I-2 (§4.2, FINDING-C1): a broker-launched stock x64sc used
+        // to boot with Drive8Type=0 (NONE) -- nothing answers unit 8, so
+        // LOAD"*",8,1 fails ?DEVICE NOT PRESENT ERROR and the entry-point
+        // checkpoint never hits. No stock MCP tool can correct this after boot
+        // (the 38-tool stock manifest has zero resource-set names by design),
+        // so the fix must be a launch-time flag. `-default` MUST be the very
+        // first element: it is VICE's reset-to-compiled-in-defaults instruction,
+        // not an inert "these are the baselines" no-op, so any flag emitted
+        // before it (including -drive8type) is silently clobbered back to its
+        // compiled-in value. `-drive8type 1541` therefore has to come
+        // immediately after `-default`, and -- per CLAUDE.md's documented
+        // constraint -- `-default` also has to come before `-binarymonitor` or
+        // the monitor never binds and the subsequent connect hangs in the
+        // backlog looking exactly like a wedge. Confirmed sufficient live in
+        // Phase 8.1's standalone probe (08.1-WALKTHROUGH-EVIDENCE.md §4):
+        // `resourceget "Drive8Type"` moved 0 -> 1541 and a `load` over the text
+        // monitor succeeded immediately. Deliberately NOT setting
+        // -drive8truedrive / Drive8TrueEmulation here: this build's own default
+        // already reads Drive8TrueEmulation=1 (same probe), so 08.2-RESEARCH.md's
+        // primary recommendation is that only -drive8type needs adding.
+        // Assumption A3 in that doc's Assumptions Log (some other stock build
+        // might default Drive8TrueEmulation to 0) is read and deliberately not
+        // pre-emptively defended against here; plan 03's live test is what would
+        // surface it if that assumption is ever wrong on a different build.
+        const args = ["-default", "-drive8type", "1541", "-binarymonitor", "-binarymonitoraddress", `ip4://${host}:${port}`];
         if (typeof remoteMonitorPort === "number") {
             if (host !== "127.0.0.1" && !warnedRemoteMonitorBindWidened) {
                 warnedRemoteMonitorBindWidened = true;
@@ -154,7 +179,7 @@ export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv,
  * spawning, so a bad configuration value is visible rather than silently
  * mis-parsed, exactly like the bash launcher's own logging discipline. */
 function spawnAndRecordInstance(reason, port, deps) {
-    const spawnFn = deps.spawn ?? ((cmd, args) => nodeSpawn(cmd, args));
+    const spawnFn = deps.spawn ?? ((cmd, args, opts) => nodeSpawn(cmd, args, opts));
     const now = deps.now ?? (() => Date.now());
     const viceBin = deps.viceBin ?? process.env.VICE_BIN ?? "x64sc";
     const backend = deps.backend ?? "fork";
@@ -165,8 +190,52 @@ function spawnAndRecordInstance(reason, port, deps) {
         remoteMonitorPort: deps.remoteMonitorPort,
     });
     const log = deps.log ?? defaultLog;
-    log(`vice-broker: launching ${viceBin} ${viceArgs.join(" ")}`);
-    const child = spawnFn(viceBin, viceArgs);
+    // I-1 rider (audit §4.4, 08.2-02-PLAN.md Task 2): production stock
+    // launches used to set no scratch XDG_CONFIG_HOME and would read whatever
+    // vicerc the operator's own $HOME already carried -- shared with the
+    // operator's own VICE usage and with the fork build. For backend ===
+    // "stock" only, compute a fresh, isolated config dir with mkdtempSync
+    // (atomic creation, random suffix, 0700 permissions -- the primitive that
+    // makes a collision or a symlink-swap into the operator's real config
+    // unreachable) and pass it as a third options argument carrying `env`
+    // only. Never `shell: true`: the existing array-form spawn(viceBin,
+    // viceArgs) call avoids shell interpretation entirely and that property
+    // must survive this widening. For backend === "fork", spawnFn is called
+    // with NO third argument at all, so the fork path's observable behaviour
+    // stays bit-for-bit what it was (BACK-02 is a standing gate and the fork
+    // backend has been the sole production backend across all of v0.1.x).
+    //
+    // Scope boundary (do not remove this note): the production broker daemon
+    // always supplies its own deps.spawn / deps.spawnFactory, so the widened
+    // default wrapper above is dead code on the real launch paths. This
+    // function's job is only to COMPUTE the value at the one seam that should
+    // own it; the forwarding to nodeSpawn() happens at four further hops --
+    // makeLoggingSpawn() and maintainWarmFloorForRealBroker's inner
+    // stashingSpawn in vice-broker.mts, and withCrashSupervision()'s wrapper
+    // body and launchSupervised()'s defaultRealSpawn in this file. All four
+    // now forward the options argument (plan 08.2-06 closed them in this same
+    // phase, with a handleAcquire() composition test that omits
+    // buildColdSpawnFactory so an injected stub cannot fake the proof). If you
+    // add a fifth spawn hop, it must forward options too, or production stock
+    // launches silently lose their config isolation again.
+    //
+    // Scratch-dir lifetime: this function deliberately does NOT clean the
+    // directory up -- the spawned emulator process outlives this function's
+    // return and needs the directory for its whole lifetime. Per-launch
+    // scratch dirs therefore accumulate under the OS temp dir for the life of
+    // the host; this is a recorded trade-off, not an oversight. If reaping
+    // them is ever worth doing, the broker's own kill/recycle path is the
+    // component that would own it (it already knows when an instance's
+    // process has actually exited).
+    let spawnOptions;
+    let logLine = `vice-broker: launching ${viceBin} ${viceArgs.join(" ")}`;
+    if (backend === "stock") {
+        const scratchConfigDir = mkdtempSync(join(tmpdir(), "vice-broker-vicerc-"));
+        spawnOptions = { env: { ...process.env, XDG_CONFIG_HOME: scratchConfigDir } };
+        logLine += ` (XDG_CONFIG_HOME=${scratchConfigDir})`;
+    }
+    log(logLine);
+    const child = spawnOptions === undefined ? spawnFn(viceBin, viceArgs) : spawnFn(viceBin, viceArgs, spawnOptions);
     const record = {
         port,
         url: `http://127.0.0.1:${port}/mcp`,
@@ -422,6 +491,14 @@ function binmonRequest(commandType, requestId) {
     header[10] = commandType;
     return header;
 }
+/** The wire's own "this is not a reply to any request I sent" sentinel
+ * (CLAUDE.md's Protocol constraint) -- REGISTER_INFO (0x31) arrives
+ * unsolicited at THIS id on every monitor open, and CHECKPOINT_INFO/STOPPED/
+ * RESUMED/JAM can too. A response-type byte alone is not enough to
+ * distinguish "an event that happens to share a type with a real reply" from
+ * an actual reply -- request-id is the only field the wire promises never
+ * collides between the two, which is exactly why demux must key on it. */
+const BINMON_UNSOLICITED_REQUEST_ID = 0xffffffff;
 /**
  * WR-01: one PING (0x81) over the binary monitor, requiring a WELL-FORMED 0x81
  * reply -- STX, the expected api_version, response type 0x81, error code 0x00,
@@ -429,6 +506,23 @@ function binmonRequest(commandType, requestId) {
  * here for exactly the reason probeReady()'s own comment gives for the HTTP
  * route: a C64 can accept a connection before it has finished booting.
  *
+ * quick task 260818-obc (live-discovered): a NEW binmon connection ALWAYS
+ * emits an unsolicited REGISTER_INFO (0x31) frame at request-id 0xffffffff
+ * the instant it opens (CLAUDE.md's own Protocol constraint) -- BEFORE this
+ * probe's own PING reply ever arrives. The naive "the first 12 bytes ARE the
+ * reply" read this code used to do treated that event frame's OWN response-
+ * type byte (0x31) as a malformed PING reply and answered `false` forever,
+ * live-reproduced against a real crash-respawned stock x64sc: the respawn
+ * never left "launching" because THIS probe could never see it as ready,
+ * even though the emulator was genuinely up and answering fine underneath.
+ * The fix walks frame boundaries using each frame's own body-length field and
+ * discards every frame whose request-id is the unsolicited sentinel (or
+ * simply is not this probe's own id) rather than assuming the first frame
+ * on the wire is the reply -- the same "demux by request-id, never by
+ * arrival order" discipline CLAUDE.md's Protocol constraint already requires
+ * of every OTHER binmon consumer in this tree (stock-protocol.ts's
+ * ViceMonitorClient chief among them).
+ *
  * Then EXIT (0xaa), unconditionally, before closing -- because the PING ITSELF
  * HALTS THE MACHINE. Any inbound byte does (docs/phase0-binmon-findings.md §4,
  * and CR-02, which fixed the same omission in the connect handshake). A
@@ -470,31 +564,52 @@ async function defaultBinmonProbe(port, timeoutMs) {
         });
         socket.on("data", (chunk) => {
             buffer = Buffer.concat([buffer, chunk]);
-            if (buffer.length < BINMON_RESPONSE_HEADER_LEN)
-                return;
-            const wellFormed = buffer[0] === BINMON_STX &&
-                buffer[1] === BINMON_API_VERSION &&
-                buffer[6] === BINMON_CMD_PING &&
-                buffer[7] === 0x00 &&
-                buffer.readUInt32LE(8) === BINMON_PROBE_REQUEST_ID;
-            if (!wellFormed) {
-                finish(false);
+            // Walk complete frames off the front of the buffer -- never assume the
+            // first BINMON_RESPONSE_HEADER_LEN bytes on the wire are this probe's
+            // own reply (see this function's own header comment on why an
+            // unsolicited event frame can and does arrive first in practice).
+            for (;;) {
+                if (buffer.length < BINMON_RESPONSE_HEADER_LEN)
+                    return; // wait for more data
+                const bodyLen = buffer.readUInt32LE(2);
+                const frameLen = BINMON_RESPONSE_HEADER_LEN + bodyLen;
+                if (buffer.length < frameLen)
+                    return; // header seen, body still incoming
+                const responseType = buffer[6];
+                const errorCode = buffer[7];
+                const requestId = buffer.readUInt32LE(8);
+                const stxOk = buffer[0] === BINMON_STX && buffer[1] === BINMON_API_VERSION;
+                if (!stxOk) {
+                    finish(false);
+                    return;
+                }
+                if (requestId === BINMON_UNSOLICITED_REQUEST_ID || requestId !== BINMON_PROBE_REQUEST_ID) {
+                    // Not a reply to anything this probe sent (an unsolicited event, or
+                    // a stale reply to a previous probe's own request id) -- discard
+                    // this one frame only and keep walking the rest of the buffer.
+                    buffer = buffer.subarray(frameLen);
+                    continue;
+                }
+                if (responseType !== BINMON_CMD_PING || errorCode !== 0x00) {
+                    finish(false);
+                    return;
+                }
+                // Resume the machine this probe's own PING halted, then close GRACEFULLY:
+                // socket.end(data, cb) writes the EXIT and then sends FIN, so the bytes
+                // are delivered before the connection goes away. A bare write() followed
+                // by destroy() can discard them (destroy may RST), which would leave the
+                // instance "ready" and frozen -- the exact outcome the EXIT exists to
+                // prevent. The resume is best-effort in its OUTCOME, though: a failed
+                // resume must not turn a READY instance into a not-ready one, since the
+                // emulator demonstrably answered, which is what this function reports on.
+                try {
+                    socket.end(binmonRequest(BINMON_CMD_EXIT, BINMON_PROBE_REQUEST_ID + 1), () => finish(true));
+                }
+                catch {
+                    finish(true);
+                }
                 return;
             }
-            // Resume the machine this probe's own PING halted, then close GRACEFULLY:
-            // socket.end(data, cb) writes the EXIT and then sends FIN, so the bytes
-            // are delivered before the connection goes away. A bare write() followed
-            // by destroy() can discard them (destroy may RST), which would leave the
-            // instance "ready" and frozen -- the exact outcome the EXIT exists to
-            // prevent. The resume is best-effort in its OUTCOME, though: a failed
-            // resume must not turn a READY instance into a not-ready one, since the
-            // emulator demonstrably answered, which is what this function reports on.
-            try {
-                socket.end(binmonRequest(BINMON_CMD_EXIT, BINMON_PROBE_REQUEST_ID + 1), () => finish(true));
-            }
-            catch {
-                finish(true);
-            }
         });
     });
 }
@@ -849,8 +964,11 @@ async function handleExit(reason, port, deps) {
 }
 /** The single exit-listener installation point in the whole module tree.
  * Wraps `baseSpawn` (a plain spawn function of the same shape
- * `(command, args) => ChildProcess` every launch path already threads
- * through) so the returned spawn function, when called, attaches a
+ * `(command, args, options?) => ChildProcess` every launch path already
+ * threads through -- the third `options` argument is load-bearing: it
+ * carries the scratch XDG_CONFIG_HOME that isolates a stock launch from the
+ * operator's real vicerc, and this wrapper MUST forward it) so the returned
+ * spawn function, when called, attaches a
  * one-shot "exit" listener that drives handleExit() above -- the SAME
  * respawn/give-up/deliberate-teardown resolution launchSupervised()'s own
  * relaunch path already uses. Returns the child object baseSpawn produced,
@@ -866,8 +984,13 @@ async function handleExit(reason, port, deps) {
  * a second inline listener, is what keeps the "exactly one installation
  * point" invariant a structural gate (broker-launch.test.ts) can hold. */
 export function withCrashSupervision(reason, port, baseSpawn, deps) {
-    return (cmd, args) => {
-        const child = baseSpawn(cmd, args);
+    // I-1 rider (08.2-06-PLAN.md, Task 1): forwards a third options argument
+    // in the BODY, not just the type -- this is the hop that matters most,
+    // because it wraps every real launch path (cold acquire, warm floor, and
+    // every respawn). A type-only widening would still silently drop a
+    // caller's options at this call site.
+    return (cmd, args, options) => {
+        const child = baseSpawn(cmd, args, options);
         child.once("exit", () => {
             void handleExit(reason, port, deps);
         });
@@ -914,9 +1037,18 @@ function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonit
     const logFileName = `${basename(viceBin)}-${Date.now()}-e${epoch}.log`;
     const logPath = join(logDir, logFileName);
     const logRelPath = `logs/${logFileName}`;
-    const defaultRealSpawn = (cmd, args) => {
+    // I-1 rider (08.2-06-PLAN.md, Task 1): forwards a third options argument
+    // and MERGES it with the per-instance log stdio -- caller options
+    // spread FIRST, `stdio` set LAST, so the per-instance log fd always
+    // wins. Never the other order: a caller-supplied `stdio` would silently
+    // redirect a crash-respawn's output away from the log file the epoch
+    // record names, and the forensic per-instance log (D-23) would point at
+    // a file that received nothing. Without this fix, a stock instance that
+    // crashes and respawns comes back reading the operator's real `vicerc`
+    // even though its original launch was isolated.
+    const defaultRealSpawn = (cmd, args, options) => {
         const fd = openSync(logPath, "a");
-        return nodeSpawn(cmd, args, { stdio: ["ignore", fd, fd] });
+        return nodeSpawn(cmd, args, { ...options, stdio: ["ignore", fd, fd] });
     };
     const baseSpawn = deps.spawnFactory ? deps.spawnFactory(port) : (deps.spawn ?? defaultRealSpawn);
     const wrappedSpawn = withCrashSupervision(reason, port, baseSpawn, deps);

package/resources/vice-broker.mjs

@@ -184,14 +184,22 @@ function writeBrokerRecordFile(stateDir, record) {
  * closure and the log's path relative to supervisorDir (the epoch
  * record's own `log` field). Shared by both launch paths -- a cold
  * acquire and warm-floor maintenance -- so there is exactly one place that
- * opens a launch log fd. */
+ * opens a launch log fd.
+ *
+ * I-1 rider (08.2-06-PLAN.md, Task 2): the returned `spawn` now also
+ * forwards a caller options object (audit item I-1), MERGING it into the
+ * object handed to nodeSpawn() -- caller options spread FIRST, `stdio` set
+ * LAST, so the launch log fd always wins over any 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
+ * D-23's forensic logs while appearing to work. */
 function makeLoggingSpawn(logDir) {
     mkdirSync(logDir, { recursive: true });
     const viceBinForLog = basename(process.env.VICE_BIN ?? "x64sc");
     const logName = `${viceBinForLog}-${Date.now()}.log`;
     const logFd = openSync(join(logDir, logName), "a");
     return {
-        spawn: (cmd, cmdArgs) => nodeSpawn(cmd, cmdArgs, { stdio: ["ignore", logFd, logFd] }),
+        spawn: (cmd, cmdArgs, options) => nodeSpawn(cmd, cmdArgs, { ...options, stdio: ["ignore", logFd, logFd] }),
         logRelPath: `logs/${logName}`,
     };
 }
@@ -684,8 +692,12 @@ function maintainWarmFloorForRealBroker(stateDir, state, backend) {
         spawnFactory: (port) => {
             const supervisorDir = join(stateDir, String(port));
             const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"));
-            const stashingSpawn = (cmd, args) => {
-                const child = spawn(cmd, args);
+            // I-1 rider (08.2-06-PLAN.md, Task 2): forwards a third options
+            // argument -- this is a SECOND, independent dropper on the
+            // warm-floor arm; fixing only makeLoggingSpawn above would leave
+            // this arm's own scratch XDG_CONFIG_HOME dropped right here.
+            const stashingSpawn = (cmd, args, options) => {
+                const child = spawn(cmd, args, options);
                 // Stash the log path where onLaunched (fired synchronously right
                 // after this returns, still within the SAME maintainWarmFloor()
                 // call -- at most one launch per call, per the serialised-warming
@@ -720,6 +732,15 @@ function maintainWarmFloorForRealBroker(stateDir, state, backend) {
         log: (line) => process.stderr.write(`${line}\n`),
     });
 }
+/** Exported ONLY so a test can drive the warm-floor arm's REAL spawn
+ * composition (this function's own makeLoggingSpawn()+stashingSpawn+
+ * withCrashSupervision() closure above) through the built artifact, the
+ * same escape-hatch pattern `_superviseDepsFor` already establishes for the
+ * respawn composition -- see vice-broker-acquire.test.ts's I-1 composition
+ * tests (08.2-06-PLAN.md, Task 3), which call this directly with no spawn
+ * override so the warm floor's own independent `stashingSpawn` dropper
+ * cannot hide behind an injected stub. */
+export const _maintainWarmFloorForRealBroker = maintainWarmFloorForRealBroker;
 /** Releases a grant and identity-verified-kills its instance -- but ONLY
  * when the port's CURRENT occupant is proven to be the SAME process this
  * grant was actually issued for (its own recorded `pid`, set at grant time