@henols/vice-mcp 0.2.2 → 0.2.4

package/resources/broker-state.mjs

@@ -2,17 +2,41 @@
 // Compiled by `tsc` from broker-state.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.
 import { createServer } from "node:net";
-/** Clears `monitorClient` as a side effect of release, recycle, or the
- * instance's own process exit (see InstanceRecord.monitorClient's own header
- * comment for the three call sites) -- so a dead or torn-down client can
- * never hold this lock forever. A no-op when no monitor client is currently
- * recorded (idempotent, matching monitor_release's own tolerance for an
- * already-cleared record). */
-export function clearMonitorClient(record) {
-    record.monitorClient = undefined;
+// ---------------------------------------------------------------------------
+// MonitorChannel: exactly two channels exist -- stock VICE
+// exposes precisely the binary monitor and the `-remotemonitor` text
+// channel -- and this project has no plan to add a third. Frozen so a
+// consumer cannot accidentally push a third value onto it at runtime.
+//
+// Declared here a SECOND time in channel-lock.ts (and a third time, as a
+// local literal union, in vice-broker-client.ts) rather than imported from a
+// single shared home: channel-lock.ts is a container-side module and this
+// module is host-bound and compiled into resources/*.mjs, so neither can
+// import the other at runtime. The shared thing between the declarations is
+// the two-value CONTRACT ("binary" | "text"), not the declaration itself.
+// ---------------------------------------------------------------------------
+export const MONITOR_CHANNELS = Object.freeze(["binary", "text"]);
+/** Clears ONE channel's entry when `channel` is passed (an explicit
+ * `monitor_release` for that channel), or EVERY channel's entry when it is
+ * omitted (the whole record's ownership is going away -- recycle, release,
+ * or the instance's own process exit; see InstanceRecord.monitorClients'
+ * own header comment for the exact call sites of each case) -- so a dead or
+ * torn-down client can never hold this lock forever, on any channel. The
+ * ONE place a holder entry is cleared, apart from broker-launch.mts's
+ * handleExit(), which assigns `{}` directly for a documented reason (see
+ * that function's own comment). A no-op when the targeted channel (or, with
+ * no channel, every channel) is not currently held -- idempotent, matching
+ * monitor_release's own tolerance for an already-cleared record. */
+export function clearMonitorClient(record, channel) {
+    if (channel !== undefined) {
+        delete record.monitorClients[channel];
+        return;
+    }
+    for (const ch of MONITOR_CHANNELS)
+        delete record.monitorClients[ch];
 }
 export function createBrokerState() {
     return { instances: new Map(), grants: new Map(), blockedPorts: new Set() };
@@ -23,13 +47,26 @@ export function createBrokerState() {
  * trip. */
 export function _snapshotState(state) {
     return {
-        instances: Array.from(state.instances.values()).map((r) => ({ ...r, viceArgs: [...r.viceArgs] })),
+        // `profile` is the SECOND nested object on an
+        // InstanceRecord (after `viceArgs`), so it needs its own copy for this
+        // function's documented "deep, plain-object copy" contract to stay true --
+        // a spread alone would hand a caller a reference into live broker state,
+        // and this file's own snapshot test asserts that mutating a nested value
+        // in the result leaves the broker's state unchanged. The key is
+        // reproduced only when present, so an absent profile stays absent in the
+        // snapshot (absent means profile-less, and a snapshot must not invent a
+        // `profile: undefined` key that the record itself does not carry).
+        instances: Array.from(state.instances.values()).map((r) => ({
+            ...r,
+            viceArgs: [...r.viceArgs],
+            ...(r.profile === undefined ? {} : { profile: { ...r.profile } }),
+        })),
         grants: Array.from(state.grants.values()).map((g) => ({ ...g })),
         blockedPorts: Array.from(state.blockedPorts).sort((a, b) => a - b),
     };
 }
-/** VICE_BROKER_BASE_PORT's default (D-18): the broker's port band moves
- * from 6510 to 6600 in this phase -- 6510-6599 stays reserved by convention
+/** VICE_BROKER_BASE_PORT's default: the broker's port band moved
+ * from 6510 to 6600 -- 6510-6599 stays reserved by convention
  * for an x64sc a human launches for their own work. */
 export const DEFAULT_BASE_PORT = 6600;
 /** Scan ceiling matching vice-broker.sh's own next_free_port(): exactly one
@@ -80,8 +117,8 @@ export function isPortBlocked(state, port) {
 export function blockPort(state, port) {
     state.blockedPorts.add(port);
 }
-/** Allocates the lowest free port at or above the base port (default 6600
- * per D-18, overridable via VICE_BROKER_BASE_PORT -- the same env var name
+/** Allocates the lowest free port at or above the base port (default 6600,
+ * overridable via VICE_BROKER_BASE_PORT -- the same env var name
  * the bash daemon used), scanning up to PORT_SCAN_CEILING candidates.
  * "Free" means: not already recorded in the instance map (granted,
  * launching or ready all occupy their port), not already in the
@@ -91,8 +128,7 @@ export function blockPort(state, port) {
  * set before scanning continues, so it is never re-offered or re-probed by
  * this process again. Never throws -- returns a typed failure naming
  * exhaustion when every candidate in the window is taken. */
-// Gap closure (plan 14, discovered live during Task 2's own end-to-end
-// proof -- see RE-FINDINGS.md's dated entry for the full account):
+// Discovered live during an end-to-end proof of this allocator:
 // EADDRINUSE is delivered to defaultPortInUse()'s `error` listener without
 // ever yielding to libuv's poll phase, so a scan running against MANY
 // already-bound candidates in a row does not merely take longer -- for its
@@ -149,14 +185,23 @@ export function countReady(state) {
 export function countTotal(state) {
     return state.instances.size;
 }
-/** Counts instances currently "launching" -- THE single counter both launch
- * paths (a cold acquire, via handleAcquire in vice-broker.mts, and warm
- * floor maintenance, via maintainWarmFloor in broker-launch.mts) consult
- * before starting a new launch. Two counters that could ever disagree about
- * whether a boot is already under way is exactly how the two bash launch
- * paths raced each other into the 2026-08-01 outage (three simultaneous
- * x64sc launches: one SEGV, one exit 1, one exit 0 at the identical spawn
- * second) -- there is now exactly one, read here and nowhere else. */
+/** Counts instances currently "launching". The warm floor and its own
+ * maintainWarmFloor() were retired -- that was the SECOND launch path
+ * that used to read this counter as a pre-check before starting a new
+ * launch, alongside the cold-acquire arm's own equivalent check. With only
+ * one launch path left (vice-broker.mts's handleAcquire(), guarded by
+ * acquirePortAndLaunch()'s own single-owner `inFlight` boolean in
+ * broker-launch.mts -- a SEPARATE, synchronous primitive, not this
+ * function), nothing in production calls this counter today; it remains
+ * exported alongside countReady()/countTotal() as status-shaped
+ * infrastructure. It is named here, and its history preserved, because it
+ * is why a SINGLE counter -- not two, one per launch path -- was the fix
+ * for the 2026-08-01 outage (three simultaneous x64sc launches: one SEGV,
+ * one exit 1, one exit 0 at the identical spawn second): two counters that
+ * could ever disagree about whether a boot was already under way is exactly
+ * how that outage happened, and the discipline of reading exactly one is
+ * what this function's own existence still documents, even with one launch
+ * path left to (potentially) consult it. */
 export function countLaunching(state) {
     let n = 0;
     for (const record of state.instances.values()) {

package/resources/container-guard.mjs

@@ -2,7 +2,7 @@
 // Compiled by `tsc` from container-guard.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.
 // container-guard.mts
 //