triflux 9.2.4 → 9.4.0

package/scripts/tfx-route.sh

@@ -617,12 +617,23 @@ codex_gte() {
 _GEMINI_PROFILE_CACHE=""
 resolve_gemini_profile() {
   local profile="$1"
+  if [[ "$profile" == gemini-* ]]; then
+    echo "$profile"
+    return
+  fi
   if [[ -z "$_GEMINI_PROFILE_CACHE" && -f "$GEMINI_PROFILES_PATH" ]]; then
     _GEMINI_PROFILE_CACHE=$(cat "$GEMINI_PROFILES_PATH" 2>/dev/null || echo "{}")
   fi
+  local settings_path="${HOME}/.gemini/settings.json"
+  local settings_cache="{}"
+  if [[ -f "$settings_path" ]]; then
+    settings_cache=$(cat "$settings_path" 2>/dev/null || echo "{}")
+  fi
   local result
   result=$("$NODE_BIN" -e "
     const name = process.argv[1];
+    const primaryRaw = process.argv[2] || '{}';
+    const settingsRaw = process.argv[3] || '{}';
     const defaults = {
       pro31: 'gemini-3.1-pro-preview',
       flash3: 'gemini-3-flash-preview',
@@ -630,13 +641,74 @@ resolve_gemini_profile() {
       flash25: 'gemini-2.5-flash',
       lite25: 'gemini-2.5-flash-lite'
     };
-    try {
-      const cfg = JSON.parse(process.argv[2] || '{}');
-      const p = cfg.profiles?.[name];
-      if (p?.model) { process.stdout.write(p.model); return; }
-    } catch {}
-    process.stdout.write(defaults[name] || 'gemini-3.1-pro-preview');
-  " "$profile" "$_GEMINI_PROFILE_CACHE" 2>/dev/null)
+
+    if (typeof name === 'string' && name.startsWith('gemini-')) {
+      process.stdout.write(name);
+      process.exit(0);
+    }
+
+    const parseJson = (raw) => {
+      try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+      } catch {
+        return {};
+      }
+    };
+
+    const getModelValue = (entry) => {
+      if (!entry) return '';
+      if (typeof entry === 'string') return entry;
+      if (typeof entry !== 'object') return '';
+      if (typeof entry.model === 'string') return entry.model;
+      if (typeof entry.name === 'string' && entry.name.startsWith('gemini-')) return entry.name;
+      if (entry.model && typeof entry.model.name === 'string') return entry.model.name;
+      return '';
+    };
+
+    const getProfileBuckets = (cfg) => {
+      const buckets = [];
+      if (cfg.profiles && typeof cfg.profiles === 'object') buckets.push(cfg.profiles);
+      if (cfg.model?.profiles && typeof cfg.model.profiles === 'object') buckets.push(cfg.model.profiles);
+      if (cfg.modelProfiles && typeof cfg.modelProfiles === 'object') buckets.push(cfg.modelProfiles);
+      if (cfg.models && typeof cfg.models === 'object') buckets.push(cfg.models);
+      return buckets;
+    };
+
+    const getDefaultModel = (cfg) => {
+      return (
+        (typeof cfg.defaultModel === 'string' && cfg.defaultModel) ||
+        (typeof cfg.default_profile === 'string' && cfg.default_profile) ||
+        (typeof cfg.defaultProfile === 'string' && cfg.defaultProfile) ||
+        (typeof cfg.model === 'string' && cfg.model) ||
+        (typeof cfg.model?.default === 'string' && cfg.model.default) ||
+        ''
+      );
+    };
+
+    const sources = [parseJson(primaryRaw), parseJson(settingsRaw)];
+    for (const cfg of sources) {
+      for (const bucket of getProfileBuckets(cfg)) {
+        const value = getModelValue(bucket[name]);
+        if (value) {
+          process.stdout.write(value);
+          process.exit(0);
+        }
+      }
+    }
+
+    if (name === 'default') {
+      for (const cfg of sources) {
+        const value = getDefaultModel(cfg);
+        if (value) {
+          process.stdout.write(value);
+          process.exit(0);
+        }
+      }
+    }
+
+    process.stdout.write(defaults[name] || defaults.pro31);
+  " "$profile" "$_GEMINI_PROFILE_CACHE" "$settings_cache" 2>/dev/null)
   echo "${result:-gemini-3.1-pro-preview}"
 }
 
@@ -853,6 +925,7 @@ CODEX_MCP_TRANSPORT_EXIT_CODE=70
 
 apply_cli_mode() {
   local codex_base="--dangerously-bypass-approvals-and-sandbox --skip-git-repo-check"
+  local gemini_tier=""
 
   case "$TFX_CLI_MODE" in
     codex)
@@ -894,7 +967,12 @@ apply_cli_mode() {
           *)
             CLI_ARGS="-m $(resolve_gemini_profile flash3) -y --prompt"; CLI_EFFORT="flash3" ;;
         esac
-        echo "[tfx-route] TFX_CLI_MODE=gemini: $AGENT_TYPE → gemini($CLI_EFFORT)로 리매핑" >&2
+        case "$CLI_EFFORT" in
+          pro*) gemini_tier="pro" ;;
+          flash*|lite*) gemini_tier="flash" ;;
+          *) gemini_tier="$CLI_EFFORT" ;;
+        esac
+        echo "[tfx-route] TFX_CLI_MODE=gemini: $AGENT_TYPE → gemini($gemini_tier)로 리매핑" >&2
       fi ;;
     auto)
       if [[ "$CLI_TYPE" == "codex" ]] && ! command -v "$CODEX_BIN" &>/dev/null; then
@@ -1226,7 +1304,7 @@ _gemini_run_once() {
   else
     "$TIMEOUT_BIN" "$TIMEOUT_SEC" "$CLI_CMD" "${g_args[@]}" "$prompt" >"$STDOUT_LOG" 2>"$STDERR_LOG" &
   fi
-  echo "$!"
+  GEMINI_RUN_PID=$!
 }
 
 gemini_with_retry() {
@@ -1243,7 +1321,12 @@ gemini_with_retry() {
   while (( attempt < max_retries )); do
     exit_code_local=0
     local pid
-    pid=$(_gemini_run_once "$use_tee_flag" "$prompt" "${g_args[@]}")
+    _gemini_run_once "$use_tee_flag" "$prompt" "${g_args[@]}"
+    pid="${GEMINI_RUN_PID:-}"
+    if [[ -z "$pid" ]]; then
+      echo "[tfx-route] Gemini: worker pid 획득 실패" >&2
+      return 1
+    fi
 
     local health_ok=true
     local intervals=(1 2 3 5 8)

package/skills/tfx-auto/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tfx-auto
-description: 통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+description: >
+  통합 CLI 오케스트레이터. 커맨드 숏컷(단일) + 자동 분류/분해(병렬) + 수동 병렬. tfx-route.sh 기반.
+  '코드 짜줘', '구현해줘', '만들어줘', '수정해줘', '고쳐줘', 'implement', 'build', 'fix' 같은
+  구현/수정 요청에 사용. CLI 라우팅이 필요한 모든 작업에 적극 활용.
 triggers:
   - tfx-auto
   - implement

package/skills/tfx-auto-codex/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tfx-auto-codex
-description: Codex 리드형 tfx-auto. Claude 네이티브 역할을 Codex로 치환하고 Gemini 사용은 유지합니다.
+description: >
+  Codex 리드형 tfx-auto. Claude 네이티브 역할을 Codex로 치환하고 Gemini 사용은 유지합니다.
+  '코덱스 리드', '코덱스가 주도', 'codex lead' 같은 요청에 사용.
 triggers:
   - tfx-auto-codex
 argument-hint: "\"작업 설명\" | N:agent_type \"작업 설명\""

package/skills/tfx-autopilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-autopilot
-description: "간단한 작업을 자율적으로 구현해야 할 때 사용한다. 'autopilot', '자동으로', '알아서 해', '그냥 해줘' 같은 요청에 반드시 사용. 명확한 단일 작업을 빠르게 자동 구현+검증할 때 적극 활용."
+description: "단일 파일/모듈 수준의 간단한 작업을 자율 구현할 때 사용한다. 구현+검증까지 5분 이내 완료 가능한 작업, '간단히', '빠르게', '하나만', '자동으로', '알아서 해', '그냥 해줘' 같은 수식어가 있을 때 사용. 복잡한 멀티파일 작업은 tfx-fullcycle을 사용하세요."
 triggers:
   - autopilot
   - 자동

package/skills/tfx-autoresearch/SKILL.md

@@ -3,6 +3,8 @@ name: tfx-autoresearch
 description: >
   자율 웹 리서치 → 실행 가능 계획 도출.
   주제를 받아 웹 검색 → 정보 수집 → 분석 → 구조화된 리서치 보고서 생성.
+  '알아봐', '조사해', '리서치해줘', '검색하고 정리해', 'research and plan' 같은 요청에 반드시 사용.
+  웹 검색 후 실행 가능한 계획까지 도출이 필요할 때 적극 활용.
 triggers:
   - autoresearch
   - 자율 리서치

package/skills/tfx-codex/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tfx-codex
-description: Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+description: >
+  Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+  '코덱스로 해줘', '코덱스한테 시켜', 'codex로', 'Codex 전용' 같은 요청에 반드시 사용.
 triggers:
   - tfx-codex
 argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""

package/skills/tfx-consensus/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: tfx-consensus
-description: 3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
-triggers: []
-argument-hint: "(내부 전용 — Deep 스킬이 자동 호출)"
+description: >
+  3자 합의 엔진 — 모든 Deep 스킬의 핵심 인프라. Claude/Codex/Gemini 독립 분석 결과를 교차검증하여 편향 없는 합의를 도출한다.
+  독립 실행도 가능: '합의로 분석해', '3자 합의', 'consensus' 같은 요청 시 직접 호출 가능.
+triggers: [consensus, 합의]
+argument-hint: "<분석 주제 또는 컨텍스트> (Deep 스킬 내부 자동 호출 또는 직접 사용 가능)"
 ---
 
 # tfx-consensus — Tri-CLI Consensus Engine

package/skills/tfx-fullcycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-fullcycle
-description: "복잡한 기능을 처음부터 끝까지 자율 개발해야 할 때 사용한다. 'deep autopilot', '풀 오토', '처음부터 끝까지', 'full auto', '전체 파이프라인으로' 같은 요청에 사용. 설계→계획→구현→QA→검증 전체 사이클이 필요한 대규모 기능에 적극 활용."
+description: "여러 파일/모듈에 걸친 복잡한 기능을 처음부터 끝까지 자율 개발할 때 사용한다. 설계→계획→구현→QA→검증 전체 파이프라인이 필요한 작업, '처음부터 끝까지', '전체', '완전히', '풀 오토', 'full auto', '전체 파이프라인으로' 같은 수식어가 있을 때 사용. 단순 단일 작업은 tfx-autopilot이 더 빠릅니다."
 triggers:
   - deep autopilot
   - 풀 오토

package/skills/tfx-gemini/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tfx-gemini
-description: Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
+description: >
+  Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
+  '제미나이로 해줘', '제미나이한테 시켜', 'gemini로', 'Gemini 전용' 같은 요청에 반드시 사용.
 triggers:
   - tfx-gemini
 argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""

package/skills/tfx-hooks/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: tfx-hooks
+description: >
+  Claude Code 훅 우선순위 관리자. AskUserQuestion 기반 인터랙티브 UI로
+  훅 스캔, 우선순위 조정, 오케스트레이터 적용/복원, 개별 훅 토글을 수행합니다.
+  사용자가 훅, hooks, 훅 관리, hook priority, 훅 우선순위, 오케스트레이터,
+  orchestrator, 훅 설정, hook 설정, 훅 순서, hook order를 언급할 때마다
+  반드시 이 스킬을 사용하세요.
+  Use when: hooks, 훅, hook priority, 훅 관리, orchestrator, 오케스트레이터, 훅 설정, 훅 순서
+triggers:
+  - tfx-hooks
+argument-hint: "[scan|apply|restore]"
+---
+
+# tfx-hooks — 훅 우선순위 관리자
+
+> Claude Code 훅의 실행 순서를 관리합니다. triflux 훅이 항상 최우선 실행되도록 보장합니다.
+
+## 핵심 개념
+
+Claude Code는 같은 이벤트에 매칭된 훅을 **병렬 실행**합니다. 순서 보장이 불가능합니다.
+triflux의 **hook-orchestrator**는 이벤트당 하나의 진입점을 두고, 내부에서 **우선순위대로 순차 실행**합니다.
+
+```
+settings.json → hook-orchestrator.mjs (단일 진입점)
+                    ↓ hook-registry.json 읽기
+                    ↓ priority 순 정렬
+                    1. triflux 훅 (priority=0)
+                    2. OMC 훅 (priority=50)
+                    3. 외부 훅 (priority=100)
+```
+
+## 워크플로우
+
+### Step 1: 현재 상태 확인
+
+```bash
+Bash("node hooks/hook-manager.mjs status")
+```
+
+결과 JSON에서 `orchestrated` 필드로 적용 여부를 판단한다.
+
+### Step 2: 메인 메뉴 (AskUserQuestion)
+
+```
+question: "훅 관리 — 어떤 작업을 수행하시겠습니까?"
+header: "Hook Manager"
+options:
+  - label: "현재 상태 보기"
+    description: "settings.json 훅 스캔 + 오케스트레이터 적용 상태"
+  - label: "오케스트레이터 적용"
+    description: "모든 훅을 통합 — triflux 최우선 실행 보장"
+  - label: "변경점 미리보기 (diff)"
+    description: "적용 시 어떻게 바뀌는지 확인"
+  - label: "원래대로 복원"
+    description: "오케스트레이터 제거, 원래 settings.json 훅으로 복원"
+  - label: "개별 훅 관리"
+    description: "특정 훅 활성/비활성, 우선순위 변경"
+```
+
+### Step 3: 선택에 따른 분기
+
+#### "현재 상태 보기"
+
+```bash
+Bash("node hooks/hook-manager.mjs scan")
+```
+
+결과 JSON을 파싱하여 테이블로 표시:
+
+```markdown
+## 현재 훅 상태
+
+| 이벤트 | 훅 수 | 소스 |
+|--------|-------|------|
+| SessionStart | 4 | triflux(3), session-vault(1) |
+| PreToolUse | 3 | triflux(1), omc(2) |
+| ...    | ...   | ... |
+
+오케스트레이터: ❌ 미적용 / ✅ 적용됨 (N개 이벤트)
+```
+
+#### "오케스트레이터 적용"
+
+먼저 diff를 보여준 후 확인:
+
+```bash
+Bash("node hooks/hook-manager.mjs diff")
+```
+
+결과를 표시한 뒤 AskUserQuestion:
+```
+question: "위 변경을 적용하시겠습니까?"
+header: "확인"
+options:
+  - label: "적용"
+    description: "settings.json 백업 후 오케스트레이터 적용"
+  - label: "취소"
+    description: "변경 없이 돌아가기"
+```
+
+"적용" 선택 시:
+```bash
+Bash("node hooks/hook-manager.mjs apply")
+```
+
+적용 결과 표시:
+```
+✅ 오케스트레이터 적용 완료
+   N개 이벤트 → 1개 오케스트레이터로 통합
+   실행 순서: triflux(0) → OMC(50) → external(100)
+   복원: /tfx-hooks → 원래대로 복원
+   또는: triflux hooks restore
+```
+
+#### "변경점 미리보기 (diff)"
+
+```bash
+Bash("node hooks/hook-manager.mjs diff")
+```
+
+결과를 테이블로 표시:
+```markdown
+| 이벤트 | 현재 | 적용 후 | 변경 |
+|--------|------|---------|------|
+| PreToolUse | 2개 개별 | 1개 오케스트레이터 (내부 4개) | 교체 |
+| PostToolUse | 없음 | 1개 오케스트레이터 (내부 1개) | 신규 |
+| ... | ... | ... | ... |
+```
+
+#### "원래대로 복원"
+
+```bash
+Bash("node hooks/hook-manager.mjs restore")
+```
+
+결과에서 status를 확인:
+- `"restored"` → "✅ 원래 훅 설정이 복원되었습니다."
+- `"no_backup"` → "⚠️ 백업이 없습니다. 오케스트레이터를 적용한 적이 없습니다."
+
+#### "개별 훅 관리"
+
+레지스트리에서 전체 훅 목록을 읽어 표시:
+
+```bash
+Bash("node -e \"const r=JSON.parse(require('fs').readFileSync('hooks/hook-registry.json','utf8')); const all=[]; for(const [e,hs] of Object.entries(r.events)) hs.forEach(h=>all.push({event:e,...h})); console.log(JSON.stringify(all))\"")
+```
+
+결과를 테이블로 표시 후 AskUserQuestion:
+```
+question: "어떤 훅을 관리하시겠습니까?"
+header: "훅 선택"
+options:
+  (레지스트리의 각 훅을 옵션으로 나열)
+  - label: "tfx-safety-guard"
+    description: "[PreToolUse:Bash] 위험 명령 차단 — priority:0, 활성"
+  - label: "tfx-agent-route-guard"
+    description: "[PreToolUse:Agent] 에이전트 라우팅 — priority:0, 활성"
+  - label: "omc-headless-guard"
+    description: "[PreToolUse:Bash|Agent] headless 가드 — priority:50, 활성"
+  ...
+```
+
+훅 선택 후 AskUserQuestion:
+```
+question: "{hookId} — 어떤 조작을 하시겠습니까?"
+header: "훅 조작"
+options:
+  - label: "활성/비활성 토글"
+    description: "현재: 활성 → 비활성으로 전환"
+  - label: "우선순위 변경"
+    description: "현재: 0 — 숫자가 낮을수록 먼저 실행"
+  - label: "뒤로"
+    description: "훅 목록으로 돌아가기"
+```
+
+"활성/비활성 토글":
+```bash
+Bash("node hooks/hook-manager.mjs toggle {hookId}")
+```
+
+"우선순위 변경":
+AskUserQuestion으로 새 우선순위 입력:
+```
+question: "새 우선순위를 입력하세요 (0=최우선, 50=중간, 100=후순위)"
+header: "Priority"
+```
+```bash
+Bash("node hooks/hook-manager.mjs set-priority {hookId} {newPriority}")
+```
+
+변경 후 오케스트레이터가 적용된 상태라면 재적용 안내:
+```
+💡 레지스트리가 변경되었습니다. 오케스트레이터는 실시간으로 레지스트리를 읽으므로 재적용 불필요합니다.
+```
+
+## CLI 대응
+
+| 스킬 UI | CLI 명령 |
+|---------|---------|
+| 현재 상태 보기 | `triflux hooks scan` |
+| 오케스트레이터 적용 | `triflux hooks apply` |
+| 변경점 미리보기 | `triflux hooks diff` |
+| 원래대로 복원 | `triflux hooks restore` |
+| 상태 확인 | `triflux hooks status` |
+| 훅 토글 | `triflux hooks toggle <hookId>` |
+| 우선순위 변경 | `triflux hooks set-priority <hookId> <priority>` |
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| hook-registry.json 없음 | "레지스트리가 없습니다. triflux hooks 디렉토리를 확인하세요." |
+| settings.json 파싱 실패 | "settings.json이 손상되었습니다. 수동 확인이 필요합니다." |
+| 백업 없이 복원 시도 | "오케스트레이터를 적용한 적이 없어 복원할 수 없습니다." |
+| hook-manager.mjs 실행 실패 | "hook-manager를 실행할 수 없습니다. node hooks/hook-manager.mjs를 직접 실행해 보세요." |

package/skills/tfx-multi/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tfx-multi
-description: 멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+description: >
+  멀티-CLI 팀 모드. Claude Native Agent Teams + Codex/Gemini 멀티모델 오케스트레이션.
+  '멀티로', '팀 모드', '다중 CLI', '3개 다 동원', 'multi' 같은 요청에 반드시 사용.
+  Claude+Codex+Gemini 협업이 필요한 모든 상황에 적극 활용.
 triggers:
   - tfx-multi
 argument-hint: '"작업 설명" | --agents codex,gemini "작업" | --tmux "작업" | status | stop'

package/skills/tfx-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tfx-plan
-description: "구현 계획이 필요할 때 사용한다. '계획 세워줘', 'plan', '플랜', '어떻게 구현하지', '태스크 분해', '작업 순서' 같은 요청에 반드시 사용. 기능 구현 전 영향 범위 파악과 태스크 분해가 필요할 때 적극 활용."
+description: "구현 계획이 필요할 때 사용한다. '계획 세워줘', 'plan', '플랜', '어떻게 구현하지', '태스크 분해', '작업 순서' 같은 요청에 반드시 사용. 기능 구현 전 영향 범위 파악과 태스크 분해가 필요할 때 적극 활용. 작업 분해, 순서 정리, '어떤 순서로', '먼저 뭐 해야', 'breakdown', 'decompose', 'task list' 같은 요청에도 적극 활용. 단순 계획은 이 스킬, 3자 합의 계획은 tfx-deep-plan을 사용."
 triggers:
   - plan
   - 계획

package/skills/tfx-psmux-rules/SKILL.md

@@ -153,34 +153,121 @@ Get-Content 'C:\path\prompts\prompt.md' -Raw | codex
 
 ---
 
-## RULE 5: WT 패인 정리 (프리징 방지)
+## RULE 5: WT 세션 정리 — CRITICAL (프리징 치명 버그)
 
-WT 패인이 psmux 세션에 attach된 상태에서 `kill-session`하면 WT가 프리징된다.
+> **이 규칙을 위반하면 Windows Terminal이 완전히 프리징된다.**
+> 복구 방법은 작업 관리자에서 WindowsTerminal.exe 강제 종료뿐이다.
+> **모든 열린 탭/세션이 유실된다.** 절대 위반하지 마라.
 
-### MUST (3단계 정리)
+### 프리징 원인
+
+WT 패인이 `psmux attach-session`으로 세션에 연결된 상태에서
+`psmux kill-session`을 직접 호출하면 WT의 PTY 핸들이 dangling 상태가 되어
+**전체 WT 프로세스가 응답 불능**이 된다.
+
+### MUST — 3단계 정리 (순서 반드시 준수)
 
 ```bash
-# 1) graceful exit
-for s in $(psmux list-sessions -F '#{session_name}' 2>/dev/null | grep codex-swarm); do
+# 1) graceful exit — 각 세션 내 프로세스를 정상 종료
+for s in $(psmux list-sessions -F '#{session_name}' 2>/dev/null | grep "$PREFIX"); do
   psmux send-keys -t "$s" "exit" Enter 2>/dev/null || true
 done
 
-# 2) WT 패인 종료 대기
+# 2) WT 패인 분리 대기 — exit이 WT에 전파되는 시간 필요
 sleep 2
 
-# 3) 잔여 세션 강제 종료
-for s in $(psmux list-sessions -F '#{session_name}' 2>/dev/null | grep codex-swarm); do
+# 3) 잔여 세션 강제 종료 — exit이 먹히지 않은 경우만
+for s in $(psmux list-sessions -F '#{session_name}' 2>/dev/null | grep "$PREFIX"); do
   psmux kill-session -t "$s" 2>/dev/null || true
 done
 ```
 
-### MUST NOT
+### MUST NOT — 아래 패턴은 전부 프리징 유발
 
 ```bash
-# WRONG — WT 프리징 발생
-for s in $(psmux list-sessions -F '#{session_name}' 2>/dev/null | grep codex-swarm); do
-  psmux kill-session -t "$s"
-done
+# WRONG 1 — exit 없이 바로 kill
+psmux kill-session -t "$session"
+
+# WRONG 2 — sleep 없이 exit 직후 kill
+psmux send-keys -t "$s" "exit" Enter
+psmux kill-session -t "$s"   # ← WT가 아직 PTY를 잡고 있음
+
+# WRONG 3 — detach 직후 kill
+psmux send-keys -t "$s" "psmux detach" Enter
+psmux kill-session -t "$s"   # ← detach 완료 전에 kill → 프리징
+```
+
+### WT 패인 직접 닫기 (세션이 아닌 WT 쪽에서 정리)
+
+```bash
+# WT 패인을 닫는 것이 세션 kill보다 안전
+wt.exe -w 0 close-pane    # 현재 포커스된 패인 닫기
+```
+
+---
+
+## RULE 5-1: psmux 경로 탐색
+
+psmux는 환경마다 설치 위치가 다르다. `hub/team/psmux.mjs`의 `PSMUX_BIN`이
+자동 탐색하지만, 스크립트에서 직접 psmux를 호출할 때도 경로를 고려해야 한다.
+
+탐색 우선순위:
+1. `$PSMUX_BIN` 환경변수 (설정 시 최우선)
+2. PATH의 `psmux`
+3. `%LOCALAPPDATA%\psmux\psmux.exe` (Windows 기본)
+4. `%APPDATA%\npm\psmux.cmd` (npm global)
+5. `~\scoop\shims\psmux.exe` (Scoop)
+
+---
+
+## RULE 5-2: WT 명령 치트시트
+
+### 패인 분할
+
+```bash
+# 현재 창에서 수평 분할 (상/하)
+wt.exe -w 0 sp -H -p triflux --title "worker" psmux attach-session -t SESSION
+
+# 현재 창에서 수직 분할 (좌/우)
+wt.exe -w 0 sp -V -p triflux --title "worker" psmux attach-session -t SESSION
+
+# 2x2 그리드 (4 패인)
+wt.exe -w 0 \
+  sp -H -p triflux --title "w1" psmux attach-session -t S1 \; \
+  sp -V -p triflux --title "w2" psmux attach-session -t S2 \; \
+  move-focus up \; \
+  sp -V -p triflux --title "w3" psmux attach-session -t S3
+```
+
+### 포커스 이동
+
+```bash
+wt.exe -w 0 move-focus up|down|left|right
+```
+
+### 패인 닫기 (세션 kill보다 안전)
+
+```bash
+wt.exe -w 0 close-pane
+```
+
+### 필수 옵션
+
+| 옵션 | 의미 | 필수 여부 |
+|------|------|----------|
+| `-w 0` | 현재 WT 윈도우 | 필수 (없으면 새 창) |
+| `-p triflux` | triflux WT 프로파일 | 필수 (테마/셸 일관성) |
+| `--title "name"` | 패인 제목 | 권장 (식별용) |
+| `sp -H` / `sp -V` | 분할 방향 | 필수 |
+
+### 새 탭 금지
+
+```bash
+# WRONG — 새 탭 생성 (nt)
+wt.exe -w 0 nt -p triflux ...
+
+# RIGHT — split-pane (sp)
+wt.exe -w 0 sp -V -p triflux ...
 ```
 
 ---