@henols/vice-mcp 0.2.2 → 0.2.3

package/vice-broker-client.ts

@@ -21,16 +21,25 @@
 // never-cache-a-negative-result" section.
 //
 // MUST NOT import hostpath.ts: the host-path consumer set is closed to
-// exactly five production modules (containerpath.ts, install-resources.ts,
-// stock-paths.ts, vice-proxy.ts, vice-sync.ts), pinned by
-// hostpath-consumers.test.ts, and host-path message text stays in
-// vice-proxy.ts, which is already on that list.
+// exactly four production modules (containerpath.ts, install-resources.ts,
+// stock-paths.ts, vice-proxy.ts), pinned by hostpath-consumers.test.ts, and
+// host-path message text stays in vice-proxy.ts, which is already on that
+// list.
 import { readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
 import { connect, type Socket } from "node:net";
 
 import { supervisorDir } from "./repo-root.ts";
+// Phase 33, plan 33-06 (D-15): TYPE-ONLY, and IMPORTED rather than
+// redeclared. broker-launch.mts is the one definition of the profile shape and
+// the module that turns a profile into argv; a second local shape here is how
+// a client would start requesting a knob the host cannot honour. Type-only, so
+// the container-side bundle never resolves the host-bound module at runtime.
+import type { LaunchProfile } from "./broker-launch.mts";
+// backend-detect.mts is ViceBackend's one home (narrowed to a single literal
+// by FORKRM-01, plan 52-06). Type-only, same discipline as the import above.
+import type { ViceBackend } from "./backend-detect.mts";
 // The module tree's ONE definition of the container-visible host alias
 // (vice.ts:49), carrying its own VICE_MCP_HOST override -- consumed below by
 // resolveControlTarget() rather than a fourth `host.docker.internal` literal
@@ -44,7 +53,7 @@ import { supervisorDir } from "./repo-root.ts";
 // and importing it would pull `hostpath.ts` into this module, which this
 // file's own header (lines 23-26) forbids and which the host-path
 // consumer-set assertion polices.
-import { mcpHost, ViceError } from "./vice.ts";
+import { mcpHost, ViceError } from "./vice-errors.ts";
 
 // -------------------------------------------------------------- request ids
 //
@@ -301,6 +310,24 @@ export interface AcquireGrant {
   url: string;
   epoch_file: string;
   supervisor_dir: string;
+  /** Plan 41-01 (D-15); made mandatory-in-fact by plan 41-05 (D-16): the
+   * broker-allocated port stock's `-remotemonitor` text monitor binds.
+   * Absent on a fork grant only -- a stock grant that could not bind a
+   * text-monitor port no longer reaches the wire at all: the acquire fails
+   * outright (`no_free_text_port`) before any grant is produced. */
+  remote_monitor_port?: number;
+}
+
+/** Plan 41-01: parses the wire's `remote_monitor_port` into a validated
+ * integer in 1..65535, or `undefined` when the key is absent OR the observed
+ * value is not a valid port -- never a fabricated 0/null standing in for
+ * "no port", and never an unvalidated number handed downstream to a dial.
+ * Shared by both AcquireGrant construction sites below so the same
+ * validation cannot drift between them. */
+function parseOptionalRemoteMonitorPort(value: unknown): number | undefined {
+  if (value === undefined) return undefined;
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : undefined;
 }
 
 export interface AcquireOverControlPlaneHandle {
@@ -327,13 +354,61 @@ export interface AcquireOverControlPlaneHandle {
  * client's generic timeout. */
 export const CONTROL_ACQUIRE_TIMEOUT_MS: number = Number(process.env.VICE_BROKER_ACQUIRE_TIMEOUT_MS || 120000);
 
+/** Phase 33, plan 33-06 (REPRO-05, D-15): the request-side launch profile.
+ * Optional and absent by default at BOTH acquire write sites in this file.
+ *
+ * ONE RULE, and it is the whole reason this shape is named rather than
+ * inlined: the `profile` key must be OMITTED ENTIRELY when no profile was
+ * requested, not written as `profile: undefined`. `JSON.stringify` drops an
+ * `undefined` value, so both spellings happen to produce the same bytes today
+ * -- but an explicit `null` or `{}` would not, and the property this phase
+ * needs is that a profile-less acquire's wire line is BYTE-IDENTICAL to the
+ * one this client has always written. The spread idiom below is what makes
+ * that structural rather than incidental.
+ *
+ * The SECOND rule, which cost this plan its own dedicated must-have: the
+ * profile has to be written at BOTH sites. This file has two independent
+ * acquire writers -- acquireOverControlPlane()'s raw `socket.write` below and
+ * openBrokerControl()'s `sendAndAwaitLine` further down. A field added to only
+ * one of them silently never arrives for callers on the other path, which is
+ * the same defect class as a tool argument that is accepted and dropped.
+ *
+ * CONSUMER STATUS: SUBSTRATE, NOT YET WIRED (33 review WR-08). The profile
+ * threads client -> wire -> narrowing -> eligibility -> argv -> record with
+ * tests at every hop, but as of phase 33 NO production call site passes one:
+ * `acquireOverControlPlane()` and `BrokerControlSession.acquire()` are only
+ * ever invoked without `opts.profile`, so `-warp` and `-console` are
+ * unreachable in production. That is deliberate -- phase 33 built the chain
+ * ahead of phases 34-38 using it -- and is recorded here rather than left for
+ * a reader to discover, because a fully-tested chain reads as a live one.
+ *
+ * Do NOT close this by inventing a call site. Note also that the profile is
+ * refused outright on the fork backend (33 review WR-03, broker-control.mts):
+ * it maps to stock-only launch flags, so the first real consumer has to be on
+ * stock. */
+export interface AcquireProfileOptions {
+  profile?: LaunchProfile;
+}
+
+/** Builds the `profile` fragment of an acquire request line -- the ONE place
+ * this client decides whether the key appears at all, so the two write sites
+ * cannot drift apart on that decision. Returns an empty object (no key) when
+ * no profile was requested. */
+function acquireProfileFragment(profile?: LaunchProfile): { profile?: LaunchProfile } {
+  return profile === undefined ? {} : { profile };
+}
+
 /** Reads broker.json ONCE for control_host/control_port/control_token,
  * opens ONE TCP connection, sends a single `acquire` request framed as one
  * JSON line, and awaits the grant line against
  * CONTROL_ACQUIRE_TIMEOUT_MS. Rejects (never throws synchronously) on any
  * failure: broker.json absent/unreadable/missing the control fields, a
- * connection error, an `error` response, or a timeout. */
-export function acquireOverControlPlane(dir: string = brokerRootDir()): Promise<AcquireOverControlPlaneHandle> {
+ * connection error, an `error` response, or a timeout.
+ *
+ * Phase 33, plan 33-06: takes an optional `profile` (see
+ * AcquireProfileOptions above). Omitting it writes the exact wire line this
+ * function has always written. */
+export function acquireOverControlPlane(dir: string = brokerRootDir(), opts: AcquireProfileOptions = {}): Promise<AcquireOverControlPlaneHandle> {
   return new Promise((resolvePromise, reject) => {
     const broker = readJsonMaybe(brokerJsonPath(dir));
     if (broker === null) {
@@ -369,7 +444,11 @@ export function acquireOverControlPlane(dir: string = brokerRootDir()): Promise<
 
     socket.on("connect", () => {
       const requestId = newRequestId();
-      socket.write(`${JSON.stringify({ op: "acquire", id: requestId, token })}\n`);
+      // Phase 33, plan 33-06: write site ONE of two (see
+      // acquireProfileFragment()'s own comment) -- the key is absent entirely
+      // when no profile was requested, so this line stays byte-identical to
+      // what it always was for a profile-less acquire.
+      socket.write(`${JSON.stringify({ op: "acquire", id: requestId, token, ...acquireProfileFragment(opts.profile) })}\n`);
     });
 
     socket.on("data", (chunk: Buffer) => {
@@ -400,12 +479,14 @@ export function acquireOverControlPlane(dir: string = brokerRootDir()): Promise<
       if (resp.kind === "grant") {
         settled = true;
         clearTimeout(timer);
+        const remoteMonitorPort = parseOptionalRemoteMonitorPort(resp.remote_monitor_port);
         const grant: AcquireGrant = {
           id: String(resp.id),
           port: Number(resp.port),
           url: String(resp.url),
           epoch_file: String(resp.epoch_file),
           supervisor_dir: String(resp.supervisor_dir),
+          ...(remoteMonitorPort === undefined ? {} : { remote_monitor_port: remoteMonitorPort }),
         };
         resolvePromise({
           grant,
@@ -550,37 +631,56 @@ interface ControlHostStateFields {
   warm_floor: number;
   max_instances: number;
   base_port: number;
-  /** WR-04: the backend verdict the BROKER resolved -- the authoritative one,
-   * since it is what decided the emulator's launch argv. `null` when the broker
-   * predates this field or sent something unrecognised: absent evidence, kept
-   * strictly distinct from a definite disagreement, so a mismatch check can
-   * refuse only on the latter. */
-  backend: "fork" | "stock" | null;
+  /** FORKRM-01 (plan 52-06): narrowed from `"fork" | "stock" | null` to
+   * `ViceBackend | null` -- `null` when the broker predates this field or
+   * sent something unrecognised: absent evidence, kept distinct from a
+   * definite value. text-tools.ts's own broker-identity cross-check (out of
+   * this plan's scope) still reads this field. */
+  backend: ViceBackend | null;
 }
 
 export type ControlHostStateResult =
   | { ok: true; hostState: ControlHostStateFields }
   | { ok: false; kind: ControlFailureKind; message: string };
 
-/** Plan 05 (BROK-02/PROTO-08, D-13): the current monitor-socket holder's own
- * identity, named in a `monitor_owned` refusal -- field-for-field the same
- * shape the broker's own MonitorHolder carries (broker-control.mts), minus
- * nothing (pid included, matching GrantRecord's own convention this whole
- * mechanism mirrors). */
+// ---------------------------------------------------------------------------
+// MonitorClaimChannel (plan 41-03, D-14): the two-value channel contract,
+// declared HERE as a local literal union rather than imported from
+// broker-state.mts -- that module is host-bound and compiled into
+// resources/*.mjs, and this file is the container-side half. The shared
+// thing between the declarations is the CONTRACT ("binary" | "text"), not
+// the declaration itself -- channel-lock.ts's own MonitorChannel and
+// broker-state.mts's own MonitorChannel each declare it separately for the
+// same reason.
+// ---------------------------------------------------------------------------
+export type MonitorClaimChannel = "binary" | "text";
+
+/** Plan 05 (BROK-02/PROTO-08, D-13; gains `channel` in plan 41-03, D-14): the
+ * current monitor-socket holder's own identity, named in a `monitor_owned`
+ * refusal -- field-for-field the same shape the broker's own MonitorHolder
+ * carries (broker-control.mts), minus nothing (pid included, matching
+ * GrantRecord's own convention this whole mechanism mirrors). */
 export interface MonitorClaimHolder {
   grantId: string;
   claimedAt: number;
   pid: number | null;
+  channel: MonitorClaimChannel;
 }
 
 export interface ClaimMonitorOptions {
   targetId: string;
   timeoutMs?: number;
+  /** Plan 41-03 (D-14): which monitor socket to claim. Omitted is
+   * byte-identical to `"binary"` -- every pre-41-03 call site (and every
+   * broker that predates this field) keeps working unchanged. */
+  channel?: MonitorClaimChannel;
 }
 
 export interface ReleaseMonitorOptions {
   targetId: string;
   timeoutMs?: number;
+  /** Plan 41-03 (D-14): same default-to-binary posture as ClaimMonitorOptions.channel. */
+  channel?: MonitorClaimChannel;
 }
 
 /** Discriminated claim outcome (plan 05): `monitor_owned` is kept STRICTLY
@@ -607,6 +707,9 @@ export interface MonitorOwnershipErrorOptions {
   holderGrantId?: string;
   holderClaimedAt?: number;
   port?: number;
+  /** Plan 41-03 (D-14): which socket is contended -- so a handshake failure
+   * can say which channel was refused without re-parsing the message. */
+  channel?: MonitorClaimChannel;
 }
 
 /** Thrown (by a caller that prefers to raise rather than branch on
@@ -628,13 +731,15 @@ export class MonitorOwnershipError extends ViceError {
   holderGrantId?: string;
   holderClaimedAt?: number;
   port?: number;
+  channel?: MonitorClaimChannel;
 
-  constructor(message: string, { holderGrantId, holderClaimedAt, port }: MonitorOwnershipErrorOptions = {}) {
+  constructor(message: string, { holderGrantId, holderClaimedAt, port, channel }: MonitorOwnershipErrorOptions = {}) {
     super(message);
     this.name = "MonitorOwnershipError";
     this.holderGrantId = holderGrantId;
     this.holderClaimedAt = holderClaimedAt;
     this.port = port;
+    this.channel = channel;
   }
 }
 
@@ -654,7 +759,10 @@ export interface ControlDeadlineOptions {
  * exactly one request line and resolves against its own deadline; none of
  * them ever reject. */
 export interface BrokerControlSession {
-  acquire(opts?: ControlDeadlineOptions): Promise<ControlAcquireResult>;
+  /** Phase 33, plan 33-06 (REPRO-05, D-15): additionally takes an optional
+   * `profile` -- see AcquireProfileOptions. Omitting it is byte-identical to
+   * every pre-33-06 call. */
+  acquire(opts?: ControlDeadlineOptions & AcquireProfileOptions): Promise<ControlAcquireResult>;
   release(): Promise<ControlReleaseResult>;
   recycle(targetId: string, opts?: ControlDeadlineOptions): Promise<ControlRecycleResult>;
   status(opts?: ControlDeadlineOptions): Promise<ControlStatusResult>;
@@ -719,6 +827,21 @@ export interface HeldLease {
    * backend-detect.mts's own documented degradation for an omitted
    * supervisorDir. */
   supervisorDir: string;
+  /** Plan 41-01 (D-15); made mandatory-in-fact by plan 41-05 (D-16): THIS
+   * instance's own text-monitor port, read by text-connect.ts's
+   * textConnect() to dial the `-remotemonitor` channel. MANDATORY on a
+   * stock grant, ABSENT on a fork grant -- the fork never launches with
+   * `-remotemonitor` and advertises no text tools. Its absence on a stock
+   * lease is a real defect, not a tolerated state (mirrors epochFile's own
+   * "NOT optional" discipline above): the mechanism that makes this true is
+   * broker-launch.mts's acquirePortAndLaunch(), which now FAILS THE WHOLE
+   * ACQUIRE when the text-port allocation fails (`no_free_text_port`)
+   * rather than degrading to a portless launch -- there is no longer a code
+   * path that produces a stock grant, and therefore a HeldLease, without
+   * this field. Its optionality here is a transitional TypeScript
+   * convenience only (the fork case is real), never a semantic "sometimes
+   * missing on stock". */
+  remoteMonitorPort?: number;
 }
 
 /** One in-flight request's settlement callback -- pushed onto the session's
@@ -746,12 +869,17 @@ type RawLineOutcome = { ok: true; line: Record<string, unknown> } | { ok: false;
 /** Never-throw extraction of a `holder` payload from untrusted wire input --
  * absent or malformed input answers `undefined`, never a partially-filled
  * object (plan 05's own never-throw-on-untrusted-input posture, matching
- * this file's own header comment on broker.json reads). */
-function extractHolder(raw: unknown): MonitorClaimHolder | undefined {
+ * this file's own header comment on broker.json reads). `channel` (plan
+ * 41-03, D-14) defaults to `requestedChannel` -- THE channel this request
+ * itself named -- when the wire omits it or sends something unrecognised;
+ * never fabricated as a plausible value, in the same register the
+ * `grantId: "unknown"` fallback one layer up (claimMonitor()'s own) uses. */
+function extractHolder(raw: unknown, requestedChannel: MonitorClaimChannel): MonitorClaimHolder | undefined {
   if (typeof raw !== "object" || raw === null) return undefined;
   const h = raw as Record<string, unknown>;
   if (typeof h.grantId !== "string" || typeof h.claimedAt !== "number") return undefined;
-  return { grantId: h.grantId, claimedAt: h.claimedAt, pid: typeof h.pid === "number" ? h.pid : null };
+  const channel = h.channel === "text" || h.channel === "binary" ? h.channel : requestedChannel;
+  return { grantId: h.grantId, claimedAt: h.claimedAt, pid: typeof h.pid === "number" ? h.pid : null, channel };
 }
 
 /** Builds the session object wrapping an already-CONNECTED socket. Wires the
@@ -835,8 +963,13 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
             // Plan 05: forward `holder` verbatim ONLY for monitor_owned --
             // every other error code carries no such field on the wire, and
             // extractHolder() itself never invents one from absent/malformed
-            // input.
-            const holder = code === "monitor_owned" ? extractHolder(line.holder) : undefined;
+            // input. Plan 41-03 (D-14): the requested channel comes from
+            // THIS payload (the request this response answers), read from
+            // the same closure `payload` sendAndAwaitLine() was called
+            // with -- an absent/malformed wire `channel` is never fabricated,
+            // it defaults to the channel this specific request itself named.
+            const requestedChannel: MonitorClaimChannel = payload.channel === "text" ? "text" : "binary";
+            const holder = code === "monitor_owned" ? extractHolder(line.holder, requestedChannel) : undefined;
             resolvePromise({
               ok: false,
               kind: code,
@@ -862,20 +995,29 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
     });
   }
 
-  async function acquire(opts: ControlDeadlineOptions = {}): Promise<ControlAcquireResult> {
+  async function acquire(opts: ControlDeadlineOptions & AcquireProfileOptions = {}): Promise<ControlAcquireResult> {
     const requestId = newRequestId();
-    const raw = await sendAndAwaitLine({ op: "acquire", id: requestId, token }, opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS);
+    // Phase 33, plan 33-06: write site TWO of two (see
+    // acquireProfileFragment()'s own comment for why both matter) -- same
+    // key-omitted-when-absent discipline as acquireOverControlPlane()'s raw
+    // socket.write above.
+    const raw = await sendAndAwaitLine(
+      { op: "acquire", id: requestId, token, ...acquireProfileFragment(opts.profile) },
+      opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS,
+    );
     if (!raw.ok) return raw;
     const line = raw.line;
     if (line.kind !== "grant") {
       return { ok: false, kind: "protocol", message: `openBrokerControl: acquire got unexpected response kind ${String(line.kind)}` };
     }
+    const remoteMonitorPort = parseOptionalRemoteMonitorPort(line.remote_monitor_port);
     const grant: AcquireGrant = {
       id: String(line.id),
       port: Number(line.port),
       url: String(line.url),
       epoch_file: String(line.epoch_file),
       supervisor_dir: String(line.supervisor_dir),
+      ...(remoteMonitorPort === undefined ? {} : { remote_monitor_port: remoteMonitorPort }),
     };
     return { ok: true, grant };
   }
@@ -957,16 +1099,17 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
         warm_floor: Number(line.warm_floor),
         max_instances: Number(line.max_instances),
         base_port: Number(line.base_port),
-        // WR-04: narrowed at the boundary, never cast -- anything other than the
-        // two known verdicts reads as `null` ("this broker did not tell us"),
-        // which callers must treat as absent evidence rather than agreement.
-        backend: line.backend === "fork" || line.backend === "stock" ? line.backend : null,
+        // FORKRM-01 (plan 52-06): narrowed at the boundary, never cast --
+        // anything other than the one known verdict reads as `null` ("this
+        // broker did not tell us"), which callers must treat as absent
+        // evidence rather than agreement.
+        backend: line.backend === "stock" ? line.backend : null,
       },
     };
   }
 
   /** Claims exclusive ownership of `opts.targetId`'s monitor socket, sending
-   * `{ op: "monitor_claim", id, target_id, token }` through the SAME
+   * `{ op: "monitor_claim", id, target_id, channel, token }` through the SAME
    * `sendAndAwaitLine()` path -- the same session, the same token, the same
    * newline-delimited JSON discipline every other op uses; no second
    * control connection is ever opened, and this function never dials the
@@ -974,10 +1117,12 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
    * -- see MonitorOwnershipError's own header comment for why the claim is
    * made BEFORE any binmon connect()). `timeout` is reported distinctly
    * from `monitor_owned`: a timeout means the broker did not answer, never
-   * that someone else owns the socket. */
+   * that someone else owns the socket. `channel` (plan 41-03, D-14) defaults
+   * to `"binary"` when omitted -- byte-identical to every pre-41-03 call. */
   async function claimMonitor(opts: ClaimMonitorOptions): Promise<ClaimMonitorOutcome> {
     const requestId = newRequestId();
-    const raw = await sendAndAwaitLine({ op: "monitor_claim", id: requestId, target_id: opts.targetId, token }, opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS);
+    const channel: MonitorClaimChannel = opts.channel ?? "binary";
+    const raw = await sendAndAwaitLine({ op: "monitor_claim", id: requestId, target_id: opts.targetId, channel, token }, opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS);
     if (!raw.ok) {
       if (raw.kind === "deadline") return { ok: false, reason: "timeout" };
       // WR-08: the `monitor_owned` REASON survives even when the wire's own
@@ -989,11 +1134,11 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
       // requires (and MonitorOwnershipError exists to preserve) was lost. The
       // broker has told us WHICH state this is; not being able to name the
       // holder does not make it a different state. Holder fields default to
-      // "unknown"/0/null so the wording still reads as an ownership conflict
-      // rather than an emulator fault -- never fabricated as a plausible grant
-      // id, which would be worse than admitting it is unknown.
+      // "unknown"/0/null/`channel` so the wording still reads as an ownership
+      // conflict rather than an emulator fault -- never fabricated as a
+      // plausible grant id, which would be worse than admitting it is unknown.
       if (raw.kind === "monitor_owned") {
-        return { ok: false, reason: "monitor_owned", holder: raw.holder ?? { grantId: "unknown", claimedAt: 0, pid: null } };
+        return { ok: false, reason: "monitor_owned", holder: raw.holder ?? { grantId: "unknown", claimedAt: 0, pid: null, channel } };
       }
       if (raw.kind === "unauthorized" || raw.kind === "bad_request" || raw.kind === "denied") return { ok: false, reason: raw.kind };
       return { ok: false, reason: "internal" };
@@ -1005,14 +1150,16 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
   }
 
   /** Releases a previously claimed monitor socket, sending
-   * `{ op: "monitor_release", id, target_id, token }` over the SAME
+   * `{ op: "monitor_release", id, target_id, channel, token }` over the SAME
    * session. Tolerates a broker that has already cleared the record (the
    * broker's own onMonitorRelease answers `ok: true` for an already-cleared
    * target) -- this function never retries and never opens a second
-   * connection. */
+   * connection. `channel` (plan 41-03, D-14) defaults to `"binary"` when
+   * omitted. */
   async function releaseMonitor(opts: ReleaseMonitorOptions): Promise<ReleaseMonitorOutcome> {
     const requestId = newRequestId();
-    const raw = await sendAndAwaitLine({ op: "monitor_release", id: requestId, target_id: opts.targetId, token }, opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS);
+    const channel: MonitorClaimChannel = opts.channel ?? "binary";
+    const raw = await sendAndAwaitLine({ op: "monitor_release", id: requestId, target_id: opts.targetId, channel, token }, opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS);
     if (!raw.ok) {
       if (raw.kind === "deadline") return { ok: false, reason: "timeout" };
       if (raw.kind === "unauthorized" || raw.kind === "bad_request" || raw.kind === "denied") return { ok: false, reason: raw.kind };