triflux 3.2.0-dev.2 → 3.2.0-dev.3

package/hub/team/nativeProxy.mjs

@@ -47,10 +47,10 @@ function atomicWriteJson(path, value) {
   renameSync(tmp, path);
 }
 
-function sleepMs(ms) {
-  const end = Date.now() + ms;
-  while (Date.now() < end) {}
-}
+function sleepMs(ms) {
+  // busy-wait를 피하고 Atomics.wait로 동기 대기 (CPU 점유 최소화)
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 
 function withFileLock(lockPath, fn, retries = 20, delayMs = 25) {
   let fd = null;
@@ -419,37 +419,42 @@ export function teamSendMessage(args = {}) {
     return err('TEAM_NOT_FOUND', `팀 디렉토리가 없습니다: ${paths.team_dir}`);
   }
 
-  const recipient = sanitizeRecipientName(to);
-  const inboxFile = join(paths.inboxes_dir, `${recipient}.json`);
-  const queue = readJsonSafe(inboxFile);
-  const list = Array.isArray(queue) ? queue : [];
-
-  const message = {
-    id: randomUUID(),
-    from: String(from),
-    text: String(text),
-    ...(summary ? { summary: String(summary) } : {}),
-    timestamp: new Date().toISOString(),
-    color: String(color || 'blue'),
-    read: false,
-  };
-  list.push(message);
-
-  try {
-    atomicWriteJson(inboxFile, list);
-  } catch (e) {
-    return err('SEND_MESSAGE_FAILED', e.message);
-  }
-
-  const unreadCount = list.filter((m) => m?.read !== true).length;
-  return {
-    ok: true,
-    data: {
-      message_id: message.id,
-      recipient,
-      inbox_file: inboxFile,
-      queued_at: message.timestamp,
-      unread_count: unreadCount,
-    },
-  };
-}
+  const recipient = sanitizeRecipientName(to);
+  const inboxFile = join(paths.inboxes_dir, `${recipient}.json`);
+  const lockFile = `${inboxFile}.lock`;
+  let message;
+
+  try {
+    const unreadCount = withFileLock(lockFile, () => {
+      const queue = readJsonSafe(inboxFile);
+      const list = Array.isArray(queue) ? queue : [];
+
+      message = {
+        id: randomUUID(),
+        from: String(from),
+        text: String(text),
+        ...(summary ? { summary: String(summary) } : {}),
+        timestamp: new Date().toISOString(),
+        color: String(color || 'blue'),
+        read: false,
+      };
+      list.push(message);
+      atomicWriteJson(inboxFile, list);
+
+      return list.filter((m) => m?.read !== true).length;
+    });
+
+    return {
+      ok: true,
+      data: {
+        message_id: message.id,
+        recipient,
+        inbox_file: inboxFile,
+        queued_at: message.timestamp,
+        unread_count: unreadCount,
+      },
+    };
+  } catch (e) {
+    return err('SEND_MESSAGE_FAILED', e.message);
+  }
+}

package/hub/team/pane.mjs

@@ -39,13 +39,18 @@ function tmux(args, opts = {}) {
 /**
  * CLI 에이전트 시작 커맨드 생성
  * @param {'codex'|'gemini'|'claude'} cli
- * @returns {string} 실행할 셸 커맨드
- */
-export function buildCliCommand(cli) {
-  switch (cli) {
-    case "codex":
-      // interactive REPL 진입 — MCP는 ~/.codex/config.json에 사전 등록
-      return "codex";
+ * @param {{ trustMode?: boolean }} [options]
+ * @returns {string} 실행할 셸 커맨드
+ */
+export function buildCliCommand(cli, options = {}) {
+  const { trustMode = false } = options;
+
+  switch (cli) {
+    case "codex":
+      // trust 모드에서는 승인/샌드박스 우회 + alt-screen 비활성화
+      return trustMode
+        ? "codex --dangerously-bypass-approvals-and-sandbox --no-alt-screen"
+        : "codex";
     case "gemini":
       // interactive 모드 — MCP는 ~/.gemini/settings.json에 사전 등록
       return "gemini";

package/package.json

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

package/scripts/tfx-route.sh

@@ -31,12 +31,19 @@ CONTEXT_FILE="${5:-}"
 CODEX_BIN="${CODEX_BIN:-$(command -v codex 2>/dev/null || echo codex)}"
 GEMINI_BIN="${GEMINI_BIN:-$(command -v gemini 2>/dev/null || echo gemini)}"
 
-# ── 상수 ──
-MAX_STDOUT_BYTES=51200  # 50KB — Claude 컨텍스트 절약
-TIMESTAMP=$(date +%s)
-STDERR_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stderr.log"
-STDOUT_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stdout.log"
-TFX_TMP="${TMPDIR:-/tmp}"
+# ── 상수 ──
+MAX_STDOUT_BYTES=51200  # 50KB — Claude 컨텍스트 절약
+TIMESTAMP=$(date +%s)
+STDERR_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stderr.log"
+STDOUT_LOG="/tmp/tfx-route-${AGENT_TYPE}-${TIMESTAMP}-stdout.log"
+TFX_TMP="${TMPDIR:-/tmp}"
+
+# ── 팀 환경변수 ──
+TFX_TEAM_NAME="${TFX_TEAM_NAME:-}"
+TFX_TEAM_TASK_ID="${TFX_TEAM_TASK_ID:-}"
+TFX_TEAM_AGENT_NAME="${TFX_TEAM_AGENT_NAME:-${AGENT_TYPE}-worker-$$}"
+TFX_TEAM_LEAD_NAME="${TFX_TEAM_LEAD_NAME:-team-lead}"
+TFX_HUB_URL="${TFX_HUB_URL:-http://127.0.0.1:27888}"
 
 # fallback 시 원래 에이전트 정보 보존
 ORIGINAL_AGENT=""
@@ -49,13 +56,83 @@ register_agent() {
     > "$agent_file" 2>/dev/null || true
 }
 
-deregister_agent() {
-  rm -f "${TFX_TMP}/tfx-agent-$$.json" 2>/dev/null || true
-}
-
-# ── 라우팅 테이블 ──
-# 반환: CLI_CMD, CLI_ARGS, CLI_TYPE, CLI_EFFORT, DEFAULT_TIMEOUT, RUN_MODE, OPUS_OVERSIGHT
-route_agent() {
+deregister_agent() {
+  rm -f "${TFX_TMP}/tfx-agent-$$.json" 2>/dev/null || true
+}
+
+# ── 팀 Hub Bridge 통신 ──
+# JSON 문자열 이스케이프 (큰따옴표, 백슬래시, 개행, 탭, CR)
+json_escape() {
+  local s="${1:-}"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\t'/\\t}"
+  s="${s//$'\r'/\\r}"
+  echo "$s"
+}
+
+team_claim_task() {
+  [[ -z "$TFX_TEAM_NAME" || -z "$TFX_TEAM_TASK_ID" ]] && return 0
+  local http_code safe_team_name safe_task_id safe_agent_name
+  safe_team_name=$(json_escape "$TFX_TEAM_NAME")
+  safe_task_id=$(json_escape "$TFX_TEAM_TASK_ID")
+  safe_agent_name=$(json_escape "$TFX_TEAM_AGENT_NAME")
+
+  http_code=$(curl -sf -o /dev/null -w "%{http_code}" -X POST "${TFX_HUB_URL}/bridge/team/task-update" \
+    -H "Content-Type: application/json" \
+    -d "{\"team_name\":\"${safe_team_name}\",\"task_id\":\"${safe_task_id}\",\"claim\":true,\"owner\":\"${safe_agent_name}\",\"status\":\"in_progress\"}" \
+    2>/dev/null) || http_code="000"
+
+  case "$http_code" in
+    200) ;; # 성공
+    409)
+      echo "[tfx-route] CLAIM_CONFLICT: task ${TFX_TEAM_TASK_ID}가 이미 claim됨. 실행 중단." >&2
+      exit 0 ;;
+    000)
+      echo "[tfx-route] 경고: Hub 연결 실패 (미실행?). claim 없이 계속 실행." >&2 ;;
+    *)
+      echo "[tfx-route] 경고: Hub claim 응답 HTTP ${http_code}. claim 없이 계속 실행." >&2 ;;
+  esac
+}
+
+team_complete_task() {
+  local result_status="${1:-completed}"
+  local result_summary="${2:-작업 완료}"
+  local safe_team_name safe_task_id safe_agent_name safe_status
+  [[ -z "$TFX_TEAM_NAME" || -z "$TFX_TEAM_TASK_ID" ]] && return 0
+  safe_team_name=$(json_escape "$TFX_TEAM_NAME")
+  safe_task_id=$(json_escape "$TFX_TEAM_TASK_ID")
+  safe_agent_name=$(json_escape "$TFX_TEAM_AGENT_NAME")
+  safe_status=$(json_escape "$result_status")
+
+  # task 상태 업데이트
+  curl -sf -X POST "${TFX_HUB_URL}/bridge/team/task-update" \
+    -H "Content-Type: application/json" \
+    -d "{\"team_name\":\"${safe_team_name}\",\"task_id\":\"${safe_task_id}\",\"status\":\"${safe_status}\",\"owner\":\"${safe_agent_name}\"}" \
+    >/dev/null 2>&1 || true
+
+  # 리드에게 메시지 전송
+  local msg_text safe_text safe_lead_name
+  msg_text=$(echo "$result_summary" | head -c 4096)
+  safe_text=$(json_escape "$msg_text")
+  safe_lead_name=$(json_escape "$TFX_TEAM_LEAD_NAME")
+
+  curl -sf -X POST "${TFX_HUB_URL}/bridge/team/send-message" \
+    -H "Content-Type: application/json" \
+    -d "{\"team_name\":\"${safe_team_name}\",\"from\":\"${safe_agent_name}\",\"to\":\"${safe_lead_name}\",\"text\":\"${safe_text}\",\"summary\":\"task ${safe_task_id} ${safe_status}\"}" \
+    >/dev/null 2>&1 || true
+
+  # Hub result 발행 (poll_messages 채널 활성화)
+  curl -sf -X POST "${TFX_HUB_URL}/bridge/result" \
+    -H "Content-Type: application/json" \
+    -d "{\"agent_id\":\"${safe_agent_name}\",\"topic\":\"task.result\",\"payload\":{\"task_id\":\"${safe_task_id}\",\"status\":\"${safe_status}\"},\"trace_id\":\"${safe_team_name}\"}" \
+    >/dev/null 2>&1 || true
+}
+
+# ── 라우팅 테이블 ──
+# 반환: CLI_CMD, CLI_ARGS, CLI_TYPE, CLI_EFFORT, DEFAULT_TIMEOUT, RUN_MODE, OPUS_OVERSIGHT
+route_agent() {
   local agent="$1"
   local codex_base="--dangerously-bypass-approvals-and-sandbox --skip-git-repo-check"
 
@@ -351,16 +428,20 @@ ${ctx_content}
   local FULL_PROMPT="$PROMPT"
   [[ -n "$mcp_hint" ]] && FULL_PROMPT="${PROMPT}. ${mcp_hint}"
 
-  # 메타정보 (stderr)
-  echo "[tfx-route] v${VERSION} type=$CLI_TYPE agent=$AGENT_TYPE effort=$CLI_EFFORT mode=$RUN_MODE timeout=${TIMEOUT_SEC}s" >&2
-  echo "[tfx-route] opus_oversight=$OPUS_OVERSIGHT mcp_profile=$MCP_PROFILE" >&2
-
-  # Per-process 에이전트 등록
-  register_agent
-
-  # CLI 실행 (stderr 분리 + 타임아웃 + 소요시간 측정)
-  local exit_code=0
-  local start_time
+  # 메타정보 (stderr)
+  echo "[tfx-route] v${VERSION} type=$CLI_TYPE agent=$AGENT_TYPE effort=$CLI_EFFORT mode=$RUN_MODE timeout=${TIMEOUT_SEC}s" >&2
+  echo "[tfx-route] opus_oversight=$OPUS_OVERSIGHT mcp_profile=$MCP_PROFILE" >&2
+  [[ -n "$TFX_TEAM_NAME" ]] && echo "[tfx-route] team=$TFX_TEAM_NAME task=$TFX_TEAM_TASK_ID agent=$TFX_TEAM_AGENT_NAME" >&2
+
+  # Per-process 에이전트 등록
+  register_agent
+
+  # 팀 모드: task claim
+  team_claim_task
+
+  # CLI 실행 (stderr 분리 + 타임아웃 + 소요시간 측정)
+  local exit_code=0
+  local start_time
   start_time=$(date +%s)
 
   if [[ "$CLI_TYPE" == "codex" ]]; then
@@ -410,13 +491,28 @@ ${ctx_content}
     fi
   fi
 
-  local end_time
-  end_time=$(date +%s)
-  local elapsed=$((end_time - start_time))
-
-  # ── 후처리: 단일 node 프로세스로 위임 ──
-  # 토큰 추출, 출력 필터링, 로그, 토큰 누적, AIMD, 이슈 추적, 결과 출력 전부 처리
-  local post_script="${HOME}/.claude/scripts/tfx-route-post.mjs"
+  local end_time
+  end_time=$(date +%s)
+  local elapsed=$((end_time - start_time))
+
+  # 팀 모드: task complete + 리드 보고
+  if [[ -n "$TFX_TEAM_NAME" ]]; then
+    if [[ "$exit_code" -eq 0 ]]; then
+      local output_preview
+      output_preview=$(head -c 2048 "$STDOUT_LOG" 2>/dev/null || echo "출력 없음")
+      team_complete_task "completed" "$output_preview"
+    elif [[ "$exit_code" -eq 124 ]]; then
+      team_complete_task "failed" "타임아웃 (${TIMEOUT_SEC}초)"
+    else
+      local err_preview
+      err_preview=$(tail -c 1024 "$STDERR_LOG" 2>/dev/null || echo "에러 정보 없음")
+      team_complete_task "failed" "exit_code=${exit_code}: ${err_preview}"
+    fi
+  fi
+
+  # ── 후처리: 단일 node 프로세스로 위임 ──
+  # 토큰 추출, 출력 필터링, 로그, 토큰 누적, AIMD, 이슈 추적, 결과 출력 전부 처리
+  local post_script="${HOME}/.claude/scripts/tfx-route-post.mjs"
   if [[ -f "$post_script" ]]; then
     node "$post_script" \
       --agent "$AGENT_TYPE" \

package/skills/tfx-team/SKILL.md

@@ -1,47 +1,47 @@
----
-name: tfx-team
-description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
-triggers:
-  - tfx-team
-argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
----
-
-# tfx-team v2 — Claude Native Teams 기반 멀티-CLI 팀 오케스트레이터
-
-> Claude Code의 네이티브 Agent Teams (in-process 모드)를 활용하여
-> tmux 없이 현재 터미널에서 Codex/Gemini/Claude 멀티모델 팀을 구성한다.
-> 각 teammate는 Claude Code 인스턴스이지만 Codex/Gemini CLI **래퍼**로 동작하여 토큰을 최소화한다.
-
-| | tfx-auto | tfx-team v1 (tmux) | **tfx-team v2 (native)** |
-|--|----------|--------------------|-----------------------------|
-| 트리아지 | Codex 분류 → Opus 분해 | 동일 | **동일** |
-| 실행 | tfx-route.sh one-shot | tmux pane interactive | **Native Teams in-process** |
-| 관찰 | stdout 반환 | Ctrl+B 방향키 | **Shift+Down teammate 전환** |
-| 통신 | 없음 | Hub MCP 버스 | **내장 Mailbox + Task List** |
-| 개입 | 불가 | tfx team send | **SendMessage** |
-| tmux 필요 | ✗ | ✓ | **✗** |
-
-## 사용법
-
+---
+name: tfx-team
+description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+triggers:
+  - tfx-team
+argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'
+---
+
+# tfx-team v2.1 — Lead Direct Bash 기반 멀티-CLI 팀 오케스트레이터
+
+> Claude Code Native Teams는 유지하되, Codex/Gemini 실행 경로에서 Claude teammate 래퍼를 제거한다.
+> 리드가 `tfx-route.sh`를 직접 병렬 실행하고, task 상태는 `team_task_list`를 truth source로 검증한다.
+
+| 구분 | v2 (기존) | v2.1 (현재) |
+|--|--|--|
+| 실행 | `Agent(teammate)` → `Bash(tfx-route.sh)` | `Lead` → `Bash(tfx-route.sh)` 직접 |
+| teammate | Claude Opus 인스턴스 × N | Codex/Gemini용 없음 |
+| task claim | teammate가 `TaskUpdate` 호출 | `tfx-route.sh`가 Hub bridge로 claim |
+| 결과 보고 | teammate가 `SendMessage` 호출 | `tfx-route.sh`가 Hub bridge로 `send-message` 호출 |
+| 결과 수집 | SendMessage 자동 수신 중심 | `team_task_list` 폴링 + stdout/결과 로그 |
+| 정리 | `shutdown_request` × N 후 `TeamDelete` | `TeamDelete` 직접 |
+| Opus 토큰 | N × 래퍼 오버헤드 | 래퍼 오버헤드 0 |
+
+## 사용법
+
 ```
 /tfx-team "인증 리팩터링 + UI 개선 + 보안 리뷰"
 /tfx-team --agents codex,gemini "프론트+백엔드"
 /tfx-team --tmux "작업"         # 레거시 tmux 모드
 /tfx-team status
-/tfx-team stop
-```
-
-## 실행 워크플로우
-
-### Phase 1: 입력 파싱
-
-```
-입력: "3:codex 리뷰"         → 수동 모드: N=3, agent=codex
-입력: "인증 + UI + 테스트"    → 자동 모드: Codex 분류 → Opus 분해
-입력: "--tmux 인증 + UI"     → tmux 레거시 모드 → Phase 3-tmux로 분기
-입력: "status"               → 제어 커맨드
-입력: "stop"                 → 제어 커맨드
-```
+/tfx-team stop
+```
+
+## 실행 워크플로우
+
+### Phase 1: 입력 파싱
+
+```
+입력: "3:codex 리뷰"         → 수동 모드: N=3, agent=codex
+입력: "인증 + UI + 테스트"    → 자동 모드: Codex 분류 → Opus 분해
+입력: "--tmux 인증 + UI"     → tmux 레거시 모드 → Phase 3-tmux로 분기
+입력: "status"               → 제어 커맨드
+입력: "stop"                 → 제어 커맨드
+```
 
 **제어 커맨드 감지:**
 - `status`, `stop`, `kill`, `attach`, `list`, `send` → `Bash("node bin/triflux.mjs team {cmd}")` 직행
@@ -49,26 +49,26 @@ argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작
 - 그 외 → Phase 2 트리아지
 
 **--tmux 감지:** 입력에 `--tmux`가 포함되면 Phase 3-tmux로 분기.
-
-### Phase 2: 트리아지 (tfx-auto와 동일)
-
-#### 자동 모드 — Codex 분류 → Opus 분해
-
-```bash
-# Step 2a: Codex 분류 (무료)
-Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하고 각 부분에 적합한 agent를 분류하라.
-
-  agent 선택:
-  - codex: 코드 구현/수정/분석/리뷰/디버깅/설계 (기본값)
-  - gemini: 문서/UI/디자인/멀티모달
-  - claude: 코드베이스 탐색/테스트 실행/검증 (최후 수단)
-
-  작업: {task}
-
-  JSON만 출력:
-  { \"parts\": [{ \"description\": \"...\", \"agent\": \"codex|gemini|claude\" }] }
-'")
-```
+
+### Phase 2: 트리아지 (tfx-auto와 동일)
+
+#### 자동 모드 — Codex 분류 → Opus 분해
+
+```bash
+# Step 2a: Codex 분류 (무료)
+Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하고 각 부분에 적합한 agent를 분류하라.
+
+  agent 선택:
+  - codex: 코드 구현/수정/분석/리뷰/디버깅/설계 (기본값)
+  - gemini: 문서/UI/디자인/멀티모달
+  - claude: 코드베이스 탐색/테스트 실행/검증 (최후 수단)
+
+  작업: {task}
+
+  JSON만 출력:
+  { \"parts\": [{ \"description\": \"...\", \"agent\": \"codex|gemini|claude\" }] }
+'")
+```
 
 > Codex 분류 실패 시 → Opus(오케스트레이터)가 직접 분류+분해
 
@@ -79,161 +79,129 @@ Bash("codex exec --full-auto --skip-git-repo-check '다음 작업을 분석하
    { cli: "gemini", subtask: "UI 개선", role: "designer" },
    { cli: "codex", subtask: "보안 리뷰", role: "reviewer" }]
 ```
-
-#### 수동 모드 (`N:agent_type` 또는 `--agents`)
-
-Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
-
-### Phase 3: Native Teams 실행
-
-트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
-
-#### Step 3a: 팀 생성
-
+
+#### 수동 모드 (`N:agent_type` 또는 `--agents`)
+
+Codex 분류 건너뜀 → Opus가 직접 N개 서브태스크 분해.
+
+### Phase 3: Native Teams 실행 (v2.1 개편)
+
+트리아지 결과를 Claude Code 네이티브 Agent Teams로 실행한다.
+
+#### Step 3a: 팀 생성
+
 ```
 teamName = "tfx-" + Date.now().toString(36).slice(-6)
 
 TeamCreate({
   team_name: teamName,
   description: "tfx-team: {원본 작업 요약}"
-})
-```
-
-#### Step 3b: 공유 작업 등록
-
-각 서브태스크에 대해 TaskCreate를 호출한다:
-
-```
-for each assignment in assignments:
-  TaskCreate({
-    subject: assignment.subtask,
-    description: "CLI: {assignment.cli}, 역할: {assignment.role}\n\n{상세 작업 내용}",
-    metadata: { cli: assignment.cli, role: assignment.role }
-  })
-```
-
-#### Step 3c: Teammate 스폰
-
-**Agent 도구**에 `team_name`과 `name` 파라미터를 전달하여 teammate를 생성한다.
-**모든 teammate를 `run_in_background: true`로 병렬 스폰한다.**
-
-각 CLI 타입별 teammate 프롬프트:
-
-**codex-worker (Codex CLI 래퍼):**
-
-```
-Agent({
-  name: "codex-worker-{n}",
-  team_name: teamName,
-  description: "codex-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Codex 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Bash(\"bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' auto\")로 실행
-4. 결과를 확인하고:
-   - 성공: TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-   - 실패: TaskUpdate에 에러 기록 + SendMessage로 리드에게 보고
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-[규칙]
-- 실제 구현은 Codex CLI가 수행 — 너는 실행+보고 역할만
-- tfx-route.sh 결과를 그대로 보고하라 (요약하지 말 것)"
-})
-```
-
-**gemini-worker (Gemini CLI 래퍼):**
-
-```
-Agent({
-  name: "gemini-worker-{n}",
-  team_name: teamName,
-  description: "gemini-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Gemini 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Bash(\"bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' auto\")로 실행
-4. 결과를 확인하고:
-   - 성공: TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-   - 실패: TaskUpdate에 에러 기록 + SendMessage로 리드에게 보고
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-[규칙]
-- 실제 구현은 Gemini CLI가 수행 — 너는 실행+보고 역할만
-- tfx-route.sh 결과를 그대로 보고하라 (요약하지 말 것)"
-})
-```
-
-**claude-worker (직접 실행):**
-
-```
-Agent({
-  name: "claude-worker-{n}",
-  team_name: teamName,
-  description: "claude-worker-{n}",
-  run_in_background: true,
-  prompt: "너는 {teamName}의 Claude 워커이다.
-
-[실행 규칙]
-1. TaskList를 호출하여 너에게 배정된 pending 작업을 확인하라
-2. TaskGet으로 작업 상세를 읽고, TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
-3. Glob, Grep, Read, Bash 등 도구를 직접 사용하여 작업 수행
-4. 완료 시 TaskUpdate(status: completed) + SendMessage(type: message, recipient: team-lead, summary: '작업 완료')
-5. TaskList를 다시 확인하고 추가 pending 작업이 있으면 반복
-
-에러 시 TaskUpdate + SendMessage로 리드에게 보고."
-})
-```
-
-#### Step 3d: 사용자 안내
-
-```
-"팀 '{teamName}' 생성 완료 ({N}명의 teammate).
-Shift+Down으로 각 teammate의 진행 상황을 확인할 수 있습니다."
-```
-
-### Phase 4: 결과 수집
-
-리드(이 오케스트레이터)가:
-1. teammate들의 SendMessage를 자동 수신 (폴링 불필요 — 자동 배달됨)
-2. 모든 teammate가 결과를 보고하면 TaskList로 전체 상태 확인
-3. 모든 작업이 completed이면 종합 보고서 출력:
-
-```markdown
-## tfx-team 실행 결과
-
-| # | Teammate | CLI | 작업 | 상태 |
-|---|----------|-----|------|------|
-| 1 | codex-worker-1 | codex | 인증 리팩터링 | ✓ completed |
-| 2 | gemini-worker-1 | gemini | UI 개선 | ✓ completed |
-| 3 | codex-worker-2 | codex | 보안 리뷰 | ✓ completed |
-```
-
-### Phase 5: 정리
-
-```
-# 각 teammate에 shutdown 요청
-for each teammate in teammates:
-  SendMessage({
-    type: "shutdown_request",
-    recipient: teammate.name,
-    content: "모든 작업 완료. 종료합니다."
-  })
-
-# 모든 teammate 종료 후 팀 삭제
-TeamDelete()
-```
-
-> **중요:** TeamDelete는 활성 멤버가 있으면 실패한다. 반드시 모든 teammate에 shutdown_request를 보내고 종료를 확인한 후 호출.
-
-### Phase 3-tmux: 레거시 tmux 모드
-
-`--tmux` 플래그가 있으면 기존 v1 방식으로 실행:
+})
+```
+
+#### Step 3b: 공유 작업 등록
+
+각 서브태스크에 대해 `TaskCreate`를 호출하고 `taskId`를 보존한다.
+리드가 실행 시 사용할 `agentName`도 함께 확정한다.
+
+```
+for each assignment in assignments (index i):
+  TaskCreate({
+    subject: assignment.subtask,
+    description: "CLI: {assignment.cli}, 역할: {assignment.role}\n\n{상세 작업 내용}",
+    metadata: { cli: assignment.cli, role: assignment.role }
+  })
+  taskId = created_task.id
+  agentName = "{assignment.cli}-worker-{i+1}"
+  runQueue.push({ taskId, agentName, ...assignment })
+```
+
+#### Step 3c: 리드가 직접 Bash 병렬 실행 (teammate 스폰 제거)
+
+Codex/Gemini 서브태스크는 teammate를 만들지 않고, 리드가 직접 `Bash(..., run_in_background=true)`를 병렬 호출한다.
+
+```
+for each item in runQueue where item.cli in ["codex", "gemini"]:
+  Bash(
+    "TFX_TEAM_NAME={teamName} TFX_TEAM_TASK_ID={item.taskId} TFX_TEAM_AGENT_NAME={item.agentName} TFX_TEAM_LEAD_NAME=team-lead bash ~/.claude/scripts/tfx-route.sh {item.role} \"{item.subtask}\" {mcp_profile}",
+    run_in_background=true
+  )
+```
+
+`tfx-route.sh` 팀 통합 동작(이미 구현됨, `TFX_TEAM_*` 기반):
+- `TFX_TEAM_NAME`: 팀 식별자
+- `TFX_TEAM_TASK_ID`: 작업 식별자
+- `TFX_TEAM_AGENT_NAME`: 워커 표기 이름
+- `TFX_TEAM_LEAD_NAME`: 리드 수신자 이름 (기본 `team-lead`)
+
+Bridge 연동:
+- 실행 시작 시 `POST /bridge/team/task-update`로 `claim + in_progress`
+- 실행 종료 시 `POST /bridge/team/task-update`로 `completed|failed`
+- 리드 보고 `POST /bridge/team/send-message`
+- 이벤트 채널 `POST /bridge/result` (`topic=task.result`) 발행
+
+#### Step 3d: claude 타입만 Agent 직접 실행
+
+`cli == claude`인 서브태스크에만 `Agent(subagent_type)`를 사용한다.
+
+```
+Agent({
+  name: "claude-worker-{n}",
+  team_name: teamName,
+  description: "claude-worker-{n}",
+  run_in_background: true,
+  subagent_type: "{role}",
+  prompt: "너는 {teamName}의 Claude 워커이다.
+
+1. TaskGet 후 TaskUpdate(status: in_progress, owner: 너의 이름)로 claim
+2. 도구를 직접 사용해 작업 수행
+3. 성공 시 TaskUpdate(status: completed) + SendMessage(to: team-lead)
+4. 실패 시 TaskUpdate(status: failed) + SendMessage(to: team-lead)"
+})
+```
+
+#### Step 3e: 사용자 안내
+
+```
+"팀 '{teamName}' 생성 완료.
+Codex/Gemini 작업은 리드가 백그라운드 Bash로 병렬 실행 중이며,
+claude 작업만 teammate로 실행됩니다."
+```
+
+### Phase 4: 결과 수집 (truth source = team_task_list)
+
+1. 리드가 Step 3c에서 실행한 모든 백그라운드 Bash 프로세스 완료를 대기한다.
+2. `team_task_list`를 최종 truth source로 조회한다.
+
+```bash
+Bash("curl -sf http://127.0.0.1:27888/bridge/team/task-list -H \"Content-Type: application/json\" -d \"{\\\"team_name\\\":\\\"${teamName}\\\"}\"")
+```
+
+3. 상태가 `failed`인 task가 있으면 Claude fallback으로 재시도한다.
+4. 재시도 후 다시 `team_task_list`를 조회해 최종 상태를 확정한다.
+5. `send-message`와 `/bridge/result(task.result)` 이벤트는 진행 관찰 채널로 사용하고, 최종 판정은 반드시 `team_task_list` 기준으로 한다.
+
+종합 보고서 예시:
+```markdown
+## tfx-team 실행 결과
+
+| # | Worker | CLI | 작업 | 상태 |
+|---|--------|-----|------|------|
+| 1 | codex-worker-1 | codex | 인증 리팩터링 | completed |
+| 2 | gemini-worker-1 | gemini | UI 개선 | completed |
+| 3 | claude-worker-1 | claude | 실패 fallback 재시도 | completed |
+```
+
+### Phase 5: 정리 (간소화)
+
+teammate 래퍼를 제거했으므로 `shutdown_request` 브로드캐스트를 사용하지 않는다.
+정리 단계는 `TeamDelete()` 직접 호출로 마무리한다.
+
+> **중요:** claude 타입 백그라운드 Agent가 아직 실행 중이면 `TeamDelete`가 실패할 수 있다. 해당 작업 완료를 확인한 뒤 삭제한다.
+
+### Phase 3-tmux: 레거시 tmux 모드
+
+`--tmux` 플래그가 있으면 기존 v1 방식으로 실행:
 
 ```bash
 # PKG_ROOT: triflux 패키지 루트 (Bash로 확인)
@@ -243,48 +211,49 @@ Bash("node {PKG_ROOT}/bin/triflux.mjs team --no-attach --agents {agents.join(','
 이후 Phase 4-5 대신 사용자에게 tmux 세션 안내:
 
 ```
-"tmux 세션이 생성되었습니다.
-  tmux attach -t {sessionId}     세션 연결
-  Ctrl+B → 방향키               pane 전환
-  Ctrl+B → D                    세션 분리
-  Ctrl+B → Z                    pane 전체화면"
-```
-
-## 에이전트 매핑
-
-| 분류 결과 | CLI | teammate 역할 | 실행 방법 |
-|----------|-----|--------------|----------|
-| codex | codex | Codex CLI 래퍼 | `tfx-route.sh {role} '{task}' auto` via Bash |
-| gemini | gemini | Gemini CLI 래퍼 | `tfx-route.sh {role} '{task}' auto` via Bash |
-| claude | claude | 직접 실행 | Glob/Grep/Read/Bash 직접 사용 |
-
-> **핵심 아이디어:** Claude teammate = Codex/Gemini 실행 래퍼
-> - Native Teams 인프라 (in-process, Task List, Mailbox) 활용
-> - 실제 작업은 Codex/Gemini가 수행 (비용 최소화)
-> - teammate의 Claude 토큰은 "실행+보고" 래퍼 역할에만 소비
-
-## 전제 조건
-
-- **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
-- **codex/gemini CLI** — 해당 에이전트 사용 시
-- **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
-
-## 에러 처리
-
-| 에러 | 처리 |
-|------|------|
-| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
-| tfx-route.sh 없음 | `tfx setup` 실행 안내 |
-| CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
-| Codex 분류 실패 | Opus 직접 분류+분해 |
-| teammate 실행 에러 | TaskUpdate(status: failed) + SendMessage로 리드에게 보고 |
-| teammate shutdown 거부 | 재시도 1회, 이후 사용자에게 보고 |
-
-## 관련
-
-| 항목 | 설명 |
-|------|------|
-| `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
-| `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
-| `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
-| `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |
+"tmux 세션이 생성되었습니다.
+  tmux attach -t {sessionId}     세션 연결
+  Ctrl+B → 방향키               pane 전환
+  Ctrl+B → D                    세션 분리
+  Ctrl+B → Z                    pane 전체화면"
+```
+
+## 에이전트 매핑
+
+| 분류 결과 | CLI | 역할 | 실행 방법 |
+|----------|-----|------|----------|
+| codex | codex | Lead 직접 라우팅 | `TFX_TEAM_* bash ~/.claude/scripts/tfx-route.sh {role} "{task}" {mcp_profile}` |
+| gemini | gemini | Lead 직접 라우팅 | `TFX_TEAM_* bash ~/.claude/scripts/tfx-route.sh {role} "{task}" {mcp_profile}` |
+| claude | claude | Claude 직접 실행 | `Agent(subagent_type={role})`로 직접 수행 |
+
+> **핵심 아이디어:** Codex/Gemini 작업은 `tfx-route.sh`가 팀 상태 동기화까지 직접 수행한다.
+> 리드는 오케스트레이션에 집중하고, Claude 토큰은 래퍼 오버헤드 없이 필요한 직접 실행(`claude` 타입)에만 사용한다.
+
+## 전제 조건
+
+- **CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1** — settings.json env에 설정 (`tfx setup`이 자동 설정)
+- **codex/gemini CLI** — 해당 에이전트 사용 시
+- **tfx setup** — tfx-route.sh 동기화 + AGENT_TEAMS 자동 설정 (사전 실행 권장)
+- **Hub bridge 활성 상태** — 기본 `http://127.0.0.1:27888` (`/bridge/team/*`, `/bridge/result` 사용)
+
+## 에러 처리
+
+| 에러 | 처리 |
+|------|------|
+| TeamCreate 실패 / Agent Teams 비활성 | `--tmux` 폴백 (Phase 3-tmux로 전환) |
+| tfx-route.sh 없음 | `tfx setup` 실행 안내 |
+| CLI 미설치 (codex/gemini) | 해당 서브태스크를 claude 워커로 대체 |
+| Codex 분류 실패 | Opus 직접 분류+분해 |
+| Bash 실행 실패 (Lead) | task를 `failed`로 마킹 후 Claude fallback 재시도 |
+| `team_task_list` 조회 실패 | `/bridge/result`/stdout로 임시 관찰 후 bridge 복구 뒤 상태 재검증 |
+| claude fallback 실패 | 실패 task 목록/원인 요약 후 사용자 승인 대기 |
+
+## 관련
+
+| 항목 | 설명 |
+|------|------|
+| `scripts/tfx-route.sh` | 팀 통합 라우터 (`TFX_TEAM_*`, task claim/complete, send-message, `/bridge/result`) |
+| `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿, 팀 설정 빌더) |
+| `hub/team/cli.mjs` | tmux 팀 CLI (`--tmux` 레거시 모드) |
+| `tfx-auto` | one-shot 실행 오케스트레이터 (병행 유지) |
+| `tfx-hub` | MCP 메시지 버스 관리 (tmux 모드용) |