elanous 0.2.41 → 0.2.43

package/src/tui/sidetab/attach.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
 import { resolveBackendSpawn, claudeBackend, codexBackend } from '../../agent-mission/driver.js';
 import { DisplayCoordinator } from '../../display/coordinator.js';
 import { createDisplayEventBus } from '../../display/events.js';
@@ -6,8 +7,10 @@ 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, type VisibleMissionPty, type VisibleMissionResult } from '../../sidetab-core/visible-agent-mission.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';
 
@@ -16,6 +19,7 @@ export interface SidetabAttachmentController {
   select(row: SidetabRow): boolean;
   showMain(): void;
   spawn(character: SidetabCharacter): boolean;
+  runMission(agent: 'codex' | 'claude', mission: string): Promise<Awaited<ReturnType<typeof runVisibleAgentMission>>>;
   kill(row: SidetabRow): boolean;
   handleKey(key: Key): boolean;
   hasModal(): boolean;
@@ -24,11 +28,43 @@ export interface SidetabAttachmentController {
   close(): void;
 }
 
+export interface AgentCliDetection {
+  agent: 'codex' | 'claude';
+  installed: boolean;
+  version: string | null;
+  login: 'ready' | 'needed' | 'unknown';
+  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({
@@ -45,6 +81,24 @@ 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 => {
     if (remoteFrameTimer !== null) clearInterval(remoteFrameTimer);
@@ -57,8 +111,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;
@@ -164,6 +252,7 @@ export function createSidetabAttachmentController(deps: {
           }
         },
       }, { termCols: cols, termRows: rows });
+      lastSpawnedSession = session;
       if (character === 'codex' || character === 'claude') {
         deps.setStatus(`${character} 실행 · agent-mission 구독 경로 scrub 적용(${unsetEnv?.length ?? 0}개 env 제거)`);
       }
@@ -177,6 +266,7 @@ export function createSidetabAttachmentController(deps: {
   return {
     attach(row) {
       stopRemote();
+      if (row.kind === 'herdr') return startHerdr(row);
       if (row.currentProcess) {
         showMain();
         return true;
@@ -195,6 +285,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();
@@ -204,6 +295,53 @@ export function createSidetabAttachmentController(deps: {
     },
     showMain,
     spawn,
+    async runMission(agent, mission) {
+      if (deps.detectAgentCli) {
+        let detection: AgentCliDetection;
+        try { detection = await deps.detectAgentCli(agent); }
+        catch (error) {
+          const message = `${agent} CLI 확인에 실패했습니다: ${error instanceof Error ? error.message : String(error)}`;
+          deps.setStatus(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, promptReturned: false, completionMarker: false, error: message };
+        }
+      }
+      lastSpawnedSession = null;
+      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 outputPath = join(cwd, '.elanous', 'mission-results', `sidetab-${Date.now()}.md`);
+      const backend = agent === 'codex' ? codexBackend : claudeBackend;
+      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.promptReady ? agent : result.startupScreen ?? agent} · ${result.error}`);
+      return result;
+    },
     kill(row) {
       if (row.currentProcess) {
         deps.setStatus('현재 TUI 세션은 사이드탭에서 종료할 수 없습니다');
@@ -229,6 +367,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;
@@ -282,10 +456,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);
     },
@@ -293,6 +468,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-client/local-chat-turn.ts

@@ -6,11 +6,17 @@ import { answerNextSidetabCall, isNextSidetabCall, type NextSidetabHandler } fro
 
 const STATUS_PREFIX = 'ELANOUS_TUI_BG_STATUS\t';
 let nextSidetabHandler: NextSidetabHandler | null = null;
+let nextSidetabIpcEnabled = false;
 
 export function setNextSidetabHandler(handler: NextSidetabHandler | null): void {
   nextSidetabHandler = handler;
 }
 
+/** The Next TUI host enables this before any sticky REPL child is created. */
+export function setNextSidetabIpcEnabled(enabled: boolean): void {
+  nextSidetabIpcEnabled = enabled;
+}
+
 interface TurnResult {
   event?: string | null;
   turnId?: string | null;
@@ -23,7 +29,7 @@ interface TurnResult {
 }
 interface WaitingTurn {
   turnId: string;
-  onDelta?: (text: string) => void;
+  onDelta?: (text: string, replace?: boolean) => void;
   onStatus?: (text: string) => void;
   resolve: (result: TurnResult) => void;
   reject: (error: Error) => void;
@@ -44,7 +50,6 @@ class LocalChatSession {
     // TUI-NEXT-QUEUE-AND-WAKE: the child's ScheduleWakeup asks this process over Bun IPC — the scheduler
     // lives here because the child dies on Esc and /new. No tool registered → no IPC, env unchanged.
     const wakeupTool = nextTuiWakeupTool();
-    const sidetabHandler = nextSidetabHandler;
     this.child = Bun.spawn({
       cmd: [process.execPath, cli, 'repl', '--session', sessionId, '--json', '--stdin-jsonl'],
       stdin: 'pipe', stdout: 'pipe', stderr: 'pipe',
@@ -52,21 +57,23 @@ class LocalChatSession {
         ...process.env, ELANOUS_NEXT_TUI_BG_STATUS: '1', ELANOUS_NEXT_TUI_STREAM: '1',
         ELANOUS_NEXT_TUI_SELF_HEALTH: '1',
         ...(wakeupTool ? { [NEXT_TUI_WAKEUP_IPC_ENV]: '1' } : {}),
-        ELANOUS_NEXT_TUI_SIDETAB_IPC: sidetabHandler ? '1' : '0',
+        // The Next TUI explicitly enables this before child startup. The
+        // callback itself stays live so a child created before handler wiring
+        // can still serve the host once it is installed.
+        ELANOUS_NEXT_TUI_SIDETAB_IPC: nextSidetabIpcEnabled ? '1' : '0',
       },
-      ...(wakeupTool || sidetabHandler ? {
-        ipc: (message: unknown, child: { send(message: unknown): unknown }) => {
+      ipc: (message: unknown, child: { send(message: unknown): unknown }) => {
           if (wakeupTool && isWakeupCallMessage(message)) {
             void answerWakeupCall(wakeupTool, message).then((reply) => {
               try { child.send(reply); } catch { /* the child exited mid-call; its dispatch times out */ }
             });
-          } else if (sidetabHandler && isNextSidetabCall(message)) {
-            void answerNextSidetabCall(sidetabHandler, message).then((reply) => {
+          } else if (isNextSidetabCall(message)) {
+            const handler = nextSidetabHandler ?? (async () => ({ error: 'Next TUI sidetab handler is not ready' }));
+            void answerNextSidetabCall(handler, message).then((reply) => {
               try { child.send(reply); } catch { /* the child exited mid-call; its dispatch times out */ }
             });
           }
-        },
-      } : {}),
+      },
     });
     const input = this.child.stdin;
     const output = this.child.stdout;
@@ -100,6 +107,12 @@ class LocalChatSession {
         }
         return;
       }
+      if (result.event === 'replace') {
+        if (result.turnId === waiting.turnId && typeof result.text === 'string') {
+          try { waiting.onDelta?.(result.text, true); } catch { /* renderer cannot break the turn */ }
+        }
+        return;
+      }
       if (result.event === 'status') {
         if (result.turnId === waiting.turnId && typeof result.text === 'string') {
           try { waiting.onStatus?.(result.text); } catch { /* renderer cannot break the turn */ }
@@ -175,7 +188,7 @@ class LocalChatSession {
     }
   }
 
-  async turn(prompt: string, writePrompt?: (payload: string) => Promise<void>, onDelta?: (text: string) => void, attachments: readonly string[] = [], onStatus?: (text: string) => void): Promise<TurnResult> {
+  async turn(prompt: string, writePrompt?: (payload: string) => Promise<void>, onDelta?: (text: string, replace?: boolean) => void, attachments: readonly string[] = [], onStatus?: (text: string) => void): Promise<TurnResult> {
     if (this.closed) throw new Error('REPL child exited');
     if (this.waiting) throw new Error('REPL turn already running');
     const turnId = `tui-${++this.turnCount}`;
@@ -255,7 +268,7 @@ export async function runLocalChatTurn(
   signal: AbortSignal,
   cli = process.argv[1],
   writePrompt?: (payload: string) => Promise<void>,
-  onDelta?: (text: string) => void,
+  onDelta?: (text: string, replace?: boolean) => void,
   compact: LocalChatTurnCompact = {},
   attachments: readonly string[] = [],
   onStatus?: (line: string) => void,
@@ -278,8 +291,8 @@ export async function runLocalChatTurn(
   if (signal.aborted) abort();
   let result: TurnResult;
   try {
-    result = await session.turn(text, writePrompt, (delta) => {
-      if (!signal.aborted) onDelta?.(delta);
+    result = await session.turn(text, writePrompt, (delta, replace) => {
+      if (!signal.aborted) onDelta?.(delta, replace);
     }, attachments, (line) => { if (!signal.aborted) onStatus?.(line); });
   } catch (error) {
     if (signal.aborted) throw new Error('응답을 취소했습니다');

package/src/tui.ts

@@ -1014,6 +1014,28 @@ export function injectKey(key: Key): boolean {
   return true;
 }
 
+// A foreground dashboard may own an interactive child terminal modal. External
+// control-IPC input must be routed to that modal before it enters the dashboard
+// readKey queue; while the parent loop is busy there may be no readKey consumer.
+let _externalTuiKeyRoutes: Array<{ token: symbol; route: (key: Key) => boolean }> = [];
+
+export function setExternalTuiKeyRoute(route: ((key: Key) => boolean) | null): () => void {
+  if (!route) return () => {};
+  const entry = { token: Symbol('external-tui-key-route'), route };
+  _externalTuiKeyRoutes.push(entry);
+  return () => {
+    _externalTuiKeyRoutes = _externalTuiKeyRoutes.filter((candidate) => candidate.token !== entry.token);
+  };
+}
+
+export function routeExternalTuiKey(key: Key): boolean {
+  const routes = [..._externalTuiKeyRoutes];
+  for (let index = routes.length - 1; index >= 0; index -= 1) {
+    if (routes[index]!.route(key)) return true;
+  }
+  return false;
+}
+
 /** `injectKey` 로 들어온 키 표지 — `takeInjectedKeys` 가 stdin 잔여 키(readKey 몫)는 두고 주입 키만 꺼낸다. */
 const _injectedKeys = new WeakSet<Key>();