create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/hub-bridge-mcp.js

@@ -0,0 +1,380 @@
+'use strict';
+
+// WP-3 (docs/remote-session-hub-bridge-2026-10-30.html §3 P-2, D-4/D-7, §5 R-4, §6.4, §8 WP-3):
+// the HUB-side MCP passthrough — the hub's OWN MCP servers, reached by a box session over the
+// WP-0 lane (lib/hub-bridge.js `handleRequest` -> lib/hub-bridge-ops.js `mcp.list` / `mcp.call`).
+//
+// Two servers are reachable, and only two:
+//
+//   playwright       the Wall-E MCP gateway's Playwright server, over Streamable HTTP at
+//                    http://127.0.0.1:<WALLE_MCP_GATEWAY_PORT|3458>/mcp/playwright. A SEPARATE
+//                    automation browser — good for localhost pages, never the user's own Chrome.
+//   chrome-devtools  chrome-devtools-mcp --autoConnect, spawned with `npx`, attached to the USER'S
+//                    real Chrome (Chrome asks the user to allow the attach the first time).
+//
+// Everything else is `mcp_server_not_allowed`: the allowlist is a frozen constant
+// (`serverConfigs(env)`), NOT a caller-supplied command line, so a box can never talk this process
+// into spawning an arbitrary server (that is `exec`'s job, behind its own, separate grant).
+//
+// D-4/§6.4: ONE connected MCP `Client` per server name, created LAZILY on first use and closed
+// after `idleMs` (default 10 min) of inactivity or by `closeAll()` (server.js shutdown). The idle
+// timer is unref'd so it never keeps the process alive. The connect is bounded by `connectTimeoutMs`
+// (default 15 s): a dead gateway answers `mcp_server_unavailable` quickly instead of hanging the
+// box's tool call until its own deadline.
+//
+// The SDK is required LAZILY (see `_sdk`) so a node_modules hiccup cannot break CTM boot, and every
+// seam is injectable (`configure`) — the integration test drives a stub Streamable-HTTP server on a
+// leased port and NEVER touches the real 3458 gateway or a real Chrome.
+
+const DEFAULT_GATEWAY_PORT = 3458;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+const DEFAULT_IDLE_MS = 10 * 60 * 1000;
+// §6.4/R-8: the lane caps a result at 1 MiB. The bridge enforces the same ceiling a second time
+// (lib/hub-bridge.js `_capResult`), but truncating HERE is what keeps an oversized image payload
+// from ever being serialised into a frame — the module says `truncated: true` when it does.
+const RESULT_MAX_BYTES = 1024 * 1024;
+
+// OQ-1/anti-goal: "chrome-devtools-mcp version drift. Pin the version, and update it deliberately."
+// `npm view chrome-devtools-mcp version` -> 1.12.0 at the time of writing (2026-10-30).
+const CHROME_DEVTOOLS_MCP_VERSION = '1.12.0';
+
+const GLOBAL_TIMERS = Object.freeze({
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (timer) => clearTimeout(timer),
+});
+
+/** The gateway port: `WALLE_MCP_GATEWAY_PORT` when it parses to a positive number, else 3458. */
+function resolveGatewayPort(env = process.env) {
+  const port = Number(env && env.WALLE_MCP_GATEWAY_PORT);
+  return Number.isFinite(port) && port > 0 ? port : DEFAULT_GATEWAY_PORT;
+}
+
+/**
+ * The frozen allowlist (§6.4). Built from `env` so the gateway port is never hard-coded at the call
+ * site; tests inject their own `serverConfigs` instead of overriding this one.
+ */
+function serverConfigs(env = process.env) {
+  const port = resolveGatewayPort(env);
+  return Object.freeze({
+    playwright: Object.freeze({
+      transport: 'http',
+      url: `http://127.0.0.1:${port}/mcp/playwright`,
+    }),
+    'chrome-devtools': Object.freeze({
+      transport: 'stdio',
+      command: 'npx',
+      args: Object.freeze(['-y', `chrome-devtools-mcp@${CHROME_DEVTOOLS_MCP_VERSION}`, '--autoConnect']),
+    }),
+  });
+}
+
+const DEFAULT_DEPS = {
+  env: process.env,
+  // (env) => frozen allowlist. Tests replace this to point at a stub server.
+  serverConfigs: null,
+  connectTimeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+  idleMs: DEFAULT_IDLE_MS,
+  timers: GLOBAL_TIMERS,
+  // { Client, StreamableHTTPClientTransport, StdioClientTransport } — injected by tests, else lazily
+  // required from @modelcontextprotocol/sdk (see `_sdk`).
+  sdk: null,
+};
+
+let _deps = null;
+// name -> { client, transport, timer, connecting }. One connected client per server name.
+const _entries = new Map();
+let _sdkCache = null;
+
+function configure(deps = {}) {
+  _deps = { ...DEFAULT_DEPS, ...(deps || {}) };
+  return _deps;
+}
+
+function _d() {
+  return _deps || DEFAULT_DEPS;
+}
+
+function _timers() {
+  const timers = _d().timers;
+  return timers && typeof timers.setTimeout === 'function' ? timers : GLOBAL_TIMERS;
+}
+
+/** The allowlist in force: the injected builder when present, else `serverConfigs(env)`. */
+function _configs() {
+  const d = _d();
+  const build = typeof d.serverConfigs === 'function' ? d.serverConfigs : serverConfigs;
+  const configs = build(d.env);
+  return configs && typeof configs === 'object' ? configs : {};
+}
+
+/** The SDK, required lazily and memoized; tests inject `deps.sdk` instead. */
+function _sdk() {
+  const injected = _d().sdk;
+  if (injected && typeof injected === 'object') return injected;
+  if (!_sdkCache) {
+    _sdkCache = {
+      Client: require('@modelcontextprotocol/sdk/client/index.js').Client,
+      StreamableHTTPClientTransport: require('@modelcontextprotocol/sdk/client/streamableHttp.js').StreamableHTTPClientTransport,
+      StdioClientTransport: require('@modelcontextprotocol/sdk/client/stdio.js').StdioClientTransport,
+    };
+  }
+  return _sdkCache;
+}
+
+/** A refusal as this module speaks it: the code rides the error, never the message. */
+function _namedError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/** `mcp_server_unavailable` carrying the FIRST LINE of the underlying error (§6.3). */
+function _unavailable(name, error) {
+  const raw = String((error && error.message) || error || 'unknown error');
+  const firstLine = raw.split('\n')[0].trim().slice(0, 300);
+  return _namedError('mcp_server_unavailable', `${name}: ${firstLine || 'connection failed'}`);
+}
+
+function _createTransport(config, sdk) {
+  const kind = String((config && config.transport) || '');
+  if (kind === 'http') {
+    return new sdk.StreamableHTTPClientTransport(new URL(String(config.url)));
+  }
+  if (kind === 'stdio') {
+    const args = Array.isArray(config.args) ? [...config.args] : [];
+    return new sdk.StdioClientTransport({ command: String(config.command), args });
+  }
+  throw _namedError('mcp_server_unavailable', `unsupported transport: ${kind || '(none)'}`);
+}
+
+/** Unref a timer when the runtime gave us a real one (a fake timer in a test simply has no unref). */
+function _unref(timer) {
+  if (timer && typeof timer.unref === 'function') {
+    try { timer.unref(); } catch { /* expected: a fake timer has no unref */ }
+  }
+  return timer;
+}
+
+/** (Re)arm the idle close for `name`. Every successful use pushes the close out by `idleMs`. */
+function _armIdle(name, entry) {
+  const { setTimeout: setT, clearTimeout: clrT } = _timers();
+  if (entry.timer) {
+    try { clrT(entry.timer); } catch { /* expected: the timer already fired */ }
+  }
+  const idleMs = Math.max(1, Number(_d().idleMs) || DEFAULT_IDLE_MS);
+  entry.timer = _unref(setT(() => {
+    // Idle close is fire-and-forget: a failure here must never surface as an unhandled rejection.
+    closeServer(name).catch(() => { /* expected: a client that already died has nothing to close */ });
+  }, idleMs));
+  return entry.timer;
+}
+
+/**
+ * Connect one MCP client for `name`. The connect is raced against `connectTimeoutMs` so a dead or
+ * unresponsive server answers `mcp_server_unavailable` at the deadline rather than hanging.
+ */
+async function _connect(name, config, entry) {
+  const sdk = _sdk();
+  const { setTimeout: setT, clearTimeout: clrT } = _timers();
+  let transport;
+  try {
+    transport = _createTransport(config, sdk);
+  } catch (error) {
+    throw _unavailable(name, error);
+  }
+  const client = new sdk.Client({ name: 'ctm-hub-bridge', version: '1.0.0' }, { capabilities: {} });
+  const timeoutMs = Math.max(1, Number(_d().connectTimeoutMs) || DEFAULT_CONNECT_TIMEOUT_MS);
+  let timer = null;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = _unref(setT(() => reject(_namedError('mcp_server_unavailable', `${name}: connect timed out after ${timeoutMs} ms`)), timeoutMs));
+  });
+  try {
+    await Promise.race([client.connect(transport), timeout]);
+  } catch (error) {
+    try { clrT(timer); } catch { /* expected: the timeout already fired */ }
+    try { await client.close(); } catch { /* expected: a failed connect may leave nothing to close */ }
+    try { await transport.close(); } catch { /* expected: the transport may already be closed */ }
+    throw error && error.code === 'mcp_server_unavailable' ? error : _unavailable(name, error);
+  }
+  try { clrT(timer); } catch { /* expected: the timeout already cleared itself */ }
+  entry.client = client;
+  entry.transport = transport;
+  _armIdle(name, entry);
+  return client;
+}
+
+/**
+ * The connected client for `server`, connecting lazily on first use. Unknown server ->
+ * `mcp_server_not_allowed`; a connect/spawn failure -> `mcp_server_unavailable`.
+ */
+async function _clientFor(server) {
+  const name = String(server || '');
+  const config = _configs()[name];
+  if (!config) {
+    throw _namedError('mcp_server_not_allowed', `MCP server '${name || '(none)'}' is not in the hub allowlist`);
+  }
+  const existing = _entries.get(name);
+  if (existing) {
+    if (existing.client) {
+      _armIdle(name, existing);
+      return existing.client;
+    }
+    if (existing.connecting) return existing.connecting;
+  }
+  const fresh = existing || { client: null, transport: null, timer: null, connecting: null };
+  _entries.set(name, fresh);
+  fresh.connecting = _connect(name, config, fresh);
+  try {
+    const client = await fresh.connecting;
+    fresh.connecting = null;
+    return client;
+  } catch (error) {
+    fresh.connecting = null;
+    // A failed connect must not leave a half-open entry behind: the next call retries from scratch.
+    if (_entries.get(name) === fresh) _entries.delete(name);
+    throw error;
+  }
+}
+
+/**
+ * A THROWN list/call error is a protocol or transport failure (a tool's own failure comes back as
+ * `isError` in the result), so the cached client is dead: drop it, so the next call reconnects
+ * instead of reusing it until the idle close (which every retry would keep pushing out).
+ */
+async function _evict(name, client) {
+  const entry = _entries.get(name);
+  if (entry && entry.client === client) await closeServer(name);
+}
+
+/** §6.4: the tool list of one allowlisted server, projected to `{name, description, inputSchema}`. */
+async function listTools(server) {
+  const client = await _clientFor(server);
+  let result;
+  try {
+    result = await client.listTools();
+  } catch (error) {
+    await _evict(String(server || ''), client);
+    throw _unavailable(String(server || ''), error);
+  }
+  const tools = result && Array.isArray(result.tools) ? result.tools : [];
+  return tools.map((tool) => ({
+    name: String((tool && tool.name) || ''),
+    description: tool && tool.description !== undefined ? String(tool.description) : undefined,
+    inputSchema: (tool && tool.inputSchema) || { type: 'object' },
+  }));
+}
+
+/**
+ * §6.4: call one tool on one allowlisted server, returning the MCP result `{content, isError}` with
+ * `truncated: true` when the 1 MiB ceiling forced a payload to be trimmed or dropped.
+ */
+async function callTool(server, tool, args) {
+  const name = String(server || '');
+  const client = await _clientFor(name);
+  const toolName = String(tool || '');
+  if (!toolName) throw _namedError('mcp_tool_required', 'tool is required');
+  let result;
+  try {
+    result = await client.callTool({
+      name: toolName,
+      arguments: args && typeof args === 'object' ? args : {},
+    });
+  } catch (error) {
+    await _evict(name, client);
+    throw _unavailable(name, error);
+  }
+  return _capResult(result);
+}
+
+/**
+ * The 1 MiB ceiling (§6.4/R-8). Under the cap the result is returned as-is; over it, content items
+ * are kept while they fit, a `text` item is sliced to fit, and anything else (image/blob data) is
+ * dropped — `truncated: true` says so, and the bridge's own `_capResult` is the second guard.
+ */
+function _capResult(result) {
+  const value = result && typeof result === 'object' ? result : {};
+  const isError = value.isError === true;
+  const content = Array.isArray(value.content) ? value.content : [];
+  let serialised;
+  try {
+    serialised = JSON.stringify({ ...value, content });
+  } catch {
+    // REPORT via truncated: a non-serialisable result can never cross the lane — say so rather than throw.
+    return { content: [{ type: 'text', text: '[hub MCP result was not serialisable]' }], isError, truncated: true };
+  }
+  if (Buffer.byteLength(serialised, 'utf8') <= RESULT_MAX_BYTES) return { content, isError };
+
+  const out = { content: [], isError, truncated: true };
+  let used = Buffer.byteLength(JSON.stringify(out), 'utf8');
+  for (const item of content) {
+    let text;
+    try {
+      text = JSON.stringify(item);
+    } catch {
+      continue; // expected: an unserialisable item is dropped; `truncated` already carries the truth
+    }
+    const bytes = Buffer.byteLength(text, 'utf8');
+    const budget = RESULT_MAX_BYTES - used;
+    if (bytes <= budget) {
+      out.content.push(item);
+      used += bytes;
+      continue;
+    }
+    if (item && item.type === 'text' && typeof item.text === 'string' && budget > 128) {
+      const narrowed = { ...item, text: Buffer.from(item.text, 'utf8').subarray(0, budget - 128).toString('utf8') };
+      out.content.push(narrowed);
+      used += Buffer.byteLength(JSON.stringify(narrowed), 'utf8');
+    }
+    // An image/blob item that cannot fit is dropped whole (its bytes are not sliceable mid-base64).
+  }
+  return out;
+}
+
+/** Close the client for `name`, clearing its idle timer. Safe to call when nothing is open. */
+async function closeServer(server) {
+  const name = String(server || '');
+  const entry = _entries.get(name);
+  if (!entry) return false;
+  _entries.delete(name);
+  if (entry.timer) {
+    try { _timers().clearTimeout(entry.timer); } catch { /* expected: the timer already fired */ }
+  }
+  try { if (entry.client) await entry.client.close(); } catch { /* expected: a dead client has nothing to close */ }
+  try { if (entry.transport && typeof entry.transport.close === 'function') await entry.transport.close(); } catch { /* expected: the transport may already be closed */ }
+  return true;
+}
+
+/** Close every connected client (server.js shutdown). Never throws. */
+async function closeAll() {
+  const names = [..._entries.keys()];
+  // closeServer() already swallows everything it can; the extra guard is only so one dead client
+  // can never stop the others from closing.
+  await Promise.all(names.map((name) => closeServer(name).catch(() => { /* expected: one dead client must not block the rest */ })));
+  _entries.clear();
+}
+
+/** Open server names — the test seam for "the client really closed after idle". */
+function _openServers() {
+  return [..._entries.keys()].sort();
+}
+
+function _resetForTests() {
+  _deps = null;
+  _entries.clear();
+  _sdkCache = null;
+}
+
+module.exports = {
+  CHROME_DEVTOOLS_MCP_VERSION,
+  DEFAULT_CONNECT_TIMEOUT_MS,
+  DEFAULT_GATEWAY_PORT,
+  DEFAULT_IDLE_MS,
+  RESULT_MAX_BYTES,
+  resolveGatewayPort,
+  serverConfigs,
+  configure,
+  listTools,
+  callTool,
+  closeServer,
+  closeAll,
+  _openServers,
+  _resetForTests,
+};

package/template/coding-task-manager/lib/hub-bridge-mesh.js

@@ -0,0 +1,313 @@
+'use strict';
+
+// WP-5 (docs/remote-session-hub-bridge-2026-10-30.html §5 R-12, D-9, §8 AC-5a): trusted-pool mesh links.
+//
+// R-12 says the bridge is SYMMETRIC: a member's role (hub or box) comes only from who opened the
+// CONTROL link, so any member can serve a request. This module is what makes that reachable without a
+// new listener: the CTM keeps a CONTROL link OPEN (lib/remote-machine-link.js `openLink`) to every
+// pool member it TRUSTS ('always', R-11 — a per-machine row, else the file default), so every trusted
+// member can ask every other one.
+//
+//   reconcile()  desired = rosterMembers() - self, filtered by trustFor(id) === 'always'
+//                for each desired member whose registry row is enabled + reachable:
+//                  openLink(row)   (idempotent — the link module reuses a live control link)
+//                  fetchCatalog(row) once, so the R-2 ownership check knows that member's sessions
+//                links THIS module opened for a member that is no longer desired are closed
+//                (closeLink); a link it did not open is never touched.
+//                A member that cannot be reached simply has no link — the 30 s tick is the retry,
+//                so there is no per-member reconnect storm here.
+//
+// The link module's own 60 s idle close is a non-issue by construction: reconcile runs every 30 s and
+// each fetchCatalog is a catalog user, which clears the idle timer. A machine that the operator stops
+// trusting drops out of the desired set on the next tick and its link is closed by us at once; an
+// untrusted-by-default pool (the default 'ask') opens nothing at all (D-9: "an untrusted one keeps
+// per-session asks").
+//
+// Everything is injectable so the unit test never boots a server, opens a socket or reads a db.
+
+const { boolFlag, registerFlag } = require('./env-flags');
+
+const MESH_INTERVAL_MS = 30000;
+
+// Default ON (design §5 R-12 / §8 WP-5): `CTM_HUB_BRIDGE_MESH=0` keeps the pre-WP-5 behaviour — only
+// the links something else asked for (a viewer, a create, a catalog sweep) exist.
+registerFlag('CTM_HUB_BRIDGE_MESH', {
+  kind: 'bool',
+  default: true,
+  desc: 'Trusted-pool mesh links: keep a CONTROL link to every pool member this machine trusts (\'always\'), so any trusted member can serve any other (docs/remote-session-hub-bridge-2026-10-30.html R-12); 0 disables the mesh',
+});
+
+function _string(value, max = 200) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+// Production defaults. Every one of them is a lazy require, so a unit test that injects its own deps
+// never loads the link/catalog/pool modules (the lib/** dependency-cycle ceiling and the hermetic rule).
+const DEFAULT_DEPS = {
+  selfInstanceId: () => '',
+  rosterMembers: () => require('./api/machine-pool').rosterMembers(),
+  trustFor: (machineInstanceId) => require('./hub-bridge-access').trustFor(machineInstanceId),
+  machineRow: (machineInstanceId) => {
+    const rows = require('./remote-machine-catalog').machineRows() || [];
+    const id = _string(machineInstanceId, 160);
+    return rows.find((row) => _string(row && row.instanceId, 160) === id) || null;
+  },
+  openLink: (row, deps) => require('./remote-machine-link').openLink(row, deps),
+  linkFor: (machineInstanceId) => require('./remote-machine-link').linkFor(machineInstanceId),
+  closeLink: (link, deps) => require('./remote-machine-link').closeLink(link, deps),
+  fetchCatalog: (machineOrId, deps) => require('./remote-machine-catalog').fetchCatalog(machineOrId, deps),
+  setIntervalFn: (fn, ms) => setInterval(fn, ms),
+  clearIntervalFn: (timer) => clearInterval(timer),
+  log: console,
+};
+
+let _deps = null;
+let _timer = null;
+// machineInstanceId -> the link THIS module opened. Only rows in here are ever closed by stop() or
+// by a reconcile that no longer desires the member (R-12: never close a link we did not open).
+const _opened = new Map();
+
+function configure(deps = {}) {
+  _deps = { ...DEFAULT_DEPS, ...(deps || {}) };
+  return _deps;
+}
+
+function _d() {
+  return _deps || DEFAULT_DEPS;
+}
+
+/** Flag read at CALL time so a test can flip CTM_HUB_BRIDGE_MESH per-process (never at module load). */
+function isEnabled() {
+  return boolFlag('CTM_HUB_BRIDGE_MESH', true);
+}
+
+function _report(message) {
+  const log = _d().log;
+  if (log && typeof log.warn === 'function') log.warn(`[hub-bridge-mesh] ${message}`);
+}
+
+/**
+ * The members this machine wants a mesh link to: every OTHER pool member whose trust is 'always'
+ * (R-11 — `trustFor` already falls back to the file default, so `default:'always'` covers every
+ * member). A roster or trust fault reads as "not desired" (fail to the ask flow, never to ambient
+ * trust), and self is always excluded.
+ */
+function desiredMembers() {
+  const d = _d();
+  let roster = [];
+  try {
+    roster = d.rosterMembers() || [];
+  } catch (error) {
+    _report(`roster read failed: ${error && error.message ? error.message : error}`);
+    return [];
+  }
+  const self = _string(typeof d.selfInstanceId === 'function' ? d.selfInstanceId() : '', 160);
+  const out = [];
+  for (const member of Array.isArray(roster) ? roster : []) {
+    const id = _string(member && member.instanceId, 160);
+    if (!id || id === self || out.includes(id)) continue;
+    let trust = 'ask';
+    try {
+      trust = _string(d.trustFor(id), 40) || 'ask';
+    } catch (error) {
+      trust = 'ask'; // REPORT via the skip: an unreadable trust file is not a grant (R-11)
+      _report(`trust read failed for ${id}: ${error && error.message ? error.message : error}`);
+    }
+    if (trust === 'always') out.push(id);
+  }
+  return out;
+}
+
+function _rowFor(machineInstanceId) {
+  const d = _d();
+  if (typeof d.machineRow !== 'function') return null;
+  try {
+    return d.machineRow(machineInstanceId) || null;
+  } catch (error) {
+    _report(`machine row read failed for ${machineInstanceId}: ${error && error.message ? error.message : error}`);
+    return null;
+  }
+}
+
+/**
+ * A row this module may dial: registered, enabled and judged reachable by the probe sweep. `unknown`
+ * is NOT dialable here — the mesh must not keep a link (and a 30 s retry) for a machine the registry
+ * has never proved, which is what keeps a NAT-blocked member at zero cost.
+ */
+function _dialable(row) {
+  if (!row) return false;
+  if (row.enabled === false || row.enabled === 0) return false;
+  return _string(row.health, 40) === 'reachable';
+}
+
+/** The link this module currently holds for `machineInstanceId`, or null when it holds none. */
+function _heldLink(machineInstanceId) {
+  const mine = _opened.get(machineInstanceId);
+  if (!mine || mine.closed) return null;
+  const d = _d();
+  let current = null;
+  try {
+    current = typeof d.linkFor === 'function' ? d.linkFor(machineInstanceId) : null;
+  } catch {
+    current = null; // expected: an unreadable link map means "cannot prove it is still ours"
+  }
+  // Only the link we opened, and only while the link module still publishes it for this machine.
+  return !current || current === mine ? mine : null;
+}
+
+function _closeHeld(machineInstanceId, link) {
+  _opened.delete(machineInstanceId);
+  const d = _d();
+  try {
+    d.closeLink(link);
+    return true;
+  } catch (error) {
+    _report(`close failed for ${machineInstanceId}: ${error && error.message ? error.message : error}`);
+    return false;
+  }
+}
+
+/** One catalog fetch, fire-and-forget: a failed fetch is `{ok:false}` by contract, never a throw. */
+function _fetchOnce(row) {
+  const d = _d();
+  try {
+    const pending = d.fetchCatalog(row);
+    if (pending && typeof pending.then === 'function') {
+      return pending.then(
+        (result) => result,
+        (error) => ({ ok: false, code: 'machine_unreachable', error: _string(error && error.message, 300) }),
+      );
+    }
+  } catch (error) {
+    // REPORT via the resolved value: the link is up, the list is a freshness bonus (R-2 owns the rest).
+    return Promise.resolve({ ok: false, code: 'machine_unreachable', error: _string(error && error.message, 300) });
+  }
+  return Promise.resolve({ ok: false, code: 'machine_unreachable', error: 'catalog_not_wired' });
+}
+
+/**
+ * One pass: close what is no longer desired, open (and refresh) what is. Never throws — a reconcile
+ * runs on a timer, and a fault in one member must not stop the others. Resolves to a small summary
+ * (`{ok, enabled, linked, closed}`) for tests and diagnostics.
+ */
+async function reconcile() {
+  if (!isEnabled()) {
+    // The flag is the operator's "no mesh" switch: links this module opened are released, links it
+    // did not open are untouched.
+    const released = [];
+    for (const [id, link] of [..._opened]) {
+      if (_closeHeld(id, link)) released.push(id);
+    }
+    return { ok: true, enabled: false, linked: [], closed: released };
+  }
+
+  const desired = desiredMembers();
+  const closed = [];
+  for (const [id, link] of [..._opened]) {
+    if (desired.includes(id)) continue;
+    if (_closeHeld(id, link)) closed.push(id);
+  }
+
+  const linked = [];
+  const fetches = [];
+  for (const id of desired) {
+    const held = _heldLink(id);
+    const row = _rowFor(id);
+    if (!held && !_dialable(row)) continue; // no link, and no attempt until the next tick
+    if (held) {
+      // Keep the link warm (and the member's session list fresh) — see the header on the idle close.
+      linked.push(id);
+      fetches.push(_fetchOnce(row || id));
+      continue;
+    }
+    // openLink REUSES a link that already exists for this machine (the catalog's or a relay's). A
+    // link someone else opened is used, never adopted: recording it as ours would let a later trust
+    // flip close a link the catalog or a live viewer depends on.
+    let existing = null;
+    try {
+      existing = typeof _d().linkFor === 'function' ? _d().linkFor(id) : null;
+    } catch {
+      existing = null; // expected: an unreadable link map reads as "no link yet"
+    }
+    if (existing) {
+      linked.push(id);
+      fetches.push(_fetchOnce(row));
+      continue;
+    }
+    let link = null;
+    try {
+      link = _d().openLink(row);
+    } catch (error) {
+      _report(`openLink failed for ${id}: ${error && error.message ? error.message : error}`);
+      link = null;
+    }
+    if (!link) continue;
+    _opened.set(id, link);
+    linked.push(id);
+    // R-2: learn that member's sessions once the link exists — the ownership check needs them.
+    fetches.push(_fetchOnce(row));
+  }
+  await Promise.allSettled(fetches);
+  return { ok: true, enabled: true, linked, closed };
+}
+
+/**
+ * Start the mesh: one reconcile now (so a boot with links already trusted does not wait a tick), then
+ * one unref'd 30 s interval. Idempotent — a second start() while running is a no-op.
+ */
+function start() {
+  if (_timer) return;
+  reconcile().catch(() => {
+    // expected: reconcile never rejects; a defensive catch keeps a timer callback from throwing.
+  });
+  const d = _d();
+  const timer = d.setIntervalFn(() => {
+    reconcile().catch(() => {
+      // expected: as above — a tick is fire-and-forget.
+    });
+  }, MESH_INTERVAL_MS);
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  _timer = timer;
+}
+
+/** Stop the mesh: clear the tick and release every link this module opened. */
+function stop() {
+  const d = _d();
+  if (_timer) {
+    try {
+      d.clearIntervalFn(_timer);
+    } catch {
+      // expected: the injected timer is already cleared.
+    }
+    _timer = null;
+  }
+  for (const [id, link] of [..._opened]) _closeHeld(id, link);
+}
+
+function isRunning() {
+  return !!_timer;
+}
+
+/** The machine ids this module currently holds a mesh link to (diagnostics + tests). */
+function openedMachineIds() {
+  return [..._opened.keys()].sort();
+}
+
+function _resetForTests() {
+  stop();
+  _deps = null;
+  _opened.clear();
+}
+
+module.exports = {
+  MESH_INTERVAL_MS,
+  configure,
+  isEnabled,
+  desiredMembers,
+  reconcile,
+  start,
+  stop,
+  isRunning,
+  openedMachineIds,
+  _resetForTests,
+};