triflux 10.3.4 → 10.7.0

package/skills/tfx-swarm/SKILL.md.tmpl

@@ -0,0 +1,218 @@
+---
+name: tfx-swarm
+description: "tfx-swarm — 다중 기기 x 다중 모델 스웜 오케스트레이션"
+triggers:
+  - swarm
+  - 스웜
+  - 병렬 실행
+  - codex-swarm
+---
+
+# {{SKILL_NAME}} — 다중 기기 x 다중 모델 스웜 오케스트레이션
+
+{{> base}}
+
+> **Multi-Machine x Multi-Model Swarm.** PRD 하나로 로컬과 원격 머신에서
+> Claude + Codex + Gemini를 병렬 실행하고, file-lease로 충돌을 방지하며,
+> 결과를 자동 통합한다. triflux의 킬러 스킬.
+
+## 트리거
+
+- `swarm`, `스웜`, `병렬 실행`, `다중 워커`, `PRD 실행`, `swarm launch`
+- `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
+- Hub 실행 중 (`curl -sf http://127.0.0.1:27888/status`)
+- Codex CLI 또는 Gemini CLI (사용할 agent에 따라)
+- 원격 shard 사용 시: SSH 키 인증 + 원격 머신에 Claude Code 설치
+- 프로젝트에 `docs/prd/` 디렉토리 존재
+
+## 실행 흐름
+
+### Step 1: PRD 탐색
+
+```bash
+find docs/prd -name '*.md' -not -name '_template.md' -not -path '*/archived/*' | sort
+```
+
+AskUserQuestion으로 실행할 PRD 선택. 복수 선택 시 각각 독립 shard.
+
+### 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 { planSwarm } from '../../hub/team/swarm-planner.mjs';
+
+const swarmPlan = planSwarm(selectedPrdPath);
+```
+
+계획을 사용자에게 보여주고 승인 요청:
+- shard 수, 파일 배분, lease 맵, merge 순서
+- 원격 shard 표시 (host 정보)
+- 모델 배분 표시 (agent 정보)
+- critical shard 표시 (redundant execution 대상)
+
+### Step 4: Hypervisor 실행
+
+```javascript
+import { createSwarmHypervisor } from '../../hub/team/swarm-hypervisor.mjs';
+
+const hyper = createSwarmHypervisor({
+  workdir: process.cwd(),
+  logsDir: join(process.cwd(), '.triflux', 'swarm-logs'),
+  maxRestarts: 2,
+});
+
+const run = hyper.launch(swarmPlan);
+```
+
+실행 중 상태 모니터링:
+- `hyper.on('shardLaunched', ...)` -> 진행 표시
+- `hyper.on('shardCompleted', ...)` -> 완료/실패 표시
+- `hyper.on('warning', ...)` -> 경고 (파일 충돌 등)
+
+원격 shard 실행 시:
+1. `probeRemoteEnv(host)` -> 원격 환경 감지 (OS, shell, Claude 경로)
+2. conductor가 `remote: true` 설정으로 SSH 경유 세션 실행
+3. 완료 후 `fetchRemoteShard()`로 원격 브랜치를 로컬로 fetch
+
+### Step 5: 결과 검증 + 통합
+
+```javascript
+const status = hyper.getStatus();
+// status.completedShards, status.failedShards, status.workers
+```
+
+통합 결과를 사용자에게 보고:
+- 성공: merged shard 목록 (로컬/원격 구분 표시)
+- 실패: 충돌/실패 shard 목록 + 수동 해결 안내
+
+### Step 6: 정리
+
+```javascript
+await hyper.shutdown('completed');
+```
+
+## PRD 예제: 다중 기기 x 다중 모델
+
+```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 리팩터 완료 후)
+```
+
+위 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 실행 프롬프트. `\|`로 멀티라인 |
+
+## 제약
+
+- `codex exec` / `gemini -p` 직접 호출 금지 (headless-guard)
+- MAX_CONCURRENCY 기본 4 (WT 프리징 방지)
+- WT 조작 간 sleep 2s (race-guard)
+- config.toml과 CLI 플래그 중복 지정 금지
+
+## Redundant Execution
+
+critical shard (hard lease 또는 고위험 파일)에 대해:
+
+```javascript
+import { shouldRunRedundant, reconcile } from '../../hub/team/swarm-reconciler.mjs';
+
+if (shouldRunRedundant(shard)) {
+  // primary + verifier 이중 실행
+  const decision = await reconcile(primaryResult, verifierResult);
+  // decision.selected: 'primary' | 'verifier' | 'hitl'
+}
+```
+
+HITL fallback 시 AskUserQuestion으로 사용자에게 선택 요청.
+
+## 장애 처리
+
+| 장애 | 분류 | 대응 |
+|------|------|------|
+| 워커 크래시 | 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-codex-swarm**: deprecated. 이 스킬로 통합됨 (backward compat alias)
+- **tfx-remote-spawn**: 단독 원격 세션 관리(list, attach, send)용으로 유지. swarm은 다중 shard 병렬 관리
+- **tfx-multi**: Claude Native Teams 기반 로컬 오케스트레이션. swarm은 PRD 기반 worktree 분할

package/tui/codex-profile.mjs

@@ -1,32 +1,56 @@
 #!/usr/bin/env node
 // tui/codex-profile.mjs — Interactive Codex Profile Manager
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
-import { join } from "node:path";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
+import { join } from "node:path";
 import {
-  clear, box, table, divider, label, ok, warn, fail, info,
-  select, confirm, input, spinner,
-  RESET, DIM, BOLD, CYAN, AMBER, GREEN, RED, YELLOW, WHITE, GRAY,
-  onExit, showCursor,
+  BOLD,
+  box,
+  CYAN,
+  clear,
+  confirm,
+  DIM,
+  divider,
+  fail,
+  GREEN,
+  info,
+  input,
+  label,
+  ok,
+  onExit,
+  RED,
+  RESET,
+  select,
+  showCursor,
+  table,
+  WHITE,
+  warn,
+  YELLOW,
 } from "./core.mjs";
 
 const CODEX_DIR = join(homedir(), ".codex");
 const CONFIG_PATH = join(CODEX_DIR, "config.toml");
 
 const KNOWN_MODELS = [
-  { label: "gpt-5.4",            hint: "최신 플래그십" },
-  { label: "gpt-5.3-codex",      hint: "코딩 특화" },
+  { label: "gpt-5.4", hint: "최신 플래그십" },
+  { label: "gpt-5.3-codex", hint: "코딩 특화" },
   { label: "gpt-5.1-codex-mini", hint: "경량 Spark" },
-  { label: "o3",                  hint: "추론 특화" },
-  { label: "o4-mini",             hint: "추론 경량" },
-  { label: "직접 입력",            hint: "" },
+  { label: "o3", hint: "추론 특화" },
+  { label: "o4-mini", hint: "추론 경량" },
+  { label: "직접 입력", hint: "" },
 ];
 
 const EFFORT_LEVELS = [
-  { label: "low",    hint: "빠른 응답, 최소 추론" },
+  { label: "low", hint: "빠른 응답, 최소 추론" },
   { label: "medium", hint: "균형 잡힌 추론" },
-  { label: "high",   hint: "깊은 추론" },
-  { label: "xhigh",  hint: "최대 추론 (느림)" },
+  { label: "high", hint: "깊은 추론" },
+  { label: "xhigh", hint: "최대 추론 (느림)" },
 ];
 
 // ── TOML Parsing ──
@@ -175,7 +199,10 @@ function showStatus(config) {
 
   console.log();
   label("기본 모델", `${WHITE}${defaults.model || "미설정"}${RESET}`);
-  label("기본 Effort", `${WHITE}${defaults.model_reasoning_effort || "미설정"}${RESET}`);
+  label(
+    "기본 Effort",
+    `${WHITE}${defaults.model_reasoning_effort || "미설정"}${RESET}`,
+  );
   console.log();
 
   if (profiles.length === 0) {
@@ -208,7 +235,9 @@ function effortColor(effort) {
 
 async function pickModel(current) {
   const idx = KNOWN_MODELS.findIndex((m) => m.label === current);
-  const choice = await select("모델 선택", KNOWN_MODELS, { initial: Math.max(0, idx) });
+  const choice = await select("모델 선택", KNOWN_MODELS, {
+    initial: Math.max(0, idx),
+  });
   if (!choice) return null;
   if (choice.value.label === "직접 입력") {
     return await input("모델 ID", current || "");
@@ -218,7 +247,9 @@ async function pickModel(current) {
 
 async function pickEffort(current) {
   const idx = EFFORT_LEVELS.findIndex((e) => e.label === current);
-  const choice = await select("Reasoning Effort 선택", EFFORT_LEVELS, { initial: Math.max(0, idx) });
+  const choice = await select("Reasoning Effort 선택", EFFORT_LEVELS, {
+    initial: Math.max(0, idx),
+  });
   if (!choice) return null;
   return choice.value.label;
 }
@@ -240,7 +271,9 @@ async function editProfile(config) {
 
   const profile = profiles[picked.index];
   console.log();
-  info(`현재: ${BOLD}${profile.name}${RESET} → ${profile.model} / ${profile.model_reasoning_effort}`);
+  info(
+    `현재: ${BOLD}${profile.name}${RESET} → ${profile.model} / ${profile.model_reasoning_effort}`,
+  );
 
   const newModel = await pickModel(profile.model);
   if (newModel === null) return config;
@@ -249,7 +282,9 @@ async function editProfile(config) {
   if (newEffort === null) return config;
 
   console.log();
-  info(`변경: ${profile.model} → ${BOLD}${newModel}${RESET}, ${profile.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`);
+  info(
+    `변경: ${profile.model} → ${BOLD}${newModel}${RESET}, ${profile.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`,
+  );
 
   if (!(await confirm("저장하시겠습니까?"))) return config;
 
@@ -259,7 +294,7 @@ async function editProfile(config) {
     if (!["name", "model", "model_reasoning_effort"].includes(k)) props[k] = v;
   }
 
-  let raw = writeProfile(config.raw, profile.name, props);
+  const raw = writeProfile(config.raw, profile.name, props);
   save(raw);
   ok(`${profile.name} 프로파일 저장 완료`);
   return readConfig();
@@ -268,7 +303,9 @@ async function editProfile(config) {
 async function editDefault(config) {
   const { defaults } = config;
   info(`현재 기본 모델: ${BOLD}${defaults.model || "미설정"}${RESET}`);
-  info(`현재 기본 Effort: ${BOLD}${defaults.model_reasoning_effort || "미설정"}${RESET}`);
+  info(
+    `현재 기본 Effort: ${BOLD}${defaults.model_reasoning_effort || "미설정"}${RESET}`,
+  );
 
   const newModel = await pickModel(defaults.model);
   if (newModel === null) return config;
@@ -277,7 +314,9 @@ async function editDefault(config) {
   if (newEffort === null) return config;
 
   console.log();
-  info(`변경: ${defaults.model} → ${BOLD}${newModel}${RESET}, ${defaults.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`);
+  info(
+    `변경: ${defaults.model} → ${BOLD}${newModel}${RESET}, ${defaults.model_reasoning_effort} → ${BOLD}${newEffort}${RESET}`,
+  );
 
   if (!(await confirm("저장하시겠습니까?"))) return config;
 
@@ -307,7 +346,10 @@ async function addProfile(config) {
   info(`추가: ${BOLD}${name}${RESET} → ${model} / ${effort}`);
   if (!(await confirm("저장하시겠습니까?"))) return config;
 
-  const raw = writeProfile(config.raw, name, { model, model_reasoning_effort: effort });
+  const raw = writeProfile(config.raw, name, {
+    model,
+    model_reasoning_effort: effort,
+  });
   save(raw);
   ok(`${name} 프로파일 추가 완료`);
   return readConfig();
@@ -325,7 +367,12 @@ async function removeProfile(config) {
   if (!picked) return config;
 
   const name = profiles[picked.index].name;
-  if (!(await confirm(`${RED}${name}${RESET} 프로파일을 삭제하시겠습니까?`, false))) {
+  if (
+    !(await confirm(
+      `${RED}${name}${RESET} 프로파일을 삭제하시겠습니까?`,
+      false,
+    ))
+  ) {
     return config;
   }
 
@@ -350,11 +397,11 @@ function save(content) {
 // ── Main Loop ──
 
 const MENU = [
-  { label: "프로파일 모델 변경",   hint: "모델/effort 수정" },
-  { label: "기본 모델 변경",       hint: "top-level default" },
-  { label: "프로파일 추가",        hint: "새 프로파일 생성" },
-  { label: "프로파일 삭제",        hint: "기존 프로파일 제거" },
-  { label: "종료",                hint: "Ctrl+C" },
+  { label: "프로파일 모델 변경", hint: "모델/effort 수정" },
+  { label: "기본 모델 변경", hint: "top-level default" },
+  { label: "프로파일 추가", hint: "새 프로파일 생성" },
+  { label: "프로파일 삭제", hint: "기존 프로파일 제거" },
+  { label: "종료", hint: "Ctrl+C" },
 ];
 
 async function main() {
@@ -384,10 +431,18 @@ async function main() {
 
     console.log();
     switch (choice.index) {
-      case 0: config = await editProfile(config); break;
-      case 1: config = await editDefault(config); break;
-      case 2: config = await addProfile(config); break;
-      case 3: config = await removeProfile(config); break;
+      case 0:
+        config = await editProfile(config);
+        break;
+      case 1:
+        config = await editDefault(config);
+        break;
+      case 2:
+        config = await addProfile(config);
+        break;
+      case 3:
+        config = await removeProfile(config);
+        break;
     }
 
     console.log();

package/tui/core.mjs

@@ -45,7 +45,9 @@ export function box(title, width = 50) {
   const left = Math.floor((inner - padded.length) / 2);
   const right = inner - left - padded.length;
   console.log(`  ${DIM}┌${"─".repeat(inner)}┐${RESET}`);
-  console.log(`  ${DIM}│${RESET}${" ".repeat(left)}${BOLD}${AMBER}${padded}${RESET}${" ".repeat(right)}${DIM}│${RESET}`);
+  console.log(
+    `  ${DIM}│${RESET}${" ".repeat(left)}${BOLD}${AMBER}${padded}${RESET}${" ".repeat(right)}${DIM}│${RESET}`,
+  );
   console.log(`  ${DIM}└${"─".repeat(inner)}┘${RESET}`);
 }
 
@@ -58,8 +60,8 @@ export function table(headers, rows, { indent = 2 } = {}) {
   const widths = headers.map((h, i) =>
     Math.max(
       stripAnsi(h).length,
-      ...rows.map((r) => stripAnsi(String(r[i] ?? "")).length)
-    )
+      ...rows.map((r) => stripAnsi(String(r[i] ?? "")).length),
+    ),
   );
 
   const top = widths.map((w) => "─".repeat(w + 2)).join("┬");
@@ -84,10 +86,18 @@ export function table(headers, rows, { indent = 2 } = {}) {
   console.log(`${pad}└${bot}┘`);
 }
 
-export function ok(msg) { console.log(`  ${GREEN}✓${RESET} ${msg}`); }
-export function warn(msg) { console.log(`  ${YELLOW}⚠${RESET} ${msg}`); }
-export function fail(msg) { console.log(`  ${RED}✗${RESET} ${msg}`); }
-export function info(msg) { console.log(`  ${CYAN}ℹ${RESET} ${msg}`); }
+export function ok(msg) {
+  console.log(`  ${GREEN}✓${RESET} ${msg}`);
+}
+export function warn(msg) {
+  console.log(`  ${YELLOW}⚠${RESET} ${msg}`);
+}
+export function fail(msg) {
+  console.log(`  ${RED}✗${RESET} ${msg}`);
+}
+export function info(msg) {
+  console.log(`  ${CYAN}ℹ${RESET} ${msg}`);
+}
 
 export function label(key, value) {
   console.log(`  ${DIM}${key}:${RESET} ${BOLD}${value}${RESET}`);
@@ -102,9 +112,14 @@ export async function select(title, options, { initial = 0 } = {}) {
       const o = typeof options[i] === "string" ? options[i] : options[i].label;
       console.log(`  ${DIM}${i + 1}.${RESET} ${o}`);
     }
-    const answer = await input(`선택 (1-${options.length})`, String(initial + 1));
+    const answer = await input(
+      `선택 (1-${options.length})`,
+      String(initial + 1),
+    );
     const idx = parseInt(answer, 10) - 1;
-    return idx >= 0 && idx < options.length ? { index: idx, value: options[idx] } : null;
+    return idx >= 0 && idx < options.length
+      ? { index: idx, value: options[idx] }
+      : null;
   }
 
   readline.emitKeypressEvents(process.stdin);
@@ -116,7 +131,8 @@ export async function select(title, options, { initial = 0 } = {}) {
   const total = options.length;
 
   const getLabel = (o) => (typeof o === "string" ? o : o.label);
-  const getHint = (o) => (typeof o === "object" && o.hint ? ` ${DIM}${o.hint}${RESET}` : "");
+  const getHint = (o) =>
+    typeof o === "object" && o.hint ? ` ${DIM}${o.hint}${RESET}` : "";
 
   const render = (first = false) => {
     if (!first) moveUp(total);
@@ -167,8 +183,13 @@ export async function select(title, options, { initial = 0 } = {}) {
 // ── Input: Confirm ──
 
 export async function confirm(message, defaultYes = true) {
-  const hint = defaultYes ? `${BOLD}Y${RESET}${DIM}/n${RESET}` : `${DIM}y/${RESET}${BOLD}N${RESET}`;
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const hint = defaultYes
+    ? `${BOLD}Y${RESET}${DIM}/n${RESET}`
+    : `${DIM}y/${RESET}${BOLD}N${RESET}`;
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
 
   return new Promise((resolve) => {
     rl.question(`  ${CYAN}?${RESET} ${message} [${hint}] `, (answer) => {
@@ -184,7 +205,10 @@ export async function confirm(message, defaultYes = true) {
 
 export async function input(message, defaultValue = "") {
   const hint = defaultValue ? ` ${DIM}(${defaultValue})${RESET}` : "";
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
 
   return new Promise((resolve) => {
     rl.question(`  ${CYAN}?${RESET} ${message}${hint}: `, (answer) => {
@@ -202,7 +226,9 @@ export function spinner(message) {
   hideCursor();
   const id = setInterval(() => {
     clearLine();
-    process.stdout.write(`  ${CYAN}${frames[i++ % frames.length]}${RESET} ${message}`);
+    process.stdout.write(
+      `  ${CYAN}${frames[i++ % frames.length]}${RESET} ${message}`,
+    );
   }, 80);
 
   return {
@@ -230,7 +256,11 @@ export function sleep(ms) {
 
 // graceful exit
 export function onExit(fn) {
-  const handler = () => { showCursor(); fn?.(); process.exit(0); };
+  const handler = () => {
+    showCursor();
+    fn?.();
+    process.exit(0);
+  };
   process.on("SIGINT", handler);
   process.on("SIGTERM", handler);
 }