create-walle 0.10.1 → 0.10.2

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

@@ -0,0 +1,693 @@
+'use strict';
+
+// WP-2 (docs/remote-machine-hub-sessions-2026-10-22.html §5 D-6/D-10, §6.3, §9 S-1/S-2/S-26):
+// hub-side remote create. A `create` frame that names a REGISTERED REMOTE machine is never
+// prepared locally — it is filtered through the §6.3 allowlist and forwarded to that box over a
+// short-lived WS client connection authenticated with the peer bearer (D-7; the ONLY credential
+// this feature has — no new env var, no new secret).
+//
+// Three rules drive every decision here:
+//   D-10  the forwarded frame is ALLOWLISTED, never the raw client frame. `msg.env`,
+//         `agentRole`, `workerRow`, every PUBLIC_CREATE_INTERNAL_CONTROLS field, every
+//         underscore-prefixed field and every field nobody classified are stripped by
+//         construction: `filterRemoteCreateForward` copies ONLY `REMOTE_CREATE_FORWARD_ALLOWLIST`
+//         members, so a new client-side create field is dropped until someone classifies it
+//         (tests/create-forward-allowlist.test.js fails on the unclassified field by name).
+//         This is the hole S-2/S1-D9 names: `msg.env` is not in the local deny list and merges
+//         into the spawn env (lib/prepared.js, lib/resolve-launch-params.js), so forwarding a raw
+//         frame would let the hub author the BOX's process environment.
+//   D-6   the ORIGINAL `id` (the create idempotency key) is forwarded verbatim; `clientMessageId`
+//         is deliberately NOT part of the forwarded payload. CORRECTED 2026-10-23 (WP-4 of
+//         docs/remote-hub-followups-credential-projects-rows-idempotency-2026-10-23.html §5
+//         D-11..D-14): this module used to claim that the box's `existing?.ptyProcess` dedupe made a
+//         same-id retry idempotent. It did not — that branch ATTACHES (a snapshot, no `created`) and
+//         the caller then rolled the attempt back as `session_setup_incomplete`, or, when the first
+//         launch was still in flight, answered `coding_model_generation_superseded` or spawned a
+//         SECOND PTY for the one id. The box's create path now carries the Idempotency-Key rules
+//         itself (fingerprint D-11, re-answer `created` D-12, `create_in_progress` D-13), so a
+//         same-id retry IS idempotent on the box — but the guarantee lives THERE, not here, and the
+//         hub still only forwards and relays whatever the box answers.
+//   S-26  env resolution is box-side BY CONSTRUCTION: forwarding happens in
+//         lib/ws/terminal-attach.js's handleCreate, BEFORE the local plan is built, so
+//         lib/resolve-launch-params.js never runs on the hub for a remote create and the box
+//         injects its own ports/hosts into the child environment.
+//
+// The persistent per-machine link (refcounted, lazy, reconnect/backoff) is WP-3's
+// lib/remote-machine-link.js and is deliberately NOT built here: this module opens ONE
+// short-lived socket per create, waits for the box's reply, and closes it.
+//
+// Dependency note: the peer credential is built from env in the same shape
+// lib/hosted-sync-worker.js's `_authHeaders` uses (that function is not exported, and this module
+// must not edit hosted-sync-worker.js — see the dependency-cycle note in lib/machine-registry.js).
+// Everything is injectable for tests.
+
+// §6.3 normative allowlist — the ONLY fields a forwarded create may carry, in §6.3's order.
+const REMOTE_CREATE_FORWARD_ALLOWLIST = Object.freeze([
+  'id',
+  'cmd',
+  'args',
+  'cwd',
+  'createCwd',
+  'label',
+  'title',
+  // D-13/WP-5 (§6.3 amendment): a CTM-composed label (`Shell:`/`Folder:`/…) marks itself
+  // `titleIntent:'default'` so the BOX's resolver writes it at tier 3. Without this the hub strips
+  // the mark and a remote create promotes its own composed label to a tier-1 (user) name.
+  'titleIntent',
+  'cols',
+  'rows',
+  'terminalDimsMeasured',
+  'model_id',
+  'model_provider',
+  'mcp_profile',
+  'agentType',
+  'chatSessionId',
+]);
+
+const DEFAULT_TIMEOUT_MS = 15000;
+
+// WP-1 (D-2): a missing peer credential is a CONFIGURATION error, not an unreachable box. The box
+// may be perfectly reachable — the hub simply has nothing to authenticate with, and no retry can
+// change that (env is read at process start). Every hub→box lane reports this one code, so an
+// operator sees "set CTM_SYNC_PEER_TOKEN", never a phantom network fault.
+const PEER_CREDENTIAL_MISSING = 'peer_credential_missing';
+
+// P-3 (rev 2): the one-hop guard's header. Every member-to-member request carries it; a receiver
+// that sees it and is asked to reach a THIRD machine refuses `machine_forward_loop`.
+const X_CTM_FORWARDED_BY = 'x-ctm-forwarded-by';
+const MACHINE_FORWARD_LOOP = 'machine_forward_loop';
+
+// ctm session id -> { machineInstanceId, machineName, at } for every session this hub created
+// ON a box (OQ-4: mirror sessions stay OUTSIDE the sessions Map, whose LIST/ATTACH-reachable
+// `_ptyProcess` surface is ~16 sites > the ~15 worth merging for). WP-3/WP-6 read this map; it is
+// deliberately in-memory (a restart re-derives nothing and the box remains the authority).
+const _mirrorSessions = new Map();
+
+let _injected = null;
+
+/** Test/host seam: override any production dependency (db, registry, env, WebSocket, …). */
+function configure(deps) {
+  _injected = deps && typeof deps === 'object' ? deps : null;
+}
+
+function _string(value, max = 1000) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+function _trimUrl(url) {
+  return _string(url, 1000).replace(/\/+$/, '');
+}
+
+// Lazy: a caller that only needs the pure filter (the unit test, the WS branch test) must never
+// load db.js / the owner client.
+function _productionDeps() {
+  return {
+    env: process.env,
+    // The same handle server.js hands lib/api/machines.js: the DB-owner mutation Proxy, so the
+    // registry read below is the one the routes use.
+    db: require('../db-owner-client'),
+    registry: require('./machine-registry'),
+    parseSyncPeers: require('./hosted-sync-worker').parseSyncPeers,
+    // WP-6 §8: the post-create catalog refresh (lazy: the catalog module requires THIS one).
+    refreshCatalog: (machineId) => {
+      try {
+        require('./remote-machine-catalog').fetchCatalog(machineId).catch(() => { /* expected: fetchCatalog resolves its own failures */ });
+      } catch { /* expected: a catalog fault must never fail a create */ }
+    },
+  };
+}
+
+function _deps(overrides) {
+  return Object.assign({}, _productionDeps(), _injected || {}, overrides || {});
+}
+
+/**
+ * The §6.3 forward: copy ONLY allowlisted own properties. Stripped ALWAYS (by construction, and
+ * asserted by the allowlist test): `env`, `agentRole`, `workerRow`, every
+ * PUBLIC_CREATE_INTERNAL_CONTROLS name, every underscore-prefixed name, and anything nobody
+ * classified. `machine` is a routing field of the hub's own protocol and never crosses.
+ */
+function filterRemoteCreateForward(msg) {
+  const out = {};
+  if (!msg || typeof msg !== 'object') return out;
+  for (const key of REMOTE_CREATE_FORWARD_ALLOWLIST) {
+    if (key.startsWith('_')) continue; // defensive: no underscore name is on the list today
+    if (!Object.prototype.hasOwnProperty.call(msg, key)) continue;
+    out[key] = msg[key];
+  }
+  return out;
+}
+
+/**
+ * WP-3 (DGX Spark coding readiness §2): which coding agent — if any — a forwarded create is about.
+ * The create path picks the CLI from `msg.agentType || detectAgentType(cmd)` (server.js:34024, whose
+ * canonical values are exactly 'claude' | 'codex' — lib/agent-capabilities.js:19,45 and
+ * lib/create/resolve-launch-params.js:692, which also writes the matching bare `cmd` at :772/:824,
+ * the same shape public/js/reviews.js:858 sends). Only those two can be signed out, so a `null`
+ * (shell / gemini / walle / anything else) is never refused — the caller checks the sign-in verdict
+ * for that agent only. Pure and total: any other shape reads `null`.
+ */
+function remoteCreateAgentKey(payload) {
+  const agentType = _string(payload && payload.agentType, 40).toLowerCase();
+  if (agentType === 'claude' || agentType === 'codex') return agentType;
+  const cmd = _string(payload && payload.cmd, 300);
+  if (!cmd) return null;
+  const base = cmd.split(/[\\/]/).pop().toLowerCase();
+  return base === 'claude' || base === 'codex' ? base : null;
+}
+
+/** The hub's own minted instance id, or '' when identity is not available yet. */
+function _localInstanceId(deps) {
+  if (typeof deps.localInstanceId === 'string') return _string(deps.localInstanceId, 160);
+  try {
+    const identity = require('./instance-identity-access').getInstanceIdentity({ required: false });
+    return _string(identity && identity.instanceId, 160);
+  } catch {
+    // expected: identity is not ready yet (pre-DB-open) — the caller then treats an explicitly
+    // named machine as remote rather than silently running a foreign session on this host.
+    return '';
+  }
+}
+
+/**
+ * S-1: does this create name a REMOTE machine? `machine` absent, empty, or equal to this
+ * process's own minted instance id takes the UNCHANGED local path (S-2: the local path and the
+ * local deny list are untouched). When the local id cannot be resolved yet, an explicitly named
+ * machine is treated as remote — the honest failure (`machine_unreachable`) beats spawning a
+ * session on the wrong host.
+ */
+function isRemoteMachineTarget(msg, deps = {}) {
+  const machine = _string(msg && msg.machine, 160);
+  if (!machine) return false;
+  const d = _deps(deps);
+  return machine !== _localInstanceId(d);
+}
+
+function _findMachine(machineId, deps) {
+  const registry = deps.registry;
+  if (!registry || typeof registry.listMachines !== 'function') return null;
+  const listed = registry.listMachines({ db: deps.db }) || {};
+  const machines = Array.isArray(listed.machines) ? listed.machines : [];
+  return machines.find((row) => _string(row.instanceId, 160) === machineId) || null;
+}
+
+function _parsePeerTokenMap(raw = '') {
+  const value = _string(raw, 10000);
+  const map = new Map();
+  if (!value) return map;
+  if (value.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const [peerId, token] of Object.entries(parsed)) {
+          if (_string(peerId, 160) && _string(token, 1000)) map.set(_string(peerId, 160), _string(token, 1000));
+        }
+        return map;
+      }
+    } catch {
+      // expected: a malformed JSON map falls through to the `id=token` list form below
+    }
+  }
+  for (const part of value.split(',')) {
+    const [peerId, ...rest] = part.split('=');
+    if (_string(peerId, 160) && _string(rest.join('='), 1000)) {
+      map.set(_string(peerId, 160), _string(rest.join('='), 1000));
+    }
+  }
+  return map;
+}
+
+/** The legacy env bearer (D-8): CTM_SYNC_PEER_TOKEN, or this host's entry in CTM_SYNC_PEER_TOKENS. */
+function _envPeerToken(env, peerId) {
+  const direct = _string(env.CTM_SYNC_PEER_TOKEN, 1000);
+  if (direct) return direct;
+  if (env.CTM_SYNC_PEER_TOKENS && peerId) return _string(_parsePeerTokenMap(env.CTM_SYNC_PEER_TOKENS).get(peerId), 1000);
+  return '';
+}
+
+/** This process's MINTED instance id (falling back to the env tag) — the P-3 hop header's value. */
+function _ownForwardId(env, deps) {
+  return _localInstanceId(deps) || _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || env.HOSTNAME || '', 160);
+}
+
+/**
+ * The hub's OWN peer credential (D-7 / D-8 rev 2 / P-8): `Authorization: Bearer <token>` +
+ * `X-CTM-Sync-Peer: <peer id>` + (rev 2, P-3) `X-CTM-Forwarded-By: <own instanceId>`.
+ *
+ *   D-8  OUTBOUND: the shared pool token when this machine has a pool (lib/machine-pool.js), else
+ *        the env CTM_SYNC_PEER_TOKEN(S) legacy fallback. The env shape and precedence are
+ *        unchanged from WP-1.
+ *   P-8  …but a pool secret is sent ONLY to a machine that is IN the pool. A legacy env-token box
+ *        that never joined would 401 a pool bearer, so once this hub has a pool, a non-member
+ *        target is dialled with the env bearer instead. The choice is per TARGET: pass
+ *        `deps.instanceId`. Precedence is
+ *          pool  when hasPool() && isMember(instanceId) — never to a non-member: a box outside the
+ *                pool cannot verify the secret, and lib/auth-context.js does not fall through on a
+ *                `ctmpool1_` bearer it cannot verify, so sending it is both a refusal and a leak,
+ *          env   when an env token is configured,
+ *          null  otherwise.
+ *        With NO `instanceId` the caller is not describing a target (a self-probe, a test), so the
+ *        old pool-if-pool precedence is kept.
+ *   P-3  EVERY result (pool or env) carries `X-CTM-Forwarded-By`. It is the one-hop guard's
+ *        signal: a receiver that sees it and is asked to dial a THIRD machine refuses
+ *        `machine_forward_loop`. The value is the sender's minted instance id (the same id the
+ *        `machine` routing field uses), read through lib/instance-identity-access; it falls back to
+ *        the env instance tag so a pre-boot dial still names the sender.
+ *
+ * Returns null when NO credential is configured (then the caller reports peer_credential_missing).
+ */
+function buildPeerControlHeaders(env = process.env, deps = {}) {
+  const peerId = _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || env.HOSTNAME || '', 160);
+  const forwardedBy = _ownForwardId(env, deps);
+  const envToken = _envPeerToken(env, peerId);
+  const poolToken = _poolToken();
+  // P-8: the per-target decision. A named non-member is dialled with the env bearer so a legacy
+  // box keeps answering; an unnamed target keeps the pool-if-pool behaviour this function had.
+  const target = _string(deps.instanceId, 160);
+  const poolApplies = !!poolToken && (!target || _isPoolMember(target));
+  if (poolApplies) {
+    return {
+      Authorization: `Bearer ${poolToken}`,
+      ...(forwardedBy ? { 'X-CTM-Sync-Peer': forwardedBy } : {}),
+      'X-CTM-Forwarded-By': forwardedBy,
+    };
+  }
+  if (!envToken) return null;
+  return {
+    Authorization: `Bearer ${envToken}`,
+    ...(peerId ? { 'X-CTM-Sync-Peer': peerId } : {}),
+    'X-CTM-Forwarded-By': forwardedBy,
+  };
+}
+
+/** P-8: is `instanceId` one of this pool's machines? Guarded so a leaf/test never loads the store. */
+function _isPoolMember(instanceId) {
+  try {
+    const pool = require('./machine-pool').getMachinePool();
+    return !!(pool && typeof pool.isMember === 'function' && pool.isMember(instanceId));
+  } catch {
+    return false; // expected: machine-pool is a pure leaf; an unreadable store means "not a member"
+  }
+}
+
+/** The loaded pool's outbound bearer, or '' — lazy + guarded so a unit test never loads the store. */
+function _poolToken() {
+  try {
+    const pool = require('./machine-pool').getMachinePool();
+    return pool && pool.hasPool() ? _string(pool.token(), 1000) : '';
+  } catch {
+    return ''; // expected: machine-pool is a pure leaf; a load failure must never break a dial
+  }
+}
+
+/**
+ * WP-1 (D-4) / D-8 rev 2 / P-8: the credential state, for surfaces that must SHOW the operator why
+ * a box cannot be reached. It answers per TARGET when given one: 'pool' when THIS target is dialled
+ * with the shared pool secret, 'env' when it is dialled with the legacy CTM_SYNC_PEER_TOKEN(S),
+ * else 'missing'. The token VALUE is never returned, logged or derived from here — only which
+ * credential class is in play. It is the same decision buildPeerControlHeaders makes, so a row's
+ * word always matches the bearer that will actually be sent.
+ */
+function peerCredentialState(env = process.env, { instanceId } = {}) {
+  return buildPeerControlHeaders(env, { instanceId }) ? _credentialClassOf(env, instanceId) : 'missing';
+}
+
+/** P-8: which credential class buildPeerControlHeaders picks for `instanceId` — never the value. */
+function _credentialClassOf(env, instanceId) {
+  const peerId = _string(env.CTM_INSTANCE_ID || env.CTM_INSTANCE_TAG || env.HOSTNAME || '', 160);
+  const target = _string(instanceId, 160);
+  const poolApplies = !!_poolToken() && (!target || _isPoolMember(target));
+  return poolApplies ? 'pool' : 'env';
+}
+
+/** P-3: the forwarded-by hop header on an inbound request, or '' (never throws on a bare ctx). */
+function forwardedByOf(source) {
+  const headers = (source && (source.headers || (source.ws && source.ws._ctmRequest && source.ws._ctmRequest.headers))) || {};
+  return _string(headers[X_CTM_FORWARDED_BY] || '', 200);
+}
+
+/**
+ * WP-1 (D-2): the operator-facing copy for PEER_CREDENTIAL_MISSING. Names the env var and BOTH
+ * machines, because the credential must be the same on each side and is only read at process start.
+ */
+function peerCredentialMissingMessage(machineName) {
+  return `Set the same CTM_SYNC_PEER_TOKEN on this machine and on ${machineName || 'the machine'}, then restart both`;
+}
+
+function _wsUrlFor(machineUrl) {
+  const base = _trimUrl(machineUrl);
+  if (!base) return '';
+  try {
+    const url = new URL(base);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${url.origin}/ws`;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The shared DIAL prologue (WP-2 + WP-3 §6.4) — everything that must happen before a peer socket
+ * exists: the ws/wss URL, the peer bearer (D-7), and the WebSocket constructor. Both the one-shot
+ * create forward (sendRemoteCreate) and the persistent hub link (lib/remote-machine-link.js) start
+ * here so the two lanes can never drift on auth or URL shape.
+ *
+ * @returns {{ok: true, url: string, headers: object, WebSocketImpl: Function}|{ok: false, code: string, error: string}}
+ */
+function preparePeerDial(machineUrl, deps = {}) {
+  const url = _wsUrlFor(machineUrl);
+  if (!url) return { ok: false, code: 'machine_unreachable', error: 'machine_url_invalid' };
+  // P-8: `deps.instanceId` is the machine this dial is FOR, when the caller knows it. The dial
+  // prologue is shared with the hub link lane, so the target must ride the deps rather than being
+  // re-derived here.
+  const headers = typeof deps.authHeaders === 'function'
+    ? deps.authHeaders()
+    : buildPeerControlHeaders(deps.env || process.env, { instanceId: deps.instanceId });
+  // D-2: the credential is mandatory on EVERY leg, so a missing one is named as a configuration
+  // error (with the machine's name in the copy when the caller knows it) instead of being folded
+  // into `machine_unreachable`, which sends the operator hunting for a network fault.
+  if (!headers) {
+    return {
+      ok: false,
+      code: PEER_CREDENTIAL_MISSING,
+      error: peerCredentialMissingMessage(_string(deps.machineName, 200)),
+    };
+  }
+  let WebSocketImpl = deps.WebSocket;
+  if (!WebSocketImpl) {
+    try {
+      WebSocketImpl = require('ws').WebSocket;
+    } catch (error) {
+      return { ok: false, code: 'machine_unreachable', error: `ws_unavailable:${error?.message || error}` };
+    }
+  }
+  return { ok: true, url, headers, WebSocketImpl };
+}
+
+/**
+ * The dial ORDER is load-bearing (D-6/§6.4 "HELLO = normal client hello"): the box's WS gate drops
+ * a terminal-protocol message — `create` included — that arrives before a compatible `client-info`.
+ * This is the one frame both lanes answer the box's `hello` with, so a browser-faithful handshake
+ * can never be re-implemented slightly differently on a second lane.
+ */
+function peerClientInfoFrame(hello) {
+  const appVersion = (hello && hello.appVersion) || {};
+  return {
+    type: 'client-info',
+    terminalProtocol: Number((hello && hello.terminalProtocol) || appVersion.terminalProtocol || 0),
+    assetEpoch: String(appVersion.assetEpoch || ''),
+    surface: 'machine-hub',
+  };
+}
+
+/**
+ * One short-lived forward: connect, HELLO handshake, send the filtered create, wait for the
+ * box's `created` (or `error`) frame, close. Never throws — the caller turns a failure into the
+ * `machine_unreachable` (or box-error) frame.
+ *
+ * @returns {Promise<{ok: true, frame: object}|{ok: false, code: string, error: string}>}
+ */
+function sendRemoteCreate({ machineUrl, payload, deps }) {
+  return new Promise((resolve) => {
+    const dial = preparePeerDial(machineUrl, deps);
+    if (!dial.ok) return resolve(dial);
+    const { url, headers, WebSocketImpl } = dial;
+    const timeoutMs = Number(deps.timeoutMs || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+    const setTimeoutFn = typeof deps.setTimeoutFn === 'function' ? deps.setTimeoutFn : setTimeout;
+    const clearTimeoutFn = typeof deps.clearTimeoutFn === 'function' ? deps.clearTimeoutFn : clearTimeout;
+
+    let socket = null;
+    let timer = null;
+    let settled = false;
+    let sent = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeoutFn(timer);
+      try { if (socket) socket.close(); } catch { /* expected: close on an already-dead socket */ }
+      resolve(result);
+    };
+    // Only ever after client-info (see the dial-order note above): a create sent earlier is
+    // dropped by the box's protocol gate and the forward would hang until the timeout.
+    const sendCreate = () => {
+      if (sent || settled) return;
+      sent = true;
+      try {
+        socket.send(JSON.stringify({ type: 'create', ...payload }));
+      } catch (error) {
+        finish({ ok: false, code: 'machine_unreachable', error: `send_failed:${error?.message || error}` });
+      }
+    };
+
+    try {
+      socket = new WebSocketImpl(url, { headers });
+    } catch (error) {
+      return resolve({ ok: false, code: 'machine_unreachable', error: `connect_failed:${error?.message || error}` });
+    }
+
+    timer = setTimeoutFn(() => {
+      try { socket.terminate(); } catch { /* expected: the socket is already gone */ }
+      finish({ ok: false, code: 'machine_unreachable', error: 'timeout' });
+    }, timeoutMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+
+    // No create on 'open': the box has not said hello yet, so its protocol gate is not satisfied.
+    socket.on('message', (raw) => {
+      let frame = null;
+      try {
+        frame = JSON.parse(raw.toString());
+      } catch {
+        return; // expected: a non-JSON frame (the box's binary/other lanes) is not the reply
+      }
+      if (!frame || typeof frame !== 'object') return;
+      if (frame.type === 'hello') {
+        // The box gates every terminal-protocol message (including 'create') behind a compatible
+        // client-info, so the hub identifies itself with the epoch the box just advertised — the
+        // same handshake a browser does. Both frames go out in this order on this one socket.
+        try {
+          socket.send(JSON.stringify(peerClientInfoFrame(frame)));
+        } catch { /* expected: the socket died between hello and client-info */ }
+        sendCreate();
+        return;
+      }
+      if (frame.type === 'created') return finish({ ok: true, frame });
+      if (frame.type === 'terminal-protocol-incompatible') {
+        // The box refused the frame on protocol grounds. Fail now with the reason instead of
+        // waiting out the timeout for a reply that will never come (this is the frame that made a
+        // mis-ordered dial look like an unreachable box).
+        return finish({
+          ok: false,
+          code: 'machine_unreachable',
+          error: `terminal_protocol_incompatible:${_string(frame.reason, 80) || _string(frame.blockedMessage, 60) || 'unknown'}`,
+        });
+      }
+      if (frame.type === 'auth-error') {
+        // The box's WS authorization verdict on a frame (server.js `_sendWsAuthFailure`), which
+        // NAMES the frame it refused in `messageType`. A verdict on the `create` means the session
+        // was never prepared — the box's own code (`rate_limited`, `insufficient_scope`, …) is the
+        // reply, so surface it rather than waiting out the timeout for a `created` that is not
+        // coming. A verdict on `client-info` is routine noise on this lane (the box applies ws
+        // build compatibility at server.js:30158, BEFORE `_authorizeWsMessage`, so it refuses the
+        // handshake frame for a peer-control identity and honours the create anyway) and must stay
+        // non-fatal — treating every auth-error as fatal would break every forward.
+        if (_string(frame.messageType, 40) === 'create') {
+          const code = _string(frame.code, 80) || 'machine_unreachable';
+          return finish({ ok: false, code, error: `box_refused_create:${code}` });
+        }
+        return;
+      }
+      if (frame.type === 'error') {
+        return finish({
+          ok: false,
+          code: _string(frame.code, 80) || 'machine_unreachable',
+          error: _string(frame.message || frame.error, 300) || 'box_error',
+        });
+      }
+      // Everything else (hello, lifecycle-pressure, session-activity, sessions, …) is either the
+      // handshake or the box's ambient traffic on this lane and is not a reply to the create.
+    });
+    socket.on('error', (error) => {
+      finish({ ok: false, code: 'machine_unreachable', error: _string(error?.message || error, 300) });
+    });
+    socket.on('close', () => {
+      finish({ ok: false, code: 'machine_unreachable', error: 'closed_before_reply' });
+    });
+  });
+}
+
+function _sendFrame(ctx, frame) {
+  try {
+    if (ctx && ctx.ws && ctx.ws.readyState === 1 && typeof ctx.send === 'function') {
+      ctx.send(JSON.stringify(frame));
+    }
+  } catch {
+    // expected: the requesting browser socket died while the box was answering — the session
+    // exists on the box and WP-6's catalog merge is what re-surfaces it.
+  }
+}
+
+function _fail(ctx, code, detail) {
+  _sendFrame(ctx, {
+    type: 'error',
+    code: code || 'machine_unreachable',
+    message: detail || 'The machine could not be reached.',
+  });
+  return { ok: false, code: code || 'machine_unreachable', error: detail || '' };
+}
+
+/**
+ * Forward an already-classified remote create (S-1). On success the box's own `created` frame is
+ * re-emitted to the requesting browser socket with `machine`/`machineName` added (AC-2a) and the
+ * mirror registration is recorded; on failure the caller's socket gets exactly one typed `error`
+ * frame and NOTHING is created locally (AC-2c).
+ */
+async function forwardRemoteCreate(ctx, msg, deps = {}) {
+  const d = _deps(deps);
+  const machineId = _string(msg && msg.machine, 160);
+  // P-3 one-hop guard. This function is reached ONLY when the create names a machine that is not
+  // this instance (lib/ws/terminal-attach.js checks isRemoteMachineTarget first), so a request that
+  // already carries the hop header is by definition a request to forward a forwarded create — the
+  // A→B→C chain (and the A→B→A loop) P-3 forbids. Nothing is dialled and nothing is created.
+  const forwardedBy = forwardedByOf(ctx);
+  if (forwardedBy) {
+    return _fail(ctx, MACHINE_FORWARD_LOOP, `This create was already forwarded by ${forwardedBy}; a forwarded request is never forwarded again`);
+  }
+  const row = _findMachine(machineId, d);
+  if (!row) return _fail(ctx, 'machine_unreachable', `machine ${machineId} is not registered on this hub`);
+  if (!row.enabled) return _fail(ctx, 'machine_unreachable', `machine ${machineId} is disabled`);
+  if (!_string(row.url, 1000)) return _fail(ctx, 'machine_unreachable', `machine ${machineId} has no url`);
+  if (_string(row.health, 40) === 'unreachable') {
+    return _fail(ctx, 'machine_unreachable', `machine ${machineId} is unreachable`);
+  }
+
+  const payload = filterRemoteCreateForward(msg);
+  // WP-3: the box judges a create only by its manifest probe, so a box that is REACHABLE but has no
+  // signed-in Claude/Codex CLI would happily spawn a session that opens at a login prompt. Refuse at
+  // the hub instead, naming the box and the URL that fixes it. 'unknown' (never probed, unreachable
+  // probe, unreadable body) and 'signed_in' both proceed: only an explicit `signedIn:false` refuses.
+  const agentKey = remoteCreateAgentKey(payload);
+  const auth = agentKey && d.registry && typeof d.registry.agentAuthFor === 'function'
+    ? d.registry.agentAuthFor(row.instanceId)
+    : null;
+  if (auth && auth[agentKey] === 'signed_out') {
+    const label = agentKey === 'codex' ? 'Codex' : 'Claude Code';
+    return _fail(ctx, 'machine_agent_signed_out', `${label} is not signed in on ${_string(row.displayName, 200) || row.instanceId} — open ${row.url} → AI Providers → Coding Agents → Sign in`);
+  }
+  // The machine's DISPLAY name rides the dial deps so a credential-less refusal can name the box
+  // the operator has to configure (D-2), not just "the machine".
+  const result = await sendRemoteCreate({
+    machineUrl: row.url,
+    payload,
+    // P-8: the TARGET's instanceId rides the dial deps so the credential is chosen per machine —
+    // a legacy env-token box that never joined the pool is dialled with the env bearer, not with a
+    // pool secret it would 401.
+    deps: { ...d, machineName: _string(row.displayName, 200), instanceId: _string(row.instanceId, 160) },
+  });
+  if (!result.ok) return _fail(ctx, result.code, result.error);
+
+  const frame = result.frame || {};
+  const sessionId = _string(frame.id || payload.id, 200);
+  if (sessionId) recordMirrorSession(sessionId, row);
+  _sendFrame(ctx, {
+    ...frame,
+    machine: _string(row.instanceId, 160),
+    machineName: _string(row.displayName, 200),
+  });
+  // WP-6 §8: "right after a forwarded create" is a catalog refresh trigger — the new session must
+  // appear in the hub's merged list at once, not on the next ~15 s probe sweep. Fire-and-forget:
+  // the in-memory registration above already makes the relay work, so a catalog fault is a stale
+  // list, never a failed create.
+  if (typeof d.refreshCatalog === 'function') {
+    try { d.refreshCatalog(_string(row.instanceId, 160)); } catch { /* expected: a catalog fault never fails a create */ }
+  }
+  return { ok: true, sessionId, machineInstanceId: _string(row.instanceId, 160) };
+}
+
+/** Record (or refresh) the in-memory mirror registration for a session this hub created on a box. */
+function recordMirrorSession(sessionId, machineRow) {
+  const id = _string(sessionId, 200);
+  if (!id) return null;
+  const entry = {
+    machineInstanceId: _string(machineRow && machineRow.instanceId, 160),
+    machineName: _string(machineRow && machineRow.displayName, 200),
+    at: Date.now(),
+  };
+  _mirrorSessions.set(id, entry);
+  return entry;
+}
+
+/**
+ * WP-6 (S-3/S-27): the SINGLE read seam every relaying caller uses — "which machine owns this ctm
+ * session id". It is the UNION over the in-memory registrations above, the live catalog
+ * (lib/remote-machine-catalog.js) and the at-rest sync mirror rows, so a hub RESTART restores
+ * relaying from the first catalog fetch (or from the sync mirror rows) with no user action — the
+ * in-memory map alone would forget every relay.
+ *
+ * The union lives in lib/remote-machine-catalog.js. The require is lazy and one-directional (this
+ * module -> the catalog; the catalog takes this module as an injected peer, wired by server.js), so
+ * the lib/** graph stays acyclic and boot order is never load-bearing. The raw-map read below stays
+ * O(1) for this module's own callers.
+ */
+function getMirrorSessionMachine(ctmSessionId) {
+  try {
+    return require('./remote-machine-catalog').getMirrorSessionMachine(ctmSessionId) || null;
+  } catch {
+    // REPORT: a catalog fault degrades to the in-memory registrations, which is strictly less
+    // knowledge — never more.
+    return getLocalMirrorSession(ctmSessionId);
+  }
+}
+
+/**
+ * Drop a registration once the hub relayed the session's kill: the box is the authority from then
+ * on (the catalog re-reads it as exited), and without this every create this process ever relayed
+ * would stay pinned in the map for the life of the process.
+ */
+function forgetMirrorSession(sessionId) {
+  return _mirrorSessions.delete(_string(sessionId, 200));
+}
+
+/** The in-memory registrations ONLY (no catalog, no sync mirror) — one map read. */
+function getLocalMirrorSession(ctmSessionId) {
+  return _mirrorSessions.get(_string(ctmSessionId, 200)) || null;
+}
+
+/** WP-3/WP-6 read seam: every mirror registration this process holds. */
+function listMirrorSessions() {
+  return [..._mirrorSessions.entries()].map(([sessionId, row]) => ({ sessionId, ...row }));
+}
+
+/** Test seam: the mirror map is module state and must never leak between tests. */
+function _resetMirrorSessionsForTests() {
+  _mirrorSessions.clear();
+}
+
+module.exports = {
+  REMOTE_CREATE_FORWARD_ALLOWLIST,
+  DEFAULT_TIMEOUT_MS,
+  configure,
+  filterRemoteCreateForward,
+  remoteCreateAgentKey,
+  isRemoteMachineTarget,
+  forwardRemoteCreate,
+  sendRemoteCreate,
+  buildPeerControlHeaders,
+  // WP-1 (D-2/D-4): the missing-credential code, its operator copy, and the hub-local state.
+  PEER_CREDENTIAL_MISSING,
+  peerCredentialMissingMessage,
+  peerCredentialState,
+  // WP-2a (P-3): the hop header name, its refusal code, and the inbound-header reader both the
+  // WS create path and (via lib/remote-machine-proxy.js) the HTTP proxy path use.
+  X_CTM_FORWARDED_BY,
+  MACHINE_FORWARD_LOOP,
+  forwardedByOf,
+  // WP-3: the shared dial/handshake prologue both lanes use (lib/remote-machine-link.js).
+  preparePeerDial,
+  peerClientInfoFrame,
+  recordMirrorSession,
+  forgetMirrorSession,
+  getMirrorSessionMachine,
+  getLocalMirrorSession,
+  listMirrorSessions,
+  _resetMirrorSessionsForTests,
+};