@henols/vice-mcp 0.1.9 → 0.1.11

package/resources/broker-launch.mjs

@@ -59,21 +59,84 @@ let inFlightReason = null;
 export function isLaunchInFlight() {
     return inFlight;
 }
-/** Resolves the emulator's own argument vector. Two shapes, matching
- * resources/vice-supervisor.sh's own VICE_ARGS convention exactly: if
- * VICE_ARGS is set in the environment (a single space-separated string,
- * fully overridable -- vice-supervisor.sh's own header comment), it is used
- * AS-IS; otherwise the MCP server flags are constructed the way the bash
- * launcher builds them -- the MCP server flag, the MCP server host from
- * VICE_BROKER_MCP_HOST (default 0.0.0.0), and the MCP server port set to
- * the allocated port. The override exists because this broker's own tests
- * (and an operator's manual dry runs) need to launch a stand-in binary
- * (e.g. /bin/sleep) that does not understand -mcpserver flags. */
-export function buildViceArgs(port, { mcpHost, viceArgsEnv } = {}) {
+// Gates the stock binmon-bind-widened stderr note below so a long-running
+// broker (or a test suite driving buildViceArgs() many times) emits it at
+// most once per process -- the repo-root.ts `warnedEnvOutsideFrom` gate
+// pattern, reused here.
+let warnedBinmonBindWidened = false;
+// Plan 03-04 (DIRECT-06, D-13): the SAME one-time-note idiom as
+// warnedBinmonBindWidened above, for the SECOND (`-remotemonitor`) port's
+// bind -- a separate boolean because the two flags widen independently (a
+// caller could widen one host override and not the other, though in
+// practice both resolve from the same `binmonHost` value below).
+let warnedRemoteMonitorBindWidened = false;
+/** Resolves the emulator's own argument vector for the given `backend`. The
+ * `VICE_ARGS` full-override short-circuit (matching
+ * resources/vice-supervisor.sh's own VICE_ARGS convention exactly) is
+ * checked FIRST, ahead of either backend branch, and stays unchanged for
+ * both: it exists because this broker's own tests (and an operator's manual
+ * dry runs) need to launch a stand-in binary (e.g. /bin/sleep) that
+ * understands neither `-mcpserver` nor `-binarymonitor` flags, and that need
+ * does not depend on which backend is configured.
+ *
+ * `backend: "fork"` returns exactly the pre-Phase-2 shape, byte-identical:
+ * the MCP server flag, the MCP server host from `mcpHost` or
+ * VICE_BROKER_MCP_HOST (default `0.0.0.0`), and the MCP server port.
+ *
+ * `backend: "stock"` returns `-binarymonitor -binarymonitoraddress
+ * ip4://<host>:<port>` (docs/phase1-probe-results.md's confirmed real-world
+ * command line). The host resolves from `binmonHost` or
+ * VICE_BROKER_BINMON_HOST, defaulting to `127.0.0.1` -- deliberately
+ * narrower than the fork path's `0.0.0.0` default, because VICE's binary
+ * monitor is unauthenticated by design and grants full read/write over the
+ * emulated machine plus process control to anything that can reach it
+ * (planner decision, `02-03-PLAN.md`). Widening the bind away from loopback
+ * emits exactly one stderr note per process, naming the resolved bind
+ * address and what the exposure grants.
+ *
+ * Plan 03-04 (DIRECT-06, D-13): when `remoteMonitorPort` is a number, the
+ * stock branch APPENDS `-remotemonitor -remotemonitoraddress
+ * ip4://<host>:<remoteMonitorPort>`, reusing the SAME resolved `host` value
+ * 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
+ * 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
+ * nothing on this port; only the launch flag lands now (see D-13's own
+ * rationale: adding the flag later would require relaunching a live
+ * instance, destroying all emulation state). */
+export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv, remoteMonitorPort, }) {
     const rawViceArgs = viceArgsEnv ?? process.env.VICE_ARGS;
     if (typeof rawViceArgs === "string" && rawViceArgs.trim() !== "") {
         return rawViceArgs.trim().split(/\s+/);
     }
+    if (backend === "stock") {
+        const host = binmonHost ?? process.env.VICE_BROKER_BINMON_HOST ?? "127.0.0.1";
+        if (host !== "127.0.0.1" && !warnedBinmonBindWidened) {
+            warnedBinmonBindWidened = true;
+            process.stderr.write(`vice-broker: stock binary-monitor bind widened to ${host} -- VICE's binary monitor is ` +
+                `unauthenticated and grants full memory read/write plus process control to anything that can ` +
+                `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}`];
+        if (typeof remoteMonitorPort === "number") {
+            if (host !== "127.0.0.1" && !warnedRemoteMonitorBindWidened) {
+                warnedRemoteMonitorBindWidened = true;
+                process.stderr.write(`vice-broker: stock text (-remotemonitor) monitor bind widened to ${host} -- VICE's text monitor ` +
+                    `accepts arbitrary monitor commands and is unauthenticated, exactly like the binary monitor; 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`);
+            }
+            args.push("-remotemonitor", "-remotemonitoraddress", `ip4://${host}:${remoteMonitorPort}`);
+        }
+        return args;
+    }
     const host = mcpHost ?? process.env.VICE_BROKER_MCP_HOST ?? "0.0.0.0";
     return ["-mcpserver", "-mcpserverhost", host, "-mcpserverport", String(port)];
 }
@@ -94,7 +157,13 @@ function spawnAndRecordInstance(reason, port, deps) {
     const spawnFn = deps.spawn ?? ((cmd, args) => nodeSpawn(cmd, args));
     const now = deps.now ?? (() => Date.now());
     const viceBin = deps.viceBin ?? process.env.VICE_BIN ?? "x64sc";
-    const viceArgs = buildViceArgs(port, { mcpHost: deps.mcpHost });
+    const backend = deps.backend ?? "fork";
+    const viceArgs = buildViceArgs(port, {
+        backend,
+        mcpHost: deps.mcpHost,
+        binmonHost: deps.binmonHost,
+        remoteMonitorPort: deps.remoteMonitorPort,
+    });
     const log = deps.log ?? defaultLog;
     log(`vice-broker: launching ${viceBin} ${viceArgs.join(" ")}`);
     const child = spawnFn(viceBin, viceArgs);
@@ -112,6 +181,7 @@ function spawnAndRecordInstance(reason, port, deps) {
         viceBin,
         viceArgs,
         dryRun: false,
+        ...(deps.remoteMonitorPort === undefined ? {} : { remoteMonitorPort: deps.remoteMonitorPort }),
     };
     deps.state.instances.set(port, record);
     return record;
@@ -188,6 +258,38 @@ export async function acquirePortAndLaunch(reason, deps) {
         const supervisorDir = join(deps.stateDir, String(port));
         const epochFile = join(supervisorDir, "epoch.json");
         const spawn = deps.spawnFactory ? deps.spawnFactory(port) : deps.spawn;
+        // Plan 03-04 (DIRECT-06, D-13): the second (`-remotemonitor`) port is
+        // resolved HERE, still inside the single in_flight owner's own
+        // try-block, immediately after the primary allocation succeeds -- both
+        // awaits stay inside this SAME try, after the guard's synchronous
+        // check-and-set above; neither is moved, duplicated, or awaited around
+        // that guard. Only ever attempted for `backend === "stock"`, and only
+        // when the caller actually provided the allocator -- every fork launch
+        // and every pre-Phase-3 caller never reaches this branch at all.
+        let remoteMonitorPort;
+        if (deps.backend === "stock" && deps.allocateRemoteMonitorPort) {
+            const remoteResult = await deps.allocateRemoteMonitorPort(deps.state, new Set([port]));
+            if (remoteResult.ok) {
+                // Assigned directly (not via broker-state.mjs's blockPort()) -- this
+                // module's own type-only import of that sibling is load-bearing
+                // (see this file's own header comment): a VALUE import would turn
+                // "./broker-state.mjs" into a real runtime resolution this file
+                // cannot satisfy when loaded directly, as this file's own unit test
+                // does. `state.blockedPorts` is a plain Set the type import already
+                // describes, so mutating it directly needs no value import at all --
+                // exactly the same discipline handleExit()'s own
+                // `record.monitorClient = undefined` uses in place of
+                // clearMonitorClient().
+                deps.state.blockedPorts.add(remoteResult.port);
+                remoteMonitorPort = remoteResult.port;
+            }
+            else {
+                // Degrade, never fail: a port nothing dials yet (Phase 3 builds no
+                // text-monitor client) must never make the backend unavailable.
+                log(`vice-broker: second (-remotemonitor) port allocation failed (${remoteResult.reason}) -- ` +
+                    `launching WITHOUT -remotemonitor; nothing in Phase 3 dials the text-monitor port anyway`);
+            }
+        }
         const record = spawnAndRecordInstance(reason, port, {
             state: deps.state,
             supervisorDir,
@@ -196,6 +298,9 @@ export async function acquirePortAndLaunch(reason, deps) {
             now: deps.now,
             viceBin: deps.viceBin,
             mcpHost: deps.mcpHost,
+            backend: deps.backend,
+            binmonHost: deps.binmonHost,
+            remoteMonitorPort,
         });
         return { ok: true, record };
     }
@@ -204,6 +309,43 @@ export async function acquirePortAndLaunch(reason, deps) {
         inFlightReason = null;
     }
 }
+/** The ONE way an instance record leaves `state.instances` for good --
+ * deleting the record AND handing its second (`-remotemonitor`) port back to
+ * the allocator in the same step.
+ *
+ * CR-02 (03-REVIEW.md): `acquirePortAndLaunch()` above adds every allocated
+ * remote-monitor port to `state.blockedPorts`, and until this function existed
+ * NOTHING ever removed one. `nextFreePort()` never reconsiders a blocked
+ * candidate for the lifetime of the process, so every teardown of a stock
+ * instance permanently consumed one more port out of the fixed
+ * PORT_SCAN_CEILING window even though the OS port was free again the instant
+ * the owning process exited -- a long-running broker (the explicit design goal
+ * of an on-demand pool with crash supervision and a warm floor) eventually
+ * exhausts its band and answers `no_free_port` to ordinary launches purely
+ * from routine churn, with no operator recourse short of a broker restart.
+ *
+ * A RESPAWN is deliberately NOT a call site: the replacement instance keeps
+ * BOTH the primary port and the remote-monitor port of the instance it
+ * replaces (launchSupervised() below threads the latter forward exactly like
+ * the port argument carries the former), so the block must stay in place for
+ * the whole chain of replacements rather than being released and immediately
+ * re-taken.
+ *
+ * Mutates `state.blockedPorts` directly rather than through a broker-state
+ * helper, for the SAME load-bearing reason acquirePortAndLaunch()'s own
+ * `blockedPorts.add` does (see this file's header comment): a VALUE import of
+ * "./broker-state.mjs" would turn a type-only dependency into a real runtime
+ * resolution this file cannot satisfy when loaded unbuilt, as its own unit
+ * test does. Callers outside this module import THIS function rather than
+ * re-deriving the pair of mutations. Idempotent, and safe for a record that
+ * never had a second port (every fork launch). */
+export function deleteInstanceRecord(state, port) {
+    const record = state.instances.get(port);
+    if (record && typeof record.remoteMonitorPort === "number") {
+        state.blockedPorts.delete(record.remoteMonitorPort);
+    }
+    state.instances.delete(port);
+}
 const DEFAULT_PROBE_TIMEOUT_S = 1;
 function defaultLog(line) {
     process.stderr.write(`${line}\n`);
@@ -240,6 +382,122 @@ async function defaultHttpProbe(port, timeoutMs) {
         clearTimeout(timer);
     }
 }
+// ---------------------------------------------------------------------------
+// WR-01: the STOCK readiness route.
+//
+// probeReady() below used to POST http://127.0.0.1:<port>/mcp unconditionally
+// and require both "version" and "machine" in the body. On the stock backend
+// that port speaks the BINARY MONITOR, so the probe could never succeed:
+// warm-floor instances stayed `launching` forever, countLaunching(state) > 0
+// short-circuited every later warm pass, and a never-usable emulator process was
+// retained until broker shutdown while still counting toward
+// countTotal()/atCapacity(). Cold acquires kept working only because the cold
+// arm grants without probing.
+//
+// WHY THE WIRE BYTES ARE HAND-BUILT HERE: stock-protocol.ts is the ONE place
+// this tree frames and DEMULTIPLEXES the binmon protocol, and this probe is
+// deliberately not a second copy of that -- it neither correlates request ids
+// nor decodes bodies. But it cannot reuse even the constants: this file is a
+// host-bound .mts compiled into resources/ by build.ts, and a .mts cannot
+// value-import a .ts module (TS5097). The same constraint already produced
+// hand-copied wire constants in binmon-fixtures.ts and a standalone client in
+// probe-binmon.mjs. What is written here is the minimum a READINESS check needs:
+// one request header out, one response header in, four bytes checked.
+// ---------------------------------------------------------------------------
+/** Hand-copied from docs/phase0-binmon-findings.md §5 -- see the block comment
+ * above for why these are not imported from stock-protocol.ts. */
+const BINMON_STX = 0x02;
+const BINMON_API_VERSION = 0x02;
+const BINMON_REQUEST_HEADER_LEN = 11;
+const BINMON_RESPONSE_HEADER_LEN = 12;
+const BINMON_CMD_PING = 0x81;
+const BINMON_CMD_EXIT = 0xaa;
+const BINMON_PROBE_REQUEST_ID = 0x0000ca11;
+function binmonRequest(commandType, requestId) {
+    const header = Buffer.alloc(BINMON_REQUEST_HEADER_LEN);
+    header[0] = BINMON_STX;
+    header[1] = BINMON_API_VERSION;
+    header.writeUInt32LE(0, 2); // no body
+    header.writeUInt32LE(requestId >>> 0, 6);
+    header[10] = commandType;
+    return header;
+}
+/**
+ * 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,
+ * and this probe's own request id. A bare TCP accept is explicitly insufficient
+ * 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.
+ *
+ * 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
+ * readiness probe that left every warm instance frozen would be a worse defect
+ * than the one it fixes: the emulator would be "ready" and stopped.
+ *
+ * Never throws -- every failure (refused, timed out, wrong reply shape, socket
+ * error) is `false`, matching defaultHttpProbe()'s own posture, so a
+ * still-booting instance simply fails THIS pass and is re-probed on the next.
+ *
+ * The socket is ALWAYS destroyed before resolving: stock VICE services exactly
+ * one binmon client, so a probe that leaked its connection would occupy the
+ * single client slot the real session needs to claim.
+ */
+async function defaultBinmonProbe(port, timeoutMs) {
+    const { createConnection } = await import("node:net");
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let buffer = Buffer.alloc(0);
+        const socket = createConnection({ host: "127.0.0.1", port });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                socket.destroy();
+            }
+            catch {
+                /* already gone */
+            }
+            resolvePromise(result);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        socket.on("error", () => finish(false));
+        socket.on("close", () => finish(false));
+        socket.on("connect", () => {
+            socket.write(binmonRequest(BINMON_CMD_PING, BINMON_PROBE_REQUEST_ID));
+        });
+        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);
+                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);
+            }
+        });
+    });
+}
 /** D-05, AS AMENDED BY P-05 -- this comment is the amendment's record, kept
  * in the exact place a three-branch description used to sit, per this
  * plan's own instruction that a code reader must meet the amendment here,
@@ -277,6 +535,14 @@ async function defaultHttpProbe(port, timeoutMs) {
 export async function probeReady(port, deps = {}) {
     const timeoutS = Number(deps.probeTimeoutSEnv ?? process.env.VICE_BROKER_PROBE_TIMEOUT_S) || DEFAULT_PROBE_TIMEOUT_S;
     const timeoutMs = timeoutS * 1000;
+    // WR-01: the route is chosen by the backend, exactly like buildViceArgs()'s
+    // own argv choice, and from the SAME threaded-down verdict. The fork arm below
+    // is byte-identical to what this function always did, including the
+    // omitted-backend default -- a fork deployment sees no behaviour change.
+    if (deps.backend === "stock") {
+        const binmonProbe = deps.binmonProbe ?? defaultBinmonProbe;
+        return binmonProbe(port, timeoutMs);
+    }
     const httpProbe = deps.httpProbe ?? defaultHttpProbe;
     return httpProbe(port, timeoutMs);
 }
@@ -325,7 +591,11 @@ function resolveCeiling(override) {
 export async function maintainWarmFloor(deps) {
     const log = deps.log ?? defaultLog;
     const now = deps.now ?? (() => Date.now());
-    const probe = deps.probe ?? ((port) => probeReady(port));
+    // WR-01: the DEFAULT probe follows this call's own backend, so a caller that
+    // threads `backend` for the launch argv and omits `probe` gets a matching
+    // readiness route rather than an HTTP POST at a binary-monitor port. An
+    // explicitly injected `probe` still wins, unchanged.
+    const probe = deps.probe ?? ((port) => probeReady(port, { backend: deps.backend ?? "fork" }));
     // Step 1: promote every "launching" instance whose probe now succeeds.
     // Runs regardless of whether a launch is in flight -- promotion and
     // speculative warming are independent concerns; an already-launched
@@ -380,11 +650,14 @@ export async function maintainWarmFloor(deps) {
         state: deps.state,
         stateDir: deps.stateDir,
         allocatePort: deps.allocatePort,
+        allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
         spawn: deps.spawn,
         spawnFactory: deps.spawnFactory,
         now: deps.now,
         viceBin: deps.viceBin,
         mcpHost: deps.mcpHost,
+        backend: deps.backend,
+        binmonHost: deps.binmonHost,
     });
     if (result.ok) {
         log(`vice-broker: warmed 1 warm instance this pass -- ${ready + 1} of ${warmFloor} ready, remainder warmed on later passes`);
@@ -491,6 +764,22 @@ async function handleExit(reason, port, deps) {
         return;
     }
     const log = deps.log ?? defaultLog;
+    // Plan 05 (BROK-02/PROTO-08): the process behind this instance's monitor
+    // socket has just exited, by every path this function can take (crash,
+    // recycle, or a deliberate teardown) -- clear the ownership record HERE,
+    // once, before any of those paths branch, so a client that died without
+    // releasing can never hold this lock forever. Redundant with the
+    // respawn/delete paths below (a fresh InstanceRecord never carries this
+    // field forward; a deleted one has no field to carry), but explicit for
+    // the same reason broker-state.mts's own header comment names this as one
+    // of the three required clearing sites. Assigned directly (not via
+    // broker-state.mjs's clearMonitorClient()) -- this module's own
+    // type-only import of that sibling (see this file's own header comment a
+    // few lines above) is load-bearing: a VALUE import would turn "./broker-
+    // state.mjs" into a real runtime resolution this file cannot satisfy when
+    // loaded directly (as broker-launch.test.ts does), rather than the
+    // compiled resources/ sibling this specifier is actually shaped for.
+    record.monitorClient = undefined;
     if (record.deliberateKill) {
         if (record.respawnAfterKill) {
             // Recycle. Capture the pre-kill state, crash history and backoff
@@ -500,7 +789,13 @@ async function handleExit(reason, port, deps) {
             const preKillState = record.state;
             const preKillCrashTimes = record.crashTimes ?? [];
             const preKillBackoffMs = record.backoffMs ?? resolveMs("VICE_RESTART_BACKOFF_S", 3, deps.initialBackoffMs);
-            const respawned = launchSupervised(reason, port, deps, preKillCrashTimes, preKillBackoffMs);
+            // CR-02 (03-REVIEW.md): the second (`-remotemonitor`) port is carried
+            // forward across the replacement exactly like the primary port is --
+            // captured BEFORE launchSupervised() overwrites this port's map entry
+            // with a brand new record, for the same reason the three values above
+            // are.
+            const preKillRemoteMonitorPort = record.remoteMonitorPort;
+            const respawned = launchSupervised(reason, port, deps, preKillCrashTimes, preKillBackoffMs, preKillRemoteMonitorPort);
             if (respawned && preKillState === "granted") {
                 respawned.state = "granted";
             }
@@ -520,7 +815,9 @@ async function handleExit(reason, port, deps) {
             deps.onOutcome?.("recycled", port);
             return;
         }
-        deps.state.instances.delete(port);
+        // CR-02: a deliberate teardown is the END of this instance -- its
+        // remote-monitor port must go back to the allocator with it.
+        deleteInstanceRecord(deps.state, port);
         deps.onOutcome?.("deliberate_teardown", port);
         return;
     }
@@ -532,7 +829,9 @@ async function handleExit(reason, port, deps) {
     if (crashTimes.length >= maxRestarts) {
         log(`vice-broker: giving up on port ${port} after ${crashTimes.length} crashes within ${crashWindowMs}ms -- ` +
             `this is not a transient crash; check VICE_ARGS and whether the port is already bound`);
-        deps.state.instances.delete(port);
+        // CR-02: giving up is likewise terminal for this instance -- release its
+        // remote-monitor port rather than leaking it out of the allocation band.
+        deleteInstanceRecord(deps.state, port);
         deps.onOutcome?.("given_up", port);
         return;
     }
@@ -541,7 +840,11 @@ async function handleExit(reason, port, deps) {
     await sleepMs(currentBackoffMs);
     const maxBackoffMs = resolveMs("VICE_RESTART_BACKOFF_MAX_S", 30, deps.maxBackoffMs);
     const nextBackoffMs = Math.min(currentBackoffMs * 2, maxBackoffMs);
-    const respawned = launchSupervised(reason, port, deps, crashTimes, nextBackoffMs);
+    // CR-02: same carry-forward as the recycle branch above -- a crash must not
+    // silently strip `-remotemonitor` (and its InstanceRecord field) off the
+    // replacement, which is what made D-13's "the instance record carries it"
+    // stop being true the first time an instance was replaced.
+    const respawned = launchSupervised(reason, port, deps, crashTimes, nextBackoffMs, record.remoteMonitorPort);
     deps.onOutcome?.(respawned ? "respawned" : "given_up", port);
 }
 /** The single exit-listener installation point in the whole module tree.
@@ -585,8 +888,17 @@ export function withCrashSupervision(reason, port, baseSpawn, deps) {
  * crashTimes/backoffMs are threaded through explicitly (not reset to
  * defaults) so a respawn's crash history and doubling backoff survive the
  * fact that spawnAndRecordInstance() creates a BRAND NEW InstanceRecord
- * object on every launch, replacing the old one at the same port key. */
-function launchSupervised(reason, port, deps, crashTimes, backoffMs) {
+ * object on every launch, replacing the old one at the same port key.
+ *
+ * CR-02 (03-REVIEW.md): `remoteMonitorPort` is threaded the SAME way and for
+ * the same reason -- it belongs to the instance, not to a single spawn of it.
+ * The replacement reuses the port the crashed/recycled process just vacated
+ * (already reserved in `state.blockedPorts`, so nothing else can have taken it
+ * meanwhile), exactly as it reuses the primary `port` argument; this function
+ * stays fully synchronous and never allocates. `undefined` is the correct
+ * value for a FIRST launch through superviseChild() and for every fork launch,
+ * which is why the parameter is optional. */
+function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonitorPort) {
     const supervisorDir = join(deps.stateDir, String(port));
     const epochFile = deps.epoch.epochPathFor(deps.stateDir, port);
     const logDir = deps.epoch.instanceLogDirFor(deps.stateDir, port);
@@ -616,6 +928,9 @@ function launchSupervised(reason, port, deps, crashTimes, backoffMs) {
         now: deps.now,
         viceBin: deps.viceBin,
         mcpHost: deps.mcpHost,
+        backend: deps.backend,
+        binmonHost: deps.binmonHost,
+        remoteMonitorPort,
         log: deps.log,
     });
     if (!record)

package/resources/broker-state.mjs

@@ -5,6 +5,15 @@
 // verbatim to tools/, so an edit made only here reaches the host but is lost on the very next
 // rebuild.
 import { createServer } from "node:net";
+/** Clears `monitorClient` as a side effect of release, recycle, or the
+ * instance's own process exit (see InstanceRecord.monitorClient's own header
+ * comment for the three call sites) -- so a dead or torn-down client can
+ * never hold this lock forever. A no-op when no monitor client is currently
+ * recorded (idempotent, matching monitor_release's own tolerance for an
+ * already-cleared record). */
+export function clearMonitorClient(record) {
+    record.monitorClient = undefined;
+}
 export function createBrokerState() {
     return { instances: new Map(), grants: new Map(), blockedPorts: new Set() };
 }
@@ -109,6 +118,8 @@ export async function nextFreePort(state, opts = {}) {
     for (let port = basePort; port < limit; port++) {
         if (state.instances.has(port))
             continue;
+        if (opts.exclude?.has(port))
+            continue;
         if (isPortBlocked(state, port))
             continue;
         if (await portInUse(port)) {