@henols/vice-mcp 0.2.2 → 0.2.3

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 (plan 41-03, D-14): 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,7 +47,20 @@ export function createBrokerState() {
  * trip. */
 export function _snapshotState(state) {
     return {
-        instances: Array.from(state.instances.values()).map((r) => ({ ...r, viceArgs: [...r.viceArgs] })),
+        // Phase 33, plan 33-06: `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),
     };
@@ -149,14 +186,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". Plan 41-05 (folded todo) retired
+ * the warm floor and its own maintainWarmFloor() -- 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
 //