elanous 0.2.42 → 0.2.44

package/src/tui/sidetab/attach.ts

@@ -7,9 +7,11 @@ import { createTerminalModalRouter } from '../../terminal/terminal-modal-router.
 import { getSessionCwd } from '../../session/working-dir.js';
 import { TerminalSessionRegistry, type TerminalSession } from '../../terminal/session-registry.js';
 import { requestRemotePtyControl } from '../../pty-shell/pty-control-ipc.js';
-import { runVisibleAgentMission } from '../../sidetab-core/visible-agent-mission.js';
+import { runVisibleAgentMission, type VisibleMissionPty, type VisibleMissionResult } from '../../sidetab-core/visible-agent-mission.js';
+import { runVisibleAgentMissionPair } from '../../sidetab-core/visible-agent-mission-pair.js';
 import type { Key } from '../../tui.js';
 import type { SidetabRow } from './list.js';
+import { createHerdrSidetabPortal, herdrPaneIdFromSidetabRow, type HerdrSidetabPortal } from './herdr-portal.js';
 
 export type SidetabCharacter = 'shell' | 'elanous' | 'codex' | 'claude';
 
@@ -19,6 +21,7 @@ export interface SidetabAttachmentController {
   showMain(): void;
   spawn(character: SidetabCharacter): boolean;
   runMission(agent: 'codex' | 'claude', mission: string): Promise<Awaited<ReturnType<typeof runVisibleAgentMission>>>;
+  runMissionPair(agent: 'codex' | 'claude', mission: string, parallelMission: string): Promise<unknown>;
   kill(row: SidetabRow): boolean;
   handleKey(key: Key): boolean;
   hasModal(): boolean;
@@ -35,13 +38,35 @@ export interface AgentCliDetection {
   message: string;
 }
 
+export function sidetabMissionFailureLog(agent: 'codex' | 'claude', result: VisibleMissionResult): {
+  event: 'startup-screen-failed' | 'mission-failed';
+  data: Record<string, unknown>;
+} | undefined {
+  if (result.ok) return undefined;
+  const startupBlocked = !result.promptReady;
+  return {
+    event: startupBlocked ? 'startup-screen-failed' : 'mission-failed',
+    data: {
+      agent,
+      screen: startupBlocked ? result.startupScreen ?? 'unclassified' : 'none',
+      error: result.startupScreen && startupBlocked ? 'known-startup-screen-blocked' : startupBlocked ? 'startup-unclassified' : 'mission-or-result-failed',
+    },
+  };
+}
+
 export function createSidetabAttachmentController(deps: {
   drawBase(): void;
   termSize(): { cols: number; rows: number };
   setStatus(message: string): void;
   drawRemoteFrame(frame: string): void;
+  logEvent?(category: string, event: string, data: Record<string, unknown>): void;
+  herdrPortal?: HerdrSidetabPortal;
   /** Owned by OPT; a missing detector keeps the hook inert until its API lands. */
   detectAgentCli?(agent: 'codex' | 'claude'): Promise<AgentCliDetection>;
+  /** Test seam for exercising the visible mission path without launching an external CLI. */
+  createVisibleMissionPty?(agent: 'codex' | 'claude'): { pty: VisibleMissionPty; cwd: string };
+  /** Runner seam keeps the controller path testable with short deterministic mission timeouts. */
+  visibleMissionRunner?: typeof runVisibleAgentMission;
 }): SidetabAttachmentController {
   const eventBus = createDisplayEventBus();
   const coordinator = new DisplayCoordinator({
@@ -58,6 +83,23 @@ export function createSidetabAttachmentController(deps: {
   let remoteFrameTimer: ReturnType<typeof setInterval> | null = null;
   let remoteFramePending = false;
   let remoteHasFrame = false;
+  const herdrPortal = deps.herdrPortal ?? createHerdrSidetabPortal();
+  let herdrPaneId: string | null = null;
+  let herdrTakenOver = false;
+  let herdrFrameTimer: ReturnType<typeof setInterval> | null = null;
+  let herdrFramePending = false;
+  const herdrInputQueues = new Map<string, Promise<void>>();
+
+  const enqueueHerdrInput = (paneId: string, send: () => Promise<void>): void => {
+    const previous = herdrInputQueues.get(paneId) ?? Promise.resolve();
+    let current: Promise<void>;
+    current = previous.catch(() => {}).then(send).catch((error: unknown) => {
+      if (herdrPaneId === paneId) deps.setStatus(`Herdr 입력 실패 · ${error instanceof Error ? error.message : String(error)}`);
+    }).finally(() => {
+      if (herdrInputQueues.get(paneId) === current) herdrInputQueues.delete(paneId);
+    });
+    herdrInputQueues.set(paneId, current);
+  };
   let lastSpawnedSession: TerminalSession | null = null;
 
   const stopRemote = (): void => {
@@ -71,8 +113,42 @@ export function createSidetabAttachmentController(deps: {
     deps.drawRemoteFrame('');
   };
 
+  const stopHerdr = (): void => {
+    if (herdrFrameTimer !== null) clearInterval(herdrFrameTimer);
+    herdrFrameTimer = null;
+    herdrPaneId = null;
+    herdrTakenOver = false;
+    deps.drawRemoteFrame('');
+  };
+
+  const startHerdr = (row: SidetabRow): boolean => {
+    const paneId = herdrPaneIdFromSidetabRow(row);
+    if (!paneId || !herdrPortal.enabled()) {
+      deps.setStatus('Herdr 연결은 HERDR_ENV=1인 관리 세션에서만 사용할 수 있습니다');
+      return false;
+    }
+    stopRemote();
+    stopHerdr();
+    herdrPaneId = paneId;
+    const refresh = async (): Promise<void> => {
+      if (herdrFramePending || herdrPaneId !== paneId) return;
+      herdrFramePending = true;
+      try {
+        const frame = await herdrPortal.readPane(paneId);
+        if (herdrPaneId === paneId) deps.drawRemoteFrame(frame);
+      } catch (error) {
+        if (herdrPaneId === paneId) deps.setStatus(`Herdr pane 읽기 실패 · ${error instanceof Error ? error.message : String(error)}`);
+      } finally { herdrFramePending = false; }
+    };
+    void refresh();
+    herdrFrameTimer = setInterval(() => { void refresh(); }, 250);
+    deps.setStatus('Herdr pane 관측 · t takeover · Esc / Ctrl+\\ 복귀 · Ctrl+Q 전체 종료 (Ctrl+[는 Esc로 읽힐 수 있음)');
+    return true;
+  };
+
   const startRemote = (row: SidetabRow): boolean => {
     if (!row.ptyId) return false;
+    stopHerdr();
     stopRemote();
     remotePtyId = row.ptyId;
     const id = row.ptyId;
@@ -192,6 +268,7 @@ export function createSidetabAttachmentController(deps: {
   return {
     attach(row) {
       stopRemote();
+      if (row.kind === 'herdr') return startHerdr(row);
       if (row.currentProcess) {
         showMain();
         return true;
@@ -210,6 +287,7 @@ export function createSidetabAttachmentController(deps: {
       return attached ? setModal(attached) : false;
     },
     select(row) {
+      if (row.kind === 'herdr') return startHerdr(row);
       if (row.ptyId && !row.currentProcess && !sessionForRow(row)) return startRemote(row);
       if (row.currentProcess) {
         showMain();
@@ -226,31 +304,156 @@ export function createSidetabAttachmentController(deps: {
         catch (error) {
           const message = `${agent} CLI 확인에 실패했습니다: ${error instanceof Error ? error.message : String(error)}`;
           deps.setStatus(message);
-          return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: message };
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: message };
         }
         if (!detection.installed) {
           const message = `${detection.message} · 설치 확인 후 미션을 다시 요청하세요`;
           deps.setStatus(message);
-          return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: message };
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: message };
         }
       }
       lastSpawnedSession = null;
-      if (!spawn(agent) || !lastSpawnedSession?.modal) {
-        return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: `${agent} side-tab PTY could not start` };
+      const injectedMissionPty = deps.createVisibleMissionPty?.(agent);
+      let modal: VisibleMissionPty;
+      let cwd: string;
+      if (injectedMissionPty) {
+        modal = injectedMissionPty.pty;
+        cwd = injectedMissionPty.cwd;
+      } else {
+        const spawned = spawn(agent);
+        const session = lastSpawnedSession as TerminalSession | null;
+        if (!spawned || !session?.modal) {
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: `${agent} side-tab PTY could not start` };
+        }
+        modal = session.modal;
+        cwd = session.cwd;
       }
-      const session = lastSpawnedSession;
-      const outputPath = join(session.cwd, '.elanous', 'mission-results', `sidetab-${Date.now()}.md`);
+      const outputPath = join(cwd, '.elanous', 'mission-results', `sidetab-${Date.now()}.md`);
       const backend = agent === 'codex' ? codexBackend : claudeBackend;
-      const result = await runVisibleAgentMission({
-        pty: session.modal,
+      const result = await (deps.visibleMissionRunner ?? runVisibleAgentMission)({
+        pty: modal,
+        agent,
         mission,
         outputPath,
+        onStartupScreen: (screen) => deps.logEvent?.('agent-mission.sidetab', 'startup-screen', { agent, screen }),
         handleTrust: (screen, write) => backend.handleTrust?.(screen, write) ?? false,
       });
+      const failureLog = sidetabMissionFailureLog(agent, result);
+      if (failureLog) deps.logEvent?.('agent-mission.sidetab', failureLog.event, failureLog.data);
       showMain();
-      deps.setStatus(result.ok ? `미션 결과 확인 · ${result.path}` : `미션 확인 실패 · ${result.error}`);
+      deps.setStatus(result.ok ? `미션 결과 확인 · ${result.path}` : `미션 확인 실패 · ${result.promptReady ? agent : result.startupScreen ?? agent} · ${result.error}`);
       return result;
     },
+    async runMissionPair(agent, mission, parallelMission) {
+      const missionId = `duo-${randomUUID()}`;
+      const startedAt = Date.now();
+      const members = [agent, agent === 'codex' ? 'claude' : 'codex'] as const;
+      if (deps.detectAgentCli) {
+        const detections = await Promise.all(members.map(async (member) => {
+          try { return await deps.detectAgentCli!(member); }
+          catch (error) {
+            return { agent: member, installed: false, version: null, login: 'unknown' as const,
+              message: `${member} CLI 확인에 실패했습니다: ${error instanceof Error ? error.message : String(error)}` };
+          }
+        }));
+        const unavailable = detections.find(({ installed }) => !installed);
+        if (unavailable) {
+          const message = `${unavailable.message} · pair 미션은 두 CLI 모두 준비돼야 시작합니다`;
+          deps.setStatus(message);
+          return { ok: false, error: message, codex: null, claude: null };
+        }
+      }
+
+      const sessions = new Map<'codex' | 'claude', TerminalSession>();
+      const workspaces = new Map<'codex' | 'claude', string>();
+      const ptySessions = new Map<VisibleMissionPty, TerminalSession>();
+      const pair = await runVisibleAgentMissionPair({
+        spawn: (member) => {
+          lastSpawnedSession = null;
+          const injected = deps.createVisibleMissionPty?.(member);
+          if (injected) {
+            workspaces.set(member, injected.cwd);
+            return injected.pty;
+          }
+          const didSpawn = spawn(member);
+          const session = lastSpawnedSession as TerminalSession | null;
+          if (!didSpawn || !session) return null;
+          sessions.set(member, session);
+          workspaces.set(member, session.cwd);
+          const pty: VisibleMissionPty = {
+            snapshot: () => session.preview.renderForLLM(),
+            write: (bytes) => session.preview.write(bytes),
+            isAlive: () => session.preview.isAlive,
+          };
+          ptySessions.set(pty, session);
+          return pty;
+        },
+        dispose: (preview) => {
+          const session = ptySessions.get(preview);
+          if (session) registry.kill(session.id);
+        },
+        run: async (member, prompt, pty) => {
+          const outputPath = join(workspaces.get(member)!, '.elanous', 'mission-results', `sidetab-pair-${randomUUID()}-${member}.md`);
+          const backend = member === 'codex' ? codexBackend : claudeBackend;
+          const result = await (deps.visibleMissionRunner ?? runVisibleAgentMission)({
+            pty, agent: member, mission: prompt, outputPath,
+            onStartupScreen: (screen) => deps.logEvent?.('agent-mission.sidetab-pair', 'startup-screen', { agent: member, screen }),
+            handleTrust: (screen, write) => backend.handleTrust?.(screen, write) ?? false,
+          });
+          const failureLog = sidetabMissionFailureLog(member, result);
+          if (failureLog) deps.logEvent?.('agent-mission.sidetab-pair', failureLog.event, failureLog.data);
+          return result;
+        },
+      }, agent, mission, parallelMission);
+      if (pair.error) {
+        showMain();
+        deps.setStatus(pair.error);
+        return pair;
+      }
+      const codexWorkspace = workspaces.get('codex');
+      const claudeWorkspace = workspaces.get('claude');
+      if (!codexWorkspace || !claudeWorkspace || codexWorkspace !== claudeWorkspace) {
+        showMain();
+        const error = '두 사이드탭이 같은 작업 디렉터리를 쓰지 않아 pair 합성을 안전하게 저장할 수 없습니다';
+        deps.setStatus(error);
+        return { ...pair, ok: false, error };
+      }
+      const missionByAgent = new Map([ [agent, mission], [agent === 'codex' ? 'claude' : 'codex', parallelMission] ] as const);
+      const completion = await (await import('../../tui-client/next-dashboard-runtime.js')).completeNextTuiMissionPair({
+        taskId: missionId,
+        codex: {
+          missionId: `${missionId}-codex`, startedAt,
+          mission: missionByAgent.get('codex')!, workspaceDir: codexWorkspace, result: pair.codex!,
+        },
+        claude: {
+          missionId: `${missionId}-claude`, startedAt,
+          mission: missionByAgent.get('claude')!, workspaceDir: claudeWorkspace, result: pair.claude!,
+        },
+      });
+      const notification = completion.notification;
+      const finalFile = notification?.resultPath;
+      deps.logEvent?.('agent-mission.sidetab-pair', 'synthesis-result', {
+        missionId, codexOk: pair.codex?.ok ?? false, claudeOk: pair.claude?.ok ?? false,
+        synthesisOk: Boolean(finalFile), status: completion.status,
+      });
+      showMain();
+      deps.setStatus(finalFile
+        ? `그래프 두 갈래·비교 합성 완료 · ${finalFile}`
+        : '그래프 두 갈래 완료 · 기존 pair 합성 파일 저장 실패');
+      return {
+        ...pair,
+        ok: pair.ok && completion.status === 'done' && Boolean(finalFile),
+        pair: 'codex+claude',
+        graph: [
+          { id: 'plan', state: 'complete', task: `${mission} ⊕ ${parallelMission}` },
+          { id: 'codex', state: pair.codex?.ok ? 'complete' : 'failed', task: missionByAgent.get('codex'), resultFile: pair.codex?.path },
+          { id: 'claude', state: pair.claude?.ok ? 'complete' : 'failed', task: missionByAgent.get('claude'), resultFile: pair.claude?.path },
+          { id: 'synthesis', state: finalFile ? 'complete' : 'failed', resultFile: finalFile },
+        ],
+        finalFile,
+        summary: notification?.output,
+      };
+    },
     kill(row) {
       if (row.currentProcess) {
         deps.setStatus('현재 TUI 세션은 사이드탭에서 종료할 수 없습니다');
@@ -276,6 +479,42 @@ export function createSidetabAttachmentController(deps: {
       return true;
     },
     handleKey(key) {
+      if (herdrPaneId) {
+        if (key.name.toLowerCase() === 'escape') {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return true;
+        }
+        if (key.ctrl && key.name.toLowerCase() === 'q') {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return false;
+        }
+        if (key.ctrl && (key.name === '\\' || key.raw === '\x1c')) {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return false;
+        }
+        if (key.name.toLowerCase() === 't' && !herdrTakenOver) {
+          herdrTakenOver = true;
+          deps.setStatus('Herdr pane takeover · Esc로 복귀');
+          return true;
+        }
+        const raw = key.raw;
+        if (herdrTakenOver && raw) {
+          const paneId = herdrPaneId;
+          if (raw.includes('\x00')) {
+            deps.setStatus('NUL 입력은 Herdr pane에 보낼 수 없습니다');
+            return true;
+          }
+          const send = (raw.length === 1 && (raw.charCodeAt(0) < 32 || raw.charCodeAt(0) === 0x7f)) || raw.startsWith('\x1b')
+            ? () => herdrPortal.sendKey(paneId, raw)
+            : () => herdrPortal.sendText(paneId, raw);
+          enqueueHerdrInput(paneId, send);
+          return true;
+        }
+        return true;
+      }
       if (remotePtyId) {
         // Keep global TUI controls reachable while a remote snapshot is displayed.
         if (key.ctrl && key.name.toLowerCase() === 'q') return false;
@@ -329,10 +568,11 @@ export function createSidetabAttachmentController(deps: {
       return routed !== 'passthrough';
     },
     hasModal: () => modalRouter.current() !== null,
-    hasRemoteView: () => remotePtyId !== null,
+    hasRemoteView: () => remotePtyId !== null || herdrPaneId !== null,
     refresh: () => coordinator.requestRenderNow({ force: true }),
     close() {
       stopRemote();
+      stopHerdr();
       modalRouter.close();
       for (const session of registry.list()) registry.kill(session.id);
     },
@@ -340,6 +580,7 @@ export function createSidetabAttachmentController(deps: {
 
   function showMain(): void {
     stopRemote();
+    stopHerdr();
     if (attachedSessionId === null) return;
     modalRouter.close();
     coordinator.requestRenderNow({ force: true });

package/src/tui/sidetab/herdr-portal.ts

@@ -0,0 +1,225 @@
+import { defaultHerdrCliRunner, type HerdrCliRunner } from '../../pty-shell/herdr-prompt.js';
+import type { SidetabRow } from '../../sidetab-core/model.js';
+
+const HERDR_ROW_PREFIX = 'herdr:';
+const SNAPSHOT_TIMEOUT_MS = 1_500;
+const PANE_READ_TIMEOUT_MS = 1_000;
+const PANE_INPUT_TIMEOUT_MS = 1_000;
+
+export type HerdrSidetabStatus =
+  | 'working' | 'idle' | 'needs-approval' | 'done-verified' | 'done-unverified' | 'stopped' | 'unknown';
+
+export interface HerdrPaneSnapshot {
+  readonly pane_id: string;
+  readonly workspace_id?: string;
+  readonly agent?: string;
+  readonly agent_status?: string;
+  readonly terminal_title?: string;
+  readonly terminal_title_stripped?: string;
+  readonly cwd?: string;
+  readonly alive?: boolean;
+  readonly cost_usd?: number;
+  readonly costUsd?: number;
+  readonly cost?: number;
+  readonly [key: string]: unknown;
+}
+
+export interface HerdrSidetabPortalOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly run?: HerdrCliRunner;
+  /** Independent completion evidence; Herdr's own `done` report is never treated as verification. */
+  readonly isVerified?: (pane: HerdrPaneSnapshot) => boolean;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+export interface HerdrSidetabPortal {
+  enabled(): boolean;
+  refreshRows(): Promise<readonly SidetabRow[]>;
+  rows(): readonly SidetabRow[];
+  readPane(paneId: string): Promise<string>;
+  sendText(paneId: string, text: string): Promise<void>;
+  sendKey(paneId: string, key: string): Promise<void>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function paneRowsFromSnapshot(value: unknown): HerdrPaneSnapshot[] {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  if (!result) throw new Error('Herdr snapshot 형식 오류 · result 객체가 없습니다');
+  const session = asRecord(result?.session_snapshot);
+  const panes = result?.panes ?? session?.panes;
+  if (!Array.isArray(panes)) throw new Error('Herdr snapshot 형식 오류 · panes 배열이 없습니다');
+  const invalidPane = panes.findIndex((candidate) => {
+    const pane = asRecord(candidate);
+    return typeof pane?.pane_id !== 'string' || pane.pane_id.length === 0;
+  });
+  if (invalidPane >= 0) throw new Error(`Herdr snapshot 형식 오류 · panes[${invalidPane}].pane_id가 없습니다`);
+  return panes as HerdrPaneSnapshot[];
+}
+
+function statusOf(pane: HerdrPaneSnapshot, verified: boolean): HerdrSidetabStatus {
+  const state = (pane.agent_status ?? '').trim().toLowerCase().replaceAll('_', '-');
+  // Approval is a first-class state. Never collapse it into idle, even if a pane has no running process.
+  if (state === 'blocked' || state === 'needs-approval' || state === 'approval-required') return 'needs-approval';
+  // A completed pane remains completed after its process exits. Herdr's `done` is not verification.
+  if (state === 'done' || state === 'complete' || state === 'completed') return verified ? 'done-verified' : 'done-unverified';
+  if (pane.alive === false || state === 'stopped' || state === 'exited') return 'stopped';
+  if (state === 'working' || state === 'busy') return 'working';
+  if (state === 'idle') return 'idle';
+  return 'unknown';
+}
+
+function displayState(status: HerdrSidetabStatus): { badge: SidetabRow['badge']; label: string } {
+  switch (status) {
+    case 'working': return { badge: 'busy', label: '실행 중' };
+    case 'idle': return { badge: 'idle', label: '대기' };
+    case 'needs-approval': return { badge: 'busy', label: '승인 필요' };
+    case 'done-verified': return { badge: 'idle', label: '검증 완료' };
+    case 'done-unverified': return { badge: 'unknown', label: '미검증 완료' };
+    case 'stopped': return { badge: 'exited', label: '멈춤' };
+    case 'unknown': return { badge: 'unknown', label: '상태 미상' };
+  }
+}
+
+function finiteCost(pane: HerdrPaneSnapshot): number | undefined {
+  for (const value of [pane.cost_usd, pane.costUsd, pane.cost]) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
+  }
+  return undefined;
+}
+
+function rowFromPane(pane: HerdrPaneSnapshot, verified: boolean): SidetabRow {
+  const status = statusOf(pane, verified);
+  const display = displayState(status);
+  const title = pane.terminal_title_stripped || pane.terminal_title || pane.agent || pane.pane_id;
+  const cost = finiteCost(pane);
+  const costText = cost === undefined ? '비용 —' : `비용 $${cost.toFixed(2)}`;
+  return {
+    id: `${HERDR_ROW_PREFIX}${pane.pane_id}`,
+    label: `Herdr · ${display.label} · ${title} · ${costText}`,
+    kind: 'herdr',
+    badge: display.badge,
+  };
+}
+
+function paneIdFromRow(row: SidetabRow): string | undefined {
+  if (row.kind !== 'herdr' || !row.id.startsWith(HERDR_ROW_PREFIX)) return undefined;
+  const id = row.id.slice(HERDR_ROW_PREFIX.length);
+  return /^w[A-Za-z0-9_-]+:p[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
+}
+
+function commandOutput(result: { code: number | null; stdout: string; stderr: string }): string {
+  if (result.code !== 0) {
+    const body = result.stderr.trim();
+    let message = body || `herdr exited with rc=${result.code ?? 'unknown'}`;
+    if (body.startsWith('{')) {
+      try {
+        const error = asRecord(asRecord(JSON.parse(body))?.error);
+        if (typeof error?.message === 'string') message = error.message;
+      } catch { /* preserve stderr */ }
+    }
+    throw new Error(message);
+  }
+  const text = result.stdout.trim();
+  if (!text.startsWith('{')) return text;
+  try {
+    const resultEnvelope = asRecord(asRecord(JSON.parse(text))?.result);
+    for (const key of ['text', 'output', 'screen', 'content'] as const) {
+      if (typeof resultEnvelope?.[key] === 'string') return resultEnvelope[key] as string;
+    }
+  } catch { /* plain terminal text may begin with a brace */ }
+  return text;
+}
+
+function logicalKey(key: string): string {
+  const aliases: Record<string, string> = {
+    '\r': 'enter', '\n': 'enter', '\x1b': 'esc', '\x7f': 'backspace', '\t': 'tab',
+    '\x03': 'ctrl+c', '\x04': 'ctrl+d', '\x1b[A': 'up', '\x1bOA': 'up', '\x1b[B': 'down', '\x1bOB': 'down',
+    '\x1b[C': 'right', '\x1bOC': 'right', '\x1b[D': 'left', '\x1bOD': 'left',
+  };
+  const mapped = aliases[key];
+  if (mapped) return mapped;
+  if (key.startsWith('\x1b')) throw new Error('지원되지 않는 Herdr escape key입니다');
+  return key;
+}
+
+export function createHerdrSidetabPortal(options: HerdrSidetabPortalOptions = {}): HerdrSidetabPortal {
+  const env = options.env ?? process.env;
+  const run = options.run ?? defaultHerdrCliRunner(env);
+  const isVerified = options.isVerified ?? (() => false);
+  const log = options.log ?? (() => {});
+  let cachedRows: SidetabRow[] = [];
+  let snapshotError: string | null = null;
+  let refreshPending: Promise<readonly SidetabRow[]> | null = null;
+
+  const visibleRows = (): SidetabRow[] => {
+    const rows = snapshotError
+      ? cachedRows.map((row) => ({ ...row, label: `${row.label} · 오래된 스냅샷` }))
+      : [...cachedRows];
+    if (snapshotError) {
+      rows.push({
+        id: 'herdr:snapshot-status',
+        label: `Herdr · snapshot 갱신 실패 · ${snapshotError}`,
+        kind: 'status',
+        badge: 'unknown',
+      });
+    }
+    return rows;
+  };
+
+  const requireEnabledPane = (paneId: string): void => {
+    if (env.HERDR_ENV !== '1') throw new Error('Herdr 포털은 Herdr 관리 pane 안에서만 사용할 수 있습니다');
+    if (!/^w[A-Za-z0-9_-]+:p[A-Za-z0-9_-]+$/.test(paneId)) throw new Error('Herdr pane id가 올바르지 않습니다');
+  };
+
+  return {
+    enabled: () => env.HERDR_ENV === '1',
+    async refreshRows() {
+      if (env.HERDR_ENV !== '1') return [];
+      if (refreshPending) return refreshPending;
+      refreshPending = (async () => {
+        const result = await run(['api', 'snapshot'], SNAPSHOT_TIMEOUT_MS);
+        const output = commandOutput(result);
+        let snapshot: unknown;
+        try { snapshot = JSON.parse(output); }
+        catch { throw new Error('Herdr snapshot 형식 오류 · JSON을 읽을 수 없습니다'); }
+        const panes = paneRowsFromSnapshot(snapshot);
+        cachedRows = panes.map((pane) => rowFromPane(pane, isVerified(pane)));
+        snapshotError = null;
+        log('snapshot', { panes: cachedRows.length });
+        return visibleRows();
+      })().catch((error: unknown) => {
+        snapshotError = (error instanceof Error ? error.message : String(error)).replace(/[\r\n\t]/g, ' ').slice(0, 160);
+        log('snapshot-failed', { error: snapshotError });
+        return visibleRows();
+      }).finally(() => { refreshPending = null; });
+      return refreshPending;
+    },
+    rows: visibleRows,
+    async readPane(paneId) {
+      requireEnabledPane(paneId);
+      const result = await run(['pane', 'read', paneId, '--source', 'visible', '--format', 'ansi'], PANE_READ_TIMEOUT_MS);
+      return commandOutput(result);
+    },
+    async sendText(paneId, text) {
+      requireEnabledPane(paneId);
+      if (!text) return;
+      const result = await run(['pane', 'send-text', paneId, text], PANE_INPUT_TIMEOUT_MS);
+      commandOutput(result);
+    },
+    async sendKey(paneId, key) {
+      requireEnabledPane(paneId);
+      const normalized = logicalKey(key);
+      if (!normalized) return;
+      const result = await run(['pane', 'send-keys', paneId, normalized], PANE_INPUT_TIMEOUT_MS);
+      commandOutput(result);
+    },
+  };
+}
+
+export function herdrPaneIdFromSidetabRow(row: SidetabRow): string | undefined {
+  return paneIdFromRow(row);
+}

package/src/tui/sidetab/list.ts

@@ -4,6 +4,7 @@ import {
   formatSidetabLines as formatCoreSidetabLines,
   loadSidetabRows as loadCoreSidetabRows,
   type SidetabRow,
+  type SidetabScope,
 } from '../../sidetab-core/model.js';
 import { listPtyManifestRows } from '../../pty-shell/pty-manifest.js';
 import { formatSidetabPeekLines } from './peek.js';
@@ -11,9 +12,9 @@ import { formatSidetabPeekLines } from './peek.js';
 type PreviewSidetabRow = SidetabRow & { readonly previewSource?: string };
 
 /** Attach the latest manifest snapshot without changing the shared row contract. */
-export function loadSidetabRows(all = false, currentSessionId?: string): SidetabRow[] {
+export function loadSidetabRows(all = false, currentSessionId?: string, scopeOverrides?: Partial<SidetabScope>): SidetabRow[] {
   const snapshots = new Map<string, string>(listPtyManifestRows().map((row) => [row.id, row.snapshot || row.frame] as const));
-  return loadCoreSidetabRows(all, currentSessionId).map((row) => ({
+  return loadCoreSidetabRows(all, currentSessionId, scopeOverrides).map((row) => ({
     ...row,
     previewSource: snapshots.get(row.id) ?? '',
   }));

package/src/tui-client/next-dashboard-runtime.ts

@@ -1,4 +1,56 @@
 /** Dashboard integrations used by next TUI, loaded only after that surface is opened. */
+import type { PendingTaskNotification } from '../agent/task-notification.js';
+import type { VisibleMissionResult } from '../sidetab-core/visible-agent-mission.js';
+
+export interface NextTuiMissionPairMember {
+  missionId: string;
+  mission: string;
+  workspaceDir: string;
+  startedAt: number;
+  result: VisibleMissionResult;
+}
+
+export interface NextTuiMissionPairCompletionInput {
+  taskId: string;
+  codex: NextTuiMissionPairMember;
+  claude: NextTuiMissionPairMember;
+}
+
+export interface NextTuiMissionPairCompletionResult {
+  status: 'done' | 'error';
+  notification?: PendingTaskNotification;
+}
+
+/** Keep the next-TUI sidetab controller on the dashboard facade, not dashboard internals. */
+export async function completeNextTuiMissionPair(
+  input: NextTuiMissionPairCompletionInput,
+): Promise<NextTuiMissionPairCompletionResult> {
+  const { enqueueClassicSidetabMissionPairCompletion } = await import('../dashboard/classic-sidetab-mission-job.js');
+  const asClassicResult = (result: VisibleMissionResult) => ({
+    ok: result.ok,
+    status: result.ok ? 'completed' as const : 'failed' as const,
+    ...(result.path ? { path: result.path } : {}),
+    ...(result.content !== undefined ? { content: result.content } : {}),
+    ...(result.error ? { error: result.error } : {}),
+    ...(result.failureStage ? { failureStage: result.failureStage } : {}),
+    ...(result.failureScreen ? { failureScreen: result.failureScreen } : {}),
+  });
+  let notification: PendingTaskNotification | undefined;
+  const completion = await enqueueClassicSidetabMissionPairCompletion({
+    codex: {
+      missionId: input.codex.missionId, taskId: input.taskId, startedAt: input.codex.startedAt,
+      mission: input.codex.mission, workspaceDir: input.codex.workspaceDir,
+      completion: Promise.resolve(asClassicResult(input.codex.result)),
+    },
+    claude: {
+      missionId: input.claude.missionId, taskId: input.taskId, startedAt: input.claude.startedAt,
+      mission: input.claude.mission, workspaceDir: input.claude.workspaceDir,
+      completion: Promise.resolve(asClassicResult(input.claude.result)),
+    },
+  }, item => { notification = item; });
+  return { status: completion.status, ...(notification ? { notification } : {}) };
+}
+
 export async function loadNextTuiDashboardRuntime() {
   const [segments, goalContinue] = await Promise.all([
     import('../dashboard/turn-start-segments.js'),