@pleri/olam-cli 0.1.180 → 0.1.182

package/host-cp/src/server.mjs

@@ -45,13 +45,14 @@ import {
   createNdjsonSpanSink,
   attachBetaResponseEvents,
 } from '../observability/ndjson-span-sink.mjs';
-import { betaResponseEmitter } from '@olam/auth-client';
+import { betaResponseEmitter, cfAccessHeaders } from '@olam/auth-client';
 import { attemptRecovery, findScenarioForKind } from '../recovery/index.mjs';
 import { detectHaltChunk } from './halt-detect.mjs';
 import { evaluateRedirect, applyRedirect } from './redirect.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { isPlanningPath } from './bootstrap-selective.mjs';
 import { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
+import { fetchWorldServices as fetchWorldServicesImpl } from './world-services.mjs';
 import { resolveHostCpEngine } from './engine-identity.mjs';
 import { StartupToken } from './auth.mjs';
 import { SseGate, isSsePath, wireRelease } from './sse-gate.mjs';
@@ -95,6 +96,7 @@ import {
 import { instrumentHandler, renderMetrics } from './metrics.mjs';
 import { handleDispatchFromEmail } from './lib/email-dispatch.mjs';
 import { emitTierSuggestion } from '../dispatch/auto-tier-scheduler.mjs';
+import { isServeOnly, isOrchestrationRoute, ORCHESTRATION_UNAVAILABLE } from './serve-only-config.mjs';
 
 // ── Deployment-mode detection ─────────────────────────────────────
 //
@@ -113,6 +115,17 @@ 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';
 
+// SERVE-ONLY mode (host-cp-gke-serve-only-mode Phase A). When
+// OLAM_HOST_CP_SERVE_ONLY=true, host-cp serves plan-chat-spa + host-native
+// `/api/*` only: NO docker transport connect, NO world discovery, NO
+// PlanOrchestrator docker wiring, NO pr-merge-poller docker/repo deps.
+// World-orchestration routes return a structured 503. Defaults OFF — FULL
+// (local docker/k3d) mode is byte-for-byte unchanged. See
+// ./serve-only-config.mjs for the pure gate decision (unit-tested there;
+// server.mjs can't be imported in a test because it binds a port + connects
+// docker at module load).
+const SERVE_ONLY = isServeOnly(process.env);
+
 // Container-engine identity, surfaced to olam-cli via the X-Olam-Engine
 // response header on /health. Resolution lives in engine-identity.mjs so
 // unit tests can import the pure function without triggering server startup.
@@ -232,9 +245,28 @@ async function refreshVersionSnapshot() {
   }
 }
 
-// Kick off an initial check immediately, then poll every 60s.
-refreshVersionSnapshot();
-const versionPollTimer = setInterval(refreshVersionSnapshot, VERSION_POLL_INTERVAL_MS);
+// SERVE-ONLY: the version snapshot polls the operator-repo HEAD + docker
+// image SHAs every 60s — neither exists on a managed cluster (buildVersionSnapshot
+// is fail-soft and would return all-'unknown', but the docker fetches are futile).
+// Seed a static all-'unknown' snapshot so GET /api/version/status returns 200
+// 'unknown' (not 503 pending) and skip the poll. clearInterval(null) is a no-op.
+const UNKNOWN_VERSION_SNAPSHOT = {
+  hostCp: { running: process.env.OLAM_BUILD_SHA ?? 'unknown', latest: 'unknown', upgradeAvailable: false },
+  authService: { running: 'unknown', latest: 'unknown', upgradeAvailable: false },
+  devbox: { running: 'unknown', latest: 'unknown', upgradeAvailable: false },
+  operatorHead: 'unknown',
+  checkedAt: new Date().toISOString(),
+  cliVersion: process.env.OLAM_CLI_VERSION ?? 'unknown',
+};
+
+let versionPollTimer = null;
+if (SERVE_ONLY) {
+  versionSnapshot = UNKNOWN_VERSION_SNAPSHOT;
+} else {
+  // Kick off an initial check immediately, then poll every 60s.
+  refreshVersionSnapshot();
+  versionPollTimer = setInterval(refreshVersionSnapshot, VERSION_POLL_INTERVAL_MS);
+}
 
 // ── World registry — persistent + admin-managed ───────────────────────
 //
@@ -254,6 +286,39 @@ const REGISTRY_PATH =
     ? '/data/host-cp-registry.json'
     : path.join(os.homedir(), '.olam', 'host-cp-registry.json'));
 
+/**
+ * Read the cloud-mode Anthropic proxy URL configured by the operator.
+ *
+ * Resolution order mirrors packages/adapters/src/shared/anthropic-base-url.ts
+ * and packages/auth-client/src/cloud-mode.ts:
+ *   1. OLAM_ANTHROPIC_BASE_URL env var
+ *   2. ~/.olam/anthropic-base-url file
+ *   3. ANTHROPIC_BASE_URL env var
+ *   4. '' (empty — skip injection)
+ *
+ * Called on each plan-creation request (not cached at startup) so operators
+ * can update the file without restarting host-cp.
+ *
+ * @returns {string}
+ */
+function readAnthropicBaseUrl() {
+  const fromOlamEnv = process.env['OLAM_ANTHROPIC_BASE_URL'];
+  if (fromOlamEnv && fromOlamEnv.length > 0) return fromOlamEnv.trim();
+
+  try {
+    const file = path.join(os.homedir(), '.olam', 'anthropic-base-url');
+    const content = fs.readFileSync(file, 'utf-8').trim();
+    if (content.length > 0) return content;
+  } catch {
+    // file absent — fall through
+  }
+
+  const fromShellEnv = process.env['ANTHROPIC_BASE_URL'];
+  if (fromShellEnv && fromShellEnv.length > 0) return fromShellEnv.trim();
+
+  return '';
+}
+
 /** @type {Record<string, number>} */
 let WORLDS = {};
 
@@ -414,7 +479,11 @@ const prPoller = createPrMergePoller({
   pollIntervalMs: PR_POLL_INTERVAL_MS,
   gracePeriodMs: MERGE_GRACE_MS,
 });
-prPoller.start();
+// SERVE-ONLY: pr-merge-poller polls GH for merged PRs then destroys worlds
+// via docker. No docker on a managed cluster — don't start the poll loop.
+// (The poller object is still constructed so the shutdown handler's
+// prPoller.stop() stays a no-op; start() is the docker/repo-touching part.)
+if (!SERVE_ONLY) prPoller.start();
 
 // ── Worlds-DB reconcile loop ────────────────────────────────────
 //
@@ -422,24 +491,31 @@ prPoller.start();
 // (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();
-    }
-  },
-});
+//
+// SERVE-ONLY: reconciliation reads worlds.db + probes docker for each
+// world's host port. No worlds.db / docker on a managed cluster — skip it;
+// WORLDS stays empty. `null` sentinel keeps the shutdown handler's
+// `worldsDbReconciler?.stop()` a safe no-op.
+const worldsDbReconciler = SERVE_ONLY
+  ? null
+  : 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) ─────────────────────────────────────
 //
@@ -533,7 +609,10 @@ function scheduleServersSnapshot() {
   }, SERVERS_SNAPSHOT_DEBOUNCE_MS);
 }
 
-const stopEvents = subscribeDockerEvents({
+// SERVE-ONLY: docker-events subscription opens a long-poll against the
+// docker /events stream — no docker on a managed cluster. Skip the
+// subscription; `stopEvents` is a no-op so the shutdown handler is safe.
+const stopEvents = SERVE_ONLY ? () => {} : subscribeDockerEvents({
   dockerHost: DOCKER_HOST,
   onWorldRestart: (worldId) => {
     cache.invalidate(worldId);
@@ -927,6 +1006,18 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   // 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).
+  //
+  // Phase A serve-only: world-ORCHESTRATION routes degrade to a structured
+  // 503 BEFORE static-serve. This must run pre-static so (a) a GET
+  // /v1/worlds/<id>/status can't be served the SPA HTML shell, and (b) a
+  // POST /api/worlds/<id>/tunnels / DELETE /api/worlds/<id> mutation can't
+  // execute (no docker on a managed cluster; honest degradation, not a
+  // hollow shell). Method-aware: bare GET /api/worlds (list) is NOT blocked
+  // (returns []). No-op in full mode (SERVE_ONLY false). See CP3 finding.
+  if (SERVE_ONLY && isOrchestrationRoute(url.pathname, req.method)) {
+    return jsonReply(res, 503, ORCHESTRATION_UNAVAILABLE);
+  }
+
   if (req.method === 'GET' || req.method === 'HEAD') {
     const served = await tryServeStatic(req, res, url.pathname);
     if (served) return;
@@ -1690,6 +1781,13 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     }
   }
 
+  // SERVE-ONLY: every `/api/world/<id>/...` route is world orchestration —
+  // it needs docker (proxy to a per-world CP, ttyd, secret fetch, progress
+  // probe). On a managed cluster there's no docker + WORLDS is empty, so all
+  // (serve-only world-orchestration 503 is handled earlier, pre-static, by
+  // the isOrchestrationRoute guard — it covers /api/world/, /api/worlds/<id>,
+  // and /v1/worlds/ for all methods, so no per-route guard is needed here.)
+
   // GET /api/world/<id>/progress — phase ladder progress for inbox row.
   const progressMatch = /^\/api\/world\/([^/?#]+)\/progress\/?$/.exec(url.pathname);
   if (progressMatch && req.method === 'GET') {
@@ -2374,6 +2472,23 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       // current SPA model; A11 vault-sync can refine the mapping).
       const planId = parsed.session_id ?? 'default';
       const basicAuth = Buffer.from(`operator:${showcasePw}`).toString('base64');
+
+      // Gap 3: enrich the dispatch body with the operator's anthropicBaseUrl
+      // so plan-DO can propagate it to spawned CF Sandbox child worlds.
+      // Only injected when not already set by the SPA (SPA has no auth-worker
+      // config knowledge — host-cp is the sole injection point).
+      const anthropicBaseUrl = readAnthropicBaseUrl();
+      const enriched = anthropicBaseUrl && !parsed.anthropicBaseUrl
+        ? JSON.stringify({ ...parsed, anthropicBaseUrl })
+        : body;
+
+      // Phase H h2: attach CF Access service-token headers when configured
+      // (machine-to-machine auth). Additive alongside Basic auth. CF Access
+      // headers are validated at the EDGE of origins behind a CF Access app
+      // (e.g. auth-worker.kaluga.co). They are inert on same-account service-
+      // binding hops (plan-DO) because those bypass the CF Access edge; a CF
+      // Access app in front of plan-DO would still not receive service-binding
+      // traffic. See docs/runbooks/cf-access-service-token.md.
       const upstream = await fetch(
         `${cloudUrl.replace(/\/+$/, '')}/v1/dispatch?plan_id=${encodeURIComponent(planId)}`,
         {
@@ -2381,8 +2496,9 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
           headers: {
             'Authorization': `Basic ${basicAuth}`,
             'content-type': 'application/json',
+            ...cfAccessHeaders(),
           },
-          body,
+          body: enriched,
         },
       );
       const upstreamBody = await upstream.text();
@@ -2398,6 +2514,72 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     }
   }
 
+  // /api/plans/create — Gap 3 plan-creation handshake (Phase H h2 v1 dogfood).
+  //
+  // Accepts a plan-creation request from the SPA, enriches it with the
+  // operator's anthropicBaseUrl from ~/.olam/anthropic-base-url, and forwards
+  // it to plan-DO's /v1/plans/create so plan-DO stores the bearer URL for
+  // subsequent dispatches + spawned CF Sandbox child worlds.
+  //
+  // Config:
+  //   OLAM_CLOUD_URL        — plan-DO deployed URL (e.g. https://plan-agent-do.workers.dev)
+  //   OLAM_SHOWCASE_PASSWORD — showcase Basic auth password
+  //
+  // Returns 503 when cloud is not configured — operators using local Docker
+  // mode skip this; the SPA treats 503 as a non-fatal degraded state.
+  if (url.pathname === '/api/plans/create' && req.method === 'POST') {
+    const cloudUrl = process.env.OLAM_CLOUD_URL;
+    const showcasePw = process.env.OLAM_SHOWCASE_PASSWORD;
+    if (!cloudUrl || !showcasePw) {
+      return jsonReply(res, 503, {
+        error: 'cloud_not_configured',
+        message: 'OLAM_CLOUD_URL + OLAM_SHOWCASE_PASSWORD not set; plan-DO bearer propagation skipped.',
+      });
+    }
+    try {
+      const reqChunks = [];
+      for await (const c of req) reqChunks.push(c);
+      let parsed = {};
+      try { parsed = JSON.parse(Buffer.concat(reqChunks).toString('utf8') || '{}'); } catch {
+        // Non-fatal: body is optional — caller may POST with no body to trigger
+        // bearer registration without additional plan metadata.
+      }
+
+      // Enrich with anthropicBaseUrl from the host config.
+      const anthropicBaseUrl = readAnthropicBaseUrl();
+      const planId = parsed.planId ?? parsed.session_id ?? `plan-${Date.now()}`;
+      const requestBody = { ...parsed, planId, ...(anthropicBaseUrl ? { anthropicBaseUrl } : {}) };
+
+      const basicAuth = Buffer.from(`operator:${showcasePw}`).toString('base64');
+      // Phase H h2: attach CF Access service-token headers when configured.
+      // See the /api/cloud-dispatch handler above + the runbook for why these
+      // are additive (kept alongside Basic) and edge-validated only on origins
+      // behind a CF Access app — inert on same-account service-binding hops.
+      const upstream = await fetch(
+        `${cloudUrl.replace(/\/+$/, '')}/v1/plans/create?plan_id=${encodeURIComponent(planId)}`,
+        {
+          method: 'POST',
+          headers: {
+            'Authorization': `Basic ${basicAuth}`,
+            'content-type': 'application/json',
+            ...cfAccessHeaders(),
+          },
+          body: JSON.stringify(requestBody),
+        },
+      );
+      const upstreamBody = await upstream.text();
+      res.statusCode = upstream.status;
+      res.setHeader('content-type', upstream.headers.get('content-type') ?? 'application/json');
+      res.setHeader('cache-control', 'no-store');
+      return res.end(upstreamBody);
+    } catch (err) {
+      return jsonReply(res, 502, {
+        error: 'plans_create_proxy_failed',
+        message: err.message,
+      });
+    }
+  }
+
   // GET /api/worlds/:id/processes
   // GET /api/worlds/:id/processes/stream — SSE fanout (5s cadence, per-world)
   // Handler: routes/process-port.mjs → handleListProcesses
@@ -2795,148 +2977,54 @@ function handleAuthEvents(req, res) {
 //
 // 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)',
-  7682: 'Terminal Shell (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 [];
-  }
+// well-known internal ports. The probe + enrichment logic lives in
+// ./world-services.mjs (extracted for isolated unit testing); this thin
+// wrapper binds the host-specific HOST_FOR_WORLD / DOCKER_HOST module
+// constants so callers keep the single-arg `fetchWorldServices(worldId)`
+// signature (used at the createLocalWorldsSource wiring above).
+function fetchWorldServices(worldId) {
+  return fetchWorldServicesImpl(worldId, {
+    hostForWorld: HOST_FOR_WORLD,
+    dockerHost: DOCKER_HOST,
+  });
 }
 
 // ── 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.
-
+// SPA dist/ is at /app/dist/ inside the container (see Dockerfile; the
+// build stages plan-chat-spa's dist/client there as of Phase E5).
+// In bare-node mode, the SPA build lives in
+// packages/plan-chat-spa/dist/client (where `vite build` writes it as of
+// the Phase E5 ATOMIC SERVING CUTOVER — plan-chat-spa supersedes
+// control-plane as host-cp's sole served SPA). The legacy
+// control-plane/public candidates are retained below as a fallback so a
+// host-cp running against a not-yet-rebuilt worktree still finds *a* SPA;
+// they are last-resort, ordered after the plan-chat-spa + host-cp/dist
+// candidates. 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 the freshly-built dist/client when it exists.
+
+// Phase E5 (ATOMIC SERVING CUTOVER) — FAIL-CLOSED candidate list.
+// Every candidate now resolves to a plan-chat-spa build. The retired
+// control-plane/public candidates were REMOVED (per /codex:rescue on the
+// cutover): keeping them meant a missing/stale plan-chat-spa build would
+// silently fall back to serving the OLD control-plane shell and look
+// superficially healthy. Now an absent plan-chat-spa dist serves nothing
+// (ENOENT → SPA-shell 404) — a loud failure, not a silent wrong-SPA serve.
+//   - /app/dist                       — container (Dockerfile stages plan-chat-spa here)
+//   - packages/plan-chat-spa/dist/client — bare-node local (vite build output)
+//   - packages/host-cp/dist           — stage-host-cp-spa.sh output (also plan-chat-spa)
 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/plan-chat-spa/dist/client'),
+    path.resolve(process.cwd(), '../plan-chat-spa/dist/client'),
     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
+  return '/app/dist'; // fallback; readFile will surface ENOENT (fail-closed)
 })();
 
 const SPA_ROUTES = new Set(['/', '/worlds', '/workspaces', '/inbox', '/repos', '/runbooks', '/plan']);
@@ -3159,6 +3247,19 @@ const _spaCacheByKey = new Map();
 //       and the token-comparison check skips reload when the cookie
 //       already matches (so non-rotation 401s — e.g. genuine auth
 //       failures — don't cause a refresh loop).
+// Phase E5 (ATOMIC SERVING CUTOVER): BOOTSTRAP_SCRIPT is NO LONGER
+// injected into the served SPA shell. host-cp now serves plan-chat-spa
+// exclusively, whose bundle re-homes the cookie-bootstrap +
+// world-fetch-rewrite + 401-recover shim (packages/plan-chat-spa/src/lib/
+// worldFetch.ts, installed at the top of src/main.tsx — Phase C). The
+// const is RETAINED, defined-but-unreferenced-in-render, because
+// scripts/audit-worker-bootstrap-parity.mjs extracts the `HN` (and `WP`)
+// arrays out of this literal via extractHN()/extractWP() and machine-gates
+// them byte-equal against worldFetch.ts's HOST_NATIVE_PREFIXES /
+// WORLD_PREFIXES. Deleting this const would make extractHN return null →
+// audit FAIL. Keep it as the canonical HN/WP-array parity source until
+// that audit is repointed at worldFetch.ts directly (follow-up).
+// eslint-disable-next-line no-unused-vars -- retained as HN/WP parity-audit source
 const BOOTSTRAP_SCRIPT = `<script>(function(){function ck(){var m=document.cookie.match(/olam_host_cp_token=([^;]+)/);return m?m[1]:'';}function sw(t){document.cookie='olam_host_cp_token='+t+'; path=/; samesite=strict';}try{var x=new XMLHttpRequest();x.open('GET','/api/bootstrap',false);x.send();if(x.status===200){var d=JSON.parse(x.responseText);sw(d.token);}}catch(e){console.error('[host-cp bootstrap]',e);}var reloading=false;function recover(){if(reloading)return;try{var x=new XMLHttpRequest();x.open('GET','/api/bootstrap',false);x.send();if(x.status===200){var d=JSON.parse(x.responseText);if(d.token&&ck()!==d.token){reloading=true;sw(d.token);console.warn('[host-cp auth recover] token rotated; reloading');location.reload();}}}catch(e){console.error('[host-cp auth recover]',e);}}var HN=['/api/bootstrap','/api/worlds','/api/projects','/api/workspaces','/api/workspaces/match','/api/repos','/api/runbooks','/api/auth','/api/host-stream','/api/plan-chat','/api/plan/agent-runtime','/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|session)\\/([^/?#]+)/);if(m)return m[2];if(/^\\/(?:worlds?|workspaces?|world|sandbox|session|inbox|plan|design|repos|runbooks|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){var pr;if(typeof input==='string'&&sr(input))pr=of(rw(input),init);else if(input&&typeof input.url==='string'&&sr(input.url))pr=of(new Request(rw(input.url),input),init);else pr=of(input,init);return pr.then(function(res){if(res&&res.status===401)recover();return res;});};var OE=window.EventSource;if(OE){window.EventSource=function(u,i){var s=u;if(typeof s==='string'&&sr(s))s=rw(s);var es=new OE(s,i);es.addEventListener('error',function(){if(es.readyState===OE.CLOSED)recover();});return es;};window.EventSource.prototype=OE.prototype;window.EventSource.CONNECTING=OE.CONNECTING;window.EventSource.OPEN=OE.OPEN;window.EventSource.CLOSED=OE.CLOSED;}})();</script>`;
 
 /**
@@ -3181,35 +3282,40 @@ function buildPlanChatBearerInjection() {
   }
 }
 
-// Phase D1 — Selective BOOTSTRAP_SCRIPT no-op.
+// Phase E5 (ATOMIC SERVING CUTOVER) — BOOTSTRAP_SCRIPT no longer injected.
 //
-// Planning paths use plan-chat-spa's own readBearer() resolver
-// (lib/bearer.ts) which reads window.__OLAM_PLAN_CHAT_BEARER__ injected
-// inline OR falls back to the URL hash channel. They DO NOT need the
-// host-cp bootstrap's cookie+fetch-rewrite shim. Non-planning surfaces
-// (/workspaces, /repos, /runbooks, /design, /inbox, /world/:id/editor,
-// /world/:id/events) still rely on bootstrap-injected cookie + the
-// monkey-patched fetch/EventSource that rewrites world-scoped paths
-// to /api/world/<id>/... — keep injecting for them until Phase E
-// migrates each to a bootstrap-free pattern.
+// host-cp now serves plan-chat-spa exclusively. plan-chat-spa's own
+// bundle re-homes BOTH auth paths:
+//   - readBearer() (lib/bearer.ts) reads window.__OLAM_PLAN_CHAT_BEARER__
+//     injected inline below (the `bearerInjection`) OR falls back to the
+//     URL-hash channel.
+//   - the cookie-bootstrap + world-fetch-rewrite + 401-recover shim
+//     (lib/worldFetch.ts, installed at the top of src/main.tsx) handles
+//     the cookie + path-rewrite duties that host-cp's BOOTSTRAP_SCRIPT
+//     used to perform.
+// So the served shell injects ONLY the bearer; the bootstrap shim is
+// dropped. isPlanningPath() (bootstrap-selective.mjs) is now a wildcard
+// (true for every string path) — this function relies on that to never
+// inject BOOTSTRAP_SCRIPT.
 //
-// Reversal: edit BOOTSTRAP_NOOP_PLANNING_PATHS in bootstrap-selective.mjs
-// to [] to restore universal injection. Single-line change.
+// Reversal: re-narrow isPlanningPath() in bootstrap-selective.mjs (see
+// the revert-seam note there) and restore the `bootstrapPart` branch
+// below if a surface ever needs host-cp's bootstrap again.
 //
-// Per K1 SCP-3 + phase-d-tasks D1 acceptance.
+// Per K1 SCP-3 + phase-d-tasks D1 + phase-e-tasks E2 acceptance.
 
 async function renderSpaShell(filePath, pathname) {
   const stat = fs.statSync(filePath);
   const bearerInjection = buildPlanChatBearerInjection();
-  // Path-selective: planning paths skip the bootstrap shim entirely
-  // (plan-chat-spa's readBearer handles auth); non-planning paths
-  // retain it (Phase E will migrate them).
+  // Phase E5: BOOTSTRAP_SCRIPT is never injected — plan-chat-spa's own
+  // worldFetch.ts shim owns the cookie-bootstrap + path-rewrite contract.
+  // We still assert the wildcard invariant so a future re-narrowing of
+  // isPlanningPath() surfaces here loudly rather than silently shipping a
+  // mixed shell.
   const skipBootstrap = isPlanningPath(pathname);
-  const bootstrapPart = skipBootstrap ? '' : BOOTSTRAP_SCRIPT;
-  // Cache key includes bearer length AND the bootstrap-presence bit so
-  // /plan and /workspaces don't share a cached shell.
-  const cacheKey =
-    stat.mtimeMs + ':' + bearerInjection.length + ':' + (skipBootstrap ? '0' : '1');
+  // Cache key includes bearer length (the only per-render-varying input
+  // now that bootstrap injection is constant-empty).
+  const cacheKey = stat.mtimeMs + ':' + bearerInjection.length;
   const cached = _spaCacheByKey.get(cacheKey);
   if (cached !== undefined) return cached;
   let html = fs.readFileSync(filePath, 'utf-8');
@@ -3219,15 +3325,11 @@ async function renderSpaShell(filePath, pathname) {
   // 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. Bearer injection runs after the host-cp
-  // bootstrap so window.__OLAM_PLAN_CHAT_BEARER__ is set before the
-  // SPA bundle reads it. On planning paths the bootstrap is empty —
-  // bearer injection still runs (plan-chat-spa reads it directly).
-  html = html.replace(
-    /<head>/i,
-    `<head>\n    ${bootstrapPart}\n    ${bearerInjection}`,
-  );
+  // Inject the bearer right after <head> so window.__OLAM_PLAN_CHAT_BEARER__
+  // is set before the SPA bundle reads it. No bootstrap shim — see the
+  // block comment above (Phase E5 cutover).
+  void skipBootstrap; // wildcard invariant: always true; documents intent
+  html = html.replace(/<head>/i, `<head>\n    ${bearerInjection}`);
   _spaCacheByKey.set(cacheKey, html);
   return html;
 }
@@ -3303,28 +3405,41 @@ server.on('upgrade', (req, clientSocket, head) => {
   }
 });
 
-// Probe persisted tunnels on startup; mark unreachable ones stale.
-tunnelManager.probeAllOnStartup().catch((err) => {
-  console.error(`tunnel startup probe failed: ${err.message}`);
-});
+// SERVE-ONLY: everything below this point through reconcileWorldsWithDocker
+// is world-orchestration observability — tunnel probes, the worlds.db /
+// docker snapshot loops, the per-world activity tracker, and the boot-time
+// reconcile. None of it has a docker daemon / worlds.db / world tunnels on a
+// managed cluster. Skip it all in serve-only; the snapshot timers + tracker
+// stay unstarted so the shutdown handler's `?.`-guarded stops are safe.
+if (!SERVE_ONLY) {
+  // Probe persisted tunnels on startup; mark unreachable ones stale.
+  tunnelManager.probeAllOnStartup().catch((err) => {
+    console.error(`tunnel startup probe failed: ${err.message}`);
+  });
 
-// Start the 1-Hz worlds.db hash-diff loop after the server boots so
-// the initial broadcast happens once the route is reachable.
-startWorldsSnapshotLoop();
-// Phase B-bonus: start tunnel + listening snapshot loops. Both
-// hash-debounce so idle windows produce zero broadcasts.
-startTunnelsSnapshotLoop();
-startListeningSnapshotLoop();
+  // Start the 1-Hz worlds.db hash-diff loop after the server boots so
+  // the initial broadcast happens once the route is reachable.
+  startWorldsSnapshotLoop();
+  // Phase B-bonus: start tunnel + listening snapshot loops. Both
+  // hash-debounce so idle windows produce zero broadcasts.
+  startTunnelsSnapshotLoop();
+  startListeningSnapshotLoop();
+}
 
 // Closes #965: live thought_count + total_cost_usd updates from each
 // active world's Claude session JSONL. Periodic (60s default) so Rico's
 // scheduling loop can read fresh values from the `worlds` table and
 // SPAs can subscribe to the `world.activity.tick` event. Fail-soft per
 // world: missing/malformed JSONL never crashes the loop.
-const worldActivityTracker = startWorldActivityTracker({
-  dbPath: WORLDS_DB_PATH,
-  broadcaster: hostStream,
-});
+//
+// SERVE-ONLY: reads worlds.db (absent on a managed cluster). `null` sentinel
+// keeps the shutdown handler's `worldActivityTracker?.stop()` a no-op.
+const worldActivityTracker = SERVE_ONLY
+  ? null
+  : startWorldActivityTracker({
+      dbPath: WORLDS_DB_PATH,
+      broadcaster: hostStream,
+    });
 
 // ── Phase 1a / B1 (PR3): engine-select + await-before-listen ─────
 //
@@ -3343,14 +3458,20 @@ const worldActivityTracker = startWorldActivityTracker({
 // resolve through the same async branch for symmetry — the call-site
 // migration to engine.* methods is a downstream task; today the engine
 // instance is held for /health diagnostic + future use.
-const hostCpEngine = await (async () => {
-  if (HOST_CP_ENGINE === 'kubernetes') {
-    const { createKubernetesEngine } = await import('./engines/kubernetes.mjs');
-    return createKubernetesEngine({ env: process.env });
-  }
-  const { createDockerEngine } = await import('./engines/docker.mjs');
-  return createDockerEngine({ dockerHost: DOCKER_HOST });
-})();
+// SERVE-ONLY: don't resolve a real container engine — there's no docker
+// daemon to talk to and the KubernetesEngine factory runs a context-
+// allowlist guard that has no managed-cluster meaning here. Use a minimal
+// inert engine descriptor so /health still reports an engine name.
+const hostCpEngine = SERVE_ONLY
+  ? { engineName: 'serve-only', context: undefined }
+  : await (async () => {
+      if (HOST_CP_ENGINE === 'kubernetes') {
+        const { createKubernetesEngine } = await import('./engines/kubernetes.mjs');
+        return createKubernetesEngine({ env: process.env });
+      }
+      const { createDockerEngine } = await import('./engines/docker.mjs');
+      return createDockerEngine({ dockerHost: DOCKER_HOST });
+    })();
 
 // ── Boot-time worlds.db ↔ docker reconciler (issue #963) ─────────────
 //
@@ -3359,17 +3480,24 @@ const hostCpEngine = await (async () => {
 // world is running/active but the container is gone, mark it 'orphaned'.
 // Fail-soft: docker unreachable or DB unavailable → log + continue boot.
 // Runs BEFORE server.listen() so the first request sees reconciled state.
-try {
-  await reconcileWorldsWithDocker({
-    dbPath: WORLDS_DB_PATH,
-    listContainerNames: () => defaultListContainerNames(DOCKER_API_BASE, console.log),
-  });
-} catch (err) {
-  console.error(`[boot-reconciler] unexpected error (continuing boot): ${err.message}`);
+//
+// SERVE-ONLY: no worlds.db / docker container list on a managed cluster.
+if (!SERVE_ONLY) {
+  try {
+    await reconcileWorldsWithDocker({
+      dbPath: WORLDS_DB_PATH,
+      listContainerNames: () => defaultListContainerNames(DOCKER_API_BASE, console.log),
+    });
+  } catch (err) {
+    console.error(`[boot-reconciler] unexpected error (continuing boot): ${err.message}`);
+  }
 }
 
 server.listen(PORT, '0.0.0.0', () => {
   console.log(`olam-host-cp B3 listening on :${PORT}`);
+  if (SERVE_ONLY) {
+    console.log('  [serve-only] OLAM_HOST_CP_SERVE_ONLY=true — SPA + host-native /api/* only; world orchestration disabled (/api/world/* → 503 orchestration_unavailable).');
+  }
   console.log(`  DOCKER_HOST=${DOCKER_HOST}`);
   console.log(`  cache TTL=${TTL_SEC}s`);
   console.log(`  worlds known: ${Object.keys(WORLDS).join(', ') || '(none)'}`);
@@ -3404,11 +3532,12 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     console.log(`received ${sig}, shutting down`);
     stopEvents();
     prPoller.stop();
-    worldsDbReconciler.stop();
+    // worldsDbReconciler + worldActivityTracker are null in SERVE-ONLY mode.
+    worldsDbReconciler?.stop();
     stopWorldsSnapshotLoop();
     stopTunnelsSnapshotLoop();
     stopListeningSnapshotLoop();
-    worldActivityTracker.stop();
+    worldActivityTracker?.stop();
     if (serversSnapshotTimer) { clearTimeout(serversSnapshotTimer); serversSnapshotTimer = null; }
     hostStream.close();
     if (ndjsonSpanSink) ndjsonSpanSink.close().catch(() => {});