@henols/vice-mcp 0.1.9 → 0.1.11

package/vice-broker-client.ts

@@ -21,9 +21,10 @@
 // never-cache-a-negative-result" section.
 //
 // MUST NOT import hostpath.ts: the host-path consumer set is closed to
-// four production modules by vice-mcp-selector-docs.test.mjs's assertion 4,
-// and host-path message text stays in vice-proxy.mjs, which is already on
-// that list.
+// 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.
 import { readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
@@ -43,7 +44,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 } from "./vice.ts";
+import { mcpHost, ViceError } from "./vice.ts";
 
 // -------------------------------------------------------------- request ids
 //
@@ -509,7 +510,13 @@ export type ControlFailureKind =
   | "denied"
   | "no_free_port"
   | "at_capacity"
-  | "internal";
+  | "internal"
+  // Plan 05 (BROK-02/PROTO-08): the broker's own ControlErrorCode gained
+  // this member for the ownership-conflict outcome; duplicated here for the
+  // same reason every other member already is (this client and the broker
+  // run in separate processes -- the shared surface is the wire format, not
+  // a TypeScript type).
+  | "monitor_owned";
 
 export type ControlAcquireResult = { ok: true; grant: AcquireGrant } | { ok: false; kind: ControlFailureKind; message: string };
 
@@ -543,12 +550,94 @@ 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;
 }
 
 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). */
+export interface MonitorClaimHolder {
+  grantId: string;
+  claimedAt: number;
+  pid: number | null;
+}
+
+export interface ClaimMonitorOptions {
+  targetId: string;
+  timeoutMs?: number;
+}
+
+export interface ReleaseMonitorOptions {
+  targetId: string;
+  timeoutMs?: number;
+}
+
+/** Discriminated claim outcome (plan 05): `monitor_owned` is kept STRICTLY
+ * separate from `timeout` -- conflating "someone else holds it" with "the
+ * broker did not answer" would reintroduce exactly the ambiguity PROTO-08
+ * exists to remove. Never thrown; a caller that wants to raise instead
+ * should construct a MonitorOwnershipError from this outcome's own fields
+ * (see that class's own header comment). */
+export type ClaimMonitorOutcome =
+  | { ok: true }
+  | { ok: false; reason: "monitor_owned"; holder: MonitorClaimHolder }
+  // "denied" (CR-03): the broker's control plane refused because the grant
+  // named is not the one THIS connection holds. In a correct client that is
+  // unreachable -- stockConnect() always claims the grant its own session
+  // acquired -- so it is carried as its own reason rather than collapsed into
+  // "internal", where a wiring bug would be indistinguishable from a broker
+  // fault. Kept strictly distinct from "monitor_owned", which is a conflict
+  // between two LEGITIMATE holders.
+  | { ok: false; reason: "timeout" | "unauthorized" | "bad_request" | "denied" | "internal" };
+
+export type ReleaseMonitorOutcome = { ok: true } | { ok: false; reason: "timeout" | "unauthorized" | "bad_request" | "denied" | "internal" };
+
+export interface MonitorOwnershipErrorOptions {
+  holderGrantId?: string;
+  holderClaimedAt?: number;
+  port?: number;
+}
+
+/** Thrown (by a caller that prefers to raise rather than branch on
+ * ClaimMonitorOutcome) when `monitor_claim` is refused because a DIFFERENT
+ * grant already holds this instance's monitor socket (plan 05, PROTO-08,
+ * D-13). Names the holding grant and the port plainly, as an ownership
+ * conflict -- a state the broker itself enforced, distinct from an emulator
+ * that has stopped answering, and NOT a state the vice-wedge-triage skill's
+ * opening move should ever be misdirected by.
+ *
+ * The claim this error reports on a refusal is made BEFORE any binmon
+ * connect() is ever attempted: stock VICE services exactly one binmon
+ * client, and a second connect() produces no reply and no EOF, so a refusal
+ * arriving only after dialling would be byte-for-byte indistinguishable
+ * from a wedge (PROTO-08). Claiming first means this refusal is a JSON
+ * response on a control-plane socket that already works, and the second
+ * client never dials the binmon port at all (D-13). */
+export class MonitorOwnershipError extends ViceError {
+  holderGrantId?: string;
+  holderClaimedAt?: number;
+  port?: number;
+
+  constructor(message: string, { holderGrantId, holderClaimedAt, port }: MonitorOwnershipErrorOptions = {}) {
+    super(message);
+    this.name = "MonitorOwnershipError";
+    this.holderGrantId = holderGrantId;
+    this.holderClaimedAt = holderClaimedAt;
+    this.port = port;
+  }
+}
+
 /** Per-call deadline override -- matches PollOptions's own established shape
  * above (pollGrant()/pollRecycleAck() already take an optional `timeoutMs`
  * this same way). The MODULE-LEVEL constant (ACQUIRE_TIMEOUT_MS etc.) is the
@@ -570,6 +659,15 @@ export interface BrokerControlSession {
   recycle(targetId: string, opts?: ControlDeadlineOptions): Promise<ControlRecycleResult>;
   status(opts?: ControlDeadlineOptions): Promise<ControlStatusResult>;
   hostState(opts?: ControlDeadlineOptions): Promise<ControlHostStateResult>;
+  /** Claims exclusive ownership of an instance's monitor socket BEFORE any
+   * binmon connect() is attempted (plan 05, PROTO-08, D-13) -- see
+   * MonitorOwnershipError's own header comment for why claiming first is
+   * the only way this refusal can ever be distinguishable from a wedge. */
+  claimMonitor(opts: ClaimMonitorOptions): Promise<ClaimMonitorOutcome>;
+  /** Releases a previously claimed monitor socket. Tolerates a broker that
+   * has already cleared the record (release/recycle/process-exit all clear
+   * it broker-side) -- a second release is `ok: true`, not an error. */
+  releaseMonitor(opts: ReleaseMonitorOptions): Promise<ReleaseMonitorOutcome>;
 }
 
 export interface OpenBrokerControlOptions {
@@ -580,6 +678,49 @@ export type OpenBrokerControlOutcome =
   | { ok: true; session: BrokerControlSession }
   | { ok: false; kind: ControlFailureKind; message: string; target?: string };
 
+/** The backend-agnostic coordinate set a session which ALREADY holds a
+ * broker grant hands to anything that needs to dial the instance that grant
+ * names (plan 02-09, PROTO-08, D-13). Declared here, beside
+ * BrokerControlSession and openBrokerControl(), because it is
+ * backend-agnostic -- the fork path does not consume it only because
+ * forwardToVice() reads activeInstance() from the same module (vice.ts)
+ * that owns the state, not because this shape is stock-specific.
+ *
+ * `targetId` is the GRANT ID, not the port -- the exact same value
+ * vice-proxy.ts's own `controlSession.recycle(grantId)` call site passes.
+ * `brokerControl` is the SAME control session the grant was acquired
+ * through; a stock handler must claim its monitor socket on this session,
+ * never on one it opened itself (see stock-dispatch.ts's own
+ * ensureStockSession() header comment for why a second acquisition would
+ * break the claim-before-dial guarantee this type exists to preserve). */
+export interface HeldLease {
+  host: string;
+  port: number;
+  targetId: string;
+  brokerControl: BrokerControlSession;
+  /** CR-06: THIS instance's own epoch.json, in the CONSUMER's view of the
+   * filesystem (i.e. already containerized -- vice-proxy.ts fills it from
+   * activeInstance().epochFile, which adoptGrant() set from the containerized
+   * grant). This is the reconnect-identity baseline stock-connect.ts's
+   * stockReconnect() proves machine identity against. NOT optional: with it
+   * absent, stockReconnect() reports a FALSE MachineRestartedError on every
+   * transient socket drop ("treat every result since the previous call as
+   * void"), because identity that cannot be proven is treated as not proven.
+   * Empty string means genuinely no epoch evidence exists, which is that same
+   * unprovable case stated explicitly rather than by omission. */
+  epochFile: string;
+  /** CR-06: the TOP-LEVEL supervisor directory -- the one holding
+   * `backend.json`, i.e. the same directory `broker.json` is read from
+   * (brokerRootDir()). Deliberately NOT the grant's own per-instance
+   * `supervisor_dir` (`<stateDir>/<port>`), which holds epoch.json and would
+   * make backend-detect.mts's capability cache look in a directory that never
+   * has a record in it -- a silent permanent miss. Empty string disables the
+   * capability cache (every connect re-probes), matching
+   * backend-detect.mts's own documented degradation for an omitted
+   * supervisorDir. */
+  supervisorDir: string;
+}
+
 /** One in-flight request's settlement callback -- pushed onto the session's
  * FIFO pending queue in sendAndAwaitLine() below, and shifted off it by
  * EXACTLY ONE of: a response line arriving (createSession()'s own "data"
@@ -595,7 +736,23 @@ interface PendingLineEntry {
   handle(line: Record<string, unknown> | null, brokerGone: boolean): void;
 }
 
-type RawLineOutcome = { ok: true; line: Record<string, unknown> } | { ok: false; kind: ControlFailureKind; message: string };
+// `holder` is optional and populated ONLY when `kind` is "monitor_owned" --
+// every other failure kind leaves it undefined, matching broker-control.mts's
+// own error variant this outcome mirrors (plan 05: extends the existing
+// generic failure shape rather than a parallel channel for the one kind
+// that needs an extra field).
+type RawLineOutcome = { ok: true; line: Record<string, unknown> } | { ok: false; kind: ControlFailureKind; message: string; holder?: MonitorClaimHolder };
+
+/** 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 {
+  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 };
+}
 
 /** Builds the session object wrapping an already-CONNECTED socket. Wires the
  * newline framing (buffer, split on "\n", one entry-per-response FIFO
@@ -675,10 +832,16 @@ function createSession(socket: Socket, token: string): BrokerControlSession {
           }
           if (line.kind === "error") {
             const code = typeof line.code === "string" ? (line.code as ControlFailureKind) : "internal";
+            // 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;
             resolvePromise({
               ok: false,
               kind: code,
               message: typeof line.message === "string" ? line.message : "openBrokerControl: broker reported an error",
+              holder,
             });
             return;
           }
@@ -794,11 +957,74 @@ 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,
       },
     };
   }
 
-  return { acquire, release, recycle, status, hostState };
+  /** Claims exclusive ownership of `opts.targetId`'s monitor socket, sending
+   * `{ op: "monitor_claim", id, target_id, 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
+   * binmon port itself, on success OR on failure (plan 05, PROTO-08, D-13
+   * -- 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. */
+  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);
+    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
+      // `holder` payload is absent or malformed. This used to be
+      // `raw.kind === "monitor_owned" && raw.holder`, so a partially-malformed
+      // refusal collapsed to `{ ok: false, reason: "internal" }` -- stockConnect()
+      // then threw a generic ViceError, convertHandshakeError() produced "stock
+      // handshake failed (...)", and the ownership-conflict framing T-02-14
+      // 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.
+      if (raw.kind === "monitor_owned") {
+        return { ok: false, reason: "monitor_owned", holder: raw.holder ?? { grantId: "unknown", claimedAt: 0, pid: null } };
+      }
+      if (raw.kind === "unauthorized" || raw.kind === "bad_request" || raw.kind === "denied") return { ok: false, reason: raw.kind };
+      return { ok: false, reason: "internal" };
+    }
+    if (raw.line.kind !== "monitor_claimed") {
+      return { ok: false, reason: "internal" };
+    }
+    return { ok: true };
+  }
+
+  /** Releases a previously claimed monitor socket, sending
+   * `{ op: "monitor_release", id, target_id, 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. */
+  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);
+    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 };
+      return { ok: false, reason: "internal" };
+    }
+    if (raw.line.kind !== "monitor_released") {
+      return { ok: false, reason: "internal" };
+    }
+    return { ok: true };
+  }
+
+  return { acquire, release, recycle, status, hostState, claimMonitor, releaseMonitor };
 }
 
 /** Opens ONE session against the control plane: reads broker.json ONCE for

package/vice-proxy.ts

@@ -105,15 +105,16 @@ import { hostPath, SET_ENV_HINT } from "./hostpath.ts";
 // own host-local coordinates before useInstance() ever adopts them (this
 // task, quick-260801-ccn). Consuming this from the proxy -- rather than
 // hand-translating a host path here -- is what keeps the host-path consumer
-// set closed to a fixed, traced list (vice-mcp-selector-docs.test.mjs's
-// assertion 4, amended by this task to include containerpath.ts itself as
-// a fifth, sibling consumer of hostpath.mjs's own knowledge).
+// set closed to a fixed, traced list of exactly five production modules
+// (containerpath.ts, install-resources.ts, stock-paths.ts, vice-proxy.ts,
+// vice-sync.ts), pinned by hostpath-consumers.test.ts.
 import { containerizeRecord } from "./containerpath.ts";
 // The container-side half of the on-demand broker protocol (Phase 01.2).
 // This module deliberately does NOT import hostpath.mjs itself -- the
-// host-path consumer set stays closed to four production modules
-// (vice-mcp-selector-docs.test.mjs's assertion 4), and this file is already
-// on that list, so any broker-related host path text is built HERE.
+// host-path consumer set stays 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 this file is
+// already on that list, so any broker-related host path text is built HERE.
 // Tasks 1+2 (this plan) swap acquisition, release AND recycle onto the TCP
 // control session (openBrokerControl()/BrokerControlSession, plan 06's
 // completed client) -- writeRequest/createLease/touchLease/releaseLease/
@@ -133,6 +134,7 @@ import {
   type BrokerLivenessResult,
   type BrokerControlSession,
   type ControlFailureKind,
+  type HeldLease,
 } from "./vice-broker-client.ts";
 // The recycle path's own incident record (plan 01.3-01) -- written BEFORE
 // anything is killed (D-17), never through any network call of its own.
@@ -166,9 +168,24 @@ import type { StandardSchemaWithJSON } from "@mastra/core/schema";
 // A real, already-resolved transitive dependency of @mastra/mcp (Plan 01's
 // Task 2 note) -- deliberately NOT added to package.json directly.
 import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+// Plan 02-10: this file's own backend-detection and stock-dispatch consumer
+// edits. Both are namespace imports, deliberately -- keeps every reference to
+// their exported members's names down to the ONE call site each below (this
+// file's own grep-gated single-occurrence acceptance criteria), rather than a
+// named import whose binding is textually repeated at both the import line
+// and every call site.
+import * as backendDetect from "./backend-detect.mts";
+import * as stockDispatch from "./stock-dispatch.ts";
 
 const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 
+// D-01/BACK-01: the backend is settled exactly ONCE here, at module scope --
+// never re-settled per tool or per call. Every seam below (manifest
+// selection, the tools construction loop's dispatch choice, and the final
+// ready log line) reads THIS constant, never the raw environment variable
+// and never a second detection call.
+const ACTIVE_BACKEND = backendDetect.resolvedBackend();
+
 // -------------------------------------------------------------- JSON-RPC
 //
 // The boundary types every handler below reads or produces. `params` and
@@ -390,10 +407,13 @@ const DIAGNOSE_TOOL: ToolDefinition = {
   },
 };
 
+// Edit 1 (plan 02-10): delegates to stock-dispatch.ts's own selector function
+// -- the ONE manifest site this file keeps, now backend-aware. The existing
+// malformed-manifest fallbacks in readManifestTools() below are untouched: a
+// missing or unreadable stock manifest still answers tools/list with an
+// empty array rather than crashing the server.
 function manifestPath(): string {
-  return process.env.VICE_TOOLS_MANIFEST
-    ? resolve(process.env.VICE_TOOLS_MANIFEST)
-    : join(HERE_DIR, "tools-manifest.json");
+  return stockDispatch.manifestPathForBackend(ACTIVE_BACKEND.backend, HERE_DIR, process.env.VICE_TOOLS_MANIFEST);
 }
 
 function readManifestTools(): ToolInfo[] {
@@ -2131,11 +2151,56 @@ function containerizeGrant(grant: Record<string, unknown>): Record<string, unkno
  * that earlier decision needs to know it no longer applies, not that it was
  * quietly dropped.
  */
-type BrokerLeaseResult = { ok: true } | { ok: false; message: string };
+// Edit 2 (plan 02-10, D-13/PROTO-08): `ok: true` now carries a `lease:
+// HeldLease | null` -- `null` only for the VICE_MCP_URL override branch
+// below, where there is no broker control session to claim a monitor socket
+// through. Every failure branch is untouched.
+type BrokerLeaseResult = { ok: true; lease: HeldLease | null } | { ok: false; message: string };
+
+/**
+ * Builds the HeldLease a stock handler needs from state read FRESH on every
+ * call -- activeInstance() and grantId -- never memoised here:
+ * handleGrantedInstanceUnreachable() overwrites both on a replacement
+ * acquisition, and a cached lease would keep pointing at the retired
+ * instance. `host` is the hostname of the active instance's ALREADY
+ * containerized `url` (containerizeGrant()'s own loopback rewrite already
+ * owns host/container translation -- reading its result here is reuse, not
+ * re-derivation). `port` is activeInstance().port (the broker allocates one
+ * port per instance and passes it to -binarymonitoraddress on the stock
+ * backend, per plan 02-03). `targetId` is grantId -- the same value
+ * controlSession.recycle(grantId) already sends on the wire. Called only
+ * from the two success returns below that hold a control session.
+ */
+function buildHeldLease(session: BrokerControlSession): HeldLease {
+  const { url, port, epochFile } = activeInstance();
+  // WR-06: `new URL(url).hostname` returns a BRACKETED literal for IPv6
+  // ("[::1]"), which net.connect() will not accept -- so the brackets are
+  // stripped here, at the one place the dial host is derived, rather than by
+  // every eventual consumer. Deliberately not a general URL-parsing helper: the
+  // bracket form is the single documented WHATWG-URL quirk this seam meets.
+  const host = new URL(url).hostname.replace(/^\[(.+)\]$/, "$1");
+  // CR-06: `epochFile` and `supervisorDir` are what make the stock handshake's
+  // two BACK-04/reconnect mechanisms actually live on the real path -- before
+  // this, no production call ever passed StockConnectDeps, so `baselineEpoch`
+  // was always null (making stockReconnect() throw a FALSE
+  // MachineRestartedError on every transient drop) and the capability cache
+  // was never read or written.
+  //
+  // Two DIFFERENT directories, deliberately, and not interchangeable:
+  //   - epochFile is THIS instance's own `<stateDir>/<port>/epoch.json`, read
+  //     fresh from activeInstance() like every other field here (adoptGrant()
+  //     put the CONTAINERIZED path there, so it is already in this process's
+  //     view of the filesystem -- no second translation here).
+  //   - supervisorDir is the TOP-LEVEL `.vice-supervisor`, where backend.json
+  //     lives, resolved through brokerRootDir() -- the SAME resolver
+  //     broker.json is read from, never a locally re-derived path (the
+  //     "re-deriving a cross-cutting seam locally" anti-pattern).
+  return { host, port, targetId: grantId ?? "", brokerControl: session, epochFile, supervisorDir: brokerRootDir() };
+}
 
 async function ensureBrokerLease(): Promise<BrokerLeaseResult> {
-  if (controlSession) return { ok: true };
-  if (process.env.VICE_MCP_URL) return { ok: true }; // explicit override -- broker never contacted
+  if (controlSession) return { ok: true, lease: buildHeldLease(controlSession) };
+  if (process.env.VICE_MCP_URL) return { ok: true, lease: null }; // explicit override -- broker never contacted, nothing to claim a monitor socket through
 
   // Classify liveness FIRST, before ever opening a connection (C10).
   // never_started and stale both return their message immediately, with no
@@ -2184,6 +2249,57 @@ async function ensureBrokerLease(): Promise<BrokerLeaseResult> {
   }
   const session = opened.session;
 
+  // WR-04: the FIRST thing done on a freshly opened control session -- before an
+  // emulator is allocated -- is to ask the broker which backend IT resolved, and
+  // refuse if it disagrees with this process's own verdict.
+  //
+  // Why this check has to exist: `ACTIVE_BACKEND` is resolved at module scope
+  // from resolvedBackend(), against the CONTAINER's filesystem, with no
+  // supervisorDir and therefore no cache -- while the emulator it describes is
+  // launched by the broker on the HOST, from the broker's own independent
+  // resolvedBackend({ supervisorDir }). In the normal devcontainer topology the
+  // container has no x64sc at all, so the proxy classifies `unknown` and
+  // degrades to `{ backend: "fork", source: "indeterminate" }`. If the host
+  // binary is stock, the proxy would otherwise advertise the fork's full
+  // manifest and forward HTTP at a binary-monitor port -- and nothing would ever
+  // report the disagreement; it would surface as an inexplicable transport
+  // failure on the first real tool call. D-01's "one reader" property holds per
+  // PROCESS but not across this pair, and this is the seam where the pair first
+  // meets.
+  //
+  // Refusing (rather than adapting) is deliberate: the advertised tool list was
+  // already built at startup from ACTIVE_BACKEND and answered to the client, so
+  // this process cannot re-decide its own surface here. VICE_BACKEND remains the
+  // explicit fix, and it must be set for BOTH processes.
+  //
+  // Absent evidence is NOT disagreement: a broker that does not report a backend
+  // (older build, or an unrecognised value) leaves `backend: null`, and a
+  // hostState() call that fails at all is not allowed to block an acquire. Only
+  // a definite, named mismatch refuses.
+  const brokerState = await session.hostState();
+  if (brokerState.ok && brokerState.hostState.backend !== null && brokerState.hostState.backend !== ACTIVE_BACKEND.backend) {
+    const brokerBackend = brokerState.hostState.backend;
+    await session.release();
+    return {
+      ok: false,
+      message:
+        `vice: backend mismatch between this MCP server and the broker that owns the emulator. This process ` +
+        `resolved "${ACTIVE_BACKEND.backend}" (source: ${ACTIVE_BACKEND.source}, binary: ${ACTIVE_BACKEND.binPath}) while the ` +
+        `broker resolved "${brokerBackend}" (binary: ${brokerState.hostState.vice_bin}) -- and the broker's verdict is the ` +
+        `authoritative one, because it is what the emulator was actually launched with. The two backends speak ` +
+        `different protocols on that port, so proceeding would send ${ACTIVE_BACKEND.backend === "fork" ? "HTTP at a binary-monitor port" : "binary-monitor frames at an HTTP endpoint"}. ` +
+        `This normally means the MCP server runs where the emulator binary is not (a container), so its own detection ` +
+        `could not see it. Set VICE_BACKEND=${brokerBackend} for THIS process as well -- it must be set for both -- ` +
+        `and restart the MCP server so its advertised tool list matches.`,
+    };
+  }
+  if (!brokerState.ok) {
+    console.error(
+      `vice-proxy: could not read the broker's own backend verdict (${brokerState.kind}: ${brokerState.message}) -- ` +
+        `proceeding with this process's own verdict "${ACTIVE_BACKEND.backend}" (source: ${ACTIVE_BACKEND.source}); a mismatch, if any, will not be detected`,
+    );
+  }
+
   const result = await session.acquire();
   if (!result.ok) {
     // No grant is coming for this session -- nothing to hold the connection
@@ -2208,7 +2324,7 @@ async function ensureBrokerLease(): Promise<BrokerLeaseResult> {
   adoptGrant({ ...result.grant });
   viceSession = null; // re-baseline: the next ensureViceSession() reads the GRANTED instance's own epoch file
   controlSession = session;
-  return { ok: true };
+  return { ok: true, lease: buildHeldLease(session) };
 }
 
 /**
@@ -3006,14 +3122,74 @@ function buildViceTool(def: ToolDefinition, run: (args: Record<string, unknown>)
 // function runs at read time. A manifest hot-reload mid-session is
 // therefore no longer picked up until the proxy restarts; the manifest is
 // regenerated by a manual, rare build step, never mid-session in practice.
+// Edit 3 (plan 02-10, D-09): the runner each manifest tool's own execute()
+// closes over is chosen by ACTIVE_BACKEND, decided ONCE above, never
+// per-tool or per-call. The first ternary arm below is byte-identical to
+// every prior plan's own forwarding call, unchanged.
+// The second arm (the OTHER backend) passes ensureBrokerLease itself as the
+// injected LeaseProvider (no locally-built acquisition wrapping it -- there
+// is exactly one acquisition function in this file, and this arm calls the
+// SAME one the first arm's own lease check already calls), plus this file's
+// own already-settled binary path so the health-check tool on that path can
+// answer BACK-03 without ever re-detecting anything itself.
+/**
+ * The ONE backend-aware registration seam (D-09). CR-07 (code review
+ * 2026-08-13) is why it is a function rather than a ternary inlined in the
+ * manifest loop: the loop was backend-aware, but the three synthetic tools
+ * registered straight after it were NOT, and `tools/list` is served from this
+ * same object -- so on the stock backend the advertised surface was `vice_ping`
+ * PLUS `vice_result_continue`, `vice_recycle` and `vice_diagnose`, and two of
+ * those three ran the fork's HTTP transport against a port speaking the binary
+ * monitor. `handleDiagnose()` reaches ensureViceSession() /
+ * gatherCheckpointTrapEvidence() / gatherBracketEvidence(); `handleRecycle()`
+ * reaches gatherWedgeEvidence(). Both go through call()/forwardToVice(). That
+ * is a direct D-09 violation ("the stock path must never fall through to the
+ * fork's HTTP forward"), and `vice_diagnose` is the wedge-triage skill's
+ * documented opening move -- so its output on stock was HTTP failure text
+ * dressed as emulator diagnosis. The pre-existing structural test could not
+ * catch it: it only checked that no code LINE pairs the string "stock" with
+ * `forwardToVice`, which this arrangement satisfied while still reaching that
+ * transport.
+ *
+ * On the stock backend every tool registered through here is answered by
+ * dispatchStock -- which either has a table entry for the name or REFUSES BY
+ * NAME. There is no third path and no fall-through, which is D-09's whole
+ * point.
+ *
+ * WHAT NOT TO DO: never register a tool whose runner can reach `call()` /
+ * `forwardToVice()` / `ensureViceSession()` without going through this
+ * function. The one legitimate exception is a runner that touches no transport
+ * at all (`vice_result_continue`, which only reads this proxy's own
+ * CONTINUATION_STORE) -- and that exception is asserted, by name, in
+ * stock-dispatch.test.ts's structural section rather than left to judgement.
+ */
+function buildBackendAwareTool(def: ToolDefinition, forkRun: (args: Record<string, unknown>) => Promise<ToolCallResult>) {
+  return ACTIVE_BACKEND.backend === "fork"
+    ? buildViceTool(def, forkRun)
+    : buildViceTool(def, (args) =>
+        stockDispatch.dispatchStock(def.name, args, {
+          ensureLease: ensureBrokerLease,
+          resolvedBinaryPath: ACTIVE_BACKEND.binPath,
+          resolvedBinaryPathIsResolved: ACTIVE_BACKEND.binPathResolved,
+        }),
+      );
+}
+
 const tools: Record<string, ReturnType<typeof buildViceTool>> = {};
 for (const def of readManifestTools()) {
   if (DENY_LIST.includes(def.name)) continue;
-  tools[def.name] = buildViceTool(def, (args) => forwardToVice(def.name, args));
+  tools[def.name] = buildBackendAwareTool(def, (args) => forwardToVice(def.name, args));
 }
+// Backend-INDEPENDENT by construction: handleResultContinue() is served
+// entirely from this proxy's own CONTINUATION_STORE and opens no socket of any
+// kind, so it is correct on either backend and is deliberately NOT routed
+// through dispatchStock (which would refuse the continuation mechanism itself).
 tools[RESULT_CONTINUE_TOOL.name] = buildViceTool(RESULT_CONTINUE_TOOL, (args) => Promise.resolve(handleResultContinue(args)));
-tools[RECYCLE_TOOL.name] = buildViceTool(RECYCLE_TOOL, (args) => handleRecycle(args));
-tools[DIAGNOSE_TOOL.name] = buildViceTool(DIAGNOSE_TOOL, (args) => handleDiagnose(args));
+// Backend-AWARE (CR-07): both of these gather evidence over the fork's HTTP
+// transport, so on stock they are refused by name rather than advertised and
+// then failed at the wire.
+tools[RECYCLE_TOOL.name] = buildBackendAwareTool(RECYCLE_TOOL, (args) => handleRecycle(args));
+tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(DIAGNOSE_TOOL, (args) => handleDiagnose(args));
 
 const server = new MCPServer({ name: "vice", version: PROXY_VERSION, tools });
 await server.startStdio();
@@ -3090,4 +3266,13 @@ server.getServer().setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-console.error(`vice-proxy: ready, forwarding to ${activeInstance().url} (port ${activeInstance().port})`);
+// Log-line correction (plan 02-10): the fork arm is byte-identical to every
+// prior plan. The stock arm cannot yet name a real instance/port -- no
+// acquisition has happened at process startup, only lazily on the first
+// tools/call -- so it names the backend and the binary-monitor target
+// instead of a coordinate pair that does not exist yet.
+console.error(
+  ACTIVE_BACKEND.backend === "fork"
+    ? `vice-proxy: ready, forwarding to ${activeInstance().url} (port ${activeInstance().port})`
+    : `vice-proxy: ready, stock backend active -- dispatching to a broker-claimed binary-monitor instance (resolved binary: ${ACTIVE_BACKEND.binPath})`,
+);