@pleri/olam-cli 0.1.102 → 0.1.104

package/dist/image-digests.json

@@ -1,10 +1,10 @@
 {
   "auth": "sha256:4853cf21c4f63ffcc0e44bf1b1e1240aa5bd33348cbced2e1e2960aca0744484",
-  "devbox": "sha256:90fc750afe69e792042809276546b9fdd372691561776dfbfc4c9ad835b985f2",
-  "devbox-base": "sha256:473ff96011309dccefefba830f332bbab394950c774f7bcd75d18751b79797d2",
-  "host-cp": "sha256:9af7f646a39eac1d68bf8de80a450fa531da0c73f082d2724429a01e2704e796",
+  "devbox": "sha256:99529690b25e22f1819366ee001d84979a9d4de714ba1b0353b1b1a7f9eb8805",
+  "devbox-base": "sha256:5e4bc98029f99eeab7fb542b333899675884c2404a1925eafa19768d31451e23",
+  "host-cp": "sha256:82de19cb665e7e368e5133e263bc3a837da03ac614f4687f05bf4a72dccaf0c1",
   "mcp-auth": "sha256:5da67023e96f685589676b191105fa260eaa0199ef1af43e7a63f982880c7bf7",
   "$schema_version": 1,
-  "$published_version": "0.1.102",
+  "$published_version": "0.1.104",
   "$registry": "ghcr.io/pleri"
 }

package/dist/index.js

@@ -10218,6 +10218,34 @@ var init_bootstrap_hooks = __esm({
 });
 
 // ../core/dist/world/tmux-supervisor.js
+function injectBindAll(start) {
+  let result = start;
+  const userBoundRails = /(^|\s)(-b|--binding)(\s+|=)\S+/.test(start);
+  const userBoundNext = /(^|\s)(-H|--hostname)(\s+|=)\S+/.test(start);
+  const userBoundVite = /(^|\s)--host(\s+\S+|=\S+)/.test(start);
+  const userBoundGunicorn = /(^|\s)(-h|--bind)(\s+|=)\S+/.test(start);
+  const userHostEnv = /(^|\s)HOST=\S+/.test(start);
+  const anyUserBound = userBoundRails || userBoundNext || userBoundVite || userBoundGunicorn;
+  if (!userHostEnv && !anyUserBound) {
+    result = `HOST=0.0.0.0 ${result}`;
+  }
+  if (!userBoundRails && /\brails\s+s(?:erver)?\b/.test(start)) {
+    result = `${result} -b 0.0.0.0`;
+  }
+  if (!userBoundNext && /\bnext\s+dev\b/.test(start)) {
+    result = `${result} -H 0.0.0.0`;
+  }
+  if (!userBoundVite && /\b(?:^|\s|=)vite\b/.test(start)) {
+    result = `${result} --host 0.0.0.0`;
+  }
+  if (!userBoundVite && /\b(?:flask\s+run|uvicorn|hypercorn)\b/.test(start)) {
+    result = `${result} --host 0.0.0.0`;
+  }
+  if (!userBoundGunicorn && /\bgunicorn\b/.test(start)) {
+    result = `${result} --bind 0.0.0.0`;
+  }
+  return result;
+}
 async function startSupervisedApps(containerName, worldId, repos, exec, options = {}) {
   if (!SAFE_IDENT2.test(containerName)) {
     throw new Error(`containerName "${containerName}" must match ${SAFE_IDENT2} (defensive guard)`);
@@ -10253,7 +10281,7 @@ async function startSupervisedApps(containerName, worldId, repos, exec, options
       windowsExisting.push(repo.name);
       continue;
     }
-    const expandedStart = repo.start.replace(/\$\{?PORT\}?/g, String(repo.hostPort));
+    const expandedStart = injectBindAll(repo.start).replace(/\$\{?PORT\}?/g, String(repo.hostPort));
     const startCmd = `cd ${shellQuote2(repo.dir)} && exec ${expandedStart}`;
     exec(containerName, `tmux new-window -t ${sessionName} -n ${repo.name} -d ${shellQuote2(startCmd)}`);
     windowsCreated.push(repo.name);

package/dist/mcp-server.js

@@ -31318,6 +31318,34 @@ async function runSeedHooks(seeds, containerName, servicePortMap, exec) {
 }
 
 // ../core/dist/world/tmux-supervisor.js
+function injectBindAll(start) {
+  let result = start;
+  const userBoundRails = /(^|\s)(-b|--binding)(\s+|=)\S+/.test(start);
+  const userBoundNext = /(^|\s)(-H|--hostname)(\s+|=)\S+/.test(start);
+  const userBoundVite = /(^|\s)--host(\s+\S+|=\S+)/.test(start);
+  const userBoundGunicorn = /(^|\s)(-h|--bind)(\s+|=)\S+/.test(start);
+  const userHostEnv = /(^|\s)HOST=\S+/.test(start);
+  const anyUserBound = userBoundRails || userBoundNext || userBoundVite || userBoundGunicorn;
+  if (!userHostEnv && !anyUserBound) {
+    result = `HOST=0.0.0.0 ${result}`;
+  }
+  if (!userBoundRails && /\brails\s+s(?:erver)?\b/.test(start)) {
+    result = `${result} -b 0.0.0.0`;
+  }
+  if (!userBoundNext && /\bnext\s+dev\b/.test(start)) {
+    result = `${result} -H 0.0.0.0`;
+  }
+  if (!userBoundVite && /\b(?:^|\s|=)vite\b/.test(start)) {
+    result = `${result} --host 0.0.0.0`;
+  }
+  if (!userBoundVite && /\b(?:flask\s+run|uvicorn|hypercorn)\b/.test(start)) {
+    result = `${result} --host 0.0.0.0`;
+  }
+  if (!userBoundGunicorn && /\bgunicorn\b/.test(start)) {
+    result = `${result} --bind 0.0.0.0`;
+  }
+  return result;
+}
 var PortInUseError = class extends Error {
   port;
   repo;
@@ -31366,7 +31394,7 @@ async function startSupervisedApps(containerName, worldId, repos, exec, options
       windowsExisting.push(repo.name);
       continue;
     }
-    const expandedStart = repo.start.replace(/\$\{?PORT\}?/g, String(repo.hostPort));
+    const expandedStart = injectBindAll(repo.start).replace(/\$\{?PORT\}?/g, String(repo.hostPort));
     const startCmd = `cd ${shellQuote2(repo.dir)} && exec ${expandedStart}`;
     exec(containerName, `tmux new-window -t ${sessionName} -n ${repo.name} -d ${shellQuote2(startCmd)}`);
     windowsCreated.push(repo.name);

package/host-cp/src/host-stream.mjs

@@ -0,0 +1,443 @@
+// Phase A → E (sse-consolidation): server-side multiplexed-SSE broadcaster.
+//
+// Single endpoint /api/host-stream replaces ~20 SPA polling loops. Hooks
+// subscribe to typed events on one connection instead of opening one
+// setInterval-loop per resource.
+//
+// Mirrors planOrchestrator.addEventSink fanout pattern verbatim — same
+// per-sink ServerResponse Set, same `event: <name>\ndata: <json>\n\n`
+// wire format, same cleanup-on-disconnect contract. Differences:
+//
+//   - Keyed by event TYPE rather than conversationId (the broadcaster is
+//     global to the host-cp, not per-conversation).
+//   - Caches last-known payload per event type so reconnecting clients
+//     receive an immediate snapshot replay before live updates resume.
+//   - No turn-buffering — snapshots are idempotent so reconnect == latest.
+//
+// Phase E adds operational polish:
+//   - E1: per-event-type trailing-edge debounce (default 100ms).
+//         Coalesces broadcast storms during world boot.
+//   - E2: per-sink 25s heartbeat (`:\n\n` comment) to keep idle SSE
+//         connections alive across most proxy 60s timeouts.
+//   - E3: backpressure-aware writes — slow sinks queue up to a bounded
+//         in-memory buffer; overflow drops oldest events with an
+//         `:overflow` comment so consumers know they missed updates.
+//   - E4: per-event-type broadcast counter + sink count metric line.
+//
+// Pure module: no docker, no DB, no global clock except `setInterval`
+// for the heartbeat/metrics timers (injectable in tests). Wiring those
+// sources to broadcast(...) lives in server.mjs (A4 + A5).
+//
+// References:
+//   - packages/host-cp/src/server.mjs:1531  SSE writer template
+//   - packages/host-cp/src/plan-orchestrator.mjs:967  addEventSink shape
+//   - docs/plans/sse-consolidation/plan-source.md  full design
+//   - docs/plans/sse-consolidation/phase-e-tasks.md  E1-E4 acceptance
+
+import crypto from 'node:crypto';
+
+/**
+ * @typedef {object} HostStreamDeps
+ * @property {(message: string) => void} [log]                  defaults to no-op
+ * @property {object}                    [debounceMs]          per-event-type debounce override
+ * @property {number}                    [debounceMs.default]  default trailing-edge ms (Phase E1)
+ * @property {number}                    [heartbeatMs]         per-sink heartbeat interval (Phase E2)
+ * @property {number}                    [metricsMs]           per-broadcaster metrics tick (Phase E4)
+ * @property {number}                    [maxQueuedPerSink]    bounded queue size (Phase E3)
+ * @property {(cb: () => void, ms: number) => any} [setTimer]  injectable setInterval (tests)
+ * @property {(handle: any) => void}     [clearTimer]          injectable clearInterval (tests)
+ */
+
+/**
+ * @typedef {object} HostStream
+ * @property {(res: import('node:http').ServerResponse) => () => void} addSink
+ * @property {(eventType: string, payload: unknown) => number}         broadcast
+ * @property {() => Record<string, unknown>}                            snapshot
+ * @property {() => void}                                               close
+ * @property {() => number}                                             sinkCount
+ * @property {() => HostStreamMetrics}                                  metrics
+ * @property {() => void}                                               flushDebounced  test-only — fire all pending coalesced broadcasts immediately
+ */
+
+/**
+ * @typedef {object} HostStreamMetrics
+ * @property {Record<string, number>} events   per-event-type broadcasts since last reset
+ * @property {number}                 sinks    current active-sink count
+ * @property {number}                 overflows total `:overflow` drops since last reset
+ */
+
+const DEFAULT_DEBOUNCE_MS = 100;
+const DEFAULT_HEARTBEAT_MS = 25_000;
+const DEFAULT_METRICS_MS = 60_000;
+const DEFAULT_MAX_QUEUED = 64;
+
+/**
+ * Event types that opt INTO the trailing-edge debounce (Phase E1). The
+ * default callers — `world.snapshot`, `tunnels.snapshot`, `servers.snapshot`,
+ * `listening.snapshot` — are all idempotent state-replay events where
+ * "last writer wins" is correct and a 100ms cap on update propagation
+ * is acceptable. Latency-sensitive events (`question.pending`) and
+ * connect-only events (`ready`) stay immediate by NOT being in this set.
+ *
+ * Per-event-type overrides via `deps.debounceMs[type] = 0` force any
+ * event off the debounce path; non-zero override flips it on with a
+ * custom window. Callers should not need to opt anything new into
+ * debouncing — adding a new snapshot event implies adding to this set.
+ */
+const DEFAULT_DEBOUNCED_EVENTS = new Set([
+  'world.snapshot',
+  'tunnels.snapshot',
+  'servers.snapshot',
+  'listening.snapshot',
+]);
+
+/**
+ * Create a host-stream broadcaster. Stateless w.r.t. the request — all
+ * source-of-truth wiring (docker events, worlds.db, etc.) is done by
+ * the caller via repeated `broadcast()` invocations.
+ *
+ * @param {HostStreamDeps} [deps]
+ * @returns {HostStream}
+ */
+export function createHostStream(deps = {}) {
+  const log = deps.log ?? (() => {});
+  const defaultDebounceMs = deps.debounceMs?.default ?? DEFAULT_DEBOUNCE_MS;
+  const heartbeatMs = deps.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const metricsMs = deps.metricsMs ?? DEFAULT_METRICS_MS;
+  const maxQueuedPerSink = deps.maxQueuedPerSink ?? DEFAULT_MAX_QUEUED;
+  const setTimer = deps.setTimer ?? ((cb, ms) => setInterval(cb, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => clearInterval(h));
+
+  /**
+   * @typedef {object} SinkState
+   * @property {import('node:http').ServerResponse} res
+   * @property {string[]}              queue
+   * @property {boolean}               paused   true while waiting for a `drain` event
+   * @property {boolean}               draining true while flushQueue is iterating
+   * @property {boolean}               drainListenerAttached
+   * @property {any | null}            heartbeatHandle
+   * @property {number}                overflows
+   */
+
+  /** @type {Map<import('node:http').ServerResponse, SinkState>} */
+  const sinks = new Map();
+
+  /** @type {Map<string, unknown>} last-known payload per event type */
+  const snapshots = new Map();
+
+  /** @type {Map<string, any>} pending debounce timers per event type */
+  const debounceTimers = new Map();
+
+  /** Per-event-type broadcast counters since last metrics flush. */
+  const eventCounters = new Map();
+  let overflowCounter = 0;
+
+  let closed = false;
+  let metricsHandle = null;
+
+  function formatEvent(eventType, payload) {
+    return `event: ${eventType}\ndata: ${JSON.stringify(payload)}\n\n`;
+  }
+
+  /**
+   * Queue-aware write. If the underlying socket's `res.write` returns
+   * `false` we buffer the chunk in the per-sink queue and register a
+   * one-shot `drain` listener to flush it when the kernel reports the
+   * socket is writable again. On overflow we emit `:overflow` so
+   * consumers know they missed updates and drop oldest.
+   *
+   * @returns {boolean} true if the chunk was accepted (synchronously or
+   *   queued) — false only when the sink is dead and was removed.
+   */
+  function writeSafe(state, chunk) {
+    const { res } = state;
+    if (res.writableEnded || res.destroyed) return false;
+
+    // If a previous write reported backpressure (returned false), queue
+    // unconditionally — preserves event ordering. The drain handler
+    // flushes the queue in FIFO order.
+    if (state.paused) {
+      enqueue(state, chunk);
+      return true;
+    }
+
+    try {
+      const ok = res.write(chunk);
+      if (ok) return true;
+      // Returned false — kernel buffer is full. Switch to queue mode so
+      // subsequent writes don't race past this one.
+      state.paused = true;
+      attachDrain(state);
+      return true;
+    } catch {
+      // Sink already closed — drop it; further writes would throw.
+      teardownSink(res);
+      return false;
+    }
+  }
+
+  function enqueue(state, chunk) {
+    if (state.queue.length >= maxQueuedPerSink) {
+      // Drop oldest, emit :overflow comment when the drain eventually
+      // flushes. The overflow comment is enqueued (not written directly)
+      // so consumers see it inline with surrounding events.
+      state.queue.shift();
+      state.overflows += 1;
+      overflowCounter += 1;
+      if (!state.queue.some((s) => s === ':overflow\n\n')) {
+        state.queue.unshift(':overflow\n\n');
+      }
+    }
+    state.queue.push(chunk);
+    attachDrain(state);
+  }
+
+  function attachDrain(state) {
+    if (state.drainListenerAttached) return;
+    const { res } = state;
+    if (typeof res.once !== 'function') return; // testing-sink fallback
+    state.drainListenerAttached = true;
+    res.once('drain', () => {
+      state.drainListenerAttached = false;
+      flushQueue(state);
+    });
+  }
+
+  function flushQueue(state) {
+    const { res } = state;
+    if (state.draining) return;
+    state.draining = true;
+    state.paused = false;
+    try {
+      while (state.queue.length > 0) {
+        if (res.writableEnded || res.destroyed) {
+          state.queue.length = 0;
+          break;
+        }
+        const next = state.queue[0];
+        let ok = false;
+        try {
+          ok = res.write(next);
+        } catch {
+          teardownSink(res);
+          return;
+        }
+        state.queue.shift();
+        if (!ok) {
+          state.paused = true;
+          attachDrain(state);
+          break;
+        }
+      }
+    } finally {
+      state.draining = false;
+    }
+  }
+
+  function teardownSink(res) {
+    const state = sinks.get(res);
+    if (!state) return;
+    if (state.heartbeatHandle) {
+      try { clearTimer(state.heartbeatHandle); } catch { /* ignore */ }
+      state.heartbeatHandle = null;
+    }
+    state.queue.length = 0;
+    sinks.delete(res);
+  }
+
+  function doBroadcast(eventType, payload) {
+    if (closed) return 0;
+    snapshots.set(eventType, payload);
+    eventCounters.set(eventType, (eventCounters.get(eventType) ?? 0) + 1);
+    const chunk = formatEvent(eventType, payload);
+    let reached = 0;
+    // Snapshot the iteration order so concurrent sink removal during
+    // a write doesn't skip a sibling sink.
+    for (const state of [...sinks.values()]) {
+      if (writeSafe(state, chunk)) reached += 1;
+    }
+    return reached;
+  }
+
+  function flushDebounced() {
+    for (const [type, info] of debounceTimers) {
+      clearTimeout(info.handle);
+      debounceTimers.delete(type);
+      doBroadcast(type, info.payload);
+    }
+  }
+
+  function logMetrics() {
+    if (eventCounters.size === 0 && sinks.size === 0 && overflowCounter === 0) return;
+    /** @type {Record<string, number>} */
+    const events = {};
+    for (const [type, count] of eventCounters) events[type] = count;
+    log(`events=${JSON.stringify(events)} sinks=${sinks.size}${overflowCounter > 0 ? ` overflows=${overflowCounter}` : ''}`);
+    eventCounters.clear();
+    overflowCounter = 0;
+  }
+
+  // Start the metrics tick eagerly — operators want visibility from
+  // boot, not just after the first event lands.
+  if (metricsMs > 0) {
+    metricsHandle = setTimer(logMetrics, metricsMs);
+    // Don't pin the event loop just for metrics in tests / shutdown paths.
+    if (metricsHandle && typeof metricsHandle.unref === 'function') metricsHandle.unref();
+  }
+
+  return {
+    addSink(res) {
+      if (closed) {
+        // Best-effort: end the response so the client sees the channel
+        // closing instead of hanging on an empty stream.
+        try { res.end(); } catch { /* ignore */ }
+        return () => {};
+      }
+
+      const state = /** @type {SinkState} */ ({
+        res,
+        queue: [],
+        paused: false,
+        draining: false,
+        drainListenerAttached: false,
+        heartbeatHandle: null,
+        overflows: 0,
+      });
+      sinks.set(res, state);
+
+      // Replay last-known snapshot for every event type so the new
+      // subscriber gets current state without waiting for the next change.
+      // Sorting keeps test assertions deterministic.
+      const types = [...snapshots.keys()].sort();
+      for (const type of types) {
+        writeSafe(state, formatEvent(type, snapshots.get(type)));
+      }
+
+      // Phase E2: per-sink heartbeat. Write a comment line every
+      // `heartbeatMs` so the SSE channel survives idle proxies. The
+      // comment is invisible to client EventSource listeners (the
+      // browser passes only `event:`/`data:` lines through), so this
+      // does NOT trigger any handler — it's pure connection-keepalive.
+      if (heartbeatMs > 0) {
+        state.heartbeatHandle = setTimer(() => {
+          // Use writeSafe so backpressure / overflow handling applies
+          // uniformly. Heartbeats that fail to flush are uninteresting
+          // — the regular broadcast loop will discover the dead sink.
+          writeSafe(state, ':\n\n');
+        }, heartbeatMs);
+        if (state.heartbeatHandle && typeof state.heartbeatHandle.unref === 'function') {
+          state.heartbeatHandle.unref();
+        }
+      }
+
+      return () => {
+        teardownSink(res);
+      };
+    },
+
+    broadcast(eventType, payload) {
+      if (closed) return 0;
+      if (typeof eventType !== 'string' || eventType.length === 0) {
+        throw new TypeError('broadcast: eventType must be a non-empty string');
+      }
+
+      // Phase E1: opt-in trailing-edge debounce.
+      //   - DEFAULT_DEBOUNCED_EVENTS opts the canonical snapshot events
+      //     into trailing-edge coalescing. Last writer wins because those
+      //     events are idempotent state replays.
+      //   - Every other event type bypasses the timer and writes
+      //     immediately — preserves the Phase A synchronous broadcast
+      //     contract that existing tests / consumers depend on.
+      //   - Per-event-type overrides via `deps.debounceMs[eventType]`
+      //     win in both directions (set to 0 to disable, or specify a
+      //     custom window).
+      //   - `flushDebounced()` is exposed for tests that want to assert
+      //     immediate effects without waiting for the timer.
+      let debounceFor;
+      const override = deps.debounceMs?.[eventType];
+      if (override !== undefined) {
+        debounceFor = override;
+      } else if (DEFAULT_DEBOUNCED_EVENTS.has(eventType)) {
+        debounceFor = defaultDebounceMs;
+      } else {
+        debounceFor = 0;
+      }
+
+      if (debounceFor <= 0) {
+        // Take the immediate path; flush any pending coalesce for this
+        // type first so order is preserved.
+        const pending = debounceTimers.get(eventType);
+        if (pending) {
+          clearTimeout(pending.handle);
+          debounceTimers.delete(eventType);
+        }
+        return doBroadcast(eventType, payload);
+      }
+
+      // Coalesce: keep the latest payload, restart the trailing timer.
+      const pending = debounceTimers.get(eventType);
+      if (pending) clearTimeout(pending.handle);
+      const handle = setTimeout(() => {
+        debounceTimers.delete(eventType);
+        doBroadcast(eventType, payload);
+      }, debounceFor);
+      if (typeof handle.unref === 'function') handle.unref();
+      debounceTimers.set(eventType, { handle, payload });
+      // Returns sinks.size as an approximation; the actual broadcast
+      // will happen after the trailing-edge delay. Tests assert via the
+      // sink writes anyway.
+      return sinks.size;
+    },
+
+    snapshot() {
+      /** @type {Record<string, unknown>} */
+      const out = {};
+      for (const [type, payload] of snapshots) out[type] = payload;
+      return out;
+    },
+
+    close() {
+      if (closed) return;
+      closed = true;
+      // Cancel pending debounce timers — anything still queued is
+      // discarded; we don't write to sinks during shutdown.
+      for (const [, info] of debounceTimers) clearTimeout(info.handle);
+      debounceTimers.clear();
+      if (metricsHandle) {
+        try { clearTimer(metricsHandle); } catch { /* ignore */ }
+        metricsHandle = null;
+      }
+      for (const [res, state] of [...sinks.entries()]) {
+        if (state.heartbeatHandle) {
+          try { clearTimer(state.heartbeatHandle); } catch { /* ignore */ }
+        }
+        try { res.end(); } catch { /* ignore */ }
+        sinks.delete(res);
+      }
+      log('closed');
+    },
+
+    sinkCount() {
+      return sinks.size;
+    },
+
+    metrics() {
+      /** @type {Record<string, number>} */
+      const events = {};
+      for (const [type, count] of eventCounters) events[type] = count;
+      return { events, sinks: sinks.size, overflows: overflowCounter };
+    },
+
+    flushDebounced,
+  };
+}
+
+/**
+ * Generate a fresh streamId for the `ready` event payload. Exposed so
+ * route handlers can attach the same id to log lines and the wire.
+ *
+ * @returns {string}
+ */
+export function newStreamId() {
+  return crypto.randomBytes(8).toString('hex');
+}

package/host-cp/src/server.mjs

@@ -34,6 +34,7 @@ import { computeProgress } from './world-progress.mjs';
 import { createPrCache } from './pr-cache.mjs';
 import { fetchContainerSecret } from './container-secret-fetcher.mjs';
 import { subscribeDockerEvents } from './docker-events.mjs';
+import { createHostStream, newStreamId } from './host-stream.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
 import { StartupToken } from './auth.mjs';
@@ -422,11 +423,219 @@ let prListCacheEntry = null; // /api/prs — 60s TTL global PR list for Cmd+K
 const sseGate = new SseGate({ maxConcurrent: SSE_CAP });
 
 // Subscribe to docker events on boot. Unsubscribed at shutdown.
+//
+// Two consumers now: the legacy secret-cache invalidator (Phase F-2-B B3)
+// AND the host-stream broadcaster (sse-consolidation Phase A4). The
+// broadcaster pushes a debounced `servers.snapshot` whenever an
+// `olam-*-devbox` container starts/stops so the SPA can drop its
+// poll-every-2s `useListeningServers` loop.
+const hostStream = createHostStream({ log: (m) => console.log(`[host-stream] ${m}`) });
+
+// A4: coalesce docker-event bursts into a single servers.snapshot. World
+// boot fires `create` + `start` + healthcheck transitions in <100ms; we
+// don't want a broadcast storm. Window matches plan-source.md P3 target.
+const SERVERS_SNAPSHOT_DEBOUNCE_MS = 100;
+let serversSnapshotTimer = null;
+function scheduleServersSnapshot() {
+  if (serversSnapshotTimer) return;
+  serversSnapshotTimer = setTimeout(() => {
+    serversSnapshotTimer = null;
+    const ids = Object.keys(WORLDS).sort();
+    hostStream.broadcast('servers.snapshot', {
+      servers: ids.map((id) => ({ id, port: WORLDS[id] })),
+      snapshotAt: new Date().toISOString(),
+    });
+  }, SERVERS_SNAPSHOT_DEBOUNCE_MS);
+}
+
 const stopEvents = subscribeDockerEvents({
   dockerHost: DOCKER_HOST,
-  onWorldRestart: (worldId) => cache.invalidate(worldId),
+  onWorldRestart: (worldId) => {
+    cache.invalidate(worldId);
+    // Only push the snapshot for olam-* world containers; the
+    // onWorldRestart handler is already filtered to `olam-<id>-devbox`
+    // by handleEvent in docker-events.mjs, so any worldId reaching
+    // this callback is by construction an olam world.
+    scheduleServersSnapshot();
+  },
 });
 
+// Initial servers.snapshot so subscribers connecting before any docker
+// event have a current snapshot to replay from.
+scheduleServersSnapshot();
+
+// A5: 1-Hz worlds.db hash-diff loop. The worlds-db reconciler above
+// reacts to fs.watch + every 30s; that's enough to keep the WORLDS
+// registry consistent, but the SPA wants sub-second freshness on
+// create/destroy. Hash the composed worlds list each tick, broadcast
+// only on change. Pure-server-side polling — never touches the network.
+const WORLDS_SNAPSHOT_TICK_MS = 1000;
+let lastWorldsHash = '';
+let worldsSnapshotTimer = null;
+let worldsSnapshotInFlight = false;
+
+async function tickWorldsSnapshot() {
+  if (worldsSnapshotInFlight) return;
+  worldsSnapshotInFlight = true;
+  try {
+    const worlds = await composeWorldsSources(worldsSources);
+    // Stable JSON for hashing — JSON.stringify is order-sensitive, so
+    // sort the array by id before serialising. Sources already return
+    // stable shape per world.
+    const sorted = [...worlds].sort((a, b) =>
+      String(a?.id ?? '').localeCompare(String(b?.id ?? '')),
+    );
+    const json = JSON.stringify(sorted);
+    const { createHash } = await import('node:crypto');
+    const hash = createHash('sha1').update(json).digest('hex');
+    if (hash === lastWorldsHash) return;
+    lastWorldsHash = hash;
+    hostStream.broadcast('world.snapshot', {
+      worlds: sorted,
+      snapshotAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    // Don't kill the loop on transient compose errors. Worst case the
+    // next tick succeeds and the diff is detected then.
+    console.warn(`[host-stream] worlds.snapshot tick failed: ${err?.message ?? err}`);
+  } finally {
+    worldsSnapshotInFlight = false;
+  }
+}
+
+function startWorldsSnapshotLoop() {
+  // Initial broadcast on host-cp start so the first subscriber gets
+  // current state before the next tick fires.
+  void tickWorldsSnapshot();
+  worldsSnapshotTimer = setInterval(() => { void tickWorldsSnapshot(); }, WORLDS_SNAPSHOT_TICK_MS);
+}
+
+function stopWorldsSnapshotLoop() {
+  if (worldsSnapshotTimer) {
+    clearInterval(worldsSnapshotTimer);
+    worldsSnapshotTimer = null;
+  }
+}
+
+// ── Phase B-bonus: tunnels.snapshot + listening.snapshot ─────────────
+//
+// Phase A wired `world.snapshot` (worlds.db) and `servers.snapshot`
+// (docker events for the host worlds-port map). The remaining Phase-B
+// hooks need additional broadcasters so they can drop their poll loops:
+//
+//   - usePublishedTunnels  → `tunnels.snapshot` (per-row, was 4 req/min × N rows on /api/worlds/<id>/tunnels)
+//   - useListeningServers  → `listening.snapshot` (per-world, scoped via filter)
+//
+// Both broadcast a SINGLE aggregate event with all worlds' data; hooks
+// filter by worldId client-side. host-stream caches by event type so a
+// reconnecting tab gets the full set on connect (replay).
+//
+// Cadence: 2s for tunnels (state changes on startTunnel/stopTunnel are
+// fast, polling catches missed updates), 5s for listening servers
+// (matches existing per-world poll cadence). The poller is server-side
+// so the network never carries N polls per refresh window.
+//
+// Note: `tunnels.snapshot` is hash-debounced so idle windows produce
+// zero broadcasts. Same pattern as world.snapshot.
+
+const TUNNELS_SNAPSHOT_TICK_MS = 2_000;
+const LISTENING_SNAPSHOT_TICK_MS = 5_000;
+let tunnelsSnapshotTimer = null;
+let listeningSnapshotTimer = null;
+let lastTunnelsHash = '';
+let lastListeningHash = '';
+
+async function tickTunnelsSnapshot() {
+  try {
+    const byWorld = tunnelManager.getAllTunnels();
+    // Stable JSON for hashing — sort worldIds + service names so
+    // identical state produces identical hash.
+    const ids = Object.keys(byWorld).sort();
+    const stable = ids.map((id) => ({
+      worldId: id,
+      tunnels: [...byWorld[id]].sort((a, b) => a.name.localeCompare(b.name)),
+    }));
+    const json = JSON.stringify(stable);
+    const { createHash } = await import('node:crypto');
+    const hash = createHash('sha1').update(json).digest('hex');
+    if (hash === lastTunnelsHash) return;
+    lastTunnelsHash = hash;
+    hostStream.broadcast('tunnels.snapshot', {
+      worlds: stable,
+      snapshotAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    console.warn(`[host-stream] tunnels.snapshot tick failed: ${err?.message ?? err}`);
+  }
+}
+
+async function tickListeningSnapshot() {
+  try {
+    // Lazy import to keep the boot path light; the poller module also
+    // owns the docker exec details.
+    const { getListeningServers } = await import('./listening-server-poller.mjs');
+    const bridgeManager = await import('./port-bridge-manager.mjs');
+    const ids = Object.keys(WORLDS).sort();
+    if (ids.length === 0) return;
+    // Per-world fetch in parallel; failures yield empty array for that world.
+    const perWorld = await Promise.all(
+      ids.map(async (id) => {
+        try {
+          const snapshot = await getListeningServers(id);
+          const bridges = bridgeManager.getWorldBridges(id);
+          const bridgeByPort = new Map(bridges.map((b) => [b.containerPort, b]));
+          const servers = (snapshot?.servers ?? []).map((s) => ({
+            ...s,
+            bridge: bridgeByPort.get(s.port) ?? null,
+          }));
+          return { worldId: id, servers };
+        } catch {
+          return { worldId: id, servers: [] };
+        }
+      }),
+    );
+    const stable = perWorld.map((w) => ({
+      worldId: w.worldId,
+      servers: [...w.servers].sort((a, b) => a.port - b.port),
+    }));
+    const json = JSON.stringify(stable);
+    const { createHash } = await import('node:crypto');
+    const hash = createHash('sha1').update(json).digest('hex');
+    if (hash === lastListeningHash) return;
+    lastListeningHash = hash;
+    hostStream.broadcast('listening.snapshot', {
+      worlds: stable,
+      snapshotAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    console.warn(`[host-stream] listening.snapshot tick failed: ${err?.message ?? err}`);
+  }
+}
+
+function startTunnelsSnapshotLoop() {
+  void tickTunnelsSnapshot();
+  tunnelsSnapshotTimer = setInterval(() => { void tickTunnelsSnapshot(); }, TUNNELS_SNAPSHOT_TICK_MS);
+}
+
+function stopTunnelsSnapshotLoop() {
+  if (tunnelsSnapshotTimer) {
+    clearInterval(tunnelsSnapshotTimer);
+    tunnelsSnapshotTimer = null;
+  }
+}
+
+function startListeningSnapshotLoop() {
+  void tickListeningSnapshot();
+  listeningSnapshotTimer = setInterval(() => { void tickListeningSnapshot(); }, LISTENING_SNAPSHOT_TICK_MS);
+}
+
+function stopListeningSnapshotLoop() {
+  if (listeningSnapshotTimer) {
+    clearInterval(listeningSnapshotTimer);
+    listeningSnapshotTimer = null;
+  }
+}
+
 /**
  * Resolve worldId → secret. Cache hit returns immediately; miss fetches
  * from the docker-socket-proxy + caches.
@@ -1117,6 +1326,35 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // sse-consolidation Phase A2: multiplexed host-stream endpoint.
+  //
+  // One long-lived SSE per SPA tab replaces 20+ setInterval polls. Event
+  // types include `world.snapshot`, `servers.snapshot`, etc. — wiring
+  // for each lives in the broadcaster + its subscribers. This handler
+  // just opens the channel, emits `ready`, replays cached snapshots,
+  // and registers for future broadcasts. Auth is the global gate above
+  // (cookie + Bearer matching auth.isAuthorized).
+  if (url.pathname === '/api/host-stream' && req.method === 'GET') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    res.write(':\n\n'); // initial heartbeat — keeps proxies from buffering
+
+    const streamId = newStreamId();
+    res.write(`event: ready\ndata: ${JSON.stringify({
+      streamId,
+      serverTime: new Date().toISOString(),
+    })}\n\n`);
+
+    const cleanup = hostStream.addSink(res);
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+    return;
+  }
+
   // ── Per-world credential telemetry routes ─────────────────────────────
   //
   // These are called by the in-world HTTPS proxy when it intercepts
@@ -2382,6 +2620,14 @@ tunnelManager.probeAllOnStartup().catch((err) => {
   console.error(`tunnel startup probe failed: ${err.message}`);
 });
 
+// Start the 1-Hz worlds.db hash-diff loop after the server boots so
+// the initial broadcast happens once the route is reachable.
+startWorldsSnapshotLoop();
+// Phase B-bonus: start tunnel + listening snapshot loops. Both
+// hash-debounce so idle windows produce zero broadcasts.
+startTunnelsSnapshotLoop();
+startListeningSnapshotLoop();
+
 server.listen(PORT, '0.0.0.0', () => {
   console.log(`olam-host-cp B3 listening on :${PORT}`);
   console.log(`  DOCKER_HOST=${DOCKER_HOST}`);
@@ -2411,6 +2657,11 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     stopEvents();
     prPoller.stop();
     worldsDbReconciler.stop();
+    stopWorldsSnapshotLoop();
+    stopTunnelsSnapshotLoop();
+    stopListeningSnapshotLoop();
+    if (serversSnapshotTimer) { clearTimeout(serversSnapshotTimer); serversSnapshotTimer = null; }
+    hostStream.close();
     clearInterval(versionPollTimer);
     cache.clear();
     server.close(() => process.exit(0));

package/host-cp/src/world-tunnel-manager.mjs

@@ -201,6 +201,29 @@ export function stopTunnel(worldId, serviceName) {
   saveState();
 }
 
+/**
+ * Return tunnel state for ALL worlds, keyed by worldId. Used by the
+ * host-stream broadcaster (sse-consolidation Phase B-bonus) to push a
+ * `tunnels.snapshot` whenever the registry changes — replaces the
+ * SPA's per-row `usePublishedTunnels` poll loop.
+ *
+ * @returns {{ [worldId: string]: Array<{name: string, port: number, url: string|null, status: string}> }}
+ */
+export function getAllTunnels() {
+  /** @type {Record<string, Array<{name: string, port: number, url: string|null, status: string}>>} */
+  const byWorld = {};
+  for (const entry of registry.values()) {
+    if (!byWorld[entry.worldId]) byWorld[entry.worldId] = [];
+    byWorld[entry.worldId].push({
+      name: entry.serviceName,
+      port: entry.port,
+      url: entry.url,
+      status: entry.status,
+    });
+  }
+  return byWorld;
+}
+
 /**
  * Return the current tunnel state for all services in a world.
  * @param {string} worldId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.102",
+  "version": "0.1.104",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"