@henols/vice-mcp 0.2.2 → 0.2.3

package/resources/broker-launch.mjs

@@ -2,7 +2,7 @@
 // Compiled by `tsc` from broker-launch.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.
 // broker-launch.mts
 //
@@ -14,8 +14,12 @@
 // in-process mechanism (collapsed from a three-way branch by Phase
 // 01.6.2.1's own plan 02 -- D-05 as amended by P-05/P-06/P-07; see
 // probeReady()'s own header comment below for the amendment's record),
-// serialised warm-floor maintenance (one launch per pass, never more), and
-// the fixed-order evaluation pass both surviving concerns run through.
+// the launching -> ready promotion sweep (promoteLaunchingInstances() --
+// plan 41-05, folded todo: this used to be step 1 inside a warm-floor
+// maintenance function that speculatively pre-launched spare instances;
+// that floor is RETIRED and VICE now launches strictly on demand, but the
+// promotion sweep outlived it), and the fixed-order evaluation pass both
+// surviving concerns run through.
 //
 // Plan 03, Task 2 grows this module into a real per-child supervisor
 // (C2/D-23), absorbing resources/vice-supervisor.sh wholesale: superviseChild()
@@ -71,6 +75,37 @@ let warnedBinmonBindWidened = false;
 // caller could widen one host override and not the other, though in
 // practice both resolve from the same `binmonHost` value below).
 let warnedRemoteMonitorBindWidened = false;
+/** Phase 33, plan 33-05 (`REPRO-01`): the random seed the stock determinism
+ * block pins, and the exact value the reproduction was measured with on this
+ * host -- exported so a capture record's reproducibility key can cite ONE
+ * definition rather than re-deriving a literal that could silently drift away
+ * from the launches it claims to describe. MEASURED 2026-09-02 against genuine
+ * stock 3.9 over `-binarymonitor` (33-RESEARCH.md M3): two cold boots WITHOUT
+ * the block differ at 59 of the 4080 addresses in the untouched `$C000-$CFEF`
+ * window; WITH it, at 0 of 4080. */
+export const STOCK_DETERMINISM_SEED = 4242;
+/** Phase 33, plan 33-05 (`REPRO-01`): the determinism block, in ONE fixed
+ * order, emitted UNCONDITIONALLY by the stock branch below (never gated on
+ * `profile` -- see buildViceArgs()'s own comment above `args`). Exported and
+ * frozen so tests and evidence scripts assert against this single definition
+ * instead of a second hand-copied array, and so no caller can mutate the
+ * shared value into a launch that no longer matches the recorded seed.
+ *
+ * The order is fixed and load-bearing beyond readability: `REPRO-04` keys
+ * captures on an argv digest, so a block whose element order varied between
+ * two launches on the same port would produce two digests for one launch
+ * intent. */
+export const STOCK_DETERMINISM_FLAGS = Object.freeze([
+    "-seed",
+    String(STOCK_DETERMINISM_SEED),
+    "-raminitstartrandom",
+    "0",
+    "-raminitrepeatrandom",
+    "0",
+    "-raminitrandomchance",
+    "0",
+    "+autostart-delay-random",
+]);
 /** Resolves the emulator's own argument vector for the given `backend`. The
  * `VICE_ARGS` full-override short-circuit (matching
  * resources/vice-supervisor.sh's own VICE_ARGS convention exactly) is
@@ -80,15 +115,12 @@ let warnedRemoteMonitorBindWidened = false;
  * understands neither `-mcpserver` nor `-binarymonitor` flags, and that need
  * does not depend on which backend is configured.
  *
- * `backend: "fork"` returns exactly the pre-Phase-2 shape, byte-identical:
- * the MCP server flag, the MCP server host from `mcpHost` or
- * VICE_BROKER_MCP_HOST (default `0.0.0.0`), and the MCP server port.
- *
- * `backend: "stock"` returns `-binarymonitor -binarymonitoraddress
+ * `backend: "stock"` (FORKRM-01, plan 52-06: the only value `ViceBackend` has
+ * left) returns `-binarymonitor -binarymonitoraddress
  * ip4://<host>:<port>` (docs/phase1-probe-results.md's confirmed real-world
  * command line). The host resolves from `binmonHost` or
  * VICE_BROKER_BINMON_HOST, defaulting to `127.0.0.1` -- deliberately
- * narrower than the fork path's `0.0.0.0` default, because VICE's binary
+ * narrow, because VICE's binary
  * monitor is unauthenticated by design and grants full read/write over the
  * emulated machine plus process control to anything that can reach it
  * (planner decision, `02-03-PLAN.md`). Widening the bind away from loopback
@@ -111,11 +143,29 @@ let warnedRemoteMonitorBindWidened = false;
  * than implied stock-3.9 coverage. Widening THIS bind away from loopback emits
  * its own one-time stderr note (`warnedRemoteMonitorBindWidened`), naming
  * the resolved address and stating that VICE's TEXT monitor accepts
- * arbitrary monitor commands and is unauthenticated -- Phase 3 dials
- * nothing on this port; only the launch flag lands now (see D-13's own
- * rationale: adding the flag later would require relaunching a live
- * instance, destroying all emulation state). */
-export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv, remoteMonitorPort, }) {
+ * arbitrary monitor commands and is unauthenticated. Phase 41 dials this
+ * port (text-connect.ts's textConnect()) and Phase 41-05 (D-16) made it
+ * MANDATORY on every stock launch -- a stock launch that cannot bind it now
+ * fails the whole acquire rather than launching without it (see D-13's own
+ * rationale for why the flag itself is set at launch time and not added
+ * later: doing so would require relaunching a live instance, destroying all
+ * emulation state).
+ *
+ * Phase 33, plan 33-05 (`D-15`, `REPRO-01`, `REPRO-05`): the stock branch now
+ * also emits STOCK_DETERMINISM_FLAGS unconditionally, and takes an optional
+ * `profile` for the two additive launch knobs. Deliberately in the same
+ * register as tryLaunchOne's own widened `spawn` field below, and for the same
+ * reason: `profile` is optional, so every pre-existing caller and every
+ * pre-existing test stub keeps compiling and behaving identically, and an
+ * ABSENT profile produces exactly the same argv as an empty one or one whose
+ * knobs are both `false`. What optionality could NOT save (33-RESEARCH.md P7,
+ * and the `D-15` amendment rider dated 2026-09-02): the determinism block is
+ * unconditional on stock, so all FIVE stock whole-argv assertions in
+ * broker-launch.test.ts move even with `profile` absent -- it is the block and
+ * not the profile that moves them. `D-15`'s byte-identity claim therefore
+ * survives in full only for the `profile` half: an absent profile adds no
+ * flag. */
+export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv, remoteMonitorPort, profile, }) {
     const rawViceArgs = viceArgsEnv ?? process.env.VICE_ARGS;
     if (typeof rawViceArgs === "string" && rawViceArgs.trim() !== "") {
         return rawViceArgs.trim().split(/\s+/);
@@ -138,11 +188,31 @@ export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv,
         // first element: it is VICE's reset-to-compiled-in-defaults instruction,
         // not an inert "these are the baselines" no-op, so any flag emitted
         // before it (including -drive8type) is silently clobbered back to its
-        // compiled-in value. `-drive8type 1541` therefore has to come
-        // immediately after `-default`, and -- per CLAUDE.md's documented
-        // constraint -- `-default` also has to come before `-binarymonitor` or
-        // the monitor never binds and the subsequent connect hangs in the
-        // backlog looking exactly like a wedge. Confirmed sufficient live in
+        // compiled-in value. `-drive8type 1541` therefore has to come AFTER
+        // `-default` -- not necessarily IMMEDIATELY after -- and -- per
+        // CLAUDE.md's documented constraint -- `-default` also has to come before
+        // `-binarymonitor` or the monitor never binds and the subsequent connect
+        // hangs in the backlog looking exactly like a wedge.
+        //
+        // WORDING CORRECTED (33 review WR-09). This paragraph used to say
+        // "immediately after `-default`", which the `-console` block below now
+        // violates by construction whenever `profile.headless` is set -- leaving
+        // the next editor to find code contradicting the comment and having to
+        // re-derive which one is authoritative. What is load-bearing is the
+        // RELATIVE ORDER (`-default` precedes everything it resets), not
+        // adjacency.
+        //
+        // The `-console` block's own citation was `alive=yes bound=1`, which does
+        // NOT cover this paragraph's property: I-2's failure mode is Drive8Type
+        // silently reverting to 0 (NONE) WHILE THE MONITOR STILL BINDS FINE, so
+        // liveness and boundness cannot tell the good case from the failure being
+        // guarded against. Re-verified against the resource itself
+        // [VERIFIED: live probe 2026-09-03, genuine unpatched stock
+        // /usr/bin/x64sc (VICE 3.9), DISPLAY and WAYLAND_DISPLAY both unset]:
+        //   [-default -console -drive8type 1541 <determinism> -binarymonitor]
+        //     alive=yes bound=1  Drive8Type=1541  Drive8TrueEmulation=1
+        // read over `RESOURCE_GET` (0x51) with `-console` interposed. So the
+        // citation now covers the RESOURCE and not only liveness. Confirmed sufficient live in
         // Phase 8.1's standalone probe (08.1-WALKTHROUGH-EVIDENCE.md §4):
         // `resourceget "Drive8Type"` moved 0 -> 1541 and a `load` over the text
         // monitor succeeded immediately. Deliberately NOT setting
@@ -153,7 +223,81 @@ export function buildViceArgs(port, { backend, mcpHost, binmonHost, viceArgsEnv,
         // might default Drive8TrueEmulation to 0) is read and deliberately not
         // pre-emptively defended against here; plan 03's live test is what would
         // surface it if that assumption is ever wrong on a different build.
-        const args = ["-default", "-drive8type", "1541", "-binarymonitor", "-binarymonitoraddress", `ip4://${host}:${port}`];
+        //
+        // Phase 33, plan 33-05, `-console` at index 1 (`REPRO-05`, `D-15`): the
+        // headless route is `-console`, and its POSITION is as load-bearing as
+        // `-default`'s. `-console` is handled in the SAME `main.c` pre-scan as
+        // `-default` -- that loop `break`s at the first option it does not
+        // recognise and then strips the prefix it handled from argv
+        // [CITED: vice-3.8/src/main.c:184-192, 232-238] -- and `console_mode`
+        // gates GTK initialisation at two call sites (`ui_init_with_args`,
+        // `ui_init`) that BOTH run before the late command-line parser
+        // `initcmdline_check_args()` [CITED: vice-3.8/src/main.c:296-345]. A
+        // `-console` seen only by the late parser therefore arrives after GTK has
+        // already tried and failed. MEASURED 2026-09-02 with `DISPLAY` and
+        // `WAYLAND_DISPLAY` both unset (33-RESEARCH.md P5):
+        //   [-default -console -binarymonitor]                    alive=yes bound=1
+        //   [-default -drive8type 1541 -console -binarymonitor]   alive=no  bound=0  Gtk-WARNING: cannot open display:
+        //   [-default -console -drive8type 1541 -binarymonitor]   alive=yes bound=1
+        // So `-console` goes immediately after `-default` and BEFORE
+        // `-drive8type` -- which is compatible with the I-2 paragraph above as
+        // corrected (33 review WR-09): that constraint is `-drive8type` AFTER
+        // `-default`, not adjacent to it, and the interposition was re-verified
+        // over `RESOURCE_GET` to leave Drive8Type=1541 rather than only to leave
+        // the monitor bound. It is pinned by an ordering assertion rather than by
+        // this comment -- a bare flag push with no reason is exactly what let the
+        // `-default` ordering constraint be rediscovered by a red CI run last
+        // time.
+        //
+        // Phase 33, plan 33-05, the determinism block (`REPRO-01`): emitted
+        // UNCONDITIONALLY on stock, never gated on `profile`. Read over
+        // `RESOURCE_GET` (0x51) on this build under `-default -drive8type 1541`
+        // [VERIFIED: live probe 2026-09-02, 33-RESEARCH.md M2],
+        // `-raminitrandomchance 0` is the LOAD-BEARING one: the factory value is
+        // **10**, i.e. 0.1% of all RAM bits randomly flipped at power-up, and it is
+        // the dominant term in the divergence this milestone removes. The
+        // `-raminitstartrandom 0` / `-raminitrepeatrandom 0` pair already reads 0
+        // at factory and is DEFENSIVE against an operator `vicerc` -- belt and
+        // braces alongside the scratch `XDG_CONFIG_HOME` the I-1 rider threads in
+        // spawnAndRecordInstance() below.
+        //
+        // `+autostart-delay-random` is a FIFTH flag beyond `REPRO-01`'s text
+        // (which names only `-seed` plus the three `raminit*`), recorded here as a
+        // deliberate ADDITION rather than smuggled in. `AutostartDelayRandom`
+        // ships at **1** on this build [VERIFIED: same probe], it draws an
+        // additional random delay of up to 10 frames
+        // [CITED: vice-3.8/src/autostart.c:1432-1436], and -- the effect that is
+        // easy to miss -- it also SELECTS WHICH keyboard-buffer feed injects `RUN`
+        // (`kbdbuf_feed_runcmd` when set, `kbdbuf_feed` when clear)
+        // [CITED: vice-3.8/src/autostart.c:882-886]. Disabling it is therefore a
+        // behavioural change and not only a timing one. Pin it once; never toggle
+        // it between the two runs of a capture pair.
+        //
+        // Phase 33, plan 33-05, `-warp` (`D-15`): position-free (MEASURED
+        // 2026-09-02), placed here only so the argv reads in the order a human
+        // would describe it. Launch-time is the ONLY route on stock: there is no
+        // runtime `WarpMode` resource at all (`RESOURCE_GET` replies `err=0x01`
+        // OBJECT_MISSING on 3.9), so no runtime setter can exist here. Worth
+        // roughly **1.97x** on this host and this launch profile -- 5.23 emulated
+        // seconds against 2.65 over the same 5 s wall clock [MEASURED:
+        // evidence/33-wallclock-control.md, Control B instance 1] -- and NOT the
+        // order of magnitude a reader may assume; `AUTOSTART` additionally turns
+        // warp on by itself during the load whatever argv says, so both loads are
+        // warped either way. It is behaviour-neutral under a frame-anchored
+        // protocol (identical registers and one identical 64K sha256 across a
+        // warped and an unwarped run, same source), which is the precondition
+        // `33-06` needs before `profile.warp` ships; it is NOT neutral for a
+        // wall-clock bracket, which it invalidates by 1.76x.
+        const args = ["-default"];
+        if (profile?.headless) {
+            args.push("-console");
+        }
+        args.push("-drive8type", "1541");
+        args.push(...STOCK_DETERMINISM_FLAGS);
+        if (profile?.warp) {
+            args.push("-warp");
+        }
+        args.push("-binarymonitor", "-binarymonitoraddress", `ip4://${host}:${port}`);
         if (typeof remoteMonitorPort === "number") {
             if (host !== "127.0.0.1" && !warnedRemoteMonitorBindWidened) {
                 warnedRemoteMonitorBindWidened = true;
@@ -186,12 +330,30 @@ function spawnAndRecordInstance(reason, port, deps) {
     const spawnFn = deps.spawn ?? ((cmd, args, opts) => nodeSpawn(cmd, args, opts));
     const now = deps.now ?? (() => Date.now());
     const viceBin = deps.viceBin ?? process.env.VICE_BIN ?? "x64sc";
-    const backend = deps.backend ?? "fork";
+    const backend = deps.backend ?? "stock";
+    // Plan 41-05 (D-16): the ONE construction site for a fresh InstanceRecord
+    // asserts the invariant every downstream consumer (HeldLease,
+    // textConnect(), etc.) was written against -- a stock record NEVER lacks a
+    // text-monitor port. acquirePortAndLaunch() above already fails the whole
+    // acquire before ever reaching this function when the second allocation
+    // fails, so a caller that lands here with `backend: "stock"` and no
+    // `remoteMonitorPort` is a defect in THIS module (a call site that bypassed
+    // that guarantee), not a state a stock record may legitimately carry --
+    // throw by name rather than silently writing a record that violates it.
+    // The fork case is real and unaffected: this check is stock-only.
+    if (backend === "stock" && deps.remoteMonitorPort === undefined) {
+        throw new Error("spawnAndRecordInstance: backend \"stock\" requires remoteMonitorPort (D-16) -- a stock launch that cannot bind a text-monitor port must fail the acquire before reaching this construction site, never write a portless stock record");
+    }
     const viceArgs = buildViceArgs(port, {
         backend,
         mcpHost: deps.mcpHost,
         binmonHost: deps.binmonHost,
         remoteMonitorPort: deps.remoteMonitorPort,
+        // Phase 33, plan 33-06: the ONE place a launch's profile becomes argv.
+        // The record built below mirrors the SAME value, so an instance's
+        // recorded profile and its actual argv are written in one step and
+        // cannot disagree.
+        profile: deps.profile,
     });
     const log = deps.log ?? defaultLog;
     // I-1 rider (audit §4.4, 08.2-02-PLAN.md Task 2): production stock
@@ -204,24 +366,23 @@ function spawnAndRecordInstance(reason, port, deps) {
     // unreachable) and pass it as a third options argument carrying `env`
     // only. Never `shell: true`: the existing array-form spawn(viceBin,
     // viceArgs) call avoids shell interpretation entirely and that property
-    // must survive this widening. For backend === "fork", spawnFn is called
-    // with NO third argument at all, so the fork path's observable behaviour
-    // stays bit-for-bit what it was (BACK-02 is a standing gate and the fork
-    // backend has been the sole production backend across all of v0.1.x).
+    // must survive this widening.
     //
     // Scope boundary (do not remove this note): the production broker daemon
     // always supplies its own deps.spawn / deps.spawnFactory, so the widened
     // default wrapper above is dead code on the real launch paths. This
     // function's job is only to COMPUTE the value at the one seam that should
-    // own it; the forwarding to nodeSpawn() happens at four further hops --
-    // makeLoggingSpawn() and maintainWarmFloorForRealBroker's inner
-    // stashingSpawn in vice-broker.mts, and withCrashSupervision()'s wrapper
-    // body and launchSupervised()'s defaultRealSpawn in this file. All four
-    // now forward the options argument (plan 08.2-06 closed them in this same
-    // phase, with a handleAcquire() composition test that omits
-    // buildColdSpawnFactory so an injected stub cannot fake the proof). If you
-    // add a fifth spawn hop, it must forward options too, or production stock
-    // launches silently lose their config isolation again.
+    // own it; the forwarding to nodeSpawn() happens at three further hops --
+    // makeLoggingSpawn() in vice-broker.mts, and withCrashSupervision()'s
+    // wrapper body and launchSupervised()'s defaultRealSpawn in this file
+    // (plan 41-05, folded todo: a FOURTH hop, the retired warm floor's own
+    // inner stashingSpawn closure in vice-broker.mts, is REMOVED along with
+    // the function that held it). All three now forward the options argument
+    // (plan 08.2-06 closed them in this same phase, with a handleAcquire()
+    // composition test that omits buildColdSpawnFactory so an injected stub
+    // cannot fake the proof). If you add another spawn hop, it must forward
+    // options too, or production stock launches silently lose their config
+    // isolation again.
     //
     // Scratch-dir lifetime: this function deliberately does NOT clean the
     // directory up -- the spawned emulator process outlives this function's
@@ -254,7 +415,26 @@ function spawnAndRecordInstance(reason, port, deps) {
         viceBin,
         viceArgs,
         dryRun: false,
+        // Plan 41-03 (D-14): non-optional, defaulted to an empty map -- "no
+        // claim on any channel" is an empty map, never an absent field. The
+        // ONE place a fresh InstanceRecord is constructed, so this is the ONE
+        // place this default is set.
+        monitorClients: {},
+        // Plan 41-05 (D-16): key omitted only on the FORK path now -- the guard
+        // above already throws before this point for any stock call with no
+        // remoteMonitorPort, so a stock record reaching this line always
+        // supplies the key. "Absent" means fork, never "stock allocation
+        // failed" (that state no longer exists).
         ...(deps.remoteMonitorPort === undefined ? {} : { remoteMonitorPort: deps.remoteMonitorPort }),
+        // Phase 33, plan 33-06: same key-omitted-when-undefined idiom as
+        // remoteMonitorPort directly above. An absent request must produce a
+        // record with NO `profile` key at all -- not `profile: undefined` --
+        // because "absent means profile-less" is the property a broker restarted
+        // mid-phase relies on when it reads records written before this field
+        // existed. A copy, not the caller's own object: the record outlives this
+        // call and a caller mutating its profile afterwards must not silently
+        // change what this instance claims it was launched with.
+        ...(deps.profile === undefined ? {} : { profile: { ...deps.profile } }),
     };
     deps.state.instances.set(port, record);
     return record;
@@ -271,10 +451,10 @@ function spawnAndRecordInstance(reason, port, deps) {
  *
  * This is the RIGHT primitive when the port is already decided and fixed
  * (most tests; any future caller with its own allocation scheme). It is
- * deliberately NOT what handleAcquire or maintainWarmFloor call for a
- * FRESH port, because nextFreePort() itself is asynchronous (a real
- * port-in-use probe requires it) -- see acquirePortAndLaunch()'s own
- * header comment for the race that creates and how it is closed. */
+ * deliberately NOT what handleAcquire calls for a FRESH port, because
+ * nextFreePort() itself is asynchronous (a real port-in-use probe requires
+ * it) -- see acquirePortAndLaunch()'s own header comment for the race that
+ * creates and how it is closed. */
 export function tryLaunchOne(reason, port, deps) {
     if (inFlight)
         return null;
@@ -291,26 +471,37 @@ export function tryLaunchOne(reason, port, deps) {
  * instant tryLaunchOne() alone guards. This closes a genuine race window
  * tryLaunchOne() cannot: nextFreePort()'s own port-in-use probe is
  * asynchronous (plan 02, C4 -- a real bind-and-release check), so two
- * overlapping callers (a cold acquire arriving over the TCP control
- * listener at any moment, and a warm-floor pass on its own poll timer)
- * could otherwise BOTH be told the SAME candidate port is free before
- * either commits it to state.instances -- a double-launch on one port,
- * silently overwriting the earlier record. The guard is checked and set
- * SYNCHRONOUSLY before the first `await`, exactly like tryLaunchOne()'s
- * own discipline, so a second concurrent call is refused immediately
- * (`launch_in_flight`) rather than racing on the allocation.
+ * overlapping callers could otherwise BOTH be told the SAME candidate port
+ * is free before either commits it to state.instances -- a double-launch on
+ * one port, silently overwriting the earlier record. The guard is checked
+ * and set SYNCHRONOUSLY before the first `await`, exactly like
+ * tryLaunchOne()'s own discipline, so a second concurrent call is refused
+ * immediately (`launch_in_flight`) rather than racing on the allocation.
  *
- * This is also the function that restores vice-broker.sh's own
- * process_requests() throttle (its `in_flight` local, checked before a
- * COLD launch, not only before a warm one): a cold acquire and a
- * warm-floor pass can never launch simultaneously, matching the bash
+ * Plan 41-05 (folded todo): this guard's own reasoning OUTLIVED the warm
+ * floor it was originally written alongside -- it exists because of the
+ * 2026-08-01 triple-launch outage (three simultaneous x64sc launches: one
+ * SEGV, one exit 1, one exit 0 at the identical spawn second) and is
+ * regression-tested (CLAUDE.md), and that history has nothing to do with
+ * whether a warm floor exists. Today the only caller of this function is the
+ * cold-acquire arm (vice-broker.mts's handleAcquire(), via `serveAcquires()`
+ * in runBrokerPass()); the overlap this guard closes is now TWO OR MORE
+ * concurrent acquires -- e.g. two requests arriving over the TCP control
+ * listener at nearly the same moment, or one arriving while an EARLIER
+ * acquire's own launch is still resolving -- never a warming pass, which no
+ * longer exists. This is also the function that restores vice-broker.sh's
+ * own process_requests() throttle (its `in_flight` local): whatever launches
+ * this broker ever attempts, they never overlap, matching the bash
  * original's declined-to-change behaviour (RESEARCH.md §A1/§C). D-07
  * (01.6.2.1-03-PLAN.md) layers non-preemptive PRIORITY on top of this same
- * "one at a time" guard, never replacing it: this function still only ever
- * refuses a second concurrent caller (`launch_in_flight`), and never kills
- * or preempts whichever caller already holds the slot -- which reason wins
- * this slot NEXT, once it frees, falls out of runBrokerPass()'s own fixed
- * evaluation order (that function's own invariant comment), not from
+ * "one at a time" guard, never replacing it, and the anti-pattern it names --
+ * killing or relaunching preemptively to serve a newer request -- is likewise
+ * unaffected by the floor's removal: this function still only ever refuses a
+ * second concurrent caller (`launch_in_flight`), and never kills or preempts
+ * whichever caller already holds the slot. Among multiple QUEUED acquires,
+ * which one wins this slot NEXT, once it frees, falls out of the
+ * arrival-ordered pending-acquire structure (broker-control.mts's D-08
+ * mechanism) that requeues a refused acquire for the next pass -- not from
  * anything in this function. The refusal below logs which reason currently
  * holds the slot and which reason is waiting, so the decision is
  * reconstructable from the log after an incident. */
@@ -351,16 +542,27 @@ export async function acquirePortAndLaunch(reason, deps) {
                 // does. `state.blockedPorts` is a plain Set the type import already
                 // describes, so mutating it directly needs no value import at all --
                 // exactly the same discipline handleExit()'s own
-                // `record.monitorClient = undefined` uses in place of
+                // `record.monitorClients = {}` uses in place of
                 // clearMonitorClient().
                 deps.state.blockedPorts.add(remoteResult.port);
                 remoteMonitorPort = remoteResult.port;
             }
             else {
-                // Degrade, never fail: a port nothing dials yet (Phase 3 builds no
-                // text-monitor client) must never make the backend unavailable.
+                // Plan 41-05 (D-16): FAIL, never degrade. Owner direction, verbatim:
+                // "it should not be possible, vice must be started witht the text
+                // channel." A stock launch that cannot bind a text-monitor port
+                // fails the whole acquire -- no process is spawned. The PRIMARY port
+                // allocated moments earlier is not yet in `state.instances` and was
+                // never added to `state.blockedPorts` by this function (only
+                // `nextFreePort()`'s own in-use probe blocks a candidate, and that
+                // never ran against the winning candidate) -- so it is already
+                // allocatable again on the very next call with no further release
+                // step; a discriminating-power test proves this rather than assuming
+                // it. This failure arm must NEVER call spawnAndRecordInstance() or
+                // otherwise leave a port "spoken for" on the caller's behalf.
                 log(`vice-broker: second (-remotemonitor) port allocation failed (${remoteResult.reason}) -- ` +
-                    `launching WITHOUT -remotemonitor; nothing in Phase 3 dials the text-monitor port anyway`);
+                    `abandoning the stock launch; the text-monitor port is mandatory on every stock launch (D-16) and the acquire fails`);
+                return { ok: false, reason: "no_free_text_port" };
             }
         }
         const record = spawnAndRecordInstance(reason, port, {
@@ -374,6 +576,7 @@ export async function acquirePortAndLaunch(reason, deps) {
             backend: deps.backend,
             binmonHost: deps.binmonHost,
             remoteMonitorPort,
+            profile: deps.profile,
         });
         return { ok: true, record };
     }
@@ -393,8 +596,9 @@ export async function acquirePortAndLaunch(reason, deps) {
  * instance permanently consumed one more port out of the fixed
  * PORT_SCAN_CEILING window even though the OS port was free again the instant
  * the owning process exited -- a long-running broker (the explicit design goal
- * of an on-demand pool with crash supervision and a warm floor) eventually
- * exhausts its band and answers `no_free_port` to ordinary launches purely
+ * of an on-demand pool with crash supervision, per plan 41-05 launched
+ * strictly on demand rather than kept warm) eventually exhausts its band and
+ * answers `no_free_port` to ordinary launches purely
  * from routine churn, with no operator recourse short of a broker restart.
  *
  * A RESPAWN is deliberately NOT a call site: the replacement instance keeps
@@ -645,8 +849,8 @@ async function defaultBinmonProbe(port, timeoutMs) {
  * fully honoured by this collapse, not reversed by it.
  *
  * No retry loop, deliberately: a still-booting instance simply fails THIS
- * pass and is re-probed on the next one (maintainWarmFloor()'s own per-pass
- * cadence, or a later grant-time re-probe) -- this is what makes the
+ * pass and is re-probed on the next one (promoteLaunchingInstances()'s own
+ * per-pass cadence, or a later grant-time re-probe) -- this is what makes the
  * shortened ~1s default below safe rather than reckless: a slow host is
  * re-probed, never starved, and the seconds-valued timeout knob
  * (VICE_BROKER_PROBE_TIMEOUT_S) still lets an operator on a slow host raise
@@ -665,61 +869,22 @@ export async function probeReady(port, deps = {}) {
     const httpProbe = deps.httpProbe ?? defaultHttpProbe;
     return httpProbe(port, timeoutMs);
 }
-// ---------------------------------------------------------------------------
-// Serialised warm-floor maintenance
-// ---------------------------------------------------------------------------
-function resolveWarmFloor(override) {
-    if (typeof override === "number")
-        return override;
-    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 resolveCeiling(override) {
-    if (typeof override === "number")
-        return override;
-    const raw = process.env.VICE_BROKER_MAX;
-    if (raw === undefined || raw === "")
-        return 16;
-    const n = Number(raw);
-    return Number.isFinite(n) ? n : 16;
-}
-/** Promotes launching instances via probe, then -- unless a launch is
- * already in flight -- launches AT MOST ONE instance toward the warm floor
- * and returns. Never loops to reach the floor in one call: reaching
- * VICE_BROKER_WARM_FLOOR this way costs one
- * additional CALL per warm instance instead of one call total, which is the exact
- * trade the 2026-08-01 outage made non-negotiable (three simultaneous
- * x64sc launches: one SEGV, one exit 1, one exit 0 at the identical spawn
- * second). `async`/`await` makes launching everything needed in one go
- * look free and idiomatic; it is actively dangerous here. DO NOT gather
- * several pending launches into a single concurrent await, and do not
- * "helpfully" loop this function internally until the floor is met.
- *
- * D-05's probe-live floor evaluation (count_ready() trusting probe-live
- * instances rather than a recorded `ready` state) is explicitly Phase
- * 01.6.2.1's criterion L, NOT this plan's -- countReady() here still
- * counts by RECORDED state, exactly like the bash original's count_ready()
- * before Decision 5.2. A reviewer must not mistake this for an oversight:
- * it is the declined-for-this-phase choice RESEARCH.md §A1 recommends, and
- * grant_from_spare()'s own live re-probe at GRANT time (broker-kill.mts /
- * plan 04's territory) is a separate, already-correct mechanism this plan
- * does not touch. */
-export async function maintainWarmFloor(deps) {
+/** Promotes every `launching` instance whose readiness probe now succeeds to
+ * `ready`, recording its readiness timestamp and logging the elapsed boot
+ * time. Runs regardless of whether a launch is in flight -- promotion and a
+ * NEW launch starting are independent concerns; an already-launched instance
+ * becomes usable the moment it answers, whether or not this same pass goes on
+ * to start anything further. No retry loop: a still-booting instance simply
+ * fails THIS pass and is re-probed on the next one (runBrokerPass()'s own
+ * per-tick cadence). */
+export async function promoteLaunchingInstances(deps) {
     const log = deps.log ?? defaultLog;
     const now = deps.now ?? (() => Date.now());
     // WR-01: the DEFAULT probe follows this call's own backend, so a caller that
-    // threads `backend` for the launch argv and omits `probe` gets a matching
-    // readiness route rather than an HTTP POST at a binary-monitor port. An
-    // explicitly injected `probe` still wins, unchanged.
-    const probe = deps.probe ?? ((port) => probeReady(port, { backend: deps.backend ?? "fork" }));
-    // Step 1: promote every "launching" instance whose probe now succeeds.
-    // Runs regardless of whether a launch is in flight -- promotion and
-    // speculative warming are independent concerns; an already-launched
-    // instance becomes usable the moment it answers, whether or not this
-    // pass goes on to warm anything further.
+    // threads `backend` and omits `probe` gets a matching readiness route
+    // rather than an HTTP POST at a binary-monitor port. An explicitly
+    // injected `probe` still wins, unchanged.
+    const probe = deps.probe ?? ((port) => probeReady(port, { backend: deps.backend ?? "stock" }));
     for (const record of deps.state.instances.values()) {
         if (record.state !== "launching")
             continue;
@@ -732,65 +897,6 @@ export async function maintainWarmFloor(deps) {
             log(`vice-broker: port ${record.port} launching -> ready (${elapsedMs}ms)`);
         }
     }
-    // Step 2 (P-06: the warm-zero "no readiness mechanism" branch that used
-    // to sit here is GONE -- the surviving probe mechanism is in-process and
-    // always available, so there is no "no mechanism" state left to warm
-    // zero against). No new boot starts while one is already under way --
-    // THE single in-flight counter (countLaunching) both this function and a
-    // cold acquire (vice-broker.mts's handleAcquire) consult.
-    if (deps.countLaunching(deps.state) > 0) {
-        // D-07's launch-slot decision log line, this decision point's own half:
-        // name WHICH reason currently holds the slot (the launching record's
-        // own `reason`, whichever call produced it -- cold acquire or an
-        // earlier warming pass), not merely that warming is waiting.
-        const inFlightRecord = Array.from(deps.state.instances.values()).find((r) => r.state === "launching");
-        const winningReason = inFlightRecord?.reason ?? "unknown";
-        log(`vice-broker: launch-slot decision -- ${winningReason} holds the slot; spare waits (D-07)`);
-        return;
-    }
-    const ready = deps.countReady(deps.state);
-    const total = deps.countTotal(deps.state);
-    const warmFloor = resolveWarmFloor(deps.warmFloor);
-    const ceiling = resolveCeiling(deps.ceiling);
-    if (!(ready < warmFloor && total < ceiling)) {
-        return;
-    }
-    // acquirePortAndLaunch() holds the SAME single in_flight owner across
-    // its own async port allocation -- not merely tryLaunchOne()'s
-    // synchronous spawn instant. This is what actually closes the race
-    // between this warm-floor launch and a cold acquire (vice-broker.mts's
-    // handleAcquire) arriving over the TCP control listener at any moment:
-    // the countLaunching() check just above is a cheap PRE-check (bails
-    // early when a launch is already recorded), but nextFreePort() is
-    // itself asynchronous, so without the guard held across the allocation
-    // too, two overlapping callers could still both be told the same
-    // candidate port is free before either commits it.
-    const result = await acquirePortAndLaunch("spare", {
-        state: deps.state,
-        stateDir: deps.stateDir,
-        allocatePort: deps.allocatePort,
-        allocateRemoteMonitorPort: deps.allocateRemoteMonitorPort,
-        spawn: deps.spawn,
-        spawnFactory: deps.spawnFactory,
-        now: deps.now,
-        viceBin: deps.viceBin,
-        mcpHost: deps.mcpHost,
-        backend: deps.backend,
-        binmonHost: deps.binmonHost,
-    });
-    if (result.ok) {
-        log(`vice-broker: warmed 1 warm instance this pass -- ${ready + 1} of ${warmFloor} ready, remainder warmed on later passes`);
-        deps.onLaunched?.(result.record);
-    }
-    else if (result.reason === "no_free_port") {
-        log(`vice-broker: no free port available -- warming no further warm instances; ${ready} of ${warmFloor} ready`);
-    }
-    else {
-        // A launch started (cold or warm) between this function's own
-        // countLaunching() check above and this call -- a narrow window
-        // closed by the guard rather than assumed impossible.
-        log("vice-broker: a warm-floor launch was attempted but a launch was already in flight -- deferring to a later pass");
-    }
 }
 /** The fixed pass order (mirrors vice-broker.sh's own broker_once(), whose
  * comment names the ordering as load-bearing: "the spare invariant is
@@ -804,21 +910,26 @@ export async function maintainWarmFloor(deps) {
  * instrumented no-op functions and assert call ORDER without needing a
  * real broker, a real port or a real launch.
  *
- * D-07 (01.6.2.1-03-PLAN.md): THIS is where launch priority actually lives
- * -- serving acquires before maintaining the warm floor is what lets a
- * request-driven launch win a freed slot before a warming launch, within
- * one pass, on top of the single in-flight owner (acquirePortAndLaunch()'s
- * own invariant comment) that this order never weakens. Inverting this
- * order lets a warming launch take the slot first and go untested against
- * a concurrently arriving acquire, which is exactly the regression
- * broker-launch.test.ts's own D-07 priority test is written to catch (its
- * own discriminating-power demonstration inverts this exact order and
- * observes the test go red). Priority decides only which reason wins the
- * NEXT freed slot -- it is never a substitute for the lock, and it never
- * kills or abandons whichever boot is already in flight. */
+ * Plan 41-05 (folded todo): the warm floor that D-07 (01.6.2.1-03-PLAN.md)
+ * originally reasoned about here is GONE -- `promoteLaunching` never calls
+ * acquirePortAndLaunch() and so never competes for the single in-flight
+ * launch slot the way a warm-floor spare launch used to. `serveAcquires()`
+ * (via its own drainPendingAcquires()) is now the ONLY caller in this pass
+ * that ever launches anything, so D-07's original "which reason wins a
+ * freed slot" question has nothing left to decide BETWEEN these two steps --
+ * that reasoning still applies WITHIN the acquire arm itself (two overlapping
+ * acquires still resolve through the single in-flight owner
+ * (acquirePortAndLaunch()'s own invariant comment), which this reordering
+ * never weakens). What the fixed order still buys: promoting AFTER serving
+ * means an instance that becomes probe-ready DURING this exact tick is not
+ * available to any acquire THIS SAME pass -- selectWarmInstance() sees it on
+ * the NEXT pass instead, a bound of one poll interval (VICE_BROKER_POLL_MS),
+ * never a correctness gap, since a cold acquire finding no ready candidate
+ * falls straight through to its own dedicated cold launch rather than
+ * waiting on one. */
 export async function runBrokerPass(deps) {
     await deps.serveAcquires();
-    await deps.maintainWarmFloor();
+    await deps.promoteLaunching();
 }
 // ===========================================================================
 // Per-child supervision (Plan 03, Task 2 -- C2/D-23): absorbs
@@ -857,9 +968,11 @@ function resolveCount(envVar, defaultValue, override) {
  *   UNEXPLAINED exit, not this one. The pre-kill crash history and backoff
  *   are carried forward UNCHANGED, and a pre-kill "granted" state is
  *   restored on the fresh record -- the relaunch primitive always creates a
- *   new record in the "launching" state, and leaving it there would let the
- *   warm floor's own ready-count numerator mistake a recycled session's own
- *   machine for an available warm instance.
+ *   new record in the "launching" state, and leaving it there (once
+ *   promoted to "ready" by the next probe pass) would let a LATER,
+ *   UNRELATED acquire's own selectWarmInstance() walk (vice-broker.mts)
+ *   mistake a recycled session's own machine for an available candidate to
+ *   grant out from under the session that already owns it.
  * - deliberateKill set WITHOUT respawnAfterKill -> "deliberate_teardown":
  *   drop the instance, no respawn. This is T-01.6.2-21's whole point --
  *   without reading this flag, every deliberate teardown would respawn
@@ -883,22 +996,25 @@ async function handleExit(reason, port, deps) {
         return;
     }
     const log = deps.log ?? defaultLog;
-    // Plan 05 (BROK-02/PROTO-08): the process behind this instance's monitor
-    // socket has just exited, by every path this function can take (crash,
-    // recycle, or a deliberate teardown) -- clear the ownership record HERE,
+    // Plan 05 (BROK-02/PROTO-08), promoted to a per-channel map by plan 41-03
+    // (D-14): the process behind this instance's monitor sockets has just
+    // exited, by every path this function can take (crash, recycle, or a
+    // deliberate teardown) -- clear EVERY channel's ownership record HERE,
     // once, before any of those paths branch, so a client that died without
-    // releasing can never hold this lock forever. Redundant with the
-    // respawn/delete paths below (a fresh InstanceRecord never carries this
-    // field forward; a deleted one has no field to carry), but explicit for
-    // the same reason broker-state.mts's own header comment names this as one
-    // of the three required clearing sites. Assigned directly (not via
-    // broker-state.mjs's clearMonitorClient()) -- this module's own
+    // releasing can never hold this lock forever on any channel. Redundant
+    // with the respawn/delete paths below (a fresh InstanceRecord never
+    // carries this forward; a deleted one has no field to carry), but
+    // explicit for the same reason broker-state.mts's own header comment
+    // names this as one of the required clearing sites. Assigned directly
+    // (not via broker-state.mjs's clearMonitorClient()) -- this module's own
     // type-only import of that sibling (see this file's own header comment a
     // few lines above) is load-bearing: a VALUE import would turn "./broker-
     // state.mjs" into a real runtime resolution this file cannot satisfy when
     // loaded directly (as broker-launch.test.ts does), rather than the
-    // compiled resources/ sibling this specifier is actually shaped for.
-    record.monitorClient = undefined;
+    // compiled resources/ sibling this specifier is actually shaped for. `{}`
+    // (not `undefined`) since `monitorClients` is non-optional -- "no claim
+    // on any channel" is an empty map.
+    record.monitorClients = {};
     if (record.deliberateKill) {
         if (record.respawnAfterKill) {
             // Recycle. Capture the pre-kill state, crash history and backoff
@@ -914,7 +1030,18 @@ async function handleExit(reason, port, deps) {
             // with a brand new record, for the same reason the three values above
             // are.
             const preKillRemoteMonitorPort = record.remoteMonitorPort;
-            const respawned = launchSupervised(reason, port, deps, preKillCrashTimes, preKillBackoffMs, preKillRemoteMonitorPort);
+            // Phase 33, plan 33-06 (D-16, T-33-24): the launch PROFILE is carried
+            // forward for exactly the reason CR-02 carries the remote-monitor port
+            // forward, and the failure it prevents is sharper. Without this, a
+            // recycled `{warp:true}` instance would come back UNWARPED while its
+            // fresh record still claimed `profile:{warp:true}` -- after which
+            // profileEligible() (vice-broker.mts) would happily hand that instance
+            // to the next warp request. That is precisely the undetectable lie
+            // D-16 exists to structurally exclude, reintroduced one respawn later.
+            // Captured BEFORE launchSupervised() overwrites this port's map entry
+            // with a brand new record, same as the four values above.
+            const preKillProfile = record.profile;
+            const respawned = launchSupervised(reason, port, deps, preKillCrashTimes, preKillBackoffMs, preKillRemoteMonitorPort, preKillProfile);
             if (respawned && preKillState === "granted") {
                 respawned.state = "granted";
             }
@@ -963,7 +1090,10 @@ async function handleExit(reason, port, deps) {
     // silently strip `-remotemonitor` (and its InstanceRecord field) off the
     // replacement, which is what made D-13's "the instance record carries it"
     // stop being true the first time an instance was replaced.
-    const respawned = launchSupervised(reason, port, deps, crashTimes, nextBackoffMs, record.remoteMonitorPort);
+    // Phase 33, plan 33-06: same carry-forward as the recycle branch above --
+    // an unexplained crash must not silently strip `-warp`/`-console` off the
+    // replacement while leaving the record claiming them (D-16, T-33-24).
+    const respawned = launchSupervised(reason, port, deps, crashTimes, nextBackoffMs, record.remoteMonitorPort, record.profile);
     deps.onOutcome?.(respawned ? "respawned" : "given_up", port);
 }
 /** The single exit-listener installation point in the whole module tree.
@@ -990,8 +1120,9 @@ async function handleExit(reason, port, deps) {
 export function withCrashSupervision(reason, port, baseSpawn, deps) {
     // I-1 rider (08.2-06-PLAN.md, Task 1): forwards a third options argument
     // in the BODY, not just the type -- this is the hop that matters most,
-    // because it wraps every real launch path (cold acquire, warm floor, and
-    // every respawn). A type-only widening would still silently drop a
+    // because it wraps every real launch path (cold acquire and every
+    // respawn -- plan 41-05 retires the warm floor, the third path this
+    // comment used to name). A type-only widening would still silently drop a
     // caller's options at this call site.
     return (cmd, args, options) => {
         const child = baseSpawn(cmd, args, options);
@@ -1024,8 +1155,20 @@ export function withCrashSupervision(reason, port, baseSpawn, deps) {
  * meanwhile), exactly as it reuses the primary `port` argument; this function
  * stays fully synchronous and never allocates. `undefined` is the correct
  * value for a FIRST launch through superviseChild() and for every fork launch,
- * which is why the parameter is optional. */
-function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonitorPort) {
+ * which is why the parameter is optional.
+ *
+ * Phase 33, plan 33-06 (D-16): `profile` is threaded the SAME way and for a
+ * sharper version of the same reason -- it belongs to the instance, not to a
+ * single spawn of it, and warp is fixed at spawn (there is no runtime
+ * `WarpMode` resource on stock at all). A replacement that dropped it would
+ * come back unwarped while its record still claimed warp, which is exactly the
+ * mismatch-between-grant-and-request that D-16's eligibility rule exists to
+ * make impossible. `undefined` is correct for a FIRST launch through
+ * superviseChild() -- production has no profile-less first-launch call site
+ * of its own left after plan 41-05 retires the warm floor, but this
+ * module's own unit tests still drive one directly -- and for every fork
+ * launch, which is why this parameter is optional too. */
+function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonitorPort, profile) {
     const supervisorDir = join(deps.stateDir, String(port));
     const epochFile = deps.epoch.epochPathFor(deps.stateDir, port);
     const logDir = deps.epoch.instanceLogDirFor(deps.stateDir, port);
@@ -1067,6 +1210,7 @@ function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonit
         backend: deps.backend,
         binmonHost: deps.binmonHost,
         remoteMonitorPort,
+        profile,
         log: deps.log,
     });
     if (!record)
@@ -1103,8 +1247,19 @@ function launchSupervised(reason, port, deps, crashTimes, backoffMs, remoteMonit
  * (crash respawn with backoff, crash-loop give-up, kill-never-recycle via
  * the deliberate-kill marker, and the per-instance boot/crash log), exactly
  * mirroring resources/vice-supervisor.sh's own respawn loop but expressed
- * as an event-loop exit handler instead of a `while true` poll. */
-export function superviseChild(reason, port, deps) {
+ * as an event-loop exit handler instead of a `while true` poll.
+ *
+ * Plan 41-05 (D-16): `remoteMonitorPort` is an OPTIONAL fourth parameter,
+ * threaded straight through to launchSupervised() exactly like every other
+ * optional trailing parameter in this file. A
+ * `backend: "stock"` caller MUST supply it: spawnAndRecordInstance()'s own
+ * construction-site assertion (D-16) throws otherwise, since this function
+ * is a genuine first-launch call site, not merely a respawn. This is not a
+ * production stock first-launch path today (only acquirePortAndLaunch() is)
+ * -- it exists for this module's own unit tests to drive a supervised first
+ * launch directly, and the parameter exists so a stock test case can do so
+ * without violating the same guarantee production code enforces. */
+export function superviseChild(reason, port, deps, remoteMonitorPort) {
     const initialBackoffMs = resolveMs("VICE_RESTART_BACKOFF_S", 3, deps.initialBackoffMs);
-    return launchSupervised(reason, port, deps, [], initialBackoffMs);
+    return launchSupervised(reason, port, deps, [], initialBackoffMs, remoteMonitorPort);
 }