@henols/vice-mcp 0.2.2 → 0.2.4

package/resources/vice-broker.mjs

@@ -2,12 +2,12 @@
 // 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
 //
-// The long-lived host broker entry point (Phase 01.6.2). Extends the Phase
-// 01.6 tracer in place rather than replacing it: parseArgs(),
+// The long-lived host broker entry point. Extends an earlier write-once
+// tracer script in place rather than replacing it: parseArgs(),
 // readBrokerRecordMaybe() and the atomic tmp-sibling-then-rename write
 // discipline all survive; main() grows a real control listener, a
 // heartbeat and a real acquire/release path spawning a real child.
@@ -29,26 +29,58 @@ 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.
+// countReady/countTotal/countLaunching are DROPPED from this import -- they
+// were used only as maintainWarmFloorForRealBroker()'s own deps for the
+// now-retired maintainWarmFloor() (the warm floor itself was retired once
+// the connection became the lease, with no separate expiry left to
+// maintain), 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, 
+// Replaces maintainWarmFloor -- the warm floor itself is retired (the
+// connection is the lease now, so there is no separate floor left to
+// keep warm); 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";
+// resolvedBackend() resolves the emulator binary's identity -- ViceBackend's
+// own definition lives in backend-detect.mts too (narrowed to a single
+// literal now that the fork backend has been removed entirely), 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";
+// 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";
+// 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).
+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
+ * from `.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,39 +105,33 @@ 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
- * point: this field used to read "vice-broker.sh" (the retiring bash
- * daemon), which was false the moment a real TypeScript broker existed.
- * It now names itself. */
+/** The deployed JavaScript broker artifact's own name. This field used to
+ * read "vice-broker.sh" (the retiring bash daemon), which was false the
+ * moment a real TypeScript broker existed. 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. This used to be a PAIR
+// with resolveWarmFloorForRecord() (VICE_BROKER_WARM_FLOOR/1), kept in
+// lockstep with broker-launch.mts's own matching pair 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 === "")
@@ -178,21 +204,21 @@ function writeBrokerRecordFile(stateDir, record) {
     return finalPath;
 }
 /** 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
+ * FRESH per-launch log file under logDir (so per-instance boot/crash 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
  * acquire and warm-floor maintenance -- so there is exactly one place that
  * 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. */
+ * The returned `spawn` now also forwards a caller options object, 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 the per-instance forensic logs while
+ * appearing to work. */
 function makeLoggingSpawn(logDir) {
     mkdirSync(logDir, { recursive: true });
     const viceBinForLog = basename(process.env.VICE_BIN ?? "x64sc");
@@ -204,8 +230,9 @@ function makeLoggingSpawn(logDir) {
     };
 }
 /** Writes the epoch record for a just-launched instance -- shared by both
- * launch paths so D-04's contract (format, location, atomic-write
- * discipline, all unchanged -- only the writer moves) is discharged from
+ * launch paths so the epoch record's own contract (format, location,
+ * atomic-write discipline, all unchanged -- only the writer moves) is
+ * discharged from
  * exactly one place regardless of WHY the instance was launched. A
  * granted instance and a still-warm instance are equally real processes; both
  * need a real epoch.json the moment they exist, or plan 04's grant-time
@@ -233,26 +260,28 @@ 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
- * 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
- * spawn factory here would produce two log files per respawn with the
- * epoch record naming the wrong one. Leaving it unset means a respawn's
- * output lands in the supervision module's own log file under the same
- * per-instance logs directory D-23 requires, and the epoch record names
- * the file that actually received the output.
+ * once per launch, so the real launch path (handleAcquire's own cold arm,
+ * here -- the second real launch path this comment used to name, the warm
+ * floor, was retired once the connection became the lease) 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 spawn factory here would produce two log files
+ * per respawn with the epoch record naming the wrong one. Leaving it unset
+ * means a respawn's output lands in the supervision module's own log file
+ * under the same per-instance logs directory the epoch record already
+ * requires, and the epoch record names the file that actually received the
+ * output.
  *
- * CR-01 (03-REVIEW.md): `backend` is a REQUIRED positional parameter, not an
+ * `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
@@ -275,8 +304,8 @@ function superviseDepsFor(stateDir, state, backend, binmonHost) {
 /** Exported ONLY so a test can install withCrashSupervision() through the
  * REAL deps object this module actually uses in production, rather than a
  * hand-built SuperviseChildDeps that can (and did) diverge from it -- the
- * exact blind spot CR-01 (03-REVIEW.md) lived in: broker-launch.test.ts's own
- * respawn/recycle tests each construct their deps inline and therefore pass
+ * exact blind spot the backend-argv bug above lived in: broker-launch.test.ts's
+ * own respawn/recycle tests each construct their deps inline and therefore pass
  * `backend: "stock"` directly, so the production builder's missing field was
  * invisible to the whole suite. Same discipline as broker-kill.mts's
  * `_HANDLED_SIGNALS`: an underscore-prefixed alias, never called by any
@@ -294,37 +323,75 @@ function markDeliberateDeath(instance, respawnAfterKill) {
     instance.deliberateKill = true;
     instance.respawnAfterKill = respawnAfterKill;
 }
+// ---------------------------------------------------------------------------
+// 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.
+//   - 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
- * the caller fall through to a cold launch (P-03). Regardless of
- * `record.reason`: per D-07, a waiting request takes an instance whichever
- * reason booted it, so a warm-floor instance and a not-yet-granted instance are
- * equally eligible. Kill-never-recycle needs no separate guard here --
+ * the caller fall through to a cold launch. Regardless of `record.reason`:
+ * a waiting request takes an instance whichever reason booted it, so a
+ * warm-floor instance and a not-yet-granted instance are equally eligible.
+ * Kill-never-recycle needs no separate guard here --
  * handleRelease() below already deletes a released instance's record
  * outright, so a released instance is structurally absent from
  * `state.instances` and can never be a candidate.
  *
  * A candidate whose grant-time probe FAILS is dropped -- de-registered from
  * `state.instances` -- and identity-verified-killed BEFORE the walk
- * continues to the next candidate, but per WR-02
- * (`.planning/todos/pending/2026-08-05-wr-02-*`, decision: fix now rather
- * than defer further) the kill itself is fire-and-forget, matching
- * handleRelease()'s own posture a few hundred lines below
- * (`verifiedKill(...).catch(...)`, never awaited by that call site either):
- * the acquiring request must not wait up to `VICE_BROKER_KILL_WAIT_S`
- * (default 5s) of SIGTERM-then-poll-then-SIGKILL PER DEAD CANDIDATE before
- * the walk can move on -- that wait is exactly what turns a warm floor's
- * fast, in-memory grant into a multi-second serial teardown on a single
- * request's hot path once the warm floor is configured above its default
- * of 1 (WR-02's own bounding condition). The drop -- `markDeliberateDeath()`
+ * continues to the next candidate, but the kill itself is deliberately
+ * fire-and-forget, matching handleRelease()'s own posture a few hundred
+ * lines below (`verifiedKill(...).catch(...)`, never awaited by that call
+ * site either): the acquiring request must not wait up to
+ * `VICE_BROKER_KILL_WAIT_S` (default 5s) of SIGTERM-then-poll-then-SIGKILL
+ * PER DEAD CANDIDATE before the walk can move on -- that wait is exactly
+ * what turns a warm floor's fast, in-memory grant into a multi-second
+ * serial teardown on a single request's hot path once the warm floor is
+ * configured above its default of 1. The drop -- `markDeliberateDeath()`
  * plus `state.instances.delete()` -- still happens SYNCHRONOUSLY, in the
  * same tick as the probe failure, before `deps.kill(...)` is even invoked;
- * only the kill's own SETTLEMENT is decoupled from this walk. This is
- * WR-02's fix option 1, not option 2 (capping how many failed candidates a
- * single acquire will wait through): option 1 matches an idiom the file
- * already uses elsewhere rather than inventing a new bound, and removes the
- * wait entirely rather than merely capping it. The grant-time-probe-failure
+ * only the kill's own SETTLEMENT is decoupled from this walk. This matches
+ * an idiom the file already uses elsewhere rather than inventing a new
+ * bound, and removes the wait entirely rather than merely capping it, by
+ * design: capping how many failed candidates a single acquire will wait
+ * through was the alternative considered and rejected. The grant-time-probe-failure
  * log line's own ordering is decoupled accordingly (see below) -- it can no
  * longer name the kill's resolved stage synchronously, since nothing here
  * waits for it to resolve. The marker is set BEFORE any signal reaches the
@@ -337,29 +404,50 @@ function markDeliberateDeath(instance, respawnAfterKill) {
  * immediately after every `await` (the probe call itself) and BEFORE ever
  * treating a probe-live candidate as the winner -- this is what makes the
  * caller's own "no await between selection and the grant-recording step"
- * property (T-01.6.2.1-03) actually hold under two concurrent acquires. A
- * candidate's own probe response cannot change because a sibling acquire
- * granted it first, but its RECORDED state does, the instant that sibling's
- * synchronous grant step runs -- recorded state alone catches that case.
- * It does NOT catch a sibling that has already DROPPED this exact candidate
- * (a failed grant-time probe: markDeliberateDeath() + state.instances.delete(),
- * which never touches record.state -- the drop path a few lines below) --
- * 01.6.2.1-VERIFICATION.md's CR-01 finding, re-confirmed here: a state-only
- * recheck is blind to a concurrent drop, letting a second caller's stale
- * object reference win a grant for a record that is no longer in
- * state.instances at all, orphaning the grant. Rechecking
+ * property actually hold under two concurrent acquires. A candidate's own
+ * probe response cannot change because a sibling acquire granted it first,
+ * but its RECORDED state does, the instant that sibling's synchronous grant
+ * step runs -- recorded state alone catches that case. It does NOT catch a
+ * sibling that has already DROPPED this exact candidate (a failed
+ * grant-time probe: markDeliberateDeath() + state.instances.delete(), which
+ * never touches record.state -- the drop path a few lines below) -- a
+ * state-only recheck is blind to a concurrent drop, letting a second
+ * caller's stale object reference win a grant for a record that is no
+ * longer in state.instances at all, orphaning the grant. Rechecking
  * `state.instances.get(record.port) === record` (identity, not merely a
  * port-number lookup) closes that case too. */
 async function selectWarmInstance(state, deps) {
     for (const record of Array.from(state.instances.values())) {
         if (record.state !== "ready")
             continue;
+        // 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;
         // "dropped" removes the record from state.instances outright and never
         // touches record.state -- so map membership must be rechecked too, not
-        // merely the state field (CR-01, 01.6.2.1-REVIEW.md/01.6.2.1-VERIFICATION.md).
+        // merely the state field.
         if (record.state !== "ready" || state.instances.get(record.port) !== record) {
             continue;
         }
@@ -367,27 +455,27 @@ async function selectWarmInstance(state, deps) {
             return record;
         }
         // Drop and de-register FIRST, synchronously, before the kill is even
-        // invoked -- this is what CR-01's identity recheck above depends on:
-        // the record must already be gone from state.instances by the time a
-        // concurrent sibling's own probe on this same candidate resolves.
-        // WR-02 only changes what happens to the kill's own PROMISE next, never
-        // this ordering.
+        // invoked -- this is what the identity recheck above depends on: the
+        // record must already be gone from state.instances by the time a
+        // concurrent sibling's own probe on this same candidate resolves. The
+        // fire-and-forget kill below only changes what happens to the kill's
+        // own PROMISE next, never this ordering.
         markDeliberateDeath(record, false);
-        // CR-02 (03-REVIEW.md): dropping a record is also where its second
+        // Dropping a record is also where its second
         // (`-remotemonitor`) port stops being spoken for -- deleteInstanceRecord()
         // is the ONE place both mutations happen together, so a drop can never
         // leak a port out of the fixed allocation band.
         deleteInstanceRecord(state, record.port);
         // Distinct wording from shutdown()'s own "shutdown complete" line
         // (broker-kill.mts) and from handleRecycleForRealBroker's own log-free
-        // path -- D-07's standing constraint that a lifecycle decision must be
+        // path -- the standing constraint that a lifecycle decision must be
         // reconstructable from the log after an incident (both 2026-08-01 and
         // 2026-08-02 were diagnosed from broker log lines). Logged BEFORE the
-        // kill settles (WR-02): the walk does not wait for deps.kill(...) to
+        // kill settles: the walk does not wait for deps.kill(...) to
         // resolve, so this line can no longer name the kill's resolved stage --
         // that gets its own, separately-logged line once the kill settles,
         // below.
-        deps.log(`vice-broker: grant-time probe failed for port ${record.port} (pid ${record.pid ?? "null"}) -- dropped the record and kicked off an identity-verified kill of the pid (not awaited by the acquire walk, WR-02)`);
+        deps.log(`vice-broker: grant-time probe failed for port ${record.port} (pid ${record.pid ?? "null"}) -- dropped the record and kicked off an identity-verified kill of the pid (not awaited by the acquire walk)`);
         // Fire-and-forget, matching handleRelease()'s own posture
         // (`verifiedKill(...).catch(...)`, a few hundred lines below in this
         // same file) -- the acquire walk moves on to the next candidate (or
@@ -414,8 +502,8 @@ async function selectWarmInstance(state, deps) {
  * The warm-instance selection arm (selectWarmInstance(), P-01) runs BEFORE
  * the cold-launch arm; `atCapacity()` gates ONLY the cold-launch arm --
  * checked only once selectWarmInstance() has already answered `null` (no
- * probe-live candidate available) -- NOT before either arm (WR-01,
- * 01.6.2.1-REVIEW.md). A full host still refuses a fresh cold launch before
+ * probe-live candidate available) -- NOT before either arm. A full host
+ * still refuses a fresh cold launch before
  * ever touching the port allocator, but a ready, probe-live warm candidate
  * is grantable even when the ceiling is already reached: granting it
  * creates no NEW instance and does not raise `countTotal()`, so refusing to
@@ -434,17 +522,17 @@ async function selectWarmInstance(state, deps) {
  * control.mts's own attemptAcquire()/enqueueAcquire() queue the request and
  * retry it later rather than refusing it. */
 export async function handleAcquire(requestId, stateDir, state, deps = {}) {
-    // WR-01: the readiness probe is backend-aware, from the SAME threaded-down
+    // 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().
+    // UNCHANGED from broker-kill.mts, 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;
@@ -467,12 +555,20 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
             state,
             stateDir,
             allocatePort: nextFreePort,
-            // CR-01 (03-REVIEW.md): the SAME local `backend` const resolved at the
+            // The SAME local `backend` const resolved at the
             // top of this function feeds BOTH the initial argv (here) and the
             // supervision deps below, so a crash-respawn of this instance can never
             // build a different backend's argv than the launch it replaces.
             backend,
             allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
+            // 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,46 +578,76 @@ export async function handleAcquire(requestId, stateDir, state, deps = {}) {
                 }),
         });
         if (!result.ok) {
+            // `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) {
-            // WR-03 (01.6.2.1-REVIEW.md): the spawn never forked a real process
-            // (e.g. a bad VICE_BIN path), so there is nothing to signal -- the
-            // fix is deleting the just-created broken record alone. Without this,
-            // a configuration failure would silently occupy a port slot and count
-            // toward countTotal()/atCapacity() until crash supervision's own
-            // delayed respawn/give-up machinery eventually noticed and freed it,
-            // 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().
+            // The spawn never forked a real process (e.g. a bad VICE_BIN path),
+            // so there is nothing to signal -- the fix is deleting the
+            // just-created broken record alone. Without this, a configuration
+            // failure would silently occupy a port slot and count toward
+            // countTotal()/atCapacity() until crash supervision's own delayed
+            // respawn/give-up machinery eventually noticed and freed it, even
+            // though the caller was already told "internal" right now.
+            // deleteInstanceRecord(), not a bare map delete -- a stock launch that
+            // failed this way already had its second port allocated and 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 -- 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. WHY that is true
+        // changed 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`
     // between resolving `record` (whichever arm produced it) and this
     // synchronous pair, so two concurrent acquires can never both grant the
-    // SAME record (T-01.6.2.1-03; see selectWarmInstance()'s own re-check for
+    // SAME record (see selectWarmInstance()'s own re-check for
     // the other half of that guarantee).
     state.grants.set(requestId, { id: requestId, port: record.port, grantedAt: Date.now(), pid: record.pid });
     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,
+            // 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,
  * computed on demand from the SAME in-memory map every other count reads --
  * strictly better than the dropped broker-instances.json projection, which
- * could go stale between passes (D-24). */
+ * could go stale between passes. */
 function handleStatus(state) {
     return Array.from(state.instances.values()).map((r) => ({
         port: r.port,
@@ -529,64 +655,72 @@ function handleStatus(state) {
         state: r.state,
         reason: r.reason,
         epoch: typeof r.epoch === "number" ? r.epoch : null,
-        hasMonitorClient: r.monitorClient !== undefined,
+        // "at least one channel is claimed" -- promoted from
+        // a single-field check, byte-identical wire shape, meaning stated
+        // explicitly.
+        hasMonitorClient: Object.keys(r.monitorClients).length > 0,
     }));
 }
 /** Resolves a monitor_claim/monitor_release target the SAME way
  * handleRelease() and handleRecycleForRealBroker() already resolve theirs:
  * `targetId` is a grant id, looked up in state.grants for its port, then
  * the instance at that port. Returns `null` for an unknown target_id/port
- * so callers answer `bad_request`, never `internal` (plan 05's own
- * acceptance criterion). */
+ * so callers answer `bad_request`, never `internal`. */
 function resolveInstanceForMonitorTarget(targetId, state) {
     const grant = state.grants.get(targetId);
     if (!grant)
         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` (per-channel): 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
- * silently accepted (spoofing a release is exactly T-02-01's own
- * disposition). An instance with no current holder at all tolerates the
+/** Answers `monitor_release` (per-channel): 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 a deliberately refused case). 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,90 +798,34 @@ 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({
+/** The second concern of the fixed-order evaluation pass, RENAMED from the
+ * retired warm-floor maintenance function this replaces (the projection
+ * write is dropped, and the grant sweep does not appear -- the connection
+ * is the lease now, so there is nothing left to sweep for expiry). 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.
+        // 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
  * by handleAcquire()'s single state.grants.set() call site), not merely
- * "whatever now holds this port number." This is Task 2's own closure of
- * CR-01's cross-session-kill blast radius (T-01.6.2.1-28): even after Task
- * 1 closes the specific concurrent-acquire race, this lookup was ALREADY
+ * "whatever now holds this port number." This closes a cross-session-kill
+ * blast radius: even after the specific concurrent-acquire race above is
+ * closed, this lookup was ALREADY
  * unsafe against any OTHER event that swaps a port's occupant without also
  * clearing the grant -- the clearest independent example being an ordinary
  * (non-deliberate) crash of a GRANTED instance that hits the give-up
@@ -771,7 +849,7 @@ export const _maintainWarmFloorForRealBroker = maintainWarmFloorForRealBroker;
  * grant's own recorded pid, and the current occupant's pid (or "none" when
  * the port is empty), worded distinctly from both the shutdown-complete
  * line (broker-kill.mts) and the grant-time-probe-failure line this same
- * file already emits (D-07's standing constraint that a lifecycle decision
+ * file already emits (the standing constraint that a lifecycle decision
  * must be reconstructable from the log after an incident).
  *
  * A legitimate recycle (broker-launch.mts's handleExit() recycle branch)
@@ -785,15 +863,16 @@ 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);
         state.grants.delete(requestId);
-        // CR-02: kill-never-recycle means this instance is gone for good, so its
+        // Kill-never-recycle means this instance is gone for good, so its
         // second (`-remotemonitor`) port must go back to the allocator with it.
         deleteInstanceRecord(state, grant.port);
         verifiedKill({ pid: instance.pid, expectedIdentity: instance.expectedIdentity }).catch(() => {
@@ -811,7 +890,7 @@ export function handleRelease(requestId, state) {
 }
 async function run(args) {
     const finalPath = join(args.stateDir, "broker.json");
-    // Plan 05 (criterion K, D-17): the tracer/plan-04-era "refuse to overwrite
+    // An early tracer-era "refuse to overwrite
     // a record naming a currently-live pid" pre-check is GONE -- REPLACED by
     // the bind-before-write singleton guard below, not merely extended
     // alongside it (this phase's own plan-time note is explicit: the
@@ -824,7 +903,7 @@ async function run(args) {
     // port itself already held" -- and broker.json becomes a pure ARBITER of
     // that question's two possible causes, never a gate in its own right.
     //
-    // D-25: the mandatory start-time banner, printed unconditionally and
+    // The mandatory start-time banner, printed unconditionally and
     // BEFORE anything else in this function runs -- an operator must be told
     // what a Ctrl-C costs before there is anything running for them to Ctrl-C.
     process.stderr.write(`${startupBanner()}\n`);
@@ -834,17 +913,17 @@ async function run(args) {
     const startedAt = new Date().toISOString(); // FIXED across every heartbeat refresh -- see writeBrokerRecordFile()'s callers below
     const pollMs = Number(process.env.VICE_BROKER_POLL_MS) || 500;
     const controlPort = resolveControlPort();
-    // Criterion I / D-15: the unconditional startup reap runs BEFORE the
+    // The unconditional startup reap runs BEFORE the
     // control listener accepts and before anything is launched. A SIGKILLed
     // prior broker never ran a shutdown path, so this is the only place the
     // "every emulator this project's port band could be squatting is either
     // ours or a human's own work" guarantee can be enforced -- no marker file
     // is consulted, per this reap's own header comment in broker-kill.mts.
     //
-    // NOTE (plan 05): this reap runs UNCONDITIONALLY, before the bind attempt
+    // NOTE: this reap runs UNCONDITIONALLY, before the bind attempt
     // below -- including for a process that goes on to LOSE the singleton
     // race a moment later (see the EADDRINUSE handling below). That ordering
-    // is D-15's own, already established and tested by plan 04
+    // is deliberate and already established and tested
     // (broker-kill.test.ts's own structural source-order check); this task
     // does not change it. A losing second broker's own reap pass is an
     // accepted, pre-existing consequence of "the reap is unconditional" --
@@ -855,59 +934,111 @@ async function run(args) {
         nextEpochFor,
         writeEpochRecord,
     });
-    // Plan 02-07 (D-01, D-03): resolved ONCE here, after the unconditional
+    // Resolved ONCE here, after the unconditional
     // startup reap and BEFORE the control listener binds -- never re-read per
     // 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).
+    // There is nothing left to detect -- the resolved
+    // `backend` is always `"stock"`; what this call still does is resolve the
+    // binary's own identity for the log line below and initialise the
+    // capability cache backend-detect.mts's own record depends on.
     const backendResult = resolvedBackend({ supervisorDir: args.stateDir });
     const backend = backendResult.backend;
-    process.stderr.write(`vice-broker: backend "${backend}" (source: ${backendResult.source}, binary: ${backendResult.binPath})\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.
+    process.stderr.write(`vice-broker: backend "${backend}" (binary: ${backendResult.binPath})\n`);
+    // THE BROKER mints/verifies the
+    // Ghidra runs-root handle here -- after the unconditional startup reap
+    // above, and BEFORE the control listener below accepts a single
+    // 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`);
+    }
+    // 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 {
         listener = await startControlListener({
             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
+                // 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 }),
+                // 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),
+            // 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.
+            // 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).
+                // 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,
             }),
         });
     }
     catch (e) {
-        // Criterion K / D-17 / D-18: CR-01 closes here. A well-known TCP port
+        // The singleton race closes here. A well-known TCP port
         // cannot be bound twice, so EADDRINUSE is the kernel enforcing the
         // singleton -- but the guarantee holds only while the control port
         // keeps its default (two brokers deliberately configured onto
@@ -942,7 +1073,7 @@ async function run(args) {
         process.exitCode = 1;
         return;
     }
-    // C5: every catchable shutdown path (SIGTERM/SIGINT/SIGHUP, an uncaught
+    // Every catchable shutdown path (SIGTERM/SIGINT/SIGHUP, an uncaught
     // exception, an unhandled rejection, normal exit) converges on ONE
     // re-entrant-safe teardown that identity-verified-kills every instance
     // this broker launched and clears the map unconditionally
@@ -950,12 +1081,22 @@ async function run(args) {
     // nothing to tear down before that point.
     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
+    // whatever was there -- the bind itself is the proof of singleton status.
+    // The fourteen-field set (narrowed to thirteen once the warm floor was
+    // retired, 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, so there is no separate expiry left to
+    // track -- `warm_floor` is likewise gone (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 +1104,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 +1125,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
+    // the retiring bash daemon's own broker_once() ordering (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
+    // (an early stubbed `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 +1147,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`);
@@ -1014,8 +1158,8 @@ async function run(args) {
     }, pollMs);
 }
 /** Parses argv, evaluates the container guard FIRST -- before any state
- * directory is read or written and before anything is spawned (PD-03) --
- * then runs the long-lived broker. Never calls process.exit(); always sets
+ * directory is read or written and before anything is spawned -- then
+ * runs the long-lived broker. Never calls process.exit(); always sets
  * process.exitCode so pending I/O flushes first. */
 export function main(argv = process.argv.slice(2)) {
     let args;