@henols/vice-mcp 0.2.2 → 0.2.4

package/resources/broker-control.mjs

@@ -2,34 +2,31 @@
 // Compiled by `tsc` from broker-control.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-control.mts
 //
-// N / D-01 (plan 01, tracer): the framing, the token gate, and acquire/
-// release. Plan 05 (task 1) completed the message set: recycle, status,
+// The framing, the token gate, acquire/release, recycle, status,
 // host_state, the arrival-ordered pending-acquire structure, and the
-// kernel-enforced singleton guard's low-level bind primitive. THIS PLAN's
-// task 2 adds a SEVENTH and EIGHTH op, `monitor_claim`/`monitor_release`
-// (BROK-02/PROTO-08, D-13): exclusive ownership of an instance's raw binmon
-// socket, enforced here rather than left to a client-side heuristic --
-// stock VICE services exactly one binmon client, and a second connect()
-// produces no reply and no EOF, so the refusal must happen BEFORE any
-// second dial is ever attempted. The subsystem's FIRST network listener: a
-// TCP control plane replacing the bash broker's requests/grants/denials/
-// leases directory tree entirely. One JSON object per line; the connection
-// open IS the claim, connection close IS the release (T-01.6.2-01 through
-// -09).
+// kernel-enforced singleton guard's low-level bind primitive. Also adds
+// `monitor_claim`/`monitor_release`: exclusive ownership of an instance's
+// raw binmon socket, enforced here rather than left to a client-side
+// heuristic -- stock VICE services exactly one binmon client, and a second
+// connect() produces no reply and no EOF, so the refusal must happen
+// BEFORE any second dial is ever attempted. The subsystem's FIRST network
+// listener: a TCP control plane replacing the bash broker's
+// requests/grants/denials/leases directory tree entirely. One JSON object
+// per line; the connection open IS the claim, connection close IS the
+// release (T-01.6.2-01 through -09).
 //
-// Wire format confirmed at plan 01's blocking checkpoint:decision
-// (2026-08-03, `as-specified`, no amendments -- see .planning/RE-FINDINGS.md
-// for the full record, including the two accepted residual risks and the
-// unix-domain-socket dead end). Auth: per-boot capability token compared
-// constant-time, checked BEFORE any state read or write. Bind: 0.0.0.0
-// explicitly, never 127.0.0.1 -- host.docker.internal is the bridge
-// address, not loopback, so a loopback-only listener is structurally
-// unreachable from the container. Port: 19510 default via
-// VICE_BROKER_CONTROL_PORT.
+// Wire format confirmed at a blocking checkpoint decision (2026-08-03,
+// `as-specified`, no amendments), which accepted some residual risk and
+// considered and rejected a unix-domain-socket alternative. Auth: per-boot
+// capability token compared constant-time, checked BEFORE any state read
+// or write. Bind: 0.0.0.0 explicitly, never 127.0.0.1 --
+// host.docker.internal is the bridge address, not loopback, so a
+// loopback-only listener is structurally unreachable from the container.
+// Port: 19510 default via VICE_BROKER_CONTROL_PORT.
 import { createServer } from "node:net";
 import { timingSafeEqual, randomBytes } from "node:crypto";
 /** 32 cryptographically random bytes rendered as hex -- the per-boot
@@ -40,14 +37,98 @@ export function newControlToken() {
     return randomBytes(32).toString("hex");
 }
 const MAX_LINE_BYTES = 65536;
-/** CR-03: the one refusal wording for a target-naming op whose `target_id` is
+/** The one refusal wording for a target-naming op whose `target_id` is
  * not the grant the asking connection itself holds. Deliberately worded as an
  * authorisation refusal and NOT as an ownership conflict between two
  * legitimate holders (`monitor_owned`, which names a holder) and never as an
  * emulator fault -- see attachControlProtocol()'s own ownsTarget() comment,
- * and T-02-18's prohibition on wedge/hang vocabulary in this file's
+ * and this file's own prohibition on wedge/hang vocabulary in its
  * monitor-op refusals. */
 const MONITOR_OWNERSHIP_DENIAL = "monitor_claim/monitor_release may only target the grant this connection itself holds";
+/** Resolves the `channel` field on a `monitor_claim`/`monitor_release`
+ * request line: an ABSENT field means `binary` deliberately -- a broker
+ * restarted mid-upgrade against a client that predates this field keeps
+ * working (backward compatibility). An unrecognised NON-EMPTY value is
+ * `bad_request`, never a silent fallback and never cast -- the caller
+ * below names both accepted values in the refusal message. */
+function resolveMonitorChannel(raw) {
+    if (raw === undefined)
+        return "binary";
+    if (raw === "binary" || raw === "text")
+        return raw;
+    return "bad_request";
+}
+// ---------------------------------------------------------------------------
+// The launch-profile narrowing site.
+//
+// THIS IS THE ONE PLACE `profile` IS NARROWED. Do not re-derive this check
+// anywhere else -- not in vice-broker.mts, not in broker-launch.mts, not in
+// the container-side client. A second copy is how one of them ends up
+// accepting a shape the other refuses.
+//
+// WHY IT HAS TO EXIST AT ALL: `ControlRequest` above carries an index
+// signature, so *anything* a container writes on the wire parses into it. The
+// profile then feeds buildViceArgs(), i.e. an `execve(x64sc, argv)` on the
+// HOST. An unvalidated `profile` is therefore an argv-construction surface
+// across a trust boundary, not merely a typing inconvenience.
+//
+// WHY UNKNOWN KEYS ARE REFUSED BY NAME rather than dropped: a silently
+// accepted typo means a caller asked for warp, got an unwarped instance, and
+// received a confident success -- the same undetectable-lie failure a
+// mismatched grant-and-request eligibility check exists to prevent one
+// layer down, and it is why the message below names the offending key --
+// the by-name unexpected-argument discipline the tool handlers already use
+// (RUN_UNTIL_KEYS' own convention).
+//
+// WHAT MUST NEVER BE ADDED HERE: a passthrough string, an `extraArgs`, or any
+// key whose VALUE reaches argv. `profile` maps to exactly two literal flag
+// tokens (`-console`, `-warp`) and to nothing else (T-33-04). `VICE_ARGS`
+// stays the single, deliberate operator-only whole-argv override.
+// ---------------------------------------------------------------------------
+/** The complete accepted key set -- the ONE binding list this narrowing
+ * checks against, so adding a knob to LaunchProfile without adding it here
+ * refuses the knob rather than silently widening the boundary. */
+const LAUNCH_PROFILE_KEYS = Object.freeze(["warp", "headless"]);
+const LAUNCH_PROFILE_SHAPE = `an object with optional boolean keys ${LAUNCH_PROFILE_KEYS.join("/")}, or absent`;
+/** Narrows an untrusted `profile` field off the wire. Never throws; answers a
+ * discriminated result so the caller writes the existing `bad_request` error
+ * shape rather than needing a try/catch at the protocol boundary.
+ *
+ * Rules, in the order they are applied:
+ * - `undefined` (key absent) and `null` -> `ok` with `undefined`. Both mean
+ *   profile-less, which is byte-identically today's behaviour.
+ * - a PLAIN object (arrays and every other non-plain value refused) whose
+ *   keys are a subset of LAUNCH_PROFILE_KEYS and whose PRESENT values are
+ *   booleans -> `ok` with that object.
+ * - anything else -> `ok: false`, with a message naming the offending value
+ *   (or key) and the accepted shape. Never coerced, never silently dropped:
+ *   `"yes"`, `1` and `"warp"` are refusals, not truthy warp requests. */
+export function normaliseLaunchProfile(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, profile: undefined };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        // Arrays are specifically excluded: `typeof [] === "object"` in JS, so
+        // without the Array.isArray() arm a JSON array would reach the key walk
+        // below and pass it vacuously (an empty array has no own keys).
+        return { ok: false, message: `profile must be ${LAUNCH_PROFILE_SHAPE}; got ${JSON.stringify(raw) ?? String(raw)}` };
+    }
+    const entries = Object.entries(raw);
+    const unknownKeys = entries.filter(([key]) => !LAUNCH_PROFILE_KEYS.includes(key)).map(([key]) => key);
+    if (unknownKeys.length > 0) {
+        return { ok: false, message: `profile has unknown key(s) ${unknownKeys.join(", ")}; accepted shape is ${LAUNCH_PROFILE_SHAPE}` };
+    }
+    const profile = {};
+    for (const [key, value] of entries) {
+        if (typeof value !== "boolean") {
+            return { ok: false, message: `profile.${key} must be a boolean; got ${JSON.stringify(value) ?? String(value)}` };
+        }
+        if (key === "warp")
+            profile.warp = value;
+        if (key === "headless")
+            profile.headless = value;
+    }
+    return { ok: true, profile };
+}
 export function resolveControlPort(override) {
     if (typeof override === "number")
         return override;
@@ -74,6 +155,20 @@ function writeLine(socket, obj) {
         socket.write(`${JSON.stringify(obj)}\n`);
     }
 }
+/** Writes a `host_tool` SUCCESS response line -- the object host-tool.mts's
+ * runHostTool() produced, whatever shape that is (`{ ok: true, ... }` or
+ * its own `{ ok: false, message }` refusal). This is deliberately NOT
+ * `writeLine()`/`ControlResponse`: the host-tool response shape is
+ * host-tool.mts's own contract, not one more `ControlResponse` variant this
+ * module would otherwise have to keep in sync with a sibling module's
+ * allowlist. A REJECTED onHostTool() promise never reaches this function --
+ * it is answered through the ordinary `writeLine()`/`error` path instead,
+ * so every protocol-level failure still goes through one shape. */
+function writeHostToolLine(socket, obj) {
+    if (socket.writable) {
+        socket.write(`${JSON.stringify(obj)}\n`);
+    }
+}
 function defaultRequestId(prefix) {
     return `${prefix}-${process.pid}-${Date.now()}`;
 }
@@ -93,9 +188,10 @@ export function enqueueAcquire(queue, entry) {
  * to stay correct; a genuinely adversarial retry pattern could still starve
  * an entry across MULTIPLE passes, which is exactly the direct fairness
  * proof this module deliberately does not author -- injecting N acquires
- * and asserting grants return in that order is Phase 01.6.2.1's D-08
- * deliverable. The original defect this queue replaces (a lexical iteration
- * over `req-<pid>-<ms>-<hex>` filenames) cannot exist here regardless: there
+ * and asserting grants return in that order is left as a property for a
+ * future test to prove, not this module's own deliverable. The original
+ * defect this queue replaces (a lexical iteration over
+ * `req-<pid>-<ms>-<hex>` filenames) cannot exist here regardless: there
  * is no file, and no re-ordering call of any kind anywhere in this region. */
 export async function drainPendingAcquires(queue) {
     const snapshot = queue.splice(0, queue.length);
@@ -162,9 +258,9 @@ function attachControlProtocol(server, opts, pendingAcquires) {
             // every other connection and from the server itself (T-01.6.2-06).
         });
         /**
-         * CR-03 (code review 2026-08-13). THE per-connection ownership predicate
-         * every target-naming op is gated on -- the same rule `recycle` has
-         * enforced since T-01.6.2-31, now shared rather than copied.
+         * THE per-connection ownership predicate every target-naming op is
+         * gated on -- the same rule `recycle` has enforced since this
+         * protocol's earliest version, now shared rather than copied.
          *
          * Before this existed, `monitor_claim`/`monitor_release` took `target_id`
          * from the request and passed it straight through, so any connection
@@ -176,8 +272,8 @@ function attachControlProtocol(server, opts, pendingAcquires) {
          * session B could lock session A out of its own monitor socket, or
          * RELEASE A's live claim, after which a third client was free to dial the
          * same single-client binmon socket. That is precisely the unserviced-
-         * backlog state D-13 exists to prevent and that CLAUDE.md says must never
-         * be reachable.
+         * backlog state this ownership check exists to prevent and that
+         * CLAUDE.md says must never be reachable.
          *
          * WHAT NOT TO DO: never add another op that acts on a caller-supplied
          * `target_id` without gating it here first. The grant a connection holds
@@ -194,10 +290,9 @@ function attachControlProtocol(server, opts, pendingAcquires) {
          * `drainPendingAcquires()` drives, so the two paths can never answer
          * differently for the same requestId.
          *
-         * Gap closure (plan 14, WR-03/T-01.6.2-87/-88): two destroyed-socket
-         * checks guard a grant against outliving the connection that owns it,
-         * and they bound TWO DIFFERENT failures -- do not conflate them into one
-         * claim.
+         * Two destroyed-socket checks guard a grant against outliving the
+         * connection that owns it, and they bound TWO DIFFERENT failures -- do
+         * not conflate them into one claim.
          *
          * Half one -- the pre-check immediately below, BEFORE onAcquire() is
          * ever called -- closes the ALWAYS-REACHABLE leak: a client that
@@ -217,7 +312,7 @@ function attachControlProtocol(server, opts, pendingAcquires) {
          * callback with the same request id instead of silently dropping the
          * grant it produced.
          */
-        function attemptAcquire(requestId) {
+        function attemptAcquire(requestId, profile) {
             // Half one: a queued entry whose owning socket is already gone is
             // settled immediately, WITHOUT ever calling onAcquire() -- this is
             // what keeps a retried drain pass from performing a real, ownerless
@@ -225,7 +320,12 @@ function attachControlProtocol(server, opts, pendingAcquires) {
             if (socket.destroyed)
                 return Promise.resolve(true);
             return opts
-                .onAcquire(requestId)
+                // The profile is threaded through THIS shared helper, which both
+                // the immediate first attempt and every later
+                // drainPendingAcquires() retry go through -- so a request that
+                // queued behind an in-flight launch is retried later with the
+                // profile it was MADE with, never with a profile-less one.
+                .onAcquire(requestId, profile)
                 .then((outcome) => {
                 if (outcome.ok) {
                     // Half two: the pre-check above ran before this call; a
@@ -245,6 +345,14 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                         url: outcome.grant.url,
                         epoch_file: outcome.grant.epochFile,
                         supervisor_dir: outcome.grant.supervisorDir,
+                        // Key omitted entirely when absent -- the fork case only now.
+                        // A stock grant whose second (text-monitor) port allocation
+                        // failed never reaches this line at all:
+                        // acquirePortAndLaunch() fails the WHOLE acquire
+                        // (`no_free_text_port`) before any grant is produced, so
+                        // "absent" no longer needs to cover that case. Never a
+                        // fabricated 0 or null standing in for "no port".
+                        ...(outcome.grant.remoteMonitorPort === undefined ? {} : { remote_monitor_port: outcome.grant.remoteMonitorPort }),
                     });
                     return true;
                 }
@@ -289,11 +397,51 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                 socket.destroy();
                 return;
             }
-            if (req.op === "acquire") {
+            // Dispatched FIRST in the chain, before "acquire" -- so the ordering
+            // reads clearly. Dispatch here is on EXACT STRING EQUALITY, never
+            // fallthrough, so branch order does not itself change which requests
+            // reach attemptAcquire() -- what actually makes this branch unable to
+            // touch lease state is that opts.onHostTool is its OWN callback (see
+            // StartControlListenerOptions' own comment), never composed from
+            // onAcquire/onRelease/onRecycle/onStatus/onHostState/onMonitorClaim/
+            // onMonitorRelease.
+            if (req.op === "host_tool") {
+                opts
+                    .onHostTool(req)
+                    .then((result) => {
+                    if (!socket.destroyed)
+                        writeHostToolLine(socket, result);
+                })
+                    .catch(() => {
+                    if (!socket.destroyed) {
+                        writeLine(socket, { kind: "error", code: "internal", message: "host_tool threw" });
+                    }
+                });
+            }
+            else if (req.op === "acquire") {
                 const requestId = typeof req.id === "string" && req.id !== "" ? req.id : defaultRequestId("req");
-                void attemptAcquire(requestId).then((settled) => {
+                // Narrow BEFORE attemptAcquire, so a malformed profile never
+                // reaches onAcquire and therefore never reaches the port allocator,
+                // a spawn, or argv construction. A refusal also does NOT enqueue --
+                // the request is answered and dropped, never retried on a later
+                // drain pass with the same bad shape.
+                const normalised = normaliseLaunchProfile(req.profile);
+                if (!normalised.ok) {
+                    writeLine(socket, { kind: "error", code: "bad_request", message: normalised.message });
+                    return;
+                }
+                const profile = normalised.profile;
+                // A profile-is-stock-only refusal used to live here: it refused
+                // `profile.warp`/`profile.headless` when this broker's resolved
+                // backend had no `-warp`/`-console` route at all, so a caller
+                // learned a knob would be silently ignored rather than getting a
+                // confident grant with no effect. Now that the fork backend is
+                // gone, there is one backend and it always has that route, so the
+                // condition this refused can no longer occur -- deleted rather than
+                // left as a check against a value that can never disagree.
+                void attemptAcquire(requestId, profile).then((settled) => {
                     if (!settled) {
-                        enqueueAcquire(pendingAcquires, { requestId, attempt: () => attemptAcquire(requestId) });
+                        enqueueAcquire(pendingAcquires, { requestId, attempt: () => attemptAcquire(requestId, profile) });
                     }
                 });
             }
@@ -313,7 +461,7 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                 // called, so a mismatched target never reaches the kill discipline
                 // and never signals anything -- an injected signal recorder stays
                 // empty for this case. Now expressed through the SAME ownsTarget()
-                // predicate monitor_claim/monitor_release use (CR-03), so the three
+                // predicate monitor_claim/monitor_release use, so the three
                 // target-naming ops cannot drift apart.
                 if (!ownsTarget(targetId)) {
                     writeLine(socket, {
@@ -354,7 +502,6 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                     started_at: hs.startedAt,
                     node_version: hs.nodeVersion,
                     vice_bin: hs.viceBin,
-                    warm_floor: hs.warmFloor,
                     max_instances: hs.maxInstances,
                     base_port: hs.basePort,
                     backend: hs.backend,
@@ -370,29 +517,39 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                     writeLine(socket, { kind: "error", code: "denied", message: MONITOR_OWNERSHIP_DENIAL });
                     return;
                 }
+                const channel = resolveMonitorChannel(req.channel);
+                if (channel === "bad_request") {
+                    writeLine(socket, {
+                        kind: "error",
+                        code: "bad_request",
+                        message: `monitor_claim: unrecognised channel ${JSON.stringify(req.channel)} -- accepted values are "binary" and "text"`,
+                    });
+                    return;
+                }
                 const requestId = typeof req.id === "string" && req.id !== "" ? req.id : defaultRequestId("claim");
-                const outcome = opts.onMonitorClaim(requestId, targetId);
+                const outcome = opts.onMonitorClaim(requestId, targetId, channel);
                 if (outcome.ok) {
                     writeLine(socket, { kind: "monitor_claimed" });
                 }
                 else if (outcome.code === "monitor_owned") {
-                    // Ownership conflict, named by holder -- deliberately worded to
-                    // never suggest the emulator itself has stopped answering
-                    // (T-02-18; the plan's own grep gate polices this).
+                    // Ownership conflict, named by holder AND channel -- deliberately
+                    // worded to never suggest the emulator itself has stopped
+                    // answering.
                     //
-                    // WR-08 (broker side): `holder` is REQUIRED by MonitorClaimOutcome for
+                    // `holder` is REQUIRED by MonitorClaimOutcome for
                     // this code, but this handler runs inside socket.on("data") with no
                     // try/catch above it, so a producer that ever omitted it would throw a
                     // TypeError out of the control listener and take the broker process
                     // with it -- a type contract is not a runtime guarantee at a wire
                     // boundary. The fallback names the holder as unknown rather than
-                    // fabricating one, matching what the container-side client now does
-                    // with a malformed holder payload.
-                    const holder = outcome.holder ?? { grantId: "unknown", claimedAt: 0, pid: null };
+                    // fabricating one (matching what the container-side client now does
+                    // with a malformed holder payload), and defaults `channel` to the
+                    // channel THIS request asked for -- never a fabricated third value.
+                    const holder = outcome.holder ?? { grantId: "unknown", claimedAt: 0, pid: null, channel };
                     writeLine(socket, {
                         kind: "error",
                         code: "monitor_owned",
-                        message: `instance already has a monitor client (grant ${holder.grantId}, claimed at ${holder.claimedAt}) -- this is an ownership conflict, not an emulator failure`,
+                        message: `instance already has a monitor client on the ${holder.channel} channel (grant ${holder.grantId}, claimed at ${holder.claimedAt}) -- this is an ownership conflict, not an emulator failure`,
                         holder,
                     });
                 }
@@ -410,8 +567,17 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                     writeLine(socket, { kind: "error", code: "denied", message: MONITOR_OWNERSHIP_DENIAL });
                     return;
                 }
+                const channel = resolveMonitorChannel(req.channel);
+                if (channel === "bad_request") {
+                    writeLine(socket, {
+                        kind: "error",
+                        code: "bad_request",
+                        message: `monitor_release: unrecognised channel ${JSON.stringify(req.channel)} -- accepted values are "binary" and "text"`,
+                    });
+                    return;
+                }
                 const requestId = typeof req.id === "string" && req.id !== "" ? req.id : defaultRequestId("release-monitor");
-                const outcome = opts.onMonitorRelease(requestId, targetId);
+                const outcome = opts.onMonitorRelease(requestId, targetId, channel);
                 if (outcome.ok) {
                     writeLine(socket, { kind: "monitor_released" });
                 }

package/resources/broker-epoch.mjs

@@ -2,17 +2,16 @@
 // Compiled by `tsc` from broker-epoch.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-epoch.mts
 //
-// B / D-04: the per-instance epoch.json writer, held to the frozen
-// eight-field contract captured in fixtures/ (task 1, before the bash
-// writer that produced them is deleted later in this phase). Ports
-// write_epoch()'s exact field shape and its atomic tmp-sibling-then-rename
-// discipline -- the tmp file is created empty, mode tightened to
-// owner-read-write BEFORE any content reaches it, content written, then
-// renamed -- matching writeBrokerRecord()'s own choke point in
+// The per-instance epoch.json writer, held to the frozen eight-field
+// contract captured in fixtures/ before the bash writer that produced them
+// was deleted. Ports write_epoch()'s exact field shape and its atomic
+// tmp-sibling-then-rename discipline -- the tmp file is created empty, mode
+// tightened to owner-read-write BEFORE any content reaches it, content
+// written, then renamed -- matching writeBrokerRecord()'s own choke point in
 // vice-broker.mts exactly.
 //
 // Plan 03, Task 1 completes this module: the path derivations

package/resources/broker-kill.mjs

@@ -2,11 +2,11 @@
 // Compiled by `tsc` from broker-kill.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-kill.mts
 //
-// D (complete, this plan -- 01.6.2-04): the identity-verified kill discipline,
+// The identity-verified kill discipline,
 // ported from resources/vice-broker.sh's signal_recorded_pid()/
 // signal_vice_child_pid(): zero-signal liveness check, identity check against
 // the process's own argument string, SIGTERM, poll-then-SIGKILL. The
@@ -30,13 +30,13 @@
 //     unconditionally (kill-never-recycle). The uncatchable signals (SIGKILL,
 //     SIGSTOP) are deliberately unhandled -- see registerShutdownHandlers()'s
 //     own comment.
-//   - reapOrphanedInstances(): the unconditional startup reap (criterion I,
-//     D-15) that reaches instances this broker process has no in-memory
+//   - reapOrphanedInstances(): the unconditional startup reap that reaches
+//     instances this broker process has no in-memory
 //     record of, derived from the emulator port band plus this broker's OWN
 //     on-disk allocation record (epoch.json) -- never a host process
-//     listing or a scan of another process's argv (02-03-PLAN.md/D-14/D-15;
+//     listing or a scan of another process's argv --
 //     see reapOrphanedInstances()'s own header comment for the incident
-//     this revision closes).
+//     this revision closes.
 import { execFileSync } from "node:child_process";
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -80,7 +80,7 @@ function defaultLog(line) {
  * signal_vice_child_pid() do. An empty/null/non-positive pid, or a pid
  * already gone, returns "already_exited" without ever signalling -- "the
  * machine being gone is the goal", per the bash version's own comment. An
- * EMPTY expectedIdentity is REFUSED outright (CR-04 -- see the guard's own
+ * EMPTY expectedIdentity is REFUSED outright (see the guard's own
  * comment below), as is a live pid whose OWN argument string does not contain
  * expectedIdentity: both return "identity_refused" without ever signalling,
  * the one outcome a caller must be able to tell apart from every other stage
@@ -99,7 +99,7 @@ export async function verifiedKill({ pid, expectedIdentity, deps = {} }) {
     if (!isAlive(pid)) {
         return "already_exited";
     }
-    // CR-04 (code review 2026-08-13): an EMPTY expectedIdentity REFUSES, it
+    // An EMPTY expectedIdentity REFUSES, it
     // never permits. `"".includes` is vacuously satisfied by every process's
     // argv, so the guard below was unconditionally true for the empty string --
     // which disabled it entirely and let the caller SIGTERM (then SIGKILL)
@@ -294,18 +294,19 @@ export function registerShutdownHandlers(deps) {
         }
     };
 }
-/** D-25's mandatory start-time banner: printed unconditionally, before the
+/** The mandatory start-time banner: printed unconditionally, before the
  * control listener begins accepting, naming exactly what a keyboard
  * interrupt or a closed terminal destroys. On 2026-08-02 a `^C` produced
  * "reap saw 4 recorded instance(s), terminated 4" and killed a live
  * session -- the incident was not caused by missing machinery, it was
  * caused by nobody being told. Detaching stays the operator's own
- * nohup/setsid/systemd choice (D-25) -- this banner names that choice
+ * nohup/setsid/systemd choice -- this banner names that choice
  * rather than offering a flag; the launcher stays thin.
  *
- * D-25/P-13 (01.6.2.1-05-PLAN.md): the one place naming the retired
- * warm-floor environment variable does not weaken D-10/D-11's clean break --
- * the line added below reports the variable's mere PRESENCE, never its
+ * The one place naming the retired
+ * warm-floor environment variable does not weaken the clean break made when
+ * the warm floor was retired -- the line added below reports the variable's
+ * mere PRESENCE, never its
  * value, and no reader anywhere in this broker still consults it (the
  * structural gate in broker-kill.test.ts proves that). Without it, an
  * operator with the retired variable set in a shell profile would silently
@@ -324,27 +325,30 @@ export function startupBanner() {
         "vice-broker: to run this broker outside the current terminal session, use your own",
         "vice-broker: nohup/setsid/systemd -- this launcher does not offer a --detach flag.",
     ];
-    if (process.env.VICE_BROKER_SPARES !== undefined) { // banner-only presence check (D-25/P-13) -- never reads the value
-        lines.push("vice-broker: NOTE -- the VICE_BROKER_SPARES environment variable is set and is IGNORED; it was retired with no alias or fallback. Use VICE_BROKER_WARM_FLOOR instead.");
+    if (process.env.VICE_BROKER_SPARES !== undefined) { // banner-only presence check -- never reads the value
+        lines.push(
+        // This note's own former "use the warm-floor
+        // knob instead" replacement is ITSELF retired along with the warm
+        // floor -- pointing an operator at a second dead knob would be worse
+        // than pointing at none. VICE now launches strictly on demand, on the
+        // first request; there is no warming knob left to name.
+        "vice-broker: NOTE -- the VICE_BROKER_SPARES environment variable is set and is IGNORED; it was retired with no alias or fallback. There is no replacement -- VICE now launches strictly on demand, on the first request.");
     }
     return lines.join("\n");
 }
 // ============================================================================
-// Startup reap: unconditional, file-free... but no longer PROCESS-TABLE-free
-// (criterion I, D-15, as revised by 02-03-PLAN.md/D-14/D-15).
+// Startup reap: unconditional, file-free... but no longer PROCESS-TABLE-free.
 //
-// 02-03-PLAN.md (BROK-03) retires this section's entire former identity
-// mechanism -- the two functions it lived in are gone from this tree
+// This section's entire former identity
+// mechanism is retired -- the two functions it lived in are gone from this tree
 // outright, not merely unused -- which used to select kill targets by
 // scanning EVERY host process's own argument string for a plain substring
 // match on the configured emulator binary path, gated only by "some bare
-// integer token >= basePort appears somewhere in that same string" -- folded
-// todo
-// `.planning/todos/pending/2026-08-12-broker-orphan-reap-substring-identity-match.md`,
+// integer token >= basePort appears somewhere in that same string". This was
 // observed killing two unrelated orchestrator shell processes on a
 // developer's host (a long scratchpad path supplied the qualifying integer;
-// a short VICE_BIN like `/bin/sleep` supplied the substring). D-15 replaces
-// that heuristic with the broker's OWN allocation record: this reap now
+// a short VICE_BIN like `/bin/sleep` supplied the substring). The replacement
+// uses the broker's OWN allocation record: this reap now
 // enumerates the instance directories under `stateDir` (which THIS broker,
 // or a same-machine predecessor, created) and kills only the pid each
 // directory's own epoch.json actually recorded launching. A host process
@@ -424,8 +428,9 @@ function bumpEpochForInstanceDir(deps, stateDir, port) {
     };
     deps.writeEpochRecord({ supervisorDir, record });
 }
-/** The unconditional startup reap (criterion I, D-15, kill-target identity
- * revised by 02-03-PLAN.md/D-14/D-15). Runs on every broker start, before the
+/** The unconditional startup reap (kill-target identity
+ * revised to use the broker's own allocation record instead of a process-table
+ * scan). Runs on every broker start, before the
  * control listener accepts and before anything is launched -- unconditional
  * because a broker killed with SIGKILL never runs a shutdown path, so "was
  * the last shutdown clean" is unanswerable, and a marker file recording that
@@ -435,14 +440,14 @@ function bumpEpochForInstanceDir(deps, stateDir, port) {
  * Enumerates the on-disk instance directories under `stateDir` in the
  * allocation band (`port >= basePort` -- the 6510-6599 range below it stays
  * reserved by convention for an emulator a human launched for their own
- * work, D-18), and for each one reads its OWN `epoch.json` -- never a host
+ * work), and for each one reads its OWN `epoch.json` -- never a host
  * process listing, never an argv scan. A directory whose record is absent,
  * unparseable, or carries no finite positive `pid` contributes nothing to
  * `found`/`killed` and is skipped by the kill half entirely, but the epoch
  * bump below still runs for it: a registry-free restart must still void
  * every in-band instance directory it finds, including one it has no usable
- * pid for, which is the exact case this seed
- * (.planning/seeds/broker-restart-reaps-and-voids.md) flags -- the void has
+ * pid for, which is the exact case a registry-free restart must handle --
+ * the void has
  * to reach instances a registry-free restart never heard of. A record that
  * DOES carry a usable pid AND a non-empty `vice_bin` is killed via
  * verifiedKill() with `expectedIdentity` set to THAT record's own `vice_bin`
@@ -450,7 +455,7 @@ function bumpEpochForInstanceDir(deps, stateDir, port) {
  * does not match what THIS broker itself recorded launching there is refused
  * (`identity_refused`), exactly like every other verifiedKill() call site in
  * this module. A record carrying a usable pid but NO `vice_bin` is NOT a kill
- * candidate at all (CR-04): it contributes nothing to `found`/`killed`, the
+ * candidate at all: it contributes nothing to `found`/`killed`, the
  * kill dep is never invoked, and only the epoch bump runs -- an unidentifiable
  * pid is refused, never killed on the strength of the pid alone.
  *
@@ -478,7 +483,7 @@ export async function reapOrphanedInstances(options) {
         if (typeof pid === "number" && Number.isFinite(pid) && pid > 0) {
             const expectedIdentity = typeof epochFields?.vice_bin === "string" ? epochFields.vice_bin : "";
             if (expectedIdentity === "") {
-                // CR-04: a record with a usable pid but NO recorded identity is not a
+                // A record with a usable pid but NO recorded identity is not a
                 // kill candidate at all -- it is not counted in `found` and the kill
                 // dep is never invoked. verifiedKill() refuses an empty identity too
                 // (second layer, deliberately: removing either leaves the other