@bahulam/code 0.1.2 → 0.1.4

package/src/daemon/event-tap.mjs

@@ -0,0 +1,197 @@
+/**
+ * Event tap — bridges SSE events from the agent loop to the relay.
+ *
+ * Each SSE event type is mapped to a relay event type. The mapping
+ * is a fixed table. Keeping it centralized avoids scattering
+ * relay-specific concerns across the agent loop. *   • Cache-invariance ( §7): this tap is READ-ONLY on the SSE
+ *     event. It never mutates `event`, never changes what stream-client
+ *     yields, and writes to a local file only. `/api/execute` body is
+ *     untouched.
+ *
+ * NOT in scope for .3:
+ *   • Broadcasting events to attached socket clients (.4).
+ *   • Compact snapshot writing (.4 — the daemon supervisor
+ *     decides when to snapshot; the tap doesn't).
+ *   • Deriving  events that don't have a direct SSE origin
+ *     (e.g. `attach_joined`, `input_lock_changed` — those come from
+ *     the socket server, not the SSE stream).
+ */
+
+import { createEventLog } from '../core/event-log.mjs';
+
+// ── env-var gate ─────────────────────────────────────────────────────
+
+function _enabled() {
+  const v = process.env.BAHULAM_DAEMON_EVENTLOG;
+  return v === '1' || v === 'true';
+}
+
+// ── per-session lazy log holder ──────────────────────────────────────
+//
+// One active log at a time. Session id change (via new turn's session_info)
+// closes the old log and opens a new one. `_current` is null when the tap
+// hasn't seen a session id yet — session_info events don't always arrive
+// before other events do, so we buffer nothing and simply drop events
+// that arrive before the id is known. First real event a re-attach sees
+// is session_started; anything before that is renderer-only anyway.
+
+let _current = null;  // { sessionId, log }
+
+function _openLogFor(sessionId) {
+  if (_current && _current.sessionId === sessionId) return _current.log;
+  if (_current) {
+    // Fire-and-forget close on the previous log. The write chain resolves
+    // internally; we don't await here because tapSseEvent is called from
+    // a hot loop that can't afford to block.
+    try { _current.log.close().catch(() => {}); } catch { /* ignore */ }
+  }
+  const log = createEventLog({ sessionId });
+  _current = { sessionId, log };
+  return log;
+}
+
+/** Test / bahulam-stop hook — close the active log and drop the ref. */
+export async function closeActiveEventLog() {
+  if (!_current) return;
+  const { log } = _current;
+  _current = null;
+  try { await log.close(); } catch { /* ignore */ }
+  _broadcasters.length = 0;
+}
+
+// ── broadcasters (.4) ─────────────────────────────────────────
+//
+// The socket server registers itself here so live events fan out to
+// attached clients as they're written to the durable log. Broadcasters
+// are fire-and-forget; a slow/broken one MUST NOT slow down or block
+// the tap. Each broadcaster is invoked in its own try/catch.
+//
+// Registration is process-global (one bahulamd = one process = one tap
+// registry). Multiple socket servers CAN register; the tap doesn't care.
+
+const _broadcasters = [];
+
+/**
+ * Register a broadcaster. Returns an unregister function.
+ * The broadcaster receives the fully-formed  event AFTER it has
+ * been written to the log (so `seq` and `ts` are populated).
+ */
+export function registerBroadcaster(fn) {
+  if (typeof fn !== 'function') throw new Error('registerBroadcaster: fn must be a function');
+  _broadcasters.push(fn);
+  return () => {
+    const i = _broadcasters.indexOf(fn);
+    if (i >= 0) _broadcasters.splice(i, 1);
+  };
+}
+
+// ── SSE →  event mapping ──────────────────────────────────────
+//
+// Table (protocol spec §5.1). Only events that map to a first-class
+//  type are logged. Everything else (status, thinking with
+// empty text, phase_update, worker_update, etc.) is renderer-transient
+// and doesn't belong in a durable event log.
+
+const SSE_TO_PRD092 = Object.freeze({
+  session_info:       'session_started',
+  turn_started:       'turn_started',
+  turn_ended:         'turn_ended',
+  thinking:           'thinking_delta',
+  tool_request:       'tool_call',
+  tool_call:          'tool_call',
+  tool_result:        'tool_result',
+  tool_done:          'tool_result',
+  approval_required:  'approval_required',
+  approval_decided:   'approval_decided',
+  file_diff:          'diff',
+  diff:               'diff',
+  test_result:        'test_result',
+  tokens_used:        'tokens_used',
+  usage_update:       'usage_update',
+  complete:           'agent_complete',
+});
+
+// Some SSE event bodies carry more than we want to log. Trim what makes
+// sense per type so we don't bloat the log with, e.g., a 200KB rendered
+// tool output when a summary would do. Everything else round-trips as-is.
+function _projectData(prd092Type, data) {
+  const src = data || {};
+  switch (prd092Type) {
+    case 'tool_call':
+      return {
+        name: src.tool || src.name,
+        tool_id: src.tool_call_id || src.tool_id || src.id,
+        args: src.args || src.tool_input || src.input || {},
+        subagent_id: src.subagent_id || undefined,
+        cwd: src.cwd || undefined,
+      };
+    case 'tool_result':
+      return {
+        tool_id: src.tool_call_id || src.tool_id || src.id,
+        ok: src.error ? false : (src.ok !== false),
+        summary: typeof src.output === 'string'
+          ? src.output.slice(0, 4096)
+          : (src.summary || undefined),
+        duration_ms: src.duration_ms || src.durationMs || undefined,
+        output_truncated: typeof src.output === 'string' && src.output.length > 4096 ? true : undefined,
+      };
+    case 'thinking_delta':
+      return { chunk: src.message || src.text || '' };
+    case 'session_started':
+      return {
+        cwd: src.cwd,
+        model: src.model,
+        product: src.product,
+        session_id_from_backend: src.session_id,
+      };
+    case 'agent_complete':
+      return { ok: src.error == null, summary: src.summary, duration_ms: src.duration_ms };
+    default:
+      return src;
+  }
+}
+
+// ── the tap ──────────────────────────────────────────────────────────
+
+/**
+ * Tap one SSE event to the  event log.
+ *
+ * @param {{type: string, data?: object}} event  the SSE frame from stream-client
+ * @param {object} opts
+ * @param {string} opts.sessionId  from session.id — required for log routing
+ * @param {string} [opts.turnId]   optional; stamped on turn-scoped events
+ *
+ * Failure modes are ALL silent — a broken tap must never affect the
+ * user-facing render path. If the env var isn't set or sessionId is
+ * missing we skip; if the file write throws internally, event-log.mjs
+ * logs to stderr and drops the event.
+ */
+export function tapSseEvent(event, { sessionId, turnId } = {}) {
+  if (!_enabled()) return;
+  if (!event || !event.type || !sessionId) return;
+  const prd092Type = SSE_TO_PRD092[event.type];
+  if (!prd092Type) return;
+  const log = _openLogFor(sessionId);
+  const data = _projectData(prd092Type, event.data);
+  let seq;
+  try {
+    seq = log.writeEvent(prd092Type, data, turnId ? { turnId } : undefined);
+  } catch (err) {
+    try { process.stderr.write(`[event-tap] writeEvent failed: ${err.message}\n`); } catch {}
+    return;
+  }
+  if (_broadcasters.length === 0) return;
+  const wireEvent = {
+    seq,
+    ts: new Date().toISOString(),
+    type: prd092Type,
+    session_id: sessionId,
+    v: 1,
+    ...(turnId ? { turn_id: turnId } : {}),
+    data,
+  };
+  for (const fn of _broadcasters) {
+    try { fn(wireEvent); }
+    catch (err) { try { process.stderr.write(`[event-tap] broadcaster failed: ${err.message}\n`); } catch {} }
+  }
+}

package/src/daemon/input-lock.mjs

@@ -0,0 +1,191 @@
+/**
+ *   — Input lock state (multi-attach input arbitration).
+ *
+ * Per PRD §6.5:
+ *   - The first attach implicitly holds the input lock.
+ *   - Later attaches join in WATCH mode (may render events, may
+ *     approve/deny, may NOT send_message / interrupt / switch_model).
+ *   - `take_input_lock` triggers a STEAL WITH GRACE:
+ *       1. Emit input_lock_changed { holder: current, pending_transfer: att_new }
+ *       2. Current holder has 3s to release_input_lock gracefully
+ *       3. After 3s (or on release) → holder := att_new,
+ *          emit input_lock_changed { holder: att_new }
+ *   - Approvals bypass the lock. That's an authorization act, not
+ *     a typing act; enforced by the socket-server, not this module.
+ *
+ * State model:
+ *   holder      : attach_id | null      currently owns typing input
+ *   since       : ISO-8601 UTC          when holder was assigned
+ *   pending     : attach_id | null      the challenger waiting on a steal
+ *   pendingTimer: NodeTimeout | null    the 3s grace timer
+ *
+ * All mutations go through the exported functions so the emitters
+ * (repl.mjs wiring) always publish an `input_lock_changed` event.
+ */
+
+const GRACE_MS = 3000;
+
+const _state = {
+  holder: null,        // attach_id | null
+  since: null,         // ISO string
+  pending: null,       // attach_id | null
+  pendingTimer: null,  // NodeTimeout | null
+};
+
+let _emit = null;      // (type, data) → void — set by wireEmit()
+
+/**
+ * Wire the event emitter. The daemon (repl.mjs) sets this to a function
+ * that writes to the event tap so `input_lock_changed` fans out to all
+ * attached clients.
+ */
+export function wireEmit(emitFn) {
+  _emit = typeof emitFn === 'function' ? emitFn : null;
+}
+
+function _now() { return new Date().toISOString(); }
+
+function _publish(extra = {}) {
+  if (!_emit) return;
+  try {
+    _emit('input_lock_changed', {
+      holder: _state.holder,
+      since: _state.since,
+      pending_transfer: _state.pending,
+      ...extra,
+    });
+  } catch { /* never blocks a state change */ }
+}
+
+// ── attach lifecycle ─────────────────────────────────────────────────
+
+/**
+ * First attach auto-takes the lock. Later attaches join in watch mode.
+ * Call from the socket-server hello handler.
+ *
+ * @param {string} attachId
+ * @returns {{holder: string, kind: 'holder'|'watch'}}
+ */
+export function onAttachJoined(attachId) {
+  if (_state.holder == null) {
+    _state.holder = attachId;
+    _state.since = _now();
+    _publish();
+    return { holder: attachId, kind: 'holder' };
+  }
+  return { holder: _state.holder, kind: 'watch' };
+}
+
+/**
+ * If the leaving attach was the holder, transfer the lock — to the pending
+ * challenger if there is one, else to nobody (holder=null). If it was a
+ * watcher, no state change.
+ */
+export function onAttachLeft(attachId) {
+  const wasHolder = _state.holder === attachId;
+  const wasPending = _state.pending === attachId;
+  if (wasPending) _clearPending();
+  if (!wasHolder) return;
+  if (_state.pending) {
+    _state.holder = _state.pending;
+    _state.since = _now();
+    _clearPending();
+  } else {
+    _state.holder = null;
+    _state.since = null;
+  }
+  _publish();
+}
+
+// ── commands ─────────────────────────────────────────────────────────
+
+/**
+ * `take_input_lock` command — steal-with-grace protocol.
+ *
+ * If the requester is already the holder → no-op (return current state).
+ * If there's no holder → immediate takeover.
+ * Otherwise → set pending, schedule 3s timer to force-transfer.
+ *
+ * Returns the state after the request is processed (not after the
+ * grace timer fires).
+ */
+export function takeInputLock(attachId) {
+  if (_state.holder === attachId) {
+    return { holder: attachId, pending: null, immediate: true };
+  }
+  if (_state.holder == null) {
+    _state.holder = attachId;
+    _state.since = _now();
+    _publish();
+    return { holder: attachId, pending: null, immediate: true };
+  }
+  // Someone else already requested — drop their pending in favor of the
+  // newer one (last-writer-wins). Restart the grace timer.
+  _clearPending();
+  _state.pending = attachId;
+  _publish();
+  _state.pendingTimer = setTimeout(() => {
+    // Grace elapsed → force transfer. Read pending BEFORE _clearPending
+    // (which nulls it) so the check + assign happen against the value at
+    // schedule time, not the intermediate cleared state.
+    if (_state.pending !== attachId) return;  // preempted by another take
+    _state.holder = attachId;
+    _state.since = _now();
+    _state.pending = null;
+    _state.pendingTimer = null;
+    _publish();
+  }, GRACE_MS);
+  // No .unref(): we want the daemon event loop to be kept alive by a
+  // pending grace transfer. In tests, connected sockets already keep
+  // the loop alive, so no diff. In prod, this prevents a bahulamd whose
+  // ONLY outstanding work is a grace-steal from exiting mid-transfer.
+  return { holder: _state.holder, pending: attachId, immediate: false, graceMs: GRACE_MS };
+}
+
+/**
+ * `release_input_lock` command — the current holder yields.
+ * If there's a pending challenger, they take the lock immediately.
+ * If not, the lock becomes null (next `take_input_lock` from anyone wins).
+ */
+export function releaseInputLock(attachId) {
+  if (_state.holder !== attachId) return { ignored: true, reason: 'not_holder' };
+  if (_state.pending) {
+    _state.holder = _state.pending;
+    _state.since = _now();
+    _clearPending();
+  } else {
+    _state.holder = null;
+    _state.since = null;
+  }
+  _publish();
+  return { holder: _state.holder };
+}
+
+// ── query ────────────────────────────────────────────────────────────
+
+/** Read current lock state. Used by socket-server to enforce writes. */
+export function currentHolder() { return _state.holder; }
+export function isHolder(attachId) { return _state.holder === attachId; }
+
+/** For tests and `bahulam status`. */
+export function snapshot() {
+  return {
+    holder: _state.holder,
+    since: _state.since,
+    pending: _state.pending,
+  };
+}
+
+/** Reset (tests only, or on daemon shutdown). */
+export function resetInputLock() {
+  _clearPending();
+  _state.holder = null;
+  _state.since = null;
+}
+
+// ── internal ─────────────────────────────────────────────────────────
+
+function _clearPending() {
+  if (_state.pendingTimer) { clearTimeout(_state.pendingTimer); _state.pendingTimer = null; }
+  _state.pending = null;
+}

package/src/daemon/relay-client.mjs

@@ -0,0 +1,258 @@
+/**
+ * Relay WebSocket client — connects to the gateway relay and routes
+ * session events to attached CLI clients.
+ *
+ * On connect the client authenticates with a bearer token, then
+ * registers as a device on each active session. Events from the
+ * relay are dispatched to the appropriate session handler. *   • Heartbeat / keepalive via WebSocket ping (20s).
+ *   • Kill-switch check: BAHULAM_RELAY_KILL=1 env var, plus config
+ *     `remote.enabled = false` polled every 10s from the file so
+ *     `bahulam remote disable` in another terminal drops us fast.
+ *
+ * Deferred (Phase 2.5):
+ *   • ChaCha20-Poly1305 AEAD payload encryption. My envelope shape is
+ *     already compatible — swap the `control` field for `aead: {...}`
+ *     without changing the transport.
+ *   • X25519 wrap key derivation from paired peer_pubkeys.
+ *   • Signed command verification (Ed25519 signatures INSIDE the aead
+ *     payload per PRD §4).
+ *   • Session-key rotation.
+ *
+ * Non-fatal design principle: any relay error MUST NOT affect the local
+ * session. If the relay is down / unreachable / kicks us, the daemon
+ * keeps running for local attaches. Reconnect quietly in the background.
+ */
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+
+const HEARTBEAT_MS = 20_000;
+const REVOKE_POLL_MS = 10_000;
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_CAP_MS = 30_000;
+
+/**
+ * Start the relay bridge for a session. Returns { stop } — call to
+ * cleanly disconnect. Safe to call even without a valid config; if
+ * `remote.enabled = false` we log a note and return a stop() no-op.
+ *
+ * @param {object} opts
+ * @param {string}   opts.sessionId
+ * @param {object}   opts.remoteConfig    — from remote.mjs loadRemoteConfig()
+ * @param {Function} opts.registerBroadcaster — from event-tap.mjs
+ * @param {object}   opts.onCommand       — { approve, deny, interrupt, send_message, ... }
+ *                                            same shape as socket-server's onCommand.
+ */
+export function startRelayBridge({ sessionId, remoteConfig, registerBroadcaster, onCommand = {} } = {}) {
+  if (!remoteConfig?.enabled) {
+    return { stop: async () => {} };
+  }
+  if (!remoteConfig.device_id || !remoteConfig.token) {
+    process.stderr.write(`${YELLOW}[relay] remote enabled but device or token missing — skipping.${RESET}\n`);
+    return { stop: async () => {} };
+  }
+  if (typeof globalThis.WebSocket !== 'function') {
+    process.stderr.write(`${YELLOW}[relay] WebSocket not available in this Node runtime (need ≥22). Skipping.${RESET}\n`);
+    return { stop: async () => {} };
+  }
+
+  const url = _buildUrl(remoteConfig.relay_url, sessionId, remoteConfig.device_id, remoteConfig.token);
+  const state = {
+    stopped: false,
+    ws: null,
+    reconnectAttempt: 0,
+    heartbeatTimer: null,
+    revokeTimer: null,
+    unregisterBroadcaster: null,
+  };
+
+  function _log(msg) {
+    try { process.stderr.write(`${DIM}[relay] ${msg}${RESET}\n`); } catch {}
+  }
+
+  function _envelope(controlBody, to = 'session') {
+    return JSON.stringify({
+      v: 1,
+      sess: sessionId,
+      from: remoteConfig.device_id,
+      to,
+      // No AEAD until Phase 2.5 — send as a `control` field which
+      // gateway's relay.py forwards untouched (see routes/relay.py:_send_envelope).
+      // Payload is one  event/command exactly as it would appear
+      // on the local socket, but plaintext for now.
+      control: controlBody,
+    });
+  }
+
+  function _send(controlBody) {
+    if (!state.ws || state.ws.readyState !== 1 /* OPEN */) return false;
+    try { state.ws.send(_envelope(controlBody)); return true; }
+    catch (err) { _log(`send failed: ${err.message}`); return false; }
+  }
+
+  function _connect() {
+    if (state.stopped) return;
+    if (process.env.BAHULAM_RELAY_KILL === '1') {
+      _log('BAHULAM_RELAY_KILL=1 — refusing to dial');
+      return;
+    }
+    _log(`dial ${url.replace(/token=[^&]+/, 'token=***')}`);
+    const ws = new WebSocket(url, ['bahulam.v1']);
+    state.ws = ws;
+
+    ws.addEventListener('open', () => {
+      state.reconnectAttempt = 0;
+      try { process.stderr.write(`${GREEN}[relay] connected${RESET}\n`); } catch {}
+      // Send a `daemon_hello` control frame so peers (mobile) know who joined.
+      _send({ type: 'daemon_hello', device_id: remoteConfig.device_id, session_id: sessionId });
+      _startHeartbeat();
+      _startRevokePoll();
+    });
+
+    ws.addEventListener('message', ev => {
+      let env;
+      try { env = JSON.parse(String(ev.data)); }
+      catch { return; }
+      // Ignore our own broadcasts echoed back.
+      if (env.from === remoteConfig.device_id) return;
+      const control = env.control;
+      if (!control || !control.type) return;
+      _dispatchIncoming(control, env.from);
+    });
+
+    ws.addEventListener('close', ev => {
+      _stopHeartbeat();
+      state.ws = null;
+      if (state.stopped) return;
+      // Codes: 1008 policy (bad auth / bad envelope) → don't reconnect.
+      if (ev && (ev.code === 1008 || ev.code === 4001 || ev.code === 4003)) {
+        _log(`closed with policy code ${ev.code} (${ev.reason || 'no reason'}) — not reconnecting`);
+        return;
+      }
+      _scheduleReconnect(ev?.code);
+    });
+
+    ws.addEventListener('error', err => {
+      _log(`ws error: ${err?.message || err}`);
+      // 'close' will fire after, which triggers reconnect.
+    });
+  }
+
+  function _scheduleReconnect(closeCode) {
+    if (state.stopped) return;
+    state.reconnectAttempt += 1;
+    const base = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * Math.pow(2, state.reconnectAttempt - 1));
+    const jitter = base * 0.5 * (Math.random() - 0.5);  // ±25%
+    const wait = Math.max(BACKOFF_BASE_MS, Math.floor(base + jitter));
+    _log(`reconnect in ${wait}ms (attempt ${state.reconnectAttempt}${closeCode ? `, close ${closeCode}` : ''})`);
+    setTimeout(() => { if (!state.stopped) _connect(); }, wait);
+  }
+
+  function _startHeartbeat() {
+    _stopHeartbeat();
+    state.heartbeatTimer = setInterval(() => {
+      // WebSocket doesn't have a JS-level ping in the browser API. Send a
+      // small control-frame keepalive instead. Gateway routes as any other
+      // envelope; peer clients can ignore type=keepalive.
+      _send({ type: 'keepalive', ts: Date.now() });
+    }, HEARTBEAT_MS);
+    if (typeof state.heartbeatTimer.unref === 'function') state.heartbeatTimer.unref();
+  }
+
+  function _stopHeartbeat() {
+    if (state.heartbeatTimer) { clearInterval(state.heartbeatTimer); state.heartbeatTimer = null; }
+  }
+
+  function _startRevokePoll() {
+    _stopRevokePoll();
+    state.revokeTimer = setInterval(() => {
+      // Re-read the local config; if remote was disabled or the device
+      // is missing, drop the connection. Fast reaction to `bahulam remote
+      // disable` in another terminal, or to `bahulam device revoke <self>`
+      // which clears the pairing block.
+      try {
+        const fresh = _reloadConfig();
+        if (!fresh?.enabled || fresh?.device_id !== remoteConfig.device_id) {
+          _log('local config changed (disabled or device mismatch) — disconnecting');
+          stop();
+        }
+      } catch { /* ignore, next poll retries */ }
+    }, REVOKE_POLL_MS);
+    if (typeof state.revokeTimer.unref === 'function') state.revokeTimer.unref();
+  }
+
+  function _stopRevokePoll() {
+    if (state.revokeTimer) { clearInterval(state.revokeTimer); state.revokeTimer = null; }
+  }
+
+  function _dispatchIncoming(control, fromDevice) {
+    const handler = onCommand[control.type];
+    if (typeof handler !== 'function') {
+      _log(`unknown control type from ${fromDevice}: ${control.type}`);
+      return;
+    }
+    // Pass fromDevice as the attach id so decisions get attributed.
+    Promise.resolve()
+      .then(() => handler(control.data || {}, `relay:${fromDevice}`))
+      .catch(err => _log(`handler for ${control.type} failed: ${err.message}`));
+  }
+
+  async function stop() {
+    if (state.stopped) return;
+    state.stopped = true;
+    _stopHeartbeat();
+    _stopRevokePoll();
+    if (state.unregisterBroadcaster) { try { state.unregisterBroadcaster(); } catch {} }
+    if (state.ws) {
+      try { state.ws.close(1000, 'client_stop'); } catch {}
+      state.ws = null;
+    }
+  }
+
+  // Register a broadcaster that forwards every daemon event to the relay.
+  // Return the unregister so stop() can clean up.
+  if (typeof registerBroadcaster === 'function') {
+    state.unregisterBroadcaster = registerBroadcaster(evt => {
+      // Forward every event as a control-frame envelope so mobile sees
+      // the same  §5.1 shape it does from the mock relay.
+      _send(evt);
+    });
+  }
+
+  _connect();
+  return { stop, _debug: state };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+function _buildUrl(relayBase, sessionId, deviceId, token) {
+  // relay_url from config is like "wss://relay.bahulam.ai" or
+  // "wss://gateway.bahulam.ai" (the router mounts /relay/*). We append
+  // /relay/session/<sess_id>?device=&token= regardless.
+  const base = String(relayBase || '').replace(/\/+$/, '');
+  const enc = encodeURIComponent;
+  return `${base}/relay/session/${enc(sessionId)}?device=${enc(deviceId)}&token=${enc(token)}`;
+}
+
+// Re-read the config from disk on each poll so the daemon reacts to
+// out-of-band changes (bahulam remote disable, bahulam device revoke)
+// without needing a signal. Lazy dynamic import: cache the resolved
+// loader function so subsequent polls are one function call each.
+let _loadRemoteConfigCached = null;
+let _loadRemoteConfigPromise = null;
+
+function _reloadConfig() {
+  if (_loadRemoteConfigCached) return _loadRemoteConfigCached();
+  // First call: kick off the import in the background. Subsequent polls
+  // pick up the cached function once it's resolved. This poll returns
+  // null in the meantime (no config → stay connected, which is safe;
+  // the next poll in 10s will have the loader ready).
+  if (!_loadRemoteConfigPromise) {
+    _loadRemoteConfigPromise = import('../commands/remote.mjs')
+      .then(mod => { _loadRemoteConfigCached = mod.loadRemoteConfig || (() => null); })
+      .catch(() => { _loadRemoteConfigCached = () => null; });
+  }
+  return null;
+}