@pleri/olam-cli 0.1.7

package/host-cp/src/server.mjs

@@ -0,0 +1,2215 @@
+#!/usr/bin/env node
+// Phase F-2-B (B3): host CP HTTP server.
+//
+// Replaces the B2 placeholder. Wires together:
+//   - secret-cache.mjs        — 5min TTL Map-based per-world secret cache
+//   - container-secret-fetcher.mjs — docker-socket-proxy exec to read secrets
+//   - docker-events.mjs       — restart/stop event subscriber
+//   - proxy.mjs               — JSON proxy + verbatim header passthrough
+//
+// Routes:
+//   - GET  /health                           server diagnostics
+//   - ANY  /api/world/<id>/<route...>        proxied to per-world CP with
+//                                            X-Olam-Secret injected
+//   - other paths (B4 ships static SPA + auth gate; B6 ships /api/projects,
+//                  /api/workspaces, /api/workspaces/match)
+//
+// World registry lookup (worldId → host port + container name) is a
+// stub for B3 — B6 wires the real `~/.olam/worlds.db` reader. For now,
+// the lookup table is populated from env (OLAM_HOST_CP_WORLDS_JSON) for
+// local dev, and the M2 ship gate test (B10) will run with a single
+// world registered via this env var until B6 lands.
+
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import url from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+import { SecretCache } from './secret-cache.mjs';
+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 { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
+import { StartupToken } from './auth.mjs';
+import { SseGate, isSsePath, wireRelease } from './sse-gate.mjs';
+import {
+  loadWorkspaces,
+  workspacesForApi,
+  projectsFromWorkspaces,
+  matchWorkspacesByProjects,
+} from './workspace-catalog.mjs';
+import {
+  createWorldNamesStore,
+  inferNameFromTask,
+  normalizeName,
+} from './world-names-store.mjs';
+import { createLocalWorldsSource } from './local-worlds-source.mjs';
+import { createPylonWorldsSource } from './pylon-worlds-source.mjs';
+import { composeWorldsSources } from './compose-worlds-sources.mjs';
+import { createWorldPrStateStore } from './world-pr-state.mjs';
+import { PlanOrchestrator } from './plan-orchestrator.mjs';
+import { createPrMergePoller } from './pr-merge-poller.mjs';
+import { parse as parseYaml } from 'yaml';
+import { startWorldsDbReconciler } from './worlds-db-source.mjs';
+import { authSecretHint } from './auth-secret-hint.mjs';
+import * as tunnelManager from './world-tunnel-manager.mjs';
+import { getProcessSnapshot, subscribeToProcesses } from './process-poller.mjs';
+import { buildVersionSnapshot } from './version-status.mjs';
+
+// ── Deployment-mode detection ─────────────────────────────────────
+//
+// host-cp runs either as a Docker container (via `olam host-cp start` /
+// compose.yaml) or as a bare-node process on the operator's host (for
+// active development on host-cp itself). The two modes differ in how
+// per-world CPs are reachable:
+//
+//   container → host.docker.internal:<port>  (Docker Desktop / Linux host-gateway)
+//   bare      → 127.0.0.1:<port>             (loopback — same machine)
+//
+// Override: OLAM_HOST_CP_MODE=container|bare
+// Auto-detect: /.dockerenv is created by the docker runtime on container start.
+
+const HOST_CP_MODE = process.env.OLAM_HOST_CP_MODE
+  ?? (fs.existsSync('/.dockerenv') ? 'container' : 'bare');
+const WORLD_HOST = HOST_CP_MODE === 'container' ? 'host.docker.internal' : '127.0.0.1';
+
+const PORT = parseInt(process.env.OLAM_HOST_CP_PORT ?? '19000', 10);
+// In container mode the host-cp talks to the docker daemon via the
+// socket-proxy sidecar (the proxy enforces the read-only API allow-list).
+// In bare-node mode there's no socket-proxy on the host; we shell out to
+// `docker exec` directly via child_process. The sentinel `docker-cli`
+// triggers that path in fetchContainerSecret. (B5 below; closes the
+// secret_fetch_failed bare-node bug class — see ~/.claude/plans/bare-node-mode-safeguards.md.)
+const DOCKER_HOST = process.env.DOCKER_HOST
+  ?? (HOST_CP_MODE === 'container' ? 'tcp://docker-socket-proxy:2375' : 'docker-cli');
+const TTL_SEC = parseInt(process.env.OLAM_SECRET_CACHE_TTL_SEC ?? '300', 10);
+const HOST_FOR_WORLD = process.env.OLAM_HOST_FOR_WORLD ?? WORLD_HOST;
+const TOKEN_PATH = process.env.OLAM_HOST_CP_TOKEN_PATH ?? '/data/host-cp.token';
+const AUTH_SERVICE_URL = process.env.OLAM_AUTH_SERVICE_URL ?? `http://${HOST_FOR_WORLD}:9999`;
+const AUTH_SERVICE_SECRET = process.env.OLAM_AUTH_SECRET ?? '';
+const SSE_CAP = parseInt(process.env.OLAM_SSE_MAX_CONCURRENT ?? '50', 10);
+const WORKSPACES_DIR = process.env.OLAM_WORKSPACES_DIR ?? '/data/workspaces';
+const WORLD_NAMES_PATH =
+  process.env.OLAM_WORLD_NAMES_PATH ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/world-names.json'
+    : path.join(os.homedir(), '.olam', 'world-names.json'));
+const PR_STATE_PATH = process.env.OLAM_WORLD_PR_STATE_PATH ?? '/data/world-pr-state.json';
+const GH_HOSTS_PATH = process.env.OLAM_GH_HOSTS_PATH ?? '/gh-config/hosts.yml';
+const PR_POLL_INTERVAL_MS = parseInt(process.env.OLAM_PR_POLL_INTERVAL_MS ?? '300000', 10);
+const MERGE_GRACE_MS = parseInt(process.env.OLAM_MERGE_GRACE_MS ?? '600000', 10);
+const PROGRESS_CACHE_MS = parseInt(process.env.OLAM_PROGRESS_CACHE_MS ?? '5000', 10);
+const STARTED_AT = Date.now();
+const WORLDS_DB_PATH =
+  process.env.OLAM_WORLDS_DB ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/worlds.db'
+    : path.join(os.homedir(), '.olam', 'worlds.db'));
+const WORLD_TUNNELS_PATH =
+  process.env.OLAM_WORLD_TUNNELS_PATH ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/world-tunnels.json'
+    : path.join(os.homedir(), '.olam', 'world-tunnels.json'));
+
+// Inject deployment-mode config into the tunnel manager so it doesn't
+// need to re-derive HOST_CP_MODE or container-specific path literals.
+tunnelManager.configure({ hostForWorld: HOST_FOR_WORLD, tunnelsPath: WORLD_TUNNELS_PATH });
+
+// ── Version detection (Phase 1 of self-upgrade) ──────────────────────────
+//
+// Polls operator's local repo HEAD every 60s and compares to the SHA baked
+// into each component image at build time. Detection only — no auto-upgrade.
+// OLAM_REPO_PATH overrides the default /operator-repo mount path.
+const VERSION_POLL_INTERVAL_MS = parseInt(
+  process.env.OLAM_VERSION_POLL_INTERVAL_MS ?? '60000', 10,
+);
+
+// Derive docker API base from DOCKER_HOST (already computed above).
+const DOCKER_API_BASE =
+  DOCKER_HOST === 'docker-cli'
+    ? 'http://localhost:2375' // bare-node: no socket proxy, docker API unavailable
+    : DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+
+/** @type {import('./version-status.mjs').VersionSnapshot | null} */
+let versionSnapshot = null;
+
+async function refreshVersionSnapshot() {
+  try {
+    versionSnapshot = await buildVersionSnapshot({
+      authServiceUrl: AUTH_SERVICE_URL,
+      dockerApiBase: DOCKER_API_BASE,
+    });
+  } catch (err) {
+    console.error(`[version] snapshot refresh failed: ${err.message}`);
+  }
+}
+
+// Kick off an initial check immediately, then poll every 60s.
+refreshVersionSnapshot();
+const versionPollTimer = setInterval(refreshVersionSnapshot, VERSION_POLL_INTERVAL_MS);
+
+// ── World registry — persistent + admin-managed ───────────────────────
+//
+// Three sources, merged in priority order (later overrides earlier):
+//   1. OLAM_HOST_CP_WORLDS_JSON env var (legacy stub, manual override)
+//   2. ~/.olam/host-cp-registry.json (mounted at /data; persistent across
+//      container restarts, edited by `olam host-cp register/deregister`
+//      and the auto-register hook in `olam create`).
+//   3. POST /api/admin/registry runtime updates (writes through to file 2).
+//
+// Format of registry file: JSON object mapping worldId → host port.
+//   { "amber-fox-1234": 20780, "atlas-audit-9999": 19180 }
+
+const REGISTRY_PATH =
+  process.env.OLAM_HOST_CP_REGISTRY_PATH ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/host-cp-registry.json'
+    : path.join(os.homedir(), '.olam', 'host-cp-registry.json'));
+
+/** @type {Record<string, number>} */
+let WORLDS = {};
+
+function loadRegistryFromEnv() {
+  try {
+    const raw = process.env.OLAM_HOST_CP_WORLDS_JSON;
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    console.error(`OLAM_HOST_CP_WORLDS_JSON parse error: ${err.message}`);
+    return {};
+  }
+}
+
+function loadRegistryFromFile() {
+  try {
+    if (!fs.existsSync(REGISTRY_PATH)) return {};
+    const raw = fs.readFileSync(REGISTRY_PATH, 'utf-8');
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    console.error(`registry file parse error at ${REGISTRY_PATH}: ${err.message}`);
+    return {};
+  }
+}
+
+function persistRegistry() {
+  try {
+    const tmp = `${REGISTRY_PATH}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(WORLDS, null, 2) + '\n');
+    fs.renameSync(tmp, REGISTRY_PATH);
+  } catch (err) {
+    console.error(`registry write failed: ${err.message}`);
+  }
+}
+
+WORLDS = { ...loadRegistryFromEnv(), ...loadRegistryFromFile() };
+
+// ── Wire dependencies ────────────────────────────────────────────────
+
+const cache = new SecretCache({ ttlSec: TTL_SEC });
+
+// Phase F-2-B (B4): startup-token auth. Generated once on boot if no
+// token file exists; reused if the lifecycle CLI (F-2-D) wrote one
+// before the container started. SPA reads via /api/bootstrap (unauthed
+// for single-user-local; T4 mitigation documented in auth.mjs).
+const auth = new StartupToken({ tokenPath: TOKEN_PATH });
+auth.ensure();
+
+// World-names store: persists human-friendly names per world. Container
+// id stays immutable; name is what the UI shows as the world's heading.
+// File path is mounted at /data/world-names.json (host: ~/.olam/world-names.json).
+const worldNames = createWorldNamesStore(WORLD_NAMES_PATH);
+
+// Phase E2 (olam-dogfood-vision): LocalWorldsSource — wraps today's
+// dockerode-driven enumeration in a WorldsSource-shaped object so E4's
+// composition layer can fan out across multiple sources. Deps are
+// injected as functions so the source reads fresh state per list()
+// (post-create/destroy mutations are visible immediately) and to avoid
+// the module-cycle that direct imports would create.
+//   getWorldsRegistry — fresh WORLDS map per call
+//   getWorldName      — operator-set friendly name or null
+//   fetchWorldServices — same probe path as the pre-E2 inline handler
+const localSource = createLocalWorldsSource({
+  getWorldsRegistry: () => WORLDS,
+  getWorldName: (id) => worldNames.get(id),
+  fetchWorldServices,
+});
+
+// Phase E4 (olam-dogfood-vision): worlds-source composition.
+//
+// `OLAM_HOST_CP_PYLON_ENABLED=1|true` adds the Pylon source to the
+// composition chain. Until the @pleri/pylon SDK is wired (E3 stub),
+// the pylon source returns []; enabling it is a strict no-op over
+// local-only behavior — it just exercises the composition path.
+const PYLON_ENABLED = ['1', 'true'].includes(
+  String(process.env.OLAM_HOST_CP_PYLON_ENABLED ?? '').toLowerCase(),
+);
+
+/**
+ * Builds the composed WorldsSource array in PRECEDENCE ORDER.
+ *
+ * ORDER MATTERS — composeWorldsSources dedupes by id and the LAST
+ * source to claim an id wins. Cloud must come AFTER local so Pylon-
+ * managed metadata overrides local docker stubs when an id is
+ * resident in both. Reordering this array silently changes which
+ * source's `status`/`services`/`name` values surface in the SPA — a
+ * regression surface that would otherwise be invisible to a code-
+ * reviewer skimming the call site.
+ *
+ * The function form (rather than a top-level const) makes the
+ * convention explicit at every call site and gives tests a clean
+ * seam for asserting precedence without re-instantiating server
+ * state.
+ *
+ * Audit follow-up (Phase E CP3 HIGH-3): extracted from inline
+ * `worldsSources` const so the precedence contract is named, not
+ * smuggled in as array-literal order.
+ *
+ * @param {{ pylonEnabled: boolean }} flags
+ * @returns {import('./worlds-source.mjs').WorldsSource[]}
+ *   Sources in precedence order (last wins on dedup).
+ */
+function buildWorldsSources({ pylonEnabled }) {
+  /** @type {import('./worlds-source.mjs').WorldsSource[]} */
+  const sources = [localSource];
+  if (pylonEnabled) {
+    // APPEND, never prepend — cloud must come after local for
+    // dedup-cloud-wins to hold.
+    sources.push(createPylonWorldsSource({ enabled: true }));
+  }
+  return sources;
+}
+
+const worldsSources = buildWorldsSources({ pylonEnabled: PYLON_ENABLED });
+
+// ── PR merge auto-destroy ─────────────────────────────────────────────
+
+const prStateStore = createWorldPrStateStore(PR_STATE_PATH);
+
+async function resolveGhToken() {
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  try {
+    const raw = fs.readFileSync(GH_HOSTS_PATH, 'utf-8');
+    const parsed = parseYaml(raw);
+    return parsed?.['github.com']?.oauth_token ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const prPoller = createPrMergePoller({
+  prStateStore,
+  getGhToken: resolveGhToken,
+  destroyWorld: async (worldId) => {
+    tunnelManager.killWorld(worldId);
+    const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+    const containerName = `olam-${worldId}-devbox`;
+    try {
+      await fetch(`${apiBase}/containers/${encodeURIComponent(containerName)}/stop`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(10000),
+      });
+    } catch (err) {
+      console.error(`[pr-merge-poller] container stop failed for ${worldId}:`, err.message);
+    }
+    if (worldId in WORLDS) {
+      const next = { ...WORLDS };
+      delete next[worldId];
+      WORLDS = next;
+      persistRegistry();
+    }
+  },
+  pollIntervalMs: PR_POLL_INTERVAL_MS,
+  gracePeriodMs: MERGE_GRACE_MS,
+});
+prPoller.start();
+
+// ── Worlds-DB reconcile loop ────────────────────────────────────
+//
+// When host-cp runs bare-node, the CLI's auto-register may not have fired
+// (e.g., host-cp started after `olam create`). This reconciler bridges
+// that gap: it reads worlds.db and registers any running worlds that
+// aren't already in WORLDS.
+const worldsDbReconciler = startWorldsDbReconciler({
+  dbPath: WORLDS_DB_PATH,
+  dockerHost: DOCKER_HOST,
+  worldHost: WORLD_HOST,
+  getRegistry: () => WORLDS,
+  onWorldAdded: (id, port) => {
+    WORLDS = { ...WORLDS, [id]: port };
+    persistRegistry();
+  },
+  onWorldRemoved: (id) => {
+    if (id in WORLDS) {
+      const next = { ...WORLDS };
+      delete next[id];
+      WORLDS = next;
+      persistRegistry();
+    }
+  },
+});
+
+// ── Plan orchestrator (Phase 1 spike) ─────────────────────────────────────
+//
+// Single-persona brainstorm conversation backed by @mariozechner/pi-coding-agent.
+// Uses the Olam auth-service vault (same credentials as the rest of host-cp).
+// No ANTHROPIC_API_KEY required — tokens are fetched from auth-service on demand.
+const planOrchestrator = new PlanOrchestrator({
+  authServiceUrl: AUTH_SERVICE_URL,
+  authServiceSecret: AUTH_SERVICE_SECRET,
+});
+
+/**
+ * Guard: return 503 when auth-service has no active claude credential.
+ * Async — calls auth-service with a 5s timeout.
+ *
+ * @param {import('node:http').ServerResponse} res
+ * @returns {Promise<boolean>}
+ */
+async function requirePlanCredential(res) {
+  const ok = await planOrchestrator.hasCredential();
+  if (!ok) {
+    jsonReply(res, 503, { error: 'no_claude_credential', message: 'No active Claude credential in vault. Add one via Settings → Credentials.' });
+    return false;
+  }
+  return true;
+}
+
+// ── World-progress caches (Phase A — feat/inbox-row-progress) ───
+//
+// `prCache` memoizes GitHub PR/check results per branch with a 30s TTL
+// so each row poll doesn't hit the GH API. `progressCache` is a 5s TTL
+// on the assembled progress envelope (thoughts + git + pr) so a 5s SPA
+// poll across N worlds is at most N file-read+1-gh-call per cycle.
+const prCache = createPrCache();
+const progressCache = new Map(); // worldId → {fetchedAt, data}
+/** @type {{ data: unknown[], fetchedAt: number } | null} */
+let prListCacheEntry = null; // /api/prs — 60s TTL global PR list for Cmd+K
+
+// Phase F-2-B (B5): SSE concurrent-connection cap (P4 mitigation). Caps
+// at OLAM_SSE_MAX_CONCURRENT (default 50). Above the cap returns
+// 503 Retry-After: 30 so the SPA can back off + the per-world CP isn't
+// flooded with proxy connections.
+const sseGate = new SseGate({ maxConcurrent: SSE_CAP });
+
+// Subscribe to docker events on boot. Unsubscribed at shutdown.
+const stopEvents = subscribeDockerEvents({
+  dockerHost: DOCKER_HOST,
+  onWorldRestart: (worldId) => cache.invalidate(worldId),
+});
+
+/**
+ * Resolve worldId → secret. Cache hit returns immediately; miss fetches
+ * from the docker-socket-proxy + caches.
+ *
+ * @param {string} worldId
+ * @returns {Promise<string>}
+ */
+async function getSecret(worldId) {
+  const cached = cache.get(worldId);
+  if (cached !== null) return cached;
+  const secret = await fetchContainerSecret({
+    worldId,
+    dockerHost: DOCKER_HOST,
+  });
+  cache.set(worldId, secret);
+  return secret;
+}
+
+// ── HTTP server ──────────────────────────────────────────────────────
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+
+  // /health: fast diagnostics, no auth, no proxying. Docker healthcheck
+  // hits this; SPA pre-load may also poll. Stays unauth so the container
+  // healthcheck doesn't need to know the token.
+  if (url.pathname === '/health') {
+    return jsonReply(res, 200, {
+      status: 'ok',
+      phase: 'B4',
+      uptime_seconds: Math.floor((Date.now() - STARTED_AT) / 1000),
+      cache: {
+        worlds: cache.worldIds(),
+        ttl_sec: TTL_SEC,
+      },
+      mode: {
+        deployment: HOST_CP_MODE,
+        world_host: HOST_FOR_WORLD,
+      },
+      registry: {
+        worlds_known: Object.keys(WORLDS),
+        source: 'env: OLAM_HOST_CP_WORLDS_JSON (B6 will wire worlds.db)',
+      },
+      auth: {
+        token_path: TOKEN_PATH,
+        token_present: Boolean(auth.token),
+      },
+      sse: sseGate.stats(),
+    });
+  }
+
+  // /api/bootstrap: SPA reads the token at load time. Unauthed because
+  // anything local that can hit 127.0.0.1:19000 can also read the token
+  // file directly (same OS-level privilege boundary). Single-user-only;
+  // multi-user mode (Phase G+) will swap this for cookie-with-Secure.
+  if (url.pathname === '/api/bootstrap') {
+    return jsonReply(res, 200, {
+      token: auth.token,
+      cookie_name: 'olam_host_cp_token',
+      header_name: 'authorization',
+      header_format: 'Bearer <token>',
+      hint: 'SPA: set document.cookie = `olam_host_cp_token=${token}; path=/; samesite=strict` then fetch (`/api/world/...`) freely.',
+    });
+  }
+
+  // Phase F-2-D dogfood fix: serve the SPA dist/ for non-API GET requests
+  // BEFORE auth gate. The SPA itself is the auth gate — it loads, fetches
+  // /api/bootstrap (unauthed), sets the cookie, then makes authed API calls.
+  // Without static-file serving the SPA can never load and the operator
+  // sees raw 401 JSON in the browser.
+  //
+  // Routes hit this branch:
+  //   /              → dist/index.html
+  //   /worlds        → dist/index.html (SPA routing)
+  //   /workspaces    → dist/index.html
+  //   /world/<id>    → dist/index.html
+  //   /assets/*.js   → dist/assets/*.js
+  //   /favicon.ico   → dist/favicon.ico (if present)
+  //
+  // Anything that doesn't match a static file falls through to the auth
+  // gate + 404 below (preserves the JSON-error contract for unknown
+  // /api/* paths).
+  if (req.method === 'GET' || req.method === 'HEAD') {
+    const served = await tryServeStatic(req, res, url.pathname);
+    if (served) return;
+  }
+
+  // ALL OTHER ROUTES require auth. Reject with 401 if neither cookie
+  // nor Bearer header matches.
+  if (!auth.isAuthorized(req)) {
+    res.writeHead(401, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'WWW-Authenticate': 'Bearer realm="olam-host-cp"',
+    });
+    return res.end(JSON.stringify({
+      error: 'unauthorized',
+      message: 'Set cookie olam_host_cp_token=<value> or Authorization: Bearer <value>. Read /api/bootstrap to get the token.',
+    }));
+  }
+
+  // /api/version/status: returns the current version snapshot (baked SHA
+  // vs operator's local HEAD). No auth required beyond the existing gate
+  // (already applied above). Phase 1 only — detection, no auto-upgrade.
+  if (url.pathname === '/api/version/status' && req.method === 'GET') {
+    if (!versionSnapshot) {
+      return jsonReply(res, 503, { error: 'version_check_pending', message: 'Version snapshot not yet available — try again in a moment.' });
+    }
+    return jsonReply(res, 200, versionSnapshot);
+  }
+
+  // /api/worlds (B7 + dogfood + E2/E4): list worlds via composed
+  // sources. With Pylon disabled (default), `worldsSources` =
+  // [localSource] and the response is identical to E2 — just the
+  // local-source's `list()` output. With OLAM_HOST_CP_PYLON_ENABLED,
+  // pylonSource is appended; on id collision, cloud wins (later
+  // source overrides earlier in the array). Until the SDK lands the
+  // pylon source returns [], so enabling it is currently a no-op.
+  if (url.pathname === '/api/worlds' && req.method === 'GET') {
+    const worlds = await composeWorldsSources(worldsSources);
+    const enriched = worlds.map((w) => {
+      const pr = prStateStore.get(w.id);
+      if (!pr) return w;
+      const graceExpiresAt = pr.pr_merged_at
+        ? new Date(new Date(pr.pr_merged_at).getTime() + MERGE_GRACE_MS).toISOString()
+        : null;
+      return {
+        ...w,
+        pr_url: pr.pr_url,
+        pr_state: pr.pr_state,
+        pr_merged_at: pr.pr_merged_at ?? null,
+        grace_expires_at: graceExpiresAt,
+        auto_destroy_on_merge: pr.auto_destroy_on_merge,
+      };
+    });
+    return jsonReply(res, 200, enriched);
+  }
+
+  // PATCH /api/worlds/<id> — rename a world. Container id is immutable;
+  // this only updates the persisted display name. Body: { name: string }.
+  // 200 on success, 400 on bad input, 404 if the world isn't in the
+  // registry. Empty/whitespace name removes the entry (revert to id).
+  const renameMatch = url.pathname.match(/^\/api\/worlds\/([^/]+)\/?$/);
+  if (renameMatch && req.method === 'PATCH') {
+    const worldId = decodeURIComponent(renameMatch[1]);
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, {
+        error: 'unknown_world',
+        worldId,
+        message: 'world not in registry',
+      });
+    }
+    let bodyRaw = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk) => { bodyRaw += chunk; });
+    req.on('end', () => {
+      let parsed;
+      try {
+        parsed = JSON.parse(bodyRaw || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      // Allow null/empty to clear the name.
+      if (parsed?.name === null || parsed?.name === '') {
+        worldNames.remove(worldId);
+        return jsonReply(res, 200, { id: worldId, name: null });
+      }
+      const normalized = normalizeName(parsed?.name);
+      if (normalized === null) {
+        return jsonReply(res, 400, {
+          error: 'invalid_name',
+          message: 'PATCH body must include {name: string} (non-empty after trim) or {name: null} to clear.',
+        });
+      }
+      try {
+        const stored = worldNames.set(worldId, normalized);
+        jsonReply(res, 200, { id: worldId, name: stored });
+      } catch (err) {
+        jsonReply(res, 500, { error: 'rename_failed', message: err.message });
+      }
+    });
+    return;
+  }
+
+  // GET /api/worlds/<id>/pr — per-world PR state for the inbox row badge.
+  // Returns { pr_number, pr_url, pr_state } sourced from prStateStore.
+  // 200 with all-null fields when no PR is tracked for this world.
+  const worldPrGetMatch = url.pathname.match(/^\/api\/worlds\/([^/]+)\/pr\/?$/);
+  if (worldPrGetMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(worldPrGetMatch[1]);
+    const pr = prStateStore.get(worldId);
+    if (!pr) {
+      return jsonReply(res, 200, { pr_number: null, pr_url: null, pr_state: null });
+    }
+    const prState = pr.pr_state === 'merged_destroyed' ? 'merged' : (pr.pr_state ?? null);
+    return jsonReply(res, 200, {
+      pr_number: pr.pr_number ?? null,
+      pr_url: pr.pr_url ?? null,
+      pr_state: prState,
+    });
+  }
+
+  // POST /api/worlds — Phase D4 (olam-dogfood-vision).
+  //
+  // Architectural decision (deviation from D4 plan, audited at phase
+  // boundary): host-cp does NOT directly invoke WorldManager.createWorld
+  // because:
+  //   - host-cp runs in a slim Docker container (node:22-slim) without
+  //     @olam/core's dependency tree (better-sqlite3 native bindings,
+  //     ~hundreds of LOC of git/docker/auth orchestration).
+  //   - Bringing @olam/core into the container would bloat the image
+  //     and tightly couple host-cp to per-platform native bindings.
+  //   - The MCP layer (Phase D1) and the CLI BOTH already have
+  //     WorldManager via @olam/core. They run on the operator's host
+  //     where native bindings + git/docker just work.
+  //
+  // So this endpoint validates the contract shape and returns a
+  // delegation payload pointing the caller at the MCP tool
+  // (`olam.create_from_prompt`) or the `olam create` CLI. The SPA's
+  // hypothetical CreateWorldModal — currently unwired — would consume
+  // this response and surface the CLI command to the operator.
+  //
+  // The shape `{useMcpTool, command, args, reason}` lets future
+  // automation (e.g., a Claude Code session triggered from the SPA)
+  // act on the response programmatically.
+  if (url.pathname === '/api/worlds' && req.method === 'POST') {
+    let bodyRaw = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk) => { bodyRaw += chunk; });
+    return req.on('end', () => {
+      let body;
+      try {
+        body = JSON.parse(bodyRaw || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return jsonReply(res, 400, {
+          error: 'invalid_body',
+          message: 'POST /api/worlds requires a JSON object body',
+        });
+      }
+      // Contract validation: at least one of (repos, workspace) required.
+      const hasRepos = Array.isArray(body.repos) && body.repos.length > 0;
+      const hasWorkspace = typeof body.workspace === 'string' && body.workspace.length > 0;
+      if (!hasRepos && !hasWorkspace) {
+        return jsonReply(res, 400, {
+          error: 'invalid_body',
+          message: 'POST /api/worlds requires either `repos: string[]` or `workspace: string` to identify the workspace',
+        });
+      }
+      // D-phase audit follow-up (HIGH-2): dropped the `cliCommand`
+      // joined-string field. The previous shape was render-ready for
+      // SPA copy-paste, but body.task / body.repos[i] could contain
+      // shell metacharacters (`;`, `&&`, `$()`, backticks) that would
+      // become injection-by-copy-paste once the SPA modal wires up.
+      // Callers wanting a CLI invocation must now compose it
+      // themselves with proper shell-quoting (Node's `child_process`
+      // arg array, or a `shell-quote` package, or hand-quoted) using
+      // the structured `mcpToolArgs` below.
+      return jsonReply(res, 200, {
+        useMcpTool: 'olam.create_from_prompt',
+        mcpToolArgs: {
+          prompt: typeof body.task === 'string' ? body.task : undefined,
+          repos: hasRepos ? body.repos : undefined,
+          workspace: hasWorkspace ? body.workspace : undefined,
+          name: typeof body.name === 'string' ? body.name : undefined,
+          autoCodexReview: body.autoCodexReview === true,
+        },
+        reason: 'host-cp does not bridge WorldManager directly. Use the MCP tool olam.create_from_prompt (Phase D1) or invoke `olam create` from the CLI on the operator host (composing the command with proper shell-quoting from mcpToolArgs). The world will auto-register with host-cp post-creation (Phase F-2-D PR #50).',
+      });
+    });
+  }
+
+  // ── Admin registry: programmatic register/deregister ──────────────
+  //
+  // POST /api/admin/registry  body: {id: string, port: number}
+  //   → upsert into registry, persist to /data/host-cp-registry.json,
+  //     return updated WORLDS map.
+  //
+  // DELETE /api/admin/registry/<id>
+  //   → remove world from registry, persist, return updated WORLDS map.
+  //
+  // GET /api/admin/registry
+  //   → return current WORLDS map (for diagnostics + idempotency checks).
+  //
+  // Used by the `olam host-cp register/deregister` CLI commands and
+  // auto-called by `olam create` / `olam destroy`.
+  if (url.pathname === '/api/admin/registry' && req.method === 'GET') {
+    return jsonReply(res, 200, { worlds: WORLDS });
+  }
+  if (url.pathname === '/api/admin/registry' && req.method === 'POST') {
+    let body = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      let parsed;
+      try {
+        parsed = JSON.parse(body || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      const id = typeof parsed?.id === 'string' ? parsed.id.trim() : null;
+      const port = typeof parsed?.port === 'number' ? parsed.port : null;
+      if (!id || !port || !Number.isFinite(port)) {
+        return jsonReply(res, 400, {
+          error: 'invalid_payload',
+          message: 'POST body must include {id: string, port: number}',
+        });
+      }
+      WORLDS = { ...WORLDS, [id]: port };
+      persistRegistry();
+      jsonReply(res, 200, { worlds: WORLDS });
+    });
+    return;
+  }
+  const adminDelete = /^\/api\/admin\/registry\/([^/?#]+)$/.exec(url.pathname);
+  if (adminDelete && req.method === 'DELETE') {
+    const id = decodeURIComponent(adminDelete[1]);
+    // Kill tunnels before removing from registry so no cloudflared procs orphan.
+    tunnelManager.killWorld(id);
+    if (id in WORLDS) {
+      const next = { ...WORLDS };
+      delete next[id];
+      WORLDS = next;
+      persistRegistry();
+    }
+    return jsonReply(res, 200, { worlds: WORLDS });
+  }
+
+  // ── Cloudflare Tunnels API ────────────────────────────────────────
+  //
+  // GET  /api/worlds/:id/tunnels         list tunnel state per service
+  // POST /api/worlds/:id/tunnels         start cloudflared per service
+  // DEL  /api/worlds/:id/tunnels/:name   stop one service's tunnel
+  // GET  /api/worlds/:id/tunnels/status  live probe results
+  //
+  // Delegates to world-tunnel-manager.mjs which owns the process Map
+  // and persists state to world-tunnels.json (same sidecar pattern as
+  // world-pr-state.json).
+
+  const tunnelsBase = /^\/api\/worlds\/([^/?#]+)\/tunnels(\/([^/?#]+))?$/.exec(url.pathname);
+  if (tunnelsBase) {
+    const worldId = decodeURIComponent(tunnelsBase[1]);
+    const serviceSegment = tunnelsBase[3] ? decodeURIComponent(tunnelsBase[3]) : null;
+
+    if (req.method === 'GET' && !serviceSegment) {
+      return jsonReply(res, 200, tunnelManager.getWorldTunnels(worldId));
+    }
+
+    if (req.method === 'GET' && serviceSegment === 'status') {
+      const tunnels = tunnelManager.getWorldTunnels(worldId);
+      const results = await Promise.all(
+        tunnels
+          .filter((t) => t.url)
+          .map(async (t) => {
+            try {
+              const r = await fetch(t.url, { signal: AbortSignal.timeout(3000) });
+              return { name: t.name, url: t.url, reachable: r.ok };
+            } catch {
+              return { name: t.name, url: t.url, reachable: false };
+            }
+          }),
+      );
+      return jsonReply(res, 200, results);
+    }
+
+    if (req.method === 'POST' && !serviceSegment) {
+      let body = '';
+      req.setEncoding('utf-8');
+      req.on('data', (chunk) => { body += chunk; });
+      req.on('end', async () => {
+        let parsed;
+        try { parsed = JSON.parse(body || '{}'); } catch (err) {
+          return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+        }
+        if (!Array.isArray(parsed?.services) || parsed.services.length === 0) {
+          return jsonReply(res, 400, {
+            error: 'invalid_payload',
+            message: 'POST body must include {services: [{name, port}]}',
+          });
+        }
+        // Infra ports must never be published — filter both client-side (PublishModal)
+        // and here so direct API callers cannot tunnel the terminal or per-world CP.
+        const INFRA_PORTS = new Set([7681, 8080]);
+        const validServices = parsed.services
+          .filter((svc) => typeof svc.name === 'string')
+          .map((svc) => ({ name: svc.name, port: Number(svc.port) }))
+          .filter((svc) => Number.isFinite(svc.port) && svc.port > 0 && !INFRA_PORTS.has(svc.port));
+        const results = await Promise.all(
+          validServices.map(async (svc) => {
+            try {
+              const tunnelUrl = await tunnelManager.startTunnel(worldId, svc.name, svc.port);
+              return { name: svc.name, port: svc.port, url: tunnelUrl, status: 'running' };
+            } catch (err) {
+              if (err.name === 'AlreadyStartingError') {
+                return { name: svc.name, port: svc.port, url: null, status: 'already_starting', message: err.message };
+              }
+              return { name: svc.name, port: svc.port, url: null, status: 'error', error: err.message };
+            }
+          }),
+        );
+        const anyAlreadyStarting = results.some((r) => r.status === 'already_starting');
+        jsonReply(res, anyAlreadyStarting ? 409 : 200, results);
+      });
+      return;
+    }
+
+    if (req.method === 'DELETE' && serviceSegment && serviceSegment !== 'status') {
+      tunnelManager.stopTunnel(worldId, serviceSegment);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+  }
+
+  // /api/workspaces (B6 + dogfood): list workspaces from
+  // ~/.olam/workspaces/*.yaml. Returns the CF-Worker-compatible
+  // envelope `{workspaces: WorkspaceSummary[]}` so the existing SPA's
+  // useWorkspaces hook unmarshals correctly. Sensitive keys redacted
+  // by workspacesForApi for any future field that holds them.
+  if (url.pathname === '/api/workspaces' && req.method === 'GET') {
+    const ws = loadWorkspaces(WORKSPACES_DIR);
+    const summaries = workspacesForApi(ws).map((w) => ({
+      name: w.name,
+      repoCount: Array.isArray(w.repos) ? w.repos.length : 0,
+      // M5 dogfood follow-up: Phase D's `olam_create_from_prompt` MCP
+      // tool + `olam create --from-prompt` CLI both call this endpoint
+      // to assemble a workspace catalog for inference. They expect
+      // `projects: string[]` per entry; without it, decideWorkspaceMatch
+      // gets an empty catalog and everything degenerates to "create-
+      // new" or low-confidence picker. Project names are NOT sensitive
+      // (workspace YAMLs are operator-curated), so emitting them here
+      // is safe and additive — existing SPA consumers ignore the
+      // extra field.
+      projects: Array.isArray(w.repos)
+        ? w.repos.map((r) => r.name).filter((n) => typeof n === 'string')
+        : [],
+      updatedAt: w.updatedAt,
+    }));
+    return jsonReply(res, 200, { workspaces: summaries });
+  }
+
+  // /api/projects (B6 + D13): deduplicated project union across all workspaces.
+  // SPA's create-world flow consumes this for the project-multi-select.
+  if (url.pathname === '/api/projects' && req.method === 'GET') {
+    const ws = loadWorkspaces(WORKSPACES_DIR);
+    return jsonReply(res, 200, projectsFromWorkspaces(ws));
+  }
+
+  // /api/workspaces/match (B6 + D13 + T14): exact set-equality match.
+  // Body: { projects: string[] }. Returns 0/1/N matching workspaces for
+  // the SPA's 3-state chip UX ([NEW] / pre-selected / dropdown).
+  if (url.pathname === '/api/workspaces/match' && req.method === 'POST') {
+    let bodyRaw = '';
+    req.setEncoding('utf-8');
+    req.on('data', (chunk) => { bodyRaw += chunk; });
+    req.on('end', () => {
+      let parsed;
+      try {
+        parsed = JSON.parse(bodyRaw || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      const projects = Array.isArray(parsed?.projects) ? parsed.projects.filter((p) => typeof p === 'string') : null;
+      if (!projects) {
+        return jsonReply(res, 400, {
+          error: 'missing_projects',
+          message: 'POST body must include {projects: string[]}',
+        });
+      }
+      const ws = loadWorkspaces(WORKSPACES_DIR);
+      const matches = matchWorkspacesByProjects(ws, projects);
+      jsonReply(res, 200, {
+        projects,
+        matches: workspacesForApi(matches),
+        count: matches.length,
+      });
+    });
+    return;
+  }
+
+  // ── Host-level auth proxy (/api/auth/*) ───────────────────────────
+  //
+  // Proxies to the olam-auth container (port 9999). These are distinct from
+  // the per-world /api/auth/* routes — they authenticate at the host level so
+  // all new worlds inherit credentials without re-authenticating.
+  //
+  // GET  /api/auth/status         → normalized {claude:{authenticated,email?}, codex:{authenticated}}
+  // POST /api/auth/claude/trigger → start PKCE, returns {loginUrl, state}
+  // POST /api/auth/claude/complete → body:{state,code}, completes exchange
+  // POST /api/auth/codex/trigger  → same for codex
+  // POST /api/auth/codex/complete → same for codex
+
+  if (url.pathname === '/api/auth/status' && req.method === 'GET') {
+    try {
+      const upstream = await authServiceFetch('GET', '/credentials/status');
+      const raw = await upstream.json();
+      const accounts = Array.isArray(raw.accounts) ? raw.accounts : [];
+      const claudeAcc = accounts.find((a) => a.provider === 'claude' && a.tokenValid);
+      const codexAcc = accounts.find((a) => a.provider === 'codex' && a.tokenValid);
+      return jsonReply(res, 200, {
+        claude: claudeAcc
+          ? { authenticated: true, email: claudeAcc.email }
+          : { authenticated: false },
+        codex: codexAcc
+          ? { authenticated: true, email: codexAcc.email }
+          : { authenticated: false },
+      });
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  // Compat aliases: /api/auth/trigger and /api/auth/complete (no
+  // claude/ prefix) are what the legacy useAuth.ts hook calls when it's
+  // mounted at host-cp scope (no /world/<id> in the URL, so the
+  // bootstrap script doesn't rewrite to a per-world path). The new
+  // useHostAuth.ts hook calls /api/auth/claude/trigger directly. Both
+  // forward to the same upstream /credentials/add. Without this alias
+  // the host-level auth modal 404s.
+  if ((url.pathname === '/api/auth/trigger' || url.pathname === '/api/auth/claude/trigger') && req.method === 'POST') {
+    try {
+      const upstream = await authServiceFetch('POST', '/credentials/add', { provider: 'claude', label: 'host-claude' });
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if ((url.pathname === '/api/auth/complete' || url.pathname === '/api/auth/claude/complete') && req.method === 'POST') {
+    try {
+      const body = await readRequestBody(req);
+      const upstream = await authServiceFetch('POST', '/credentials/complete', body);
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/auth/codex/trigger' && req.method === 'POST') {
+    try {
+      const upstream = await authServiceFetch('POST', '/credentials/add', { provider: 'codex', label: 'host-codex' });
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/auth/codex/complete' && req.method === 'POST') {
+    try {
+      const body = await readRequestBody(req);
+      const upstream = await authServiceFetch('POST', '/credentials/complete', body);
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  // ── Multi-credential vault (PR #79 surface) ─────────────────────────
+  //
+  // The auth-service's `/credentials/status` already returns the full
+  // vault — `{accounts:[{id, accountLabel, email, provider, plan, state,
+  // tokenValid, expiresIn, rateLimited, rateLimitResetsAt, lastUsed,
+  // lastRefreshed, usage}, …]}`. We re-shape it here into the contract
+  // the SPA's CredentialFleet expects (camelCase, flat usage block) so
+  // future auth-service refactors stay invisible to the dashboard.
+  //
+  // GET    /api/auth/credentials                    → {credentials:[…]}
+  // POST   /api/auth/credentials/add                → body:{provider,label}
+  // POST   /api/auth/credentials/<id>/disable
+  // POST   /api/auth/credentials/<id>/enable
+  // DELETE /api/auth/credentials/<id>
+  // GET    /api/auth/events                         → SSE hotswap stream
+
+  if (url.pathname === '/api/auth/credentials' && req.method === 'GET') {
+    try {
+      const upstream = await authServiceFetch('GET', '/credentials/status');
+      const raw = await upstream.json();
+      const accounts = Array.isArray(raw.accounts) ? raw.accounts : [];
+      return jsonReply(res, upstream.status, { credentials: accounts.map(normalizeCredential) });
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/auth/credentials/add' && req.method === 'POST') {
+    try {
+      const body = await readRequestBody(req);
+      const provider = body && typeof body === 'object' && body.provider ? String(body.provider) : 'claude';
+      const label = body && typeof body === 'object' && body.label ? String(body.label) : '';
+      if (!label) return jsonReply(res, 400, { error: 'label_required' });
+      const upstream = await authServiceFetch('POST', '/credentials/add', { provider, label });
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/auth/credentials/complete' && req.method === 'POST') {
+    try {
+      const body = await readRequestBody(req);
+      const upstream = await authServiceFetch('POST', '/credentials/complete', body);
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  const credActionMatch = /^\/api\/auth\/credentials\/([^/]+)\/(disable|enable)$/.exec(url.pathname);
+  if (credActionMatch && req.method === 'POST') {
+    const id = decodeURIComponent(credActionMatch[1]);
+    const action = credActionMatch[2];
+    try {
+      const upstream = await authServiceFetch('POST', `/credentials/${encodeURIComponent(id)}/${action}`);
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  const credDeleteMatch = /^\/api\/auth\/credentials\/([^/]+)$/.exec(url.pathname);
+  if (credDeleteMatch && req.method === 'DELETE') {
+    const id = decodeURIComponent(credDeleteMatch[1]);
+    try {
+      const upstream = await authServiceFetch('DELETE', `/credentials/${encodeURIComponent(id)}`);
+      const data = await upstream.json();
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/auth/events' && req.method === 'GET') {
+    handleAuthEvents(req, res);
+    return;
+  }
+
+  // ── Per-world credential telemetry routes ─────────────────────────────
+  //
+  // These are called by the in-world HTTPS proxy when it intercepts
+  // api.anthropic.com responses. Authentication is via the same
+  // Authorization: Bearer <OLAM_HOST_CP_TOKEN> that all API routes use.
+  //
+  // POST /api/worlds/:worldId/credentials/:account/rate-limited
+  //   → forward to auth-service /credentials/:id/rate-limited
+  // POST /api/worlds/:worldId/credentials/:account/invalidate
+  //   → forward to auth-service /credentials/:id/invalidate
+  // POST /api/worlds/:worldId/usage-cap-hit
+  //   → forward to auth-service /credentials/:id/usage-cap-hit
+  //     (account id comes from the request body)
+
+  const worldCredActionMatch = /^\/api\/worlds\/([^/?#]+)\/credentials\/([^/?#]+)\/(rate-limited|invalidate)$/.exec(url.pathname);
+  if (worldCredActionMatch && req.method === 'POST') {
+    const worldId = decodeURIComponent(worldCredActionMatch[1]);
+    const account = decodeURIComponent(worldCredActionMatch[2]);
+    const action = worldCredActionMatch[3];
+    try {
+      const body = await readRequestBody(req).catch(() => ({}));
+      const upstream = await authServiceFetch(
+        'POST',
+        `/credentials/${encodeURIComponent(account)}/${action}`,
+        body,
+      );
+      const data = await upstream.json().catch(() => ({}));
+      console.log(`[worlds/${worldId}] credential ${action}: account="${account}" → ${upstream.status}`);
+      return jsonReply(res, upstream.status, data);
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  const worldUsageCapMatch = /^\/api\/worlds\/([^/?#]+)\/usage-cap-hit$/.exec(url.pathname);
+  if (worldUsageCapMatch && req.method === 'POST') {
+    const worldId = decodeURIComponent(worldUsageCapMatch[1]);
+    try {
+      const body = await readRequestBody(req).catch(() => ({}));
+      // The proxy includes `account` in the body (from ~/.claude/.olam-account-id).
+      // Forward to auth-service if account is provided; log audit entry regardless.
+      console.log(`[worlds/${worldId}] usage-cap-hit: account="${body?.account ?? 'unknown'}" reason="${body?.reason ?? 'unknown'}" match="${body?.match ?? ''}"`);
+      if (body && typeof body === 'object' && body.account) {
+        const account = String(body.account);
+        const upstream = await authServiceFetch(
+          'POST',
+          `/credentials/${encodeURIComponent(account)}/usage-cap-hit`,
+          { resetsAt: body.resetsAt, reason: body.reason, match: body.match },
+        );
+        const data = await upstream.json().catch(() => ({}));
+        return jsonReply(res, upstream.status, data);
+      }
+      // No account: log telemetry but can't update vault state.
+      return jsonReply(res, 200, { ok: true, forwarded: false, reason: 'no_account_in_body' });
+    } catch (err) {
+      return jsonReply(res, 502, { error: 'auth_service_unavailable', message: err.message });
+    }
+  }
+
+  // GET /api/world/<id>/progress — phase ladder progress for inbox row.
+  const progressMatch = /^\/api\/world\/([^/?#]+)\/progress\/?$/.exec(url.pathname);
+  if (progressMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(progressMatch[1]);
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, { error: 'unknown_world', worldId, message: 'world not in registry' });
+    }
+    const now = Date.now();
+    const cached = progressCache.get(worldId);
+    if (cached && now - cached.fetchedAt < PROGRESS_CACHE_MS) {
+      return jsonReply(res, 200, cached.data);
+    }
+    const data = await computeProgress(worldId, {
+      worldsDbPath: WORLDS_DB_PATH,
+      prCache,
+      prStateStore,
+      getGhToken: resolveGhToken,
+    });
+    progressCache.set(worldId, { fetchedAt: Date.now(), data });
+    return jsonReply(res, 200, data);
+  }
+
+  // /api/world/<id>/* → proxy to per-world CP with X-Olam-Secret injected.
+  const parsed = parseProxyPath(url.pathname);
+  if (parsed) {
+    const { worldId, subPath } = parsed;
+    const port = WORLDS[worldId];
+    if (port === undefined) {
+      return jsonReply(res, 404, {
+        error: 'unknown_world',
+        worldId,
+        message: 'world not in registry; B6 will wire worlds.db. For dev, set OLAM_HOST_CP_WORLDS_JSON.',
+      });
+    }
+
+    // Phase F-2-D dogfood: synthesize /session/<id>/state. The CF Worker
+    // had a Durable Object tracking phase progression (created → syncing
+    // → cloning → configuring → warming-claude → ready). The per-world
+    // CP doesn't have a phase machine — by the time it's serving HTTP,
+    // the world is already provisioned + apps booted (or about to). We
+    // short-circuit and return `ready` so useWorldPhase advances past
+    // the default "created" + the SPA renders the dispatch UI without
+    // false progression noise.
+    //
+    // The match is anchored: /session/<exact-worldId>/state. Anything
+    // else falls through to the proxy.
+    const stateMatch = subPath.match(/^\/session\/([^/?#]+)\/state(?:\?|$|#)/);
+    if (stateMatch && stateMatch[1] === worldId && req.method === 'GET') {
+      return jsonReply(res, 200, {
+        phase: 'ready',
+        sessionId: worldId,
+        detail: 'world container running (docker-mode synthesized state)',
+        setupLog: [],
+      });
+    }
+
+    // /api/world/<id>/ttyd/* → proxy directly to ttyd port (NOT the
+    // per-world CP). The per-world CP serves its own SPA fallback for
+    // unknown paths, which would clobber ttyd's HTML and produce
+    // nonsensical /assets/<spa-hash>.css MIME errors.
+    if (subPath.startsWith('/ttyd/') || subPath === '/ttyd') {
+      const portOffset = port - 19080;
+      const ttydPort = 17681 + portOffset;
+      const ttydBase = `http://${HOST_FOR_WORLD}:${ttydPort}`;
+      const ttydSubPath = (subPath === '/ttyd' ? '/' : subPath.slice('/ttyd'.length)) + url.search;
+      proxyToWorld({ req, res, subPath: ttydSubPath, targetBase: ttydBase, secret: '' });
+      return;
+    }
+
+    let secret;
+    try {
+      secret = await getSecret(worldId);
+    } catch (err) {
+      return jsonReply(res, 502, {
+        error: 'secret_fetch_failed',
+        worldId,
+        message: err.message,
+      });
+    }
+    const targetBase = perWorldBase(port, HOST_FOR_WORLD);
+    // Preserve query string + hash on the upstream URL.
+    const subPathWithQuery = subPath + url.search;
+
+    // SSE paths get gated by the concurrent-connection cap (P4). If
+    // we're at cap, the gate writes 503 and returns null; we bail.
+    // Below the cap, we acquire a slot and wire release on close/finish.
+    if (isSsePath(subPath)) {
+      const slot = sseGate.acquire(res);
+      if (!slot) return; // 503 already written
+      wireRelease(res, slot.release);
+    }
+
+    proxyToWorld({ req, res, subPath: subPathWithQuery, targetBase, secret });
+    return;
+  }
+
+  // POST /api/admin/world-pr — record PR association for a world
+  if (url.pathname === '/api/admin/world-pr' && req.method === 'POST') {
+    if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
+    let body = '';
+    req.setEncoding('utf-8');
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      let parsed;
+      try { parsed = JSON.parse(body || '{}'); } catch { return jsonReply(res, 400, { error: 'invalid_json' }); }
+      const { worldId, prUrl, prNumber, prRepo } = parsed ?? {};
+      if (!worldId || !prUrl) return jsonReply(res, 400, { error: 'worldId and prUrl required' });
+      prStateStore.set(worldId, {
+        pr_url: prUrl,
+        pr_number: prNumber ?? null,
+        pr_repo: prRepo ?? null,
+        pr_created_at: new Date().toISOString(),
+        pr_state: 'open',
+        pr_merged_at: null,
+        auto_destroy_on_merge: true,
+      });
+      jsonReply(res, 200, { worldId, pr_state: 'open' });
+    });
+    return;
+  }
+
+  // PATCH /api/admin/world-pr/:worldId — update PR settings (e.g. disable auto-destroy)
+  const worldPrPatch = /^\/api\/admin\/world-pr\/([^/?#]+)$/.exec(url.pathname);
+  if (worldPrPatch && req.method === 'PATCH') {
+    if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
+    const worldId = decodeURIComponent(worldPrPatch[1]);
+    let body = '';
+    req.setEncoding('utf-8');
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      let parsed;
+      try { parsed = JSON.parse(body || '{}'); } catch { return jsonReply(res, 400, { error: 'invalid_json' }); }
+      const existing = prStateStore.get(worldId);
+      if (!existing) return jsonReply(res, 404, { error: 'world not in PR state store' });
+      const updates = {};
+      if (typeof parsed.autoDestroyOnMerge === 'boolean') updates.auto_destroy_on_merge = parsed.autoDestroyOnMerge;
+      prStateStore.set(worldId, updates);
+      jsonReply(res, 200, prStateStore.get(worldId));
+    });
+    return;
+  }
+
+  // DELETE /api/worlds/:worldId — immediate destroy
+  const worldDestroyMatch = /^\/api\/worlds\/([^/?#]+)$/.exec(url.pathname);
+  if (worldDestroyMatch && req.method === 'DELETE') {
+    if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
+    const worldId = decodeURIComponent(worldDestroyMatch[1]);
+    tunnelManager.killWorld(worldId);
+    const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+    const containerName = `olam-${worldId}-devbox`;
+    try {
+      await fetch(`${apiBase}/containers/${encodeURIComponent(containerName)}/stop`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(10000),
+      });
+    } catch (err) {
+      console.error(`[destroy] container stop failed for ${worldId}:`, err.message);
+    }
+    if (worldId in WORLDS) {
+      const next = { ...WORLDS };
+      delete next[worldId];
+      WORLDS = next;
+      persistRegistry();
+    }
+    prStateStore.set(worldId, { pr_state: 'merged_destroyed' });
+    return jsonReply(res, 200, { worldId, destroyed: true });
+  }
+
+  // ── Plan API (Phase 2: multi-persona) ────────────────────────────────────
+  //
+  // GET  /api/plan/personas                                — list personas
+  // POST /api/plan/conversations                           — create conversation
+  // GET  /api/plan/conversations                           — list conversations
+  // GET  /api/plan/conversations/:id                       — get conversation + tree
+  // POST /api/plan/conversations/:id/turns                 — submit turn (+ personaOverride)
+  // POST /api/plan/conversations/:id/handoff               — trigger handoff
+  // GET  /api/plan/conversations/:id/stream                — SSE stream
+
+  if (url.pathname === '/api/plan/personas' && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    return jsonReply(res, 200, planOrchestrator.listPersonas());
+  }
+
+  if (url.pathname === '/api/plan/conversations' && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    let body;
+    try { body = await readRequestBody(req); } catch (err) {
+      return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+    }
+    const title = (body && typeof body === 'object' && typeof body.title === 'string')
+      ? body.title.trim() || null
+      : null;
+    try {
+      const conv = planOrchestrator.createConversation({ title });
+      return jsonReply(res, 201, conv);
+    } catch (err) {
+      return jsonReply(res, 500, { error: 'create_failed', message: err.message });
+    }
+  }
+
+  if (url.pathname === '/api/plan/conversations' && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    try {
+      return jsonReply(res, 200, planOrchestrator.listConversations());
+    } catch (err) {
+      return jsonReply(res, 500, { error: 'list_failed', message: err.message });
+    }
+  }
+
+  const planConvMatch = /^\/api\/plan\/conversations\/([^/?#]+)$/.exec(url.pathname);
+  if (planConvMatch && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    const id = decodeURIComponent(planConvMatch[1]);
+    try {
+      const conv = planOrchestrator.getConversation(id);
+      if (!conv) return jsonReply(res, 404, { error: 'not_found', id });
+      // Return persisted turns alongside conversation metadata.
+      const turns = planOrchestrator.getTurns(id);
+      return jsonReply(res, 200, { ...conv, turns });
+    } catch (err) {
+      return jsonReply(res, 500, { error: 'get_failed', message: err.message });
+    }
+  }
+
+  const planTurnMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/turns$/.exec(url.pathname);
+  if (planTurnMatch && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planTurnMatch[1]);
+    let body;
+    try { body = await readRequestBody(req); } catch (err) {
+      return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+    }
+    const content = (body && typeof body === 'object' && typeof body.content === 'string')
+      ? body.content.trim()
+      : '';
+    if (!content) return jsonReply(res, 400, { error: 'content_required' });
+    const personaOverride = (body && typeof body === 'object' && typeof body.personaOverride === 'string')
+      ? body.personaOverride
+      : undefined;
+    try {
+      const result = await planOrchestrator.submitTurn({ conversationId, content, personaOverride });
+      return jsonReply(res, 202, result);
+    } catch (err) {
+      if (err.code === 'NOT_FOUND') return jsonReply(res, 404, { error: 'not_found', id: conversationId });
+      return jsonReply(res, 500, { error: 'submit_failed', message: err.message });
+    }
+  }
+
+  const planHandoffMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/handoff$/.exec(url.pathname);
+  if (planHandoffMatch && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planHandoffMatch[1]);
+    let body;
+    try { body = await readRequestBody(req); } catch (err) {
+      return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+    }
+    const toPersona = body?.toPersona;
+    if (typeof toPersona !== 'string' || !toPersona) {
+      return jsonReply(res, 400, { error: 'toPersona_required' });
+    }
+    const mode = ['full', 'distilled', 'quoted'].includes(body?.mode) ? body.mode : 'full';
+    const selectedTurnIds = Array.isArray(body?.selectedTurnIds) ? body.selectedTurnIds : [];
+    try {
+      const result = await planOrchestrator.handoff({
+        conversationId, toPersona, mode, selectedTurnIds,
+      });
+      return jsonReply(res, 200, result);
+    } catch (err) {
+      if (err.code === 'NOT_FOUND') return jsonReply(res, 404, { error: 'not_found', id: conversationId });
+      return jsonReply(res, 500, { error: 'handoff_failed', message: err.message });
+    }
+  }
+
+  const planStreamMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/stream$/.exec(url.pathname);
+  if (planStreamMatch && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planStreamMatch[1]);
+    const conv = planOrchestrator.getConversation(conversationId);
+    if (!conv) return jsonReply(res, 404, { error: 'not_found', id: conversationId });
+
+    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
+
+    // Replay any buffered events from the in-flight turn before subscribing.
+    planOrchestrator.drainReplayBuffer(conversationId, res);
+    const cleanup = planOrchestrator.addEventSink(conversationId, res);
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+    return;
+  }
+
+  // ── Phase 4B: lookout agent management ──────────────────────────────────────
+  //
+  // GET    /api/plan/conversations/:id/agents              list lookout agents
+  // POST   /api/plan/conversations/:id/agents/:persona/invite  invite as lookout
+  // PATCH  /api/plan/conversations/:id/agents/:persona     update muted/mode
+  // DELETE /api/plan/conversations/:id/agents/:persona     uninvite
+  // POST   /api/plan/conversations/:id/sidebar/:signalId/dismiss  dismiss signal
+  // POST   /api/plan/conversations/:id/sidebar/:signalId/use      use signal
+
+  const planAgentsMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/agents$/.exec(url.pathname);
+  if (planAgentsMatch && req.method === 'GET') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planAgentsMatch[1]);
+    return jsonReply(res, 200, planOrchestrator.listLookoutAgents(conversationId));
+  }
+
+  const planAgentInviteMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/agents\/([^/?#]+)\/invite$/.exec(url.pathname);
+  if (planAgentInviteMatch && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planAgentInviteMatch[1]);
+    const personaId = decodeURIComponent(planAgentInviteMatch[2]);
+    const conv = planOrchestrator.getConversation(conversationId);
+    if (!conv) return jsonReply(res, 404, { error: 'not_found', id: conversationId });
+    const agent = planOrchestrator.inviteLookout(conversationId, personaId);
+    return jsonReply(res, 200, agent);
+  }
+
+  const planAgentMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/agents\/([^/?#]+)$/.exec(url.pathname);
+  if (planAgentMatch && req.method === 'PATCH') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planAgentMatch[1]);
+    const personaId = decodeURIComponent(planAgentMatch[2]);
+    let body;
+    try { body = await readRequestBody(req); } catch (err) {
+      return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+    }
+    const updates = {};
+    if (typeof body?.muted === 'boolean') updates.muted = body.muted;
+    if (typeof body?.mode === 'string') updates.mode = body.mode;
+    const agent = planOrchestrator.updateLookout(conversationId, personaId, updates);
+    if (!agent) return jsonReply(res, 404, { error: 'not_found' });
+    return jsonReply(res, 200, agent);
+  }
+
+  if (planAgentMatch && req.method === 'DELETE') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planAgentMatch[1]);
+    const personaId = decodeURIComponent(planAgentMatch[2]);
+    planOrchestrator.uninviteLookout(conversationId, personaId);
+    return jsonReply(res, 204, null);
+  }
+
+  const planSidebarSignalMatch = /^\/api\/plan\/conversations\/([^/?#]+)\/sidebar\/([^/?#]+)\/(dismiss|use)$/.exec(url.pathname);
+  if (planSidebarSignalMatch && req.method === 'POST') {
+    if (!await requirePlanCredential(res)) return;
+    const conversationId = decodeURIComponent(planSidebarSignalMatch[1]);
+    const signalId = decodeURIComponent(planSidebarSignalMatch[2]);
+    const action = planSidebarSignalMatch[3];
+    const changed = action === 'dismiss'
+      ? planOrchestrator.dismissSignal(conversationId, signalId)
+      : planOrchestrator.useSignal(conversationId, signalId);
+    if (!changed) return jsonReply(res, 404, { error: 'not_found' });
+    return jsonReply(res, 200, { ok: true });
+  }
+
+  // GET /api/worlds/:id/processes — JSON snapshot of in-container processes.
+  // GET /api/worlds/:id/processes/stream — SSE fanout (5s cadence, per-world).
+  // Inserted after auth middleware and the /api/worlds/:id/services route.
+  const processesMatch = /^\/api\/worlds\/([^/?#]+)\/processes(\/stream)?\/?$/.exec(url.pathname);
+  if (processesMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(processesMatch[1]);
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, { error: 'unknown_world', worldId, message: 'world not in registry' });
+    }
+    const isStream = processesMatch[2] === '/stream';
+    if (isStream) {
+      subscribeToProcesses(worldId, res);
+      return;
+    }
+    const snapshot = await getProcessSnapshot(worldId);
+    return jsonReply(res, 200, snapshot);
+  }
+
+  // GET /api/prs — list recent GitHub PRs for the Cmd+K palette.
+  // Wraps `gh pr list` with a 60s in-process TTL cache so repeated
+  // palette opens don't hammer the GitHub API.
+  if (url.pathname === '/api/prs' && req.method === 'GET') {
+    const now = Date.now();
+    if (prListCacheEntry && now - prListCacheEntry.fetchedAt < 60_000) {
+      return jsonReply(res, 200, prListCacheEntry.data);
+    }
+    try {
+      const { stdout } = await execFileAsync('gh', [
+        'pr', 'list',
+        '--state', 'all',
+        '--limit', '50',
+        '--json', 'number,title,state,headRefName',
+      ], { timeout: 10_000 });
+      const data = JSON.parse(stdout.trim() || '[]');
+      prListCacheEntry = { data, fetchedAt: Date.now() };
+      return jsonReply(res, 200, data);
+    } catch (err) {
+      console.error('[api/prs] gh pr list failed:', err.message);
+      // Return stale cache if available rather than a hard error.
+      if (prListCacheEntry) return jsonReply(res, 200, prListCacheEntry.data);
+      return jsonReply(res, 500, { error: 'gh_failed', message: err.message });
+    }
+  }
+
+  // Anything else → 404. B4 ships static SPA serving + auth.
+  jsonReply(res, 404, {
+    error: 'not_found',
+    pathname: url.pathname,
+    message: 'B3 ships /health + /api/world/<id>/*. B4-B9 ship the rest.',
+  });
+});
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} body
+ */
+function jsonReply(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * Read the full request body as a parsed JSON object. Rejects on body > 64KB
+ * or invalid JSON. Used by auth proxy endpoints.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {Promise<unknown>}
+ */
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    let size = 0;
+    req.setEncoding('utf-8');
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > 65536) { reject(new Error('body too large')); req.destroy(); return; }
+      raw += chunk;
+    });
+    req.on('end', () => {
+      try { resolve(JSON.parse(raw || '{}')); }
+      catch (err) { reject(err); }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Throttle for the auth-secret-misconfigured hint. We log it ONCE per
+ * process boot — repeated 401s on every poll would spam the operator's
+ * docker-compose-logs view. The flag flips back to false only on
+ * restart, which is fine because the env-var → restart cycle is the
+ * only way the secret changes.
+ */
+let _authSecretWarned = false;
+
+/**
+ * Proxy a request to the auth service. Adds X-Olam-Secret header when
+ * AUTH_SERVICE_SECRET is set. Returns the raw fetch Response so callers can
+ * inspect status + body.
+ *
+ * On 401 we log a single, throttled hint that tells the operator
+ * exactly which env var to fix. Pre-fix, an empty OLAM_AUTH_SECRET
+ * silently produced "0 credentials" in the SPA — the only signal was
+ * the operator noticing the missing list.
+ *
+ * @param {'GET' | 'POST' | 'DELETE'} method
+ * @param {string} path  e.g. '/credentials/status'
+ * @param {unknown} [body]  JSON-serializable body (POST only)
+ * @returns {Promise<Response>}
+ */
+async function authServiceFetch(method, path, body) {
+  /** @type {HeadersInit} */
+  const headers = { 'Content-Type': 'application/json' };
+  if (AUTH_SERVICE_SECRET) headers['X-Olam-Secret'] = AUTH_SERVICE_SECRET;
+  const res = await fetch(`${AUTH_SERVICE_URL}${path}`, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  if (res.status === 401 && !_authSecretWarned) {
+    _authSecretWarned = true;
+    console.warn(authSecretHint({
+      authServiceUrl: AUTH_SERVICE_URL,
+      hasSecret: AUTH_SERVICE_SECRET.length > 0,
+    }));
+  }
+  return res;
+}
+
+// ── Multi-credential helpers ────────────────────────────────────────
+
+/**
+ * Reshape an auth-service status entry into the dashboard's flat fleet
+ * record. Forward-only: extra upstream fields are dropped so the SPA
+ * doesn't need to know about server-side migration columns.
+ *
+ * @param {Record<string, unknown>} a
+ */
+function normalizeCredential(a) {
+  /** @type {Record<string, unknown>} */
+  const usage = (a && typeof a.usage === 'object' && a.usage !== null) ? a.usage : {};
+  return {
+    id: a?.id ?? '',
+    label: a?.accountLabel ?? a?.id ?? '',
+    email: a?.email ?? null,
+    provider: a?.provider ?? 'claude',
+    plan: a?.plan ?? null,
+    state: a?.state ?? (a?.tokenValid === false ? 'expired' : 'active'),
+    tokenValid: a?.tokenValid !== false,
+    rateLimitResetsAt: a?.rateLimitResetsAt ?? null,
+    lastUsed: a?.lastUsed ?? null,
+    addedAt: a?.addedAt ?? null,
+    usage: {
+      requestCount5h: Number(usage.requestCount5h ?? 0),
+      windowStartedAt: usage.windowStartedAt ?? null,
+      last429At: usage.last429At ?? null,
+      cumulativeTokens: Number(usage.cumulativeTokens ?? 0),
+    },
+  };
+}
+
+/**
+ * SSE stream of multi-credential fleet events. The host-cp polls the
+ * auth-service every 4s and diffs the previous credential states; any
+ * `active → cooldown` transition emits a hotswap event so the dashboard
+ * can toast it. Active → expired and cooldown → active are surfaced too
+ * (the latter for "credential recovered" hints).
+ *
+ * Event shapes (one JSON object per `data:` line):
+ *   {type:"hello", credentials:[…]}            — initial snapshot
+ *   {type:"hotswap", from_label, reason:"rate-limited",
+ *    to_label?, resetsAt?}
+ *   {type:"recovered", label}
+ *   {type:"snapshot", credentials:[…]}         — periodic refresh hint
+ *
+ * SSE clients reconnect on close; we don't store-and-forward, so a
+ * brief network blip may drop a transition. The fleet hook treats events
+ * as best-effort — the polling cadence still surfaces the new state.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ */
+function handleAuthEvents(req, res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+
+  /** @type {Map<string, {state: string, label: string}>} */
+  let prev = new Map();
+  let closed = false;
+
+  function send(obj) {
+    if (closed) return;
+    try {
+      res.write(`data: ${JSON.stringify(obj)}\n\n`);
+    } catch {
+      closed = true;
+    }
+  }
+
+  async function snapshot() {
+    if (closed) return;
+    try {
+      const upstream = await authServiceFetch('GET', '/credentials/status');
+      const raw = await upstream.json();
+      const accounts = Array.isArray(raw.accounts) ? raw.accounts : [];
+      const credentials = accounts.map(normalizeCredential);
+      const next = new Map();
+      for (const c of credentials) next.set(c.id, { state: c.state, label: c.label });
+
+      // First snapshot: send a hello, no diff.
+      if (prev.size === 0 && next.size > 0) {
+        send({ type: 'hello', credentials });
+      } else {
+        // Diff: detect active→cooldown (rate-limit) and cooldown→active
+        // (recovery). Pick the next active credential as the to_label
+        // hint — selectors elsewhere in the system use lowest-usage, but
+        // the dashboard hint only needs *some* active alternative.
+        const alive = credentials.filter((c) => c.state === 'active');
+        for (const c of credentials) {
+          const before = prev.get(c.id);
+          if (!before) continue;
+          if (before.state === 'active' && c.state === 'cooldown') {
+            const alt = alive.find((a) => a.id !== c.id);
+            send({
+              type: 'hotswap',
+              from_label: before.label,
+              from_id: c.id,
+              to_label: alt ? alt.label : null,
+              to_id: alt ? alt.id : null,
+              reason: 'rate-limited',
+              resetsAt: c.rateLimitResetsAt,
+            });
+          } else if (before.state === 'active' && c.state === 'usage-capped') {
+            const alt = alive.find((a) => a.id !== c.id);
+            send({
+              type: 'hotswap',
+              from_label: before.label,
+              from_id: c.id,
+              to_label: alt ? alt.label : null,
+              to_id: alt ? alt.id : null,
+              reason: 'usage-capped',
+              resetsAt: c.rateLimitResetsAt,
+            });
+          } else if ((before.state === 'cooldown' || before.state === 'usage-capped') && c.state === 'active') {
+            send({ type: 'recovered', label: c.label, id: c.id });
+          }
+        }
+      }
+      prev = next;
+    } catch (err) {
+      // Don't tear down the stream on transient auth-service errors —
+      // the next tick may succeed.
+      send({ type: 'error', message: err?.message ?? 'auth_service_error' });
+    }
+  }
+
+  // Heartbeat keeps proxies from killing idle SSE connections.
+  const heartbeat = setInterval(() => {
+    if (closed) return;
+    try { res.write(': heartbeat\n\n'); } catch { closed = true; }
+  }, 25000);
+
+  // Poll cadence: 4s. Faster than the 5s SPA modal poll so the toast
+  // beats the next visual refresh; slower than 1s so we don't hammer the
+  // auth-service when many tabs are open.
+  const ticker = setInterval(() => { void snapshot(); }, 4000);
+  void snapshot();
+
+  req.on('close', () => {
+    closed = true;
+    clearInterval(heartbeat);
+    clearInterval(ticker);
+  });
+}
+
+// ── Service enrichment (Phase F-2-D dogfood fix) ───────────────────
+//
+// Fetch port bindings for a world's container via docker-socket-proxy
+// inspect. Returns [{name, host_port, internal_port, url}] tagged with
+// well-known internal ports.
+
+const WELL_KNOWN_PORTS = {
+  3000: 'atlas-core (Rails)',
+  5175: 'diner-app (Vite)',
+  7681: 'Terminal (ttyd)',
+  8080: 'Per-world CP',
+};
+
+/**
+ * Quick liveness probe against a service URL. Returns true if the
+ * service responds with ANY HTTP response (1xx-5xx) — we don't care
+ * about status codes because each app has its own conventions (Vite
+ * 200s on /, ttyd may 401, Rails may 500 on /, the per-world CP 200s).
+ * What matters is that something is listening.
+ *
+ * Probed from inside the host-cp container so we use HOST_FOR_WORLD
+ * (host.docker.internal on macOS/Windows, 172.17.0.1 on Linux) — the
+ * SPA's own 127.0.0.1:<port> URL is unreachable from container-side.
+ *
+ * Tight 800ms timeout. Worst case: 4 services × 800ms in parallel ≤ 1s
+ * added to the /api/worlds response — acceptable for a 4s poll cycle.
+ */
+async function probeServiceLive(hostPort) {
+  const probeUrl = `http://${HOST_FOR_WORLD}:${hostPort}/`;
+  try {
+    const res = await fetch(probeUrl, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(800),
+      redirect: 'manual',
+    });
+    return res.status > 0;
+  } catch {
+    // ECONNREFUSED, timeout, DNS — anything counts as not-live. Try
+    // GET as a fallback because some servers (e.g. ttyd) close on HEAD
+    // and we don't want false negatives from picky upstream behavior.
+    try {
+      const res2 = await fetch(probeUrl, {
+        method: 'GET',
+        signal: AbortSignal.timeout(800),
+        redirect: 'manual',
+      });
+      return res2.status > 0;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Get the running container's port bindings from socket-proxy + map
+ * each to a clickable URL. Each service is then probed in parallel
+ * for actual reachability — the docker port mapping just tells us
+ * what's CONFIGURED; the probe confirms what's actually LISTENING.
+ *
+ * Returns [] on any docker-inspect failure (container missing, socket-
+ * proxy down) so the API still returns a valid worlds list.
+ *
+ * @param {string} worldId
+ * @returns {Promise<Array<{name: string, host_port: number, internal_port: number, url: string, live: boolean}>>}
+ */
+async function fetchWorldServices(worldId) {
+  const containerName = `olam-${worldId}-devbox`;
+  let data;
+  try {
+    if (DOCKER_HOST === 'docker-cli') {
+      // Bare-node mode: shell out to `docker inspect` instead of HTTP.
+      // Same fix pattern as fetchContainerSecret (PR #108). Without
+      // this, the services array is always empty in bare-node and the
+      // SPA can't find the ttyd host port → terminal renders blank.
+      const { spawnSync } = await import('node:child_process');
+      const result = spawnSync(
+        'docker',
+        ['inspect', containerName],
+        { encoding: 'utf-8', timeout: 2000 },
+      );
+      if (result.status !== 0) return [];
+      const arr = JSON.parse(result.stdout || '[]');
+      data = Array.isArray(arr) && arr.length > 0 ? arr[0] : null;
+      if (!data) return [];
+    } else {
+      const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+      const res = await fetch(`${apiBase}/containers/${encodeURIComponent(containerName)}/json`, {
+        signal: AbortSignal.timeout(2000),
+      });
+      if (!res.ok) return [];
+      data = await res.json();
+    }
+    const ports = data?.NetworkSettings?.Ports ?? {};
+    const draft = [];
+    for (const [internal, bindings] of Object.entries(ports)) {
+      if (!Array.isArray(bindings) || bindings.length === 0) continue;
+      const internalPort = parseInt(internal.split('/')[0], 10);
+      const hostPort = parseInt(bindings[0].HostPort, 10);
+      if (!Number.isFinite(internalPort) || !Number.isFinite(hostPort)) continue;
+      draft.push({
+        name: WELL_KNOWN_PORTS[internalPort] ?? `App (port ${internalPort})`,
+        host_port: hostPort,
+        internal_port: internalPort,
+        url: `http://127.0.0.1:${hostPort}`,
+      });
+    }
+
+    // Probe each service in parallel for actual reachability. Adds a
+    // `live: boolean` field. The UI dims chips for non-live services
+    // so operators can see what's configured-but-down vs configured-
+    // and-up at a glance.
+    const liveResults = await Promise.all(
+      draft.map((s) => probeServiceLive(s.host_port)),
+    );
+    const services = draft.map((s, i) => ({ ...s, live: liveResults[i] }));
+
+    // Stable order: well-known ports first (CP, then Rails/Vite, then terminal).
+    services.sort((a, b) => a.internal_port - b.internal_port);
+    return services;
+  } catch {
+    return [];
+  }
+}
+
+// ── Static file serving (Phase F-2-D dogfood fix) ──────────────────
+//
+// SPA dist/ is at /app/dist/ inside the container (see Dockerfile).
+// In bare-node mode, the SPA build lives in packages/control-plane/public
+// (where the workspace's `npm run build` writes it). The legacy
+// packages/host-cp/dist used to be hand-tarballed but can drift out of
+// sync with the index.html→bundle hash mapping; prefer public/ when it
+// exists so a stale dist doesn't 404 on /assets/<hash>.js.
+
+const DIST_DIR = (() => {
+  const candidates = [
+    '/app/dist',
+    path.resolve(process.cwd(), 'packages/control-plane/public'),
+    path.resolve(process.cwd(), '../control-plane/public'),
+    path.resolve(process.cwd(), 'dist'),
+    path.resolve(process.cwd(), 'packages/host-cp/dist'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c) && fs.existsSync(path.join(c, 'index.html'))) return c;
+  }
+  return '/app/dist'; // fallback; readFile will surface ENOENT
+})();
+
+const SPA_ROUTES = new Set(['/', '/worlds', '/workspaces', '/inbox']);
+const SPA_PREFIX = ['/world/', '/worlds/', '/workspaces/', '/inbox/'];
+
+// Top-level path segments that are NOT world IDs. Mirrors RESERVED_SEGMENTS
+// in lib/worldId.ts — keep in sync.
+const RESERVED_TOP_LEVEL = new Set([
+  'sandbox', 'world', 'inbox', 'worlds', 'workspaces',
+  'api', 'assets', 'health', 'favicon.ico',
+  'session', 'hooks', 'dispatch', 'lanes', 'codex', 'review',
+]);
+
+/**
+ * True when `pathname` is a bare world-ID SPA route:
+ *   /<id>
+ *   /<id>/<tab>
+ *   /<id>/sessions/<name>[/<tab>]
+ * where <id> is not a reserved segment.
+ */
+function isBareWorldSpaPath(pathname) {
+  const m = /^\/([^/?#/]+)(\/.*)?$/.exec(pathname);
+  if (!m) return false;
+  const seg = m[1];
+  if (RESERVED_TOP_LEVEL.has(seg)) return false;
+  // World IDs are lowercase kebab-case.
+  return /^[a-z][a-z0-9-]*$/.test(seg);
+}
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+/**
+ * Try to serve a static file from dist/. Returns true if served (caller
+ * must `return`); false if no file matched (caller falls through to
+ * auth + 404).
+ *
+ * SPA routing: any path matching SPA_ROUTES or SPA_PREFIX returns
+ * dist/index.html so React Router-style /world/<id> works.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} pathname
+ * @returns {Promise<boolean>}
+ */
+async function tryServeStatic(req, res, pathname) {
+  // Never serve static for /api/* — those are JSON routes.
+  if (pathname.startsWith('/api/') || pathname === '/health') return false;
+
+  // Devtools speculatively fetch /assets/<bundle>.js.map even when the
+  // bundle has no `//# sourceMappingURL` comment. We don't ship maps in
+  // production, so return 204 (no content) instead of falling through
+  // to the auth gate's 401 — that 401 surfaces as "Source Map loading
+  // errors" in the browser console and clutters debugging.
+  if (pathname.startsWith('/assets/') && pathname.endsWith('.map')) {
+    res.writeHead(204, { 'Cache-Control': 'public, max-age=31536000, immutable' });
+    res.end();
+    return true;
+  }
+
+  // SPA shell paths → dist/index.html.
+  // Inbox routing: in addition to known SPA_ROUTES/SPA_PREFIX, also treat
+  // root-level /<worldId>, /<worldId>/<tab>, /<worldId>/details, and
+  // /<worldId>/sessions/<name>[/<tab>] as SPA shells.
+  const isSpaShell =
+    SPA_ROUTES.has(pathname) ||
+    SPA_PREFIX.some((p) => pathname === p.slice(0, -1) || pathname.startsWith(p)) ||
+    isBareWorldSpaPath(pathname);
+
+  let filePath;
+  if (isSpaShell) {
+    filePath = path.join(DIST_DIR, 'index.html');
+  } else {
+    // Direct asset request (/assets/*.js, /favicon.ico, etc.)
+    // path.join normalises; we then re-check the result is still under DIST_DIR
+    // to defend against path traversal (../../etc/passwd).
+    const requested = path.join(DIST_DIR, pathname);
+    if (!requested.startsWith(DIST_DIR + path.sep) && requested !== DIST_DIR) {
+      return false;
+    }
+    filePath = requested;
+  }
+
+  if (!fs.existsSync(filePath)) {
+    // Asset 404 falls through to the auth + JSON-404 path; for SPA-shell
+    // paths a missing index.html means the build hasn't been staged.
+    return false;
+  }
+
+  const ext = path.extname(filePath);
+  const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+
+  // SPA shell (index.html) gets the bootstrap script injected so the
+  // browser sets the auth cookie BEFORE React mounts + makes API calls.
+  // Without this the SPA loads but every fetch 401s and the operator
+  // sees "Could not load worlds — HTTP 401".
+  if (isSpaShell) {
+    const html = await renderSpaShell(filePath);
+    res.writeHead(200, {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-cache, no-store, must-revalidate',
+    });
+    if (req.method === 'HEAD') {
+      res.end();
+      return true;
+    }
+    res.end(html);
+    return true;
+  }
+
+  // Direct asset serve.
+  const stat = fs.statSync(filePath);
+  res.writeHead(200, {
+    'Content-Type': contentType,
+    'Content-Length': String(stat.size),
+    'Cache-Control': pathname.startsWith('/assets/')
+      ? 'public, max-age=31536000, immutable'
+      : 'no-cache, no-store, must-revalidate',
+  });
+  if (req.method === 'HEAD') {
+    res.end();
+    return true;
+  }
+  fs.createReadStream(filePath).pipe(res);
+  return true;
+}
+
+// Memoized injected SPA shell. Read once at first request; serve from
+// memory thereafter. Cache invalidates on dist/ mtime change so a
+// rebuilt bundle is picked up without restart.
+let _spaCache = null;
+let _spaCacheMtime = 0;
+
+/**
+ * Bootstrap script injected into the SPA shell. Two responsibilities:
+ *
+ *   1. Synchronously fetch /api/bootstrap, set the cookie. Runs BEFORE
+ *      the SPA bundle so React's first render has a valid cookie.
+ *
+ *   2. Monkey-patch fetch + EventSource. When the SPA is at /world/<id>,
+ *      world-scoped API calls (`/api/world`, `/api/stream`, `/session/*`,
+ *      `/hooks/*`, etc.) get rewritten to `/api/world/<id>/...` so
+ *      host-cp's proxy routes them to the right per-world CP. Without
+ *      this, every hook in the existing SPA bundle 404s because the
+ *      bundle was built for the per-world CP context where `/api/world`
+ *      WAS the per-world endpoint.
+ *
+ * Sync XHR is deprecated but reliable for one-time bootstrap before any
+ * other script runs. Modern browsers warn but allow it.
+ *
+ * The patch reads `location.pathname` on EVERY fetch call so it tracks
+ * client-side SPA navigation — though world-card clicks today use full
+ * page reloads (window.location.assign), this is defense-in-depth for
+ * any future React Router migration.
+ */
+// Bootstrap shim injected into the SPA shell. Two responsibilities:
+//
+// 1. Set `olam_host_cp_token` cookie from /api/bootstrap (synchronous XHR
+//    so it lands before React mounts and starts firing requests).
+//
+// 2. Monkey-patch `fetch` + `EventSource` so paths the SPA was authored
+//    against the per-world CP for (the SPA bundle is shared with CF
+//    Worker mode) get rewritten under host-cp to `/api/world/<id>/...`
+//    when the page is on `/world/<id>`. host-cp's proxy strips the
+//    prefix and forwards to the per-world CP at the right port.
+//
+// Path classification:
+//   - HOST_NATIVE: paths host-cp owns. NEVER rewrite.
+//   - WORLD_PREFIXES: per-world CP paths. Rewrite when on /world/<id>.
+//
+// WORLD_PREFIXES intentionally lists every per-world top-level surface
+// the SPA touches today: /api/* (status, world, thoughts, dispatch...),
+// /session/* (resume, destroy, completion), /hooks/* (PostToolUse +
+// thoughts feed), /dispatch (POST prompt → tmux claude-main), /lanes*
+// (parallel-work coordination, CF-only feature), /codex/* (codex sidecar
+// auth + status), /review/* (codex review history). Missing entries
+// would 404 through host-cp returning the SPA shell — observed during
+// M5 dogfood: clicking Dispatch on /world/<id> hit /dispatch directly,
+// host-cp had no handler, and the SPA got HTML back instead of JSON.
+const BOOTSTRAP_SCRIPT = `<script>(function(){try{var x=new XMLHttpRequest();x.open('GET','/api/bootstrap',false);x.send();if(x.status===200){var d=JSON.parse(x.responseText);document.cookie='olam_host_cp_token='+d.token+'; path=/; samesite=strict';}}catch(e){console.error('[host-cp bootstrap]',e);}var HN=['/api/bootstrap','/api/worlds','/api/projects','/api/workspaces','/api/workspaces/match','/api/auth','/health'];var WP=['/api/','/session/','/hooks/','/dispatch','/lanes','/codex/','/review/'];function sr(p){if(typeof p!=='string')return false;if(p.startsWith('/api/world/'))return false;for(var i=0;i<HN.length;i++){var n=HN[i];if(p===n||p.startsWith(n+'?')||p.startsWith(n+'/'))return false;}for(var j=0;j<WP.length;j++){var w=WP[j];if(p===w||p===w.replace(/\\/$/,'')||p.startsWith(w)||p.startsWith(w.replace(/\\/$/,'')+'?')||p.startsWith(w.replace(/\\/$/,'')+'/'))return true;}return false;}function wid(){var p=location.pathname;var m=p.match(/^\\/(world|inbox)\\/([^/?#]+)/);if(m)return m[2];if(/^\\/(?:worlds?|workspaces?|world|sandbox|inbox|plan|design|assets|api|health|favicon)($|\\/|\\?)/.test(p))return null;var r=p.match(/^\\/([a-z][a-z0-9-]+)(?:\\/|$|\\?)/);return r?r[1]:null;}function rw(p){var w=wid();return w?'/api/world/'+w+p:p;}var of=window.fetch.bind(window);window.fetch=function(input,init){if(typeof input==='string'&&sr(input))return of(rw(input),init);if(input&&typeof input.url==='string'&&sr(input.url))return of(new Request(rw(input.url),input),init);return of(input,init);};var OE=window.EventSource;if(OE){window.EventSource=function(u,i){var s=u;if(typeof s==='string'&&sr(s))s=rw(s);return new OE(s,i);};window.EventSource.prototype=OE.prototype;window.EventSource.CONNECTING=OE.CONNECTING;window.EventSource.OPEN=OE.OPEN;window.EventSource.CLOSED=OE.CLOSED;}})();</script>`;
+
+async function renderSpaShell(filePath) {
+  const stat = fs.statSync(filePath);
+  if (_spaCache !== null && stat.mtimeMs === _spaCacheMtime) {
+    return _spaCache;
+  }
+  let html = fs.readFileSync(filePath, 'utf-8');
+  // Vite emits relative asset paths (`./assets/...`) so the SPA bundle
+  // is portable across deploy paths. But under host-cp's path-segment
+  // routing, /world/<id> would resolve `./assets/` to `/world/assets/`
+  // which 404s. Rewrite to absolute `/assets/` so all SPA shell paths
+  // (/, /worlds, /workspaces, /world/<id>) reference the same bundle.
+  html = html.replace(/(href|src)="\.\/assets\//g, '$1="/assets/');
+  // Inject right after <head> so the bootstrap runs before any other
+  // script tag on the page.
+  html = html.replace(/<head>/i, `<head>\n    ${BOOTSTRAP_SCRIPT}`);
+  _spaCache = html;
+  _spaCacheMtime = stat.mtimeMs;
+  return html;
+}
+
+// WebSocket upgrade handler for ttyd's terminal stream.
+// ttyd opens ws://<host>/ws after loading; host-cp must forward the
+// upgrade to the world's ttyd port (17681 + offset). Path:
+// /api/world/<id>/ttyd/ws.
+server.on('upgrade', (req, clientSocket, head) => {
+  try {
+    const url = new URL(req.url ?? '/', `http://localhost:${PORT}`);
+    const parsed = parseProxyPath(url.pathname);
+    if (!parsed) { clientSocket.destroy(); return; }
+    const { worldId, subPath } = parsed;
+    const port = WORLDS[worldId];
+    if (port === undefined) { clientSocket.destroy(); return; }
+    if (!subPath.startsWith('/ttyd/') && subPath !== '/ttyd') {
+      clientSocket.destroy();
+      return;
+    }
+    const portOffset = port - 19080;
+    const ttydPort = 17681 + portOffset;
+    const ttydSubPath = subPath === '/ttyd' ? '/' : subPath.slice('/ttyd'.length);
+    const ttydPath = ttydSubPath + (url.search || '');
+    /** @type {Record<string, string | string[]>} */
+    const outHeaders = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (v === undefined) continue;
+      const lower = k.toLowerCase();
+      if (lower === 'host' || lower === 'x-olam-secret') continue;
+      outHeaders[k] = v;
+    }
+    outHeaders['host'] = `${HOST_FOR_WORLD}:${ttydPort}`;
+    const upstreamReq = http.request({
+      hostname: HOST_FOR_WORLD,
+      port: ttydPort,
+      path: ttydPath,
+      method: req.method ?? 'GET',
+      headers: outHeaders,
+    });
+    upstreamReq.on('upgrade', (upstreamRes, upstreamSocket, upstreamHead) => {
+      const headerLines = [
+        `HTTP/1.1 ${upstreamRes.statusCode} ${upstreamRes.statusMessage ?? 'Switching Protocols'}`,
+      ];
+      for (const [k, v] of Object.entries(upstreamRes.headers)) {
+        if (Array.isArray(v)) {
+          for (const item of v) headerLines.push(`${k}: ${item}`);
+        } else if (v !== undefined) {
+          headerLines.push(`${k}: ${v}`);
+        }
+      }
+      headerLines.push('', '');
+      clientSocket.write(headerLines.join('\r\n'));
+      if (upstreamHead && upstreamHead.length > 0) clientSocket.write(upstreamHead);
+      upstreamSocket.pipe(clientSocket);
+      clientSocket.pipe(upstreamSocket);
+      upstreamSocket.on('error', () => clientSocket.destroy());
+      clientSocket.on('error', () => upstreamSocket.destroy());
+    });
+    upstreamReq.on('error', (err) => {
+      console.error(`[upgrade] upstream error for ttyd ${ttydPort}: ${err.message}`);
+      clientSocket.destroy();
+    });
+    if (head && head.length > 0) upstreamReq.write(head);
+    upstreamReq.end();
+  } catch (err) {
+    console.error(`[upgrade] handler error: ${err.message}`);
+    clientSocket.destroy();
+  }
+});
+
+// Probe persisted tunnels on startup; mark unreachable ones stale.
+tunnelManager.probeAllOnStartup().catch((err) => {
+  console.error(`tunnel startup probe failed: ${err.message}`);
+});
+
+server.listen(PORT, '0.0.0.0', () => {
+  console.log(`olam-host-cp B3 listening on :${PORT}`);
+  console.log(`  DOCKER_HOST=${DOCKER_HOST}`);
+  console.log(`  cache TTL=${TTL_SEC}s`);
+  console.log(`  worlds known: ${Object.keys(WORLDS).join(', ') || '(none)'}`);
+  console.log(`  mode=${HOST_CP_MODE} world-host=${HOST_FOR_WORLD}`);
+  console.log(`  (override: OLAM_HOST_CP_MODE=container|bare, OLAM_HOST_FOR_WORLD=<host>)`);
+  // Surface the auth wiring state at boot. An empty OLAM_AUTH_SECRET
+  // here is silently fatal for the credential surfaces — the operator
+  // would otherwise only see "0 credentials" in the SPA with no hint
+  // why. Logging it once at boot makes the misconfiguration obvious
+  // in docker-compose-logs without waiting for the first 401.
+  if (AUTH_SERVICE_URL && AUTH_SERVICE_SECRET.length === 0) {
+    console.warn(authSecretHint({
+      authServiceUrl: AUTH_SERVICE_URL,
+      hasSecret: false,
+    }));
+  } else if (AUTH_SERVICE_URL) {
+    console.log(`  auth-service=${AUTH_SERVICE_URL} (X-Olam-Secret configured)`);
+  }
+});
+
+// Graceful shutdown so docker compose down → SIGTERM → flush + close.
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => {
+    console.log(`received ${sig}, shutting down`);
+    stopEvents();
+    prPoller.stop();
+    worldsDbReconciler.stop();
+    clearInterval(versionPollTimer);
+    cache.clear();
+    server.close(() => process.exit(0));
+  });
+}