@pleri/olam-cli 0.1.186 → 0.1.195

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.
@@ -219,6 +232,17 @@ function validateChunkInput(body) {
   return null;
 }
 
+// P1 — promote idempotency window. Keyed by chunk_id; value is
+// { worldId, specPath, promoteId, createdAt }. Entries expire after
+// PROMOTE_DEDUPE_TTL_MS so a genuine re-promote (after operator intent)
+// is allowed rather than silently re-routing to the original world.
+// In-memory only: a process restart clears the map. For v1 this is
+// sufficient — the same Linear-retry window (seconds) is far shorter
+// than the TTL (30s). Persistent dedup (across restarts / multi-replica)
+// is deferred to U2.
+const PROMOTE_DEDUPE_TTL_MS = 30_000;
+const _promoteDedupe = new Map(); // chunk_id → { worldId, specPath, promoteId, createdAt }
+
 /**
  * Build the HTTP request handler. Pure factory — easy to test against a
  * stubbed pool. Production callers pass a real pg.Pool.
@@ -240,6 +264,17 @@ export function createHandler({
   shapeDebugLog,
   createWorld,
   destroyWorld,
+  /**
+   * P1 — injectable dispatchTask callback. Accepts { worldId, containerName,
+   * task, tier } and dispatches the task to the newly-created world.
+   * Production callers wire in autoDispatchTask from @olam/core; tests inject
+   * a stub. When omitted, the promote endpoint returns 501.
+   *
+   * Tier routing: the caller is responsible for reading compute.default
+   * from the workspace config and passing it as opts.tier when applicable.
+   * This keeps plan-chat-service free from workspace-config coupling.
+   */
+  dispatchTask,
   /** B4 — optional override for tests. When supplied, replaces principalFromBearer
    *  so the test harness can inject a hardcoded server-resolved actor_id and verify
    *  the mismatch guard. Production callers omit this. */
@@ -248,6 +283,17 @@ export function createHandler({
    *  default per-bearer rate limiter (60 req/min). Tests inject a stub with
    *  lower capacity to exercise the 429 path quickly. Production callers omit. */
   rateLimiter,
+  /**
+   * P1 — override the dedupe map for tests. Allows tests to pre-populate
+   * 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) {
@@ -270,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;
@@ -518,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.
@@ -539,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
@@ -655,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).
@@ -837,12 +1274,231 @@ export function createHandler({
     }
   }
 
+  // P1 — POST /v1/prototypes/:id/promote
+  //
+  // Accepts a prototype chunk_id in the URL path. Validates the chunk exists
+  // and is a prototype-shaped tool_use chunk, then dispatches a docker world
+  // to implement it. Returns 202 Accepted with { worldId, promoteId, specPath }
+  // before the docker world finishes booting (the boot is async).
+  //
+  // Idempotency: same chunk_id within PROMOTE_DEDUPE_TTL_MS returns
+  // 202 { action: "deduplicated", worldId } without creating a second world.
+  // Rationale: Linear retries on non-2xx; a 409 would trigger infinite retries.
+  // 202 + action body is the correct idempotent-promote semantic.
+  //
+  // Tier routing: the injected `dispatchTask` callback owns tier selection.
+  // The caller (production: WorldManager glue in server.mjs) passes the
+  // workspace's `compute.default` tier as part of the dispatchTask closure.
+  // This keeps plan-chat-service free from workspace config coupling.
+  async function handlePostPrototypePromote(req, res, chunkId) {
+    if (!checkAuth(req)) return unauthorized(res);
+
+    // createWorld + dispatchTask must both be wired. If either is absent,
+    // surface a clear 501 rather than crashing (mirrors crystallize guard).
+    if (typeof createWorld !== 'function' || typeof dispatchTask !== 'function') {
+      return send(res, 501, {
+        error: 'promote-not-wired',
+        message: 'createWorld and dispatchTask callbacks are required',
+      });
+    }
+
+    // Idempotency: check dedupe map before any DB reads.
+    const now = Date.now();
+    const existing = promoteDedupe.get(chunkId);
+    if (existing && now - existing.createdAt < PROMOTE_DEDUPE_TTL_MS) {
+      return send(res, 202, {
+        action: 'deduplicated',
+        worldId: existing.worldId,
+        promoteId: existing.promoteId,
+        specPath: existing.specPath,
+      });
+    }
+
+    // Parse optional body { targetWorldName?, specName? }
+    let body = {};
+    try {
+      body = await readJson(req);
+    } catch (err) {
+      return send(res, err?.status ?? 400, { error: err?.message ?? 'bad-request' });
+    }
+
+    // Look up the chunk by id in the chunks table.
+    let chunk;
+    try {
+      const result = await pool.query(
+        `SELECT world_id, session_id, message_id, seq, actor_id, actor_type,
+                role, chunk, chunk_type
+           FROM chunks WHERE message_id = $1
+           LIMIT 1`,
+        [chunkId],
+      );
+      chunk = result.rows[0] ?? null;
+    } catch (err) {
+      return send(res, 500, {
+        error: 'query-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+
+    if (!chunk) {
+      return send(res, 404, {
+        error: 'chunk-not-found',
+        message: `No chunk found with id '${chunkId}'`,
+      });
+    }
+
+    // Validate: must be a tool_use chunk with a prototype-shaped name.
+    if (chunk.chunk_type !== 'tool_use') {
+      return send(res, 400, {
+        error: 'invalid-chunk-type',
+        message: `chunk must have chunk_type='tool_use', got '${chunk.chunk_type}'`,
+      });
+    }
+
+    let parsedChunk;
+    try {
+      parsedChunk = JSON.parse(chunk.chunk);
+    } catch {
+      return send(res, 400, {
+        error: 'invalid-chunk-json',
+        message: 'chunk content is not valid JSON',
+      });
+    }
+
+    const toolName = typeof parsedChunk?.name === 'string' ? parsedChunk.name : '';
+    if (!toolName.includes('prototype')) {
+      return send(res, 400, {
+        error: 'not-a-prototype-chunk',
+        message: `chunk tool name '${toolName}' does not match prototype shape (name must include 'prototype')`,
+      });
+    }
+
+    // Derive world name and spec path from the chunk's input.
+    const input = parsedChunk.input ?? {};
+    const rawTitle =
+      (typeof body.specName === 'string' && body.specName.length > 0
+        ? body.specName
+        : typeof input.title === 'string' && input.title.length > 0
+          ? input.title
+          : 'prototype')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40) || 'prototype';
+
+    const worldName =
+      typeof body.targetWorldName === 'string' && body.targetWorldName.length > 0
+        ? body.targetWorldName
+        : `proto-${rawTitle}`;
+
+    const specPath = `design-specs/${rawTitle}-v1.spec.html`;
+    const specSource =
+      typeof input.source === 'string' ? input.source : JSON.stringify(input);
+
+    // Build the dispatch prompt: embed the spec source + instruct the agent
+    // to write it at specPath on first tool use. Per D3: the agent inside
+    // the world writes the file — host-cp does not need docker mount access.
+    const dispatchPrompt = [
+      `## Prototype implementation task`,
+      ``,
+      `A prototype has been promoted for implementation. Write the spec file`,
+      `at \`${specPath}\` as your first action, then implement it production-ready.`,
+      ``,
+      `### Spec source (write verbatim to ${specPath})`,
+      ``,
+      `\`\`\`html`,
+      specSource,
+      `\`\`\``,
+      ``,
+      `After writing the spec file, implement it fully — components, styles,`,
+      `tests, and documentation. The spec is the source of truth.`,
+      `If a file already exists at \`${specPath}\`, surface a conflict chunk`,
+      `to the operator before overwriting (per D4 of the promote endpoint plan).`,
+    ].join('\n');
+
+    // Create the world.
+    let worldId;
+    try {
+      const world = await createWorld({ name: worldName });
+      worldId = world.id;
+    } catch (err) {
+      return send(res, 500, {
+        error: 'world-creation-failed',
+        message: String(err?.message ?? err),
+      });
+    }
+
+    // Dispatch the task to the new world.
+    try {
+      await dispatchTask({ worldId, task: dispatchPrompt });
+    } catch (err) {
+      // The world was created but dispatch failed. Surface 502 so the caller
+      // can retry dispatch manually via `olam dispatch <id> "<task>"`.
+      return send(res, 502, {
+        error: 'dispatch-failed',
+        worldId,
+        message: String(err?.message ?? err),
+      });
+    }
+
+    const promoteId = `promote-${chunkId}-${worldId}`;
+
+    // Record in dedupe map before returning.
+    promoteDedupe.set(chunkId, { worldId, specPath, promoteId, createdAt: now });
+
+    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);
@@ -859,6 +1515,16 @@ export function createHandler({
       if (req.method === 'PATCH') return handlePatchArtifact(req, res, id);
       return send(res, 405, { error: 'method-not-allowed' });
     }
+
+    // P1 — /v1/prototypes/:id/promote
+    // startsWith + endsWith guard prevents shadowing a future /v1/prototypes
+    // GET list route (per risk note in the plan). The match is exact.
+    const promoteMatch = /^\/v1\/prototypes\/([^/]+)\/promote$/.exec(url.pathname);
+    if (promoteMatch && req.method === 'POST') {
+      const chunkId = decodeURIComponent(promoteMatch[1]);
+      return handlePostPrototypePromote(req, res, chunkId);
+    }
+
     return send(res, 404, { error: 'not-found' });
   };
 }
@@ -883,14 +1549,46 @@ 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,
     electricUrl,
     shapeDebug: opts.shapeDebug,
     shapeDebugLog: opts.shapeDebugLog,
+    createWorld: opts.createWorld,
+    destroyWorld: opts.destroyWorld,
+    dispatchTask: opts.dispatchTask,
     resolveActor: opts.resolveActor,
     rateLimiter: opts.rateLimiter,
+    _promoteDedupe: opts._promoteDedupe,
+    dispatchTurnForward: opts.dispatchTurnForward,
   });
   const server = http.createServer((req, res) => {
     handler(req, res).catch((err) => {