@pleri/olam-cli 0.1.7

package/host-cp/src/plan-orchestrator.mjs

@@ -0,0 +1,829 @@
+// plan-orchestrator.mjs — Phase 2: multi-persona conversation coordinator.
+//
+// Architecture:
+//  - AgentRegistry holds one pi AgentSession per (conversationId, personaId).
+//  - HandoffEngine forks the session tree when the active persona changes.
+//  - All persona turns share one session.jsonl per conversation.
+//  - SSE sinks are an in-process Set<ServerResponse> per conversationId.
+//
+// Credentials:
+//  - Uses the Olam auth-service vault (same as the rest of host-cp).
+//  - No ANTHROPIC_API_KEY required; tokens fetched on demand via auth-service.
+
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import Database from 'better-sqlite3';
+import { SessionManager } from '@mariozechner/pi-coding-agent';
+import { PERSONAS, DEFAULT_PERSONA_ID, getPersona } from './plan/personas.mjs';
+import { AgentRegistry } from './plan/agent-registry.mjs';
+import { HandoffEngine } from './plan/handoff-engine.mjs';
+
+// ── Paths ─────────────────────────────────────────────────────────────────────
+
+const PLAN_DB_PATH = path.join(os.homedir(), '.olam', 'plan.db');
+const PLAN_DIR = path.join(os.homedir(), '.olam', 'plan');
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function initSessionFile(sessionFile, sessionId) {
+  const header = {
+    type: 'session',
+    version: 3,
+    id: sessionId,
+    timestamp: new Date().toISOString(),
+    cwd: os.homedir(),
+  };
+  fs.writeFileSync(sessionFile, JSON.stringify(header) + '\n');
+}
+
+/**
+ * Derive a short title from the first user message content.
+ * Truncates at a word boundary to at most maxLen characters.
+ * @param {string} content
+ * @param {number} [maxLen=40]
+ * @returns {string}
+ */
+export function deriveTitle(content, maxLen = 40) {
+  const trimmed = content.trim().replace(/\s+/g, ' ');
+  if (!trimmed) return '(empty)';
+  if (trimmed.length <= maxLen) return trimmed;
+  const cut = trimmed.slice(0, maxLen);
+  const lastSpace = cut.lastIndexOf(' ');
+  return (lastSpace > 0 ? cut.slice(0, lastSpace) : cut) + '…';
+}
+
+// ── PlanOrchestrator ──────────────────────────────────────────────────────────
+
+export class PlanOrchestrator {
+  #db;
+  #authServiceUrl;
+  #authServiceSecret;
+  #registry;
+  #handoffEngine;
+
+  /** Tracks the active persona per conversationId: Map<conversationId, personaId> */
+  #activePersona = new Map();
+
+  /** @type {Map<string, Set<import('node:http').ServerResponse>>} */
+  #sinks = new Map();
+
+  /**
+   * Ring buffer of in-flight SSE events per conversationId.
+   * Populated while a turn is active; cleared on turn_complete.
+   * Used by drainReplayBuffer to replay missed events on reconnect.
+   * @type {Map<string, Array<{event: string, data: object}>>}
+   */
+  #activeTurns = new Map();
+
+  /**
+   * Mutable current-chunk refs per conversationId.
+   * ChunkEmitter updates these; read_sidebar tool reads them.
+   * @type {Map<string, { current: string|null }>}
+   */
+  #currentChunkRefs = new Map();
+
+  /**
+   * @param {{ authServiceUrl: string, authServiceSecret: string }} opts
+   */
+  constructor({ authServiceUrl, authServiceSecret }) {
+    this.#authServiceUrl = authServiceUrl;
+    this.#authServiceSecret = authServiceSecret;
+
+    this.#registry = new AgentRegistry({ authServiceUrl, authServiceSecret });
+    this.#handoffEngine = new HandoffEngine(this.#registry);
+
+    fs.mkdirSync(path.dirname(PLAN_DB_PATH), { recursive: true });
+    this.#db = new Database(PLAN_DB_PATH);
+    this.#db.exec(`
+      CREATE TABLE IF NOT EXISTS plan_conversations (
+        id TEXT PRIMARY KEY,
+        title TEXT,
+        persona TEXT NOT NULL DEFAULT 'brainstorm',
+        created_at INTEGER NOT NULL,
+        last_turn_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS plan_turns (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL REFERENCES plan_conversations(id),
+        role TEXT NOT NULL,
+        content TEXT NOT NULL DEFAULT '',
+        persona TEXT,
+        from_persona TEXT,
+        to_persona TEXT,
+        mode TEXT,
+        fork_node_id TEXT,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS plan_turns_conv_idx
+        ON plan_turns(conversation_id, created_at);
+
+      -- Phase 4B: lookout agent registry per conversation
+      CREATE TABLE IF NOT EXISTS plan_lookout_agents (
+        conversation_id TEXT NOT NULL,
+        persona_id TEXT NOT NULL,
+        muted INTEGER NOT NULL DEFAULT 0,
+        mode TEXT NOT NULL DEFAULT 'observe',
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (conversation_id, persona_id)
+      );
+
+      -- Phase 4B: sidebar signals from lookout agents
+      CREATE TABLE IF NOT EXISTS plan_sidebar_signals (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        urgency TEXT NOT NULL DEFAULT 'p2',
+        reason TEXT NOT NULL DEFAULT '',
+        content TEXT NOT NULL DEFAULT '',
+        chunk_id TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        tension_subject TEXT,
+        parent_signal_id TEXT
+      );
+      CREATE INDEX IF NOT EXISTS plan_sidebar_conv_idx
+        ON plan_sidebar_signals(conversation_id, created_at);
+      CREATE INDEX IF NOT EXISTS plan_sidebar_chunk_idx
+        ON plan_sidebar_signals(chunk_id);
+    `);
+  }
+
+  // ── Auth-service credential fetching ──────────────────────────────────────
+
+  /**
+   * Fetch a live Claude API token from the vault.
+   * @returns {Promise<string>}
+   */
+  async #fetchToken() {
+    return this.#registry.fetchToken('claude');
+  }
+
+  /**
+   * Lightweight check — returns true if vault has an active credential.
+   * @returns {Promise<boolean>}
+   */
+  async hasCredential() {
+    try {
+      await this.#fetchToken();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── Conversation management ───────────────────────────────────────────────
+
+  /**
+   * @param {{ title?: string }} [opts]
+   * @returns {{ id: string, title: string|null, persona: string, created_at: number }}
+   */
+  createConversation({ title } = {}) {
+    const id = randomUUID();
+    const created_at = Date.now();
+
+    const sessionDir = path.join(PLAN_DIR, id);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    initSessionFile(path.join(sessionDir, 'session.jsonl'), id);
+
+    this.#db
+      .prepare(
+        `INSERT INTO plan_conversations (id, title, persona, created_at)
+         VALUES (?, ?, ?, ?)`,
+      )
+      .run(id, title ?? null, DEFAULT_PERSONA_ID, created_at);
+
+    this.#activePersona.set(id, DEFAULT_PERSONA_ID);
+
+    return { id, title: title ?? null, persona: DEFAULT_PERSONA_ID, created_at };
+  }
+
+  /** @returns {Array<{id, title, created_at, last_turn_at, persona}>} */
+  listConversations() {
+    return this.#db
+      .prepare(
+        `SELECT id, title, created_at, last_turn_at, persona
+         FROM plan_conversations
+         ORDER BY created_at DESC`,
+      )
+      .all();
+  }
+
+  /**
+   * @param {string} id
+   * @returns {{ id, title, persona, created_at, last_turn_at, tree } | null}
+   */
+  getConversation(id) {
+    const row = this.#db
+      .prepare(
+        `SELECT id, title, persona, created_at, last_turn_at
+         FROM plan_conversations WHERE id = ?`,
+      )
+      .get(id);
+
+    if (!row) return null;
+
+    const sessionFile = path.join(PLAN_DIR, id, 'session.jsonl');
+    let tree = [];
+    try {
+      const mgr = SessionManager.open(sessionFile, path.join(PLAN_DIR, id));
+      tree = mgr.getTree();
+    } catch {
+      // Session file missing or corrupt — return empty tree.
+    }
+
+    return { ...row, tree };
+  }
+
+  // ── Active persona management ─────────────────────────────────────────────
+
+  /**
+   * @param {string} conversationId
+   * @returns {string} Active persona ID.
+   */
+  getActivePersona(conversationId) {
+    if (this.#activePersona.has(conversationId)) {
+      return this.#activePersona.get(conversationId);
+    }
+    const row = this.#db
+      .prepare(`SELECT persona FROM plan_conversations WHERE id = ?`)
+      .get(conversationId);
+    const personaId = row?.persona ?? DEFAULT_PERSONA_ID;
+    this.#activePersona.set(conversationId, personaId);
+    return personaId;
+  }
+
+  /**
+   * Set the active default persona for a conversation (does NOT trigger a handoff).
+   * @param {string} conversationId
+   * @param {string} personaId
+   */
+  setActivePersona(conversationId, personaId) {
+    this.#activePersona.set(conversationId, personaId);
+    this.#db
+      .prepare(`UPDATE plan_conversations SET persona = ? WHERE id = ?`)
+      .run(personaId, conversationId);
+  }
+
+  // ── SSE broadcast ─────────────────────────────────────────────────────────
+
+  #broadcast(conversationId, eventName, data) {
+    // Buffer event while a turn is active for reconnect replay.
+    const buf = this.#activeTurns.get(conversationId);
+    if (buf) {
+      buf.push({ event: eventName, data });
+    }
+
+    const sinks = this.#sinks.get(conversationId);
+    if (!sinks || sinks.size === 0) return;
+    const chunk = `event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of sinks) {
+      try { res.write(chunk); } catch { /* client disconnected */ }
+    }
+
+    // Clear buffer after turn_complete so the next turn starts fresh.
+    if (eventName === 'turn_complete') {
+      this.#activeTurns.delete(conversationId);
+    }
+  }
+
+  // ── Lookout agent management ──────────────────────────────────────────────
+
+  /**
+   * Invite a persona as a lookout for a conversation.
+   * @param {string} conversationId
+   * @param {string} personaId
+   * @returns {{ persona_id: string, state: string, muted: boolean, mode: string }}
+   */
+  inviteLookout(conversationId, personaId) {
+    const now = Date.now();
+    this.#db
+      .prepare(`INSERT OR IGNORE INTO plan_lookout_agents (conversation_id, persona_id, muted, mode, created_at) VALUES (?, ?, 0, 'observe', ?)`)
+      .run(conversationId, personaId, now);
+    const agent = { persona_id: personaId, state: 'listening', muted: false, mode: 'observe' };
+    this.#broadcast(conversationId, 'agent_state', { persona_id: personaId, state: 'listening' });
+    return agent;
+  }
+
+  /**
+   * Update muted status (or mode) for a lookout agent.
+   * @param {string} conversationId
+   * @param {string} personaId
+   * @param {{ muted?: boolean, mode?: string }} updates
+   * @returns {{ persona_id: string, state: string, muted: boolean, mode: string } | null}
+   */
+  updateLookout(conversationId, personaId, { muted, mode } = {}) {
+    const row = this.#db
+      .prepare(`SELECT * FROM plan_lookout_agents WHERE conversation_id = ? AND persona_id = ?`)
+      .get(conversationId, personaId);
+    if (!row) return null;
+
+    const newMuted = muted !== undefined ? (muted ? 1 : 0) : row.muted;
+    const newMode = mode ?? row.mode;
+    this.#db
+      .prepare(`UPDATE plan_lookout_agents SET muted = ?, mode = ? WHERE conversation_id = ? AND persona_id = ?`)
+      .run(newMuted, newMode, conversationId, personaId);
+
+    const newState = newMuted ? 'idle' : 'listening';
+    this.#broadcast(conversationId, 'agent_state', { persona_id: personaId, state: newState });
+    return { persona_id: personaId, state: newState, muted: !!newMuted, mode: newMode };
+  }
+
+  /**
+   * Remove a lookout agent.
+   * @param {string} conversationId
+   * @param {string} personaId
+   */
+  uninviteLookout(conversationId, personaId) {
+    this.#db
+      .prepare(`DELETE FROM plan_lookout_agents WHERE conversation_id = ? AND persona_id = ?`)
+      .run(conversationId, personaId);
+  }
+
+  /**
+   * List active lookout agents for a conversation.
+   * @param {string} conversationId
+   * @returns {Array<{ persona_id: string, state: string, muted: boolean, mode: string }>}
+   */
+  listLookoutAgents(conversationId) {
+    const rows = this.#db
+      .prepare(`SELECT persona_id, muted, mode FROM plan_lookout_agents WHERE conversation_id = ?`)
+      .all(conversationId);
+    return rows.map((r) => ({
+      persona_id: r.persona_id,
+      state: r.muted ? 'idle' : 'listening',
+      muted: !!r.muted,
+      mode: r.mode,
+    }));
+  }
+
+  // ── Sidebar signal management ─────────────────────────────────────────────
+
+  /**
+   * Dismiss a sidebar signal.
+   * @param {string} conversationId
+   * @param {string} signalId
+   * @returns {boolean}
+   */
+  dismissSignal(conversationId, signalId) {
+    const info = this.#db
+      .prepare(`UPDATE plan_sidebar_signals SET status = 'dismissed' WHERE id = ? AND conversation_id = ?`)
+      .run(signalId, conversationId);
+    return info.changes > 0;
+  }
+
+  /**
+   * Mark a sidebar signal as used (for next turn context).
+   * @param {string} conversationId
+   * @param {string} signalId
+   * @returns {boolean}
+   */
+  useSignal(conversationId, signalId) {
+    const info = this.#db
+      .prepare(`UPDATE plan_sidebar_signals SET status = 'used' WHERE id = ? AND conversation_id = ?`)
+      .run(signalId, conversationId);
+    return info.changes > 0;
+  }
+
+  /**
+   * List sidebar signals for a conversation (optionally filtered by chunk_id).
+   * @param {string} conversationId
+   * @param {string} [chunkId]
+   * @returns {Array<object>}
+   */
+  listSignals(conversationId, chunkId) {
+    if (chunkId) {
+      return this.#db
+        .prepare(`SELECT * FROM plan_sidebar_signals WHERE conversation_id = ? AND chunk_id = ? ORDER BY created_at ASC`)
+        .all(conversationId, chunkId);
+    }
+    return this.#db
+      .prepare(`SELECT * FROM plan_sidebar_signals WHERE conversation_id = ? ORDER BY created_at ASC`)
+      .all(conversationId);
+  }
+
+  // ── Lookout analysis ──────────────────────────────────────────────────────
+
+  /**
+   * Persona-specific heuristics for lookout analysis.
+   * Returns { shouldComment: boolean, urgency, content, reason, tension_subject? }
+   * or null if no comment warranted.
+   *
+   * @param {string} personaId
+   * @param {string} content — chunk content to analyze
+   * @returns {{ urgency: string, content: string, reason: string, tension_subject?: string } | null}
+   */
+  #analyzeChunkHeuristic(personaId, content) {
+    const lower = content.toLowerCase();
+
+    if (personaId === 'scout') {
+      // Scout: flag unsubstantiated claims and factual assertions
+      const claimPatterns = [
+        /\b(research shows|studies (show|indicate|suggest)|data (shows|indicates|suggests))\b/i,
+        /\b\d+(\.\d+)?\s*%\b/,
+        /\b(always|never|all|every|none|no one)\b/i,
+        /\b(proven|definitive|certain|guaranteed|undeniable)\b/i,
+        /\b(industry standard|best practice|widely accepted)\b/i,
+      ];
+      const matched = claimPatterns.find((p) => p.test(content));
+      if (matched) {
+        return {
+          urgency: 'p2',
+          reason: 'Factual claim without cited source',
+          content: 'This response contains claims that should be verified with evidence. What data or sources back this up?',
+        };
+      }
+      // Scout spark: look for unexplored data angles
+      if (lower.includes('option') || lower.includes('approach') || lower.includes('strategy')) {
+        if (Math.random() < 0.3) {
+          return {
+            urgency: 'spark',
+            reason: 'Potential evidence gap',
+            content: '_What metrics or signals would tell us which option is actually better here?_',
+          };
+        }
+      }
+    }
+
+    if (personaId === 'pm') {
+      // PM: flag scope ambiguity and missing requirements
+      const scopePatterns = [
+        /\b(could|might|maybe|perhaps|possibly|potentially)\b/i,
+        /\b(later|eventually|someday|future)\b/i,
+        /\b(depends on|unclear|tbd|to be determined)\b/i,
+      ];
+      const matched = scopePatterns.find((p) => p.test(content));
+      if (matched) {
+        return {
+          urgency: 'p1',
+          reason: 'Scope ambiguity detected',
+          content: 'Scope boundary needs clarification. What specifically is in vs. out for this iteration?',
+        };
+      }
+      // PM: flag missing success criteria
+      if ((lower.includes('implement') || lower.includes('build') || lower.includes('create')) && !lower.includes('success') && !lower.includes('metric') && !lower.includes('goal')) {
+        if (Math.random() < 0.4) {
+          return {
+            urgency: 'p2',
+            reason: 'Missing acceptance criteria',
+            content: 'What does done look like here? Define the measurable success criteria before building.',
+          };
+        }
+      }
+    }
+
+    if (personaId === 'brainstorm') {
+      // Brainstorm: flag premature convergence on a single option
+      const convergencePatterns = [
+        /\b(the (best|right|correct|only) (way|approach|solution|option))\b/i,
+        /\b(we should|we must|we need to|the answer is)\b/i,
+        /\b(obviously|clearly|simply|just)\b/i,
+      ];
+      const matched = convergencePatterns.find((p) => p.test(content));
+      if (matched) {
+        return {
+          urgency: 'spark',
+          reason: 'Early convergence on one path',
+          content: '_Before narrowing: what\'s the alternative that explicitly rejects this approach? What would it look like?_',
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Run lookout analysis for all active lookout agents after a turn completes.
+   * Emits sidebar_entry SSE events for any signals generated.
+   *
+   * @param {string} conversationId
+   * @param {string} chunkId — the turn ID used as chunk reference
+   * @param {string} chunkContent — the assistant's response text
+   * @param {string} chunkPersona — which persona produced the chunk
+   */
+  async #runLookoutAnalysis(conversationId, chunkId, chunkContent, chunkPersona) {
+    const lookouts = this.#db
+      .prepare(`SELECT persona_id, muted FROM plan_lookout_agents WHERE conversation_id = ? AND muted = 0`)
+      .all(conversationId);
+
+    for (const lookout of lookouts) {
+      const { persona_id: personaId } = lookout;
+
+      // Skip if this is the persona that produced the chunk
+      if (personaId === chunkPersona) continue;
+
+      // Emit thinking state
+      this.#broadcast(conversationId, 'agent_state', { persona_id: personaId, state: 'thinking' });
+
+      // Small async gap to let the SSE event reach the client before analysis
+      await new Promise((resolve) => setTimeout(resolve, 300 + Math.random() * 700));
+
+      try {
+        const analysis = this.#analyzeChunkHeuristic(personaId, chunkContent);
+
+        if (analysis) {
+          const signalId = randomUUID();
+          const now = Date.now();
+          this.#db
+            .prepare(
+              `INSERT INTO plan_sidebar_signals (id, conversation_id, agent_id, urgency, reason, content, chunk_id, created_at, status, tension_subject)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)`,
+            )
+            .run(signalId, conversationId, personaId, analysis.urgency, analysis.reason, analysis.content, chunkId, now, analysis.tension_subject ?? null);
+
+          const signal = {
+            id: signalId,
+            agent_id: personaId,
+            urgency: analysis.urgency,
+            reason: analysis.reason,
+            content: analysis.content,
+            chunk_id: chunkId,
+            created_at: now,
+            status: 'active',
+            tension_subject: analysis.tension_subject ?? null,
+            parent_signal_id: null,
+          };
+
+          this.#broadcast(
+            conversationId,
+            analysis.urgency === 'p0' ? 'interrupt' : 'sidebar_entry',
+            { signal },
+          );
+        }
+      } catch (err) {
+        console.error(`[plan] lookout analysis error ${conversationId}/${personaId}:`, err.message);
+      }
+
+      // Return to listening state
+      this.#broadcast(conversationId, 'agent_state', { persona_id: personaId, state: 'listening' });
+    }
+  }
+
+  // ── Persona subscription setup ────────────────────────────────────────────
+
+  /**
+   * Wire pi event listeners for a session so tokens + turn_complete events are
+   * forwarded to SSE clients.
+   *
+   * @param {string} conversationId
+   * @param {string} personaId
+   * @param {import('@mariozechner/pi-coding-agent').AgentSession} session
+   */
+  #wireSessionEvents(conversationId, personaId, session) {
+    session.subscribe((event) => {
+      if (event.type === 'message_update') {
+        const ae = event.assistantMessageEvent;
+        if (ae.type === 'text_delta') {
+          this.#broadcast(conversationId, 'token', { delta: ae.delta, persona: personaId });
+        }
+      } else if (event.type === 'agent_end') {
+        const msgs = event.messages;
+        const last = msgs[msgs.length - 1];
+
+        let persistedText = '';
+        let turnId = last?.id ?? randomUUID();
+
+        // Persist the assistant turn so history loads correctly.
+        if (last) {
+          const text = (last.content ?? [])
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text ?? '')
+            .join('');
+          if (text) {
+            persistedText = text;
+            const now = Date.now();
+            this.#db
+              .prepare(
+                `INSERT OR IGNORE INTO plan_turns
+                 (id, conversation_id, role, content, persona, created_at)
+                 VALUES (?, ?, 'assistant', ?, ?, ?)`,
+              )
+              .run(turnId, conversationId, text, personaId, now);
+          }
+        }
+
+        this.#broadcast(conversationId, 'turn_complete', {
+          turnId,
+          persona: personaId,
+          finishReason: last?.stopReason ?? 'end_turn',
+        });
+        this.#db
+          .prepare(`UPDATE plan_conversations SET last_turn_at = ? WHERE id = ?`)
+          .run(Date.now(), conversationId);
+
+        // Trigger lookout analysis asynchronously — does not block the turn.
+        if (persistedText) {
+          this.#runLookoutAnalysis(conversationId, turnId, persistedText, personaId)
+            .catch((err) => console.error('[plan] lookout run error:', err.message));
+        }
+      }
+    });
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  /**
+   * Submit a user turn to the active (or overridden) persona.
+   * Returns immediately; tokens stream over SSE.
+   *
+   * @param {{
+   *   conversationId: string,
+   *   content: string,
+   *   personaOverride?: string,
+   * }} params
+   * @returns {Promise<{ turnId: string, persona: string }>}
+   */
+  async submitTurn({ conversationId, content, personaOverride }) {
+    const row = this.#db
+      .prepare(`SELECT id, title FROM plan_conversations WHERE id = ?`)
+      .get(conversationId);
+
+    if (!row) {
+      const err = new Error('conversation not found');
+      err.code = 'NOT_FOUND';
+      throw err;
+    }
+
+    const now = Date.now();
+
+    // Open (or reset) the replay buffer for this turn.
+    this.#activeTurns.set(conversationId, []);
+
+    // Set title from first user message if still null.
+    if (row.title === null) {
+      this.#db
+        .prepare(`UPDATE plan_conversations SET title = ? WHERE id = ?`)
+        .run(deriveTitle(content), conversationId);
+    }
+
+    // Persist the user turn for history replay.
+    this.#db
+      .prepare(
+        `INSERT INTO plan_turns (id, conversation_id, role, content, created_at)
+         VALUES (?, ?, 'user', ?, ?)`,
+      )
+      .run(randomUUID(), conversationId, content, now);
+
+    const personaId = personaOverride ?? this.getActivePersona(conversationId);
+    const onStubCall = (event) => {
+      this.#broadcast(conversationId, 'tool_stub_call', { persona: personaId, ...event });
+    };
+
+    const { session, authStorage } = await this.#registry.getAgent(conversationId, personaId, { onStubCall });
+
+    // Wire events on first use (idempotent because pi de-duplicates subscribers).
+    this.#wireSessionEvents(conversationId, personaId, session);
+
+    // Refresh credential before each turn.
+    const token = await this.#fetchToken();
+    authStorage.setRuntimeApiKey('anthropic', token);
+
+    const turnId = randomUUID();
+
+    session.prompt(content).catch((err) => {
+      console.error(`[plan] prompt error ${conversationId}/${personaId}:`, err.message);
+      this.#broadcast(conversationId, 'error', {
+        message: err.message,
+        code: err.code ?? 'PROMPT_ERROR',
+      });
+    });
+
+    return { turnId, persona: personaId };
+  }
+
+  /**
+   * Execute a handoff, switching the default active persona.
+   *
+   * @param {{
+   *   conversationId: string,
+   *   toPersona: string,
+   *   mode?: 'full' | 'distilled' | 'quoted',
+   *   selectedTurnIds?: string[],
+   * }} params
+   * @returns {Promise<{ handoffId: string, forkNodeId: string | null, seededTurnCount: number }>}
+   */
+  async handoff({ conversationId, toPersona, mode = 'full', selectedTurnIds = [] }) {
+    const row = this.#db
+      .prepare(`SELECT id FROM plan_conversations WHERE id = ?`)
+      .get(conversationId);
+    if (!row) {
+      const err = new Error('conversation not found');
+      err.code = 'NOT_FOUND';
+      throw err;
+    }
+
+    const fromPersona = this.getActivePersona(conversationId);
+    const onStubCall = (event) => {
+      this.#broadcast(conversationId, 'tool_stub_call', { persona: toPersona, ...event });
+    };
+
+    const result = await this.#handoffEngine.handoff({
+      conversationId,
+      fromPersona,
+      toPersona,
+      mode,
+      selectedTurnIds,
+      fetchToken: () => this.#fetchToken(),
+      onStubCall,
+    });
+
+    // Update the active persona for this conversation.
+    this.setActivePersona(conversationId, toPersona);
+
+    // Persist handoff marker so history replay can reconstruct it.
+    this.#db
+      .prepare(
+        `INSERT OR IGNORE INTO plan_turns
+         (id, conversation_id, role, content, from_persona, to_persona, mode, fork_node_id, created_at)
+         VALUES (?, ?, 'handoff', '', ?, ?, ?, ?, ?)`,
+      )
+      .run(result.handoffId, conversationId, fromPersona, toPersona, mode, result.forkNodeId ?? null, Date.now());
+
+    // Broadcast the handoff event to SSE clients.
+    this.#broadcast(conversationId, 'handoff', {
+      handoffId: result.handoffId,
+      fromPersona,
+      toPersona,
+      mode,
+      forkNodeId: result.forkNodeId,
+    });
+
+    // Wire events for the new persona's session.
+    try {
+      const { session } = await this.#registry.getAgent(conversationId, toPersona, { onStubCall });
+      this.#wireSessionEvents(conversationId, toPersona, session);
+    } catch {
+      // Best-effort — events will be wired on first turn if this fails.
+    }
+
+    return result;
+  }
+
+  /**
+   * Replay buffered in-flight SSE events to a reconnecting client.
+   * Call this before addEventSink so the client gets events it missed.
+   * No-op if no turn is active.
+   *
+   * @param {string} conversationId
+   * @param {import('node:http').ServerResponse} res
+   */
+  drainReplayBuffer(conversationId, res) {
+    const buf = this.#activeTurns.get(conversationId);
+    if (!buf || buf.length === 0) return;
+    for (const { event, data } of buf) {
+      try {
+        res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+      } catch { /* client closed before drain completed */ }
+    }
+  }
+
+  /**
+   * Register an SSE sink for a conversation. Returns a cleanup function.
+   * @param {string} conversationId
+   * @param {import('node:http').ServerResponse} res
+   * @returns {() => void}
+   */
+  addEventSink(conversationId, res) {
+    if (!this.#sinks.has(conversationId)) {
+      this.#sinks.set(conversationId, new Set());
+    }
+    this.#sinks.get(conversationId).add(res);
+    return () => {
+      const s = this.#sinks.get(conversationId);
+      if (s) s.delete(res);
+    };
+  }
+
+  /**
+   * Return the ordered turn list for a conversation (for history replay).
+   * Each turn is one of:
+   *   { role:'user'|'assistant', content, persona?, created_at }
+   *   { role:'handoff', from_persona, to_persona, mode, fork_node_id, created_at }
+   * @param {string} conversationId
+   * @returns {Array<object>}
+   */
+  getTurns(conversationId) {
+    return this.#db
+      .prepare(
+        `SELECT id, role, content, persona, from_persona, to_persona, mode, fork_node_id, created_at
+         FROM plan_turns
+         WHERE conversation_id = ?
+         ORDER BY created_at ASC`,
+      )
+      .all(conversationId);
+  }
+
+  /** Expose persona list for the /api/plan/personas endpoint. */
+  listPersonas() {
+    return PERSONAS.map((p) => ({
+      id: p.id,
+      displayName: p.displayName,
+      model: p.model,
+      toolNames: p.toolNames,
+      systemPromptPreview: p.systemPrompt.length > 120
+        ? p.systemPrompt.slice(0, 117) + '...'
+        : p.systemPrompt,
+    }));
+  }
+}