create-walle 0.10.2 → 0.10.3

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

@@ -9,9 +9,16 @@
 // 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).
+//   LINK        two kinds, both lazy, both in ONE Map (WP-1 D-1):
+//               * VIEWER link — one upstream WS per (machine, hub socket), keyed by
+//                 `machineId\0clientId:socketGeneration`. Opened on the FIRST viewed session of that
+//                 hub socket and closed immediately when the socket goes away (or after
+//                 IDLE_CLOSE_MS once it stops viewing every session on that machine). It carries
+//                 that one socket's session traffic and nobody else's, so the box runs one delivery
+//                 (one in-flight frame, acked by that one viewer) per hub viewer — exactly like a
+//                 local client.
+//               * CONTROL link — one per machine, keyed by machineId, created ONLY by openLink()
+//                 (the catalog `list` lane + onLinkReady). It never carries a session view.
 //   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
@@ -19,29 +26,52 @@
 //               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.
+//               ONE exception, and only for the geometry family (WP-3 D-4/D-5): `socketGeneration`
+//               is a PER-CONNECTION identity minted by whichever server accepted the socket, so the
+//               relay rewrites it per hop to the identity of the socket on the receiving side (RFC
+//               9110 §7.6.1's per-hop field model) — outbound `_toBoxHop` sets link.boxSocketGeneration
+//               on terminal-geometry-claim-v2 (and its `measurement.socketGeneration`) and on a v2
+//               `resize`; inbound `_toHubHop` sets the receiving hub socket's generation on
+//               terminal-geometry-claim-ack-v2 / -fenced / -owner-revoked. `clientMessageId` and every
+//               other id stay verbatim; the browser's object is never mutated.
+//   FAN-OUT     box -> the hub browser sockets VIEWING that session (S-22). WP-1 D-2: a viewer link
+//               delivers to its OWN ctx only, so co-viewers each receive their own copy on their own
+//               link. WP-1 D-3: a content payload (`type:'frame'`, or `type:'frame-v2'` since WP-2) is
+//               written with `sendFrame` (ctx.ws) — the LOCAL path — bypassing hub send admission, and
+//               WP-2 R-3 projects a `frame-v2` per RECEIVING socket (v2 verbatim, v1 through
+//               projectFrameForProtocol; a projection throw is counted and skips just that frame).
+//               Every other type keeps `ctx.send` (admission + per-hop geometry identity). Reply
+//               frames (submit-prompt-status,
+//               approval-resolution-result, model-change-result, session-lifecycle-result, …) go to
+//               the ORIGINATING hub socket ONLY, matched by the original `clientMessageId`/`requestId`
+//               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.
+// BACKPRESSURE (§10 risk 2), the choice this module makes: with WP-1 D-1 each hub socket has its OWN
+// upstream link, so the box runs one delivery per hub viewer (one in-flight frame, acked by that one
+// socket) — the local client contract. A slow/stalled hub viewer can never stall the frames the OTHER
+// viewers of the same session receive; each hub socket's acks (`ack`/`nack`/`frame-receipt`) go up
+// its own link, 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 { sendFrame } = require('./ws-send-admission');
+// WP-2 (docs/relay-frame-v2-negotiation-box-session-mouse-2026-10-31.html §5 R-3/R-6): the box now
+// answers the hub's peer client-info with `frame-v2` (the frame that carries surface.mouse), so the
+// hub projects it down per RECEIVING hub socket — exactly the box's own fan-out contract.
+const { FRAME_PROTOCOL_V1, FRAME_PROTOCOL_V2, projectFrameForProtocol } = require('./state-sync/frame-protocol');
+
+// Content frame types that take the direct path (sendFrame, no hub admission) on a viewer link.
+// Both speak the same delivery semantics; only the projection differs per receiving socket (R-3).
+const RELAYED_CONTENT_FRAME_TYPES = new Set(['frame', 'frame-v2']);
 
 const BACKOFF_BASE_MS = 500;
 const BACKOFF_CAP_MS = 30000;
@@ -58,7 +88,12 @@ const RELAY_TYPES = Object.freeze(new Set([
   // 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
+  // WP-3 (docs/remote-terminal-cursor-and-geometry-claim-relay-2026-10-27.html §5 D-3/D-4, §9 S-4):
+  // `terminal-geometry-claim-v2` is a viewer's size claim for a MIRROR session — the box owns the
+  // PTY, so without this the claim never crosses the hop and the box PTY keeps its spawn size. Its
+  // `socketGeneration` is rewritten per hop (see the FORWARD note above).
   'input', 'resize', 'reflow', 'reconcile', 'flow', 'detach', 'interrupt-session',
+  'terminal-geometry-claim-v2',
   // 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.
@@ -102,6 +137,10 @@ const REPLY_TYPES = Object.freeze(new Set([
   'session-lifecycle-result',
   'session-interrupt-result',
   'resume-prompt-result',
+  // WP-3 (docs/remote-terminal-cursor-and-geometry-claim-relay-2026-10-27.html §5 D-6, §9 S-5): the
+  // box's verdict on a relayed geometry claim. Routed to the CLAIMING socket only — every other hub
+  // viewer of the same mirror session must not see a lease outcome it never asked for.
+  'terminal-geometry-claim-ack-v2',
   'request-error',
   'error',
 ]));
@@ -115,12 +154,22 @@ const REPLY_TYPES = Object.freeze(new Set([
 const REMEMBER_TYPES = Object.freeze(new Set([
   'submit-prompt', 'approval-resolve', 'model-change', 'park', 'wake', 'kill', 'interrupt-session',
   'resume-prompt-select',
+  // WP-3 (§5 D-6): a claim carries no `clientMessageId`, so its pending entry is matched by
+  // `replyType` (`terminal-geometry-claim-ack-v2`) alone — `_rememberPending` falls back to a
+  // per-session seq key when `clientMessageId` is absent, which is exactly what `_takePending`'s
+  // replyType predicate consumes.
+  'terminal-geometry-claim-v2',
 ]));
 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-0 (docs/relay-per-viewer-delivery-contract-2026-10-27.html §5 D-5, §6, §8 WP-0): at most one
+// `relay-frame-undelivered` diagnostic per (session, reason) window. The counter itself is
+// unthrottled; only the report is.
+const UNDELIVERED_REPORT_INTERVAL_MS = 10000;
+
 // 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',
@@ -130,6 +179,8 @@ const REPLY_FOR_REQUEST = Object.freeze({
   'wake': 'session-lifecycle-result',
   'interrupt-session': 'session-interrupt-result',
   'resume-prompt-select': 'resume-prompt-result',
+  // WP-3 (§5 D-6, §9 S-6): the box's geometry-claim verdict.
+  'terminal-geometry-claim-v2': 'terminal-geometry-claim-ack-v2',
 });
 
 // WP-6: how long a catalog `list` request waits for the box's `sessions` reply before giving up.
@@ -138,12 +189,25 @@ const CATALOG_TIMEOUT_MS = 5000;
 let _injected = null;
 let _uninstallIntercept = null;
 let _productionCache = null;
+// WP-0 (D-5): the hub's session-diagnostics reporter, wired by lib/ws/terminal-attach.js's
+// configure() to the SAME `remoteCreateDeps.recordSessionDiagnostic` the rest of the hub uses (so
+// this needs no server.js edit). Module state, not a deps field, because the production dep object
+// below is memoized once and must read the sink at CALL time (the sink is set at boot).
+let _diagnosticsSink = null;
 
 /** Test/host seam: override any production dependency (registry, WebSocket, timers, clock, log). */
 function configure(deps) {
   _injected = deps && typeof deps === 'object' ? deps : null;
 }
 
+/**
+ * WP-0 (D-5): set the diagnostics sink the production `recordDiagnostic` dep forwards to. A
+ * non-function clears it, so a `configure()` without a reporter can never leave a stale one behind.
+ */
+function setDiagnosticsSink(fn) {
+  _diagnosticsSink = typeof fn === 'function' ? fn : null;
+}
+
 function _string(value, max = 200) {
   return String(value == null ? '' : value).trim().slice(0, max);
 }
@@ -181,6 +245,13 @@ function _productionDeps() {
     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,
+    // WP-0 (D-5, §9 S-2): the report path for a relayed frame a hub viewer did not get. Forwards to
+    // whatever lib/ws/terminal-attach.js's configure() installed via setDiagnosticsSink(); a hub with
+    // no sink records nothing but still counts (undeliveredCounters()). Tests override this dep
+    // directly with `configure({ recordDiagnostic })`.
+    recordDiagnostic: (sessionId, event, details) => {
+      if (_diagnosticsSink) _diagnosticsSink(sessionId, event, details);
+    },
     log: console,
     idleCloseMs: IDLE_CLOSE_MS,
     heartbeatMs: HEARTBEAT_MS,
@@ -225,35 +296,259 @@ function sessionIdsOf(msg) {
 }
 
 function _frameSessionId(frame) {
+  // WP-0 (docs/hub-viewed-box-conv-freshness-and-paste-render-2026-10-31.html §5 D-1, §6, §9 S-1):
+  // `ctmSessionId` is the spelling the box's per-conversation broadcasts use (`conversation-updated`,
+  // `session-image-refs-updated` — server.js:9165/9192), so reading only `id`/`sessionId` dropped
+  // every one of them on the floor at :811. All three spellings name the same session.
   if (!frame || typeof frame !== 'object') return '';
-  return _string(frame.id || frame.sessionId, 200);
+  return _string(frame.id || frame.sessionId || frame.ctmSessionId, 200);
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-0 (docs/relay-per-viewer-delivery-contract-2026-10-27.html §5 D-5, §6, §8 WP-0, §9 S-1..S-3):
+// the per-session relay UNDELIVERED counter.
+//
+// The local delivery contract (docs/terminal-delivery-contract-simplification-2026-09-21.html D-4)
+// bypasses send admission, so a frame that reached nobody is counted locally. The relay did NOT:
+// every hub-browser copy goes through `ctx.send` = `_wsSend`, whose ADMISSION_RESULTS value was
+// discarded, so a throttled / stalled / coalesced viewer silently missed frames the box believed it
+// had delivered (and acked). This counts every non-'sent' downstream send and reports it, throttled
+// so one stalled viewer cannot flood the diagnostics table. WP-1 then makes the frame path report
+// only send-error / socket-not-open, which is the live proof of D-3.
+// ---------------------------------------------------------------------------------------------
+
+// `${sessionId}\u0000${reason}` -> { count, total, sinceMs, lastReportMs, type, clientId }
+// `count` is the accumulation since the last report; `total` is the lifetime count.
+const _undelivered = new Map();
+
+/** Plain snapshot of the undelivered counters, for tests and a hub diagnostics read. */
+function undeliveredCounters() {
+  const rows = [];
+  for (const [key, entry] of _undelivered) {
+    const sep = key.indexOf('\u0000');
+    rows.push({
+      sessionId: key.slice(0, sep),
+      reason: key.slice(sep + 1),
+      count: entry.count,
+      total: entry.total,
+      type: entry.type,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Record one downstream relayed send this viewer did not get as sent. Reason is an ADMISSION_RESULTS
+ * value ('dropped-backpressure' | 'closed-backpressure' | 'dropped-diet' | 'coalesced') or our own
+ * 'send-error' / 'socket-not-open'. At most one `relay-frame-undelivered` diagnostic per
+ * (sessionId, reason) per UNDELIVERED_REPORT_INTERVAL_MS, carrying the count accumulated in the
+ * window. A sink fault is swallowed: the COUNTER is the contract, and a diagnostics failure must
+ * never break relayed frame delivery.
+ */
+function _noteUndelivered(ctx, frame, reason, d) {
+  const sessionId = _frameSessionId(frame);
+  const key = `${sessionId}\u0000${reason}`;
+  const now = d.now();
+  let entry = _undelivered.get(key);
+  if (!entry) {
+    entry = {
+      count: 0,
+      total: 0,
+      sinceMs: now,
+      lastReportMs: null,
+      type: frame && frame.type,
+      clientId: String((ctx && ctx.ws && ctx.ws.clientId) || ''),
+    };
+    _undelivered.set(key, entry);
+  }
+  entry.count += 1;
+  entry.total += 1;
+  entry.type = frame && frame.type;
+  if (entry.lastReportMs != null && now - entry.lastReportMs < UNDELIVERED_REPORT_INTERVAL_MS) return;
+  try {
+    if (typeof d.recordDiagnostic === 'function') {
+      d.recordDiagnostic(sessionId, 'relay-frame-undelivered', {
+        reason, type: entry.type, count: entry.count, sinceMs: entry.sinceMs, clientId: entry.clientId,
+      });
+    }
+  } catch {
+    // expected: a diagnostics-sink fault must never break relayed frame delivery
+  }
+  entry.count = 0;
+  entry.lastReportMs = now;
+  entry.sinceMs = now;
+}
+
+// ---------------------------------------------------------------------------------------------
+// WP-0 (docs/remote-relay-ack-rate-limit-typing-delay-2026-10-28.html §5 D-4b, §6, §8 WP-0,
+// §9 S-7): the upstream twin of the counter above.
+//
+// A box refusing a RELAYED frame answers `auth-error {messageType, code}`. `_routeAuthError` can
+// only hand that verdict to the socket that asked, so a refusal with NO pending origin — exactly the
+// shape of a rate-limited `ack`/`frame-receipt`, which is never remembered as pending — was dropped
+// on the floor: the hub browser waited for a verdict that no one ever saw (design doc §5 D-4b).
+// Count every such refusal and report it, throttled the same way and for the same reason.
+// ---------------------------------------------------------------------------------------------
+
+// `${machineInstanceId}\u0000${sessionId}\u0000${messageType}` -> { count, total, code, sinceMs,
+// lastReportMs }. `count` is the accumulation since the last report; `total` is the lifetime count.
+const _upstreamRefused = new Map();
+
+/** Plain snapshot of the upstream-refusal counters, for tests and a hub diagnostics read. */
+function upstreamRefusedCounters() {
+  const rows = [];
+  for (const [key, entry] of _upstreamRefused) {
+    const [machineInstanceId, sessionId, messageType] = key.split('\u0000');
+    rows.push({
+      machineInstanceId, sessionId, messageType, code: entry.code, count: entry.count, total: entry.total,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Record one box `auth-error` refusing a RELAYED frame that no pending origin could claim. At most
+ * one `relay-upstream-refused` diagnostic per (machine, session, messageType) per
+ * UNDELIVERED_REPORT_INTERVAL_MS, carrying the count accumulated in the window. A sink fault is
+ * swallowed: the COUNTER is the contract, and a diagnostics failure must never break relayed frames.
+ */
+function _noteUpstreamRefused(link, frame, messageType, d) {
+  const machineInstanceId = _string(link && link.machineInstanceId, 200);
+  const sessionId = _frameSessionId(frame);
+  const key = `${machineInstanceId}\u0000${sessionId}\u0000${messageType}`;
+  const now = d.now();
+  let entry = _upstreamRefused.get(key);
+  if (!entry) {
+    entry = {
+      count: 0,
+      total: 0,
+      code: _string(frame && frame.code, 40),
+      sinceMs: now,
+      lastReportMs: null,
+    };
+    _upstreamRefused.set(key, entry);
+  }
+  entry.count += 1;
+  entry.total += 1;
+  entry.code = _string(frame && frame.code, 40);
+  if (entry.lastReportMs != null && now - entry.lastReportMs < UNDELIVERED_REPORT_INTERVAL_MS) return;
+  try {
+    if (typeof d.recordDiagnostic === 'function') {
+      d.recordDiagnostic(sessionId, 'relay-upstream-refused', {
+        messageType, code: entry.code, count: entry.count, machineInstanceId,
+      });
+    }
+  } catch {
+    // expected: a diagnostics-sink fault must never break relayed frame delivery
+  }
+  entry.count = 0;
+  entry.lastReportMs = now;
+  entry.sinceMs = now;
 }
 
 /** Deliver an already-serialized frame to one hub browser socket (fan-out or reply routing). */
-function _sendToCtx(ctx, payload) {
+function _sendToCtx(ctx, payload, frame, d) {
   try {
-    if (ctx && ctx.ws && ctx.ws.readyState === 1 && typeof ctx.send === 'function') ctx.send(payload);
+    if (!ctx || typeof ctx.send !== 'function') return;
+    if (!ctx.ws || ctx.ws.readyState !== 1) {
+      // WP-0 (D-5): the hub viewer's socket is gone — this frame reached nobody. Count it instead of
+      // dropping it silently; the box owns the session and the viewer re-subscribes on reconnect.
+      _noteUndelivered(ctx, frame, 'socket-not-open', d);
+      return;
+    }
+    const result = ctx.send(payload);
+    // WP-0 (D-5): `ctx.send` is `_wsSend(ws, payload)` in production, which returns an
+    // ADMISSION_RESULTS value. Anything but 'sent' means THIS viewer did not get the frame as sent.
+    // `undefined` (a test ctx whose send returns nothing) is not a verdict and records nothing.
+    if (typeof result === 'string' && result !== 'sent') _noteUndelivered(ctx, frame, result, d);
   } 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.
+    _noteUndelivered(ctx, frame, 'send-error', d);
+  }
+}
+
+function _sendFrame(ctx, frame, d) {
+  _sendToCtx(ctx, JSON.stringify(_toHubHop(frame, ctx)), frame, d);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Per-hop identity (WP-3, docs/remote-terminal-cursor-and-geometry-claim-relay-2026-10-27.html
+// §5 D-4/D-5, RFC 9110 §7.6.1). `socketGeneration` is minted by whichever server accepted the WS
+// (server.js's per-connection `ws.socketGeneration`) and the box checks it against the accepting
+// connection (lib/terminal-geometry-claim.js:59-61/106-108). The hub browser's generation is
+// meaningless to the box, and several hub sockets share ONE box generation (they share one link),
+// so the relay owns hop identity: it rewrites ONLY `socketGeneration` (and, for the claim, the
+// nested `measurement.socketGeneration`) on the geometry family, per direction. `clientMessageId`
+// and every other id stay verbatim, and the caller's object is never mutated.
+// ---------------------------------------------------------------------------------------------
+
+// Box -> hub: the geometry family, whose `socketGeneration` must name the RECEIVING hub socket.
+const GEOMETRY_INBOUND_TYPES = Object.freeze(new Set([
+  'terminal-geometry-claim-ack-v2', 'terminal-geometry-fenced', 'terminal-geometry-owner-revoked',
+]));
+
+/** True for a hub-browser frame whose outbound `socketGeneration` must name the LINK's box socket. */
+function _isOutboundGeometry(msg) {
+  if (!msg || typeof msg !== 'object') return false;
+  if (msg.type === 'terminal-geometry-claim-v2') return true;
+  // A v2 resize is the other per-connection identity carrier (a legacy v1 resize has no generation).
+  return msg.type === 'resize' && msg.geometryProtocolVersion === 2;
+}
+
+/**
+ * Outbound hop rewrite (D-4). Returns `msg` ITSELF unless it is a geometry message; otherwise a
+ * SHALLOW COPY with `socketGeneration = link.boxSocketGeneration` and, for the claim, a copied
+ * `measurement` with `measurement.socketGeneration` rewritten too. No other field changes.
+ */
+function _toBoxHop(link, msg) {
+  if (!_isOutboundGeometry(msg)) return msg;
+  const generation = Number(link && link.boxSocketGeneration) || 0;
+  const hop = { ...msg, socketGeneration: generation };
+  if (msg.type === 'terminal-geometry-claim-v2' && msg.measurement && typeof msg.measurement === 'object') {
+    hop.measurement = { ...msg.measurement, socketGeneration: generation };
   }
+  return hop;
 }
 
-function _sendFrame(ctx, frame) {
-  _sendToCtx(ctx, JSON.stringify(frame));
+/**
+ * Inbound hop rewrite (D-5). Returns `frame` ITSELF unless it is one of GEOMETRY_INBOUND_TYPES;
+ * otherwise a SHALLOW COPY whose `socketGeneration` names the RECEIVING hub socket. Applied at
+ * `_sendFrame`, so both the reply-to-origin path and the fan-out path are covered per receiving
+ * socket.
+ */
+function _toHubHop(frame, ctx) {
+  if (!frame || typeof frame !== 'object' || !GEOMETRY_INBOUND_TYPES.has(frame.type)) return frame;
+  return { ...frame, socketGeneration: Number(ctx && ctx.ws && ctx.ws.socketGeneration) || 0 };
 }
 
 // ---------------------------------------------------------------------------------------------
 // Links
 // ---------------------------------------------------------------------------------------------
 
-const _links = new Map(); // machineInstanceId -> link
+const _links = new Map(); // key -> link (control key = machineInstanceId; viewer key = _viewerKey(...))
+
+/**
+ * WP-1 (D-1): the VIEWER-link key — one upstream link per (machine, hub socket). `clientId` and
+ * `socketGeneration` are the hub-side per-connection identity (server.js's own `ws.clientId` /
+ * `ws.socketGeneration`), so two tabs on the same machine get two links and therefore two box
+ * deliveries. A missing ctx/ws degrades to the `':0'` suffix (the caller guards it anyway).
+ */
+function _viewerKey(machineId, ctx) {
+  const ws = ctx && ctx.ws;
+  return `${machineId}\u0000${String((ws && ws.clientId) || '')}:${Number(ws && ws.socketGeneration) || 0}`;
+}
 
-function _newLink(machineId, machineName, url) {
+function _newLink(machineId, machineName, url, kind = 'control', viewerCtx = null) {
   return {
+    key: kind === 'viewer' ? _viewerKey(machineId, viewerCtx) : machineId,
     machineInstanceId: machineId,
     machineName,
     url,
+    // WP-1 (D-1): 'control' (key = machineId, the catalog lane) | 'viewer' (key = _viewerKey, one per
+    // hub socket). `viewerCtx` is the hub ctx a viewer link delivers to; null on a control link.
+    kind,
+    viewerCtx,
     socket: null,
     ready: false,
     closed: false,
@@ -264,6 +559,10 @@ function _newLink(machineId, machineName, url) {
     state: 'idle',
     attempts: 0,
     generation: 0,
+    // WP-3 (D-4): the BOX-side socket identity the box's `hello` reports, recorded on every hello.
+    // Outbound geometry frames carry THIS value (the box checks it against its own accepting socket);
+    // 0 until the first hello, which is why a pre-hello geometry frame is queued (flushed with it).
+    boxSocketGeneration: 0,
     pingMisses: 0,
     heartbeatTimer: null,
     reconnectTimer: null,
@@ -283,8 +582,14 @@ function _newLink(machineId, machineName, url) {
   };
 }
 
-function linkFor(machineId) {
-  return _links.get(_string(machineId, 160)) || null;
+/**
+ * WP-1 (D-1): resolve the link for `machineId` — with a `ctx`, that ctx's VIEWER link; without, the
+ * machine's CONTROL link. Returns null when no such link exists.
+ */
+function linkFor(machineId, ctx) {
+  const id = _string(machineId, 160);
+  if (ctx) return _links.get(_viewerKey(id, ctx)) || null;
+  return _links.get(id) || null;
 }
 
 function listLinks() {
@@ -292,9 +597,10 @@ function listLinks() {
 }
 
 /**
- * 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.
+ * Open (or reuse) the CONTROL link to a machine — the catalog `list`/onLinkReady lane, keyed by the
+ * machine id. `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. A viewing hub socket gets its OWN link via `_ensureViewerLink` (WP-1 D-1).
  */
 function openLink(machine, deps) {
   const d = _d(deps);
@@ -302,7 +608,18 @@ function openLink(machine, deps) {
   if (!row) return null;
   const machineId = _string(row.instanceId, 160);
   if (!machineId) return null;
-  const existing = _links.get(machineId);
+  return _openKeyed(machineId, row, d, 'control', null);
+}
+
+/**
+ * WP-1 (D-1): the shared open/reuse body for BOTH link kinds. `key` is the Map key (machineId for a
+ * control link, `_viewerKey` for a viewer link); the enabled/url/health checks and `_dial` are
+ * identical for both, so only the key/kind/viewerCtx differ.
+ */
+function _openKeyed(key, row, d, kind, viewerCtx) {
+  const machineId = _string(row.instanceId, 160);
+  if (!machineId) return null;
+  const existing = _links.get(key);
   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
@@ -316,8 +633,8 @@ function openLink(machine, deps) {
   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);
+  const link = _newLink(machineId, _string(row.displayName, 200), url, kind, viewerCtx);
+  _links.set(key, link);
   _dial(link, d);
   return link;
 }
@@ -473,12 +790,35 @@ function _onUpstreamFrame(link, raw, d) {
     // 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);
+    _routeAuthError(link, frame, d);
+    return;
+  }
+  if (frame.type === 'hub-bridge-request') {
+    // WP-0 (docs/remote-session-hub-bridge-2026-10-30.html §6.1, §8 WP-0): the box -> hub request
+    // lane. The BOX asks the hub that dialled it to run an op; the reply rides the SAME CONTROL
+    // socket. Route BEFORE the session-frame branches: the frame names no session and is not a
+    // relay frame. `handleRequest` never throws and never rejects, and it writes EXACTLY ONE
+    // response through the upstream send (`_sendUpstream`) — never a local run (R-7).
+    try {
+      const hubBridge = require('./hub-bridge');
+      const pending = hubBridge.handleRequest(link, frame, (reply) => _sendUpstream(link, reply, d));
+      if (pending && typeof pending.catch === 'function') {
+        pending.catch((error) => _report(d, `link ${link.machineInstanceId}: hub-bridge failed: ${error?.message || error}`));
+      }
+    } catch (error) {
+      _report(d, `link ${link.machineInstanceId}: hub-bridge failed: ${error?.message || error}`);
+    }
     return;
   }
 
   const sessionId = _frameSessionId(frame);
-  if (!sessionId) return;
+  if (!sessionId) {
+    // WP-0 (D-4, §9 S-2): an upstream frame that still names no session is reported once per
+    // (link, type) rather than vanishing — this exact silent `return` hid the conversation-updated
+    // drop for four minutes of live traffic.
+    _reportUnroutedOnce(link, frame.type, d);
+    return;
+  }
   if (_routeReplyToOrigin(link, frame, sessionId, d)) return;
   _fanout(link, frame, sessionId, d);
 }
@@ -493,7 +833,24 @@ function _onHello(link, frame, d) {
   link.ready = true;
   link.dialing = false;
   link.attempts = 0; // backoff resets ON SUCCESS (full-jitter contract)
+  // WP-3 (D-4, §9 S-7): the box's `hello` carries the identity of THIS (box-side) connection — the
+  // value every outbound geometry frame must present. Recorded before the pending flush below, so a
+  // queued pre-hello claim goes out with this generation.
+  link.boxSocketGeneration = Number(frame.socketGeneration) || 0;
   _sendUpstream(link, remoteMachineCreate.peerClientInfoFrame(frame), d);
+  // WP-0 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-2, §6.1, §8 WP-0): a CONTROL link
+  // identifies ITSELF to the box once per (re)connect, right after the client-info, so the box knows
+  // which hub dialled it and can route a `hub-bridge-request` back down this very socket. Sent ONLY
+  // on the control link (a viewer link carries one socket's session traffic, never the lane), and
+  // only when this process has an identity to name — `controlHelloFrame()` returns null pre-boot.
+  if (link.kind === 'control') {
+    try {
+      const helloFrame = require('./hub-bridge').controlHelloFrame();
+      if (helloFrame) _sendUpstream(link, helloFrame, d);
+    } catch (error) {
+      _report(d, `link ${link.machineInstanceId}: hub-bridge hello failed: ${error?.message || error}`);
+    }
+  }
   // 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;
@@ -501,7 +858,9 @@ function _onHello(link, frame, 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);
+  // WP-3 (D-4): the hop rewrite is applied at FLUSH time (not enqueue time), so a geometry frame
+  // queued before this hello carries the generation the hello just reported.
+  for (const queued of link.pendingSends.splice(0)) _sendUpstream(link, _toBoxHop(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.
@@ -509,7 +868,9 @@ function _onHello(link, frame, d) {
   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') {
+  // WP-1 (D-1/S-9): the CONTROL link owns the catalog lane — a viewer link never fires this, so a
+  // per-socket viewing link never pays a catalog round-trip.
+  if (!catalogAsked && link.kind === 'control' && typeof d.onLinkReady === 'function') {
     try { d.onLinkReady(link); } catch { /* expected: a catalog hook fault must not break the link */ }
   }
 }
@@ -634,11 +995,17 @@ function _takePending(link, match) {
  * Deliver it to the originating socket; the routine verdict on our own client-info carries no
  * `messageType` and stays noise.
  */
-function _routeAuthError(link, frame) {
+function _routeAuthError(link, frame, d) {
   const messageType = _string(frame.messageType, 40);
   if (!messageType) return;
   const entry = _takePending(link, (e) => e.requestType === messageType);
-  if (entry) _sendFrame(entry.ctx, frame);
+  if (entry) {
+    _sendFrame(entry.ctx, frame, d);
+    return;
+  }
+  // WP-0 (D-4b): a refusal of a RELAYED type with no pending origin is the silent case — count it
+  // (the reply routing above is unchanged, so this is diagnostics only).
+  if (RELAY_TYPES.has(messageType)) _noteUpstreamRefused(link, frame, messageType, d);
 }
 
 /**
@@ -659,7 +1026,7 @@ function _routeReplyToOrigin(link, frame, sessionId, d) {
     if (requestId) {
       const entry = _takePending(link, (e) => e.sessionId === sessionId
         && e.replyType === frame.type && e.requestId === requestId);
-      if (entry) _sendFrame(entry.ctx, frame);
+      if (entry) _sendFrame(entry.ctx, frame, d);
       return true;
     }
     // A result carrying no requestId keeps the legacy clientMessageId/type fallback below.
@@ -670,21 +1037,89 @@ function _routeReplyToOrigin(link, frame, sessionId, d) {
     : null)
     || _takePending(link, (e) => e.sessionId === sessionId && e.replyType === frame.type);
   if (!entry) return false;
-  _sendFrame(entry.ctx, frame);
+  _sendFrame(entry.ctx, frame, d);
   return true;
 }
 
+/**
+ * WP-1 (D-3/D-4): deliver one box content frame straight to the viewer's hub socket through
+ * `sendFrame` — the SAME no-admission primitive server.js's local frame channel uses. A viewer
+ * whose socket is gone (or whose write throws) did not get this frame, so it is counted (WP-0/D-5)
+ * and THAT viewer's link is closed (D-4): the box detaches that delivery and the socket's own
+ * reconnect re-attaches + re-bootstraps. No other viewer is affected.
+ *
+ * WP-2 (R-3/R-6): both content frame types (`frame`, `frame-v2`) take this direct path. A
+ * `frame-v2` is projected to v1 for a hub socket that did not negotiate v2 — per-HOP versioning,
+ * the hub speaks v2 to the box on its own behalf and v1 to a V1 viewer. The projection runs
+ * WITHOUT validation for a V2 socket (verbatim; the browser validates), and a projection THROW
+ * counts as `projection-error` and skips just that frame for that viewer — the link stays OPEN,
+ * matching the box's own fan-out.
+ */
+function _deliverFrameDirect(ctx, frame, link, d) {
+  if (!ctx || !ctx.ws || ctx.ws.readyState !== 1) {
+    _noteUndelivered(ctx, frame, 'socket-not-open', d);
+    closeLink(link, d);
+    return;
+  }
+  let payload = frame;
+  if (frame.type === 'frame-v2' && ctx.ws.frameProtocol !== FRAME_PROTOCOL_V2) {
+    try {
+      // R-3: NARROW the v2 frame to what this v1 socket understands. The v2 projection is the
+      // step that VALIDATES the authority (projectFrameForProtocol's v1 branch is a pure
+      // field-strip and refuses nothing on its own), so a malformed frame-v2 is skipped here for
+      // THIS viewer instead of being handed down half-understood.
+      payload = projectFrameForProtocol(projectFrameForProtocol(frame, FRAME_PROTOCOL_V2), FRAME_PROTOCOL_V1);
+    } catch {
+      // expected: a v2 frame this hub cannot project (invalid authority) is skipped for THIS viewer
+      // only; the counter is the contract and the link must survive (R-6).
+      _noteUndelivered(ctx, frame, 'projection-error', d);
+      return;
+    }
+  }
+  if (!sendFrame(ctx.ws, JSON.stringify(payload))) {
+    _noteUndelivered(ctx, frame, 'send-error', d);
+    closeLink(link, d);
+  }
+}
+
 function _fanout(link, frame, sessionId, d) {
   const viewers = link.viewers.get(sessionId);
   if (!viewers || viewers.size === 0) return;
+  // WP-1 (D-2/D-3): a viewer link holds just its own ctx, and a content payload (`frame` or, WP-2,
+  // `frame-v2`) goes straight to that socket with `sendFrame` (the local path — no hub admission),
+  // projected per receiving socket inside _deliverFrameDirect. Every other frame type keeps
+  // the existing paths: a geometry frame carries the RECEIVING hub socket's own generation, so it is
+  // still serialized per viewer via _sendFrame.
+  if (RELAYED_CONTENT_FRAME_TYPES.has(frame.type) && link.kind === 'viewer') {
+    for (const ctx of viewers) _deliverFrameDirect(ctx, frame, link, d);
+    return;
+  }
+  if (GEOMETRY_INBOUND_TYPES.has(frame.type)) {
+    for (const ctx of viewers) _sendFrame(ctx, frame, d);
+    return;
+  }
   const payload = JSON.stringify(frame);
-  for (const ctx of viewers) _sendToCtx(ctx, payload);
+  for (const ctx of viewers) _sendToCtx(ctx, payload, frame, d);
 }
 
 // ---------------------------------------------------------------------------------------------
 // Downstream (hub browser -> box)
 // ---------------------------------------------------------------------------------------------
 
+/**
+ * WP-1 (D-4): install the ONCE-per-hub-socket close hook that releases every bit of this socket's
+ * relay state — its own viewer links close outright, and its viewer entries on any other link drop
+ * (arming the idle close). Installed from BOTH the viewing path (`viewSession`) and the forward-only
+ * path (`_ensureViewerLink`): a socket that only ever relays a lifecycle/prompt frame for a mirror it
+ * never viewed still owns a viewer link, and without this hook that link would outlive the socket.
+ * Idempotent per socket, because the relay must not need an edit to server.js's own `ws.on('close')`.
+ */
+function _hookSocketClose(ctx, d) {
+  if (!ctx || !ctx.ws || typeof ctx.ws.once !== 'function' || ctx.ws._remoteRelayCloseHooked) return;
+  ctx.ws._remoteRelayCloseHooked = true;
+  ctx.ws.once('close', () => releaseSocket(ctx, d));
+}
+
 /**
  * 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.
@@ -706,12 +1141,8 @@ function viewSession(link, sessionId, ctx, deps) {
   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));
-    }
+    // 60 s idle close) — it never closes the upstream link directly.
+    _hookSocketClose(ctx, d);
   }
   if (first && link.ready) _attachUpstream(link, id, d, 'hub-view');
   return first;
@@ -727,10 +1158,18 @@ function releaseViewer(link, sessionId, ctx, deps) {
   _maybeScheduleIdleClose(link, d);
 }
 
-/** A hub socket went away: drop it from every session's viewer set on every link. */
+/** A hub socket went away: close ITS viewer links outright, and drop it from any other link's viewers. */
 function releaseSocket(ctx, deps) {
   const d = _d(deps);
-  for (const link of _links.values()) {
+  // Snapshot: closeLink mutates _links while we iterate (WP-1 D-4).
+  for (const link of [..._links.values()]) {
+    // WP-1 (D-4): a viewer link belongs to exactly ONE hub socket, so that socket going away closes
+    // the link IMMEDIATELY — no 60 s idle. The box then detaches that delivery, and the socket's own
+    // reconnect re-attaches + re-bootstraps. (A LIVE socket that merely stops viewing keeps the idle.)
+    if (link.kind === 'viewer' && link.viewerCtx === ctx) {
+      closeLink(link, d);
+      continue;
+    }
     for (const [sessionId, viewers] of [...link.viewers]) {
       if (viewers.delete(ctx) && viewers.size === 0) link.viewers.delete(sessionId);
     }
@@ -777,7 +1216,7 @@ function _clearIdleClose(link, d) {
  * re-syncs via keyframe.
  */
 function forward(link, msg, ctx, deps) {
-  if (!link || link.closed) return false;
+  if (!link || link.closed) { if (msg?.type === 'kill') console.warn(`[kill-drop] site=relay-link-closed id=${sessionIdsOf(msg)[0] || ''}`); return false; }
   const d = _d(deps);
   const sessionId = sessionIdsOf(msg)[0] || '';
   _rememberPending(link, sessionId, msg, ctx, d);
@@ -789,7 +1228,7 @@ function forward(link, msg, ctx, deps) {
     if (link.pendingSends.length < PENDING_SEND_MAX) link.pendingSends.push(msg);
     return true;
   }
-  const sent = _sendUpstream(link, msg, d);
+  const sent = _sendUpstream(link, _toBoxHop(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).
@@ -828,15 +1267,21 @@ function interceptRelay(ctx, msg, deps) {
     const mirror = d.mirrorFor(id);
     if (mirror) mirrors.push({ id, mirror });
   }
-  if (mirrors.length === 0) return false;
+  if (mirrors.length === 0) { if (type === 'kill') console.warn(`[kill-drop] site=relay-no-mirror id=${ids[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;
+  // The viewer links this frame touched, so their idle close can be re-evaluated once per frame
+  // (see the forward-only note below) instead of at every early `continue`.
+  const touched = [];
   for (const { id, mirror } of mirrors) {
-    const link = _ensureLink(mirror, d);
-    if (!link) { handled = false; continue; }
+    // WP-1 (D-1): the link is resolved from the mirror's machine AND the calling hub socket, so each
+    // hub socket relays on its OWN upstream link (one box delivery per viewer).
+    const link = _ensureViewerLink(mirror, ctx, d);
+    if (!link) { if (type === 'kill') console.warn(`[kill-drop] site=relay-no-link id=${id}`); handled = false; continue; }
+    touched.push(link);
     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
@@ -850,17 +1295,35 @@ function interceptRelay(ctx, msg, deps) {
     }
     forward(link, msg, ctx, d);
   }
+  // WP-1 (D-4): a FORWARD-ONLY viewer link — a lifecycle/prompt frame for a mirror this socket never
+  // viewed — registers no viewer, so nothing above would ever arm its idle close and it would hold an
+  // upstream socket open forever. Arm it here (a no-op for a link that does hold a viewer, and
+  // idempotent when releaseViewer already armed it). A later attach cancels it via _clearIdleClose.
+  for (const link of touched) _maybeScheduleIdleClose(link, 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;
+/**
+ * WP-1 (D-1/D-2): the VIEWER link for (mirror.machineInstanceId, ctx) — replaces the old machine-only
+ * `_ensureLink`, so each hub socket gets its own upstream link and therefore its own box delivery.
+ * Reuse clears the idle close. A missing ctx (or a ctx with no ws) has no per-socket identity and
+ * falls back to the control link, silently.
+ */
+function _ensureViewerLink(mirror, ctx, d) {
+  const machineId = _string(mirror && mirror.machineInstanceId, 160);
+  if (!machineId) return null;
+  if (!ctx || !ctx.ws) return openLink(machineId, d);
+  const row = d.machineRow(machineId, d);
+  if (!row) return null;
+  const link = _openKeyed(_viewerKey(machineId, ctx), row, d, 'viewer', ctx);
+  if (link) {
+    // WP-1 (D-4): this socket now owns a viewer link — hook its close here too, not only in
+    // viewSession, so a FORWARD-ONLY relay (a lifecycle/prompt frame for a mirror it never viewed)
+    // is still released the moment the socket goes away. Idempotent per socket.
+    _hookSocketClose(ctx, d);
+    _clearIdleClose(link, d);
   }
-  return openLink(machineId, d);
+  return link;
 }
 
 function installIntercept() {
@@ -884,7 +1347,10 @@ function closeLink(link, deps) {
   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);
+  // WP-1 (D-1): the Map is keyed by `link.key` (machineId for a control link, _viewerKey for a
+  // viewer link) — never by machineId alone, or closing one viewer's link would evict another's.
+  const key = link.key || link.machineInstanceId;
+  if (_links.get(key) === link) _links.delete(key);
 }
 
 function _report(d, message) {
@@ -892,6 +1358,19 @@ function _report(d, message) {
   if (d && d.log && typeof d.log.warn === 'function') d.log.warn(`[remote-machine-link] ${message}`);
 }
 
+/**
+ * WP-0 (docs/hub-viewed-box-conv-freshness-and-paste-render-2026-10-31.html §5 D-4): report an
+ * upstream frame the relay cannot route — once per (link, type), so a repeating unnamed frame
+ * cannot flood the log while the first occurrence still shows up in `ctm.log`.
+ */
+function _reportUnroutedOnce(link, type, d) {
+  const key = _string(type, 60) || '(none)';
+  if (!link._unroutedTypes) link._unroutedTypes = new Set();
+  if (link._unroutedTypes.has(key)) return;
+  link._unroutedTypes.add(key);
+  _report(d, `link ${link.machineInstanceId}: dropped upstream frame type=${key} (names no session)`);
+}
+
 /** Test seam: links and their timers are module state and must never leak between tests. */
 function _resetForTests() {
   for (const link of [..._links.values()]) {
@@ -906,6 +1385,10 @@ function _resetForTests() {
     try { link.heartbeatTimer && clearInterval(link.heartbeatTimer); } catch { /* expected: test teardown */ }
   }
   _links.clear();
+  // WP-0 (D-5): the undelivered counters are module state too — a test that drove drops must not
+  // leak its (session, reason) rows into the next one. Same for the WP-0 upstream-refusal counters.
+  _undelivered.clear();
+  _upstreamRefused.clear();
   _injected = null;
 }
 
@@ -915,12 +1398,16 @@ module.exports = {
   IDLE_CLOSE_MS,
   PING_MISS_LIMIT,
   CATALOG_TIMEOUT_MS,
+  UNDELIVERED_REPORT_INTERVAL_MS,
   RELAY_TYPES,
   VIEW_TYPES,
   REPLY_TYPES,
   REPLY_FOR_REQUEST,
   REMEMBER_TYPES,
   configure,
+  setDiagnosticsSink,
+  undeliveredCounters,
+  upstreamRefusedCounters,
   installIntercept,
   openLink,
   linkFor,