@henols/vice-mcp 0.1.12 → 0.2.1

package/r2000-verify.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// r2000-verify.ts -- the ONE place that interprets regenerator2000's
+// `--verify` output.
+//
+// WHY PARSING IS REQUIRED AT ALL (D-10, the concrete incident): with ACME
+// absent from PATH and ca65 present, a real `regenerator2000 0.9.20 --verify`
+// run on this host printed
+//
+//   ✗ ACME — ACME not found in PATH (skipped)
+//   ✓ All roundtrip verifications passed.
+//   EXIT=0
+//
+// -- exit 0, and a summary line that reads as a full pass, while the one
+// assembler this project actually cares about (`!cpu 6510`, ACME 0.97) never
+// ran at all. Trusting the exit code here would let ACME be silently
+// skipped and still report success. This is the WHAT-NOT-TO-DO for any
+// future edit to this file: never derive `ok` from `status`, ever, no
+// matter how tempting a bare zero-exit-status check looks. The verdict this
+// module produces comes ONLY from parsing the per-assembler result lines
+// and reading ACME's own line -- never from the process exit code, and
+// never from the aggregate "All roundtrip verifications passed." summary
+// line, which is itself the thing that lied in the transcript above.
+//
+// Both captured transcripts (the honest pass and this exact false-pass trap)
+// are pinned verbatim as fixtures in r2000-verify.test.ts, so a future
+// "simplification" back to an exit-code check fails a unit test immediately.
+//
+// WR-04 (10-REVIEW.md, fixed in plan 11-01): the verdict must also never
+// trust just the FIRST ACME result line. `acmeVerdict()` used to select
+// ACME's line with a bare array .find() over the first matching entry, so
+// a transcript containing both a
+// passing and a failing ACME line (a shape --verify has never printed as of
+// 0.9.20, but one this defensive parser is explicitly meant to survive)
+// reported `ok: true` from the first (passing) line while discarding the
+// later failure -- exactly the "misleading success" this module exists to
+// refuse. The fix requires UNANIMITY: every parsed ACME line must be `ok`,
+// the first non-ok line (if any) drives the verdict, and if more than one
+// ACME line is present after passing that check, the module refuses to
+// guess which one is authoritative rather than picking one arbitrarily.
+// Both the mixed-transcript case and the too-many-ACME-lines case are pinned
+// verbatim as fixtures in r2000-verify.test.ts.
+//
+// Import nothing from `hostpath.ts`/`containerpath.ts` -- plan 10-01's
+// absence assertion in `hostpath-consumers.test.ts` already names this file.
+
+import { buildVerifyArgs, runR2000 } from "./r2000-launch.ts";
+
+/** The three possible outcomes for a single per-assembler `--verify` result
+ * line. `"skipped"` and `"ok"` are DIFFERENT outcomes and must never be
+ * conflated -- a skipped assembler did not run, so it proves nothing, while
+ * an `ok` assembler was actually invoked and its output byte-diffed. */
+export type AssemblerOutcome = "ok" | "skipped" | "failed";
+
+export interface VerifyLine {
+  assembler: string;
+  outcome: AssemblerOutcome;
+  detail: string;
+}
+
+// Matches exactly a per-assembler result line, e.g.:
+//   ✓ ACME — byte-identical (44 bytes)
+//   ✗ 64tass — 64tass not found in PATH (skipped)
+// Tolerates an em-dash (U+2014), en-dash (U+2013) or plain hyphen as the
+// separator, since only the ACME verdict is load-bearing here and the exact
+// glyph regenerator2000 prints is an upstream formatting detail, not
+// something this parser should be brittle against. Deliberately does NOT
+// match the aggregate "✓ All roundtrip verifications passed." summary line
+// (no separator token present there) or the "EXIT=N" line some transcripts
+// carry -- both are excluded from the returned array by construction, not
+// by a special-cased skip: they simply never match this shape.
+const VERIFY_LINE_PATTERN = /^[✓✗]\s+(.+?)\s+[—–-]\s+(.+)$/;
+
+/**
+ * Parses `regenerator2000 --verify`'s stdout into one `VerifyLine` per
+ * per-assembler result line. The aggregate `✓ All roundtrip verifications
+ * passed.` line is a summary, not an assembler line -- it never matches
+ * `VERIFY_LINE_PATTERN` (no `—`/`-` separator), so it is excluded from the
+ * result by construction rather than filtered out after the fact.
+ */
+export function parseVerifyOutput(stdout: string): VerifyLine[] {
+  const lines: VerifyLine[] = [];
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(VERIFY_LINE_PATTERN);
+    if (!match) continue;
+    const [, assemblerRaw, detailRaw] = match;
+    const assembler = assemblerRaw!.trim();
+    const detail = detailRaw!.trim();
+    // A "(skipped)" suffix always means skipped, regardless of the leading
+    // glyph. Anything else takes its outcome from the leading glyph: a
+    // leading ✓ is "ok", any other non-skipped result line is "failed" --
+    // this project has never observed a real ACME/ca65 failure transcript,
+    // but a future one must not silently parse as "ok".
+    const outcome: AssemblerOutcome = /\(skipped\)\s*$/i.test(detail)
+      ? "skipped"
+      : trimmed.startsWith("✓")
+        ? "ok"
+        : "failed";
+    lines.push({ assembler, outcome, detail });
+  }
+  return lines;
+}
+
+/**
+ * Derives the ACME-specific verdict from a parsed line set. `ok` only when
+ * at least one ACME line exists, EVERY parsed ACME line has outcome `"ok"`
+ * (unanimity -- WR-04), AND exactly one ACME line is present. A missing
+ * ACME line, any ACME line with outcome `"skipped"` or `"failed"`, and more
+ * than one `"ok"` ACME line each return `ok: false` with a distinct,
+ * quotable reason -- never conflate "skipped" with "passed", never let a
+ * passing line hide a later failing one, and never fall back to the summary
+ * line (which this module never even parses as a VerifyLine, see
+ * `parseVerifyOutput`).
+ */
+export function acmeVerdict(lines: VerifyLine[]): { ok: boolean; reason: string } {
+  const acmeLines = lines.filter((l) => l.assembler.toLowerCase() === "acme");
+
+  if (acmeLines.length === 0) {
+    return {
+      ok: false,
+      reason:
+        "no ACME line found in --verify output -- ACME was never invoked at all, which is a failure, " +
+        "not an absence of evidence",
+    };
+  }
+
+  // First non-ok line wins -- so a passing ACME line earlier in the
+  // transcript can never hide a failing one later in it (WR-04).
+  const bad = acmeLines.find((l) => l.outcome !== "ok");
+
+  if (bad?.outcome === "skipped") {
+    return {
+      ok: false,
+      reason:
+        `ACME was skipped, not run -- "${bad.detail}". A skipped ACME is a failure, never a pass ` +
+        `(D-10): --verify can print "✓ All roundtrip verifications passed." and exit 0 even when ` +
+        `ACME never ran at all -- exactly the false pass observed live on this host with ACME absent ` +
+        `and ca65 present.`,
+    };
+  }
+
+  if (bad?.outcome === "failed") {
+    return { ok: false, reason: `ACME reported a failure: "${bad.detail}"` };
+  }
+
+  // Every ACME line is ok at this point. Still refuse to guess which one is
+  // authoritative if more than one was printed (WR-04) -- unanimous is not
+  // the same as unambiguous.
+  if (acmeLines.length > 1) {
+    return {
+      ok: false,
+      reason: `--verify printed ${acmeLines.length} ACME result lines -- refusing to guess which one is the verdict`,
+    };
+  }
+
+  return { ok: true, reason: `ACME reported: ${acmeLines[0]!.detail}` };
+}
+
+export interface VerifyProjectResult {
+  ok: boolean;
+  reason: string;
+  lines: VerifyLine[];
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Runs `regenerator2000 --verify` against `projectPath` (via
+ * `buildVerifyArgs()`/`runR2000()`, so the `--vice` scan applies here too),
+ * parses stdout, and derives `ok` from `acmeVerdict()` -- deliberately NOT
+ * from `status`. Returns the raw status and streams so a caller can print
+ * them for diagnostics, but no code path in this function ever lets a zero
+ * exit status alone make `ok` true. A warning on stderr is never treated as
+ * a failure -- only the parsed ACME result line decides the verdict.
+ */
+export function verifyProject(projectPath: string): VerifyProjectResult {
+  const argv = buildVerifyArgs({ projectPath });
+  const { status, stdout, stderr } = runR2000(argv);
+  const lines = parseVerifyOutput(stdout);
+  const verdict = acmeVerdict(lines);
+  return { ok: verdict.ok, reason: verdict.reason, lines, status, stdout, stderr };
+}

package/resources/backend-detect.mjs

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

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