elanous 0.2.42 → 0.2.44

package/src/core-turn/types.ts

@@ -125,6 +125,8 @@ export interface CoreTurnCallbacks {
  *  `src/core-turn/` never imports from dashboard / chat / tui /
  *  display — the headless guard test enforces this structurally. */
 export interface CoreTurnContext {
+  /** Caller-owned identity for correlating this turn's research and debug events. */
+  runId?: string;
   /** Identifier for the hosting session. Piped through for future
    *  correlation; the turn logic does not branch on it. */
   sessionId: string;
@@ -149,6 +151,8 @@ export interface CoreTurnContext {
   /** Optional provider request-size hook. Only providers with a measured
    *  serializer consume it; all others retain their existing request path. */
   requestSizeGuard?: LLMOpts['requestSizeGuard'];
+  /** Optional per-turn reasoning effort; high/xhigh/max also opts into the default deep Bloom frame. */
+  reasoningEffort?: LLMOpts['reasoningEffort'];
   /** Tool catalog the model may call this turn. Empty array means
    *  "text-only" — the loop delegates to plain `streamLLM`. */
   tools: LLMToolSpec[];

package/src/dashboard/chat/acp-chat.ts

@@ -89,6 +89,8 @@ export interface AcpChatHandlers {
   /** Append streamed assistant text. Caller accumulates + redraws.
    *  Receives each chunk exactly as the ACP agent emits it. */
   appendChunk: (delta: string) => void;
+  /** Replace the current streamed assistant answer with its authoritative final text. */
+  replaceText?: (fullText: string) => void;
   /** A goal iteration ended; fold only that interim reply in the visible pane. */
   foldGoalInterim?: (text: string) => void;
   /** Called once per tool_call event with a rendered label like
@@ -441,6 +443,14 @@ export class DashboardAcpChat {
         }
         const c = update.content;
         if (c.type === 'text') {
+          const meta = (update as typeof update & { _meta?: { elanous?: { textOperation?: unknown } } })._meta;
+          if (meta?.elanous?.textOperation === 'replace') {
+            this.closeStreamBuffer(sess, 'flush');
+            if (handlers.replaceText) handlers.replaceText(c.text);
+            else handlers.appendChunk(c.text);
+            handlers.redraw?.();
+            return;
+          }
           this.routeText(sess, c.text, handlers);
         }
         return;

package/src/dashboard/classic-sidetab-mission-job.ts

@@ -1,9 +1,110 @@
 import type { PendingTaskNotification } from '../agent/task-notification.js';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { debug } from '../debug/log.js';
 import { redactMissionResultPath, type StartedClassicMissionCliJob } from './mission-cli-consumer.js';
+import type { ClassicSidetabMissionResult } from './classic-sidetab-mission.js';
 
 export type ClassicMissionNotificationEnqueue = (notification: PendingTaskNotification) => void;
 export const CLASSIC_SIDETAB_MISSION_LABEL = 'sidetab mission';
+const CLASSIC_SIDETAB_PAIR_TIMEOUT_MS = 60 * 60 * 1_000;
+export interface ClassicSidetabMissionPairCompletionResult {
+  codex: ClassicSidetabMissionResult;
+  claude: ClassicSidetabMissionResult;
+  status: 'done' | 'error';
+  finishedAt: number;
+}
+type ClassicSidetabPairOutcome = ClassicSidetabMissionResult;
+interface ClassicSidetabMissionPairJob {
+  missionId?: string;
+  taskId: string;
+  parentSessionId?: string;
+  startedAt: number;
+  mission: string;
+  workspaceDir: string;
+  completion: Promise<ClassicSidetabPairOutcome>;
+}
+
+function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 80) || 'pair';
+}
+
+function resultFileLabel(workspaceDir: string, result: ClassicSidetabPairOutcome): string {
+  if (!result.path) return '없음';
+  const rel = relative(workspaceDir, result.path);
+  return rel && !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`) ? rel : basename(result.path);
+}
+
+function buildPairSynthesis(
+  pair: { codex: ClassicSidetabMissionPairJob; claude: ClassicSidetabMissionPairJob },
+  codex: ClassicSidetabPairOutcome,
+  claude: ClassicSidetabPairOutcome,
+): string {
+  const rows = [
+    { agent: 'Codex', job: pair.codex, result: codex },
+    { agent: 'Claude Code', job: pair.claude, result: claude },
+  ];
+  const cell = (value: string): string => value.replace(/[\r\n]+/g, ' ').trim().replaceAll('\\', '&#92;').replaceAll('|', '&#124;');
+  const table = rows.map(({ agent, job, result }) => {
+    const accepted = result.ok && Boolean(result.content?.trim());
+    const decision = accepted
+      ? '채택 — 별도 기여로 보존; 두 결과 간 우열을 임의 판정하지 않음'
+      : `미채택 — ${result.error ?? (result.ok ? '빈 결과' : '실패')}`;
+    const task = job.mission.length > 240 ? `${job.mission.slice(0, 240)}…` : job.mission;
+    return `| ${cell(agent)} | ${cell(task)} | ${cell(resultFileLabel(job.workspaceDir, result))} | ${accepted ? '성공' : '실패/빈 결과'} | ${cell(decision)} |`;
+  }).join('\n');
+  const contributions = rows.flatMap(({ agent, result }) => {
+    const content = result.ok ? result.content?.trim() : '';
+    if (!content) return [];
+    return [`## ${agent} 기여`, redactMissionResultPath(content, result.path)];
+  });
+  return [
+    '# Codex + Claude mission pair synthesis', '',
+    `- Codex mission: ${pair.codex.missionId ?? 'unavailable'}`,
+    `- Claude mission: ${pair.claude.missionId ?? 'unavailable'}`, '',
+    '## 비교·채택 표', '',
+    '| 손 | 맡은 작업 | 결과 파일 | 판정 | 채택 근거 |',
+    '|---|---|---|---|---|', table, '',
+    '채택 기준: 성공하고 비어 있지 않은 결과를 각자 독립 기여로 보존한다. 두 손의 답이 서로 다른 작업 분담에서 나온 경우 품질 순위를 추정하지 않으며, 실패·빈 결과는 채택하지 않고 사유를 남긴다.', '',
+    ...contributions.flatMap((section) => [section, '']),
+  ].join('\n').trimEnd() + '\n';
+}
+
+function persistPairSynthesis(
+  pair: { codex: ClassicSidetabMissionPairJob; claude: ClassicSidetabMissionPairJob },
+  taskId: string,
+  codex: ClassicSidetabPairOutcome,
+  claude: ClassicSidetabPairOutcome,
+): string {
+  if (typeof pair.codex.workspaceDir !== 'string' || !pair.codex.workspaceDir.trim()
+    || pair.codex.workspaceDir !== pair.claude.workspaceDir) {
+    throw new Error('pair members must share a workspace to persist one synthesis artifact');
+  }
+  const dir = join(pair.codex.workspaceDir, '.elanous', 'mission-results');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `classic-pair-synthesis-${safeFilePart(taskId)}-${randomUUID()}.md`);
+  writeFileSync(path, buildPairSynthesis(pair, codex, claude), { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  return path;
+}
+
+function compactPairNotification(status: 'done' | 'error', body: string, id: string): string {
+  const clean = (value: string): string => value.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
+  const payload = { status, body: clean(body), id: clean(id).slice(0, 80) || 'pair' };
+  let serialized = JSON.stringify(payload);
+  while (serialized.length > 500 && payload.body.length > 0) {
+    payload.body = payload.body.slice(0, -1);
+    serialized = JSON.stringify(payload);
+  }
+  return serialized;
+}
+
+function pairFailurePreview(name: string, result: ClassicSidetabPairOutcome): string {
+  const value = result.ok ? result.content?.trim() ?? '' : result.error ?? 'no result returned';
+  const redacted = redactMissionResultPath(value, result.path);
+  const clean = redacted.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim();
+  return `${name}: ${clean.slice(0, 110)}${clean.length > 110 ? '…' : ''}`;
+}
 
 /** Deliver one eventual sidetab result through the parent's existing task-notification input path. */
 export function enqueueClassicSidetabMissionCompletion(
@@ -56,3 +157,94 @@ export function enqueueClassicSidetabMissionCompletion(
     });
   });
 }
+
+/** Deliver a single combined parent notification after both parallel agents finish. */
+export function enqueueClassicSidetabMissionPairCompletion(
+  pair: { codex: ClassicSidetabMissionPairJob; claude: ClassicSidetabMissionPairJob },
+  enqueue: ClassicMissionNotificationEnqueue,
+  now: () => number = Date.now,
+  options: { timeoutMs?: number; onTimeout?: () => void; onComplete?: (result: ClassicSidetabMissionPairCompletionResult) => void } = {},
+): Promise<ClassicSidetabMissionPairCompletionResult> {
+  const taskId = pair.codex.taskId;
+  const startedAt = Math.min(pair.codex.startedAt, pair.claude.startedAt);
+  const timeoutMs = options.timeoutMs ?? CLASSIC_SIDETAB_PAIR_TIMEOUT_MS;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<[ClassicSidetabPairOutcome, ClassicSidetabPairOutcome]>((resolve) => {
+    timeout = setTimeout(() => {
+      try { options.onTimeout?.(); } catch { /* timeout cleanup cannot suppress the receipt */ }
+      const failure = (member: string): ClassicSidetabPairOutcome => ({ ok: false, status: 'failed', error: `${member} sidetab mission exceeded the one-hour safety timeout` });
+      resolve([failure('Codex'), failure('Claude')]);
+    }, Math.max(1, timeoutMs));
+  });
+  const rejected = (name: string) => (error: unknown): ClassicSidetabPairOutcome => ({
+    ok: false,
+    status: 'failed',
+    error: `${name} sidetab mission rejected: ${error instanceof Error ? error.message : String(error)}`,
+  });
+  return Promise.race([
+    Promise.all([pair.codex.completion.catch(rejected('Codex')), pair.claude.completion.catch(rejected('Claude'))]),
+    timedOut,
+  ]).then(([codex, claude]) => {
+    const finishedAt = now();
+    const bothSucceeded = codex.ok && claude.ok && Boolean(codex.content?.trim()) && Boolean(claude.content?.trim());
+    let synthesisPath: string | undefined;
+    let synthesisError: string | undefined;
+    try { synthesisPath = persistPairSynthesis(pair, taskId, codex, claude); }
+    catch (error) {
+      synthesisError = error instanceof Error ? error.message : String(error);
+      debug.log('classic-sidetab.mission-pair', 'synthesis-write-failed', { taskId, reason: synthesisError }, { level: 'warn' });
+    }
+    const ok = bothSucceeded && Boolean(synthesisPath);
+    const result: ClassicSidetabMissionPairCompletionResult = {
+      codex, claude, status: ok ? 'done' : 'error', finishedAt,
+    };
+    try { options.onComplete?.(result); }
+    catch { debug.log('classic-sidetab.mission-pair', 'completion-callback-failed', { taskId, retry: false }); }
+    const summary = synthesisPath
+      ? bothSucceeded ? 'Both missions completed. Full comparison attached.' : 'Pair completed with failures. Full comparison attached.'
+      : `Synthesis save failed; ${pairFailurePreview('Codex', codex)}; ${pairFailurePreview('Claude', claude)}`;
+    const output = compactPairNotification(ok ? 'done' : 'error', summary, pair.codex.missionId ?? pair.claude.missionId ?? taskId);
+    try {
+      enqueue({
+        taskId,
+        ...(pair.codex.parentSessionId ? { parentSessionId: pair.codex.parentSessionId } : {}),
+        agentName: 'Codex + Claude',
+        label: CLASSIC_SIDETAB_MISSION_LABEL,
+        state: ok ? 'done' : 'error',
+        output,
+        truncated: !synthesisPath,
+        ...(synthesisPath ? { resultPath: synthesisPath } : {}),
+        durationMs: Math.max(0, finishedAt - startedAt),
+        finishedAt,
+      });
+    } catch {
+      debug.log('classic-sidetab.mission-pair', 'completion-enqueue-failed', { taskId, retry: false });
+    }
+    return result;
+  }).catch(() => {
+    const finishedAt = now();
+    const failure = (error: string): ClassicSidetabMissionResult => ({ ok: false, status: 'failed', error });
+    const result: ClassicSidetabMissionPairCompletionResult = {
+      codex: failure('Codex/Claude pair failed before results were available'),
+      claude: failure('Codex/Claude pair failed before results were available'),
+      status: 'error', finishedAt,
+    };
+    try { options.onComplete?.(result); } catch { debug.log('classic-sidetab.mission-pair', 'completion-callback-failed', { taskId, retry: false }); }
+    try {
+      enqueue({
+        taskId,
+        ...(pair.codex.parentSessionId ? { parentSessionId: pair.codex.parentSessionId } : {}),
+        agentName: 'Codex + Claude',
+        label: CLASSIC_SIDETAB_MISSION_LABEL,
+        state: 'error',
+        output: compactPairNotification('error', 'Concurrent Codex/Claude missions failed before results were available', pair.codex.missionId ?? pair.claude.missionId ?? taskId),
+        truncated: false,
+        durationMs: Math.max(0, finishedAt - startedAt),
+        finishedAt,
+      });
+    } catch {
+      debug.log('classic-sidetab.mission-pair', 'completion-enqueue-failed', { taskId, retry: false });
+    }
+    return result;
+  }).finally(() => { if (timeout) clearTimeout(timeout); });
+}

package/src/dashboard/classic-sidetab-mission-pair.ts

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+import type { ClassicSidetabMissionPairResult, ClassicSidetabMissionPairSessionRegistry, ClassicSidetabMissionResult, ClassicSidetabMissionDispatchContext } from './classic-sidetab-mission.js';
+import { enqueueClassicSidetabMissionPairCompletion, type ClassicMissionNotificationEnqueue, type ClassicSidetabMissionPairCompletionResult } from './classic-sidetab-mission-job.js';
+
+interface ClassicSidetabPairSession {
+  id: string;
+  cwd: string;
+}
+
+export interface StartClassicSidetabMissionPairDeps<Session extends ClassicSidetabPairSession> {
+  agent: 'codex' | 'claude';
+  mission: string;
+  parallelMission: string;
+  context?: ClassicSidetabMissionDispatchContext;
+  spawnVisible: (agent: 'codex' | 'claude', missionId: string, attemptId: string) => Session | null;
+  runVisible: (agent: 'codex' | 'claude', prompt: string, session: Session | null, missionId?: string) => Promise<ClassicSidetabMissionResult>;
+  registry: ClassicSidetabMissionPairSessionRegistry;
+  hasSession: (sessionId: string) => boolean;
+  killSession: (sessionId: string) => void;
+  enqueue: ClassicMissionNotificationEnqueue;
+  now?: () => number;
+  createId?: () => string;
+  timeoutMs?: number;
+  onComplete?: (result: ClassicSidetabMissionPairCompletionResult) => void;
+}
+
+/** Production seam: start both visible PTYs, bind IDs/cancellation, and deliver one parent-linked completion receipt. */
+export function startClassicSidetabMissionPair<Session extends ClassicSidetabPairSession>(
+  deps: StartClassicSidetabMissionPairDeps<Session>,
+): { result: ClassicSidetabMissionPairResult; completion: Promise<ClassicSidetabMissionPairCompletionResult> } {
+  // Keep Codex as the last-opened PTY regardless of which mission prompt is
+  // primary. The dashboard closes each popup after spawn, detaching its modal
+  // while preserving the session in the sidetab registry. On the tested
+  // Codex-first demo path, opening Codex last avoids a missed follow-up
+  // completion marker; this is a sequencing workaround, not a fix for
+  // background PTY marker detection (tracked by SIDETAB-MARKER-BACKGROUND-DETECT).
+  const createId = deps.createId ?? randomUUID;
+  const codexMissionId = createId();
+  const claudeMissionId = createId();
+  const codexAttemptId = createId();
+  const claudeAttemptId = createId();
+  const claudeSession = deps.spawnVisible('claude', claudeMissionId, claudeAttemptId);
+  const codexSession = deps.spawnVisible('codex', codexMissionId, codexAttemptId);
+  const missionIds = [codexSession ? codexMissionId : undefined, claudeSession ? claudeMissionId : undefined].filter((id): id is string => Boolean(id));
+  const activeCodexMissionId = codexSession ? codexMissionId : undefined;
+  const activeClaudeMissionId = claudeSession ? claudeMissionId : undefined;
+  const sessionIds = [codexSession?.id, claudeSession?.id].filter((id): id is string => Boolean(id));
+  deps.registry.register(missionIds, sessionIds);
+
+  const codexPrompt = deps.agent === 'codex' ? deps.mission : deps.parallelMission;
+  const claudePrompt = deps.agent === 'claude' ? deps.mission : deps.parallelMission;
+  const startedAt = (deps.now ?? Date.now)();
+  const codexCompletion = deps.runVisible('codex', codexPrompt, codexSession, activeCodexMissionId);
+  const claudeCompletion = deps.runVisible('claude', claudePrompt, claudeSession, activeClaudeMissionId);
+  // callId is the parent tool invocation identity; falling back to a mission id
+  // preserves queue uniqueness for embedders that do not expose a call id.
+  const taskId = deps.context?.callId || activeCodexMissionId || activeClaudeMissionId || createId();
+  const workspaceDir = codexSession?.cwd ?? claudeSession?.cwd ?? '';
+  const completion = missionIds.length
+    ? enqueueClassicSidetabMissionPairCompletion({
+      codex: { missionId: activeCodexMissionId, taskId, parentSessionId: deps.context?.parentSessionId, startedAt, mission: codexPrompt, workspaceDir, completion: codexCompletion },
+      claude: { missionId: activeClaudeMissionId, taskId, parentSessionId: deps.context?.parentSessionId, startedAt, mission: claudePrompt, workspaceDir, completion: claudeCompletion },
+    }, deps.enqueue, deps.now, {
+      timeoutMs: deps.timeoutMs,
+      onTimeout: () => { for (const sessionId of sessionIds) if (deps.hasSession(sessionId)) deps.killSession(sessionId); },
+      ...(deps.onComplete ? { onComplete: deps.onComplete } : {}),
+    }).finally(() => deps.registry.clear(missionIds))
+    : Promise.resolve<ClassicSidetabMissionPairCompletionResult>({
+      codex: { ok: false, status: 'failed' as const, error: 'Codex sidetab PTY could not start' },
+      claude: { ok: false, status: 'failed' as const, error: 'Claude sidetab PTY could not start' },
+      status: 'error' as const, finishedAt: (deps.now ?? Date.now)(),
+    });
+
+  return {
+    result: {
+      pairId: `${activeCodexMissionId ?? 'codex-unavailable'}+${activeClaudeMissionId ?? 'claude-unavailable'}`,
+      codex: codexSession ? { ok: true, status: 'running', path: '', interactionId: activeCodexMissionId } : { ok: false, status: 'failed', error: 'Codex sidetab PTY could not start' },
+      claude: claudeSession ? { ok: true, status: 'running', path: '', interactionId: activeClaudeMissionId } : { ok: false, status: 'failed', error: 'Claude sidetab PTY could not start' },
+    },
+    completion,
+  };
+}

package/src/dashboard/classic-sidetab-mission-trio.ts

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import type { ClassicSidetabMissionDispatchContext, ClassicSidetabMissionPairSessionRegistry, ClassicSidetabMissionResult } from './classic-sidetab-mission.js';
+import { redactMissionResultPath } from './mission-cli-consumer.js';
+import type { ClassicMissionNotificationEnqueue } from './classic-sidetab-mission-job.js';
+
+export type ClassicMissionAgent = 'codex' | 'claude' | 'grok';
+
+interface TrioSession { id: string; cwd: string }
+interface MissionOutcome extends ClassicSidetabMissionResult { content?: string }
+const MAX_FINAL_SCREEN_CHARS = 4_000;
+
+export interface StartClassicSidetabMissionTrioDeps<Session extends TrioSession> {
+  mission: string;
+  context?: ClassicSidetabMissionDispatchContext;
+  checkGrokAuth: () => { ok: boolean; reason?: string } | Promise<{ ok: boolean; reason?: string }>;
+  spawnVisible: (agent: ClassicMissionAgent, missionId: string, attemptId: string) => Session | null;
+  runVisible: (agent: ClassicMissionAgent, mission: string, session: Session | null, missionId?: string) => Promise<MissionOutcome>;
+  registry: ClassicSidetabMissionPairSessionRegistry;
+  hasSession: (sessionId: string) => boolean;
+  killSession: (sessionId: string) => void;
+  enqueue: ClassicMissionNotificationEnqueue;
+  now?: () => number;
+  createId?: () => string;
+  timeoutMs?: number;
+}
+
+export interface ClassicSidetabMissionTrioStart {
+  trioId: string;
+  members: Record<ClassicMissionAgent, ClassicSidetabMissionResult>;
+  grokFallback?: string;
+}
+
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1_000;
+const MAX_ANSWER_CHARS = 8_000;
+
+function markdownCell(value: string | undefined): string {
+  return (value ?? '—').replaceAll('|', '\\|').replace(/\r?\n/g, '<br>');
+}
+
+function fenced(value: string): string {
+  const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}text\n${value}\n${fence}`;
+}
+
+function renderTrioSynthesis(mission: string, results: Record<ClassicMissionAgent, MissionOutcome>): string {
+  const agents: ClassicMissionAgent[] = ['codex', 'claude', 'grok'];
+  const rows = agents.map((agent) => {
+    const result = results[agent];
+    return `| ${agent} | ${markdownCell(mission)} | ${markdownCell(result.path)} | ${result.ok ? '완료' : markdownCell(result.error ?? result.status ?? '실패')} |  |`;
+  });
+  const candidates = agents.map((agent) => {
+    const result = results[agent];
+    return [`### ${agent}`, `- 결과 경로: ${result.path ?? '없음'}`, `- 상태: ${result.ok ? '완료' : result.error ?? result.status ?? '실패'}`, '', result.content?.trim() ? fenced(result.content.trim()) : '_결과 내용 없음_'].join('\n');
+  });
+  return [
+    '# Sidetab mission synthesis record',
+    '',
+    '## 요청',
+    fenced(mission),
+    '',
+    '## 손별 귀속',
+    '| 손 | 맡은 일 | 결과 파일 | 결과 상태 | 채택 여부 |',
+    '| --- | --- | --- | --- | --- |',
+    ...rows,
+    '',
+    '## 후보 결과',
+    ...candidates,
+    '',
+    '## 채택 결과',
+    '_최종 채택문은 알림을 받은 부모 응답에서 작성한다. 성공 후보가 있으면 이 후보들만 근거로 채택하고, 성공 후보가 하나면 그 결과를 그대로 채택한다._',
+    '',
+    '## 채택 근거',
+    '_후보별 상태와 원문은 위 표에 기록했다. 실패한 손은 채택 근거에서 제외한다._',
+    '',
+  ].join('\n');
+}
+
+function persistTrioSynthesis(cwd: string, trioId: string, mission: string, results: Record<ClassicMissionAgent, MissionOutcome>): string {
+  const safeId = trioId.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 120) || randomUUID();
+  const dir = join(cwd, '.elanous', 'mission-results');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `classic-trio-synthesis-${safeId}.md`);
+  writeFileSync(path, renderTrioSynthesis(mission, results), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  return path;
+}
+
+/** Starts three visible PTYs with one verbatim goal; an unavailable Grok degrades to Codex + Claude. */
+export async function startClassicSidetabMissionTrio<Session extends TrioSession>(
+  deps: StartClassicSidetabMissionTrioDeps<Session>,
+): Promise<{ result: ClassicSidetabMissionTrioStart; completion: Promise<void> }> {
+  const createId = deps.createId ?? randomUUID;
+  const now = deps.now ?? Date.now;
+  const startedAt = now();
+  // Start the first hand before the bounded subscribed-access probe. The
+  // probe may need a network round-trip, but must not consume the whole
+  // 30-second three-hand startup budget before any visible work begins.
+  const ids = new Map<ClassicMissionAgent, string>();
+  const sessions = new Map<ClassicMissionAgent, Session | null>();
+  const agents: ClassicMissionAgent[] = [];
+  const spawn = (agent: ClassicMissionAgent): Session | null => {
+    const missionId = createId();
+    ids.set(agent, missionId);
+    agents.push(agent);
+    const session = deps.spawnVisible(agent, missionId, createId());
+    if (!session) {
+      ids.delete(agent);
+      agents.pop();
+      return null;
+    }
+    sessions.set(agent, session);
+    return session;
+  };
+  spawn('claude');
+  spawn('codex');
+  const grokAuth = await deps.checkGrokAuth();
+  let grokFallback = grokAuth.ok ? undefined : grokAuth.reason ?? 'Grok login unavailable';
+  if (grokAuth.ok && !spawn('grok')) {
+    grokFallback = 'Grok sidetab PTY could not start';
+  }
+  const sessionIds = [...sessions.values()].flatMap((session) => session ? [session.id] : []);
+  const missionIds = [...ids.values()];
+  deps.registry.register(missionIds, sessionIds);
+  const outcomes = new Map<ClassicMissionAgent, Promise<MissionOutcome>>();
+  const completedOutcomes = new Map<ClassicMissionAgent, MissionOutcome>();
+  for (const agent of agents) {
+    const session = sessions.get(agent) ?? null;
+    if (agent === 'grok' && !session) continue;
+    const outcome = Promise.resolve().then(() => deps.runVisible(agent, deps.mission, session, ids.get(agent))).catch((error): MissionOutcome => ({
+      ok: false, status: 'failed', error: error instanceof Error ? error.message : String(error),
+    }));
+    outcomes.set(agent, outcome.then((result) => { completedOutcomes.set(agent, result); return result; }));
+  }
+  const members: Record<ClassicMissionAgent, ClassicSidetabMissionResult> = {
+    codex: sessions.get('codex') ? { ok: true, status: 'running', interactionId: ids.get('codex') } : { ok: false, status: 'failed', error: 'Codex sidetab PTY could not start' },
+    claude: sessions.get('claude') ? { ok: true, status: 'running', interactionId: ids.get('claude') } : { ok: false, status: 'failed', error: 'Claude sidetab PTY could not start' },
+    grok: sessions.get('grok') ? { ok: true, status: 'running', interactionId: ids.get('grok') } : { ok: false, status: 'failed', error: grokFallback ?? 'Grok sidetab PTY could not start' },
+  };
+  const taskId = deps.context?.callId || ids.get('codex') || ids.get('claude') || createId();
+  const timeoutMs = Math.max(1, deps.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<void>((resolve) => {
+    timeout = setTimeout(() => {
+      for (const sessionId of sessionIds) if (deps.hasSession(sessionId)) deps.killSession(sessionId);
+      resolve();
+    }, timeoutMs);
+  });
+  const settled = Promise.all([...outcomes].map(async ([agent, promise]) => [agent, await promise] as const));
+  const completion = Promise.race([settled.then((results) => ({ didTimeout: false, results })), timedOut.then(() => ({ didTimeout: true, results: [...completedOutcomes.entries()] as const }))]).then(({ didTimeout, results }) => {
+    const finishedAt = now();
+    const all: Record<ClassicMissionAgent, MissionOutcome> = {
+      codex: { ...members.codex, ...(members.codex.status === 'running' ? { error: undefined } : {}) },
+      claude: { ...members.claude, ...(members.claude.status === 'running' ? { error: undefined } : {}) },
+      grok: { ...members.grok, ...(members.grok.status === 'running' ? { error: undefined } : {}) },
+    };
+    for (const [agent, outcome] of results) all[agent] = outcome;
+    let synthesisPath: string | undefined;
+    let synthesisError: string | undefined;
+    const artifactCwd = [...sessions.values()].find((session): session is Session => Boolean(session))?.cwd;
+    if (artifactCwd) {
+      try {
+        const trioId = `trio-${ids.get('codex') ?? ids.get('claude') ?? createId()}`;
+        synthesisPath = persistTrioSynthesis(artifactCwd, trioId, deps.mission, all);
+        debug.log('classic-sidetab.mission-trio', 'synthesis-record-written', {
+          taskId,
+          trioId,
+          resultPath: synthesisPath,
+          candidateCount: Object.values(all).filter((result) => Boolean(result.path || result.content)).length,
+        });
+      } catch (error) {
+        synthesisError = error instanceof Error ? error.message : String(error);
+      }
+    } else {
+      synthesisError = 'no sidetab workspace was available for the synthesis record';
+    }
+    const timeoutReason = didTimeout ? 'mission exceeded the configured safety timeout' : undefined;
+    const answer = (agent: ClassicMissionAgent): string => {
+      const result = all[agent];
+      const screen = result.finalScreen?.trim();
+      const screenRecord = screen ? `\n\n${agent} final raw PTY screen:\n${screen.length > MAX_FINAL_SCREEN_CHARS ? `${screen.slice(-MAX_FINAL_SCREEN_CHARS)}\n[screen tail truncated]` : screen}` : '';
+      const initial = result.initialScreen?.trim();
+      const initialRecord = initial ? `\n\n${agent} first PTY snapshot:\n${initial.length > 1_200 ? `${initial.slice(-1_200)}\n[first screen tail truncated]` : initial}` : '';
+      if (timeoutReason && result.status === 'running') return `${agent}: ${timeoutReason}${initialRecord}${screenRecord}`;
+      if (!result.ok) return `${agent}: ${result.error ?? 'failed; no answer returned'}${initialRecord}${screenRecord}`;
+      const content = result.content?.trim();
+      if (!content) return `${agent}: completed without an answer${screenRecord}`;
+      const safe = redactMissionResultPath(content, result.path);
+      return `${agent} candidate:\n${safe.length > MAX_ANSWER_CHARS ? `${safe.slice(0, MAX_ANSWER_CHARS)}\n[answer truncated]` : safe}${initialRecord}${screenRecord}`;
+    };
+    const grokFailed = Boolean(grokFallback) || !all.grok.ok;
+    // When Grok cannot start, the run is explicitly a two-hand fallback;
+    // do not count the unstarted Grok hand as missing coverage or a failure.
+    const expectedAgents = grokFallback ? (['codex', 'claude'] as const) : (['codex', 'claude', 'grok'] as const);
+    const candidateAgents = expectedAgents.filter((agent) => all[agent].ok && Boolean(all[agent].content?.trim()));
+    const failedMembers = expectedAgents
+      .filter((agent) => !candidateAgents.includes(agent))
+      .map((agent) => ({
+        agent,
+        reason: timeoutReason && all[agent].status === 'running'
+          ? timeoutReason
+          : all[agent].error ?? (all[agent].ok ? 'completed without an answer' : all[agent].status ?? 'failed'),
+      }));
+    // A completed notification with at least one candidate lets the parent
+    // synthesize/adopt the available work. `coverage` describes partial runs;
+    // state and JSON status intentionally share the same done/error value.
+    const notificationStatus = candidateAgents.length > 0 ? 'done' : 'error';
+    const coverage = candidateAgents.length === 0 ? 'none' : candidateAgents.length === expectedAgents.length ? 'complete' : 'partial';
+    const body = [
+      `Three-hand comparison · same goal · ${grokFailed ? `Grok unavailable; continued with Codex + Claude (${all.grok.error ?? 'failed'})` : 'Codex + Claude + Grok results'}`,
+      `Coverage: ${coverage}; successful candidates: ${candidateAgents.length ? candidateAgents.join(', ') : 'none'}; failed members: ${failedMembers.length ? failedMembers.map(({ agent, reason }) => `${agent} (${reason})`).join('; ') : 'none'}.`,
+      synthesisPath ? `Synthesis record: ${synthesisPath}` : `Synthesis record unavailable: ${synthesisError ?? 'unknown write failure'}`,
+      candidateAgents.length > 0
+        ? 'Adopt or synthesize the final answer from the successful candidates only. If exactly one candidate succeeded, adopt it directly. Name failed members and never imply they succeeded.'
+        : 'No candidate succeeded; explicitly report that no result can be adopted.',
+      '', answer('codex'), '', answer('claude'), '', answer('grok'), '',
+      candidateAgents.length > 0 ? 'Present a non-empty adopted result and a short reason.' : 'Leave the adopted result explicitly unavailable; do not fabricate one.',
+    ].join('\n');
+    try {
+      deps.enqueue({
+        taskId,
+        ...(deps.context?.parentSessionId ? { parentSessionId: deps.context.parentSessionId } : {}),
+        agentName: grokFailed ? 'Codex + Claude (Grok fallback)' : 'Codex + Claude + Grok',
+        label: 'sidetab mission comparison',
+        state: notificationStatus,
+        output: JSON.stringify({ status: notificationStatus, coverage, successfulMembers: candidateAgents, failedMembers, body, artifacts: synthesisPath ? [synthesisPath] : [], id: ids.get('codex') ?? ids.get('claude') ?? taskId, grokFallback: grokFailed ? all.grok.error : undefined }),
+        ...(synthesisPath ? { resultPath: synthesisPath } : {}),
+        truncated: body.includes('[answer truncated]'),
+        durationMs: Math.max(0, finishedAt - startedAt),
+        finishedAt,
+      });
+    } catch { /* notification delivery cannot interrupt the missions */ }
+  }).finally(() => {
+    if (timeout) clearTimeout(timeout);
+    for (const sessionId of sessionIds) if (deps.hasSession(sessionId)) deps.killSession(sessionId);
+    deps.registry.clear(missionIds);
+  });
+
+  return { result: { trioId: `trio-${ids.get('codex') ?? ids.get('claude') ?? createId()}`, members, ...(grokFallback ? { grokFallback } : {}) }, completion };
+}