triflux 5.2.0 → 6.0.0

package/hub/team/headless.mjs

@@ -1,9 +1,12 @@
 // hub/team/headless.mjs — 헤드리스 CLI 오케스트레이션
 // psmux pane에서 CLI를 헤드리스 모드로 실행하고 결과를 수집한다.
+// v5.2.0: 기본 headless 엔진 (runHeadless, runHeadlessWithCleanup)
+// v6.0.0: Lead-direct 모드 (runHeadlessInteractive, autoAttachTerminal)
 // 의존성: psmux.mjs (Node.js 내장 모듈만 사용)
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { execSync, execFileSync } from "node:child_process";
 import {
   createPsmuxSession,
   killPsmuxSession,
@@ -11,6 +14,8 @@ import {
   dispatchCommand,
   waitForCompletion,
   capturePsmuxPane,
+  startCapture,
+  psmuxExec,
 } from "./psmux.mjs";
 
 const RESULT_DIR = join(tmpdir(), "tfx-headless");
@@ -30,7 +35,7 @@ export function buildHeadlessCommand(cli, prompt, resultFile) {
     case "codex":
       return `codex exec '${escaped}' -o '${resultFile}' --color never`;
     case "gemini":
-      return `gemini -p '${escaped}' -o text > '${resultFile}' 2>&1`;
+      return `gemini -p '${escaped}' -o text > '${resultFile}' 2>'${resultFile}.err'`;
     case "claude":
       return `claude -p '${escaped}' --output-format text > '${resultFile}' 2>&1`;
     default:
@@ -41,8 +46,7 @@ export function buildHeadlessCommand(cli, prompt, resultFile) {
 /**
  * 결과 파일 읽기 (없으면 capture-pane fallback)
  * @param {string} resultFile
- * @param {string} sessionName
- * @param {string} paneName
+ * @param {string} paneId
  * @returns {string}
  */
 function readResult(resultFile, paneId) {
@@ -62,6 +66,8 @@ function readResult(resultFile, paneId) {
  * @param {number} [opts.timeoutSec=300] — 각 워커 타임아웃
  * @param {string} [opts.layout='2x2'] — pane 레이아웃
  * @param {(event: object) => void} [opts.onProgress] — 진행 콜백
+ * @param {number} [opts.progressIntervalSec=0] — N초마다 progress 이벤트 발화 (0=비활성)
+ * @param {boolean} [opts.progressive=true] — true면 pane을 하나씩 split-window로 추가 (실시간 스플릿)
  * @returns {{ sessionName: string, results: Array<{cli: string, paneName: string, matched: boolean, exitCode: number|null, output: string, sessionDead?: boolean}> }}
  */
 export async function runHeadless(sessionName, assignments, opts = {}) {
@@ -69,29 +75,96 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     timeoutSec = 300,
     layout = "2x2",
     onProgress,
+    progressIntervalSec = 0,
+    progressive = true,
   } = opts;
 
   mkdirSync(RESULT_DIR, { recursive: true });
-  const paneCount = assignments.length + 1; // +1 for lead pane (unused but reserved)
-  const session = createPsmuxSession(sessionName, { layout, paneCount });
 
-  if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
+  let dispatches;
 
-  // 각 워커 pane에 헤드리스 명령 dispatch
-  const dispatches = assignments.map((assignment, i) => {
-    const paneName = `worker-${i + 1}`;
-    const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
-    const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
-    const dispatch = dispatchCommand(sessionName, paneName, cmd);
+  if (progressive) {
+    // ─── 실시간 스플릿 모드: lead pane만 생성 후, 워커를 하나씩 추가 ───
+    const session = createPsmuxSession(sessionName, { layout, paneCount: 1 });
+    applyTrifluxTheme(sessionName);
+    if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
 
-    if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+    dispatches = assignments.map((assignment, i) => {
+      const paneName = `worker-${i + 1}`;
+      const paneTitle = assignment.role
+        ? `${assignment.cli} (${assignment.role})`
+        : `${assignment.cli}-${i + 1}`;
 
-    return { ...dispatch, paneName, resultFile, cli: assignment.cli, role: assignment.role };
-  });
+      // split-window로 새 pane 추가 — paneId 직접 획득
+      const newPaneId = psmuxExec([
+        "split-window", "-t", sessionName, "-P", "-F",
+        "#{session_name}:#{window_index}.#{pane_index}",
+      ]);
+
+      // 타이틀 설정
+      try { psmuxExec(["select-pane", "-t", newPaneId, "-T", paneTitle]); } catch { /* 무시 */ }
+
+      if (onProgress) onProgress({ type: "worker_added", paneName, cli: assignment.cli, paneTitle });
+
+      // 캡처 시작 + 명령 dispatch (paneId 직접 사용 — resolvePane race 회피)
+      const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
+      const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
+      startCapture(sessionName, newPaneId);
+      const dispatch = dispatchCommand(sessionName, newPaneId, cmd);
+
+      if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+
+      return { ...dispatch, paneId: newPaneId, paneName, resultFile, cli: assignment.cli, role: assignment.role };
+    });
+
+    // 모든 split 완료 후 레이아웃 한 번만 정렬 (깜빡임 방지)
+    try { psmuxExec(["select-layout", "-t", sessionName, "tiled"]); } catch { /* 무시 */ }
+
+  } else {
+    // ─── 기존 모드: 모든 pane을 한 번에 생성 ───
+    const paneCount = assignments.length + 1;
+    const session = createPsmuxSession(sessionName, { layout, paneCount });
+    applyTrifluxTheme(sessionName);
+    if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
+
+    dispatches = assignments.map((assignment, i) => {
+      const paneName = `worker-${i + 1}`;
+      const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
+      const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
+      const dispatch = dispatchCommand(sessionName, paneName, cmd);
+
+      // P1 fix: 비-progressive에서는 pane 리네임 금지 — 캡처 로그 경로가 타이틀 기반이므로
+      // 리네임하면 waitForCompletion이 "codex (role).log"를 찾지만 실제는 "worker-N.log"로 불일치
+      // progressive 모드에서는 split-window 시 새 pane에 바로 타이틀이 설정되므로 문제없음
+
+      if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+
+      return { ...dispatch, paneName, resultFile, cli: assignment.cli, role: assignment.role };
+    });
+  }
 
   // 병렬 대기 (Promise.all — 모든 pane 동시 폴링, 총 시간 = max(개별 시간))
   const results = await Promise.all(dispatches.map(async (d) => {
-    const completion = await waitForCompletion(sessionName, d.paneName, d.token, timeoutSec);
+    // onPoll → onProgress 변환 (throttle by progressIntervalSec)
+    const pollOpts = {};
+    if (onProgress && progressIntervalSec > 0) {
+      let lastProgressAt = 0;
+      const intervalMs = progressIntervalSec * 1000;
+      pollOpts.onPoll = ({ content }) => {
+        const now = Date.now();
+        if (now - lastProgressAt >= intervalMs) {
+          lastProgressAt = now;
+          onProgress({
+            type: "progress",
+            paneName: d.paneName,
+            cli: d.cli,
+            snapshot: content.split("\n").slice(-15).join("\n"), // 마지막 15줄
+          });
+        }
+      };
+    }
+
+    const completion = await waitForCompletion(sessionName, d.paneName, d.token, timeoutSec, pollOpts);
 
     const output = completion.matched
       ? readResult(d.resultFile, d.paneId)
@@ -111,6 +184,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     return {
       cli: d.cli,
       paneName: d.paneName,
+      paneId: d.paneId,
       role: d.role,
       matched: completion.matched,
       exitCode: completion.exitCode,
@@ -144,3 +218,231 @@ export async function runHeadlessWithCleanup(assignments, opts = {}) {
     }
   }
 }
+
+// ─── v6.0.0: Theme + Visual ───
+
+/**
+ * psmux 세션에 triflux 테마를 적용한다.
+ * status bar + pane border 색상 + 브랜딩.
+ *
+ * @param {string} sessionName
+ */
+export function applyTrifluxTheme(sessionName) {
+  const opts = [
+    // Status bar — Catppuccin Mocha 기반
+    ["status-style", "bg=#1e1e2e,fg=#cdd6f4"],
+    ["status-left", " #[fg=#89b4fa,bold]▲ triflux#[default] "],
+    ["status-left-length", "20"],
+    ["status-right", " #[fg=#a6adc8]#{pane_title}#[default] │ #[fg=#f9e2af]%H:%M#[default] "],
+    ["status-right-length", "40"],
+    // Pane border — active/inactive 구분
+    ["pane-active-border-style", "fg=#89b4fa"],
+    ["pane-border-style", "fg=#45475a"],
+    // Status bar 위치
+    ["status-position", "bottom"],
+  ];
+  for (const [key, value] of opts) {
+    try { psmuxExec(["set-option", "-t", sessionName, key, value]); } catch { /* 무시 */ }
+  }
+}
+
+// ─── v6.0.0: Lead-Direct Interactive Mode ───
+
+/**
+ * Windows Terminal에서 psmux 세션을 자동 attach한다.
+ * 별도 창이 열리며 사용자가 실시간으로 CLI 출력을 볼 수 있다.
+ *
+ * @param {string} sessionName — attach할 psmux 세션 이름
+ * @param {object} [opts]
+ * @param {string} [opts.position] — "right" | "left" | 없으면 기본 위치
+ * @returns {boolean} 성공 여부
+ */
+export function autoAttachTerminal(sessionName, opts = {}) {
+  try {
+    // Windows Terminal이 설치되어 있는지 확인
+    execSync("where wt.exe", { stdio: "ignore" });
+  } catch {
+    return false; // wt.exe 미설치 — 사용자에게 수동 attach 안내 필요
+  }
+
+  try {
+    // Fix P2: argv 스타일 — shell injection 방지
+    execFileSync("wt.exe", ["-w", "0", "nt", "psmux", "attach", "-t", sessionName], { stdio: "ignore" });
+    return true;
+  } catch {
+    try {
+      execFileSync("wt.exe", ["psmux", "attach", "-t", sessionName], { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * 모든 워커 pane의 현재 스냅샷을 수집한다.
+ *
+ * @param {string} sessionName
+ * @param {Array<{paneId: string, paneName: string, cli: string}>} dispatches
+ * @param {number} [lines=15] — 각 pane에서 캡처할 줄 수
+ * @returns {Array<{paneName: string, cli: string, snapshot: string}>}
+ */
+export function getProgressSnapshots(sessionName, dispatches, lines = 15) {
+  if (!psmuxSessionExists(sessionName)) return [];
+  return dispatches.map((d) => {
+    try {
+      const snapshot = capturePsmuxPane(d.paneId, lines);
+      return { paneName: d.paneName, cli: d.cli, snapshot };
+    } catch {
+      return { paneName: d.paneName, cli: d.cli, snapshot: "(캡처 실패)" };
+    }
+  });
+}
+
+/**
+ * Lead-Direct Interactive 헤드리스 실행.
+ * 세션을 유지하면서 결과 수집 후에도 추가 명령을 dispatch할 수 있다.
+ * 반환된 handle의 kill()을 반드시 호출하여 세션을 정리해야 한다.
+ *
+ * @param {string} sessionName — psmux 세션 이름
+ * @param {Array<{cli: string, prompt: string, role?: string}>} assignments
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutSec=300]
+ * @param {string} [opts.layout='2x2']
+ * @param {(event: object) => void} [opts.onProgress]
+ * @param {number} [opts.progressIntervalSec=0]
+ * @param {boolean} [opts.autoAttach=false] — Windows Terminal 자동 attach
+ * @param {AbortSignal} [opts.signal] — abort 시 자동 세션 정리
+ * @param {number} [opts.maxIdleSec=0] — 유휴 시 자동 정리 (0=비활성)
+ * @returns {Promise<{
+ *   sessionName: string,
+ *   results: Array,
+ *   dispatches: Array,
+ *   dispatch: (paneName: string, command: string) => {paneId: string, paneName: string, token: string},
+ *   capture: (paneName: string, lines?: number) => string,
+ *   snapshots: (lines?: number) => Array,
+ *   waitFor: (paneName: string, token: string, timeoutSec?: number, opts?: object) => Promise,
+ *   alive: () => boolean,
+ *   kill: () => void,
+ * }>}
+ */
+export async function runHeadlessInteractive(sessionName, assignments, opts = {}) {
+  const {
+    autoAttach = false,
+    signal,
+    maxIdleSec = 0,
+    ...runOpts
+  } = opts;
+
+  // autoAttach를 session_created 시점에 트리거 (CLI 실행 전에 터미널 열림)
+  const userOnProgress = runOpts.onProgress;
+  let terminalAttached = false;
+  runOpts.onProgress = (event) => {
+    if (autoAttach && event.type === "session_created" && !terminalAttached) {
+      terminalAttached = true;
+      autoAttachTerminal(sessionName);
+    }
+    if (userOnProgress) userOnProgress(event);
+  };
+
+  // Phase 1: 세션 생성 → 즉시 터미널 팝업 → dispatch → 대기 → 결과 수집
+  const { results } = await runHeadless(sessionName, assignments, runOpts);
+
+  // Phase 2: 세션을 유지하고 interactive handle 반환
+  // Fix P2: paneId를 dispatches에 포함 (snapshots에서 필요)
+  const dispatches = results.map((r, i) => ({
+    paneName: r.paneName,
+    paneId: r.paneId || "",
+    cli: r.cli,
+    role: r.role,
+  }));
+
+  // Fix P2: maxIdleSec 리셋을 위한 타이머 관리
+  let idleTimer = null;
+  function resetIdleTimer() {
+    if (idleTimer) clearTimeout(idleTimer);
+    if (maxIdleSec > 0) {
+      idleTimer = setTimeout(() => handle.kill(), maxIdleSec * 1000);
+      if (idleTimer.unref) idleTimer.unref();
+    }
+  }
+
+  const handle = {
+    sessionName,
+    results,
+    dispatches,
+    _killed: false,
+
+    /** 특정 pane에 후속 명령 dispatch (캡처 자동 재시작) */
+    dispatch(paneName, command) {
+      if (this._killed) throw new Error("세션이 이미 종료되었습니다.");
+      try { startCapture(sessionName, paneName); } catch { /* 이미 활성 — 무시 */ }
+      resetIdleTimer();
+      return dispatchCommand(sessionName, paneName, command);
+    },
+
+    /** 특정 pane의 현재 출력 캡처 */
+    capture(paneName, lines = 30) {
+      if (this._killed) return "";
+      try {
+        // Fix P2: paneName으로 resolvePane을 경유하여 정확한 paneId 획득
+        return capturePsmuxPane(paneName, lines);
+      } catch {
+        return "(캡처 실패)";
+      }
+    },
+
+    /** 모든 pane 스냅샷 */
+    snapshots(lines = 15) {
+      if (this._killed) return [];
+      return getProgressSnapshots(sessionName, dispatches, lines);
+    },
+
+    /** 특정 pane에서 완료 대기 */
+    async waitFor(paneName, token, timeoutSec = 300, waitOpts = {}) {
+      if (this._killed) return { matched: false, sessionDead: true };
+      resetIdleTimer();
+      return waitForCompletion(sessionName, paneName, token, timeoutSec, waitOpts);
+    },
+
+    /** 세션 생존 확인 */
+    alive() {
+      if (this._killed) return false;
+      return psmuxSessionExists(sessionName);
+    },
+
+    /** 세션 종료 */
+    kill() {
+      if (this._killed) return;
+      this._killed = true;
+      try { killPsmuxSession(sessionName); } catch { /* 무시 */ }
+    },
+  };
+
+  // AbortController signal로 자동 정리
+  if (signal) {
+    if (signal.aborted) {
+      handle.kill();
+    } else {
+      signal.addEventListener("abort", () => handle.kill(), { once: true });
+    }
+  }
+
+  // 유휴 타임아웃 자동 정리
+  if (maxIdleSec > 0) {
+    const timer = setTimeout(() => handle.kill(), maxIdleSec * 1000);
+    if (timer.unref) timer.unref(); // Node.js exit를 방해하지 않음
+  }
+
+  // 프로세스 종료 시 safety net
+  const exitHandler = () => handle.kill();
+  process.on("exit", exitHandler);
+  // kill() 후 리스너 제거를 위해 참조 보관
+  const originalKill = handle.kill.bind(handle);
+  handle.kill = function () {
+    originalKill();
+    process.removeListener("exit", exitHandler);
+  };
+
+  return handle;
+}

package/hub/team/psmux.mjs

@@ -641,9 +641,11 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
  * @param {string} paneNameOrTarget
  * @param {string|RegExp} pattern
  * @param {number} timeoutSec
+ * @param {object} [opts]
+ * @param {(snapshot: {content: string, paneId: string, paneName: string, elapsed: number}) => void} [opts.onPoll] — 각 폴링 주기마다 호출
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null }}
  */
-export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300) {
+export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300, opts = {}) {
   ensurePsmuxInstalled();
 
   // E4 크래시 복구: 초기 resolvePane도 세션 사망을 감지
@@ -670,7 +672,8 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     throw new Error(`캡처 로그가 없습니다. 먼저 startCapture(${sessionName}, ${paneName})를 호출하세요.`);
   }
 
-  const deadline = Date.now() + Math.max(0, Math.trunc(timeoutSec * 1000));
+  const startTime = Date.now();
+  const deadline = startTime + Math.max(0, Math.trunc(timeoutSec * 1000));
   const regex = toPatternRegExp(pattern);
 
   while (Date.now() <= deadline) {
@@ -692,6 +695,14 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     }
 
     const content = readCaptureLog(logPath);
+
+    // onPoll 콜백 — 각 폴링 주기마다 중간 상태 전달
+    if (opts.onPoll) {
+      try {
+        opts.onPoll({ content, paneId: pane.paneId, paneName, elapsed: Date.now() - startTime });
+      } catch { /* 콜백 예외는 삼킴 — 폴링 루프 보호 */ }
+    }
+
     const match = regex.exec(content);
     if (match) {
       return {
@@ -724,14 +735,15 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
  * @param {string} paneNameOrTarget
  * @param {string} token
  * @param {number} timeoutSec
+ * @param {object} [opts] — waitForPattern에 전달할 옵션 (onPoll 등)
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, token: string, exitCode: number|null }}
  */
-export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300) {
+export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300, opts = {}) {
   const completionRegex = new RegExp(
     `${escapeRegExp(COMPLETION_PREFIX)}${escapeRegExp(token)}:(\\d+)`,
     "m",
   );
-  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec);
+  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec, opts);
   const exitMatch = result.match ? completionRegex.exec(result.match) : null;
   return {
     ...result,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "5.2.0",
+  "version": "6.0.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/lib/logger.mjs

@@ -93,13 +93,13 @@ export function createModuleLogger(module) {
 
 // 정상 종료 시 버퍼 flush 보장
 process.on('uncaughtException', (err) => {
-  const finalLogger = pino.final(logger);
-  finalLogger.fatal({ err }, 'process.uncaught_exception');
+  logger.fatal({ err }, 'process.uncaught_exception');
+  logger.flush();
   process.exit(1);
 });
 
 process.on('unhandledRejection', (reason) => {
-  const finalLogger = pino.final(logger);
-  finalLogger.fatal({ reason: String(reason) }, 'process.unhandled_rejection');
+  logger.fatal({ reason: String(reason) }, 'process.unhandled_rejection');
+  logger.flush();
   process.exit(1);
 });

package/skills/tfx-multi/SKILL.md

@@ -148,34 +148,58 @@ status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 3. 실패 시 `forceCleanupTeam(teamName)` → 그래도 실패 시 `rm -rf ~/.claude/teams/{teamName}/` 안내
 4. 종합 보고서 출력
 
-### Phase 3-mux: psmux 헤드리스 모드
+### Phase 3-direct: Lead-Direct Headless 실행 (v6.0.0, 기본)
 
-`--tmux`/`--psmux` 시 pane 기반 헤드리스 실행. Agent 래퍼 없이 Lead가 직접 CLI를 제어하여 토큰 76-89% 절감.
+CLI 워커(Codex/Gemini/Claude)를 Agent 래퍼 없이 Lead가 headless.mjs로 직접 실행.
+Windows Terminal에 psmux 세션이 자동 팝업되어 사용자가 실시간으로 CLI 출력을 확인.
 
-**핵심 프리미티브** (`hub/team/psmux.mjs`):
-- `createPsmuxSession(name, {layout, paneCount})` — 세션 + pane 분할
-- `dispatchCommand(session, paneName, cmd)` → `{token, paneId, logPath}`
-- `waitForCompletion(session, paneName, token, timeoutSec)` → `{matched, exitCode, sessionDead?}`
-- 완료 마커: `__TRIFLUX_DONE__:token:exitCode` (PowerShell 래핑)
-- pane 이름: `"lead"` → index 0, `"worker-N"` → index N (대소문자 무관)
+**핵심 기능:**
+- `progressive: true` (기본) — pane이 하나씩 split-window로 추가 (실시간 스플릿)
+- `autoAttach: true` — 세션 생성 즉시 Windows Terminal 자동 팝업
+- `progressIntervalSec` — N초마다 각 pane 스냅샷을 onProgress로 전달
+- `applyTrifluxTheme()` — status bar + pane border 테마 자동 적용
+- 피드백 재실행 — 같은 pane에 후속 명령 dispatch (세션 유지)
 
-**헤드리스 오케스트레이션** (`hub/team/headless.mjs`):
-```
-import { runHeadlessWithCleanup } from "hub/team/headless.mjs";
-const { results } = runHeadlessWithCleanup([
+**Lead 오케스트레이션 패턴:**
+
+```javascript
+// headless.mjs의 runHeadlessInteractive()를 Bash 내에서 호출
+// Lead는 Bash의 결과를 직접 파싱 — Agent 래퍼 불필요
+const handle = await runHeadlessInteractive("tfx-session", [
   { cli: "codex", prompt: "코드 리뷰", role: "reviewer" },
   { cli: "gemini", prompt: "문서 작성", role: "writer" },
-], { timeoutSec: 300 });
+  { cli: "claude", prompt: "테스트 실행", role: "tester" },
+], {
+  timeoutSec: 300,
+  autoAttach: true,          // WT 자동 팝업
+  progressive: true,         // 실시간 스플릿 (기본)
+  progressIntervalSec: 10,   // 10초마다 진행 스냅샷
+});
+// handle: { results, dispatch(), capture(), snapshots(), waitFor(), kill() }
+```
+
+**결정 로직:**
+```
+Phase 3 선택:
+  assignments.every(a => a.cli !== 'claude')
+    → Phase 3-direct (headless, 전부 CLI)
+  assignments.some(a => a.cli === 'claude') AND Claude 워커가 Read/Edit 필요
+    → Claude 워커: Agent(subagent_type), CLI 워커: Phase 3-direct
+  fallback (psmux 미설치)
+    → Phase 3 Native Teams (기존 slim wrapper)
 ```
 
 **CLI 헤드리스 명령 패턴:**
 | CLI | 명령 | 출력 |
 |-----|-------|------|
 | Codex | `codex exec 'prompt' -o result.txt --color never` | 파일 |
-| Gemini | `gemini -p 'prompt' -o text > result.txt` | 리다이렉트 |
-| Claude | `claude -p 'prompt' --output-format text > result.txt` | 리다이렉트 |
+| Gemini | `gemini -p 'prompt' -o text > result.txt 2>result.txt.err` | 리다이렉트 |
+| Claude | `claude -p 'prompt' --output-format text > result.txt 2>&1` | 리다이렉트 |
 
 **E4 크래시 복구:** `waitForCompletion`이 세션 사망 시 `{sessionDead: true}` 반환 (throw 대신).
+**elevation 불필요:** psmux IPC는 TCP 기반. 비-elevated 환경에서 정상 실행. (v5.2.0 검증 완료)
+**시각적 확인:** Windows Terminal 자동 팝업 + pane 타이틀 `codex (reviewer)` + triflux 테마.
+**실수로 닫아도:** psmux 세션은 독립적. `psmux attach -t 세션이름`으로 재연결.
 
 **레거시 인터랙티브 모드:** `Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")`