@henols/vice-mcp 0.2.2 → 0.2.3

package/resources/vice-broker.mjs

@@ -2,7 +2,7 @@
 // Compiled by `tsc` from vice-broker.mts. Edit the TypeScript source and rebuild;
 // changes made directly to this file are silently overwritten by the next build, and are never
 // deployed to the host on their own -- install-resources.mjs copies THIS file's on-disk contents
-// verbatim to tools/, so an edit made only here reaches the host but is lost on the very next
+// verbatim to .c64-re-tools/bin/, so an edit made only here reaches the host but is lost on the very next
 // rebuild.
 // vice-broker.mts
 //
@@ -29,26 +29,56 @@ import { join, basename, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { containerGuardReport, containerGuardEnforce } from "./container-guard.mjs";
-import { createBrokerState, nextFreePort, countReady, countTotal, countLaunching, atCapacity, resolveBasePort, clearMonitorClient, } from "./broker-state.mjs";
-import { acquirePortAndLaunch, deleteInstanceRecord, maintainWarmFloor, probeReady, runBrokerPass, withCrashSupervision, } from "./broker-launch.mjs";
-// Plan 02-07: resolvedBackend() is now the ONE reader of VICE_BACKEND in
-// this tree -- ViceBackend's own definition moved to backend-detect.mts too,
-// so broker-launch.mjs's own (type-only) re-import of it and this file's
-// VALUE import both name the same one home. A real value import is safe
-// here (unlike inside broker-launch.mts) because vice-broker.mts is ALWAYS
-// run from its own compiled resources/ form -- both modules are compiled
-// together in the same build.ts pass, so "./backend-detect.mjs" always
-// exists as a real sibling file by the time this import resolves.
+// Plan 41-05 (folded todo): countReady/countTotal/countLaunching are DROPPED
+// from this import -- they were used only as maintainWarmFloorForRealBroker()'s
+// own deps for the now-retired maintainWarmFloor(), passed through by
+// shorthand property (`countReady,` etc.), never called directly in this
+// file. atCapacity() is the one survivor actually called here (its own
+// cold-launch-arm gate, below).
+import { createBrokerState, nextFreePort, atCapacity, resolveBasePort, clearMonitorClient, } from "./broker-state.mjs";
+import { acquirePortAndLaunch, deleteInstanceRecord, 
+// Plan 41-05 (folded todo): replaces maintainWarmFloor -- the warm floor
+// itself is retired; this is ONLY the launching -> ready promotion sweep
+// the floor used to carry as its own step 1.
+promoteLaunchingInstances, probeReady, runBrokerPass, withCrashSupervision, } from "./broker-launch.mjs";
+// Plan 02-07: resolvedBackend() resolves the emulator binary's identity --
+// ViceBackend's own definition lives in backend-detect.mts too (narrowed to
+// a single literal by FORKRM-01, plan 52-06), so broker-launch.mjs's own
+// (type-only) re-import of it and this file's VALUE import both name the
+// same one home. A real value import is safe here (unlike inside
+// broker-launch.mts) because vice-broker.mts is ALWAYS run from its own
+// compiled resources/ form -- both modules are compiled together in the
+// same build.ts pass, so "./backend-detect.mjs" always exists as a real
+// sibling file by the time this import resolves.
 import { resolvedBackend } from "./backend-detect.mjs";
 import { verifiedKill, registerShutdownHandlers, startupBanner, reapOrphanedInstances } from "./broker-kill.mjs";
 import { writeEpochRecord, epochPathFor, nextEpochFor, instanceLogDirFor } from "./broker-epoch.mjs";
+// Phase 34, plan 34-01 (SEAM-01): a VALUE import of the host-tool executor --
+// safe here for the SAME reason every other sibling value import above is:
+// this file is ALWAYS run from its own compiled resources/ form, and
+// "./host-tool.mjs" is compiled into that same directory by the same build.ts
+// pass (host-tool.mts is added to HOST_BOUND_ARTIFACTS/tsconfig.build.json's
+// include[] in this same commit).
+import { runHostTool } from "./host-tool.mjs";
+// Gap G-40-1, requirement R2 (plan 40-09): a VALUE import of the same
+// handle-minting function for the SAME reason as the host-tool.mjs import
+// immediately above -- this file is always run from its own compiled
+// resources/ form, and "./ghidra-project.mjs" is compiled into that same
+// directory by the same build.ts pass (both source and target are already
+// listed in HOST_BOUND_ARTIFACTS, since plan 40-08 landed the module).
+import { ensureGhidraRunsHandle } from "./ghidra-project.mjs";
 import { startControlListener, newControlToken, drainPendingAcquires, resolveControlPort, } from "./broker-control.mjs";
 const USAGE = "usage: vice-broker.mjs --repo-root <path> [--state-dir <path>] [--check-container] [--dry-run]";
 /** `--repo-root` is required UNLESS `--check-container` is given -- the
  * container guard needs no paths at all, matching the bash launcher's own
  * `--check-container` handling (answered before any path resolution).
  * `--state-dir` defaults to VICE_POOL_DIR from the environment when set,
- * otherwise `.vice-supervisor` under the repo root. */
+ * otherwise `.c64-re-tools/supervisor` under the repo root (moved 2026-09-08,
+ * D-33 -- was `.vice-supervisor`; the three-tier chain itself -- explicit
+ * `--state-dir`, then `VICE_POOL_DIR`, then this default -- is unchanged,
+ * only the default's location moved). This module is host-bound and compiled
+ * by `build.ts`, so it must not import the container-side `repo-root.ts`;
+ * the two segments are joined directly, matching that file's `toolsDir()`. */
 export function parseArgs(argv) {
     let repoRoot = null;
     let stateDir = null;
@@ -73,7 +103,9 @@ export function parseArgs(argv) {
     if (!checkContainer && !repoRoot) {
         throw new Error(USAGE);
     }
-    const resolvedStateDir = stateDir ?? process.env.VICE_POOL_DIR ?? (repoRoot ? join(repoRoot, ".vice-supervisor") : ".vice-supervisor");
+    const resolvedStateDir = stateDir ??
+        process.env.VICE_POOL_DIR ??
+        (repoRoot ? join(repoRoot, ".c64-re-tools", "supervisor") : join(".c64-re-tools", "supervisor"));
     return { repoRoot: repoRoot ?? "", stateDir: resolvedStateDir, checkContainer, dryRun };
 }
 /** The deployed JavaScript broker artifact's own name -- D-26's entire
@@ -82,30 +114,23 @@ export function parseArgs(argv) {
  * It now names itself. */
 export const WRITTEN_BY = "vice-broker.mjs";
 // ---------------------------------------------------------------------------
-// Small, locally-duplicated env-var readers (plan 05) -- the SAME pattern
+// Small, locally-duplicated env-var reader (plan 05) -- the SAME pattern
 // broker-kill.mts's own resolveBasePortForReap()/resolveViceBinForReap()
 // already established: this module cannot import broker-launch.mts's
-// PRIVATE resolveWarmFloor()/resolveCeiling() (they are not exported, and
-// this file is already the top-level wiring module value-importing every
-// sibling .mjs directly -- exporting them would widen broker-launch.mts's
-// own surface for a one-line env-var read this file can duplicate exactly
-// as cheaply). Both mirror broker-launch.mts's defaults precisely
-// (VICE_BROKER_WARM_FLOOR/1, VICE_BROKER_MAX/16) so broker.json's config echo
-// and host_state's own answer can never disagree with what maintainWarmFloor
-// itself actually enforces. The floor default dropped from 3 to 1 in
-// 01.6.2.1-03-PLAN.md (D-06) -- BOTH readers changed together in that same
-// commit, deliberately, because this invariant (the two numbers never
-// disagree) breaks silently the moment only one of them moves. The
-// ceiling's own default (16) is untouched by D-06 -- it is the unrun
-// concurrency-ceiling spike's territory, not this phase's.
+// PRIVATE resolveCeiling() (it is not exported, and this file is already
+// the top-level wiring module value-importing every sibling .mjs directly --
+// exporting it would widen broker-launch.mts's own surface for a one-line
+// env-var read this file can duplicate exactly as cheaply). Mirrors
+// broker-launch.mts's own default precisely (VICE_BROKER_MAX/16) so
+// broker.json's config echo and host_state's own answer can never disagree
+// with what atCapacity() itself actually enforces. Plan 41-05 (folded todo):
+// this used to be a PAIR with resolveWarmFloorForRecord() (VICE_BROKER_WARM_
+// FLOOR/1), kept in lockstep with broker-launch.mts's own matching pair
+// (01.6.2.1-03-PLAN.md, D-06) so the two numbers could never disagree. The
+// warm-floor half of that pair is RETIRED along with the floor itself -- the
+// ceiling's own default (16) is untouched, since it is a separate concern
+// (VICE_BROKER_MAX / atCapacity()) this plan does not touch.
 // ---------------------------------------------------------------------------
-function resolveWarmFloorForRecord() {
-    const raw = process.env.VICE_BROKER_WARM_FLOOR;
-    if (raw === undefined || raw === "")
-        return 1;
-    const n = Number(raw);
-    return Number.isFinite(n) ? n : 1;
-}
 function resolveCeilingForRecord() {
     const raw = process.env.VICE_BROKER_MAX;
     if (raw === undefined || raw === "")
@@ -179,7 +204,7 @@ function writeBrokerRecordFile(stateDir, record) {
 }
 /** Builds a spawn function that redirects the child's stdout/stderr into a
  * FRESH per-launch log file under logDir (D-23: per-instance boot/crash
- * logs survive under .vice-supervisor/<port>/logs/, same paths, same
+ * logs survive under .c64-re-tools/supervisor/<port>/logs/, same paths, same
  * format as the retiring bash supervisor), returning both the spawn
  * closure and the log's path relative to supervisorDir (the epoch
  * record's own `log` field). Shared by both launch paths -- a cold
@@ -233,9 +258,10 @@ function writeEpochForLaunch(record, logRelPath) {
     record.epoch = epochRecord.epoch;
 }
 /** Builds the supervision dependency object for withCrashSupervision(),
- * once per launch, so both real launch paths (handleAcquire here; Task 2's
- * maintainWarmFloorForRealBroker) pass a structurally identical
- * SuperviseChildDeps object into the SAME shared wrapper. Deliberately does
+ * once per launch, so the real launch path (handleAcquire's own cold arm,
+ * here -- plan 41-05 retires the second real launch path this comment used
+ * to name, the warm floor) passes a structurally identical SuperviseChildDeps
+ * object into the shared wrapper. Deliberately does
  * NOT set spawnFactory: on a respawn, launchSupervised() (broker-launch.mts)
  * derives its own per-instance log path from instanceLogDirFor and names
  * that same path in the epoch record it writes -- supplying a competing
@@ -248,11 +274,11 @@ function writeEpochForLaunch(record, logRelPath) {
  * CR-01 (03-REVIEW.md): `backend` is a REQUIRED positional parameter, not an
  * optional field a call site may quietly omit. Before this, both real call
  * sites built their deps here WITHOUT it, so `spawnAndRecordInstance()`'s own
- * `deps.backend ?? "fork"` default silently took over the moment crash
- * supervision replaced an instance -- a stock instance's crash-respawn or
- * `vice_recycle` relaunched it with the FORK's `-mcpserver` argv, which stock
- * upstream VICE does not understand at all, leaving a pool member that can
- * never be reached over the binary monitor again while still counting toward
+ * unset-parameter default silently took over the moment crash supervision
+ * replaced an instance -- a stock instance's crash-respawn or `vice_recycle`
+ * could relaunch it with a different backend's argv shape than the one it
+ * was actually launched with, leaving a pool member that can never be
+ * reached over the binary monitor again while still counting toward
  * countReady()/countTotal(). Making it positional and required is what makes
  * that omission a compile error rather than a silent backend swap: the FIRST
  * launch and every REPLACEMENT of it now build their argv from the SAME
@@ -294,6 +320,47 @@ function markDeliberateDeath(instance, respawnAfterKill) {
     instance.deliberateKill = true;
     instance.respawnAfterKill = respawnAfterKill;
 }
+// ---------------------------------------------------------------------------
+// Phase 33, plan 33-06 (REPRO-05, D-16, T-33-23/T-33-24): the warm-instance
+// PROFILE-ELIGIBILITY rule.
+//
+// THE DECISION, stated out loud because two of the three available answers
+// are wrong in ways the CALLER CANNOT DETECT:
+//   - Refuse the acquire outright when a mismatched warm instance exists ->
+//     warp becomes unusable whenever a warm floor exists (the default is 1,
+//     so: essentially always).
+//   - Serve the request with the mismatched instance -> the caller asked for
+//     warp, got an unwarped machine, and received a confident grant. The knob
+//     is a lie and nothing in the response says so.
+//   - D-16, what this implements: the mismatched instance is INELIGIBLE. The
+//     walk skips it and the acquire falls through to the cold arm, which
+//     launches a DEDICATED instance for that grant.
+//
+// WHAT MUST NEVER BE ADDED HERE: a retro-warp, and a kill-then-relaunch of a
+// mismatched warm instance. There is no runtime `WarpMode` resource on stock
+// at all (vsync.c:220-241, deliberately), so an existing instance cannot be
+// adjusted -- it can only be ineligible. And "killing or relaunching
+// preemptively to serve a newer request" is a NAMED anti-pattern in this
+// project (CLAUDE.md): it would make an interactive session's emulator vanish
+// because some capture run asked for warp. A test asserts the kill dependency
+// is not called and the instance stays `ready`.
+// ---------------------------------------------------------------------------
+/** True when `record` was launched with the SAME profile `requested` asks
+ * for. FULLY SYNCHRONOUS by requirement, not by convenience -- see the call
+ * site inside selectWarmInstance() below for why.
+ *
+ * Absent is `{}`: a record with no `profile` field (a pre-33-06 record, a
+ * fork launch, a warm-floor spare, or a record a broker restarted mid-phase
+ * read from a state directory written before the field existed) is compared
+ * as though it carried `{}`, and so is an absent request. Each knob is
+ * compared `=== true` on BOTH sides, so `undefined` and `false` are the same
+ * request -- which is what makes an absent profile, an explicit `{}` and
+ * `{warp:false, headless:false}` one single behaviour rather than three. */
+export function profileEligible(record, requested) {
+    const have = record.profile ?? {};
+    const want = requested ?? {};
+    return (have.warp === true) === (want.warp === true) && (have.headless === true) === (want.headless === true);
+}
 /** Walks `state.instances` for probe-live `ready` candidates, in iteration
  * order, and returns the first that answers a grant-time re-probe (P-02) --
  * or `null` once every candidate has been tried and none answered, letting
@@ -354,6 +421,28 @@ async function selectWarmInstance(state, deps) {
     for (const record of Array.from(state.instances.values())) {
         if (record.state !== "ready")
             continue;
+        // Phase 33, plan 33-06 (D-16, T-33-23): a SYNCHRONOUS `continue`, sitting
+        // immediately beside the `record.state !== "ready"` filter directly
+        // above and BEFORE the readiness probe below. That placement is
+        // load-bearing twice over, and neither reason is stylistic:
+        //
+        //   1. It introduces NO new `await` into the region the single-owner
+        //      `inFlight` launch guard protects. That guard exists because of the
+        //      2026-08-01 triple-launch outage and must stay a synchronous
+        //      check-and-set with no `await` between (CLAUDE.md, regression-
+        //      tested). A filter placed after the probe would put a fresh
+        //      suspension point inside that region -- which is why this plan
+        //      verifies the placement by line-number comparison, not by comment.
+        //   2. An ineligible candidate costs no probe at all -- no socket, no
+        //      round trip, no wait.
+        //
+        // An ineligible miss falls through EXACTLY as a "no warm instance" miss
+        // does: to the caller's own cold arm, which records the one and only
+        // grant. It opens no second `state.grants.set()` call, and it never
+        // kills, recycles or re-warps the mismatched instance (see
+        // profileEligible()'s own banner for why those are excluded by design).
+        if (!profileEligible(record, deps.requestedProfile))
+            continue;
         const isReady = await deps.probe(record.port);
         // A sibling acquire may have granted OR dropped this exact candidate
         // while this probe was in flight. "Granted" changes record.state;
@@ -437,14 +526,14 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
     // WR-01: the readiness probe is backend-aware, from the SAME threaded-down
     // 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 ?? "fork";
+    const backend = deps.backend ?? "stock";
     const probe = deps.probe ?? ((port) => probeReady(port, { backend }));
     // Textually a verifiedKill( call site, not merely a reference -- reused
     // UNCHANGED from broker-kill.mts (Phase 01.6.2 criterion 6), never
     // re-derived, and never replaced by a bare process.kill().
     const kill = deps.kill ?? ((opts) => verifiedKill(opts));
     const log = deps.log ?? ((line) => process.stderr.write(`${line}\n`));
-    const winner = await selectWarmInstance(state, { probe, kill, log });
+    const winner = await selectWarmInstance(state, { probe, kill, log, requestedProfile: deps.profile });
     let record;
     if (winner) {
         record = winner;
@@ -473,6 +562,14 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             // build a different backend's argv than the launch it replaces.
             backend,
             allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
+            // Phase 33, plan 33-06 (D-15/D-16): the profile the warm arm just
+            // refused to compromise on reaches buildViceArgs() here, and is
+            // mirrored onto the fresh InstanceRecord by spawnAndRecordInstance()
+            // in the SAME step -- so this instance's recorded profile and its real
+            // argv are written together and cannot disagree. This is the arm that
+            // makes "a dedicated instance for that grant" true rather than
+            // aspirational.
+            profile: deps.profile,
             spawnFactory: deps.buildColdSpawnFactory ??
                 ((port) => {
                     const supervisorDir = join(stateDir, String(port));
@@ -482,6 +579,13 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
                 }),
         });
         if (!result.ok) {
+            // Plan 41-05 (D-16, checkpoint option B): `result.reason` passes
+            // straight through -- `AcquireLaunchResult`'s reason union
+            // ("launch_in_flight" | "no_free_port" | "no_free_text_port") is a
+            // subset of `AcquireOutcome`'s, so a failed text-port allocation's own
+            // `no_free_text_port` reaches the control plane as its own distinct
+            // code (broker-control.mts's ControlErrorCode) rather than collapsing
+            // to `internal` or to the generic `no_free_port`.
             return { ok: false, reason: result.reason };
         }
         if (result.record.pid === null) {
@@ -494,16 +598,29 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             // even though the caller was already told "internal" right now.
             // CR-02: deleteInstanceRecord(), not a bare map delete -- a stock launch
             // that failed this way already had its second port allocated and
-            // blocked by acquirePortAndLaunch().
+            // blocked by acquirePortAndLaunch(), and deleteInstanceRecord() hands
+            // that second port back to the allocator (via state.blockedPorts) in
+            // the SAME step as it removes the broken record -- confirmed still
+            // true after plan 41-05 (D-16): this branch is reached only once a
+            // record already exists, i.e. only once BOTH allocations already
+            // succeeded (a failed second allocation now fails the acquire before
+            // any record -- and before this `pid === null` check -- is ever
+            // reached at all).
             deleteInstanceRecord(state, result.record.port);
             return { ok: false, reason: "internal" };
         }
         record = result.record;
-        // Only the cold-launch arm ever writes a FRESH epoch record -- the warm
-        // arm's winner already has one, written when it was warmed
-        // (maintainWarmFloorForRealBroker()'s own onLaunched hook), and
-        // rewriting it here would advance an epoch no restart caused, which the
-        // container-side assertSameMachine() would read as a machine change.
+        // Only the cold-launch arm ever writes a FRESH epoch record here --
+        // selectWarmInstance()'s own winner already has one. Plan 41-05 (folded
+        // todo) changes WHY that is true without changing that it IS true: a
+        // ready, ungranted candidate no longer comes from a warm-floor pass's
+        // own onLaunched hook (retired along with the floor) -- it comes from
+        // broker-launch.mts's own crash-supervision respawn path
+        // (launchSupervised(), which writes its own epoch record via
+        // deps.epoch.writeEpochRecord() on every launch and every respawn).
+        // Either way, rewriting the epoch here would advance an epoch no restart
+        // caused, which the container-side assertSameMachine() would read as a
+        // machine change.
         writeEpochForLaunch(record, lastLogRelPath);
     }
     // THE single grant-recording step, fed by both arms above -- no `await`
@@ -515,7 +632,18 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
     record.state = "granted";
     return {
         ok: true,
-        grant: { port: record.port, url: record.url, epochFile: record.epochFile, supervisorDir: record.supervisorDir },
+        grant: {
+            port: record.port,
+            url: record.url,
+            epochFile: record.epochFile,
+            supervisorDir: record.supervisorDir,
+            // Plan 41-01 (D-15): key omitted entirely when the record has none --
+            // the fork case, and (until a later plan closes the port-allocation
+            // degrade path) a stock instance whose second port allocation itself
+            // failed. Same key-omitted-when-undefined idiom
+            // spawnAndRecordInstance() already uses for this same field.
+            ...(record.remoteMonitorPort === undefined ? {} : { remoteMonitorPort: record.remoteMonitorPort }),
+        },
     };
 }
 /** Answers the `status` control-plane request: one entry per instance,
@@ -529,7 +657,10 @@ function handleStatus(state) {
         state: r.state,
         reason: r.reason,
         epoch: typeof r.epoch === "number" ? r.epoch : null,
-        hasMonitorClient: r.monitorClient !== undefined,
+        // Plan 41-03 (D-14): "at least one channel is claimed" -- promoted from
+        // a single-field check, byte-identical wire shape, meaning stated
+        // explicitly (D-15).
+        hasMonitorClient: Object.keys(r.monitorClients).length > 0,
     }));
 }
 /** Resolves a monitor_claim/monitor_release target the SAME way
@@ -544,49 +675,55 @@ function resolveInstanceForMonitorTarget(targetId, state) {
         return null;
     return state.instances.get(grant.port) ?? null;
 }
-/** Answers `monitor_claim` (plan 05, BROK-02/PROTO-08, D-13): exclusive
- * monitor-socket ownership enforced HERE, broker-side, so a conflicting
- * claim is refused by name before any second `connect()` is ever attempted
- * -- the one state stock VICE cannot report and no client-side heuristic
- * can diagnose. `targetId` doubles as both "which instance" (resolved via
- * the SAME grant lookup handleRelease()/handleRecycleForRealBroker() already
- * use) and "the requesting grant's own identity" -- the claim IS the grant,
- * so there is no separate identity to carry. A repeated claim from the SAME
- * grant is idempotent (`ok: true`, no second holder created); a claim from
- * a DIFFERENT grant while the instance already has a holder is refused,
- * naming the current holder (T-02-18) -- never the emulator's own fault. */
-export function handleMonitorClaim(requestId, targetId, state) {
+/** Answers `monitor_claim` (plan 05, BROK-02/PROTO-08, D-13; per-channel
+ * since plan 41-03, D-14): exclusive monitor-socket ownership enforced
+ * HERE, broker-side, PER CHANNEL, so a conflicting claim is refused by name
+ * before any second `connect()` is ever attempted -- the one state stock
+ * VICE cannot report and no client-side heuristic can diagnose. `targetId`
+ * doubles as both "which instance" (resolved via the SAME grant lookup
+ * handleRelease()/handleRecycleForRealBroker() already use) and "the
+ * requesting grant's own identity" -- the claim IS the grant, so there is
+ * no separate identity to carry. A repeated claim from the SAME grant on
+ * the SAME channel is idempotent (`ok: true`, no second holder created); a
+ * claim from a DIFFERENT grant while that channel already has a holder is
+ * refused, naming the current holder and the channel (T-02-18) -- never the
+ * emulator's own fault. A DIFFERENT channel's holder is irrelevant to this
+ * decision -- claiming one channel never evicts or is refused by the
+ * other's holder. */
+export function handleMonitorClaim(requestId, targetId, channel, state) {
     void requestId; // correlation only -- the claim's own identity is targetId itself
     const instance = resolveInstanceForMonitorTarget(targetId, state);
     if (!instance)
         return { ok: false, code: "bad_request" };
-    const existing = instance.monitorClient;
+    const existing = instance.monitorClients[channel];
     if (!existing) {
-        instance.monitorClient = { grantId: targetId, claimedAt: Date.now(), pid: instance.pid };
+        instance.monitorClients[channel] = { grantId: targetId, claimedAt: Date.now(), pid: instance.pid };
         return { ok: true };
     }
     if (existing.grantId === targetId) {
-        return { ok: true }; // idempotent repeat from the SAME grant -- no second holder
+        return { ok: true }; // idempotent repeat from the SAME grant on the SAME channel -- no second holder
     }
-    return { ok: false, code: "monitor_owned", holder: { grantId: existing.grantId, claimedAt: existing.claimedAt, pid: existing.pid } };
+    return { ok: false, code: "monitor_owned", holder: { grantId: existing.grantId, claimedAt: existing.claimedAt, pid: existing.pid, channel } };
 }
-/** Answers `monitor_release` (plan 05, T-02-01): clears `monitorClient` ONLY
- * when `targetId` names the CURRENT holder -- a non-holder is refused, not
+/** Answers `monitor_release` (plan 05, T-02-01; per-channel since plan
+ * 41-03, D-14): clears ONLY the named channel's entry, ONLY when `targetId`
+ * names that channel's CURRENT holder -- a non-holder is refused, not
  * silently accepted (spoofing a release is exactly T-02-01's own
- * disposition). An instance with no current holder at all tolerates the
+ * disposition). A channel with no current holder at all tolerates the
  * release as a success, matching the container-side client's own documented
  * tolerance for releasing a socket the broker already cleared. */
-export function handleMonitorRelease(requestId, targetId, state) {
+export function handleMonitorRelease(requestId, targetId, channel, state) {
     void requestId; // correlation only, matching handleMonitorClaim()'s own posture
     const instance = resolveInstanceForMonitorTarget(targetId, state);
     if (!instance)
         return { ok: false, code: "bad_request" };
-    if (!instance.monitorClient)
+    const existing = instance.monitorClients[channel];
+    if (!existing)
         return { ok: true }; // already cleared -- tolerated, not an error
-    if (instance.monitorClient.grantId !== targetId) {
+    if (existing.grantId !== targetId) {
         return { ok: false, code: "denied" };
     }
-    clearMonitorClient(instance);
+    clearMonitorClient(instance, channel);
     return { ok: true };
 }
 /** Resolves a recycle target's emulator child pid from THIS broker's own
@@ -664,83 +801,26 @@ async function handleRecycleForRealBroker(targetId, state) {
     const reason = killStage === "identity_refused" ? "process identity did not match the recorded emulator binary -- the target was NOT signalled and is still running" : "";
     return { port: instance.port, pid: instance.pid, viceBin: instance.viceBin, killStage, epochBefore, outcome, reason };
 }
-/** The warm-floor concern of the fixed-order evaluation pass (D-24 drops
- * the projection write; the grant sweep does not appear -- D-12's
- * connection-is-the-lease). Builds a fresh MaintainWarmFloorDeps per call
- * (never reused across passes) wiring broker-state.mjs's real
- * allocatePort/counts and broker-launch.mjs's real probeReady, and hooks
- * onLaunched to write the SAME epoch record a cold acquire writes -- a
- * warm instance is a real process the moment it exists, per D-04.
- *
- * WR-04 (01.6.2.1-REVIEW.md): the log-path stash below is a LOCAL variable,
- * declared fresh once per call to THIS function -- exactly mirroring how
- * handleAcquire()'s own equivalent cold-launch log-path variable
- * (`lastLogRelPath`) is already scoped locally rather than to the module.
- * Both the write site (the spawn-wrapping closure) and the read site (the
- * `onLaunched` callback) live inside this SAME function body, so this is a
- * pure relocation with no behavioural change -- it removes the
- * cross-call-sharing risk a module-level `let` carried (correct only
- * because of invariants -- at most one launch per call, never invoked
- * concurrently with itself -- enforced elsewhere and never checked at the
- * point the variable used to be declared). */
-function maintainWarmFloorForRealBroker(stateDir, state, backend) {
-    let lastWarmLaunchLogRelPath = "";
-    return maintainWarmFloor({
+/** Plan 41-05 (folded todo): the second concern of the fixed-order
+ * evaluation pass, RENAMED from the retired warm-floor maintenance function
+ * this replaces (D-24 drops the projection write; the grant sweep does not
+ * appear -- D-12's connection-is-the-lease). Unlike the function it
+ * replaces, this one never launches anything -- it wires only
+ * broker-launch.mjs's real promoteLaunchingInstances() against this
+ * broker's own state and the backend-aware readiness probe, so a
+ * `launching` instance (however it got there -- a cold acquire's own
+ * instance, or a crash-respawn) is promoted to `ready` the moment it
+ * answers. */
+function promoteLaunchingForRealBroker(state, backend) {
+    return promoteLaunchingInstances({
         state,
-        stateDir,
         backend,
-        spawnFactory: (port) => {
-            const supervisorDir = join(stateDir, String(port));
-            const { spawn, logRelPath } = makeLoggingSpawn(join(supervisorDir, "logs"));
-            // 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
-                // invariant) can find it. withCrashSupervision() below composes
-                // AROUND this function, so the stash still runs (and still
-                // completes before onLaunched reads it) before the exit listener
-                // is ever attached.
-                lastWarmLaunchLogRelPath = logRelPath;
-                return child;
-            };
-            // CR-01 (03-REVIEW.md): the SAME resolved `backend` this function
-            // already receives for the launch argv is threaded into the supervision
-            // deps, so a warm instance's own crash-respawn stays on its backend.
-            return withCrashSupervision("spare", port, stashingSpawn, superviseDepsFor(stateDir, state, backend));
-        },
-        // WR-01: same backend-aware probe route as handleAcquire's, from the SAME
-        // resolved verdict this function already receives for the launch argv.
+        // WR-01: same backend-aware probe route as handleAcquire's, from the
+        // SAME resolved verdict this function already receives.
         probe: (port) => probeReady(port, { backend }),
-        allocatePort: nextFreePort,
-        // Plan 03-04 (DIRECT-06, D-13): same wiring as handleAcquire()'s own
-        // cold-launch arm -- acquirePortAndLaunch() (reached via
-        // maintainWarmFloor() below) gates the second allocation on
-        // `backend === "stock"` itself, so this function need not check the
-        // backend before passing it.
-        allocateRemoteMonitorPort: (s, exclude) => nextFreePort(s, { exclude }),
-        countReady,
-        countTotal,
-        countLaunching,
-        onLaunched: (record) => {
-            writeEpochForLaunch(record, lastWarmLaunchLogRelPath);
-        },
         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
@@ -785,10 +865,11 @@ export function handleRelease(requestId, state) {
     const instance = state.instances.get(grant.port);
     if (instance && instance.pid === grant.pid) {
         markDeliberateDeath(instance, false);
-        // Plan 05: releasing clears monitor-client ownership as a side effect
-        // -- redundant with the instance-map deletion two lines below (the
-        // WHOLE record, monitorClient included, is going away), but explicit
-        // for the same reason GrantRecord's own clearing is explicit here: the
+        // Plan 05: releasing clears monitor-client ownership (every channel) as
+        // a side effect -- redundant with the instance-map deletion two lines
+        // below (the WHOLE record, monitorClients included, is going away), but
+        // explicit for the same reason GrantRecord's own clearing is explicit
+        // here: the
         // instance-map deletion is a Task-2-era invariant this task must not
         // depend on silently continuing to hold.
         clearMonitorClient(instance);
@@ -860,18 +941,47 @@ async function run(args) {
     // launch, and never called from inside broker-launch.mts's `inFlight`
     // single-owner guard (this call sits entirely outside it; no launch is
     // even possible yet at this point in run()). `supervisorDir: args.stateDir`
-    // is passed explicitly -- args.stateDir IS `.vice-supervisor` under this
+    // is passed explicitly -- args.stateDir IS `.c64-re-tools/supervisor` under this
     // broker's own repo root (see parseArgs() above), so this is the SAME
     // directory repo-root.ts's supervisorDir() would resolve to, without this
     // host-bound module ever importing that container-side resolver directly
-    // (backend-detect.mts's own header comment explains why it cannot). An
-    // `indeterminate` outcome does not prevent the broker from starting: it
-    // logs its own note (backend-detect.mts) and this line proceeds with the
-    // "fork" answer resolvedBackend() already returns for that case -- the
-    // pre-Phase-2 behaviour every existing install already has.
+    // (backend-detect.mts's own header comment explains why it cannot).
+    // FORKRM-01 (plan 52-06): 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 BACK-04 record depends on.
     const backendResult = resolvedBackend({ supervisorDir: args.stateDir });
     const backend = backendResult.backend;
-    process.stderr.write(`vice-broker: backend "${backend}" (source: ${backendResult.source}, binary: ${backendResult.binPath})\n`);
+    process.stderr.write(`vice-broker: backend "${backend}" (binary: ${backendResult.binPath})\n`);
+    // Gap G-40-1, requirement R2 (plan 40-09): 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
+    // connection -- so a container-side MCP server with no host tooling of
+    // its own still finds the handle in place the moment it can reach this
+    // broker at all. This is deliberately NOT the only call site:
+    // resolveGhidraProject() (ghidra-project.mts) calls the same function as
+    // an idempotent precondition, because two host-side routes never involve
+    // a broker at all -- the direct spawn of resources/host-tool.mjs from
+    // host-tool-client.ts:269-273 (the everyday route on a host with no
+    // devcontainer, and the route CI uses), and tests importing that
+    // artifact directly. Both callers write the identical relative-target
+    // link, so a race between them is a benign EEXIST, not a conflict (see
+    // ensureGhidraRunsHandle()'s own header). The negative rule: container-
+    // side code must NEVER mint this handle -- the link target is relative
+    // and correct only when written from the host's view of the workspace.
+    //
+    // Handled WITHOUT throwing: run() has no try/catch around this region and
+    // the broker must start regardless of the outcome here -- it serves
+    // twelve allowlisted tool ids and only one of them (ghidra.analyze) needs
+    // this handle. A refusal is surfaced as ONE stderr line naming the
+    // consequence; every other tool id is unaffected.
+    const ghidraHandleResult = ensureGhidraRunsHandle(args.repoRoot);
+    if (ghidraHandleResult.ok) {
+        process.stderr.write(`vice-broker: ghidra runs handle ${ghidraHandleResult.handle} -> ${ghidraHandleResult.target}\n`);
+    }
+    else {
+        process.stderr.write(`vice-broker: ghidra runs handle refused: ${ghidraHandleResult.message} -- ghidra.analyze will refuse by name until this is fixed by hand; every other tool id is unaffected\n`);
+    }
     // D-18: the singleton guarantee holds only while the control port keeps its default -- two brokers deliberately configured onto different ports are two brokers, and no code prevents that.
     let listener;
     try {
@@ -879,29 +989,52 @@ async function run(args) {
             host: controlHost,
             port: controlPort,
             token,
-            onAcquire: (requestId) => handleAcquire(requestId, args.stateDir, state, {
+            onAcquire: (requestId, profile) => handleAcquire(requestId, args.stateDir, state, {
                 backend,
                 // Plan 03-04 (DIRECT-06, D-13): threaded down to
                 // acquirePortAndLaunch()'s own gate (backend === "stock"); this
-                // callback does NOT re-read VICE_BACKEND itself.
+                // callback does not re-read any environment variable itself.
                 allocateRemoteMonitorPort: (s, exclude) => nextFreePort(s, { exclude }),
+                // Phase 33, plan 33-06 (REPRO-05, D-15): the ALREADY-NARROWED
+                // profile broker-control.mts handed this callback. Nothing here
+                // re-validates it and nothing here reads a raw wire field --
+                // normaliseLaunchProfile() is the single narrowing site, and it ran
+                // before this callback was ever invoked.
+                profile,
             }),
             onRelease: (requestId) => handleRelease(requestId, state),
             onRecycle: (targetId) => handleRecycleForRealBroker(targetId, state),
             onStatus: () => handleStatus(state),
-            onMonitorClaim: (requestId, targetId) => handleMonitorClaim(requestId, targetId, state),
-            onMonitorRelease: (requestId, targetId) => handleMonitorRelease(requestId, targetId, state),
+            // Phase 34, plan 34-01 (SEAM-01): its OWN callback, wired alongside
+            // (never derived from) the other six above -- handed only
+            // `args.repoRoot` and a stderr logger, never this broker's `state` map,
+            // so it structurally cannot reach lease state through this closure.
+            // 34-09 (CR-04): deliberately supplies no timeout, and that is
+            // authoritative here, not an omission -- the per-tool budget table
+            // inside runHostTool()/hostToolTimeoutMs() (host-tool.mts) is the ONE
+            // place a budget is decided, and no wire field carries one across the
+            // seam at all (the `deps.timeoutMs` this callback could pass is an
+            // in-process test seam, not something a caller's request ever
+            // supplies). A reader arriving here from the artifact this plan's
+            // completeness case checks should find this comment as the answer,
+            // not an apparent gap.
+            onHostTool: (raw) => runHostTool(raw, {
+                repoRoot: args.repoRoot,
+                log: (line) => process.stderr.write(`${line}\n`),
+            }),
+            onMonitorClaim: (requestId, targetId, channel) => handleMonitorClaim(requestId, targetId, channel, state),
+            onMonitorRelease: (requestId, targetId, channel) => handleMonitorRelease(requestId, targetId, channel, state),
             onHostState: () => ({
                 pid: process.pid,
                 startedAt,
                 nodeVersion: process.version,
                 viceBin: resolveViceBinForHostState(),
-                warmFloor: resolveWarmFloorForRecord(),
                 maxInstances: resolveCeilingForRecord(),
                 basePort: resolveBasePort(),
-                // WR-04: the verdict THIS process resolved once, at startup, above --
-                // the same one every launch argv is built from. Never a second
-                // resolvedBackend() call (backend-detect.mts's own prohibition).
+                // FORKRM-01 (plan 52-06): the verdict THIS process resolved once, at
+                // startup, above -- kept on the wire because text-tools.ts's own
+                // broker-identity cross-check (out of this plan's scope) still reads
+                // it. Never a second resolvedBackend() call.
                 backend,
             }),
         });
@@ -951,11 +1084,21 @@ async function run(args) {
     registerShutdownHandlers({ state });
     // A successful bind writes the record UNCONDITIONALLY, overwriting
     // whatever was there -- the bind itself is the proof of singleton status
-    // (D-17). The fourteen-field set (D-27, criterion G): the lease
-    // time-to-live field the bash original carried is gone -- the connection
-    // is the lease now (D-12) -- and every other config-echo field survives
+    // (D-17). The fourteen-field set (D-27, criterion G; narrowed from
+    // fourteen to thirteen by plan 41-05, then widened back to fourteen to add
+    // node_exec_path): the lease time-to-live field the bash original carried
+    // is gone -- the connection is the lease now (D-12) -- `warm_floor` is
+    // likewise gone (plan 41-05: there is no warm floor left to echo a
+    // configured value for) -- and every other config-echo field survives
     // even though no consumer parses it beyond a status message, because a
     // human reading this file by hand benefits from the full echo.
+    //
+    // node_exec_path is process.execPath, not something threaded in from
+    // outside: exec() replaces the process image, so whatever interpreter the
+    // launcher resolved and gated IS this process's own execPath by the time
+    // this line runs -- the record tells the truth without either side having
+    // to pass anything, and it stays truthful even when this broker was
+    // started directly, bypassing the launcher entirely.
     let record = {
         version: 1,
         written_by: WRITTEN_BY,
@@ -963,17 +1106,17 @@ async function run(args) {
         started_at: startedAt,
         heartbeat_at: new Date().toISOString(),
         node_version: process.version,
+        node_exec_path: process.execPath,
         control_host: listener.host,
         control_port: listener.port,
         control_token: token, // never logged -- T-01.6.2-02
-        warm_floor: resolveWarmFloorForRecord(),
         max_instances: resolveCeilingForRecord(),
         base_port: resolveBasePort(),
         poll_ms: pollMs,
         dry_run: args.dryRun,
     };
     writeBrokerRecordFile(args.stateDir, record);
-    process.stderr.write(`vice-broker: wrote ${finalPath} (node ${record.node_version}); control listener bound on ${listener.host}:${listener.port}\n`);
+    process.stderr.write(`vice-broker: wrote ${finalPath} (node ${record.node_version} at ${record.node_exec_path}); control listener bound on ${listener.host}:${listener.port}\n`);
     const heartbeatMs = Number(process.env.VICE_BROKER_HEARTBEAT_MS) || 30000;
     setInterval(() => {
         // The refresh path goes through the SAME atomic tmp-then-rename choke
@@ -984,18 +1127,21 @@ async function run(args) {
         writeBrokerRecordFile(args.stateDir, record);
     }, heartbeatMs);
     // The fixed-order evaluation pass (runBrokerPass, broker-launch.mts):
-    // serve pending acquires, then maintain the warm floor -- mirroring
-    // vice-broker.sh's own broker_once() ordering. Ticks on
-    // VICE_BROKER_POLL_MS (default 500, the SAME env var name and semantics
-    // the bash daemon used). serveAcquires now drains the arrival-ordered
-    // pending-acquire structure this listener instance owns (D-08's
-    // mechanism; plan 02's own `serveAcquires: () => {}` comment reserved
-    // exactly this room) -- an acquire queued because a launch was already in
-    // flight is retried here, on the SAME pass that also maintains the warm
-    // floor, so a stalled pass shows up as a stale record rather than a
-    // silently wrong one. Re-entrancy guarded: a pass that is still running
-    // (e.g. a slow readiness probe against a genuinely slow host) is never
-    // overlapped by the next tick.
+    // serve pending acquires, then promote launching -> ready -- mirroring
+    // vice-broker.sh's own broker_once() ordering (plan 41-05, folded todo:
+    // the warm floor this pass used to maintain as its second concern is
+    // RETIRED; see runBrokerPass()'s own comment in broker-launch.mts for what
+    // the fixed order still buys now that only serveAcquires() ever launches
+    // anything). Ticks on VICE_BROKER_POLL_MS (default 500, the SAME env var
+    // name and semantics the bash daemon used). serveAcquires now drains the
+    // arrival-ordered pending-acquire structure this listener instance owns
+    // (D-08's mechanism; plan 02's own `serveAcquires: () => {}` comment
+    // reserved exactly this room) -- an acquire queued because a launch was
+    // already in flight is retried here, on the SAME pass that also promotes
+    // any newly-ready instance, so a stalled pass shows up as a stale record
+    // rather than a silently wrong one. Re-entrancy guarded: a pass that is
+    // still running (e.g. a slow readiness probe against a genuinely slow
+    // host) is never overlapped by the next tick.
     let passInFlight = false;
     setInterval(() => {
         if (passInFlight)
@@ -1003,7 +1149,7 @@ async function run(args) {
         passInFlight = true;
         runBrokerPass({
             serveAcquires: () => drainPendingAcquires(listener.pendingAcquires),
-            maintainWarmFloor: () => maintainWarmFloorForRealBroker(args.stateDir, state, backend),
+            promoteLaunching: () => promoteLaunchingForRealBroker(state, backend),
         })
             .catch((e) => {
             process.stderr.write(`vice-broker: evaluation pass failed: ${e.message}\n`);