triflux 5.1.1 → 5.2.0

package/hub/team/cli/commands/start/index.mjs

@@ -8,6 +8,7 @@ import { fail, ok, warn } from "../../render.mjs";
 import { parseTeamArgs } from "./parse-args.mjs";
 import { startInProcessTeam } from "./start-in-process.mjs";
 import { startMuxTeam } from "./start-mux.mjs";
+import { startHeadlessTeam } from "./start-headless.mjs";
 import { startWtTeam } from "./start-wt.mjs";
 
 function printStartUsage() {
@@ -68,9 +69,11 @@ export async function teamStart(args = []) {
 
   const state = effectiveMode === "in-process"
     ? await startInProcessTeam({ sessionId, task, lead, agents, subtasks, hubUrl })
-    : effectiveMode === "wt"
-      ? await startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl })
-      : await startMuxTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl, teammateMode: effectiveMode });
+    : effectiveMode === "headless"
+      ? await startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout })
+      : effectiveMode === "wt"
+        ? await startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl })
+        : await startMuxTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl, teammateMode: effectiveMode });
 
   if (!state) return fail("in-process supervisor 시작 실패");
   saveTeamState(state);

package/hub/team/cli/commands/start/start-headless.mjs

@@ -0,0 +1,76 @@
+import { BOLD, DIM, GREEN, RESET, AMBER } from "../../../shared.mjs";
+import { runHeadless } from "../../../headless.mjs";
+import { killPsmuxSession } from "../../../psmux.mjs";
+import { ok, warn } from "../../render.mjs";
+import { buildTasks } from "../../services/task-model.mjs";
+
+export async function startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout }) {
+  console.log(`  ${AMBER}모드: headless (psmux 헤드리스 CLI 실행)${RESET}`);
+
+  const assignments = subtasks.map((subtask, i) => ({
+    cli: agents[i],
+    prompt: subtask,
+    role: `worker-${i + 1}`,
+  }));
+
+  ok("헤드리스 실행 시작...");
+  const { sessionName, results } = await runHeadless(sessionId, assignments, {
+    timeoutSec: 300,
+    layout,
+    onProgress(event) {
+      if (event.type === "dispatched") {
+        console.log(`  ${DIM}[${event.paneName}] ${event.cli} dispatch${RESET}`);
+      } else if (event.type === "completed") {
+        const icon = event.matched && event.exitCode === 0 ? `${GREEN}✓${RESET}` : `${AMBER}✗${RESET}`;
+        console.log(`  ${icon} [${event.paneName}] ${event.cli} exit=${event.exitCode}${event.sessionDead ? " (session dead)" : ""}`);
+      }
+    },
+  });
+
+  // 결과 요약
+  const succeeded = results.filter((r) => r.matched && r.exitCode === 0);
+  const failed = results.filter((r) => !r.matched || r.exitCode !== 0);
+
+  console.log(`\n  ${GREEN}${BOLD}헤드리스 실행 완료${RESET}`);
+  console.log(`  ${DIM}성공: ${succeeded.length} / 실패: ${failed.length} / 전체: ${results.length}${RESET}`);
+
+  if (failed.length > 0) {
+    warn("실패 워커:");
+    for (const r of failed) {
+      console.log(`    ${r.paneName} (${r.cli}): exit=${r.exitCode}${r.sessionDead ? " session dead" : ""}`);
+    }
+  }
+
+  // 결과 출력 (각 워커의 output 요약)
+  for (const r of results) {
+    if (r.output) {
+      const preview = r.output.length > 200 ? `${r.output.slice(0, 200)}…` : r.output;
+      console.log(`\n  ${DIM}── ${r.paneName} (${r.cli}) ──${RESET}`);
+      console.log(`  ${preview}`);
+    }
+  }
+
+  // 세션 정리
+  try { killPsmuxSession(sessionName); } catch { /* already cleaned */ }
+
+  const members = [
+    { role: "lead", name: "lead", cli: lead, pane: `${sessionName}:0.0` },
+    ...results.map((r, i) => ({ role: "worker", name: r.paneName, cli: r.cli, pane: `${sessionName}:0.${i + 1}`, subtask: subtasks[i] })),
+  ];
+
+  return {
+    sessionName,
+    task,
+    lead,
+    agents,
+    layout,
+    teammateMode: "headless",
+    startedAt: Date.now(),
+    members,
+    headlessResults: results,
+    tasks: buildTasks(subtasks, members.filter((m) => m.role === "worker")),
+    postSave() {
+      console.log(`\n  ${DIM}세션 자동 정리 완료. 결과는 위에 표시됨.${RESET}\n`);
+    },
+  };
+}

package/hub/team/cli/services/runtime-mode.mjs

@@ -8,6 +8,7 @@ import {
 export function normalizeTeammateMode(mode = "auto") {
   const raw = String(mode).toLowerCase();
   if (raw === "inline" || raw === "native") return "in-process";
+  if (raw === "headless" || raw === "hl") return "headless";
   if (raw === "in-process" || raw === "tmux" || raw === "wt" || raw === "psmux") return raw;
   if (raw === "windows-terminal" || raw === "windows_terminal") return "wt";
   if (raw === "auto") {

package/hub/team/headless.mjs

@@ -0,0 +1,146 @@
+// hub/team/headless.mjs — 헤드리스 CLI 오케스트레이션
+// psmux pane에서 CLI를 헤드리스 모드로 실행하고 결과를 수집한다.
+// 의존성: psmux.mjs (Node.js 내장 모듈만 사용)
+import { join } from "node:path";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import {
+  createPsmuxSession,
+  killPsmuxSession,
+  psmuxSessionExists,
+  dispatchCommand,
+  waitForCompletion,
+  capturePsmuxPane,
+} from "./psmux.mjs";
+
+const RESULT_DIR = join(tmpdir(), "tfx-headless");
+
+/**
+ * CLI별 헤드리스 명령 빌더
+ * @param {'codex'|'gemini'|'claude'} cli
+ * @param {string} prompt — 실행할 프롬프트
+ * @param {string} resultFile — 결과 저장 파일 경로
+ * @returns {string} PowerShell 명령
+ */
+export function buildHeadlessCommand(cli, prompt, resultFile) {
+  // 프롬프트의 단일 인용부호를 이스케이프
+  const escaped = prompt.replace(/'/g, "''");
+
+  switch (cli) {
+    case "codex":
+      return `codex exec '${escaped}' -o '${resultFile}' --color never`;
+    case "gemini":
+      return `gemini -p '${escaped}' -o text > '${resultFile}' 2>&1`;
+    case "claude":
+      return `claude -p '${escaped}' --output-format text > '${resultFile}' 2>&1`;
+    default:
+      throw new Error(`지원하지 않는 CLI: ${cli}`);
+  }
+}
+
+/**
+ * 결과 파일 읽기 (없으면 capture-pane fallback)
+ * @param {string} resultFile
+ * @param {string} sessionName
+ * @param {string} paneName
+ * @returns {string}
+ */
+function readResult(resultFile, paneId) {
+  if (existsSync(resultFile)) {
+    return readFileSync(resultFile, "utf8").trim();
+  }
+  // fallback: capture-pane (paneId = "tfx:0.1" 형태)
+  return capturePsmuxPane(paneId, 30);
+}
+
+/**
+ * 헤드리스 CLI 오케스트레이션 실행
+ *
+ * @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'] — pane 레이아웃
+ * @param {(event: object) => void} [opts.onProgress] — 진행 콜백
+ * @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 = {}) {
+  const {
+    timeoutSec = 300,
+    layout = "2x2",
+    onProgress,
+  } = 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 });
+
+  // 각 워커 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 (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);
+
+    const output = completion.matched
+      ? readResult(d.resultFile, d.paneId)
+      : "";
+
+    if (onProgress) {
+      onProgress({
+        type: "completed",
+        paneName: d.paneName,
+        cli: d.cli,
+        matched: completion.matched,
+        exitCode: completion.exitCode,
+        sessionDead: completion.sessionDead || false,
+      });
+    }
+
+    return {
+      cli: d.cli,
+      paneName: d.paneName,
+      role: d.role,
+      matched: completion.matched,
+      exitCode: completion.exitCode,
+      output,
+      sessionDead: completion.sessionDead || false,
+    };
+  }));
+
+  return { sessionName, results };
+}
+
+/**
+ * 헤드리스 실행 + 자동 정리
+ * 성공/실패에 관계없이 세션을 정리한다.
+ *
+ * @param {Array<{cli: string, prompt: string, role?: string}>} assignments
+ * @param {object} [opts] — runHeadless opts + sessionPrefix
+ * @returns {{ results: Array, sessionName: string }}
+ */
+export async function runHeadlessWithCleanup(assignments, opts = {}) {
+  const { sessionPrefix = "tfx-hl", ...runOpts } = opts;
+  const sessionName = `${sessionPrefix}-${Date.now().toString(36).slice(-6)}`;
+
+  try {
+    return await runHeadless(sessionName, assignments, runOpts);
+  } finally {
+    try {
+      killPsmuxSession(sessionName);
+    } catch {
+      // 이미 종료된 세션 — 무시
+    }
+  }
+}

package/hub/team/psmux.mjs

@@ -37,6 +37,10 @@ function sleepMs(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms));
 }
 
+function sleepMsAsync(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
 function tokenizeCommand(command) {
   const source = String(command || "").trim();
   if (!source) return [];
@@ -248,14 +252,29 @@ function listPaneDetails(sessionName) {
   return parsePaneDetails(output);
 }
 
+function paneTitleToIndex(name) {
+  const lower = String(name).toLowerCase();
+  if (lower === "lead") return 0;
+  const m = /^worker-(\d+)$/.exec(lower);
+  if (!m) return -1;
+  const idx = parseInt(m[1], 10);
+  // worker-0은 유효하지 않음 (lead와 충돌, toPaneTitle은 worker-0을 생성하지 않음)
+  return idx >= 1 ? idx : -1;
+}
+
 function resolvePane(sessionName, paneNameOrTarget) {
   const wanted = String(paneNameOrTarget);
-  const pane = listPaneDetails(sessionName)
-    .find((entry) => entry.title === wanted || entry.paneId === wanted);
-  if (!pane) {
-    throw new Error(`Pane을 찾을 수 없습니다: ${paneNameOrTarget}`);
-  }
-  return pane;
+  const panes = listPaneDetails(sessionName);
+
+  // 1차: title 또는 paneId 직접 매칭
+  const direct = panes.find((entry) => entry.title === wanted || entry.paneId === wanted);
+  if (direct) return direct;
+
+  // 2차: psmux title 미설정 fallback — "lead"→0, "worker-N"→N 인덱스 매칭
+  const idx = paneTitleToIndex(wanted);
+  if (idx >= 0 && idx < panes.length) return panes[idx];
+
+  throw new Error(`Pane을 찾을 수 없습니다: ${paneNameOrTarget}`);
 }
 
 function refreshCaptureSnapshot(sessionName, paneNameOrTarget) {
@@ -624,9 +643,27 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
  * @param {number} timeoutSec
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null }}
  */
-export function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300) {
+export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300) {
   ensurePsmuxInstalled();
-  const pane = resolvePane(sessionName, paneNameOrTarget);
+
+  // E4 크래시 복구: 초기 resolvePane도 세션 사망을 감지
+  let pane;
+  try {
+    pane = resolvePane(sessionName, paneNameOrTarget);
+  } catch (resolveError) {
+    if (!psmuxSessionExists(sessionName)) {
+      return {
+        matched: false,
+        paneId: "",
+        paneName: String(paneNameOrTarget),
+        logPath: "",
+        match: null,
+        sessionDead: true,
+      };
+    }
+    throw resolveError; // 세션은 살아있지만 pane을 못 찾음 → 원래 에러 전파
+  }
+
   const paneName = pane.title || paneNameOrTarget;
   const logPath = getCaptureLogPath(sessionName, paneName);
   if (!existsSync(logPath)) {
@@ -637,7 +674,23 @@ export function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSe
   const regex = toPatternRegExp(pattern);
 
   while (Date.now() <= deadline) {
-    refreshCaptureSnapshot(sessionName, pane.paneId);
+    // E4 크래시 복구: capture 실패 시 세션 생존 체크
+    try {
+      refreshCaptureSnapshot(sessionName, pane.paneId);
+    } catch {
+      if (!psmuxSessionExists(sessionName)) {
+        return {
+          matched: false,
+          paneId: pane.paneId,
+          paneName,
+          logPath,
+          match: null,
+          sessionDead: true,
+        };
+      }
+      // 일시적 오류 — 다음 폴링에서 재시도
+    }
+
     const content = readCaptureLog(logPath);
     const match = regex.exec(content);
     if (match) {
@@ -653,7 +706,7 @@ export function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSe
     if (Date.now() > deadline) {
       break;
     }
-    sleepMs(POLL_INTERVAL_MS);
+    await sleepMsAsync(POLL_INTERVAL_MS);
   }
 
   return {
@@ -673,12 +726,12 @@ export function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSe
  * @param {number} timeoutSec
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, token: string, exitCode: number|null }}
  */
-export function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300) {
+export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300) {
   const completionRegex = new RegExp(
     `${escapeRegExp(COMPLETION_PREFIX)}${escapeRegExp(token)}:(\\d+)`,
     "m",
   );
-  const result = waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec);
+  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec);
   const exitMatch = result.match ? completionRegex.exec(result.match) : null;
   return {
     ...result,
@@ -825,6 +878,7 @@ export function captureWorkerOutput(sessionName, workerName, lines = 50) {
 // ─── CLI 진입점 ───
 
 if (process.argv[1] && process.argv[1].endsWith("psmux.mjs")) {
+  (async () => {
   const [, , cmd, ...args] = process.argv;
 
   // CLI 인자 파싱 헬퍼
@@ -907,7 +961,7 @@ if (process.argv[1] && process.argv[1].endsWith("psmux.mjs")) {
           console.error("사용법: node psmux.mjs wait-pattern --session <세션> --name <pane> --pattern <정규식> [--timeout <초>]");
           process.exit(1);
         }
-        const result = waitForPattern(session, name, pattern, timeoutSec);
+        const result = await waitForPattern(session, name, pattern, timeoutSec);
         console.log(JSON.stringify(result, null, 2));
         if (!result.matched) process.exit(2);
         break;
@@ -921,7 +975,7 @@ if (process.argv[1] && process.argv[1].endsWith("psmux.mjs")) {
           console.error("사용법: node psmux.mjs wait-completion --session <세션> --name <pane> --token <토큰> [--timeout <초>]");
           process.exit(1);
         }
-        const result = waitForCompletion(session, name, token, timeoutSec);
+        const result = await waitForCompletion(session, name, token, timeoutSec);
         console.log(JSON.stringify(result, null, 2));
         if (!result.matched) process.exit(2);
         break;
@@ -943,4 +997,5 @@ if (process.argv[1] && process.argv[1].endsWith("psmux.mjs")) {
     console.error(`오류: ${err.message}`);
     process.exit(1);
   }
+  })();
 }

package/package.json

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

package/scripts/lib/mcp-filter.mjs

@@ -176,7 +176,10 @@ function normalizeProfileName(profile) {
   if (raw === 'auto') return raw;
   if (PROFILE_DEFINITIONS[raw]) return raw;
   if (LEGACY_PROFILE_ALIASES[raw]) return LEGACY_PROFILE_ALIASES[raw];
-  throw new Error(`지원하지 않는 MCP 프로필: ${raw}`);
+  // graceful fallback: --flag나 잘못된 프로필 → 'auto'로 폴백 (hard crash 방지)
+  if (raw.startsWith('-') || raw.startsWith('/')) return 'auto';
+  console.error(`[mcp-filter] 경고: 알 수 없는 프로필 '${raw}', 'auto'로 폴백`);
+  return 'auto';
 }
 
 function resolveAutoProfile(agentType = '') {
@@ -696,7 +699,14 @@ export async function runCli(argv = process.argv.slice(2)) {
     return;
   }
 
-  const policy = buildMcpPolicy(args);
+  let policy;
+  try {
+    policy = buildMcpPolicy(args);
+  } catch (error) {
+    console.error(`[mcp-filter] ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 65;
+    return;
+  }
   if (args.command === 'shell') {
     process.stdout.write(`${toShellExports(policy)}\n`);
     return;

package/scripts/tfx-route.sh

@@ -121,6 +121,16 @@ MCP_PROFILE="${3:-auto}"
 USER_TIMEOUT="${4:-}"
 CONTEXT_FILE="${5:-}"
 
+# ── CLI 이름은 route_agent()에서 기본 역할 alias로 처리됨 (codex→executor, gemini→designer, claude→explore) ──
+
+# ── 인자 검증: MCP_PROFILE이 --flag 형태인 경우 거절 ──
+if [[ "$MCP_PROFILE" == --* ]]; then
+  echo "ERROR: MCP 프로필 위치(3번째 인자)에 플래그 '$MCP_PROFILE'가 들어왔습니다." >&2
+  echo "사용법: tfx-route.sh <역할> \"프롬프트\" [mcp_profile] [timeout]" >&2
+  echo "지원 프로필: auto, executor, analyze, implement, review, minimal, full" >&2
+  exit 64
+fi
+
 # ── CLI 경로 해석 (Windows npm global 대응) ──
 NODE_BIN="${NODE_BIN:-$(command -v node 2>/dev/null || echo node)}"
 CODEX_BIN="${CODEX_BIN:-$(command -v codex 2>/dev/null || echo codex)}"
@@ -461,22 +471,22 @@ team_claim_task() {
   esac
 }
 
-team_complete_task() {
-  local result="${1:-success}"            # success/failed/timeout
-  local result_summary="${2:-작업 완료}"
-  [[ -z "$TFX_TEAM_NAME" || -z "$TFX_TEAM_TASK_ID" ]] && return 0
-
-  local summary_trimmed result_payload
-  summary_trimmed=$(echo "$result_summary" | head -c 4096)
-  result_payload=$(bridge_json_stringify task-result "$TFX_TEAM_TASK_ID" "$result" 2>/dev/null || true)
-
-  # task 파일 completion 쓰기는 Worker Step 6 TaskUpdate가 authority다.
-  # route 레벨에서는 task.result 발행 + 로컬 backup만 유지한다.
-
-  # Hub result 발행 (poll_messages 채널 활성화)
-  if [[ -n "$result_payload" ]]; then
-    if ! bridge_cli_with_restart "Hub result 발행" "Hub 재시작 후 Hub result 발행 성공." \
-      result \
+team_complete_task() {
+  local result="${1:-success}"            # success/failed/timeout
+  local result_summary="${2:-작업 완료}"
+  [[ -z "$TFX_TEAM_NAME" || -z "$TFX_TEAM_TASK_ID" ]] && return 0
+
+  local summary_trimmed result_payload
+  summary_trimmed=$(echo "$result_summary" | head -c 4096)
+  result_payload=$(bridge_json_stringify task-result "$TFX_TEAM_TASK_ID" "$result" 2>/dev/null || true)
+
+  # task 파일 completion 쓰기는 Worker Step 6 TaskUpdate가 authority다.
+  # route 레벨에서는 task.result 발행 + 로컬 backup만 유지한다.
+
+  # Hub result 발행 (poll_messages 채널 활성화)
+  if [[ -n "$result_payload" ]]; then
+    if ! bridge_cli_with_restart "Hub result 발행" "Hub 재시작 후 Hub result 발행 성공." \
+      result \
       --agent "$TFX_TEAM_AGENT_NAME" \
       --topic task.result \
       --payload "$result_payload" \
@@ -637,13 +647,13 @@ route_agent() {
       CLI_ARGS="-m gemini-3-flash-preview -y --prompt"
       CLI_EFFORT="flash"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
-    # ─── 탐색/검증/테스트 (Claude-native 우선, TFX_NO_CLAUDE_NATIVE=1일 때만 Codex 리매핑) ───
-    explore|verifier|test-engineer|qa-tester)
-      CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
-      CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=600; RUN_MODE="fg"; OPUS_OVERSIGHT="false"
-      case "$agent" in
-        test-engineer|qa-tester) DEFAULT_TIMEOUT=1200; RUN_MODE="bg" ;;
-      esac
+    # ─── 탐색/검증/테스트 (Claude-native 우선, TFX_NO_CLAUDE_NATIVE=1일 때만 Codex 리매핑) ───
+    explore|verifier|test-engineer|qa-tester)
+      CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
+      CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=600; RUN_MODE="fg"; OPUS_OVERSIGHT="false"
+      case "$agent" in
+        test-engineer|qa-tester) DEFAULT_TIMEOUT=1200; RUN_MODE="bg" ;;
+      esac
       ;;
 
     # ─── 경량 ───
@@ -651,11 +661,24 @@ route_agent() {
       CLI_TYPE="codex"; CLI_CMD="codex"
       CLI_ARGS="exec --profile spark_fast ${codex_base}"
       CLI_EFFORT="spark_fast"; DEFAULT_TIMEOUT=180; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+    # ─── CLI 이름 alias (사용자 편의) ───
+    codex)
+      CLI_TYPE="codex"; CLI_CMD="codex"
+      CLI_ARGS="exec ${codex_base}"
+      CLI_EFFORT="high"; DEFAULT_TIMEOUT=1080; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+    gemini)
+      CLI_TYPE="gemini"; CLI_CMD="gemini"
+      CLI_ARGS="-m gemini-3.1-pro-preview -y --prompt"
+      CLI_EFFORT="pro"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+    claude)
+      CLI_TYPE="claude-native"; CLI_CMD=""; CLI_ARGS=""
+      CLI_EFFORT="n/a"; DEFAULT_TIMEOUT=600; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     *)
       echo "ERROR: 알 수 없는 에이전트 타입: $agent" >&2
       echo "사용 가능: executor, build-fixer, debugger, deep-executor, architect, planner, critic, analyst," >&2
       echo "          code-reviewer, security-reviewer, quality-reviewer, scientist, document-specialist," >&2
-      echo "          designer, writer, explore, verifier, test-engineer, qa-tester, spark" >&2
+      echo "          designer, writer, explore, verifier, test-engineer, qa-tester, spark," >&2
+      echo "          codex, gemini, claude (CLI alias)" >&2
       exit 1 ;;
   esac
 }

package/skills/tfx-multi/SKILL.md

@@ -148,10 +148,36 @@ status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 3. 실패 시 `forceCleanupTeam(teamName)` → 그래도 실패 시 `rm -rf ~/.claude/teams/{teamName}/` 안내
 4. 종합 보고서 출력
 
-### Phase 3-mux: 레거시 psmux/tmux 모드
+### Phase 3-mux: psmux 헤드리스 모드
 
-`--tmux`/`--psmux` 시 pane 기반 실행. psmux가 Windows 1순위.
-`Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")`
+`--tmux`/`--psmux` 시 pane 기반 헤드리스 실행. Agent 래퍼 없이 Lead가 직접 CLI를 제어하여 토큰 76-89% 절감.
+
+**핵심 프리미티브** (`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 (대소문자 무관)
+
+**헤드리스 오케스트레이션** (`hub/team/headless.mjs`):
+```
+import { runHeadlessWithCleanup } from "hub/team/headless.mjs";
+const { results } = runHeadlessWithCleanup([
+  { cli: "codex", prompt: "코드 리뷰", role: "reviewer" },
+  { cli: "gemini", prompt: "문서 작성", role: "writer" },
+], { timeoutSec: 300 });
+```
+
+**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` | 리다이렉트 |
+
+**E4 크래시 복구:** `waitForCompletion`이 세션 사망 시 `{sessionDead: true}` 반환 (throw 대신).
+
+**레거시 인터랙티브 모드:** `Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")`
 
 ## 전제 조건