create-walle 0.10.0 → 0.10.2

package/template/coding-task-manager/lib/remote-machine-link.js

@@ -0,0 +1,939 @@
+'use strict';
+
+// WP-3 (docs/remote-machine-hub-sessions-2026-10-22.html §6.4, §7, §8 AC-3a..3d, §9 S-22/S-23/S-24):
+// the hub-side LIVE PLANE relay.
+//
+// A remote session (created through lib/remote-machine-create.js — WP-2) lives IN THE BOX's
+// process. It is deliberately NOT an entry in this process's `sessions` Map (OQ-4: ~16 list/attach
+// `.ptyProcess` dereferences is more than merging is worth), so every frame the hub's browser sends
+// about it — a keystroke, a prompt, an approval verdict, a resize — must be carried to the box and
+// every frame the box produces must be carried back. This module owns that carry:
+//
+//   LINK        one upstream WS per machine, lazy, opened on the first viewed session and closed
+//               after IDLE_CLOSE_MS with no viewers. `listLinks().length <= 1` per machine by
+//               construction (a Map keyed by the machine's minted instance id).
+//   INTERCEPT   the single dispatch seam (lib/ws-router.js's pre-dispatch hook, consulted at
+//               `dispatchWs` before ANY local handler). A message naming a MIRROR session is
+//               diverted here; a message naming a local session returns false immediately and takes
+//               the byte-identical existing path (S-22, and the brief's "local sessions must take
+//               the byte-identical existing path").
+//   FORWARD     hub browser -> box, VERBATIM. `clientMessageId` (S-24) and every other id is the
+//               ORIGINAL one the browser minted — this module never re-mints an idempotency key.
+//   FAN-OUT     box -> every hub browser socket viewing that session (S-22). Reply frames
+//               (submit-prompt-status, approval-resolution-result, model-change-result, parked,
+//               killed, …) go to the ORIGINATING hub socket ONLY, matched by the original
+//               `clientMessageId` when the frame carries one.
+//   RECONNECT   full-jitter backoff 500 ms -> 30 s cap, reset on success; on every (re)connect the
+//               link re-attaches every viewed session and issues `keyframe-req`, so the box's own
+//               seq/keyframe authority is what re-syncs content (no duplicate/no gap by design).
+//   PINGS       two consecutive missed WS pings force a reconnect (the link owns its own liveness —
+//               the peer-control allowlist deliberately has no CTM `ping` message).
+//
+// BACKPRESSURE (§10 risk 2), the choice this module makes: the box sees exactly ONE attached
+// client — the link — so its credit/window is the LINK's, not any single hub browser's. Fan-out to
+// hub sockets is a local, unconditional, non-blocking send per socket, so a slow/stalled hub viewer
+// can never stall the frames the OTHER viewers of the same session receive; the hub socket acks
+// (`ack`/`nack`/`frame-receipt`) are forwarded upstream VERBATIM, per session, which is the credit
+// signal the box already understands (lib/ws/state-sync.js keys acks by session). Nothing is
+// re-minted, no local credit is invented.
+//
+// No durable state (lead ruling 4): links and viewer refcounts are in-memory and rebuilt lazily
+// from viewed sessions after a hub restart. Everything is injectable for tests.
+
+const { registerWsPreDispatchHook } = require('./ws-router');
+const remoteMachineCreate = require('./remote-machine-create');
+
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 30000;
+const IDLE_CLOSE_MS = 60000;
+const PING_MISS_LIMIT = 2;
+const HEARTBEAT_MS = 15000;
+
+// Message types a hub browser sends that name a session and therefore may be relayed upstream.
+// Deliberately a closed set: a type nobody classified is NOT relayed (it falls through to the
+// local handler, which is the pre-WP-3 behaviour for a session it does not know).
+const RELAY_TYPES = Object.freeze(new Set([
+  // viewing / resync (S-22)
+  // WP-3b: `terminal-bootstrap-ack` is the matched pair of `terminal-bootstrap` (the viewer's
+  // receipt of the cold bootstrap) — both cross the hop, so both are relayed.
+  'attach', 'view', 'keyframe-req', 'snapshot', 'terminal-bootstrap', 'terminal-bootstrap-ack', 'wake-resync',
+  // typing + geometry
+  'input', 'resize', 'reflow', 'reconcile', 'flow', 'detach', 'interrupt-session',
+  // prompts + approvals + model (S-23/S-24). `image-deliver-now` is WP-3 of
+  // docs/remote-session-image-upload-forwarding-2026-10-24.html §6: the viewer asks the BOX that
+  // owns the session to deliver the already-uploaded draft, so the frame must cross the hop.
+  // WP-1 (docs/remote-resume-choice-click-2026-10-25.html §5 D-1, §9 S-1): `resume-prompt-select`
+  // is the resume strip's choice chip. A mirror id must reach the BOX that owns the session —
+  // otherwise the hub's LOCAL handler rejects the click
+  // (`resume-prompt-rejected {reason:'session_not_found',channel:'choice'}`).
+  'submit-prompt', 'approval-resolve', 'model-change', 'image-deliver-now',
+  'resume-prompt-select',
+  // lifecycle (WP-6 routes the hub UI here; the relay just carries them)
+  'park', 'wake', 'kill',
+  // delivery credit (lib/ws/state-sync.js keys these by session)
+  'ack', 'nack', 'frame-receipt',
+]));
+
+// The subset that means "this socket is viewing the session" — the first viewer of a session
+// triggers the upstream attach + keyframe-req.
+const VIEW_TYPES = Object.freeze(new Set([
+  'attach', 'view', 'keyframe-req', 'snapshot', 'terminal-bootstrap', 'wake-resync',
+]));
+
+// Downstream types that are a REPLY to one specific request, so they are delivered to the
+// originating hub socket only (never fanned out to co-viewers).
+//
+// WP-6 fix: this set lists the frame types the BOX ACTUALLY SENDS back for a relayed request. The
+// pre-WP-6 set named `parked`, `killed` and `wake-result`, which do not exist anywhere in the box's
+// code — so a box's park/wake reply was fanned out to every co-viewer of the session instead of
+// being routed to the socket that asked. The real answers are:
+//   park / pin / wake        -> lib/ws/lifecycle.js `session-lifecycle-result` (+ `action`)
+//   interrupt-session        -> lib/ws/input.js        `session-interrupt-result`
+//   resume-prompt-select     -> lib/ws/input.js        `resume-prompt-result`
+//   kill                     -> a BROADCAST `exit` frame (server.js handleKill), which is NOT a
+//                               reply: every viewer must see it, so it is deliberately absent here
+//                               and fans out.
+// tests/remote-machine-link.test.js pins this set against the `type:` literals the box's own
+// handlers emit, so a renamed reply type fails the test instead of silently fanning out.
+const REPLY_TYPES = Object.freeze(new Set([
+  'submit-prompt-status',
+  'approval-resolution-result',
+  'model-change-result',
+  'session-lifecycle-result',
+  'session-interrupt-result',
+  'resume-prompt-result',
+  'request-error',
+  'error',
+]));
+
+// Requests whose reply (or auth-error verdict) is routed back to the originating socket. `input`
+// is deliberately absent: a keystroke has no reply, and remembering every one would evict the
+// pending prompt/approval entries from the bounded map below.
+// WP-1 (docs/remote-resume-choice-click-2026-10-25.html §5 D-3, §9 S-2): `resume-prompt-select`
+// is remembered so its `resume-prompt-result` (which echoes the browser's `requestId`) can be
+// routed to the socket that asked instead of being fanned out to every co-viewer.
+const REMEMBER_TYPES = Object.freeze(new Set([
+  'submit-prompt', 'approval-resolve', 'model-change', 'park', 'wake', 'kill', 'interrupt-session',
+  'resume-prompt-select',
+]));
+const PENDING_TTL_MS = 60000;
+const PENDING_MAX = 512;
+// Bounded queue of frames sent to a link that is still dialing (see forward()):
+const PENDING_SEND_MAX = 64;
+
+// WP-6: the request -> reply-type pairs the box's handlers really implement (see REPLY_TYPES).
+const REPLY_FOR_REQUEST = Object.freeze({
+  'submit-prompt': 'submit-prompt-status',
+  'approval-resolve': 'approval-resolution-result',
+  'model-change': 'model-change-result',
+  'park': 'session-lifecycle-result',
+  'wake': 'session-lifecycle-result',
+  'interrupt-session': 'session-interrupt-result',
+  'resume-prompt-select': 'resume-prompt-result',
+});
+
+// WP-6: how long a catalog `list` request waits for the box's `sessions` reply before giving up.
+const CATALOG_TIMEOUT_MS = 5000;
+
+let _injected = null;
+let _uninstallIntercept = null;
+let _productionCache = null;
+
+/** Test/host seam: override any production dependency (registry, WebSocket, timers, clock, log). */
+function configure(deps) {
+  _injected = deps && typeof deps === 'object' ? deps : null;
+}
+
+function _string(value, max = 200) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Dependencies (lazy: a pure unit test must never load db.js / machine-registry)
+// ---------------------------------------------------------------------------------------------
+
+function _defaultMachineRow(machineId, deps) {
+  const registry = require('./machine-registry');
+  const db = require('../db-owner-client');
+  const listed = registry.listMachines({ db }) || {};
+  const machines = Array.isArray(listed.machines) ? listed.machines : [];
+  return machines.find((row) => _string(row.instanceId, 160) === _string(machineId, 160)) || null;
+}
+
+function _productionDeps() {
+  return {
+    env: process.env,
+    now: () => Date.now(),
+    random: Math.random,
+    setTimeoutFn: global.setTimeout,
+    clearTimeoutFn: global.clearTimeout,
+    setIntervalFn: global.setInterval,
+    clearIntervalFn: global.clearInterval,
+    // The machine ROW (url/enabled/health) for a registered machine — resolved through the same
+    // registry read the routes and WP-2's forward use.
+    machineRow: _defaultMachineRow,
+    // Which machine owns a ctm session id (lib/remote-machine-create.js's mirror registry, which
+    // WP-6 widened to the union over the live catalog and the at-rest sync mirror rows).
+    mirrorFor: (sessionId) => remoteMachineCreate.getMirrorSessionMachine(sessionId),
+    // WP-6 catalog lane. The hooks are lazy `require`s and the catalog never requires THIS module
+    // back (it takes the link as a peer wired by server.js), so the lib/** graph stays acyclic.
+    onLinkReady: (link) => { try { require('./remote-machine-catalog').onLinkReady(link); } catch { /* expected: a catalog fault must never break the link */ } },
+    onSessionList: (link, rows, frame) => { try { require('./remote-machine-catalog').recordSessionList(link.machineInstanceId, rows); } catch { /* expected: ditto — the box's list is a freshness bonus, not a link obligation */ } },
+    onRelayedKill: (link) => { try { require('./remote-machine-catalog').fetchCatalog(link.machineInstanceId); } catch { /* expected: ditto — the kill already crossed; the refresh is best effort */ } },
+    catalogTimeoutMs: CATALOG_TIMEOUT_MS,
+    log: console,
+    idleCloseMs: IDLE_CLOSE_MS,
+    heartbeatMs: HEARTBEAT_MS,
+    backoffBaseMs: BACKOFF_BASE_MS,
+    backoffCapMs: BACKOFF_CAP_MS,
+  };
+}
+
+function _d(overrides) {
+  // The production dependency object is PURE (constants + closures, no per-call state), and it is
+  // built on the hot path: `interceptRelay` runs for every relayable frame of every LOCAL session
+  // too (a keystroke, a resize, a frame-receipt), so re-assembling 14 properties per message would
+  // tax exactly the typing lane this module must not slow down. Memoized once; a caller that passes
+  // its own deps still gets a private merged object.
+  if (!_productionCache) _productionCache = _productionDeps();
+  if (!_injected && !overrides) return _productionCache;
+  return Object.assign({}, _productionCache, _injected || {}, overrides || {});
+}
+
+// ---------------------------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * The session id a frame names. `view` is the one set-declaring type (D-1), so it yields every id
+ * it declares; every other type yields its single `id` (or `sessionId`, the spelling a few frames
+ * use).
+ */
+function sessionIdsOf(msg) {
+  if (!msg || typeof msg !== 'object') return [];
+  if (msg.type === 'view') {
+    const ids = Array.isArray(msg.ids) ? msg.ids : [];
+    const out = [];
+    for (const raw of ids.slice(0, 64)) {
+      const id = _string(raw, 200);
+      if (id && !out.includes(id)) out.push(id);
+    }
+    return out;
+  }
+  const id = _string(msg.id || msg.sessionId, 200);
+  return id ? [id] : [];
+}
+
+function _frameSessionId(frame) {
+  if (!frame || typeof frame !== 'object') return '';
+  return _string(frame.id || frame.sessionId, 200);
+}
+
+/** Deliver an already-serialized frame to one hub browser socket (fan-out or reply routing). */
+function _sendToCtx(ctx, payload) {
+  try {
+    if (ctx && ctx.ws && ctx.ws.readyState === 1 && typeof ctx.send === 'function') ctx.send(payload);
+  } catch {
+    // expected: the hub browser socket died while a relayed frame was in flight — the box owns the
+    // session and WP-5's UI re-subscribes on the next connect.
+  }
+}
+
+function _sendFrame(ctx, frame) {
+  _sendToCtx(ctx, JSON.stringify(frame));
+}
+
+// ---------------------------------------------------------------------------------------------
+// Links
+// ---------------------------------------------------------------------------------------------
+
+const _links = new Map(); // machineInstanceId -> link
+
+function _newLink(machineId, machineName, url) {
+  return {
+    machineInstanceId: machineId,
+    machineName,
+    url,
+    socket: null,
+    ready: false,
+    closed: false,
+    dialing: false,
+    // WP-1 (D-3): 'idle' | 'credential_missing'. The latter is terminal — the link stays usable
+    // in-memory (no socket, no timers) and only an explicit openLink on a hub whose env now
+    // carries the token dials again.
+    state: 'idle',
+    attempts: 0,
+    generation: 0,
+    pingMisses: 0,
+    heartbeatTimer: null,
+    reconnectTimer: null,
+    idleTimer: null,
+    viewers: new Map(), // sessionId -> Set<ctx>
+    pending: new Map(), // key -> {ctx, replyType, at}
+    pendingSeq: 0,
+    pendingSends: [], // frames sent while the link was still dialing (flushed on hello)
+    // WP-6 catalog lane: the box's `sessions` reply to a `list` request. `catalogUsers` is the
+    // refcount of catalog-initiated users — it holds the 60 s idle close off while a request is in
+    // flight and is released the moment the reply lands, so a catalog fetch never keeps a machine
+    // link open.
+    catalogWaiters: new Map(), // seq -> finish(result)
+    catalogSeq: 0,
+    catalogUsers: 0,
+    lastSessions: null, // {rows, frame, at} — the most recent list the box sent this link
+  };
+}
+
+function linkFor(machineId) {
+  return _links.get(_string(machineId, 160)) || null;
+}
+
+function listLinks() {
+  return [..._links.values()];
+}
+
+/**
+ * Open (or reuse) the one link to a machine. `machine` is a registry row or a machine instance id.
+ * Never throws: a machine that is not registered / disabled / url-less yields null and the caller
+ * degrades to the existing "no frames" UX.
+ */
+function openLink(machine, deps) {
+  const d = _d(deps);
+  const row = typeof machine === 'string' ? d.machineRow(_string(machine, 160), d) : machine;
+  if (!row) return null;
+  const machineId = _string(row.instanceId, 160);
+  if (!machineId) return null;
+  const existing = _links.get(machineId);
+  if (existing && !existing.closed) {
+    // D-3: a link parked on a missing credential is retried by the NEXT acquire — that is the
+    // "hub restarted with CTM_SYNC_PEER_TOKEN set" path, and it is the only thing that can clear
+    // the state, because nothing here polls. The state is deliberately NOT reset first: `_dial`
+    // reads `credential_missing` as "already reported", so a hub that still has no credential
+    // re-dials on each acquire without logging the same line again (and a successful dial clears it).
+    if (existing.state === 'credential_missing') _dial(existing, d);
+    return existing;
+  }
+  if (!row.enabled) return null;
+  const url = _string(row.url, 1000);
+  if (!url) return null;
+  if (_string(row.health, 40) === 'unreachable') return null;
+  const link = _newLink(machineId, _string(row.displayName, 200), url);
+  _links.set(machineId, link);
+  _dial(link, d);
+  return link;
+}
+
+function _dial(link, d) {
+  if (link.closed || link.dialing || link.ready) return;
+  link.dialing = true;
+  const dial = remoteMachineCreate.preparePeerDial(link.url, { ...d, machineName: link.machineName });
+  if (!dial.ok) {
+    link.dialing = false;
+    // WP-1 (D-3): a missing peer credential is a CONFIGURATION error, not a transient one. The
+    // token is read from process.env on every call and env changes only on restart, so a retry
+    // would fail identically forever — one report, then a terminal state, no reconnect timer.
+    // `openLink` re-dials from that state, which is what a hub restarted WITH the credential needs.
+    if (dial.code === remoteMachineCreate.PEER_CREDENTIAL_MISSING) {
+      if (link.state !== 'credential_missing') {
+        link.state = 'credential_missing';
+        _report(d, `link ${link.machineInstanceId}: ${dial.error}`);
+      }
+      return;
+    }
+    _report(d, `link ${link.machineInstanceId}: ${dial.error}`);
+    _scheduleReconnect(link, d);
+    return;
+  }
+  link.state = 'idle';
+  const generation = link.generation + 1;
+  link.generation = generation;
+  let socket = null;
+  try {
+    socket = new dial.WebSocketImpl(dial.url, { headers: dial.headers });
+  } catch (error) {
+    link.dialing = false;
+    _report(d, `link ${link.machineInstanceId}: connect failed: ${error?.message || error}`);
+    _scheduleReconnect(link, d);
+    return;
+  }
+  link.socket = socket;
+  const isCurrent = () => link.generation === generation && !link.closed;
+  socket.on('message', (raw) => { if (isCurrent()) _onUpstreamFrame(link, raw, d); });
+  socket.on('pong', () => { if (isCurrent()) link.pingMisses = 0; });
+  socket.on('error', (error) => { if (isCurrent()) _report(d, `link ${link.machineInstanceId}: socket error: ${error?.message || error}`); });
+  socket.on('close', () => { if (isCurrent()) _onSocketGone(link, d); });
+}
+
+function _onSocketGone(link, d) {
+  link.socket = null;
+  link.ready = false;
+  link.dialing = false;
+  _stopHeartbeat(link, d);
+  if (link.closed) return;
+  _scheduleReconnect(link, d);
+}
+
+/** Full-jitter backoff: `random() * min(cap, base * 2^attempt)`. */
+function backoffDelayMs(attempt, d) {
+  const base = Number(d?.backoffBaseMs || BACKOFF_BASE_MS) || BACKOFF_BASE_MS;
+  const cap = Number(d?.backoffCapMs || BACKOFF_CAP_MS) || BACKOFF_CAP_MS;
+  const ceiling = Math.min(cap, base * (2 ** Math.max(0, attempt)));
+  const random = typeof d?.random === 'function' ? d.random : Math.random;
+  return Math.max(0, Math.floor(random() * ceiling));
+}
+
+function _scheduleReconnect(link, d) {
+  if (link.closed || link.reconnectTimer) return;
+  const delay = backoffDelayMs(link.attempts, d);
+  link.attempts += 1;
+  const timer = d.setTimeoutFn(() => {
+    link.reconnectTimer = null;
+    if (!link.closed) _dial(link, d);
+  }, delay);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  link.reconnectTimer = timer;
+}
+
+function _startHeartbeat(link, d) {
+  _stopHeartbeat(link, d);
+  const every = Number(d.heartbeatMs || HEARTBEAT_MS) || HEARTBEAT_MS;
+  const timer = d.setIntervalFn(() => heartbeatTick(link, d), every);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  link.heartbeatTimer = timer;
+}
+
+function _stopHeartbeat(link, d) {
+  if (link.heartbeatTimer) {
+    try { d.clearIntervalFn(link.heartbeatTimer); } catch { /* expected: the injected interval is already cleared */ }
+    link.heartbeatTimer = null;
+  }
+}
+
+/**
+ * One liveness tick. Exposed (and driven by the injected interval) so a test can prove the
+ * "two missed pings -> reconnect" rule with mock timers and no real sleep.
+ */
+function heartbeatTick(link, deps) {
+  const d = _d(deps);
+  if (link.closed || !link.ready || !link.socket) return;
+  if (link.pingMisses >= PING_MISS_LIMIT) {
+    _report(d, `link ${link.machineInstanceId}: ${link.pingMisses} missed pings — reconnecting`);
+    _forceReconnect(link, d);
+    return;
+  }
+  link.pingMisses += 1;
+  try { link.socket.ping?.(); } catch { /* expected: the socket died between the ready check and the ping */ }
+}
+
+function _forceReconnect(link, d) {
+  const socket = link.socket;
+  // Bump the generation FIRST: the close/error handlers of the socket we are abandoning must not
+  // schedule a second reconnect for the same dead connection.
+  link.generation += 1;
+  link.socket = null;
+  link.ready = false;
+  link.dialing = false;
+  _stopHeartbeat(link, d);
+  try { socket?.terminate?.(); } catch { /* expected: the abandoned socket is already gone */ }
+  if (!link.closed) _scheduleReconnect(link, d);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Upstream (box -> hub)
+// ---------------------------------------------------------------------------------------------
+
+function _onUpstreamFrame(link, raw, d) {
+  let frame = null;
+  try {
+    frame = JSON.parse(raw.toString());
+  } catch {
+    return; // expected: a binary/non-JSON frame on this lane is not a relayable protocol frame
+  }
+  if (!frame || typeof frame !== 'object') return;
+
+  if (frame.type === 'hello') {
+    _onHello(link, frame, d);
+    return;
+  }
+  if (frame.type === 'sessions') {
+    // WP-6: the box's session list — the reply to our catalog `list` request, and also a frame the
+    // box BROADCASTS on every session-list change (server.js handleList / the list broadcast). It
+    // names no single session, so it is recorded for the catalog and settled to any waiter; it is
+    // never fanned out to a hub browser (the hub builds its own list).
+    _deliverSessionList(link, frame, d);
+    return;
+  }
+  if (frame.type === 'terminal-protocol-incompatible') {
+    _report(d, `link ${link.machineInstanceId}: box refused the protocol: ${_string(frame.reason, 80)}`);
+    _forceReconnect(link, d);
+    return;
+  }
+  if (frame.type === 'auth-error') {
+    // The box answers a peer's client-info with `auth-error insufficient_scope` (ws build
+    // compatibility runs before the peer-control rule table) — routine noise on this lane,
+    // tolerated exactly as WP-2's dial tolerates it. A verdict that NAMES a relayed message type
+    // is the box refusing THAT frame, so it is reported to the socket that sent it instead of
+    // being swallowed (a silent refusal is indistinguishable from a broken relay).
+    _routeAuthError(link, frame);
+    return;
+  }
+
+  const sessionId = _frameSessionId(frame);
+  if (!sessionId) return;
+  if (_routeReplyToOrigin(link, frame, sessionId, d)) return;
+  _fanout(link, frame, sessionId, d);
+}
+
+/**
+ * The box's own handshake. Both the client-info AND the re-attach of every viewed session must
+ * follow it, in that order: the box's protocol gate drops a terminal-protocol frame that arrives
+ * before a compatible client-info (see lib/remote-machine-create.js's dial-order note).
+ */
+function _onHello(link, frame, d) {
+  const alreadyReady = link.ready;
+  link.ready = true;
+  link.dialing = false;
+  link.attempts = 0; // backoff resets ON SUCCESS (full-jitter contract)
+  _sendUpstream(link, remoteMachineCreate.peerClientInfoFrame(frame), d);
+  // Re-attach AFTER the client-info above: the box's protocol gate drops a terminal-protocol frame
+  // that arrives before a compatible client-info (the dial-order rule the create lane learned).
+  link.pingMisses = 0;
+  _startHeartbeat(link, d);
+  for (const sessionId of link.viewers.keys()) _attachUpstream(link, sessionId, d, alreadyReady ? 'link-reconnect' : 'link-ready');
+  // WP-6: a catalog `list` requested while the link was still dialing is flushed HERE, after the
+  // client-info above — the box's protocol gate drops a terminal-protocol frame that arrives first.
+  for (const queued of link.pendingSends.splice(0)) _sendUpstream(link, queued, d);
+  // A catalog request that was queued while this link was dialing sends its `list` HERE, so this
+  // hello has already asked the box for its list — skip the refresh hook below rather than paying a
+  // second identical round-trip on the same connection.
+  const catalogAsked = link.catalogWaiters.size > 0;
+  for (const finish of [...link.catalogWaiters.values()]) _sendCatalogList(link, finish, d);
+  // WP-6 §8: "on link (re)connect" is one of the catalog's refresh triggers. Injected (not
+  // required) so this module never has to depend on the catalog module it feeds.
+  if (!catalogAsked && typeof d.onLinkReady === 'function') {
+    try { d.onLinkReady(link); } catch { /* expected: a catalog hook fault must not break the link */ }
+  }
+}
+
+function _sendCatalogList(link, finish, d) {
+  if (!_sendUpstream(link, { type: 'list' }, d)) {
+    finish({ ok: false, code: 'machine_unreachable', error: 'catalog_send_failed' });
+  }
+}
+
+function _deliverSessionList(link, frame, d) {
+  const rows = Array.isArray(frame.sessions) ? frame.sessions : [];
+  link.lastSessions = { rows, frame, at: d.now ? d.now() : Date.now() };
+  if (typeof d.onSessionList === 'function') {
+    try { d.onSessionList(link, rows, frame); } catch { /* expected: a catalog hook fault must not break the link */ }
+  }
+  for (const finish of [...link.catalogWaiters.values()]) finish({ ok: true, rows, frame });
+}
+
+/**
+ * WP-6 (§6.6/AC-6a): ask the box for its session list over this link. One link user for the
+ * duration of the request, released on the reply — so the 60 s idle close still applies to a
+ * catalog-only link and the hub never accumulates a permanently open connection per machine.
+ *
+ * @returns {Promise<{ok: true, rows: Array, frame: object}|{ok: false, code: string, error: string}>}
+ */
+function requestSessionList(link, deps = {}) {
+  return new Promise((resolve) => {
+    const d = _d(deps);
+    if (!link || link.closed) return resolve({ ok: false, code: 'machine_unreachable', error: 'link_closed' });
+    const timeoutMs = Number(d.catalogTimeoutMs || CATALOG_TIMEOUT_MS) || CATALOG_TIMEOUT_MS;
+    const seq = ++link.catalogSeq;
+    let done = false;
+    let timer = null;
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      if (timer) { try { d.clearTimeoutFn(timer); } catch { /* expected: the injected timer already fired */ } }
+      link.catalogWaiters.delete(seq);
+      _releaseCatalogUser(link, d);
+      resolve(result);
+    };
+    link.catalogWaiters.set(seq, finish);
+    _holdCatalogUser(link, d);
+    timer = d.setTimeoutFn(() => finish({ ok: false, code: 'machine_unreachable', error: 'catalog_timeout' }), timeoutMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+    if (link.ready) _sendCatalogList(link, finish, d);
+  });
+}
+
+function _holdCatalogUser(link, d) {
+  link.catalogUsers = (Number(link.catalogUsers) || 0) + 1;
+  _clearIdleClose(link, d);
+}
+
+function _releaseCatalogUser(link, d) {
+  link.catalogUsers = Math.max(0, (Number(link.catalogUsers) || 0) - 1);
+  _maybeScheduleIdleClose(link, d);
+}
+
+function _attachUpstream(link, sessionId, d, reason) {
+  const sentAttach = _sendUpstream(link, { type: 'attach', id: sessionId }, d);
+  const sentKeyframe = _sendUpstream(link, {
+    type: 'keyframe-req', id: sessionId, requestToken: `hub-link-${sessionId}`, reason: _string(reason, 48) || 'hub-link',
+  }, d);
+  return sentAttach && sentKeyframe;
+}
+
+/** The ONE raw send site for this module's upstream lane (the peer socket, not a hub browser). */
+function _sendUpstream(link, frame, d) {
+  if (!link || !link.socket || !link.ready) return false;
+  try {
+    link.socket.send(JSON.stringify(frame));
+    return true;
+  } catch (error) {
+    _report(d, `link ${link.machineInstanceId}: send failed: ${error?.message || error}`);
+    return false;
+  }
+}
+
+function _pendingKey(sessionId, frame) {
+  const cm = _string(frame && frame.clientMessageId, 200);
+  return cm ? `${sessionId}\u0000cm:${cm}` : '';
+}
+
+function _rememberPending(link, sessionId, msg, ctx, d) {
+  if (!REMEMBER_TYPES.has(msg.type)) return;
+  const now = d.now();
+  // Bounded by construction: a keystroke stream cannot grow this map without bound.
+  for (const [key, entry] of link.pending) {
+    if (now - entry.at > PENDING_TTL_MS) link.pending.delete(key);
+  }
+  while (link.pending.size >= PENDING_MAX) {
+    const oldest = link.pending.keys().next();
+    if (oldest.done) break;
+    link.pending.delete(oldest.value);
+  }
+  const clientMessageId = _string(msg.clientMessageId, 200);
+  // WP-1 (docs/remote-resume-choice-click-2026-10-25.html §5 D-3, §6): the browser mints a
+  // `requestId` for a resume choice and the box echoes it back; keeping it on the pending entry is
+  // what lets two concurrent viewers' results be told apart (a requestId-less request stores '').
+  const requestId = _string(msg.requestId, 200);
+  const key = _pendingKey(sessionId, msg) || `${sessionId}\u0000seq:${++link.pendingSeq}`;
+  link.pending.set(key, {
+    ctx, replyType: REPLY_FOR_REQUEST[msg.type] || '', requestType: msg.type, clientMessageId, requestId, at: now, sessionId,
+  });
+}
+
+function _takePending(link, match) {
+  for (const [key, entry] of link.pending) {
+    if (match(entry)) {
+      link.pending.delete(key);
+      return entry;
+    }
+  }
+  return null;
+}
+
+/**
+ * The box's `auth-error` verdict on a relayed frame names the message type it refused (the §6.2
+ * peer-control allowlist is a closed set, so a relayed type it does not contain is refused here).
+ * Deliver it to the originating socket; the routine verdict on our own client-info carries no
+ * `messageType` and stays noise.
+ */
+function _routeAuthError(link, frame) {
+  const messageType = _string(frame.messageType, 40);
+  if (!messageType) return;
+  const entry = _takePending(link, (e) => e.requestType === messageType);
+  if (entry) _sendFrame(entry.ctx, frame);
+}
+
+/**
+ * Route a reply frame to the ORIGINATING hub socket only (S-22): matched by the ORIGINAL
+ * `clientMessageId` first (S-24 — the id the browser minted, forwarded verbatim), then by the
+ * request/response type pair.
+ */
+function _routeReplyToOrigin(link, frame, sessionId, d) {
+  if (!REPLY_TYPES.has(frame.type)) return false;
+  // WP-1 (docs/remote-resume-choice-click-2026-10-25.html §5 D-3, §6, RFC 8887 §4.3.2): a resume
+  // choice result is correlated by the `requestId` the browser minted and the box echoed — never by
+  // "oldest pending entry of this reply type" — because two viewers of ONE mirror session can have
+  // their choices in flight at once and the box may complete them out of order. An identified result
+  // that matches no pending request belongs to nobody: it is CONSUMED here (`return true`) so
+  // `_onUpstreamFrame` never fans it out to co-viewers who did not ask for it.
+  if (frame.type === 'resume-prompt-result') {
+    const requestId = _string(frame.requestId, 200);
+    if (requestId) {
+      const entry = _takePending(link, (e) => e.sessionId === sessionId
+        && e.replyType === frame.type && e.requestId === requestId);
+      if (entry) _sendFrame(entry.ctx, frame);
+      return true;
+    }
+    // A result carrying no requestId keeps the legacy clientMessageId/type fallback below.
+  }
+  const clientMessageId = _string(frame.clientMessageId, 200);
+  const entry = (clientMessageId
+    ? _takePending(link, (e) => e.sessionId === sessionId && e.clientMessageId === clientMessageId)
+    : null)
+    || _takePending(link, (e) => e.sessionId === sessionId && e.replyType === frame.type);
+  if (!entry) return false;
+  _sendFrame(entry.ctx, frame);
+  return true;
+}
+
+function _fanout(link, frame, sessionId, d) {
+  const viewers = link.viewers.get(sessionId);
+  if (!viewers || viewers.size === 0) return;
+  const payload = JSON.stringify(frame);
+  for (const ctx of viewers) _sendToCtx(ctx, payload);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Downstream (hub browser -> box)
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Register `ctx` as a viewer of `sessionId` on this link. The FIRST viewer of a session makes the
+ * link attach upstream and ask for a keyframe, so the box pushes that session's frames to the link.
+ *
+ * @returns {boolean} true when this call was the session's first viewer
+ */
+function viewSession(link, sessionId, ctx, deps) {
+  if (!link || link.closed) return false;
+  const d = _d(deps);
+  const id = _string(sessionId, 200);
+  if (!id) return false;
+  _clearIdleClose(link, d);
+  let viewers = link.viewers.get(id);
+  const first = !viewers || viewers.size === 0;
+  if (!viewers) {
+    viewers = new Set();
+    link.viewers.set(id, viewers);
+  }
+  if (ctx) {
+    viewers.add(ctx);
+    // AC-3d: a hub browser tab closing RELEASES its viewers (and only then arms the machine's
+    // 60 s idle close) — it never closes the upstream link directly. Hooked here, once per socket,
+    // because the relay must not need an edit to server.js's own `ws.on('close')`.
+    if (ctx.ws && typeof ctx.ws.once === 'function' && !ctx.ws._remoteRelayCloseHooked) {
+      ctx.ws._remoteRelayCloseHooked = true;
+      ctx.ws.once('close', () => releaseSocket(ctx, d));
+    }
+  }
+  if (first && link.ready) _attachUpstream(link, id, d, 'hub-view');
+  return first;
+}
+
+function releaseViewer(link, sessionId, ctx, deps) {
+  if (!link) return;
+  const d = _d(deps);
+  const viewers = link.viewers.get(_string(sessionId, 200));
+  if (!viewers) return;
+  viewers.delete(ctx);
+  if (viewers.size === 0) link.viewers.delete(_string(sessionId, 200));
+  _maybeScheduleIdleClose(link, d);
+}
+
+/** A hub socket went away: drop it from every session's viewer set on every link. */
+function releaseSocket(ctx, deps) {
+  const d = _d(deps);
+  for (const link of _links.values()) {
+    for (const [sessionId, viewers] of [...link.viewers]) {
+      if (viewers.delete(ctx) && viewers.size === 0) link.viewers.delete(sessionId);
+    }
+    _maybeScheduleIdleClose(link, d);
+  }
+}
+
+function _maybeScheduleIdleClose(link, d) {
+  for (const viewers of link.viewers.values()) {
+    if (viewers.size > 0) return; // a machine link lives as long as ANY of its sessions is viewed
+  }
+  // WP-6: a catalog request in flight is a link user too (released on the reply), so the link is
+  // never closed out from under it — but it is NOT a reason to keep the link open afterwards.
+  if ((Number(link.catalogUsers) || 0) > 0) return;
+  if (link.idleTimer || link.closed) return;
+  const ms = Number(d.idleCloseMs || IDLE_CLOSE_MS) || IDLE_CLOSE_MS;
+  const timer = d.setTimeoutFn(() => {
+    link.idleTimer = null;
+    if (link.closed) return;
+    for (const viewers of link.viewers.values()) {
+      if (viewers.size > 0) return; // someone came back during the idle window
+    }
+    if ((Number(link.catalogUsers) || 0) > 0) return; // a catalog request arrived during the window
+    closeLink(link, d);
+  }, ms);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  link.idleTimer = timer;
+}
+
+function _clearIdleClose(link, d) {
+  if (!link.idleTimer) return;
+  try { d.clearTimeoutFn(link.idleTimer); } catch { /* expected: the injected idle timer is already fired/cleared */ }
+  link.idleTimer = null;
+}
+
+/**
+ * Carry one hub-browser frame to the box, VERBATIM (S-24: `clientMessageId` and every other id is
+ * forwarded as-is, never re-minted). A request that can produce a reply is remembered so the reply
+ * can be routed back to the originating socket only.
+ *
+ * While the link is down this drops the frame (and returns false): hub browsers already show the
+ * existing reconnect/stale UX for a session that stops producing frames, and WP-5 owns any UI
+ * beyond that. Nothing is queued or replayed — the box is the authority and the reconnect path
+ * re-syncs via keyframe.
+ */
+function forward(link, msg, ctx, deps) {
+  if (!link || link.closed) return false;
+  const d = _d(deps);
+  const sessionId = sessionIdsOf(msg)[0] || '';
+  _rememberPending(link, sessionId, msg, ctx, d);
+  if (!link.ready) {
+    // WP-6 (§7, AC-6b): a lifecycle frame can be the FIRST thing a hub browser sends about a
+    // session nobody has viewed yet — its mirror lookup opens the link, and the frame arrives while
+    // the socket is still dialing. Dropping it would mean "the hub ignored park" for exactly the
+    // sync-mirror-only case WP-6 must route. Bounded, and flushed the moment the box says hello.
+    if (link.pendingSends.length < PENDING_SEND_MAX) link.pendingSends.push(msg);
+    return true;
+  }
+  const sent = _sendUpstream(link, msg, d);
+  // WP-6: a relayed kill changes the box's session list, so the catalog re-reads it right away
+  // rather than waiting out the ~15 s probe cadence (the row becomes exited on the box), and the
+  // in-memory mirror registration for the killed id is dropped (the catalog keeps routing it).
+  if (sent && msg.type === 'kill') {
+    remoteMachineCreate.forgetMirrorSession(sessionId);
+    if (typeof d.onRelayedKill === 'function') {
+      try { d.onRelayedKill(link); } catch { /* expected: a catalog fault never breaks the relay */ }
+    }
+  }
+  return sent;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The dispatch seam
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Pre-dispatch hook (lib/ws-router.js). Returns true only for a frame that names at least one
+ * MIRROR session; every other frame returns false immediately — no msg mutation, no allocation on
+ * the local path — so a local session's handling is byte-identical to pre-WP-3.
+ */
+function interceptRelay(ctx, msg, deps) {
+  if (!msg || typeof msg !== 'object') return false;
+  const type = typeof msg.type === 'string' ? msg.type : '';
+  if (!RELAY_TYPES.has(type)) return false;
+  const d = _d(deps);
+  // The overwhelmingly common case is a LOCAL session, which must take the byte-identical existing
+  // path: one id string, one mirror-map miss, `false`. `sessionIdsOf` (an array per frame) is only
+  // paid for `view`, the one type that declares a set — so a keystroke or an ack on a local session
+  // never allocates here.
+  const ids = type === 'view' ? sessionIdsOf(msg) : [(_string(msg.id || msg.sessionId, 200))];
+  if (ids.length === 0 || !ids[0]) return false;
+
+  const mirrors = [];
+  for (const id of ids) {
+    const mirror = d.mirrorFor(id);
+    if (mirror) mirrors.push({ id, mirror });
+  }
+  if (mirrors.length === 0) return false;
+  // A `view` frame declaring BOTH local and remote sessions is left to the local handler (it owns
+  // the local viewer set); the mirror ids are still registered below.
+  const mixedView = type === 'view' && mirrors.length !== ids.length;
+
+  let handled = true;
+  for (const { id, mirror } of mirrors) {
+    const link = _ensureLink(mirror, d);
+    if (!link) { handled = false; continue; }
+    if (VIEW_TYPES.has(type)) {
+      const first = viewSession(link, id, ctx, d);
+      // `attach`/`view` are synthesized upstream by viewSession; `keyframe-req` and the rest are
+      // carried verbatim below (a repeat keyframe-req is exactly what a re-sync asks for).
+      if (type === 'attach' || type === 'view') continue;
+      if (type === 'keyframe-req' && first) continue; // viewSession just issued the equivalent one
+    }
+    if (type === 'detach') {
+      releaseViewer(link, id, ctx, d);
+      continue;
+    }
+    forward(link, msg, ctx, d);
+  }
+  return mixedView ? false : handled;
+}
+
+function _ensureLink(mirror, d) {
+  const machineId = _string(mirror.machineInstanceId, 160);
+  const existing = _links.get(machineId);
+  if (existing && !existing.closed) {
+    _clearIdleClose(existing, d);
+    return existing;
+  }
+  return openLink(machineId, d);
+}
+
+function installIntercept() {
+  if (_uninstallIntercept) return _uninstallIntercept;
+  _uninstallIntercept = registerWsPreDispatchHook('remote-machine-link', (ctx, msg) => interceptRelay(ctx, msg));
+  return _uninstallIntercept;
+}
+
+function closeLink(link, deps) {
+  const d = _d(deps);
+  if (!link || link.closed) return;
+  link.closed = true;
+  if (link.reconnectTimer) {
+    try { d.clearTimeoutFn(link.reconnectTimer); } catch { /* expected: the injected timer is already cleared */ }
+    link.reconnectTimer = null;
+  }
+  _clearIdleClose(link, d);
+  _stopHeartbeat(link, d);
+  const socket = link.socket;
+  link.socket = null;
+  link.ready = false;
+  link.generation += 1;
+  try { socket?.close?.(); } catch { /* expected: the upstream socket is already gone */ }
+  if (_links.get(link.machineInstanceId) === link) _links.delete(link.machineInstanceId);
+}
+
+function _report(d, message) {
+  // REPORT (never throw): a link fault is a degraded remote session, not a hub fault.
+  if (d && d.log && typeof d.log.warn === 'function') d.log.warn(`[remote-machine-link] ${message}`);
+}
+
+/** Test seam: links and their timers are module state and must never leak between tests. */
+function _resetForTests() {
+  for (const link of [..._links.values()]) {
+    link.closed = true;
+    // A pending catalog request is settled, not abandoned: an unresolved promise would keep a
+    // test's await (and the process) alive.
+    for (const finish of [...(link.catalogWaiters || new Map()).values()]) {
+      try { finish({ ok: false, code: 'machine_unreachable', error: 'link_closed' }); } catch { /* expected: test teardown */ }
+    }
+    try { link.reconnectTimer && clearTimeout(link.reconnectTimer); } catch { /* expected: test teardown */ }
+    try { link.idleTimer && clearTimeout(link.idleTimer); } catch { /* expected: test teardown */ }
+    try { link.heartbeatTimer && clearInterval(link.heartbeatTimer); } catch { /* expected: test teardown */ }
+  }
+  _links.clear();
+  _injected = null;
+}
+
+module.exports = {
+  BACKOFF_BASE_MS,
+  BACKOFF_CAP_MS,
+  IDLE_CLOSE_MS,
+  PING_MISS_LIMIT,
+  CATALOG_TIMEOUT_MS,
+  RELAY_TYPES,
+  VIEW_TYPES,
+  REPLY_TYPES,
+  REPLY_FOR_REQUEST,
+  REMEMBER_TYPES,
+  configure,
+  installIntercept,
+  openLink,
+  linkFor,
+  listLinks,
+  closeLink,
+  viewSession,
+  releaseViewer,
+  releaseSocket,
+  forward,
+  interceptRelay,
+  heartbeatTick,
+  backoffDelayMs,
+  sessionIdsOf,
+  requestSessionList,
+  _resetForTests,
+};