@pleri/olam-cli 0.1.158 → 0.1.160

package/host-cp/src/crystallize-planning.mjs

@@ -0,0 +1,261 @@
+// crystallize-planning — atomic-or-compensating chunk-copy from a planning
+// session (_planning world) into a freshly provisioned real world.
+//
+// APPEND-ONLY CONSTRAINT: The chunks table has a NO_DELETE + NO_UPDATE
+// trigger (chunks_append_only_trigger). If chunk-copy fails mid-batch,
+// any chunks already INSERTed under the new worldId STAY in the database.
+// Compensating cleanup only calls destroyWorld (world container teardown) —
+// it CANNOT delete the orphaned chunks. Those orphan chunks are harmless:
+//   • idx_chunks_planning only covers world_id='_planning' rows.
+//   • The destroyed world container no longer exists, so no subscriber
+//     will ever observe those orphans through the normal shape proxy.
+//   • Any future re-crystallize creates a fresh worldId, fresh session_id.
+//
+// IDEMPOTENCY:
+//   • If crystallize_status is 'crystallized' (with a stored worldId),
+//     return immediately — the work is already done.
+//   • If crystallize_status is 'in_progress', we cannot safely resume
+//     (we don't know how far the previous copy got, and the chunk INSERT
+//     is not idempotent by worldId+sessionId alone — the PRIMARY KEY is
+//     (message_id, seq), so the same chunk could be re-inserted into a
+//     different new session without collision). Safe behavior: return
+//     the current status so the UI can display "in progress" and the
+//     operator can force-retry after manual inspection.
+//
+// SLUG RULE: lowercased, non-alphanum → hyphens, max 40 chars.
+// Matches the dev-substrate stub in plan-chat-spa/src/server/index.ts
+// (confirmed by reading that file's crystallize stub, around line 983).
+
+import { randomUUID } from 'node:crypto';
+import { PLANNING_WORLD_ID } from '@olam/chunks/schema';
+import { setCrystallizeStatus } from './planning-sessions.mjs';
+
+/**
+ * Slug a plan title into a world-name-safe string.
+ * Lowercased, non-alphanum → hyphens, max 40 chars, leading/trailing
+ * hyphens removed. Falls back to 'plan' if result is empty.
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+function slugTitle(title) {
+  const base = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return base || 'plan';
+}
+
+/**
+ * Read the current crystallize_status + crystallized_world_id for a session.
+ *
+ * @param {object} pool
+ * @param {string} sessionId
+ * @returns {Promise<{crystallize_status: string, crystallized_world_id: string | null}>}
+ */
+async function readCrystallizeState(pool, sessionId) {
+  const result = await pool.query(
+    `SELECT crystallize_status, crystallized_world_id
+     FROM planning_sessions
+     WHERE session_id = $1`,
+    [sessionId],
+  );
+  if (result.rows.length === 0) {
+    return { crystallize_status: 'open', crystallized_world_id: null };
+  }
+  const row = result.rows[0];
+  return {
+    crystallize_status: row.crystallize_status,
+    crystallized_world_id: row.crystallized_world_id ?? null,
+  };
+}
+
+/**
+ * SELECT all planning chunks for a session, ordered by seq.
+ *
+ * @param {object} pool
+ * @param {string} sessionId
+ * @returns {Promise<Array<{world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type}>>}
+ */
+async function selectPlanningChunks(pool, sessionId) {
+  const result = await pool.query(
+    `SELECT world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type
+     FROM chunks
+     WHERE world_id = $1 AND session_id = $2
+     ORDER BY seq ASC`,
+    [PLANNING_WORLD_ID, sessionId],
+  );
+  return result.rows;
+}
+
+/**
+ * INSERT a single chunk into the new world's session.
+ * Uses the original message_id + seq verbatim; only world_id and
+ * session_id change to point at the new world's session.
+ *
+ * @param {object} pool
+ * @param {object} chunk   — row from the planning session
+ * @param {string} newWorldId
+ * @param {string} newSessionId
+ * @returns {Promise<void>}
+ */
+async function insertChunkIntoNewWorld(pool, chunk, newWorldId, newSessionId) {
+  await pool.query(
+    `INSERT INTO chunks
+       (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+    [
+      newWorldId,
+      newSessionId,
+      chunk.message_id,
+      chunk.seq,
+      chunk.actor_id,
+      chunk.actor_type,
+      chunk.role,
+      chunk.chunk,
+      chunk.chunk_type,
+    ],
+  );
+}
+
+/**
+ * INSERT a system marker chunk into the ORIGINAL planning session to
+ * leave an audit trail of crystallization. The marker lands at
+ * world_id='_planning' + the original sessionId.
+ *
+ * @param {object} pool
+ * @param {string} sessionId   — original planning session id
+ * @param {string} worldId     — newly created world id
+ * @param {number} phaseCount  — number of phases in the plan
+ * @returns {Promise<void>}
+ */
+async function insertMarkerChunk(pool, sessionId, worldId, phaseCount) {
+  const messageId = randomUUID();
+  // Find the current max seq so the marker doesn't collide.
+  const seqResult = await pool.query(
+    `SELECT COALESCE(MAX(seq), -1) AS max_seq
+     FROM chunks
+     WHERE world_id = $1 AND session_id = $2`,
+    [PLANNING_WORLD_ID, sessionId],
+  );
+  const nextSeq = Number(seqResult.rows[0].max_seq) + 1;
+  await pool.query(
+    `INSERT INTO chunks
+       (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+    [
+      PLANNING_WORLD_ID,
+      sessionId,
+      messageId,
+      nextSeq,
+      'system',
+      'system',
+      'system',
+      `Plan crystallized into world "${worldId}" (${phaseCount} phase${phaseCount === 1 ? '' : 's'}).`,
+      'text',
+    ],
+  );
+}
+
+/**
+ * crystallizePlanningSession
+ *
+ * 4-phase atomic-or-compensating process:
+ *   1. Set crystallize_status='in_progress'
+ *   2. Call createWorld({ name: slugged-title }) → { id: worldId }
+ *   3. SELECT all chunks in _planning/sessionId; INSERT each into new world
+ *   4. Set crystallize_status='crystallized' (with worldId); INSERT marker chunk
+ *
+ * Compensating pattern on partial failure:
+ *   - If createWorld throws: set status='failed', rethrow. destroyWorld NOT called.
+ *   - If chunk-copy throws mid-batch: set status='failed', call destroyWorld(worldId),
+ *     rethrow. Orphan chunks already INSERTed stay (append-only; see file header).
+ *
+ * Idempotency:
+ *   - Already 'crystallized': return immediately without re-running.
+ *   - Already 'in_progress': return current status (safe short-circuit; see header).
+ *
+ * @param {object} opts
+ * @param {object}   opts.pool           — pg.Pool-compatible with .query()
+ * @param {string}   opts.sessionId      — planning session to crystallize
+ * @param {string}   opts.planTitle      — plan title (used for world name slug)
+ * @param {Array}    opts.planPhases     — array of phase objects (name, acceptance, risks?)
+ * @param {Function} opts.createWorld    — async ({ name }) => { id: string, ... }
+ * @param {Function} opts.destroyWorld   — async (worldId) => void
+ *
+ * @returns {Promise<{worldId: string, status: string, new_session_id: string}>}
+ * @throws  on failure (crystallize_status already set to 'failed' when thrown)
+ */
+export async function crystallizePlanningSession({
+  pool,
+  sessionId,
+  planTitle,
+  planPhases,
+  createWorld,
+  destroyWorld,
+}) {
+  // ── Idempotency guard ────────────────────────────────────────────────────
+  const currentState = await readCrystallizeState(pool, sessionId);
+
+  if (currentState.crystallize_status === 'crystallized') {
+    return {
+      worldId: currentState.crystallized_world_id,
+      status: `crystallized:${currentState.crystallized_world_id}`,
+      new_session_id: null,
+    };
+  }
+
+  if (currentState.crystallize_status === 'in_progress') {
+    // Cannot safely resume without knowing how far the copy got.
+    // Return current status so the UI shows 'in_progress'.
+    return {
+      worldId: currentState.crystallized_world_id,
+      status: 'in_progress',
+      new_session_id: null,
+    };
+  }
+
+  // ── Phase 1: mark in_progress ────────────────────────────────────────────
+  await setCrystallizeStatus({ pool, sessionId, status: 'in_progress', worldId: null });
+
+  // ── Phase 2: create world ────────────────────────────────────────────────
+  let worldId;
+  try {
+    const worldName = slugTitle(planTitle);
+    const world = await createWorld({ name: worldName });
+    worldId = world.id;
+  } catch (err) {
+    await setCrystallizeStatus({ pool, sessionId, status: 'failed', worldId: null });
+    throw err;
+  }
+
+  // ── Phase 3: copy chunks into new world ──────────────────────────────────
+  const newSessionId = randomUUID();
+  try {
+    const chunks = await selectPlanningChunks(pool, sessionId);
+    for (const chunk of chunks) {
+      await insertChunkIntoNewWorld(pool, chunk, worldId, newSessionId);
+    }
+  } catch (err) {
+    await setCrystallizeStatus({ pool, sessionId, status: 'failed', worldId: null });
+    try {
+      await destroyWorld(worldId);
+    } catch {
+      // Compensating destroy failure is non-fatal — the world may already
+      // be partially torn down or the destroy operation may not be
+      // reversible. Log is left to the caller's context.
+    }
+    throw err;
+  }
+
+  // ── Phase 4: mark crystallized + insert marker ───────────────────────────
+  await setCrystallizeStatus({ pool, sessionId, status: 'crystallized', worldId });
+  await insertMarkerChunk(pool, sessionId, worldId, planPhases.length);
+
+  return {
+    worldId,
+    status: `crystallized:${worldId}`,
+    new_session_id: newSessionId,
+  };
+}

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

@@ -35,6 +35,8 @@ import { Readable } from 'node:stream';
 import { URL } from 'node:url';
 import pg from 'pg';
 import { ensureSecret, timingSafeEqual, SECRET_PATH } from './plan-chat-secret.mjs';
+import { listPlanningSessions } from './planning-sessions.mjs';
+import { crystallizePlanningSession } from './crystallize-planning.mjs';
 
 const DEFAULT_PORT = 3200;
 const DEFAULT_DB_URL = 'postgres://postgres:spike@localhost:54321/chunks';
@@ -42,6 +44,7 @@ const DEFAULT_ELECTRIC_URL = 'http://localhost:30001';
 
 const ACTOR_TYPES = new Set(['agent', 'operator', 'codex', 'system']);
 const ROLES = new Set(['user', 'assistant', 'tool', 'system']);
+const CHUNK_TYPES = new Set(['text', 'tool_use']);
 
 // PB2 — scope-ID shape. world_id + session_id query params are interpolated
 // into the upstream Electric `where` clause; the regex IS the SQL-injection
@@ -172,6 +175,10 @@ function validateChunkInput(body) {
   if (!Number.isInteger(body.seq) || body.seq < 0) return 'seq must be a non-negative integer';
   if (typeof body.chunk !== 'string') return 'chunk must be a string';
   if (!ROLES.has(body.role)) return `role must be one of ${[...ROLES].join(', ')}`;
+  // Optional chunk_type field — defaults to 'text' when absent.
+  if ('chunk_type' in body && !CHUNK_TYPES.has(body.chunk_type)) {
+    return `chunk_type must be one of ${[...CHUNK_TYPES].join(', ')}`;
+  }
   // actor_id and actor_type from the client are IGNORED (server-derived).
   return null;
 }
@@ -195,6 +202,8 @@ export function createHandler({
   electricUrl,
   shapeDebug,
   shapeDebugLog,
+  createWorld,
+  destroyWorld,
 }) {
   if (!pool) throw new Error('createHandler: { pool } required');
   if (typeof bearer !== 'string' || bearer.length === 0) {
@@ -231,8 +240,8 @@ export function createHandler({
     try {
       await pool.query(
         `INSERT INTO chunks
-           (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk)
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+           (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
         [
           body.world_id,
           body.session_id,
@@ -242,6 +251,7 @@ export function createHandler({
           principal.actorType,
           body.role,
           body.chunk,
+          body.chunk_type ?? 'text',
         ],
       );
     } catch (err) {
@@ -257,6 +267,7 @@ export function createHandler({
       seq: body.seq,
       actor_id: principal.actorId,
       actor_type: principal.actorType,
+      chunk_type: body.chunk_type ?? 'text',
     });
   }
 
@@ -413,11 +424,82 @@ export function createHandler({
     }
   }
 
+  async function handleGetPlanningSessions(req, res, url) {
+    if (!checkAuth(req)) return unauthorized(res);
+    // Derive actorId from the bearer principal (no body on GET).
+    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 listPlanningSessions({ pool, actorId: principal.actorId, limit });
+      return send(res, 200, { sessions });
+    } catch (err) {
+      return send(res, 500, { error: 'list-failed', message: String(err?.message ?? err) });
+    }
+  }
+
+  async function handlePostCrystallize(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' });
+    }
+
+    // Validate required fields: session_id + plan.title + plan.phases
+    if (!body || typeof body.session_id !== 'string' || body.session_id.length === 0) {
+      return badRequest(res, 'session_id required');
+    }
+    if (!body.plan || typeof body.plan.title !== 'string' || body.plan.title.length === 0) {
+      return badRequest(res, 'plan.title required');
+    }
+    if (!Array.isArray(body.plan.phases)) {
+      return badRequest(res, 'plan.phases must be an array');
+    }
+
+    // createWorld + destroyWorld callbacks must be wired at handler creation
+    // time (production: WorldManager closures; tests: stubs). If they are not
+    // provided, surface a clear 501 rather than crashing.
+    if (typeof createWorld !== 'function' || typeof destroyWorld !== 'function') {
+      return send(res, 501, {
+        ok: false,
+        error: 'crystallize-not-wired',
+        status: 'failed',
+      });
+    }
+
+    try {
+      const result = await crystallizePlanningSession({
+        pool,
+        sessionId: body.session_id,
+        planTitle: body.plan.title,
+        planPhases: body.plan.phases,
+        createWorld,
+        destroyWorld,
+      });
+      return send(res, 200, {
+        ok: true,
+        created_world_id: result.worldId,
+        world_url: result.worldId ? `/world/${result.worldId}` : null,
+        status: result.status,
+      });
+    } catch (err) {
+      return send(res, 500, {
+        ok: false,
+        error: String(err?.message ?? err),
+        status: 'failed',
+      });
+    }
+  }
+
   return async function handler(req, res) {
     const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
     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/crystallize') return handlePostCrystallize(req, res);
     return send(res, 404, { error: 'not-found' });
   };
 }

package/host-cp/src/planning-sessions.mjs

@@ -0,0 +1,270 @@
+// planning-sessions — host-cp surface for creating and inspecting in-flight
+// planning sessions stored under world_id = PLANNING_WORLD_ID ('_planning').
+//
+// Formalises what the plan-chat-spa dev substrate does ad hoc:
+//
+//   createPlanningSession({ actorId, pool })
+//     Seeds a session with one 'system' chunk so the Electric shape subscriber
+//     gets a non-empty initial response on its first long-poll cycle. Also
+//     INSERTs a row into the planning_sessions sidecar table inside the same
+//     transaction so no partial state can exist (chunk written, no metadata row).
+//     Returns the allocated world_id, session_id, and the inserted seed chunk.
+//
+//   loadPlanningSession({ pool, sessionId })
+//     Lightweight metadata read: chunk count, first/last timestamps, first
+//     operator content (for title derivation). SPA still streams live chunks
+//     via the existing /v1/shape proxy — this is metadata-only.
+//
+//   recordPlanningSession({ pool, sessionId, actorId, summary })
+//     UPSERT into planning_sessions. Used by createPlanningSession (wrapped in
+//     a transaction) and later to update the summary as the session evolves.
+//
+//   setCrystallizeStatus({ pool, sessionId, status, worldId })
+//     UPDATE planning_sessions.crystallize_status + crystallized_world_id.
+//     Throws if status is not in PLANNING_SESSION_STATUSES.
+//
+//   listPlanningSessions({ pool, actorId, limit })
+//     SELECT rows for actorId, ordered created_at DESC. Returns array.
+//
+// Neither function calls validateChunkInput — that's for the public POST
+// surface. INSERTs here are built directly against the chunks column list.
+//
+// Pool errors surface loudly (never swallowed) so the caller sees the full
+// pg error message and can diagnose connectivity or constraint failures.
+
+import { randomUUID } from 'node:crypto';
+import { PLANNING_WORLD_ID, PLANNING_SESSION_STATUSES } from '@olam/chunks/schema';
+
+/**
+ * UPSERT a row in planning_sessions for the given sessionId.
+ *
+ * On first call (from createPlanningSession): inserts a fresh row.
+ * On subsequent calls: updates summary + updated_at only (leaves
+ * crystallize_status and crystallized_world_id untouched).
+ *
+ * @param {object} opts
+ * @param {object} opts.pool
+ * @param {string} opts.sessionId
+ * @param {string} opts.actorId
+ * @param {string | null} [opts.summary]
+ */
+export async function recordPlanningSession({ pool, sessionId, actorId, summary = null }) {
+  await pool.query(
+    `INSERT INTO planning_sessions (session_id, actor_id, summary)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (session_id) DO UPDATE
+       SET summary    = EXCLUDED.summary,
+           updated_at = NOW()`,
+    [sessionId, actorId, summary],
+  );
+}
+
+/**
+ * Create a new in-flight planning session under world_id='_planning'.
+ *
+ * Allocates a fresh session_id (UUID v4) and, inside a single transaction:
+ *   1. INSERTs a seed chunk (actor_type='system', seq=0) so the Electric shape
+ *      subscriber receives a non-empty initial long-poll response.
+ *   2. INSERTs a planning_sessions sidecar row (via recordPlanningSession) so
+ *      listPlanningSessions can return it immediately.
+ *
+ * Transaction guarantee: both INSERTs succeed or both roll back. A chunk
+ * written without a corresponding planning_sessions row is the partial-state
+ * bug this transaction prevents.
+ *
+ * @param {object} opts
+ * @param {string} opts.actorId  — actor_id to attribute the seed chunk to
+ *                                  (typically 'system' or the host-cp service id)
+ * @param {object} opts.pool     — pg.Pool-compatible object with .query() and
+ *                                  optionally .connect() for transactional clients.
+ *                                  Tests may supply a stub with a transaction-aware
+ *                                  .query() (BEGIN / INSERT / INSERT / COMMIT).
+ * @returns {Promise<{
+ *   world_id:   string,
+ *   session_id: string,
+ *   seed_chunk: {
+ *     world_id: string, session_id: string, message_id: string, seq: number,
+ *     actor_id: string, actor_type: string, role: string, chunk: string,
+ *     chunk_type: string,
+ *   },
+ * }>}
+ */
+export async function createPlanningSession({ actorId, pool }) {
+  const sessionId = randomUUID();
+  const messageId = randomUUID();
+  const seq = 0;
+  const actorType = 'system';
+  const role = 'system';
+  const chunk = 'Planning session created.';
+  const chunkType = 'text';
+
+  // Use a transactional client when pool.connect() is available (real pg.Pool).
+  // Test stubs that only implement .query() fall through to the flat path;
+  // the transactional contract is proven by the test that uses a stub whose
+  // second .query() throws and asserts the chunk INSERT was rolled back.
+  if (typeof pool.connect === 'function') {
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query(
+        `INSERT INTO chunks
+           (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+        [PLANNING_WORLD_ID, sessionId, messageId, seq, actorId, actorType, role, chunk, chunkType],
+      );
+      await recordPlanningSession({ pool: client, sessionId, actorId, summary: null });
+      await client.query('COMMIT');
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } else {
+    // Flat path for test stubs: queries run sequentially on the stub pool.
+    await pool.query(
+      `INSERT INTO chunks
+         (world_id, session_id, message_id, seq, actor_id, actor_type, role, chunk, chunk_type)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+      [PLANNING_WORLD_ID, sessionId, messageId, seq, actorId, actorType, role, chunk, chunkType],
+    );
+    await recordPlanningSession({ pool, sessionId, actorId, summary: null });
+  }
+
+  return {
+    world_id: PLANNING_WORLD_ID,
+    session_id: sessionId,
+    seed_chunk: {
+      world_id: PLANNING_WORLD_ID,
+      session_id: sessionId,
+      message_id: messageId,
+      seq,
+      actor_id: actorId,
+      actor_type: actorType,
+      role,
+      chunk,
+      chunk_type: chunkType,
+    },
+  };
+}
+
+/**
+ * Update crystallize_status (and optionally crystallized_world_id) for a
+ * planning session.
+ *
+ * @param {object} opts
+ * @param {object} opts.pool
+ * @param {string} opts.sessionId
+ * @param {string} opts.status   — must be in PLANNING_SESSION_STATUSES
+ * @param {string | null} [opts.worldId] — required when status='crystallized'
+ */
+export async function setCrystallizeStatus({ pool, sessionId, status, worldId = null }) {
+  if (!PLANNING_SESSION_STATUSES.includes(status)) {
+    throw new Error(
+      `setCrystallizeStatus: invalid status "${status}"; ` +
+      `must be one of ${PLANNING_SESSION_STATUSES.join(', ')}`,
+    );
+  }
+  await pool.query(
+    `UPDATE planning_sessions
+     SET crystallize_status    = $2,
+         crystallized_world_id = $3,
+         updated_at            = NOW()
+     WHERE session_id = $1`,
+    [sessionId, status, worldId],
+  );
+}
+
+/**
+ * List planning sessions for a given actorId, ordered by created_at DESC.
+ *
+ * @param {object} opts
+ * @param {object} opts.pool
+ * @param {string} opts.actorId
+ * @param {number} [opts.limit=50]
+ * @returns {Promise<Array<{
+ *   session_id: string,
+ *   summary: string | null,
+ *   crystallize_status: string,
+ *   crystallized_world_id: string | null,
+ *   created_at: string,
+ *   updated_at: string,
+ * }>>}
+ */
+export async function listPlanningSessions({ pool, actorId, limit = 50 }) {
+  const result = await pool.query(
+    `SELECT session_id, summary, crystallize_status, crystallized_world_id,
+            created_at, updated_at
+     FROM planning_sessions
+     WHERE actor_id = $1
+     ORDER BY created_at DESC
+     LIMIT $2`,
+    [actorId, limit],
+  );
+  return result.rows;
+}
+
+/**
+ * Load lightweight metadata for an existing in-flight planning session.
+ *
+ * Performs two queries scoped to world_id='_planning' AND session_id=<sessionId>:
+ *  1. Aggregate: chunk_count, first_chunk_at, last_chunk_at.
+ *  2. First operator content: earliest chunk where actor_type='operator',
+ *     used by the SPA for session title derivation.
+ *
+ * The SPA streams live chunks via the existing /v1/shape proxy; this function
+ * is metadata-only and does NOT subscribe to any Electric shape.
+ *
+ * @param {object} opts
+ * @param {object} opts.pool      — pg.Pool-compatible object with a .query(sql, params) method
+ * @param {string} opts.sessionId — UUID of the planning session to inspect
+ * @returns {Promise<{
+ *   world_id:               string,
+ *   session_id:             string,
+ *   exists:                 boolean,
+ *   chunk_count:            number,
+ *   first_chunk_at:         string | null,
+ *   last_chunk_at:          string | null,
+ *   first_operator_content: string | null,
+ * }>}
+ */
+export async function loadPlanningSession({ pool, sessionId }) {
+  const aggResult = await pool.query(
+    `SELECT COUNT(*) AS chunk_count,
+            MIN(created_at) AS first_chunk_at,
+            MAX(created_at) AS last_chunk_at
+     FROM chunks
+     WHERE world_id = $1 AND session_id = $2`,
+    [PLANNING_WORLD_ID, sessionId],
+  );
+
+  const row = aggResult.rows[0];
+  const chunkCount = Number(row.chunk_count);
+  const exists = chunkCount > 0;
+
+  let firstOperatorContent = null;
+
+  if (exists) {
+    const opResult = await pool.query(
+      `SELECT chunk
+       FROM chunks
+       WHERE world_id = $1 AND session_id = $2 AND actor_type = 'operator'
+       ORDER BY created_at ASC
+       LIMIT 1`,
+      [PLANNING_WORLD_ID, sessionId],
+    );
+    if (opResult.rows.length > 0) {
+      firstOperatorContent = opResult.rows[0].chunk;
+    }
+  }
+
+  return {
+    world_id: PLANNING_WORLD_ID,
+    session_id: sessionId,
+    exists,
+    chunk_count: chunkCount,
+    first_chunk_at: exists ? row.first_chunk_at : null,
+    last_chunk_at: exists ? row.last_chunk_at : null,
+    first_operator_content: firstOperatorContent,
+  };
+}

package/host-cp/src/server.mjs

@@ -53,6 +53,7 @@ import {
   normalizeName,
 } from './world-names-store.mjs';
 import { createLocalWorldsSource } from './local-worlds-source.mjs';
+import { dispatchTasksRoute } from './tasks-route.mjs';
 import { createPylonWorldsSource } from './pylon-worlds-source.mjs';
 import { composeWorldsSources } from './compose-worlds-sources.mjs';
 import { createWorldPrStateStore } from './world-pr-state.mjs';
@@ -793,6 +794,14 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     }));
   }
 
+  // /api/tasks/* — B2.2: @olam/tasks-write-api mount via pgPoolExecutor
+  // adapter. Bearer-auth already applied above; per-request scopes + olamNodeId
+  // come from X-Olam-* headers; RLS enforced server-side per D-B-23.
+  if (url.pathname.startsWith('/api/tasks')) {
+    const handled = await dispatchTasksRoute(req, res, url);
+    if (handled) return;
+  }
+
   // /api/version/status: returns the current version snapshot (baked SHA
   // vs operator's local HEAD). No auth required beyond the existing gate
   // (already applied above). Phase 1 only — detection, no auto-upgrade.