triflux 6.0.16 → 6.0.18

package/bin/triflux.mjs

@@ -1615,10 +1615,10 @@ function cmdUpdate() {
             stdio: ["pipe", "pipe", "pipe"],
             windowsHide: true,
           }).trim().split(/\r?\n/)[0];
-        } catch (retryErr) {
-          // Windows: 자기 자신의 파일 잠금으로 첫 시도 실패 가능 → 1회 재시도
-          info("첫 시도 실패, 재시도 중...");
-          result = execSync(npmCmd, {
+        } catch {
+          // Windows: 자기 자신의 파일 잠금으로 첫 시도 실패 가능 → --force 재시도
+          info("첫 시도 실패, --force 재시도 중...");
+          result = execSync(`${npmCmd} --force`, {
             encoding: "utf8",
             timeout: 90000,
             stdio: ["pipe", "pipe", "pipe"],

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

@@ -15,7 +15,7 @@ function printStartUsage() {
   console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET}\n`);
   console.log(`  사용법: ${WHITE}tfx multi "작업 설명"${RESET}`);
   console.log(`          ${WHITE}tfx multi --agents codex,gemini --lead claude "작업"${RESET}`);
-  console.log(`          ${WHITE}tfx multi --teammate-mode psmux "작업"${RESET} ${DIM}(Windows psmux 네이티브)${RESET}`);
+  console.log(`          ${WHITE}tfx multi --teammate-mode headless "작업"${RESET} ${DIM}(psmux 헤드리스, 기본)${RESET}`);
   console.log(`          ${WHITE}tfx multi --teammate-mode wt "작업"${RESET} ${DIM}(Windows Terminal split-pane)${RESET}`);
   console.log(`          ${WHITE}tfx multi --teammate-mode in-process "작업"${RESET} ${DIM}(mux 불필요)${RESET}\n`);
 }

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

@@ -9,11 +9,12 @@ 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 === "psmux") return "headless";
+  if (raw === "in-process" || raw === "tmux" || raw === "wt") return raw;
   if (raw === "windows-terminal" || raw === "windows_terminal") return "wt";
   if (raw === "auto") {
     if (process.env.TMUX) return "tmux";
-    return detectMultiplexer() === "psmux" ? "psmux" : "in-process";
+    return detectMultiplexer() === "psmux" ? "headless" : "in-process";
   }
   return "in-process";
 }

package/package.json

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

package/scripts/headless-guard.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * headless-guard.mjs — PreToolUse 훅 (auto-route 모드)
+ *
+ * Phase 3 headless 모드 활성 중 Lead가 Bash(tfx-route.sh)로 개별 호출하면
+ * deny 대신 자동으로 headless 명령으로 변환한다.
+ *
+ * 동작:
+ * - 마커 존재 + Bash(tfx-route.sh agent prompt mcp) → updatedInput: tfx multi --headless --assign
+ * - 마커 존재 + Agent(codex/gemini CLI 워커) → deny (tool 타입 변환 불가, 안내 메시지)
+ * - 마커 없음 → 전부 통과
+ * - 마커 30분 초과 → 자동 만료 (stale 방지)
+ *
+ * Exit 0 + stdout JSON: auto-route (updatedInput)
+ * Exit 2 + stderr: deny (Agent CLI 래핑만)
+ * Exit 0 (no stdout): allow
+ */
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const LOCK_FILE = join(tmpdir(), "tfx-headless-guard.lock");
+const MAX_AGE_MS = 30 * 60 * 1000; // 30분
+
+function isLockActive() {
+  if (!existsSync(LOCK_FILE)) return false;
+  try {
+    const ts = Number(readFileSync(LOCK_FILE, "utf8").trim());
+    if (Date.now() - ts > MAX_AGE_MS) {
+      unlinkSync(LOCK_FILE);
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * tfx-route.sh 명령에서 agent, prompt를 파싱한다.
+ * 형식: bash ~/.claude/scripts/tfx-route.sh {agent} '{prompt}' {mcp} [timeout] [context]
+ */
+function parseRouteCommand(cmd) {
+  // MCP 프로필 목록 (tfx-route.sh의 마지막 위치 인자)
+  const MCP_PROFILES = ["implement", "analyze", "review", "docs"];
+
+  // 전략: agent명 추출 후, 나머지에서 MCP 프로필을 역방향으로 찾아 프롬프트 경계를 결정
+  const agentMatch = cmd.match(/tfx-route\.sh\s+(\S+)\s+/);
+  if (!agentMatch) return null;
+
+  const agent = agentMatch[1];
+  const afterAgent = cmd.slice(agentMatch.index + agentMatch[0].length);
+
+  // MCP 프로필을 역방향으로 찾기
+  let mcp = "";
+  let promptRaw = afterAgent;
+  for (const profile of MCP_PROFILES) {
+    // 프롬프트 뒤에 오는 MCP 프로필 (공백 구분)
+    const profileIdx = afterAgent.lastIndexOf(` ${profile}`);
+    if (profileIdx >= 0) {
+      mcp = profile;
+      promptRaw = afterAgent.slice(0, profileIdx);
+      break;
+    }
+  }
+
+  // 프롬프트에서 바깥쪽 따옴표 제거
+  const prompt = promptRaw
+    .replace(/^['"]/, "")
+    .replace(/['"]$/, "")
+    .replace(/'\\''/g, "'")  // bash '\'' → '
+    .replace(/'"'"'/g, "'")  // bash '"'"' → '
+    .trim();
+
+  return { agent, prompt, mcp };
+}
+
+function autoRoute(updatedCommand, reason) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      updatedInput: { command: updatedCommand },
+      additionalContext: reason,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stderr.write(reason);
+  process.exit(2);
+}
+
+async function main() {
+  if (!isLockActive()) process.exit(0);
+
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || "";
+  const toolInput = input.tool_input || {};
+
+  // ── Bash: tfx-route.sh → headless auto-route ──
+  if (toolName === "Bash") {
+    const cmd = toolInput.command || "";
+
+    // 이미 headless 명령이면 통과
+    if (cmd.includes("tfx multi") || cmd.includes("triflux.mjs multi")) {
+      process.exit(0);
+    }
+
+    // 마커 조작 통과
+    if (cmd.includes("tfx-headless-guard")) {
+      process.exit(0);
+    }
+
+    // codex/gemini 직접 CLI 호출 감지 → deny (auto-route 불가: 원본 agent/role 정보 없음)
+    if (/\bcodex\s+exec\b/.test(cmd) || /\bgemini\s+(-p|--prompt)\b/.test(cmd)) {
+      deny(
+        "[headless-guard] Phase 3 활성 중. codex/gemini를 직접 호출하지 마세요. " +
+        'Bash("tfx multi --teammate-mode headless --assign \'codex:prompt:role\' ...") 로 headless 엔진에 위임하세요.',
+      );
+    }
+
+    // tfx-route.sh 개별 호출 → headless 자동 변환
+    if (cmd.includes("tfx-route.sh")) {
+      const parsed = parseRouteCommand(cmd);
+      if (parsed) {
+        const role = parsed.agent;
+        // 프롬프트에서 싱글쿼트 이스케이프
+        const safePrompt = parsed.prompt.replace(/'/g, "'\\''");
+        const headlessCmd =
+          `tfx multi --teammate-mode headless --auto-attach ` +
+          `--assign '${parsed.agent}:${safePrompt}:${role}' --timeout 600`;
+        autoRoute(
+          headlessCmd,
+          `[headless-guard] auto-route: tfx-route.sh → headless 변환. 원본 agent=${parsed.agent}, mcp=${parsed.mcp}`,
+        );
+      }
+      // 파싱 실패 시 deny fallback
+      deny(
+        "[headless-guard] Phase 3 활성 중. tfx-route.sh 명령을 headless로 변환할 수 없습니다. " +
+        'Bash("tfx multi --teammate-mode headless --auto-attach --assign \'cli:prompt:role\' ...") 형식을 사용하세요.',
+      );
+    }
+  }
+
+  // ── Agent: CLI 워커 래핑 시도 → deny (tool 타입 변환 불가) ──
+  if (toolName === "Agent") {
+    const prompt = (toolInput.prompt || "").toLowerCase();
+    const desc = (toolInput.description || "").toLowerCase();
+    const combined = `${prompt} ${desc}`;
+
+    const cliWorkerPatterns = [
+      /codex\s+(exec|run|실행)/,
+      /gemini\s+(-p|run|실행)/,
+      /tfx-route/,
+      /bash.*codex/,
+      /bash.*gemini/,
+    ];
+
+    if (cliWorkerPatterns.some((p) => p.test(combined))) {
+      deny(
+        "[headless-guard] Phase 3 활성 중. " +
+        "Codex/Gemini를 Agent()로 래핑하지 말고 headless --assign으로 전달하세요. " +
+        'Bash("tfx multi --teammate-mode headless --assign \'codex:prompt:role\' ...")',
+      );
+    }
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/skills/tfx-auto/SKILL.md

@@ -160,19 +160,18 @@ Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
 | 2개+ + thorough | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
 | psmux 미설치 fallback | Native Teams (Agent slim wrapper) | native.mjs |
 
-**전환 방법:** 트리아지 완료 후 서브태스크 배열을 headless.runHeadlessInteractive()에 전달.
-Windows Terminal에 psmux 세션이 자동 팝업되어 사용자가 실시간으로 CLI 출력 확인.
+> **MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수**
+> `Agent()` 백그라운드나 `Bash(tfx-route.sh)` 개별 호출로 대체 금지.
+> 반드시 아래 `Bash("tfx multi ...")` 명령으로 headless 엔진에 위임한다.
+
+**전환 방법:**
 
 ```
 thorough = args에 -t 또는 --thorough 포함
 
 if subtasks.length >= 2:
   if psmux 설치됨:
-    → headless.runHeadlessInteractive(assignments, {
-        autoAttach: true,     // WT 자동 팝업
-        progressive: true,    // 실시간 스플릿
-        progressIntervalSec: 10,
-      })
+    → Bash("tfx multi --teammate-mode headless --auto-attach --assign 'cli:prompt:role' ...")
     → if thorough: verify → fix loop
   else:
     → fallback: tfx-multi Phase 3 Native Teams (Agent slim wrapper)

package/skills/tfx-multi/SKILL.md

@@ -75,60 +75,73 @@ preflight와 Agent 생성을 병렬로 실행하여 사용자 체감 지연을
 
 ### Phase 3: Lead-Direct Headless 실행 (v6.0.0, 기본)
 
-CLI 워커(Codex/Gemini/Claude)를 Agent 래퍼 없이 Lead가 headless.mjs로 직접 실행.
-Windows Terminal에 psmux 세션이 자동 팝업되어 사용자가 실시간으로 CLI 출력을 확인.
-
-**핵심 기능:**
-- `progressive: true` (기본) — pane이 하나씩 split-window로 추가 (실시간 스플릿)
-- `autoAttach: true` — 세션 생성 즉시 Windows Terminal 자동 팝업
-- `progressIntervalSec` — N초마다 각 pane 스냅샷을 onProgress로 전달
-- `applyTrifluxTheme()` — status bar + pane border 테마 자동 적용
-- 피드백 재실행 — 같은 pane에 후속 명령 dispatch (세션 유지)
-
-**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" },
-  { cli: "claude", prompt: "테스트 실행", role: "tester" },
-], {
-  timeoutSec: 300,
-  autoAttach: true,          // WT 자동 팝업
-  progressive: true,         // 실시간 스플릿 (기본)
-  progressIntervalSec: 10,   // 10초마다 진행 스냅샷
-});
-// handle: { results, dispatch(), capture(), snapshots(), waitFor(), kill() }
+> **MANDATORY: 2개+ CLI 워커 실행 시 headless 엔진 필수**
+> 서브태스크가 2개 이상이면 반드시 아래 `Bash()` 명령으로 headless 엔진을 실행한다.
+> `Agent()` 백그라운드나 `Bash(tfx-route.sh)` 개별 호출로 대체하지 않는다.
+> headless 엔진이 psmux 세션 생성 → WT 자동 팝업 → CLI dispatch → 결과 수집을 전부 처리한다.
+
+**Step 1 — headless guard 활성화 (Phase 3 진입 시 반드시 먼저 실행):**
+
+```
+Bash("node -e \"require('fs').writeFileSync(require('os').tmpdir()+'/tfx-headless-guard.lock', String(Date.now()))\"")
+```
+
+**Step 2 — headless 엔진 실행 (Lead가 호출하는 유일한 명령):**
+
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --assign 'codex:{프롬프트1}:{역할1}' --assign 'gemini:{프롬프트2}:{역할2}' --timeout 600")
+```
+
+**Step 3 — headless guard 해제 (Phase 3 완료 후):**
+
+```
+Bash("node -e \"try{require('fs').unlinkSync(require('os').tmpdir()+'/tfx-headless-guard.lock')}catch{}\"")
+```
+
+**예시:**
+
+```
+Bash("tfx multi --teammate-mode headless --auto-attach --assign 'codex:코드 리뷰하고 개선 사항 제안:reviewer' --assign 'gemini:API 문서 작성:writer' --assign 'codex:보안 취약점 분석:security' --timeout 600")
+```
+
+**Claude 워커가 Read/Edit 필요한 경우 (하이브리드):**
+
+Claude 워커는 headless에서 실행 불가 (Read/Edit 도구 필요). CLI 워커만 headless로 보내고 Claude 워커는 Agent로 병렬 실행.
+
+```
+# 1. CLI 워커를 headless로 dispatch
+Bash("tfx multi --teammate-mode headless --auto-attach --assign 'codex:{프롬프트}:{역할}' --assign 'gemini:{프롬프트}:{역할}' --timeout 600")
+
+# 2. Claude 워커를 Agent로 병렬 실행 (headless Bash와 동시에 spawn)
+Agent(subagent_type="...", prompt="...", run_in_background=true)
 ```
 
 **결정 로직:**
 ```
-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 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 테마.
+if 모든 워커가 CLI (codex/gemini):
+  → Bash("tfx multi --teammate-mode headless --auto-attach --assign ...")
+elif CLI + Claude 혼합:
+  → CLI 워커: Bash("tfx multi --teammate-mode headless --assign ...")
+  → Claude 워커: Agent(subagent_type, run_in_background=true)
+elif psmux 미설치:
+  → Phase 3-fallback (아래)
+```
+
+**headless 엔진이 자동으로 수행하는 것:**
+- psmux 세션 생성 + progressive split-window
+- Windows Terminal 자동 팝업 (autoAttach)
+- triflux 테마 적용 (Catppuccin Mocha status bar)
+- CLI 명령 dispatch + 완료 토큰 폴링
+- 결과 수집 + JSON stdout 출력
+- 세션 정리
+
+**출력 파싱:** headless 완료 후 stdout에 JSON 결과가 출력된다. 성공/실패 워커 수, 각 워커 출력을 파싱.
+**크래시 복구:** 세션 사망 시 `{sessionDead: true}` 반환 (throw 대신).
 **실수로 닫아도:** psmux 세션은 독립적. `psmux attach -t 세션이름`으로 재연결.
 
 ### Phase 4: 결과 수집 + 정리
 
-headless 완료 후 `handle.results`에서 직접 수집. `handle.kill()`로 세션 정리.
+headless stdout 출력에서 성공/실패 워커를 파싱.
 실패 워커(`exitCode !== 0`)는 Claude fallback 재시도.
 
 ### Phase 3-fallback: Native Teams (psmux 미설치 시)
@@ -138,8 +151,6 @@ psmux가 없는 환경에서만 사용. Agent slim wrapper로 CLI를 실행.
 
 > 래퍼 규칙 상세 → [`references/agent-wrapper-rules.md`](references/agent-wrapper-rules.md)
 
-**레거시 인터랙티브 모드:** `Bash("node {PKG_ROOT}/bin/triflux.mjs multi --no-attach --agents {agents} \\\"{task}\\\"")`
-
 ## 전제 조건
 
 - **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — `tfx setup`이 자동 설정