@henols/vice-mcp 0.2.2 → 0.2.3

package/resources/broker-control.mjs

@@ -2,7 +2,7 @@
 // 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
 //
@@ -48,6 +48,91 @@ const MAX_LINE_BYTES = 65536;
  * and T-02-18's prohibition on wedge/hang vocabulary in this file's
  * 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 (plan 41-03, D-14): an ABSENT field means `binary`
+ * deliberately -- a broker restarted mid-phase against a client that
+ * predates this field keeps working (backward compatibility, this plan's
+ * own must-have). 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";
+}
+// ---------------------------------------------------------------------------
+// Phase 33, plan 33-06 (REPRO-05, D-15, T-33-03/T-33-04): 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. That is the same undetectable-lie failure
+// D-16 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 +159,21 @@ function writeLine(socket, obj) {
         socket.write(`${JSON.stringify(obj)}\n`);
     }
 }
+/** Phase 34, plan 34-01: 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()}`;
 }
@@ -217,7 +317,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 +325,12 @@ function attachControlProtocol(server, opts, pendingAcquires) {
             if (socket.destroyed)
                 return Promise.resolve(true);
             return opts
-                .onAcquire(requestId)
+                // Phase 33, plan 33-06: 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 +350,14 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                         url: outcome.grant.url,
                         epoch_file: outcome.grant.epochFile,
                         supervisor_dir: outcome.grant.supervisorDir,
+                        // D-15; tightened by plan 41-05 (D-16): 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 +402,52 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                 socket.destroy();
                 return;
             }
-            if (req.op === "acquire") {
+            // Phase 34, plan 34-01 (SEAM-01): dispatched FIRST in the chain, before
+            // "acquire" -- so the ordering reads as the requirement does. 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) => {
+                // Phase 33, plan 33-06 (T-33-03): 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;
+                // 33 review WR-03's profile-is-stock-only refusal lived 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. FORKRM-01 (plan 52-06):
+                // there is one backend now 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) });
                     }
                 });
             }
@@ -354,7 +508,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,15 +523,25 @@ 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 (plan 41-03,
+                    // D-14) -- deliberately worded to never suggest the emulator
+                    // itself has stopped answering (T-02-18; the plan's own grep gate
+                    // polices this).
                     //
                     // WR-08 (broker side): `holder` is REQUIRED by MonitorClaimOutcome for
                     // this code, but this handler runs inside socket.on("data") with no
@@ -386,13 +549,14 @@ function attachControlProtocol(server, opts, pendingAcquires) {
                     // 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 +574,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,7 +2,7 @@
 // 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
 //

package/resources/broker-kill.mjs

@@ -2,7 +2,7 @@
 // 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
 //
@@ -325,7 +325,13 @@ export function startupBanner() {
         "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.");
+        lines.push(
+        // Plan 41-05 (folded todo): 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");
 }