@pleri/olam-cli 0.1.7

package/dist/output.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared output helpers for consistent CLI formatting.
+ */
+export declare function printError(message: string): void;
+export declare function printSuccess(message: string): void;
+export declare function printWarning(message: string): void;
+export declare function printInfo(label: string, value: string): void;
+export declare function printHeader(title: string): void;
+export declare function formatAge(createdAt: string): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQnD"}

package/dist/output.js

@@ -0,0 +1,31 @@
+/**
+ * Shared output helpers for consistent CLI formatting.
+ */
+import pc from 'picocolors';
+export function printError(message) {
+    console.error(`${pc.red('error')} ${message}`);
+}
+export function printSuccess(message) {
+    console.log(`${pc.green('ok')} ${message}`);
+}
+export function printWarning(message) {
+    console.log(`${pc.yellow('warn')} ${message}`);
+}
+export function printInfo(label, value) {
+    console.log(`  ${pc.dim(label.padEnd(14))} ${value}`);
+}
+export function printHeader(title) {
+    console.log(`\n${pc.bold(title)}`);
+}
+export function formatAge(createdAt) {
+    const ms = Date.now() - new Date(createdAt).getTime();
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ${minutes % 60}m`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ${hours % 24}h`;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAa;IACpD,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;IACxC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,GAAG,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACvC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,GAAG,KAAK,KAAK,OAAO,GAAG,EAAE,GAAG,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACpC,OAAO,GAAG,IAAI,KAAK,KAAK,GAAG,EAAE,GAAG,CAAC;AACnC,CAAC"}

package/host-cp/compose.yaml

@@ -0,0 +1,126 @@
+# Phase F-2-B (B2): olam-host-cp compose stack.
+#
+# Two services on a private internal network:
+#
+# 1. host-cp        — the SPA proxy server (B3+ implementation). Exposes
+#                     port 19000 to the operator's host. Talks to the
+#                     docker-socket-proxy via `tcp://docker-socket-proxy:2375`
+#                     (NOT the raw /var/run/docker.sock).
+#
+# 2. docker-socket-proxy
+#                   — tecnativa/docker-socket-proxy sidecar. Mounts the
+#                     real /var/run/docker.sock read-only and exposes a
+#                     whitelisted subset of the Docker API. Whitelist:
+#                       CONTAINERS=1 — list/inspect (find world IDs)
+#                       EVENTS=1     — stream restart/stop events
+#                                      (cache invalidation; B3 / T2)
+#                       EXEC=1       — exec inside containers
+#                                      (read /tmp/olam-container-secret)
+#                     Everything else is denied (images, volumes,
+#                     networks, swarm, build, push, etc.). T6 + T8
+#                     mitigation: blast-radius reduction vs raw socket.
+#
+# Bring up: `docker compose -f packages/host-cp/compose.yaml up --build -d`
+# Tear down: `docker compose -f packages/host-cp/compose.yaml down`
+
+services:
+  host-cp:
+    container_name: olam-host-cp
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: olam-host-cp:latest
+    ports:
+      # Bind to 127.0.0.1 only — single-user-per-host assumption (T4).
+      # Multi-user / TLS / remote access lands in Phase G+.
+      - "127.0.0.1:19000:19000"
+    environment:
+      # Connection string for docker-socket-proxy. The proxy listens on
+      # tcp://0.0.0.0:2375 inside the internal network. host-cp uses
+      # this to enumerate worlds (containers list) + read secrets
+      # (containers exec) + subscribe to restart events.
+      DOCKER_HOST: "tcp://docker-socket-proxy:2375"
+      # Phase F-2-B M2 ship gate: secret cache TTL (5min, demoted from
+      # 1h per D2). B3 reads this; B10's m2-cache-invalidate.sh tests
+      # the docker-events invalidation path.
+      OLAM_SECRET_CACHE_TTL_SEC: "300"
+      # Bind operator-facing UI port. Always 19000 in compose.
+      OLAM_HOST_CP_PORT: "19000"
+      # Token + workspace + world registry mount points. Bind-mounted
+      # below; host CP reads these at boot.
+      OLAM_HOST_CP_TOKEN_PATH: "/data/host-cp.token"
+      OLAM_WORKSPACES_DIR: "/data/workspaces"
+      OLAM_WORLDS_DB: "/data/worlds.db"
+      OLAM_PR_POLL_INTERVAL_MS: "300000"
+      OLAM_MERGE_GRACE_MS: "600000"
+      # Version detection: path to the operator's olam repo checkout.
+      # host-cp reads .git/refs/heads/main (or the active branch) to
+      # determine "latest" SHA. Defaults to $HOME/Projects/ein-sof/olam;
+      # override with OLAM_REPO_PATH env var before `docker compose up`.
+      OLAM_REPO_PATH: "${OLAM_REPO_PATH:-}"
+      # Auth-service inter-service auth. The secret is shared with the
+      # long-lived olam-auth container (generated on first `olam auth
+      # up` at ~/.olam/auth-secret). Without it, X-Olam-Secret is never
+      # sent and auth-service 401s every host-cp → /credentials/* call,
+      # which surfaces in the dashboard as a failed Connect Claude flow.
+      OLAM_AUTH_SERVICE_URL: "http://host.docker.internal:9999"
+      OLAM_AUTH_SECRET: "${OLAM_AUTH_SECRET:-}"
+    volumes:
+      # ~/.olam/ from operator's home → /data/ inside container. B4
+      # writes the startup token here (chmod 600). B6 reads workspaces
+      # + worlds.db from here. ~/.olam/ is the canonical operator-state
+      # directory established by the Olam CLI; consistent with the
+      # devbox container's mount layout.
+      - ${HOME}/.olam:/data
+      - ${HOME}/.config/gh:/gh-config:ro
+      # Operator's olam repo mounted read-only so host-cp can poll
+      # .git/refs/heads/main to detect when a new version is available.
+      # The path inside the container is always /operator-repo.
+      # On the host: OLAM_REPO_PATH env var, or defaults to
+      # $HOME/Projects/ein-sof/olam. If the path doesn't exist, the
+      # mount is a no-op and version detection reports "operator-repo not mounted".
+      - ${OLAM_REPO_PATH:-${HOME}/Projects/ein-sof/olam}:/operator-repo:ro
+    depends_on:
+      docker-socket-proxy:
+        condition: service_started
+    networks:
+      - olam-host-cp-internal
+    restart: unless-stopped
+
+  docker-socket-proxy:
+    container_name: olam-docker-socket-proxy
+    # Pin to a specific tag, not :latest. Update via Renovate / dependabot.
+    # tecnativa/docker-socket-proxy:0.3.0 (2024-10-22) — last tagged
+    # release as of plan-pass-2 emit. T8 mitigation: pinning prevents
+    # supply-chain drift on the sidecar.
+    image: tecnativa/docker-socket-proxy:0.3.0
+    environment:
+      # Whitelist matches plan D5 + T6/T8: host CP needs exactly these
+      # four operations. EVERYTHING else stays at the proxy default
+      # (deny). Audit periodically; widen with explicit justification.
+      CONTAINERS: "1"
+      EVENTS: "1"
+      EXEC: "1"
+      # tecnativa/docker-socket-proxy 0.3.0 requires POST=1 to allow
+      # POST verbs on whitelisted endpoints (exec creation requires
+      # POST /containers/<id>/exec + POST /exec/<id>/start). Phase
+      # F-2-D dogfood revealed the missing perm.
+      POST: "1"
+      # Optional: lower log verbosity. Default is INFO; DEBUG floods
+      # logs in dev. Comment out for troubleshooting.
+      LOG_LEVEL: "warning"
+    volumes:
+      # Mount the host's docker socket READ-ONLY. The proxy is the only
+      # consumer of the raw socket. host-cp talks to the proxy over
+      # TCP (port 2375 on the internal network).
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - olam-host-cp-internal
+    restart: unless-stopped
+
+networks:
+  olam-host-cp-internal:
+    name: olam-host-cp-internal
+    driver: bridge
+    # Internal-only: no host port published; host-cp <-> proxy traffic
+    # never leaves the docker network.

package/host-cp/src/auth-secret-hint.mjs

@@ -0,0 +1,45 @@
+/**
+ * Operator-facing diagnostic for auth-service authentication failures.
+ *
+ * Pre-fix, an empty OLAM_AUTH_SECRET (compose.yaml's
+ * `${OLAM_AUTH_SECRET:-}` interpolation when the operator's shell
+ * didn't export it) silently 401'd every host-cp → auth-service
+ * call. The SPA showed "0 credentials" with no log line explaining
+ * why. Logging a clear hint — both at boot when the env var is empty
+ * AND on the first runtime 401 — turns a silent footgun into a
+ * grep-able warning.
+ *
+ * Lives in its own file (not server.mjs) so unit tests can import it
+ * without triggering server.mjs's top-level mkdir + http.listen side
+ * effects.
+ */
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.authServiceUrl
+ *   The configured auth-service base URL — quoted back to the operator
+ *   so they can cross-reference with their compose env.
+ * @param {boolean} ctx.hasSecret
+ *   True when host-cp's OLAM_AUTH_SECRET is set (and the 401 means a
+ *   value mismatch); false when it's empty (the original silent-fail
+ *   regression mode).
+ * @returns {string}
+ *   A single-line message safe for `console.warn` / docker-compose-logs.
+ */
+export function authSecretHint({ authServiceUrl, hasSecret }) {
+  if (!hasSecret) {
+    return (
+      `[auth] auth-service at ${authServiceUrl} is configured but ` +
+      `OLAM_AUTH_SECRET is empty — every credentials/* call will 401. ` +
+      `Set the env var to the contents of ~/.olam/auth-secret (or run ` +
+      `'olam host-cp start' so the CLI loads it for you).`
+    );
+  }
+  return (
+    `[auth] auth-service at ${authServiceUrl} returned 401 even though ` +
+    `OLAM_AUTH_SECRET is set — the secret does NOT match the value the ` +
+    `auth-service container is using. Check that both containers were ` +
+    `started from the same ~/.olam/auth-secret file and recreate them ` +
+    `together if the file changed.`
+  );
+}

package/host-cp/src/auth.mjs

@@ -0,0 +1,155 @@
+// Phase F-2-B (B4): startup-token authentication for host CP.
+//
+// On boot: generate a 32-byte hex token (or reuse the file if it
+// exists), write to `~/.olam/host-cp.token` with mode 0600, cache in
+// memory. Middleware on all non-static, non-bootstrap routes validates
+// the request via:
+//   - Cookie `olam_host_cp_token=<value>`
+//   - OR Authorization: Bearer <value>
+// Reject 401 if neither matches.
+//
+// Threat model (T4 mitigation):
+//   - Bound to 127.0.0.1:19000 only (compose.yaml). No public exposure.
+//   - Single-user-per-host assumption; multi-user is Phase G+.
+//   - Token file is chmod 600 owned by the operator. Browser tabs on
+//     the same machine that try to hit :19000 are blocked unless they
+//     have the token (cookie or header).
+//   - /api/bootstrap returns the token unauthenticated. Rationale:
+//     anything local that can hit 127.0.0.1:19000 can also read
+//     ~/.olam/host-cp.token (same OS-level privilege boundary). This
+//     just removes a UX friction step. NOT acceptable in multi-user
+//     mode (Phase G+ uses cookie-with-Secure+HttpOnly via real auth).
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class StartupToken {
+  /**
+   * @param {object} opts
+   * @param {string} opts.tokenPath              absolute path to the token file
+   * @param {() => string} [opts.generate]      defaults to 32-byte hex via crypto.randomBytes
+   * @param {(message: string) => void} [opts.log]
+   * @param {typeof fs} [opts.fs]               injectable for tests
+   */
+  constructor({ tokenPath, generate, log = console.log, fs: fsImpl = fs }) {
+    if (!tokenPath || !path.isAbsolute(tokenPath)) {
+      throw new Error('StartupToken: tokenPath must be an absolute path');
+    }
+    this.tokenPath = tokenPath;
+    this.generate = generate ?? (() => crypto.randomBytes(32).toString('hex'));
+    this.log = log;
+    this.fs = fsImpl;
+    /** @type {string | null} */
+    this.token = null;
+  }
+
+  /**
+   * Ensure the token exists in memory + on disk. Call once at server
+   * boot before listen(). Idempotent: subsequent calls return the
+   * cached value.
+   *
+   * Behavior:
+   *   - If tokenPath exists: read it, cache, return it. (Lifecycle
+   *     CLI's `olam host-cp start` may have written the token before
+   *     the container starts; we must reuse the operator-visible
+   *     value, not regenerate it.)
+   *   - Else: generate a new token, write file with mode 0600, return.
+   *
+   * @returns {string}
+   */
+  ensure() {
+    if (this.token) return this.token;
+    const dir = path.dirname(this.tokenPath);
+    if (!this.fs.existsSync(dir)) {
+      this.fs.mkdirSync(dir, { recursive: true });
+    }
+    if (this.fs.existsSync(this.tokenPath)) {
+      const raw = this.fs.readFileSync(this.tokenPath, 'utf-8').trim();
+      if (raw.length < 16) {
+        // Defensive: a too-short token is almost certainly a corrupted
+        // file. Regenerate rather than accept.
+        this.log(`auth: existing token at ${this.tokenPath} too short (${raw.length}); regenerating`);
+        this.token = this._writeNew();
+      } else {
+        this.token = raw;
+        this.log(`auth: reused existing token at ${this.tokenPath}`);
+      }
+    } else {
+      this.token = this._writeNew();
+    }
+    return this.token;
+  }
+
+  /** @private */
+  _writeNew() {
+    const t = this.generate();
+    this.fs.writeFileSync(this.tokenPath, t, { mode: 0o600 });
+    this.log(`auth: generated new token at ${this.tokenPath} (${t.length} chars)`);
+    return t;
+  }
+
+  /**
+   * Check request authorization. Constant-time comparison via
+   * crypto.timingSafeEqual prevents timing-side-channel leaks of the
+   * token's first-byte mismatches.
+   *
+   * @param {import('node:http').IncomingMessage} req
+   * @returns {boolean}
+   */
+  isAuthorized(req) {
+    if (!this.token) return false;
+
+    // Bearer header
+    const authHeader = req.headers['authorization'];
+    if (typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
+      const got = authHeader.slice('Bearer '.length).trim();
+      if (this._compare(got)) return true;
+    }
+
+    // Cookie
+    const cookieHeader = req.headers['cookie'];
+    if (typeof cookieHeader === 'string') {
+      const cookies = parseCookies(cookieHeader);
+      const got = cookies['olam_host_cp_token'];
+      if (got && this._compare(got)) return true;
+    }
+
+    return false;
+  }
+
+  /** @private */
+  _compare(got) {
+    if (!this.token) return false;
+    if (got.length !== this.token.length) return false;
+    try {
+      return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(this.token));
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Parse a Cookie request header into an object. Handles `; ` separators
+ * and `=` value-may-contain-equals (e.g., base64). Empty values + cookies
+ * without `=` are tolerated.
+ *
+ * @param {string} header
+ * @returns {Record<string, string>}
+ */
+export function parseCookies(header) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const pair of header.split(';')) {
+    const trimmed = pair.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) {
+      out[trimmed] = '';
+    } else {
+      out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+    }
+  }
+  return out;
+}

package/host-cp/src/compose-worlds-sources.mjs

@@ -0,0 +1,170 @@
+/**
+ * Phase E4 (olam-dogfood-vision): WorldsSource composition + dedup.
+ *
+ * Runs every configured WorldsSource (E1) in parallel and dedupes by
+ * `id`. Source-array order expresses precedence: the LAST source to
+ * claim an id wins on collision. server.mjs (E4 wiring via
+ * `buildWorldsSources`) orders sources `[localSource, pylonSource]`
+ * so cloud-side metadata overrides local stubs when the Pylon SDK
+ * eventually returns real data for a world that's also docker-
+ * resident locally.
+ *
+ * The function is intentionally pure + dep-free (no env reads, no
+ * http, no module-level state) so vitest can drive it with two mock
+ * sources to assert dedup direction without spinning up the server.
+ *
+ * ## Failure-mode contract (CP3 audit follow-up — closes CRIT/HIGH-1+2)
+ *
+ * Robustness goals:
+ *   1. **One bad source must NOT take down the union.** Pylon SDK
+ *      transient outages, auth errors, network blips — these MUST
+ *      degrade to "cloud worlds missing this poll" rather than
+ *      "/api/worlds endpoint hangs". Achieved via `Promise.allSettled`
+ *      + per-source try/log/treat-as-empty.
+ *   2. **Slow sources MUST NOT extend wall time past the SPA poll
+ *      cadence.** The SPA polls every 4s (Worlds.tsx:124); a Pylon
+ *      `client.worlds.list()` that takes 8s would block, queue
+ *      sockets, and pile up overlapping fetches. Achieved via
+ *      per-source `Promise.race` with `timeoutMs` (default 2000ms,
+ *      matching the existing docker-inspect timeout in
+ *      fetchWorldServices). A timed-out source is treated as `[]` for
+ *      this poll.
+ *   3. **A failing source must produce a log line, not a silent
+ *      empty.** Operators need to see "[worlds-source] pylon-cloud
+ *      list() failed: <err>" in the host-cp boot log so the
+ *      degradation is observable.
+ *
+ * ## Dedup semantics on collision (CP3 audit follow-up — closes HIGH-4)
+ *
+ * Whole-record replacement (the pre-audit behavior) blanks fields the
+ * later source doesn't populate. Concrete example: Pylon returns
+ * `{services: undefined}` (or omits the field entirely) for a freshly-
+ * claimed world while Local has `{services: [4 entries]}`. Whole-
+ * record replacement would drop the local services array; the SPA
+ * would render the world with no clickable links until Pylon
+ * back-fills.
+ *
+ * Field-merge (the post-audit behavior): later source's defined
+ * fields override earlier; earlier source's fields are preserved
+ * where the later source omits them. `id` and `source` always come
+ * from the later source (the precedence contract). Implementation:
+ * `{ ...byId.get(id), ...world }` — ES spread skips own properties
+ * with value `undefined` only if the producer ELIDES them; explicit
+ * `field: undefined` does override. Therefore source authors should
+ * OMIT fields they don't manage rather than setting them to
+ * `undefined` / `[]`.
+ *
+ * @typedef {import('./worlds-source.mjs').WorldsSource} WorldsSource
+ * @typedef {import('./worlds-source.mjs').WorldSummary} WorldSummary
+ */
+
+/**
+ * @typedef {object} ComposeWorldsSourcesOptions
+ * @property {number} [timeoutMs=2000]
+ *   Per-source timeout cap. A source whose `list()` doesn't resolve
+ *   within this budget is treated as `[]` for this composition pass
+ *   (logged at error level). Default matches the docker-inspect
+ *   timeout used elsewhere in host-cp so the /api/worlds path's worst-
+ *   case wall time stays bounded by it.
+ * @property {(sourceName: string, err: unknown) => void} [onSourceError]
+ *   Invoked when a source rejects or times out. Defaults to
+ *   `console.error('[worlds-source] <name> list() failed:', err)`.
+ *   Tests inject a spy to assert log behavior without polluting
+ *   stderr.
+ */
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/**
+ * Per-source last-known-good cache. Keyed by source.name → WorldSummary[].
+ * When a source resolves successfully, its output is stored here. When a
+ * source rejects or times out, we fall back to the cached value so the
+ * dashboard shows stale data rather than blanking. Stale data self-heals
+ * on the next successful poll.
+ *
+ * Process-local, no TTL — the running server is authoritative. Tests that
+ * need a clean slate should call _resetLastKnownGoodCache().
+ *
+ * @type {Map<string, import('./worlds-source.mjs').WorldSummary[]>}
+ */
+const _lastKnownGood = new Map();
+
+/**
+ * Wraps a Promise in a per-source timeout race. The timeout error
+ * carries the source name so `onSourceError` can log it usefully.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} sourceName
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, sourceName) {
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`source "${sourceName}" timed out after ${ms}ms`));
+    }, ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer !== null) clearTimeout(timer);
+  });
+}
+
+/**
+ * Reset the last-known-good cache. Exposed for tests only — call before
+ * each test that needs a clean slate.
+ */
+export function _resetLastKnownGoodCache() {
+  _lastKnownGood.clear();
+}
+
+/**
+ * @param {WorldsSource[]} sources
+ *   Sources to compose. Order expresses precedence: later wins.
+ * @param {ComposeWorldsSourcesOptions} [options]
+ * @returns {Promise<WorldSummary[]>}
+ *   Deduped union of every source's `list()` output, keyed by `id`.
+ *   On collision: fields from later source override earlier where
+ *   defined; earlier fields preserved where later source omits them.
+ */
+export async function composeWorldsSources(sources, options = {}) {
+  if (sources.length === 0) return [];
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const onSourceError =
+    options.onSourceError ??
+    ((name, err) => {
+      console.error(`[worlds-source] ${name} list() failed:`, err);
+    });
+
+  const settled = await Promise.allSettled(
+    sources.map((s) => withTimeout(s.list(), timeoutMs, s.name)),
+  );
+
+  /** @type {Map<string, WorldSummary>} */
+  const byId = new Map();
+  for (let i = 0; i < settled.length; i++) {
+    const result = settled[i];
+    const source = sources[i];
+    let resolved;
+    if (result.status === 'rejected') {
+      onSourceError(source.name, result.reason);
+      const lkg = _lastKnownGood.get(source.name);
+      if (!lkg) continue;
+      resolved = lkg;
+    } else {
+      resolved = result.value;
+      _lastKnownGood.set(source.name, result.value);
+    }
+    for (const world of resolved) {
+      // Field-merge on collision: later source overrides earlier
+      // where defined; earlier preserved where later omits. Keeps
+      // local service-strip + host_port intact when Pylon claims a
+      // world but hasn't populated those fields yet.
+      const prior = byId.get(world.id);
+      byId.set(world.id, prior ? { ...prior, ...world } : world);
+    }
+  }
+  return [...byId.values()];
+}