@pleri/olam-cli 0.1.143 → 0.1.145

package/host-cp/src/agent-runtime-trigger.mjs

@@ -0,0 +1,262 @@
+// agent-runtime-trigger — Phase B B7 (minimum-demo cut) host-side launch hook.
+//
+// When the SPA opens the plan-tab for a (worldId, sessionId), it POSTs
+// here; host-cp idempotently spawns the agent-stream-launch supervisor
+// inside the world's devbox container via `docker exec`. The supervisor
+// (PID 1 within the spawned exec session) then fork-spawns driver +
+// codex runners that long-poll host-cp's /v1/shape.
+//
+// Demo-cut simplifications (per minimum-demo decision; full B7 in follow-up):
+//   - In-memory idempotency map keyed by `(worldId, sessionId)`. Restart of
+//     host-cp loses state; second call after restart re-issues docker exec,
+//     which the supervisor's idempotency check (B6-full's flock + PID-file)
+//     would catch. B6-minimum has no such check → restart of host-cp +
+//     re-trigger may spawn two supervisors. Acceptable for single-operator
+//     local demo; full B7 + B6-full close this.
+//   - Uses shared-secret bearer (from `~/.olam/plan-chat-secret` per the
+//     existing plan-chat-service contract). JWT scope-claim migration is B9.
+//   - No conversation_id ↔ (worldId, sessionId) join-table (A1.4
+//     §migration-schema open question). For demo, the supervisor is
+//     keyed by (worldId, sessionId) directly; codex's APPROVE chunks
+//     write under (worldId, sessionId) — `conversation_id` plumbing
+//     deferred until lookouts (B3) need it.
+//   - No host-cp restart cleanup of dead supervisor entries (the in-memory
+//     map only tracks live spawns; container crash + re-trigger DOES
+//     re-spawn).
+//
+// Source: docs/design/olam-plan-chat-agent-runtime.md `lifecycle` +
+// `bake-in-seam` sections, minimum-demo cut.
+
+import { spawnSync, spawn } from 'node:child_process';
+
+const SPAWN_TIMEOUT_MS = 10_000;
+
+// Default container-side path for the supervisor binary. The devbox image
+// COPYs `packages/intelligence/dist/agent-stream/` to this location during
+// build (devbox Dockerfile update lands alongside this PR or in a follow-up).
+// Compiled supervisor lives at /opt/olam/agent-stream/dist/agent-stream-launch.js
+// per the devbox runtime Dockerfile build-in-image step (tsc writes dist/).
+const DEFAULT_SUPERVISOR_PATH = '/opt/olam/agent-stream/dist/agent-stream-launch.js';
+
+/**
+ * @typedef {object} TriggerArgs
+ * @property {string} worldId
+ * @property {string} sessionId
+ * @property {string} hostCpUrl — URL the container reaches host-cp at
+ *   (e.g. `http://host.docker.internal:3112`)
+ * @property {string} bearer — shared-secret token (read from
+ *   `~/.olam/plan-chat-secret` server-side; never passed in from SPA)
+ * @property {string} [dockerHost='docker-cli'] — `'docker-cli'` for bare-node
+ *   mode; `tcp://...` for container mode (docker-socket-proxy)
+ * @property {string} [supervisorPath] — override for tests
+ * @property {(cmd: string, args: string[], opts?: object) => any} [spawnSyncImpl]
+ *   — injectable for tests; defaults to node:child_process spawnSync
+ * @property {(cmd: string, args: string[], opts?: object) => any} [spawnImpl]
+ *   — injectable for tests; defaults to node:child_process spawn (detached)
+ */
+
+/**
+ * Internal state: which `(worldId, sessionId)` pairs we've already
+ * spawned. Survives only within a single host-cp process instance.
+ *
+ * @type {Map<string, {spawnedAt: number, pid?: number}>}
+ */
+const liveSpawns = new Map();
+
+/** @param {string} worldId @param {string} sessionId */
+function key(worldId, sessionId) {
+  return `${worldId}::${sessionId}`;
+}
+
+/**
+ * Idempotently spawn the agent-stream supervisor inside the world's container.
+ *
+ * Returns `{status: 'spawned' | 'already-running', container, pid?}`.
+ * Throws on docker-CLI failure or container-not-running.
+ *
+ * @param {TriggerArgs} args
+ */
+export async function triggerAgentRuntime(args) {
+  const {
+    worldId,
+    sessionId,
+    hostCpUrl,
+    bearer,
+    dockerHost = 'docker-cli',
+    supervisorPath = DEFAULT_SUPERVISOR_PATH,
+    spawnSyncImpl = spawnSync,
+    spawnImpl = spawn,
+  } = args;
+
+  if (!worldId || !sessionId || !hostCpUrl || !bearer) {
+    throw new Error(
+      'triggerAgentRuntime: worldId, sessionId, hostCpUrl, bearer all required',
+    );
+  }
+
+  const k = key(worldId, sessionId);
+  if (liveSpawns.has(k)) {
+    const entry = liveSpawns.get(k);
+    return {
+      status: 'already-running',
+      container: `olam-${worldId}-devbox`,
+      spawnedAt: entry.spawnedAt,
+      pid: entry.pid,
+    };
+  }
+
+  const containerName = `olam-${worldId}-devbox`;
+
+  // Bare-node mode: shell out to docker exec --detach (or background
+  // via & in a wrapper command). Detached so the SPA's HTTP request
+  // returns promptly; the supervisor lives until SIGTERM.
+  if (dockerHost === 'docker-cli') {
+    // First, verify the container exists and is running. `docker inspect`
+    // returns exit 1 if the container is not found; exit 0 with stdout
+    // containing the state if found.
+    const inspect = spawnSyncImpl(
+      'docker',
+      ['inspect', '--format', '{{.State.Running}}', containerName],
+      { encoding: 'utf-8', timeout: SPAWN_TIMEOUT_MS },
+    );
+    if (inspect.error) {
+      throw new Error(
+        `docker inspect ${containerName} failed: ${inspect.error.message}`,
+      );
+    }
+    if (inspect.status !== 0) {
+      throw new Error(
+        `docker inspect ${containerName} exit ${inspect.status}: ${(inspect.stderr || '').trim()}`,
+      );
+    }
+    if ((inspect.stdout || '').trim() !== 'true') {
+      throw new Error(
+        `container ${containerName} is not running (state: ${(inspect.stdout || '').trim()})`,
+      );
+    }
+
+    // Use docker exec --detach to spawn the supervisor in the background.
+    // -e flags inject the runtime env; the supervisor binary path is the
+    // last positional argument.
+    const env = {
+      HOST_CP_URL: hostCpUrl,
+      HOST_CP_BEARER: bearer,
+      WORLD_ID: worldId,
+      SESSION_ID: sessionId,
+    };
+    const execArgs = ['exec', '--detach'];
+    for (const [k_, v] of Object.entries(env)) {
+      execArgs.push('-e', `${k_}=${v}`);
+    }
+    execArgs.push(containerName, 'node', supervisorPath);
+
+    const detached = spawnImpl('docker', execArgs, {
+      stdio: 'ignore',
+      detached: true,
+    });
+    detached.unref?.();
+
+    liveSpawns.set(k, { spawnedAt: Date.now(), pid: detached.pid });
+
+    return {
+      status: 'spawned',
+      container: containerName,
+      pid: detached.pid,
+    };
+  }
+
+  // Container mode (docker-socket-proxy on tcp://<host>:<port>).
+  // Two-step Docker API exec: POST /containers/<name>/exec creates an
+  // exec instance, then POST /exec/<id>/start with Detach=true runs it
+  // in the background. Matches the pattern in container-secret-fetcher.mjs.
+  if (dockerHost.startsWith('tcp://')) {
+    const apiBase = dockerHost.replace(/^tcp:\/\//, 'http://');
+
+    // Step 0: verify the container is running.
+    const inspectRes = await fetch(
+      `${apiBase}/containers/${encodeURIComponent(containerName)}/json`,
+    );
+    if (!inspectRes.ok) {
+      throw new Error(
+        `socket-proxy GET /containers/${containerName}/json: ${inspectRes.status} ${inspectRes.statusText}`,
+      );
+    }
+    const inspect = await inspectRes.json();
+    if (!inspect?.State?.Running) {
+      throw new Error(
+        `container ${containerName} is not running (state: ${JSON.stringify(inspect?.State)})`,
+      );
+    }
+
+    // Step 1: create exec instance with env injection.
+    const createRes = await fetch(
+      `${apiBase}/containers/${encodeURIComponent(containerName)}/exec`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          Cmd: ['node', supervisorPath],
+          Env: [
+            `HOST_CP_URL=${hostCpUrl}`,
+            `HOST_CP_BEARER=${bearer}`,
+            `WORLD_ID=${worldId}`,
+            `SESSION_ID=${sessionId}`,
+          ],
+          AttachStdout: false,
+          AttachStderr: false,
+          Tty: false,
+        }),
+      },
+    );
+    if (!createRes.ok) {
+      const errBody = await createRes.text().catch(() => '<no body>');
+      throw new Error(
+        `socket-proxy POST /containers/${containerName}/exec: ${createRes.status} — ${errBody}`,
+      );
+    }
+    const { Id: execId } = await createRes.json();
+
+    // Step 2: start exec in detached mode.
+    const startRes = await fetch(`${apiBase}/exec/${execId}/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ Detach: true, Tty: false }),
+    });
+    if (!startRes.ok && startRes.status !== 200) {
+      const errBody = await startRes.text().catch(() => '<no body>');
+      throw new Error(
+        `socket-proxy POST /exec/${execId}/start: ${startRes.status} — ${errBody}`,
+      );
+    }
+
+    liveSpawns.set(k, { spawnedAt: Date.now(), execId });
+
+    return {
+      status: 'spawned',
+      container: containerName,
+      execId,
+    };
+  }
+
+  throw new Error(
+    `triggerAgentRuntime: unsupported dockerHost mode '${dockerHost}'`,
+  );
+}
+
+/**
+ * Test-only: clear the in-memory live-spawns map.
+ * Production code should NEVER call this — it would let a duplicate
+ * supervisor spawn.
+ */
+export function _clearLiveSpawnsForTests() {
+  liveSpawns.clear();
+}
+
+/**
+ * Inspect-only: read the current live-spawns map (for observability).
+ *
+ * @returns {ReadonlyMap<string, {spawnedAt: number, pid?: number}>}
+ */
+export function getLiveSpawns() {
+  return new Map(liveSpawns);
+}

package/host-cp/src/engine-identity.mjs

@@ -0,0 +1,32 @@
+// Container-engine identity for host-cp.
+//
+// Phase 1a / A1: defaults to "docker"; switches to "kubernetes" when running
+// inside a K8s pod (autodetected via KUBERNETES_SERVICE_HOST). Operators can
+// override either way via OLAM_HOST_CP_ENGINE.
+//
+// This module exists separately from server.mjs to keep the engine-resolution
+// logic pure (no I/O, no mkdir, no global side-effects) so unit tests can
+// import it without triggering server startup. server.mjs imports
+// resolveHostCpEngine from here and computes its module-level HOST_CP_ENGINE
+// constant.
+//
+// KubernetesEngine adapter (Phase B / PR3) consumes the same env variables
+// when constructing the engine; the context-allowlist guard (T6 / Decision 10)
+// lives inside that adapter, not here. This module is "what name to surface
+// in the X-Olam-Engine response header" — nothing more.
+
+/**
+ * Resolve the active container-engine identity for host-cp.
+ *
+ * Precedence (matches HOST_CP_MODE convention at server.mjs:85-87):
+ *   1. Explicit env override: OLAM_HOST_CP_ENGINE=docker|kubernetes
+ *   2. Autodetect: KUBERNETES_SERVICE_HOST set → "kubernetes"
+ *   3. Default: "docker"
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env] - environment to inspect.
+ * @returns {string} - engine identity surfaced via X-Olam-Engine header.
+ */
+export function resolveHostCpEngine(env = process.env) {
+  return env.OLAM_HOST_CP_ENGINE
+    ?? (env.KUBERNETES_SERVICE_HOST ? 'kubernetes' : 'docker');
+}

package/host-cp/src/server.mjs

@@ -37,6 +37,7 @@ import { subscribeDockerEvents } from './docker-events.mjs';
 import { createHostStream, newStreamId } from './host-stream.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
+import { resolveHostCpEngine } from './engine-identity.mjs';
 import { StartupToken } from './auth.mjs';
 import { SseGate, isSsePath, wireRelease } from './sse-gate.mjs';
 import {
@@ -56,6 +57,8 @@ 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 { triggerAgentRuntime } from './agent-runtime-trigger.mjs';
+import { readSecret as readPlanChatSecret, SECRET_PATH as PLAN_CHAT_SECRET_PATH } from './plan-chat-secret.mjs';
 import { createPrMergePoller } from './pr-merge-poller.mjs';
 import { parse as parseYaml } from 'yaml';
 import { startWorldsDbReconciler } from './worlds-db-source.mjs';
@@ -86,6 +89,11 @@ 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';
 
+// 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.
+const HOST_CP_ENGINE = resolveHostCpEngine();
+
 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).
@@ -662,7 +670,13 @@ const server = http.createServer(async (req, res) => {
   // /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.
+  //
+  // X-Olam-Engine header surfaces the active container-engine adapter to
+  // olam-cli (consumed by `olam doctor`, `olam logs`, `olam status`). Lives
+  // in the header (NOT the body) so the response body shape stays unchanged
+  // and probes don't accidentally leak engine identity to body parsers.
   if (url.pathname === '/health') {
+    res.setHeader('X-Olam-Engine', HOST_CP_ENGINE);
     return jsonReply(res, 200, {
       status: 'ok',
       phase: 'B4',
@@ -723,6 +737,13 @@ const server = http.createServer(async (req, res) => {
     if (served) return;
   }
 
+  // /api/plan-chat/* bypasses the host-cp session-token gate because the
+  // plan-chat-service it proxies to has its own Bearer auth (the
+  // plan-chat-secret). The proxy handler is registered later in the file;
+  // dispatch by continuing past the gate.
+  if (url.pathname.startsWith('/api/plan-chat/') || url.pathname === '/api/plan-chat') {
+    // fall through to the proxy route below
+  } else
   // ALL OTHER ROUTES require auth. Reject with 401 if neither cookie
   // nor Bearer header matches.
   if (!auth.isAuthorized(req)) {
@@ -1861,6 +1882,123 @@ const server = http.createServer(async (req, res) => {
     return jsonReply(res, 200, { signals });
   }
 
+  // POST /api/plan/agent-runtime/trigger — Phase B B7 (minimum-demo cut).
+  // SPA POSTs here when /session/<worldId>/plan opens; host-cp idempotently
+  // docker-execs the agent-stream-launch supervisor inside the world's
+  // devbox container. Body: { worldId, sessionId }. Returns the spawn
+  // status + container name + supervisor pid.
+  //
+  // Source: docs/design/olam-plan-chat-agent-runtime.md `lifecycle` +
+  // `bake-in-seam` sections.
+  if (url.pathname === '/api/plan/agent-runtime/trigger' && 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 });
+    }
+    if (!body.worldId || !body.sessionId) {
+      return jsonReply(res, 400, {
+        error: 'missing_fields',
+        message: 'worldId and sessionId required',
+      });
+    }
+    // Bearer for the container-side runners: shared-secret from
+    // ~/.olam/plan-chat-secret (matches plan-chat-service.mjs auth).
+    // JWT scope-claim migration is B9 / post-demo.
+    let bearer;
+    try {
+      bearer = readPlanChatSecret();
+    } catch (err) {
+      return jsonReply(res, 503, {
+        error: 'plan_chat_secret_unavailable',
+        message: `plan-chat-secret unreadable at ${PLAN_CHAT_SECRET_PATH}: ${err.message}`,
+      });
+    }
+    // host-cp's URL as seen from inside the devbox container. Bare-node
+    // mode (docker-cli) uses host.docker.internal; container mode uses
+    // the host-cp service name. Default: host.docker.internal for the
+    // operator-local demo flow.
+    const hostCpUrlForContainer =
+      process.env.OLAM_AGENT_RUNTIME_HOST_CP_URL ?? 'http://host.docker.internal:3112';
+    try {
+      const result = await triggerAgentRuntime({
+        worldId: body.worldId,
+        sessionId: body.sessionId,
+        hostCpUrl: hostCpUrlForContainer,
+        bearer,
+        dockerHost: DOCKER_HOST,
+      });
+      return jsonReply(res, 200, result);
+    } catch (err) {
+      return jsonReply(res, 500, {
+        error: 'agent_runtime_trigger_failed',
+        message: err.message,
+      });
+    }
+  }
+
+  // /api/plan-chat/* — passthrough proxy to plan-chat-service.
+  // The sidecar runs on PLAN_CHAT_SERVICE_URL (default http://127.0.0.1:3112).
+  // Strips the /api/plan-chat prefix; forwards method, headers, body, and
+  // query verbatim. Streams the response (Electric SQL long-poll friendly).
+  // Auth: client supplies Bearer; we don't add or strip it.
+  if (url.pathname.startsWith('/api/plan-chat/') || url.pathname === '/api/plan-chat') {
+    const upstreamBase =
+      process.env.PLAN_CHAT_SERVICE_URL ??
+      // Default depends on where host-cp runs. In-container = host.docker.internal;
+      // bare-node = 127.0.0.1. DOCKER_HOST=tcp://* implies container mode.
+      ((process.env.DOCKER_HOST ?? '').startsWith('tcp://')
+        ? 'http://host.docker.internal:3112'
+        : 'http://127.0.0.1:3112');
+    const subPath = url.pathname === '/api/plan-chat'
+      ? '/'
+      : url.pathname.slice('/api/plan-chat'.length);
+    const upstreamUrl = new URL(subPath + url.search, upstreamBase);
+    try {
+      const headers = {};
+      for (const [k, v] of Object.entries(req.headers)) {
+        if (k === 'host' || k === 'connection' || k === 'content-length') continue;
+        if (Array.isArray(v)) headers[k] = v.join(', ');
+        else if (typeof v === 'string') headers[k] = v;
+      }
+      // Buffer body for non-GET/HEAD; GET shouldn't carry one.
+      let body;
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        const chunks = [];
+        for await (const c of req) chunks.push(c);
+        body = Buffer.concat(chunks);
+      }
+      const upstreamRes = await fetch(upstreamUrl.toString(), {
+        method: req.method,
+        headers,
+        body,
+        redirect: 'manual',
+      });
+      res.statusCode = upstreamRes.status;
+      upstreamRes.headers.forEach((value, name) => {
+        if (name === 'content-encoding' || name === 'transfer-encoding' || name === 'connection') return;
+        res.setHeader(name, value);
+      });
+      if (upstreamRes.body) {
+        const reader = upstreamRes.body.getReader();
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          res.write(value);
+        }
+      }
+      return res.end();
+    } catch (err) {
+      return jsonReply(res, 502, {
+        error: 'plan_chat_proxy_failed',
+        upstream: upstreamUrl.toString(),
+        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
@@ -1933,6 +2071,85 @@ const server = http.createServer(async (req, res) => {
     }
   }
 
+  // ── /v1/worlds/:id/{status,logs} (Phase C / C1) ─────────────────
+  //
+  // Engine-agnostic per-world surfaces consumed by `olam status <world>`
+  // and `olam logs <world>`. Delegates to the active ContainerEngine
+  // (DockerEngine or KubernetesEngine) so the wire shape is identical
+  // regardless of the underlying runtime per Decision 17.
+  //
+  // Auth: this branch is INSIDE the `auth.isAuthorized(req)` gate above
+  // (line 742) — any caller without a valid token has already received
+  // 401. The v1-worlds-endpoints.test.mjs source-asserts that this
+  // route is registered after the auth gate, NOT outside it
+  // (Decision 18 — security-critical positional contract).
+  //
+  // worldId hardening: the K8s engine uses worldId as a labelSelector
+  // value (`olam-world-id=<worldId>`). A worldId containing `,` could
+  // synthesise additional label clauses ("comma-injection"). A token-
+  // holding caller already has full host-cp access so this is
+  // defense-in-depth, but we still reject non-canonical values to keep
+  // the engine's external query shape predictable.
+  const V1_WORLD_ID = /^[A-Za-z0-9._-]+$/;
+  const v1WorldsStatusMatch = /^\/v1\/worlds\/([^/?#]+)\/status\/?$/.exec(url.pathname);
+  if (v1WorldsStatusMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(v1WorldsStatusMatch[1]);
+    if (!V1_WORLD_ID.test(worldId)) {
+      return jsonReply(res, 400, { error: 'invalid_world_id', worldId });
+    }
+    try {
+      const report = await hostCpEngine.getWorldStatus(worldId);
+      return jsonReply(res, 200, report);
+    } catch (err) {
+      return jsonReply(res, 500, {
+        error: 'engine_error',
+        worldId,
+        message: err?.message ?? String(err),
+      });
+    }
+  }
+
+  const v1WorldsLogsMatch = /^\/v1\/worlds\/([^/?#]+)\/logs\/?$/.exec(url.pathname);
+  if (v1WorldsLogsMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(v1WorldsLogsMatch[1]);
+    if (!V1_WORLD_ID.test(worldId)) {
+      return jsonReply(res, 400, { error: 'invalid_world_id', worldId });
+    }
+    const tailParam = url.searchParams.get('tail');
+    const followParam = url.searchParams.get('follow');
+    const serviceParam = url.searchParams.get('service');
+    const opts = {
+      tail: tailParam != null ? parseInt(tailParam, 10) : 200,
+      follow: followParam === '1' || followParam === 'true',
+      ...(serviceParam ? { service: serviceParam } : {}),
+    };
+    const abortController = new AbortController();
+    req.on('close', () => abortController.abort());
+    res.writeHead(200, {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Cache-Control': 'no-cache',
+    });
+    try {
+      // Engine yields canonical { ts, container, subContainer, line }
+      // records; server formats one line per record: `<ts> <pod>/<container> <line>`.
+      const iterable = hostCpEngine.getWorldLogs(worldId, { ...opts, signal: abortController.signal });
+      for await (const rec of iterable) {
+        if (res.writableEnded || abortController.signal.aborted) break;
+        const ts = rec.ts || '-';
+        const container = rec.container || '-';
+        const sub = rec.subContainer || container;
+        res.write(`${ts} ${container}/${sub} ${rec.line}\n`);
+      }
+    } catch (err) {
+      if (!res.writableEnded) {
+        res.write(`# engine error: ${err?.message ?? String(err)}\n`);
+      }
+    } finally {
+      if (!res.writableEnded) res.end();
+    }
+    return;
+  }
+
   // Anything else → 404. B4 ships static SPA serving + auth.
   jsonReply(res, 404, {
     error: 'not_found',
@@ -2318,7 +2535,7 @@ const DIST_DIR = (() => {
 })();
 
 const SPA_ROUTES = new Set(['/', '/worlds', '/workspaces', '/inbox', '/repos', '/runbooks']);
-const SPA_PREFIX = ['/world/', '/worlds/', '/workspaces/', '/inbox/', '/repos/', '/runbooks/'];
+const SPA_PREFIX = ['/world/', '/worlds/', '/workspaces/', '/inbox/', '/repos/', '/runbooks/', '/session/'];
 
 // Top-level path segments that are NOT world IDs. Mirrors RESERVED_SEGMENTS
 // in lib/worldId.ts — keep in sync.
@@ -2536,7 +2753,7 @@ let _spaCacheMtime = 0;
 //       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).
-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','/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|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>`;
+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>`;
 
 async function renderSpaShell(filePath) {
   const stat = fs.statSync(filePath);
@@ -2642,12 +2859,39 @@ startWorldsSnapshotLoop();
 startTunnelsSnapshotLoop();
 startListeningSnapshotLoop();
 
+// ── Phase 1a / B1 (PR3): engine-select + await-before-listen ─────
+//
+// Decision 15: the async KubernetesEngine factory MUST be fully awaited
+// BEFORE `server.listen()`. If the factory throws (context-allowlist guard
+// rejects a non-local kubectl context), startup aborts via the top-level
+// await's unhandled rejection — the HTTP server never binds. No half-live
+// state.
+//
+// Selection precedence matches the existing resolveHostCpEngine():
+//   1. OLAM_HOST_CP_ENGINE=kubernetes  → KubernetesEngine
+//   2. KUBERNETES_SERVICE_HOST set     → KubernetesEngine (autodetect)
+//   3. otherwise                       → DockerEngine
+//
+// DockerEngine ships as a sync factory (no await needed), but we still
+// 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 });
+})();
+
 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(`  engine=${hostCpEngine.engineName}${hostCpEngine.context ? ` ctx=${hostCpEngine.context}` : ''}`);
   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

package/package.json

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