@pleri/olam-cli 0.1.201 → 0.1.205

package/host-cp/src/server.mjs

@@ -27,6 +27,7 @@ import path from 'node:path';
 import url from 'node:url';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
 
 const execFileAsync = promisify(execFile);
 import { SecretCache } from './secret-cache.mjs';
@@ -48,6 +49,10 @@ import {
 import { betaResponseEmitter, cfAccessHeaders } from '@olam/auth-client';
 import { attemptRecovery, findScenarioForKind } from '../recovery/index.mjs';
 import { detectHaltChunk } from './halt-detect.mjs';
+import {
+  buildPlanChatProxyHeaders,
+  injectBrokerSecret,
+} from './plan-chat-proxy-headers.mjs';
 import { evaluateRedirect, applyRedirect } from './redirect.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { isPlanningPath } from './bootstrap-selective.mjs';
@@ -104,6 +109,11 @@ import { handleDispatchFromLinear } from './lib/linear-dispatch.mjs';
 // (safePersistLastDispatch imported above alongside readLastDispatch)
 import { emitTierSuggestion } from '../dispatch/auto-tier-scheduler.mjs';
 import { isServeOnly, isOrchestrationRoute, ORCHESTRATION_UNAVAILABLE } from './serve-only-config.mjs';
+// D.1 — operator-side long-poll (Phase D of 3-axis-local-cloud-mode-v1).
+// Feature-flag-gated: only imported when OLAM_OPSIDE_LONGPOLL=1.
+// Import is static so the module is parsed at startup (cheap), but
+// startPoll() is only called when the flag is on.
+import { startPoll, stopPoll } from './op-side-longpoll.mjs';
 
 // ── Deployment-mode detection ─────────────────────────────────────
 //
@@ -197,13 +207,43 @@ const OLAM_EMAIL_ATTACHMENTS_ROOT =
   (HOST_CP_MODE === 'container'
     ? '/data/email-attachments'
     : path.join(os.homedir(), '.olam', 'email-attachments'));
-// Linear-webhook trigger (POST /v1/dispatch-from-linear).
-// OLAM_LINEAR_WEBHOOK_SECRET — shared secret set in Linear webhook settings.
+// Linear-dispatch trigger (POST /v1/dispatch-from-linear).
+// OLAM_LINEAR_DISPATCH_SIGNING_SECRET — shared secret with the
+//   cloudflare-worker-linear-sync Worker. The Worker signs a canonical
+//   dispatch string and carries the signature in the request BODY (NOT an
+//   X-Linear-Signature header). This MUST match the Worker's
+//   OLAM_LINEAR_DISPATCH_SIGNING_SECRET.
+// OLAM_LINEAR_WEBHOOK_SECRET — retained for back-compat / any future direct
+//   inbound-Linear-webhook receiver; NOT used by the dispatch hop.
 // OLAM_LINEAR_WORLD_ID       — optional; when set, route events to this worldId
 //                              instead of spawning a new world each time.
 // See docs/architecture/linear-as-trigger.md.
 const OLAM_LINEAR_WEBHOOK_SECRET = process.env.OLAM_LINEAR_WEBHOOK_SECRET ?? '';
+const OLAM_LINEAR_DISPATCH_SIGNING_SECRET =
+  process.env.OLAM_LINEAR_DISPATCH_SIGNING_SECRET ?? '';
 const OLAM_LINEAR_WORLD_ID = process.env.OLAM_LINEAR_WORLD_ID ?? '';
+// Cloud-burst dispatch (3-axis-local-cloud-mode-v1 Phase A1).
+// OLAM_SANDBOX_RUNNER_URL  — public HTTPS URL of the worker-runner-cloudflare-sandbox /spawn endpoint.
+// OLAM_SANDBOX_RUNNER_TOKEN — bearer token presented to the runner's /spawn.
+// Both required for the /api/world/:id/dispatch-cloud-burst endpoint to function.
+// When either is absent, the endpoint returns 503 cloud_burst_not_configured.
+const OLAM_SANDBOX_RUNNER_URL = process.env.OLAM_SANDBOX_RUNNER_URL ?? '';
+const OLAM_SANDBOX_RUNNER_TOKEN = process.env.OLAM_SANDBOX_RUNNER_TOKEN ?? '';
+
+// D.1 — operator-side long-poll feature flag.
+// Set OLAM_OPSIDE_LONGPOLL=1 to enable. Default OFF (no behavior change
+// when unset). Also requires OLAM_CLOUD_URL to know where plan-DO lives.
+// OLAM_OPSIDE_LONGPOLL_AUTH provides the Authorization header value for
+// Basic auth to plan-DO; defaults to Basic auth with operator/<SHOWCASE_PW>.
+const OLAM_OPSIDE_LONGPOLL = process.env.OLAM_OPSIDE_LONGPOLL === '1';
+const OLAM_CLOUD_URL = process.env.OLAM_CLOUD_URL ?? '';
+const OLAM_SHOWCASE_PASSWORD = process.env.OLAM_SHOWCASE_PASSWORD ?? '';
+// Build the Basic auth header from OLAM_SHOWCASE_PASSWORD when not
+// explicitly overridden. Showcase Basic auth is the v1 mechanism (Decision #7).
+const OLAM_OPSIDE_LONGPOLL_AUTH = process.env.OLAM_OPSIDE_LONGPOLL_AUTH
+  ?? (OLAM_SHOWCASE_PASSWORD
+    ? `Basic ${Buffer.from(`operator:${OLAM_SHOWCASE_PASSWORD}`).toString('base64')}`
+    : '');
 
 // In-flight delivery IDs for deduplication. Linear retries on non-2xx;
 // we MUST return 2xx for duplicates so retries terminate. Never use 409.
@@ -360,6 +400,33 @@ function readDogfoodRepoUrl() {
   return '';
 }
 
+/**
+ * Resolve the default MULTI-repo clone list to inject into cloud-dispatch
+ * bodies as `repoUrls[]`. The SPA composer has no multi-repo picker (it sends
+ * a single optional repoUrl at most), so for multi-repo worlds (e.g.
+ * atlas-core + diner-app) host-cp injects the operator-configured default.
+ * Source order: OLAM_DOGFOOD_REPO_URLS env, then ~/.olam/dogfood-repo-urls
+ * file. Both accept newline- OR comma-separated URLs. Absent/empty → [] (no
+ * injection; falls back to the single-repo dogfoodRepoUrl path). Mirrors
+ * readDogfoodRepoUrl() — operators have ONE pattern, singular + plural.
+ * @returns {string[]}
+ */
+function readDogfoodRepoUrls() {
+  const raw =
+    process.env['OLAM_DOGFOOD_REPO_URLS'] ??
+    (() => {
+      try {
+        return fs.readFileSync(path.join(os.homedir(), '.olam', 'dogfood-repo-urls'), 'utf-8');
+      } catch {
+        return '';
+      }
+    })();
+  return raw
+    .split(/[\n,]/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 /**
  * Resolve the cloud-kg-mirror classifier proxy URL the runner forwards
  * into spawned CF Sandbox child worlds. When set, host-cp enriches
@@ -404,6 +471,139 @@ function readKgProxyBearer() {
   return '';
 }
 
+/**
+ * KG workspace the dispatched sandbox queries (e.g. `atlas-one`, which spans
+ * atlas-core + diner-app + 9 sibling repos). The runner exports it as
+ * OLAM_KG_PROXY_WORKSPACE so the in-sandbox `kg` helper scopes `/v1/graph` and
+ * the classify hook scopes its L2 probe. Source order: OLAM_KG_PROXY_WORKSPACE
+ * env, then ~/.olam/kg-proxy-workspace file. The per-world `workspace` field on
+ * the dispatch body (when present) wins over this at the enrich site below.
+ * Absent → no workspace injection (the KG is reachable but graph queries are
+ * un-scoped). Mirrors readKgProxyUrl/Bearer — operators have ONE pattern.
+ */
+function readKgProxyWorkspace() {
+  const fromOlamEnv = process.env['OLAM_KG_PROXY_WORKSPACE'];
+  if (fromOlamEnv && fromOlamEnv.length > 0) return fromOlamEnv.trim();
+  try {
+    const file = path.join(os.homedir(), '.olam', 'kg-proxy-workspace');
+    const content = fs.readFileSync(file, 'utf-8').trim();
+    if (content.length > 0) return content;
+  } catch {
+    // file absent — fall through
+  }
+  return '';
+}
+
+/**
+ * Resolve the REMOTE host-cp base URL to inject into cloud-dispatch bodies as
+ * `hostCpUrl`. The CF-Sandbox runner posts chunks back to whatever
+ * OLAM_HOST_CP_URL it was deployed with — NOT this local host-cp. To see live
+ * agent reasoning in the SPA, the operator stands up a public tunnel (e.g.
+ * `cloudflared tunnel --url http://127.0.0.1:19000`) to THIS host-cp and writes
+ * the tunnel URL to ~/.olam/remote-host-cp-url. We forward it so the runner's
+ * in-container chunk-poster targets it (body.hostCpUrl wins over the runner's
+ * deploy-time env). Source order: OLAM_REMOTE_HOST_CP_URL env, then the file.
+ * Absent → no injection (chunks land at the runner's default sink). Mirrors
+ * readKgProxyUrl() — operators have ONE pattern.
+ */
+function readRemoteHostCpUrl() {
+  const fromOlamEnv = process.env['OLAM_REMOTE_HOST_CP_URL'];
+  if (fromOlamEnv && fromOlamEnv.length > 0) return fromOlamEnv.trim();
+  try {
+    const file = path.join(os.homedir(), '.olam', 'remote-host-cp-url');
+    const content = fs.readFileSync(file, 'utf-8').trim();
+    if (content.length > 0) return content;
+  } catch {
+    // file absent — fall through
+  }
+  return '';
+}
+
+/**
+ * TTL-cached aggregator for the four ~/.olam/ config values that enrich
+ * cloud-dispatch payloads. Called on every /api/cloud-dispatch and
+ * /api/plans/create request — without caching each call issued 4 synchronous
+ * readFileSync syscalls that block the Node.js event loop in series.
+ *
+ * Cache design:
+ *   TTL: OLAM_DISPATCH_CONFIG_TTL_MS (default 10 000 ms).
+ *     Worst-case staleness after an operator file edit: one TTL window.
+ *
+ *   fs.watch: each of the 4 ~/.olam/ files is watched for 'change'/'rename'
+ *     events on first read. A watcher event immediately sets _dispatchConfigCache.value
+ *     to null, so the next request re-reads all four files fresh — operator
+ *     edits typically take effect on the very next dispatch, not after the TTL.
+ *     Watchers are armed once and never torn down (host-cp is a long-running
+ *     process; the 4 files are operator-written config, rarely mutated).
+ *     fs.watch failures (e.g. network-mounted homedir, non-existent file) are
+ *     swallowed — the TTL provides the fallback path.
+ *
+ *   Env-var paths (OLAM_ANTHROPIC_BASE_URL etc.) can only change on process
+ *     restart; the individual readers short-circuit on env before touching disk,
+ *     so their values naturally stay consistent with the cached result.
+ *
+ *   Thread-safety: Node.js is single-threaded. Concurrent async handlers
+ *     race to read/write the same cache object. All outcomes are idempotent
+ *     (same files → same values); the last writer wins harmlessly.
+ *
+ * Saving: 4 synchronous readFileSync calls per dispatch eliminated within the
+ *   TTL window. Under concurrent dispatch bursts this removes the most
+ *   common event-loop blocking on the hot path.
+ *
+ * @returns {{ anthropicBaseUrl: string, dogfoodRepoUrl: string, kgProxyUrl: string, kgProxyBearer: string, kgWorkspace: string }}
+ */
+const _DISPATCH_CONFIG_TTL_MS =
+  Number(process.env['OLAM_DISPATCH_CONFIG_TTL_MS'] ?? 10_000);
+
+/** @type {{ value: { anthropicBaseUrl: string, dogfoodRepoUrl: string, kgProxyUrl: string, kgProxyBearer: string, kgWorkspace: string } | null, ts: number, watchersArmed: boolean }} */
+const _dispatchConfigCache = { value: null, ts: 0, watchersArmed: false };
+
+function _invalidateDispatchConfigCache() {
+  _dispatchConfigCache.value = null;
+}
+
+function _armDispatchConfigWatchers() {
+  if (_dispatchConfigCache.watchersArmed) return;
+  _dispatchConfigCache.watchersArmed = true;
+  const watchFiles = [
+    'anthropic-base-url',
+    'dogfood-repo-url',
+    'kg-proxy-url',
+    'kg-proxy-bearer',
+    'kg-proxy-workspace',
+  ];
+  for (const name of watchFiles) {
+    const file = path.join(os.homedir(), '.olam', name);
+    try {
+      fs.watch(file, () => _invalidateDispatchConfigCache());
+    } catch {
+      // File absent or fs.watch unavailable (e.g. network-mounted homedir).
+      // TTL covers this fallback path — no action needed.
+    }
+  }
+}
+
+function readHostDispatchConfig() {
+  const now = Date.now();
+  if (
+    _dispatchConfigCache.value !== null &&
+    now - _dispatchConfigCache.ts < _DISPATCH_CONFIG_TTL_MS
+  ) {
+    return _dispatchConfigCache.value;
+  }
+  const value = {
+    anthropicBaseUrl: readAnthropicBaseUrl(),
+    dogfoodRepoUrl: readDogfoodRepoUrl(),
+    kgProxyUrl: readKgProxyUrl(),
+    kgProxyBearer: readKgProxyBearer(),
+    kgWorkspace: readKgProxyWorkspace(),
+  };
+  _dispatchConfigCache.value = value;
+  _dispatchConfigCache.ts = now;
+  _armDispatchConfigWatchers();
+  return value;
+}
+
 /** @type {Record<string, number>} */
 let WORLDS = {};
 
@@ -825,7 +1025,6 @@ async function tickWorldsSnapshot() {
       String(a?.id ?? '').localeCompare(String(b?.id ?? '')),
     );
     const json = JSON.stringify(sorted);
-    const { createHash } = await import('node:crypto');
     const hash = createHash('sha1').update(json).digest('hex');
     if (hash === lastWorldsHash) return;
     lastWorldsHash = hash;
@@ -895,7 +1094,6 @@ async function tickTunnelsSnapshot() {
       tunnels: [...byWorld[id]].sort((a, b) => a.name.localeCompare(b.name)),
     }));
     const json = JSON.stringify(stable);
-    const { createHash } = await import('node:crypto');
     const hash = createHash('sha1').update(json).digest('hex');
     if (hash === lastTunnelsHash) return;
     lastTunnelsHash = hash;
@@ -938,7 +1136,6 @@ async function tickListeningSnapshot() {
       servers: [...w.servers].sort((a, b) => a.port - b.port),
     }));
     const json = JSON.stringify(stable);
-    const { createHash } = await import('node:crypto');
     const hash = createHash('sha1').update(json).digest('hex');
     if (hash === lastListeningHash) return;
     lastListeningHash = hash;
@@ -1055,6 +1252,11 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   // 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.
+  //
+  // Phase B (3-axis-local-cloud-mode-v1) adds two new fields:
+  //   capabilities — { local_docker, cloud_burst, cloud_tier } runtime capability flags
+  //   apiBase      — '' by default; non-empty routes all SPA fetches to a different host
+  // Both fields are additive; existing fields are preserved for backward compat.
   if (url.pathname === '/api/bootstrap') {
     return jsonReply(res, 200, {
       token: auth.token,
@@ -1063,6 +1265,17 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       header_format: 'Bearer <token>',
       hint: 'SPA: set document.cookie = `olam_host_cp_token=${token}; path=/; samesite=strict` then fetch (`/api/world/...`) freely.',
       cloud_enabled: Boolean(process.env.OLAM_CLOUD_URL && process.env.OLAM_SHOWCASE_PASSWORD),
+      // Phase B: tri-state capability flags. SPA reads these to populate
+      // the PlanModeSelector (Phase C) and to gate the executor dispatch path.
+      capabilities: {
+        local_docker: true,
+        cloud_burst: Boolean(OLAM_SANDBOX_RUNNER_URL && OLAM_SANDBOX_RUNNER_TOKEN),
+        cloud_tier: Boolean(process.env.OLAM_CLOUD_URL),
+      },
+      // Phase B: remote host-cp re-targeting. '' means same origin (no-op).
+      // v1 always returns '' — the field exists so the SPA can read it
+      // without a code change when a future operator sets a non-empty value.
+      apiBase: '',
     });
   }
 
@@ -1949,6 +2162,118 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   const parsed = parseProxyPath(url.pathname);
   if (parsed) {
     const { worldId, subPath } = parsed;
+
+    // /api/world/:id/dispatch-cloud-burst — must be checked BEFORE the WORLDS
+    // registry lookup below. Cloud-burst dispatches to the CF Sandbox runner
+    // directly (no local Docker world required). The runner can receive bursts
+    // for worlds that have never been registered locally — this is the whole
+    // point of the cloud-burst path. The handler after the if(parsed) block is
+    // unreachable because the proxy block returns before it; this is the
+    // authoritative check.
+    if (subPath === '/dispatch-cloud-burst' && req.method === 'POST') {
+      if (!OLAM_SANDBOX_RUNNER_URL || !OLAM_SANDBOX_RUNNER_TOKEN) {
+        return jsonReply(res, 503, {
+          error: 'cloud_burst_not_configured',
+          message:
+            'host-cp needs OLAM_SANDBOX_RUNNER_URL + OLAM_SANDBOX_RUNNER_TOKEN to dispatch cloud bursts. ' +
+            'Set both env vars + restart host-cp.',
+        });
+      }
+      try {
+        const reqChunks = [];
+        for await (const c of req) reqChunks.push(c);
+        let parsedBody;
+        try {
+          parsedBody = JSON.parse(Buffer.concat(reqChunks).toString('utf8'));
+        } catch {
+          return jsonReply(res, 400, { error: 'body_not_json' });
+        }
+        // Seam C guard (T1): strip ANTHROPIC_API_KEY + sk-ant-* keys from options
+        // before building the spawn body. Structural — matches sandbox-dispatch-client.
+        const safeOptions = {};
+        if (parsedBody.options && typeof parsedBody.options === 'object') {
+          for (const [k, v] of Object.entries(parsedBody.options)) {
+            if (k !== 'ANTHROPIC_API_KEY' && !k.startsWith('sk-ant-')) safeOptions[k] = v;
+          }
+        }
+        // Enrich with host config (parity with cloud-dispatch handler).
+        // readHostDispatchConfig() is TTL-cached (default 10 s) + fs.watch invalidated.
+        // Body-field-wins semantics: caller-supplied value always takes precedence over
+        // the host default for each optional field (additive: absent fields use the
+        // host default so vault-routed deployments propagate without SPA changes).
+        // idempotencyKey is always generated fresh — deduplicates retried bursts at
+        // the runner's /spawn endpoint (mirrors the cloud-dispatch handler A3.2 contract).
+        const {
+          anthropicBaseUrl: hostAnthropicBaseUrl,
+          dogfoodRepoUrl: hostRepoUrl,
+          kgProxyUrl: hostKgProxyUrl,
+          kgProxyBearer: hostKgProxyBearer,
+          kgWorkspace: hostKgWorkspace,
+        } = readHostDispatchConfig();
+        const burstAnthropicBaseUrl = parsedBody.anthropicBaseUrl || hostAnthropicBaseUrl;
+        const burstRepoUrl = parsedBody.repoUrl || hostRepoUrl;
+        const burstKgProxyUrl = parsedBody.kgProxyUrl || hostKgProxyUrl;
+        const burstKgProxyBearer = parsedBody.kgProxyBearer || hostKgProxyBearer;
+        const burstKgWorkspace = parsedBody.kgWorkspace ||
+          (typeof parsedBody.workspace === 'string' && parsedBody.workspace.length > 0 ? parsedBody.workspace : '') ||
+          hostKgWorkspace;
+        const burstHostCpUrl = parsedBody.hostCpUrl || readRemoteHostCpUrl();
+        const burstChunksSinkUrl = parsedBody.chunksSinkUrl || OLAM_CLOUD_URL;
+        // Always generate a fresh idempotency key — prevents double-spawn on
+        // retried requests (mirrors the cloud-dispatch handler's A3.2 contract).
+        const idempotencyKey = crypto.randomUUID();
+        const spawnBody = {
+          prompt: parsedBody.prompt ?? '',
+          sessionId: parsedBody.session_id ?? worldId,
+          worldId: parsedBody.world_id ?? worldId,
+          bypassPermissions: typeof parsedBody.bypassPermissions === 'boolean' ? parsedBody.bypassPermissions : true,
+          ...(burstRepoUrl ? { repoUrl: burstRepoUrl } : {}),
+          ...(parsedBody.repoUrls && Array.isArray(parsedBody.repoUrls) && parsedBody.repoUrls.length > 0 ? { repoUrls: parsedBody.repoUrls } : {}),
+          // submodules → runner clones with --recurse-submodules (vs --depth 1).
+          // cloud-dispatch forwards it via its `...parsed` spread; cloud-burst
+          // builds an explicit spawnBody, so it must forward it too or a
+          // submodule repo dispatched via burst silently clones without its
+          // submodules (drift parity with cloud-dispatch — same class as #1572).
+          ...(typeof parsedBody.submodules === 'boolean' ? { submodules: parsedBody.submodules } : {}),
+          ...(burstAnthropicBaseUrl ? { anthropicBaseUrl: burstAnthropicBaseUrl } : {}),
+          ...(burstKgProxyUrl ? { kgProxyUrl: burstKgProxyUrl } : {}),
+          ...(burstKgProxyBearer ? { kgProxyBearer: burstKgProxyBearer } : {}),
+          ...(burstKgWorkspace ? { kgWorkspace: burstKgWorkspace } : {}),
+          ...(burstHostCpUrl ? { hostCpUrl: burstHostCpUrl } : {}),
+          ...(burstChunksSinkUrl ? { chunksSinkUrl: burstChunksSinkUrl } : {}),
+          idempotencyKey,
+          ...safeOptions,
+        };
+        const spawnRes = await fetch(`${OLAM_SANDBOX_RUNNER_URL}/spawn`, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${OLAM_SANDBOX_RUNNER_TOKEN}`,
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify(spawnBody),
+        });
+        if (!spawnRes.ok) {
+          const errText = (await spawnRes.text()).slice(0, 200);
+          return jsonReply(res, spawnRes.status, {
+            error: 'cloud_burst_runner_error',
+            message: errText,
+          });
+        }
+        let spawnAck = {};
+        try { spawnAck = await spawnRes.json(); } catch { /* older runner */ }
+        return jsonReply(res, 200, {
+          status: 'dispatched',
+          sandbox_session_id: spawnAck.sessionId,
+          world_id: parsedBody.world_id ?? worldId,
+        });
+      } catch (err) {
+        return jsonReply(res, 502, {
+          error: 'cloud_burst_dispatch_failed',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     const port = WORLDS[worldId];
     if (port === undefined) {
       return jsonReply(res, 404, {
@@ -1958,6 +2283,53 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       });
     }
 
+    // SPA-driven UAT (WS4): /api/world/<id>/uat[/status] is NOT a per-world-CP
+    // proxy — it forwards to the Cloudflare worker-runner that boots atlas-core
+    // + diner-app in a sandbox and returns the two quick-tunnel URLs. Handle it
+    // HERE, BEFORE the docker per-world secret-fetch + proxy below (which assumes
+    // a local `olam-<id>-devbox` container and 500s for cloud UAT worlds).
+    if ((subPath === '/uat' || subPath === '/uat/status') && req.method === 'POST') {
+      if (!OLAM_SANDBOX_RUNNER_URL || !OLAM_SANDBOX_RUNNER_TOKEN) {
+        return jsonReply(res, 503, {
+          error: 'uat_not_configured',
+          message: 'host-cp needs OLAM_SANDBOX_RUNNER_URL + OLAM_SANDBOX_RUNNER_TOKEN to run UAT.',
+        });
+      }
+      const isStatus = subPath === '/uat/status';
+      try {
+        const reqChunks = [];
+        for await (const c of req) reqChunks.push(c);
+        let uatIn = {};
+        if (reqChunks.length) {
+          try { uatIn = JSON.parse(Buffer.concat(reqChunks).toString('utf8')); }
+          catch { return jsonReply(res, 400, { error: 'body_not_json' }); }
+        }
+        const uatBody = {
+          sessionId: uatIn.session_id ?? uatIn.sessionId ?? worldId,
+          ...(uatIn.atlasCoreUrl ? { atlasCoreUrl: uatIn.atlasCoreUrl } : {}),
+          ...(uatIn.dinerAppUrl ? { dinerAppUrl: uatIn.dinerAppUrl } : {}),
+          // Only the start call clones; inject the gh token server-side so the
+          // browser never carries it.
+          ...(!isStatus && process.env.OLAM_UAT_GH_TOKEN ? { ghToken: process.env.OLAM_UAT_GH_TOKEN } : {}),
+        };
+        const uatRes = await fetch(`${OLAM_SANDBOX_RUNNER_URL}${isStatus ? '/uat/status' : '/uat'}`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${OLAM_SANDBOX_RUNNER_TOKEN}`, 'content-type': 'application/json' },
+          body: JSON.stringify(uatBody),
+          signal: AbortSignal.timeout(90_000),
+        });
+        const text = await uatRes.text();
+        let payload;
+        try { payload = JSON.parse(text); } catch { payload = { raw: text.slice(0, 400) }; }
+        return jsonReply(res, uatRes.ok ? 200 : uatRes.status, payload);
+      } catch (err) {
+        return jsonReply(res, 502, {
+          error: 'uat_dispatch_failed',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     // 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
@@ -2445,12 +2817,7 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       : 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;
-      }
+      const headers = buildPlanChatProxyHeaders(req.headers);
       // Buffer body for non-GET/HEAD; GET shouldn't carry one.
       let body;
       if (req.method !== 'GET' && req.method !== 'HEAD') {
@@ -2472,6 +2839,17 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
         } catch {
           // Body not JSON — pass through to upstream as-is. No event.
         }
+
+        // F3 (T9) — this host-cp proxy is the TRUSTED operator surface: the
+        // SPA browser → host-cp → plan-chat-service. A WORLD process never
+        // routes through here (it talks to plan-chat-service directly via
+        // host.docker.internal). So when the operator-chunk broker secret is
+        // configured, inject it here so the operator's own SPA interject is
+        // authorised to write operator chunks, while a world process — which
+        // cannot present this secret — is rejected by plan-chat-service's gate.
+        // Injected only for chunk writes; harmless for non-operator chunks
+        // (the gate only checks it for actor_type='operator').
+        injectBrokerSecret(headers, process.env.OLAM_OPERATOR_CHUNK_SECRET);
       }
 
       const upstreamRes = await fetch(upstreamUrl.toString(), {
@@ -2582,13 +2960,16 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     return;
   }
 
-  // POST /v1/dispatch-from-linear — Linear webhook receiver.
+  // POST /v1/dispatch-from-linear — linear-sync Worker dispatch receiver.
   //
-  // Linear POSTs a JSON payload and an HMAC-SHA256 signature in
-  // X-Linear-Signature. host-cp validates the signature, deduplicates
-  // by webhookId (Linear retries on non-2xx — duplicates MUST return 202),
-  // and either routes to a pinned world (OLAM_LINEAR_WORLD_ID) or returns
-  // a spawn_pending descriptor for the MCP/CLI layer.
+  // The cloudflare-worker-linear-sync Worker POSTs a structured dispatch
+  // payload whose HMAC-SHA256 signature is carried IN THE BODY
+  // (`payload.signature`) over a canonical string, keyed by
+  // OLAM_LINEAR_DISPATCH_SIGNING_SECRET (NOT an X-Linear-Signature header,
+  // NOT the Linear webhook secret). host-cp validates that signature +
+  // replay window, deduplicates by deliveryId (Worker retries — duplicates
+  // MUST return 202), and either routes to a pinned world
+  // (OLAM_LINEAR_WORLD_ID) or returns a spawn_pending descriptor.
   //
   // Dedup rule: HTTP 202 { action: 'deduplicated' } — NEVER 409.
   // Body cap: 1 MiB (Linear payloads are small JSON, no attachments).
@@ -2610,7 +2991,6 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     req.on('end', async () => {
       if (aborted) return;
       const rawBody = Buffer.concat(chunks);
-      const signature = req.headers['x-linear-signature'] ?? '';
       let payload;
       try {
         payload = JSON.parse(rawBody.toString('utf8') || '{}');
@@ -2619,10 +2999,8 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       }
       try {
         const result = await handleDispatchFromLinear({
-          rawBody,
           payload,
-          signature,
-          secret: OLAM_LINEAR_WEBHOOK_SECRET,
+          secret: OLAM_LINEAR_DISPATCH_SIGNING_SECRET,
           worlds: WORLDS,
           inFlight: linearInFlight,
           targetWorldId: OLAM_LINEAR_WORLD_ID || undefined,
@@ -2638,6 +3016,100 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     return;
   }
 
+  // plan-chat-spa-attachments Phase A — POST /api/cloud-attachment.
+  //
+  // Bearer-gated (the central auth.isAuthorized gate above covers all /api/*
+  // routes — same auth the SPA already carries for /api/cloud-dispatch). This
+  // is a RAW-BYTE proxy: it streams the multipart body to plan-DO's
+  // /v1/attachment (Basic operator:$OLAM_SHOWCASE_PASSWORD) WITHOUT decoding
+  // it — `Buffer.concat(chunks)` with NO `.toString('utf8')` (utf8-decoding
+  // binary file bytes corrupts them) and forwards Content-Type VERBATIM so the
+  // upstream multipart boundary stays intact.
+  //
+  // Streaming size-guard (mirrors /v1/dispatch-from-email @ ~2893): a running
+  // byte counter aborts with 413 + req.destroy() BEFORE fully buffering. Capped
+  // at 32 MiB/file. Do NOT copy the JSON-buffering shape of /api/cloud-dispatch.
+  if (url.pathname === '/api/cloud-attachment' && 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_attachment_not_configured',
+        message:
+          'host-cp needs OLAM_CLOUD_URL + OLAM_SHOWCASE_PASSWORD to proxy cloud attachments. ' +
+          'Set both env vars + restart host-cp.',
+      });
+    }
+    // session_id query param → upstream plan_id (per-session = per-plan).
+    // NOTE: this proxy reads session_id from the QUERY STRING, NOT the parsed
+    // body — it is a raw-byte multipart proxy that never decodes the envelope.
+    // (/api/cloud-dispatch differs: it parses its JSON body and reads
+    // session_id from there.) The SPA must therefore carry session_id in the
+    // upload URL query, or every upload forwards plan_id='default'. Defaults
+    // to 'default' when absent.
+    const sessionId = url.searchParams.get('session_id') ?? 'default';
+    const contentType = req.headers['content-type'] ?? 'application/octet-stream';
+
+    const chunks = [];
+    let size = 0;
+    // P2-5 — this caps the RAW MULTIPART BODY (envelope), not the file. A
+    // max-allowed 32 MiB file plus its multipart headers/boundary exceeds
+    // 32 MiB, so capping at 32 here 413'd an at-ceiling file. The 32 MiB
+    // PER-FILE limit is enforced downstream at plan-DO (/v1/attachment); this
+    // 33 MiB cap only bounds the envelope to keep a runaway upload from
+    // buffering unbounded.
+    const MAX_BODY = 33 * 1024 * 1024;
+    let aborted = false;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        aborted = true;
+        jsonReply(res, 413, { error: 'attachment_too_large', maxBytes: MAX_BODY });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('error', () => {
+      if (!aborted && !res.headersSent) {
+        aborted = true;
+        jsonReply(res, 400, { error: 'attachment_stream_error' });
+      }
+    });
+    req.on('end', async () => {
+      if (aborted) return;
+      // RAW BYTES — never decode. utf8-decoding binary corrupts the file.
+      const rawBody = Buffer.concat(chunks);
+      const basicAuth = Buffer.from(`operator:${showcasePw}`).toString('base64');
+      try {
+        const upstream = await fetch(
+          `${cloudUrl.replace(/\/+$/, '')}/v1/attachment?plan_id=${encodeURIComponent(sessionId)}`,
+          {
+            method: 'POST',
+            headers: {
+              'Authorization': `Basic ${basicAuth}`,
+              // Content-Type VERBATIM — preserves the multipart boundary.
+              'content-type': contentType,
+              ...cfAccessHeaders(),
+            },
+            body: rawBody,
+          },
+        );
+        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: 'cloud_attachment_proxy_failed',
+          message: err.message,
+        });
+      }
+    });
+    return;
+  }
+
   if (url.pathname === '/api/cloud-dispatch' && req.method === 'POST') {
     const cloudUrl = process.env.OLAM_CLOUD_URL;
     const showcasePw = process.env.OLAM_SHOWCASE_PASSWORD;
@@ -2706,34 +3178,77 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
         );
       }
 
-      // 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();
-      // Sibling injection: default repoUrl for the cloud Sandbox coding loop.
-      // The SPA has no repo-config knowledge today (Decision 2 in
-      // olam-builds-olam-cloud-dogfood: no SPA repo-selector); host-cp is the
-      // injection point. Source order: OLAM_DOGFOOD_REPO_URL env, then
-      // ~/.olam/dogfood-repo-url file. Absent → no injection (the dispatch
-      // runs text-only, like before this change).
-      const dogfoodRepoUrl = readDogfoodRepoUrl();
-      // cloud-kg-mirror Phase 1: propagate the classifier Worker URL +
-      // bearer so the runner can inject them into the sandbox env. When
-      // either is missing the dispatched world's PreToolUse hook falls
-      // through to grep via the existing fail-open path. Operator opts
-      // in by writing ~/.olam/kg-proxy-url + ~/.olam/kg-proxy-bearer.
-      const kgProxyUrl = readKgProxyUrl();
-      const kgProxyBearer = readKgProxyBearer();
+      // Gap 3: enrich the dispatch body with the operator's host config so
+      // plan-DO can propagate these values to spawned CF Sandbox child worlds.
+      // Only injected when not already set by the SPA — host-cp is the sole
+      // injection point for auth-worker / repo / kg-proxy config.
+      // readHostDispatchConfig() is TTL-cached (default 10 s) + fs.watch
+      // invalidated — eliminates 4 synchronous readFileSync calls per dispatch
+      // on the hot path; see its JSDoc for the staleness window contract.
+      const {
+        anthropicBaseUrl,
+        dogfoodRepoUrl,
+        kgProxyUrl,
+        kgProxyBearer,
+        kgWorkspace: hostKgWorkspace,
+      } = readHostDispatchConfig();
+      // KG workspace: the per-world `workspace` field (set by the SPA's
+      // WorkspacePicker) wins; otherwise fall back to the host default
+      // (~/.olam/kg-proxy-workspace). The runner exports it as
+      // OLAM_KG_PROXY_WORKSPACE so the in-sandbox `kg` helper + classify hook
+      // scope their queries to the right graph (e.g. atlas-one).
+      const kgWorkspace =
+        (typeof parsed.workspace === 'string' && parsed.workspace.length > 0
+          ? parsed.workspace
+          : '') || hostKgWorkspace;
+      // 3-axis-local-cloud-mode-v1 Phase A3 A3.2: generate a uuid-v7 per dispatch
+      // for idempotency deduplication at the runner's /spawn endpoint. The key
+      // travels as both a header (Idempotency-Key) and a body field (idempotencyKey)
+      // so plan-DO can forward it even without native header-forwarding support
+      // (the body field path is the safe fallback until plan-DO gains header
+      // propagation in a follow-up phase).
+      const idempotencyKey = crypto.randomUUID();
+      // Multi-repo default: the SPA composer can't pass repoUrls[] (no picker),
+      // so inject the operator-configured multi-repo default for multi-repo
+      // worlds (atlas-core + diner-app). Only when the body carries neither a
+      // repoUrls[] nor a single repoUrl — explicit caller input always wins.
+      const dogfoodRepoUrls = readDogfoodRepoUrls();
+      // plan-chat-spa-attachments Phase A: `parsed.attachments` (a top-level
+      // AttachmentRef[] field — NEVER inside messages[].content) is forwarded
+      // UNTOUCHED to plan-DO. It rides through the `...parsed` spread chain
+      // below verbatim; it is NOT routed through the messages→prompt `.join`
+      // normalisation above (which would stringify a structured array — T1).
+      // Keep it on the enriched body if a future refactor narrows the spread.
       let enrichedObj = null;
       if (anthropicBaseUrl && !parsed.anthropicBaseUrl) enrichedObj = { ...(enrichedObj ?? parsed), anthropicBaseUrl };
-      if (dogfoodRepoUrl && !parsed.repoUrl) enrichedObj = { ...(enrichedObj ?? parsed), repoUrl: dogfoodRepoUrl };
+      if (
+        dogfoodRepoUrls.length > 0 &&
+        !(Array.isArray(parsed.repoUrls) && parsed.repoUrls.length > 0) &&
+        !parsed.repoUrl
+      ) {
+        enrichedObj = { ...(enrichedObj ?? parsed), repoUrls: dogfoodRepoUrls };
+      } else if (dogfoodRepoUrl && !parsed.repoUrl) {
+        enrichedObj = { ...(enrichedObj ?? parsed), repoUrl: dogfoodRepoUrl };
+      }
       if (kgProxyUrl && !parsed.kgProxyUrl) enrichedObj = { ...(enrichedObj ?? parsed), kgProxyUrl };
       if (kgProxyBearer && !parsed.kgProxyBearer) enrichedObj = { ...(enrichedObj ?? parsed), kgProxyBearer };
+      if (kgWorkspace && !parsed.kgWorkspace) enrichedObj = { ...(enrichedObj ?? parsed), kgWorkspace };
+      // Dynamic chunk-sink: forward the operator's remote (tunnel) host-cp URL
+      // so the CF-Sandbox runner streams chunks back to the host-cp the
+      // operator is watching (live SPA reasoning). body value wins if present.
+      const remoteHostCpUrl = readRemoteHostCpUrl();
+      if (remoteHostCpUrl && !parsed.hostCpUrl) enrichedObj = { ...(enrichedObj ?? parsed), hostCpUrl: remoteHostCpUrl };
+      // Host-cp-independent chunk sink: forward the public plan-DO URL so the
+      // runner posts chunks straight to plan-DO /v1/chunks → Neon → Electric →
+      // SPA (no host-cp in the chunk path). OLAM_CLOUD_URL is plan-DO's URL.
+      if (OLAM_CLOUD_URL && !parsed.chunksSinkUrl) enrichedObj = { ...(enrichedObj ?? parsed), chunksSinkUrl: OLAM_CLOUD_URL };
+      // Always inject idempotencyKey into the body so plan-DO forwards it to the
+      // runner even when the Idempotency-Key header is not propagated.
+      enrichedObj = { ...(enrichedObj ?? parsed), idempotencyKey };
       // Use `parsed` (not raw `body`) as the no-enrichment fallback so that the
       // messages→prompt normalisation above is always forwarded even when no
       // env-var enrichments are applied.
-      const enriched = enrichedObj ? JSON.stringify(enrichedObj) : JSON.stringify(parsed);
+      const enriched = JSON.stringify(enrichedObj);
 
       if (parsed.world_id && parsed.prompt) {
         safePersistLastDispatch({
@@ -2758,6 +3273,7 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
           headers: {
             'Authorization': `Basic ${basicAuth}`,
             'content-type': 'application/json',
+            'Idempotency-Key': idempotencyKey,
             ...cfAccessHeaders(),
           },
           body: enriched,
@@ -2776,6 +3292,14 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     }
   }
 
+  // (dispatch-cloud-burst /api/world/<id>/dispatch-cloud-burst is handled earlier,
+  // inside the /api/world/<id>/* block, BEFORE the WORLDS registry check — see above.
+  // The subPath check fires before the WORLDS lookup because cloud-burst does not
+  // require a locally-registered Docker world.)
+
+  // (SPA-driven UAT /api/world/<id>/uat[/status] is handled earlier, inside the
+  // /api/world/<id>/* block, BEFORE the docker per-world proxy — see above.)
+
   // /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
@@ -2808,9 +3332,18 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
       }
 
       // Enrich with anthropicBaseUrl + kgProxy from the host config.
-      const anthropicBaseUrl = readAnthropicBaseUrl();
-      const kgProxyUrl = readKgProxyUrl();
-      const kgProxyBearer = readKgProxyBearer();
+      // Note: plans/create always stamps host values (no !parsed.X guard) —
+      // plan-DO needs the authoritative bearer URL, not whatever the SPA sent.
+      // dogfoodRepoUrl is intentionally not forwarded here (plans/create is
+      // a bearer-registration call, not a coding-sandbox dispatch).
+      // kgWorkspace MUST travel with kgProxyUrl/kgProxyBearer: the worker-runner
+      // gates KG on `kgEnabled = Boolean(kgProxyUrl && kgWorkspace)`, and plan-DO
+      // forwards all three onto the sandbox spawn body (plan-agent.ts). Stamping
+      // only 2 of the 3 would send the bearer but leave KG disabled (or silently
+      // fall back to the runner's deploy-time workspace, not the authoritative
+      // host value) — the same drift the other two dispatch sites already avoid.
+      // readHostDispatchConfig() is TTL-cached — see its JSDoc.
+      const { anthropicBaseUrl, kgProxyUrl, kgProxyBearer, kgWorkspace } = readHostDispatchConfig();
       const planId = parsed.planId ?? parsed.session_id ?? `plan-${Date.now()}`;
       const requestBody = {
         ...parsed,
@@ -2818,6 +3351,7 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
         ...(anthropicBaseUrl ? { anthropicBaseUrl } : {}),
         ...(kgProxyUrl ? { kgProxyUrl } : {}),
         ...(kgProxyBearer ? { kgProxyBearer } : {}),
+        ...(kgWorkspace ? { kgWorkspace } : {}),
       };
 
       const basicAuth = Buffer.from(`operator:${showcasePw}`).toString('base64');
@@ -3615,6 +4149,18 @@ 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/');
+  // Idempotent injection: strip ANY pre-existing bearer / cloud-enabled
+  // bootstrap script before injecting fresh values. A built dist may carry a
+  // STALE baked `<script>window.__OLAM_PLAN_CHAT_BEARER__=...;window.__OLAM_CLOUD_ENABLED__=false;</script>`
+  // (a fixture stamped at build/stage time). Without stripping it, host-cp's
+  // freshly-injected `__OLAM_CLOUD_ENABLED__=true` is OVERRIDDEN by the stale
+  // `=false` that runs second in source order — silently force-disabling Cloud
+  // mode in the browser. Remove any such prior injection first so the
+  // server-resolved values are authoritative.
+  html = html.replace(
+    /<script>window\.__OLAM_(?:PLAN_CHAT_BEARER|CLOUD_ENABLED)__=[^<]*<\/script>/g,
+    '',
+  );
   // 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).
@@ -3937,6 +4483,20 @@ server.listen(PORT, '0.0.0.0', () => {
   } else if (hasShowcasePw && !hasCloudUrl) {
     console.warn('  [cloud] OLAM_SHOWCASE_PASSWORD set but OLAM_CLOUD_URL missing — cloud_enabled will be false');
   }
+
+  // D.1 — start operator-side long-poll after server is ready.
+  // Only when OLAM_OPSIDE_LONGPOLL=1. Requires OLAM_CLOUD_URL and auth.
+  // Default OFF — byte-for-byte no change when the flag is unset.
+  if (OLAM_OPSIDE_LONGPOLL) {
+    if (!OLAM_CLOUD_URL) {
+      console.warn('  [op-poll] OLAM_OPSIDE_LONGPOLL=1 but OLAM_CLOUD_URL is not set — long-poll disabled');
+    } else if (!OLAM_OPSIDE_LONGPOLL_AUTH) {
+      console.warn('  [op-poll] OLAM_OPSIDE_LONGPOLL=1 but OLAM_SHOWCASE_PASSWORD is not set — long-poll disabled (no auth)');
+    } else {
+      console.log(`  [op-poll] starting operator-side long-poll → ${OLAM_CLOUD_URL}/v1/op-poll`);
+      startPoll(OLAM_CLOUD_URL, OLAM_OPSIDE_LONGPOLL_AUTH);
+    }
+  }
 });
 
 // Graceful shutdown so docker compose down → SIGTERM → flush + close.
@@ -3945,6 +4505,8 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     console.log(`received ${sig}, shutting down`);
     stopEvents();
     prPoller.stop();
+    // D.1: stop the operator-side long-poll loop if it was started.
+    stopPoll();
     // worldsDbReconciler + worldActivityTracker + worldWatchdog are null in SERVE-ONLY mode.
     worldsDbReconciler?.stop();
     stopWorldsSnapshotLoop();