triflux 5.1.2 → 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 [];
@@ -639,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)) {
@@ -652,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) {
@@ -668,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 {
@@ -688,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,
@@ -840,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 인자 파싱 헬퍼
@@ -922,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;
@@ -936,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;
@@ -958,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.2",
+  "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 = '') {

package/scripts/tfx-route.sh

@@ -121,14 +121,7 @@ MCP_PROFILE="${3:-auto}"
 USER_TIMEOUT="${4:-}"
 CONTEXT_FILE="${5:-}"
 
-# ── 인자 검증: CLI 이름을 role 자리에 사용한 경우 안내 ──
-case "$AGENT_TYPE" in
-  codex|gemini|claude|claude-native)
-    echo "ERROR: '$AGENT_TYPE'는 CLI 이름이지 에이전트 역할이 아닙니다." >&2
-    echo "올바른 사용법: TFX_CLI_MODE=$AGENT_TYPE bash tfx-route.sh <역할> \"프롬프트\"" >&2
-    echo "사용 가능한 역할: executor, code-reviewer, scientist, designer, architect, verifier 등" >&2
-    exit 64 ;;
-esac
+# ── CLI 이름은 route_agent()에서 기본 역할 alias로 처리됨 (codex→executor, gemini→designer, claude→explore) ──
 
 # ── 인자 검증: MCP_PROFILE이 --flag 형태인 경우 거절 ──
 if [[ "$MCP_PROFILE" == --* ]]; then
@@ -668,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}\\\"")`
 
 ## 전제 조건