triflux 10.2.1 → 10.3.0

package/skills/tfx-setup/SKILL.md

@@ -130,6 +130,118 @@ Bash("triflux setup")
       description: "나중에 /tfx-profile --gemini로 관리"
   ```
 
+#### 단계 3.6: Codex MCP Gateway 싱글톤 전환
+
+Codex CLI가 매 호출마다 MCP 서버를 stdio로 spawn하면 좀비 Node.js 프로세스가 생긴다.
+gateway SSE 싱글톤을 사용하도록 config.toml을 전환한다.
+
+```bash
+node scripts/codex-mcp-gateway-sync.mjs --status
+```
+
+- 전부 `sse` → ✅ 이미 전환됨
+- `stdio` 또는 `missing` 있으면 → AskUserQuestion:
+  ```
+  question: "Codex MCP 서버를 gateway 싱글톤(SSE)으로 전환하시겠습니까? 매 호출마다 MCP를 새로 spawn하는 대신, 영속 gateway 데몬을 공유합니다. (좀비 Node.js 방지)"
+  header: "MCP Gateway"
+  options:
+    - label: "전환 (Recommended)"
+      description: "stdio → SSE URL 전환. 좀비 프로세스 방지"
+    - label: "건너뛰기"
+      description: "현재 stdio 방식 유지"
+  ```
+  "전환" 선택 시:
+  1. gateway 데몬이 안 떠 있으면 먼저 기동: `node scripts/mcp-gateway-start.mjs`
+  2. config.toml 전환: `node scripts/codex-mcp-gateway-sync.mjs --enable`
+  3. 결과 확인: `node scripts/codex-mcp-gateway-sync.mjs --status`
+
+#### 단계 3.7: Codex config.toml 충돌 감지
+
+`~/.codex/config.toml`을 Read 도구로 읽어 `approval_mode`와 `sandbox` 설정을 확인한다.
+
+**충돌 감지 규칙:**
+- `approval_mode = "full-auto"` 가 config.toml에 있으면 → CLI에서 `--full-auto` 플래그 중복 사용 금지
+- `sandbox = "elevated"` 가 config.toml에 있으면 → CLI에서 sandbox 플래그 중복 사용 금지
+- 프로파일별 설정과 기본 설정이 충돌하면 → 경고 표시
+
+결과 표시:
+```
+## Codex config.toml 분석
+
+| 설정 | 값 | CLI 주의사항 |
+|------|-----|-------------|
+| approval_mode | full-auto | --full-auto 플래그 생략 필수 |
+| sandbox | elevated | sandbox 플래그 생략 필수 |
+| model | codex-mini-latest | 프로파일별 오버라이드 가능 |
+```
+
+충돌 발견 시 AskUserQuestion:
+```
+question: "config.toml에 approval_mode=full-auto가 설정되어 있습니다. triflux의 headless 실행에서 CLI 플래그 중복을 방지하려면 이 설정을 유지하는 것이 좋습니다. 현재 설정을 유지할까요?"
+header: "Codex Config"
+options:
+  - label: "유지 (Recommended)"
+    description: "config.toml 기본값 사용, CLI 플래그 자동 생략"
+  - label: "수정"
+    description: "config.toml을 편집하여 직접 조정"
+```
+
+**CLAUDE.md 주입 (필수):** 감지된 config.toml 설정을 프로젝트 CLAUDE.md의 `<codex-config>` 섹션에 반영한다.
+이렇게 해야 훅(headless-guard, safety-guard)이 명령을 차단했을 때, Claude가 차단 메시지를 읽고 "왜 차단됐는지" + "어떻게 수정해야 하는지"를 CLAUDE.md에서 찾아서 올바르게 재시도할 수 있다.
+
+주입 예시 (Edit 도구로 `<codex-config>` 섹션 업데이트):
+```markdown
+<codex-config>
+## Codex config.toml
+
+config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
+
+| config.toml에 있으면 | CLI에서 생략 |
+|---------------------|-------------|
+| `approval_mode = "full-auto"` | `--full-auto` |
+| `sandbox = "elevated"` | `--full-auto` |
+
+안전 패턴: config.toml에 기본값을 두고, CLI에서는 `--profile` 선택만 한다.
+</codex-config>
+```
+
+차단 → 수정 흐름:
+1. headless-guard가 `codex exec --full-auto` 차단
+2. 차단 메시지: "config.toml에 approval_mode=full-auto 있으므로 --full-auto 중복"
+3. Claude가 CLAUDE.md `<codex-config>` 읽음 → `--full-auto` 제거 후 재실행
+4. 동일 실수 반복 방지
+
+#### 단계 3.8: 원격 기기 프로빙 (Swarm Multi-Machine)
+
+`references/hosts.json` 또는 `~/.triflux/hosts.json` 존재 여부 확인.
+
+- 파일 없음 → AskUserQuestion:
+  ```
+  question: "원격 기기에서 스웜을 실행할 계획이 있나요? (tfx-swarm의 다중 기기 기능)"
+  header: "Remote"
+  options:
+    - label: "네, 원격 설정"
+      description: "SSH 호스트를 감지하고 연결 테스트합니다"
+    - label: "나중에"
+      description: "로컬만 사용. 나중에 /tfx-remote-setup으로 설정"
+  ```
+  "네" 선택 시 → `/tfx-remote-setup` 스킬 호출하여 호스트 위저드 실행
+
+- 파일 있음 → 등록된 호스트 각각에 대해 SSH 연결 + Claude 설치 프로브:
+  ```bash
+  ssh -o ConnectTimeout=5 <host> echo ok 2>/dev/null && echo "REACHABLE" || echo "UNREACHABLE"
+  ```
+  결과 표시:
+  ```
+  ## 원격 기기 상태
+
+  | 호스트 | SSH | Claude | 스웜 사용 |
+  |--------|-----|--------|----------|
+  | ryzen5-7600 | ✅ | ✅ v1.0.30 | 가능 |
+  | m2 | ✅ | ⚠ 미설치 | 불가 (Claude 설치 필요) |
+  | ultra4 | ❌ 연결 실패 | — | 불가 |
+  ```
+
 #### 단계 4: CLI 진단
 
 `triflux doctor --json`에는 psmux 설치 여부뿐 아니라 **버전/capability preflight**도 포함된다.
@@ -354,14 +466,26 @@ options:
 | 파일 동기화 | ✅ |
 | HUD 설정 | ✅ statusLine 등록됨 |
 | Codex 프로파일 | ✅ 3개 확인 |
+| Codex config.toml | ✅ approval_mode=full-auto (CLI 플래그 자동 생략) |
 | Codex CLI | ✅ |
 | Gemini CLI | ⚠ 미설치 (선택) |
+| 원격 기기 | ✅ 2대 사용 가능 (ryzen5-7600, m2) / ❌ 1대 연결 실패 |
 | MCP 인벤토리 | ✅ N개 서버 |
 | 검색 MCP | ✅ Exa, Tavily / ⏭ Brave (키 없음) |
 
+### 스웜 기능 수준
+
+| 기능 | 상태 | 필요 조건 |
+|------|------|----------|
+| 로컬 단일 모델 | ✅ | Codex CLI |
+| 로컬 다중 모델 | ✅ | Codex CLI + Gemini CLI |
+| 다중 기기 스웜 | ✅ 2대 | SSH 호스트 + Claude 설치 |
+| 전체 (다중 기기 x 다중 모델) | ✅ | 위 전부 |
+
 ### 다음 단계
 - Codex 미설치 시: `npm install -g @openai/codex`
 - Gemini 미설치 시: `npm install -g @google/gemini-cli`
+- 원격 호스트 추가: `/tfx-remote-setup`
 - 검색 MCP 추가/변경: `/tfx-setup` → 단계별 선택 → 검색 MCP
 - 세션 재시작하면 HUD + 검색 MCP가 활성화됩니다
 ```

package/skills/tfx-swarm/SKILL.md

@@ -1,18 +1,31 @@
-# tfx-swarm — 통합 스웜 오케스트레이션
+# tfx-swarm — 다중 기기 x 다중 모델 스웜 오케스트레이션
 
-> **Canonical swarm entrypoint.** tfx-codex-swarm + tfx-remote-spawn을 일반화 통합.
-> PRD → swarm-planner → swarm-hypervisor 파이프라인을 단일 스킬 호출�� 실행한다.
+> **Multi-Machine x Multi-Model Swarm.** PRD 하나로 로컬과 원격 머신에서
+> Claude + Codex + Gemini를 병렬 실행하고, file-lease로 충돌을 방지하며,
+> 결과를 자동 통합한다. triflux의 킬러 스킬.
 
 ## 트리거
 
 - `swarm`, `스웜`, `병렬 실행`, `다중 워커`, `PRD 실행`, `swarm launch`
-- `codex-swarm` (backward compat → 이 스킬로 라우팅)
+- `codex-swarm` (backward compat -> 이 스킬로 라우팅)
+
+## 핵심 기능
+
+| 기능 | 설명 |
+|------|------|
+| **다중 모델** | shard별 `agent: codex\|gemini\|claude` 지정. 작업 특성에 맞는 모델 배치 |
+| **다중 기기** | shard별 `host: <ssh-host>` 지정. 로컬/원격 혼합 실행 |
+| **File Lease** | shard별 파일 소유권. 동일 파일 동시 수정 방지 |
+| **Redundant Execution** | critical shard는 다른 모델로 이중 실행 후 reconcile |
+| **자동 통합** | 의존 순서대로 merge. 원격 shard는 SSH 경유 fetch |
+| **장애 폴백** | rate limit -> 다른 모델로 자동 전환 (codex<->gemini<->claude) |
 
 ## 전제조건
 
-- psmux ≥ 3.3.0
+- psmux >= 3.3.0
 - Hub 실행 중 (`curl -sf http://127.0.0.1:27888/status`)
-- Codex CLI (`codex --version`)
+- Codex CLI 또는 Gemini CLI (사용할 agent에 따라)
+- 원격 shard 사용 시: SSH 키 인증 + 원격 머신에 Claude Code 설치
 - 프로젝트에 `docs/prd/` 디렉토리 존재
 
 ## 실행 흐름
@@ -25,72 +38,133 @@ find docs/prd -name '*.md' -not -name '_template.md' -not -path '*/archived/*' |
 
 AskUserQuestion으로 실행할 PRD 선택. 복수 선택 시 각각 독립 shard.
 
-### Step 2: 계획 생성
+### Step 2: 원격/모델 구성 확인
+
+PRD 파싱 후, shard에 `host:` 필드가 있으면 AskUserQuestion으로 원격 실행 여부를 확인한다.
+
+AskUserQuestion:
+
+> PRD에 원격 호스트가 지정된 shard가 있습니다:
+> - `{shard_name}` -> `{host}` ({agent})
+>
+> 원격 실행을 어떻게 할까요?
+
+Options:
+- A) 원격 포함 실행 (PRD 그대로) — 로컬+원격 혼합
+- B) 전부 로컬에서 실행 — host 필드 무시
+- C) 원격만 실행 — 로컬 shard 건너뛰기
+
+PRD에 다중 agent가 지정된 경우에도 AskUserQuestion:
+
+> PRD에 여러 모델이 지정되어 있습니다:
+> - codex: {N}개 shard
+> - gemini: {N}개 shard
+> - claude: {N}개 shard
+>
+> 모델 배치를 어떻게 할까요?
+
+Options:
+- A) PRD 그대로 — shard별 지정 모델 사용 (권장)
+- B) 전부 Codex로 — 단일 모델
+- C) 전부 Gemini로 — 단일 모델
+
+### Step 3: 계획 생성
 
 ```javascript
-import { plan } from '../../hub/team/swarm-planner.mjs';
+import { planSwarm } from '../../hub/team/swarm-planner.mjs';
 
-const swarmPlan = plan({
-  prdText: selectedPrdContent,
-  baseBranch: 'main',
-  provider: 'codex', // 기본값, AskUserQuestion으로 변경 가능
-});
+const swarmPlan = planSwarm(selectedPrdPath);
 ```
 
 계획을 사용자에게 보여주고 승인 요청:
 - shard 수, 파일 배분, lease 맵, merge 순서
+- 원격 shard 표시 (host 정보)
+- 모델 배분 표시 (agent 정보)
 - critical shard 표시 (redundant execution 대상)
 
-### Step 3: Hypervisor 실행
+### Step 4: Hypervisor 실행
 
 ```javascript
 import { createSwarmHypervisor } from '../../hub/team/swarm-hypervisor.mjs';
 
 const hyper = createSwarmHypervisor({
-  rootDir: process.cwd(),
-  maxConcurrency: 4,
+  workdir: process.cwd(),
+  logsDir: join(process.cwd(), '.triflux', 'swarm-logs'),
+  maxRestarts: 2,
 });
 
-const run = await hyper.launch(swarmPlan);
+const run = hyper.launch(swarmPlan);
 ```
 
 실행 중 상태 모니터링:
-- `hyper.on('shardLaunched', ...)` → 진행 표시
-- `hyper.on('shardDone', ...)` → 완료/실패 표시
-- `hyper.on('zombieDetected', ...)` → 경고
+- `hyper.on('shardLaunched', ...)` -> 진행 표시
+- `hyper.on('shardCompleted', ...)` -> 완료/실패 표시
+- `hyper.on('warning', ...)` -> 경고 (파일 충돌 등)
 
-### Step 4: 결과 검증 + 통합
+원격 shard 실행 시:
+1. `probeRemoteEnv(host)` -> 원격 환경 감지 (OS, shell, Claude 경로)
+2. conductor가 `remote: true` 설정으로 SSH 경유 세션 실행
+3. 완료 후 `fetchRemoteShard()`로 원격 브랜치를 로컬로 fetch
 
-```javascript
-// 각 shard 결과 검증
-for (const shard of swarmPlan.shards) {
-  const v = hyper.validateResult(run.runId, shard.id);
-  if (!v.accepted) console.log(`${shard.id}: ${v.reason}`);
-}
+### Step 5: 결과 검증 + 통합
 
-// merge order에 따라 integration branch로 통합
-const integration = await hyper.integrateResults(run.runId);
+```javascript
+const status = hyper.getStatus();
+// status.completedShards, status.failedShards, status.workers
 ```
 
 통합 결과를 사용자에게 보고:
-- 성공: merged shard 목록
+- 성공: merged shard 목록 (로컬/원격 구분 표시)
 - 실패: 충돌/실패 shard 목록 + 수동 해결 안내
 
-### Step 5: 정리
+### Step 6: 정리
 
 ```javascript
-await hyper.cleanup(run.runId, { keepFailedWorktrees: true });
+await hyper.shutdown('completed');
 ```
 
-### Step 6: pack.mjs 동기화
-
-새 모듈이 hub/team/에 추가되었으므로:
+## PRD 예제: 다중 기기 x 다중 모델
 
-```bash
-npm run pack
+```markdown
+## Shard: auth-refactor
+- agent: codex
+- files: src/auth.mjs, src/middleware/jwt.mjs
+- prompt: JWT 인증 미들웨어 리팩터링
+
+## Shard: ui-dashboard
+- agent: gemini
+- files: src/ui/dashboard.mjs, src/ui/charts.mjs
+- prompt: 대시보드 UI 개선
+
+## Shard: security-audit
+- agent: claude
+- host: ryzen5-7600
+- files: src/security.mjs
+- critical: true
+- prompt: 보안 취약점 감사
+
+## Shard: perf-optimization
+- agent: codex
+- host: m2
+- files: src/engine/optimizer.mjs
+- depends: auth-refactor
+- prompt: 성능 최적화 (auth 리팩터 완료 후)
 ```
 
-REMOTE_INDEX에 새 export가 필요하면 scripts/pack.mjs 수정 후 재실행.
+위 PRD 하나로: Codex(로컬) + Gemini(로컬) + Claude(ryzen5-7600) + Codex(m2) 4개 워커가 병렬 실행된다.
+security-audit는 `critical: true`이므로 다른 모델로 이중 실행 후 reconcile.
+
+## PRD Shard 필드 레퍼런스
+
+| 필드 | 필수 | 기본값 | 설명 |
+|------|------|--------|------|
+| `agent` | - | `codex` | 실행 모델: `codex`, `gemini`, `claude` |
+| `host` | - | (로컬) | SSH 호스트. 미지정 시 로컬 실행 |
+| `files` | O | - | shard가 수정할 파일 목록 (file-lease 대상) |
+| `depends` | - | - | 의존하는 shard 이름. 해당 shard 완료 후 실행 |
+| `critical` | - | `false` | `true`면 다른 모델로 이중 실행 + reconcile |
+| `mcp` | - | - | 필요한 MCP 서버 목록 |
+| `prompt` | O | - | shard 실행 프롬프트. `\|`로 멀티라인 |
 
 ## 제약
 
@@ -115,40 +189,18 @@ if (shouldRunRedundant(shard)) {
 
 HITL fallback 시 AskUserQuestion으로 사용자에게 선택 요청.
 
-## Remote Shard 지원 (Lake 3)
-
-PRD에 `- host: <ssh-host>` 필드를 추가하면 해당 shard가 원격 머신에서 실행된다.
-
-```markdown
-## Shard: heavy-analysis
-- agent: codex
-- host: ultra4
-- files: src/analysis/engine.mjs
-- prompt: 대규모 분석 엔진 구��
-```
-
-동작 원리:
-1. swarm-planner가 `host` 필드를 파싱하여 shard에 포함
-2. swarm-hypervisor의 `launchShard()`가 `probeRemoteEnv(host)`로 원격 환경 감지
-3. conductor의 `spawnSession({ remote: true, host, ... })`로 원격 세션 실행
-4. worktree-lifecycle이 `remoteGit()`으로 SSH 경유 worktree 생성
-
-전제조건:
-- SSH 키 인증 설정 완료 (`ssh ultra4` 패스워드 없이 접속 가능)
-- 원격 머신에 Claude Code 설치됨 (`probeRemoteEnv`가 자동 확인)
-- hosts.json 등록 권장 (`/tfx-remote-setup`으로 설정)
-
-host 미지정 shard는 기존대로 로컬 실행. 로컬/원격 혼합 가능.
-
-## 기존 tfx-codex-swarm과의 관계
+## 장애 처리
 
-- tfx-codex-swarm은 이 스킬의 **backward compat alias**
-- 기존 워크플로우(PRD 스캔 → worktree 생성 → Codex 실행)는 동일
-- 차이: 프로그래밍 API 기반, file lease, redundant exec, 자동 merge
+| 장애 | 분류 | 대응 |
+|------|------|------|
+| 워커 크래시 | F1 | conductor auto-restart (최대 2회) |
+| Rate limit | F2 | 다른 모델로 자동 전환 (codex->gemini->claude) |
+| Stall | F3 | health probe 감지 -> kill -> restart |
+| File lease 위반 | F4 | 워커 변경 revert, shard 실패 처리 |
+| Merge 충돌 | F5 | 충돌 해결 재시도 |
 
-## tfx-remote-spawn과의 관계
+## 기존 스킬과의 관계
 
-- tfx-remote-spawn의 핵심 함수가 `hub/team/remote-session.mjs`로 모듈화됨
-- swarm-hypervisor가 이 모듈을 사용하여 원격 세션을 관리
-- tfx-remote-spawn 스킬은 **단독 원격 세션 관리**용으로 유지 (list, attach, send)
-- swarm은 **다중 shard 병렬 관리** (로컬+원격 혼합)
+- **tfx-codex-swarm**: deprecated. 이 스킬로 통합됨 (backward compat alias)
+- **tfx-remote-spawn**: 단독 원격 세션 관리(list, attach, send)용으로 유지. swarm은 다중 shard 병렬 관리
+- **tfx-multi**: Claude Native Teams 기반 로컬 오케스트레이션. swarm은 PRD 기반 worktree 분할