@pleri/olam-cli 0.1.188 → 0.1.196

package/host-cp/src/plan-chat-service.mjs

@@ -34,8 +34,18 @@ import { performance } from 'node:perf_hooks';
 import { Readable } from 'node:stream';
 import { URL } from 'node:url';
 import pg from 'pg';
+import { SCHEMA_SQL } from '@olam/chunks/schema';
 import { ensureSecret, timingSafeEqual, SECRET_PATH } from './plan-chat-secret.mjs';
-import { listPlanningSessions } from './planning-sessions.mjs';
+import {
+  listPlanningSessions,
+  createDispatchSession,
+  claimDispatchTurnLock,
+  clearDispatchTurnLock,
+  getDispatchSession,
+  haltDispatchSession,
+  reactivateDispatchSession,
+  listDispatchSessions,
+} from './planning-sessions.mjs';
 import { crystallizePlanningSession } from './crystallize-planning.mjs';
 import { resolveId, RESOLVE_ID_RE, createRateLimiter } from './resolver.mjs';
 
@@ -69,7 +79,10 @@ const SCOPE_ID_RE = /^[A-Za-z0-9_.-]+$/;
 // /v1/shape. Only these tables have server-side where-rewrite support; any
 // other table=... param gets a 400. Guards against a client enumerating
 // tables the service doesn't own.
-const ALLOWED_SHAPE_TABLES = new Set(['chunks', 'message_usage', 'planning_artifacts']);
+// planning_sessions added in Phase C C-S1 so useDispatchSessions can subscribe
+// via Electric long-poll. The handleGetShape `where` rewriter uses world_id +
+// session_id; planning_sessions rows carry world_id (added in Phase A A1).
+const ALLOWED_SHAPE_TABLES = new Set(['chunks', 'message_usage', 'planning_artifacts', 'planning_sessions']);
 
 // B6 (plan-chat-context-window-display Phase B): context-window caps per
 // model. Mirrors CONTEXT_CAPS from @olam/intelligence/src/llm-router/providers/claude.ts.
@@ -275,6 +288,12 @@ export function createHandler({
    * or inspect the idempotency store. Production callers omit this.
    */
   _promoteDedupe: promoteDedupe = _promoteDedupe,
+  /** multi-turn-cloud-sandbox-dispatch Phase A3 — optional override for tests.
+   *  When supplied, replaces the default plan-DO forward path so tests can
+   *  inject a stub returning a fake sandbox_session_id without exercising the
+   *  real cloud-dispatch path. Production callers omit; A6 wires the real
+   *  forward. */
+  dispatchTurnForward,
 }) {
   if (!pool) throw new Error('createHandler: { pool } required');
   if (typeof bearer !== 'string' || bearer.length === 0) {
@@ -297,6 +316,90 @@ export function createHandler({
   // through ids at line-rate without the bucket).
   const resolveLimiter = rateLimiter ?? createRateLimiter({ capacity: 60, windowMs: 60_000 });
 
+  /**
+   * Default plan-DO forward — used by handlePostDispatchTurn when no
+   * test-injected stub is provided.
+   *
+   * Phase B follow-up (operator E2E directive 2026-05-27: full SPA→plan-DO→CF
+   * chain test): when OLAM_CLOUD_URL + OLAM_SHOWCASE_PASSWORD are set, this
+   * function POSTs the turn payload to plan-DO at
+   * `${OLAM_CLOUD_URL}/v1/dispatch?plan_id=<session_id>` with showcase Basic
+   * auth (mirrors server.mjs /api/cloud-dispatch's existing forward shape).
+   * Plan-DO then spawns the CF Sandbox container; chunks flow back to host-cp
+   * via the cloudflared tunnel + the in-container chunk-poster pattern
+   * (PR #1165 substrate).
+   *
+   * When the envs are absent (typical for unit-test setups), the function
+   * throws — operators MUST set both envs to enable real CF dispatch. The
+   * existing `dispatchTurnForward` opt remains available for tests that
+   * want to inject a stub returning a fake sandbox_session_id.
+   *
+   * @param {object} ctx
+   * @param {{ session_id: string, world_id: string|null, actor_id: string }} ctx.session
+   * @param {string} ctx.turn_id
+   * @param {string} ctx.prompt
+   * @param {string} ctx.conversation_preamble — Phase B fills this; empty in Phase A
+   * @returns {Promise<{ sandbox_session_id: string | null }>}
+   */
+  async function defaultDispatchTurnForward(ctx) {
+    const cloudUrl = process.env.OLAM_CLOUD_URL;
+    const showcasePw = process.env.OLAM_SHOWCASE_PASSWORD;
+    if (!cloudUrl || !showcasePw) {
+      throw new Error(
+        'dispatch-turn forward not wired: set OLAM_CLOUD_URL + OLAM_SHOWCASE_PASSWORD ' +
+          'env vars (see /api/cloud-dispatch pattern in server.mjs) OR inject ' +
+          '`dispatchTurnForward` via createHandler() opts for test stubs.',
+      );
+    }
+    const planId = ctx.session.session_id;
+    const basicAuth = Buffer.from(`operator:${showcasePw}`).toString('base64');
+    // Mirror /api/cloud-dispatch's enriched body: include the operator's
+    // anthropicBaseUrl (so spawned CF Sandbox child worlds can reach the
+    // auth-Worker), the operator's repoUrl (for the in-container clone),
+    // plus the new multi-turn fields (turn_id, conversation_preamble).
+    // anthropicBaseUrl + repoUrl are read from ~/.olam/* by the existing
+    // host-cp pattern; here we just forward whatever the SPA passed (the
+    // SPA may have included them) — and rely on plan-DO's own enrichment
+    // for absent fields.
+    const body = JSON.stringify({
+      world_id: ctx.session.world_id,
+      session_id: ctx.session.session_id,
+      actor_id: ctx.session.actor_id,
+      turn_id: ctx.turn_id,
+      prompt: ctx.prompt,
+      conversation_preamble: ctx.conversation_preamble ?? '',
+    });
+    const upstream = await fetch(
+      `${cloudUrl.replace(/\/+$/, '')}/v1/dispatch?plan_id=${encodeURIComponent(planId)}`,
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': `Basic ${basicAuth}`,
+          'content-type': 'application/json',
+        },
+        body,
+      },
+    );
+    if (!upstream.ok) {
+      const errBody = await upstream.text().catch(() => '');
+      throw new Error(
+        `plan-DO /v1/dispatch returned ${upstream.status}: ${errBody.slice(0, 200)}`,
+      );
+    }
+    // plan-DO returns { sandbox_session_id, ... } on success per PR #1165
+    // (see packages/plan-agent-do/src/dispatch-sandbox-agent.ts). We pluck
+    // sandbox_session_id for the SPA's session-thread render; everything
+    // else flows back via the in-container chunk-poster → host-cp
+    // /api/plan-chat/v1/chunks path (NOT through this return).
+    let parsed;
+    try {
+      parsed = await upstream.json();
+    } catch {
+      parsed = {};
+    }
+    return { sandbox_session_id: parsed.sandbox_session_id ?? null };
+  }
+
   function checkAuth(req) {
     const header = req.headers.authorization;
     if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
@@ -545,12 +648,23 @@ export function createHandler({
         'world_id query param required (alphanumerics + _ - . only)',
       );
     }
-    if (!sessionId || !SCOPE_ID_RE.test(sessionId)) {
+    // Phase C C-S1 — planning_sessions shapes are scoped by world_id only
+    // (no session_id; the hook fetches all dispatch sessions for a world).
+    // All other tables require session_id for the (session_id, world_id)
+    // predicate that guards per-session Electric cache isolation.
+    const requiresSessionId = tableParam !== 'planning_sessions';
+    if (requiresSessionId && (!sessionId || !SCOPE_ID_RE.test(sessionId))) {
       return badRequest(
         res,
         'session_id query param required (alphanumerics + _ - . only)',
       );
     }
+    if (sessionId && !SCOPE_ID_RE.test(sessionId)) {
+      return badRequest(
+        res,
+        'session_id query param must match alphanumerics + _ - . only',
+      );
+    }
 
     // Forward all client query params EXCEPT the scoped set. Client-supplied
     // `where` is silently dropped — server-derived `where` always wins.
@@ -566,14 +680,14 @@ export function createHandler({
     // PB2 — server-derived `where` clause; safe because SCOPE_ID_RE has
     // already rejected single-quotes, semicolons, and SQL meta-characters.
     //
-    // Predicate order: session_id FIRST. Electric SQL caches shapes by the
-    // exact predicate string; flipping the original (world_id, session_id)
-    // order forces a fresh shape and avoids a known cache-staleness bug
-    // where an empty-result shape persists after new rows land.
-    upstream.searchParams.set(
-      'where',
-      `session_id='${sessionId}' AND world_id='${worldId}'`,
-    );
+    // planning_sessions: world_id only (no per-session scope needed).
+    // All other tables: session_id FIRST per Electric cache-isolation rule
+    // (flipping order forces a fresh shape and avoids a known cache-staleness
+    // bug where an empty-result shape persists after new rows land).
+    const whereClause = requiresSessionId
+      ? `session_id='${sessionId}' AND world_id='${worldId}'`
+      : `world_id='${worldId}'`;
+    upstream.searchParams.set('where', whereClause);
 
     // Phase A A2 — log BEFORE upstream fetch. Includes the rewritten
     // `where` predicate so an operator can correlate client-supplied
@@ -682,6 +796,302 @@ export function createHandler({
     }
   }
 
+  /**
+   * POST /v1/sessions/create — multi-turn dispatch session bootstrap
+   * (multi-turn-cloud-sandbox-dispatch Phase A2).
+   *
+   * Body shape:
+   *   {
+   *     world_id: string,               // required — target dispatch world
+   *     budget_usd_cap?: number | null, // optional — per-session budget cap; null = uncapped
+   *     allow_unpriced_models?: boolean // optional — opt session into the
+   *                                     //  pricingForModel-returns-null fallback
+   *                                     //  (Plan A T11); default false (refuse unknown
+   *                                     //  models with 502 at /v1/dispatch-turn time).
+   *   }
+   *
+   * Returns 200 { session_id: uuid }.
+   *
+   * Auth: plan-chat-secret Bearer (same gate as /v1/chunks + /v1/shape).
+   * actor_id is derived from the bearer principal (single-tenant v1; multi-tenant
+   * scoping is the cloud-spa-tenant-scoping plan's surface, NOT this endpoint's).
+   */
+  async function handlePostSessionsCreate(req, res) {
+    if (!checkAuth(req)) return unauthorized(res);
+    let body;
+    try {
+      body = await readJson(req);
+    } catch (err) {
+      return send(res, err?.status ?? 400, { error: err?.message ?? 'bad-request' });
+    }
+    if (!body || typeof body.world_id !== 'string' || body.world_id.length === 0) {
+      return badRequest(res, 'world_id required');
+    }
+    const principal = principalFromBearer(bearer, body);
+    const budgetUsdCap =
+      typeof body.budget_usd_cap === 'number' && Number.isFinite(body.budget_usd_cap)
+        ? body.budget_usd_cap
+        : null;
+    const allowUnpricedModels = body.allow_unpriced_models === true;
+    // A6 (Decision 9 always-on threading): host-cp's /api/cloud-dispatch
+    // pre-creates the planning_sessions row using the dispatch's session_id.
+    // The SPA may also call /v1/sessions/create directly; ON CONFLICT
+    // DO NOTHING in createDispatchSession handles both shapes.
+    const providedSessionId =
+      typeof body.session_id === 'string' && body.session_id.length > 0
+        ? body.session_id
+        : null;
+    try {
+      const result = await createDispatchSession({
+        pool,
+        actorId: principal.actorId,
+        worldId: body.world_id,
+        budgetUsdCap,
+        allowUnpricedModels,
+        sessionId: providedSessionId,
+      });
+      return send(res, 200, result);
+    } catch (err) {
+      return send(res, 500, {
+        error: 'create-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+  }
+
+  /**
+   * POST /v1/dispatch-turn — multi-turn dispatch turn entry-point
+   * (multi-turn-cloud-sandbox-dispatch Phase A3 — load-bearing seam).
+   *
+   * Body shape:
+   *   {
+   *     session_id: string,                  // required — existing dispatch session
+   *     prompt: string,                      // required — operator's prompt for this turn
+   *   }
+   *
+   * Returns:
+   *   - 200 { turn_id, sandbox_session_id } — turn dispatched; agent runtime
+   *           streams chunks to /v1/chunks under (world_id, session_id).
+   *   - 401 — bearer missing/wrong.
+   *   - 400 — body invalid (missing session_id / prompt).
+   *   - 404 — session not found OR not owned by caller (ownership check via actor_id).
+   *   - 409 — in_flight_turn_id lock already held (concurrent dispatch).
+   *   - 402 — budget_usd_cap exhausted; clear cap or halt to retry.
+   *   - 502 — Phase D unknown-model guard fires (model pricing returned null
+   *           AND session has allow_unpriced_models=false).
+   *
+   * Phase A3 SCOPE (this commit):
+   *   - Atomic lock claim via UPDATE...WHERE in_flight_turn_id IS NULL RETURNING.
+   *   - Budget cap check via getDispatchSession.total_usd vs budget_usd_cap.
+   *   - Preamble construction STUBBED (Phase B fills the prior-conversation envelope).
+   *   - plan-DO forward STUBBED via injectable `dispatchTurnForward` callback
+   *     (test stubs return a fake sandbox_session_id; production wires to plan-DO).
+   *   - 502 unknown-model guard STUBBED (Phase D wires real pricingForModel check).
+   *
+   * Phase B-D layers on:
+   *   - Phase B: replace preamble stub with `<prior-conversation>` envelope
+   *     constructed from chunks (host-cp owns rehydration per Decision 6).
+   *   - Phase D: replace 502 stub with real pricingForModel fail-loud guard.
+   *   - Phase D: implement total_usd atomic UPDATE on chunk-land + stale-lock cron.
+   */
+  async function handlePostDispatchTurn(req, res) {
+    if (!checkAuth(req)) return unauthorized(res);
+    let body;
+    try {
+      body = await readJson(req);
+    } catch (err) {
+      return send(res, err?.status ?? 400, { error: err?.message ?? 'bad-request' });
+    }
+    if (!body || typeof body.session_id !== 'string' || body.session_id.length === 0) {
+      return badRequest(res, 'session_id required');
+    }
+    if (typeof body.prompt !== 'string' || body.prompt.length === 0) {
+      return badRequest(res, 'prompt required');
+    }
+    const principal = principalFromBearer(bearer, body);
+
+    // Ownership check: session must exist AND belong to caller.
+    let session;
+    try {
+      session = await getDispatchSession({
+        pool,
+        sessionId: body.session_id,
+        actorId: principal.actorId,
+      });
+    } catch (err) {
+      return send(res, 500, {
+        error: 'session-lookup-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+    if (!session) {
+      return send(res, 404, { error: 'session_not_found' });
+    }
+
+    // Halted check (A4) — operator's "block next turn" state takes precedence
+    // over budget + lock checks because it's an explicit operator pause. The
+    // running container is NOT signalled (T13); only future turns are blocked.
+    if (session.halted_at) {
+      return send(res, 409, {
+        error: 'session_halted',
+        session_id: body.session_id,
+        halted_at: session.halted_at,
+      });
+    }
+
+    // Budget cap check (Phase D layers on the unknown-model guard).
+    if (
+      session.budget_usd_cap !== null &&
+      Number.isFinite(session.budget_usd_cap) &&
+      session.total_usd >= session.budget_usd_cap
+    ) {
+      return send(res, 402, {
+        error: 'budget_exhausted',
+        total_usd: session.total_usd,
+        budget_usd_cap: session.budget_usd_cap,
+      });
+    }
+
+    // Atomic lock claim — second concurrent attempt sees empty result.
+    const turnId = `turn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let claimed;
+    try {
+      claimed = await claimDispatchTurnLock({
+        pool,
+        sessionId: body.session_id,
+        turnId,
+      });
+    } catch (err) {
+      return send(res, 500, {
+        error: 'lock-claim-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+    if (!claimed) {
+      return send(res, 409, { error: 'in_flight', session_id: body.session_id });
+    }
+
+    // Forward to plan-DO (stubbed via injected callback for tests; production
+    // implementation lands when /api/cloud-dispatch is refactored to share the
+    // forward path — A6 work).
+    try {
+      const forward = dispatchTurnForward ?? defaultDispatchTurnForward;
+      const result = await forward({
+        session: {
+          session_id: session.session_id,
+          world_id: session.world_id,
+          actor_id: session.actor_id,
+        },
+        turn_id: turnId,
+        prompt: body.prompt,
+        // Phase B fills preamble with conversation history from chunks.
+        conversation_preamble: '',
+      });
+      return send(res, 200, {
+        turn_id: turnId,
+        sandbox_session_id: result.sandbox_session_id ?? null,
+      });
+    } catch (err) {
+      // Forward failed — clear the lock so the operator can retry.
+      try {
+        await clearDispatchTurnLock({ pool, sessionId: body.session_id });
+      } catch { /* logged separately */ }
+      return send(res, 502, {
+        error: 'dispatch_forward_failed',
+        message: String(err?.message ?? err),
+      });
+    }
+  }
+
+  /**
+   * GET /v1/sessions — list multi-turn dispatch sessions for the caller
+   * (multi-turn-cloud-sandbox-dispatch Phase A5).
+   *
+   * Scoped to actor_id (single-tenant ownership isolation; cloud-spa-tenant-scoping
+   * adds Neon RLS as defense-in-depth). Returns dispatch sessions only
+   * (session_type='dispatch'), excluding archived rows, ordered by last_turn_at
+   * DESC (most recently active first) then created_at DESC as tiebreaker.
+   *
+   * Query params:
+   *   ?limit=<N>  — capped at 200; default 50.
+   *
+   * Response: 200 { sessions: [...] }
+   *
+   * Auth: plan-chat-secret Bearer. NO body (GET).
+   */
+  async function handleGetSessions(req, res, url) {
+    if (!checkAuth(req)) return unauthorized(res);
+    const principal = principalFromBearer(bearer, null);
+    const limitParam = url.searchParams.get('limit');
+    const limit = limitParam ? Math.min(parseInt(limitParam, 10) || 50, 200) : 50;
+    try {
+      const sessions = await listDispatchSessions({ pool, actorId: principal.actorId, limit });
+      return send(res, 200, { sessions });
+    } catch (err) {
+      return send(res, 500, {
+        error: 'list-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+  }
+
+  /**
+   * POST /v1/sessions/:id/halt — operator-driven "block next turn"
+   * (multi-turn-cloud-sandbox-dispatch Phase A4 + T13).
+   *
+   * Clears in_flight_turn_id (releases the lock if held) AND sets halted_at.
+   * Future /v1/dispatch-turn calls return 409 'session_halted' until
+   * /v1/sessions/:id/reactivate clears halted_at.
+   *
+   * Does NOT stop an in-flight container. The running container completes
+   * its current turn naturally; only NEXT turns are blocked. UX must label
+   * the halt button "Block next turn" (Plan A Phase C C6).
+   *
+   * Auth: plan-chat-secret Bearer. Ownership via actor_id.
+   * Returns 200 { halted: true } | 404 session_not_found | 401 | 500.
+   */
+  async function handlePostSessionHalt(req, res, sessionId) {
+    if (!checkAuth(req)) return unauthorized(res);
+    const principal = principalFromBearer(bearer, null);
+    try {
+      const halted = await haltDispatchSession({
+        pool,
+        sessionId,
+        actorId: principal.actorId,
+      });
+      if (!halted) return send(res, 404, { error: 'session_not_found' });
+      return send(res, 200, { halted: true, session_id: sessionId });
+    } catch (err) {
+      return send(res, 500, {
+        error: 'halt-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+  }
+
+  /**
+   * POST /v1/sessions/:id/reactivate — inverse of halt; clears halted_at
+   * so subsequent dispatch turns can proceed. Idempotent.
+   */
+  async function handlePostSessionReactivate(req, res, sessionId) {
+    if (!checkAuth(req)) return unauthorized(res);
+    const principal = principalFromBearer(bearer, null);
+    try {
+      const reactivated = await reactivateDispatchSession({
+        pool,
+        sessionId,
+        actorId: principal.actorId,
+      });
+      if (!reactivated) return send(res, 404, { error: 'session_not_found' });
+      return send(res, 200, { reactivated: true, session_id: sessionId });
+    } catch (err) {
+      return send(res, 500, {
+        error: 'reactivate-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+  }
+
   async function handleGetPlanningSessions(req, res, url) {
     if (!checkAuth(req)) return unauthorized(res);
     // Derive actorId from the bearer principal (no body on GET).
@@ -1039,12 +1449,56 @@ export function createHandler({
     return send(res, 202, { worldId, promoteId, specPath, status: 'dispatched' });
   }
 
+  // multi-turn-cloud-sandbox-dispatch A7 follow-up (operator E2E directive
+  // 2026-05-27): the SPA at http://127.0.0.1:19000 talks to plan-chat-service
+  // at http://127.0.0.1:3200 — different origins → browser preflight required.
+  // Allow-list controlled via OLAM_PLAN_CHAT_CORS_ORIGINS env (comma-separated).
+  // Default includes the local SPA dev port; production deployments override.
+  // Surfaced by the webwright spec which the .mjs Playwright spec did NOT
+  // catch (page.evaluate fetch ≠ server-to-server fetch).
+  const corsOrigins = (
+    process.env.OLAM_PLAN_CHAT_CORS_ORIGINS ?? 'http://127.0.0.1:19000,http://localhost:19000'
+  ).split(',').map((o) => o.trim()).filter(Boolean);
+
+  function applyCorsHeaders(req, res) {
+    const origin = req.headers.origin;
+    if (typeof origin === 'string' && corsOrigins.includes(origin)) {
+      res.setHeader('access-control-allow-origin', origin);
+      res.setHeader('vary', 'origin');
+      res.setHeader('access-control-allow-credentials', 'true');
+      res.setHeader('access-control-allow-methods', 'GET, POST, OPTIONS');
+      res.setHeader('access-control-allow-headers', 'authorization, content-type');
+      res.setHeader('access-control-max-age', '600');
+    }
+  }
+
   return async function handler(req, res) {
     const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+    applyCorsHeaders(req, res);
+    // CORS preflight — short-circuit OPTIONS for allow-listed origins.
+    if (req.method === 'OPTIONS') {
+      const origin = req.headers.origin;
+      if (typeof origin === 'string' && corsOrigins.includes(origin)) {
+        res.statusCode = 204;
+        return res.end();
+      }
+      // Not allowlisted — fall through to 404 (default not-found shape).
+    }
     if (req.method === 'GET' && url.pathname === '/livez') return send(res, 200, { ok: true });
     if (req.method === 'POST' && url.pathname === '/v1/chunks') return handlePostChunks(req, res);
     if (req.method === 'GET' && url.pathname === '/v1/shape') return handleGetShape(req, res, url);
     if (req.method === 'GET' && url.pathname === '/v1/planning-sessions') return handleGetPlanningSessions(req, res, url);
+    if (req.method === 'POST' && url.pathname === '/v1/sessions/create') return handlePostSessionsCreate(req, res);
+    if (req.method === 'GET' && url.pathname === '/v1/sessions') return handleGetSessions(req, res, url);
+    if (req.method === 'POST' && url.pathname === '/v1/dispatch-turn') return handlePostDispatchTurn(req, res);
+    const haltMatch = /^\/v1\/sessions\/([^/]+)\/halt$/.exec(url.pathname);
+    if (haltMatch && req.method === 'POST') {
+      return handlePostSessionHalt(req, res, decodeURIComponent(haltMatch[1]));
+    }
+    const reactivateMatch = /^\/v1\/sessions\/([^/]+)\/reactivate$/.exec(url.pathname);
+    if (reactivateMatch && req.method === 'POST') {
+      return handlePostSessionReactivate(req, res, decodeURIComponent(reactivateMatch[1]));
+    }
     if (req.method === 'POST' && url.pathname === '/v1/crystallize') return handlePostCrystallize(req, res);
     // Phase A A1 — /v1/resolve/:id (plan-chat-spa-supersedes-control-plane).
     const resolveMatch = /^\/v1\/resolve\/([^/]+)$/.exec(url.pathname);
@@ -1095,6 +1549,33 @@ export async function startService(opts = {}) {
   const bearer = opts.bearer ?? ensureSecret(secretPath);
 
   const pool = opts.pool ?? new pg.Pool({ connectionString: databaseUrl, max: 8 });
+
+  // multi-turn-cloud-sandbox-dispatch A7 follow-up (operator E2E directive
+  // 2026-05-27): apply SCHEMA_SQL on boot so a fresh local dev stack picks
+  // up A1+A4 migrations (planning_sessions session_type / world_id /
+  // halted_at / etc.) automatically. Skipped when opts.pool was supplied
+  // (test pool stubs don't run real SQL); skipped when OLAM_PLAN_CHAT_SKIP_SCHEMA
+  // is set (operator escape hatch for managed-DB environments where the
+  // app shouldn't apply DDL). Webwright E2E surfaced this gap: the API-only
+  // tests pass against a stubbed pool, but a real-Neon dev stack hit
+  // `column "session_type" of relation "planning_sessions" does not exist`
+  // until SCHEMA_SQL was applied manually.
+  if (!opts.pool && process.env.OLAM_PLAN_CHAT_SKIP_SCHEMA !== '1') {
+    try {
+      await pool.query(SCHEMA_SQL);
+      // eslint-disable-next-line no-console
+      console.error('[plan-chat-service] SCHEMA_SQL applied on boot');
+    } catch (schemaErr) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[plan-chat-service] SCHEMA_SQL apply FAILED on boot: ${schemaErr?.message ?? schemaErr}`,
+      );
+      // Don't crash the service — schema may already be applied externally
+      // (e.g. CI managed DB). Fail-soft + log; the operator's first POST
+      // will surface the column-missing error if the schema really is stale.
+    }
+  }
+
   const handler = createHandler({
     pool,
     bearer,
@@ -1107,6 +1588,7 @@ export async function startService(opts = {}) {
     resolveActor: opts.resolveActor,
     rateLimiter: opts.rateLimiter,
     _promoteDedupe: opts._promoteDedupe,
+    dispatchTurnForward: opts.dispatchTurnForward,
   });
   const server = http.createServer((req, res) => {
     handler(req, res).catch((err) => {