triflux 10.9.19 → 10.9.20

package/CLAUDE.md

@@ -0,0 +1,212 @@
+<!-- prompt-hygiene:ignore line_count_warning -->
+# triflux — Claude Code 운영 가이드
+
+<core-systems>
+## 핵심 스킬 시스템 (항상 인지)
+
+이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
+
+| 시스템 | 접두사 | 용도 | 스킬 수 |
+|--------|--------|------|---------|
+| **triflux** | `/tfx-*` | CLI 라우팅, 멀티모델 오케스트레이션, 스웜, 원격 실행 | ~40개 |
+| **gstack** | `/` (접두사 없음) | QA, ship, investigate, design, review, checkpoint | ~35개 |
+| **omc** | `/oh-my-claudecode:*` | autopilot, ralph, team, ultrawork, ccg | ~25개 |
+
+스킬을 모르면 자연어 라우팅(아래)으로 자동 매핑된다.
+세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+</core-systems>
+
+<psmux-wt>
+## psmux/WT 규칙
+
+psmux 세션·WT 패인을 생성/조작/정리할 때 `tfx-psmux-rules` 스킬을 참조한다.
+WT 프리징 방지: exit → sleep 2 → kill 순서. 바로 kill하지 않는다.
+
+### wt.exe → wt-manager 경유
+
+safety-guard가 `wt.exe`, `wt new-tab`, `wt split-pane`, `Start-Process wt`를 차단한다.
+`hub/team/wt-manager.mjs`의 API를 사용한다.
+
+| 용도 | API |
+|------|-----|
+| 새 탭 | `createTab({ title, command, profile, cwd })` |
+| 패인 분할 | `splitPane({ direction: 'H'\|'V', title, command })` |
+| 다중 배치 | `applySplitLayout([{ title, command, direction }])` |
+| 탭 정리 | `closeTab(title)` / `closeStale({ olderThanMs, titlePattern })` |
+
+차단과 대안은 항상 쌍으로 존재해야 한다. 차단만 추가하고 대안을 안 만들면 데드락.
+
+### psmux에서 Codex 실행
+
+| 방식 | 동작 | 이유 |
+|------|------|------|
+| `codex` (interactive) | 불가 | psmux에서 TTY를 못 잡음 |
+| `codex < prompt.md` | 불가 | "stdin is not a terminal" |
+| `codex exec "$(cat prompt.md)" -s danger-full-access --dangerously-bypass-approvals-and-sandbox` | 사용 | 유일한 안전 경로 |
+
+`codex exec`는 config.toml `approval_mode`를 무시하므로 `--dangerously-bypass-approvals-and-sandbox` 필수.
+`-s` 유효값: read-only, workspace-write, danger-full-access.
+</psmux-wt>
+
+<codex-config>
+## Codex config.toml
+
+config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
+
+| config.toml에 있으면 | CLI에서 생략 |
+|---------------------|-------------|
+| `approval_mode = "auto"` | `-a`, `--full-auto` |
+| `sandbox = "workspace-write"` | `-s`, `--full-auto` |
+
+안전 패턴: config.toml에 기본값을 두고, CLI에서는 `--profile` 선택만 한다.
+</codex-config>
+
+<account-broker>
+## AccountBroker (계정 브로커)
+
+conductor, headless, swarm-hypervisor가 하나의 AccountBroker 싱글턴을 공유한다.
+
+| 항목 | 설명 |
+|------|------|
+| 계정별 CircuitBreaker | 장애 격리 — 한 계정 오류가 다른 계정에 전파되지 않음 |
+| busy 플래그 | 동일 계정 이중 임대(double-lease) 방지 |
+| `/broker/reload` | 장시간 세션 중 accounts.json 핫리로드 |
+| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts` — HUD 연동용 |
+</account-broker>
+
+<remote>
+## 원격 실행
+
+### 스킬 구분
+
+| 스킬 | 대상 | 방식 |
+|------|------|------|
+| tfx-codex-swarm | 로컬 전용 | 로컬 worktree + psmux |
+| tfx-remote-spawn | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
+
+codex를 SSH 너머로 직접 실행하지 않는다. config.toml 충돌 + TTY 문제.
+원격에서 codex가 필요하면: remote-spawn → Claude Code → Claude가 내부에서 codex 호출.
+
+### SSH 패턴
+
+hosts.json `os` 필드로 대상 셸을 판단한다. safety-guard도 이 필드를 참조.
+
+| 대상 OS | 셸 | 패턴 |
+|---------|-----|------|
+| windows | PowerShell | scp + `pwsh -File` 필수. `$var` → `$env:VAR`, `2>/dev/null` → `2>$null` |
+| darwin | zsh | 인라인 가능. brew PATH 주의 (`/opt/homebrew/bin`) |
+| linux | bash | 인라인 가능. 표준 POSIX |
+
+- `~` → `$HOME` 변환은 모든 OS 공통
+</remote>
+
+<headless-retrieval>
+## Headless 결과 회수
+
+background로 실행한 headless 결과는 **반드시 task-notification 완료 후** 읽는다.
+
+| 패턴 | 올바름 | 이유 |
+|------|--------|------|
+| task-notification 후 output 파일 읽기 | YES | 프로세스 종료 = 워커 전부 완료 |
+| task-notification 전 output 파일 tail | NO | 시작 메시지만 보이고 "실패"로 오진 |
+| psmux capture-pane으로 중간 체크 | NO | 워커 진행 중이면 빈 화면일 수 있음 |
+
+완료 마커: `=== HEADLESS_COMPLETE succeeded=N failed=N total=N ===`
+워커 상세: `$TMPDIR/tfx-headless/{sessionName}-worker-N.txt`
+</headless-retrieval>
+
+<cross-review>
+## 교차 검증
+
+- Claude 작성 코드 → Codex 리뷰
+- Codex 작성 코드 → Claude 리뷰
+- 동일 모델 self-approve 하지 않는다
+- git commit 전 미검증 파일 감지 시 nudge
+</cross-review>
+
+<session-context>
+## 맥락 이탈 판단
+
+현재 세션 맥락과 무관한 요청이 감지되면 psmux 격리를 제안한다.
+
+| 확신도 | 신호 | 행동 |
+|--------|------|------|
+| 확실 | "새 탭", "별도로", "새 세션" | 바로 psmux spawn |
+| 높음 | 다른 프로젝트/스택 언급 | 분리 제안 |
+| 중간 | 작업 유형 전환 | 분리 제안 + 현재 세션 옵션 |
+| 낮음 | 현재 작업 연장 | 세션 유지 |
+</session-context>
+
+<routing>
+## 자연어 → 스킬 라우팅
+
+사용자가 스킬명을 모르더라도 자연어로 요청하면 아래 규칙에 따라 적절한 스킬을 호출한다.
+
+### 행동 유형 → 스킬 매핑
+
+| 의도 | 자연어 신호 | 스킬 |
+|------|-----------|------|
+| 구현/수정 | 만들어, 고쳐, 구현해, 짜줘, 수정해, 바꿔 | tfx-auto |
+| 리뷰 | 봐줘, 리뷰해, 검토해, 괜찮아? | tfx-review |
+| 분석 | 분석해, 어떻게 돌아가?, 구조가 뭐야 | tfx-analysis |
+| 계획 | 계획, 어떻게 하지, 설계해 | tfx-plan |
+| 검색 | 찾아, 어디있어, 파일 찾아 | tfx-find |
+| 리서치 (빠른) | 검색해줘, 찾아봐, 공식문서, 이거 뭐야 | tfx-research |
+| 리서치 (자율) | 자율 리서치, 검색하고 정리해, research and plan | tfx-autoresearch |
+| 테스트 | 테스트, 검증, 돌려봐, QA | tfx-qa |
+| 정리 | 정리해, 슬롭 제거, 클린업 | tfx-prune |
+| 토론 | 뭐가 나을까, 비교해, A vs B | tfx-debate |
+
+### 깊이 수정자
+
+| 수정자 | 신호 | 효과 |
+|--------|------|------|
+| 기본 | (없음), 빠르게, 간단히 | Light 스킬 |
+| 깊이 | 제대로, 꼼꼼히, 철저히 | Deep 스킬 (tfx-deep-*). 예외: tfx-deep-interview는 Gemini 단독 |
+| 합의 | 3자, 교차, 다각도 | consensus 프로토콜 |
+| 반복 | 끝까지, 멈추지마, ralph | persist 모드 |
+| 자율 | 알아서, 자동으로, autopilot | autopilot 모드 |
+
+### CLI 라우팅
+
+headless-guard가 `codex exec` / `gemini -y -p` 직접 호출을 차단한다. tfx 스킬 경유 필수.
+
+**Layer 1 — Light** (tfx-route.sh → 단일 CLI)
+
+| 스킬 | CLI | 용도 |
+|------|-----|------|
+| tfx-auto | 자동 | 통합 진입점 |
+| tfx-codex | Codex | Codex 전용 |
+| tfx-gemini | Gemini | Gemini 전용 |
+| tfx-autopilot | Codex→검증 | 단일 파일, 5분 이내 |
+| tfx-autoroute | 자동 승격 | 실패→더 강한 모델 |
+
+**Layer 2 — Deep** (headless 3-CLI 합의)
+
+tfx-deep-review, tfx-deep-qa, tfx-deep-plan, tfx-deep-research, tfx-consensus, tfx-debate, tfx-panel, tfx-fullcycle, tfx-persist
+
+**Layer 3 — Remote/병렬**
+
+| 스킬 | 용도 |
+|------|------|
+| tfx-multi | 2+개 태스크 headless 병렬 |
+| tfx-swarm | PRD별 worktree + 다중 모델(Codex/Gemini/Claude) + 다중 기기(로컬+원격) |
+| tfx-remote-spawn | Claude Code 원격 세션 (SSH, setup 필수) |
+
+**Claude 네이티브** (CLI 불필요): tfx-find, tfx-forge, tfx-prune, tfx-index, tfx-setup, tfx-doctor, tfx-hooks, tfx-hub
+
+자원 우선순위: remote-spawn > swarm > multi > Light > 로컬 단독
+
+### 충돌 해소
+
+- ralph = persist alias
+- "auto" 단독 → tfx-auto. "알아서 해" → tfx-autopilot
+- "코드에서 찾아" → tfx-find. "알아봐" → tfx-research
+- 복합 의도: "구현하고 리뷰까지" → tfx-auto → cross-review hook
+
+### Q-Learning 동적 라우팅 (실험적)
+
+- `TRIFLUX_DYNAMIC_ROUTING=true` 또는 `1` 설정 시 Q-Learning 기반 동적 스킬 라우팅 활성화
+- `routing-weights.json` + Q-table로 스킬 선택 최적화
+- 기본 비활성
+</routing>

package/hub/lib/bash-path.mjs

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+
+const GIT_BASH_PATHS = Object.freeze([
+  "C:/Program Files/Git/bin/bash.exe",
+  "C:/Program Files/Git/usr/bin/bash.exe",
+  "C:/Program Files (x86)/Git/bin/bash.exe",
+  "C:/Program Files (x86)/Git/usr/bin/bash.exe",
+]);
+
+/**
+ * Resolve a concrete Git Bash executable on Windows.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform=process.platform]
+ * @param {(path: string) => boolean} [opts.exists=existsSync]
+ * @returns {string | null}
+ */
+export function resolveGitBashExecutable(opts = {}) {
+  const { platform = process.platform, exists = existsSync } = opts;
+
+  if (platform !== "win32") {
+    return null;
+  }
+
+  return GIT_BASH_PATHS.find((candidate) => exists(candidate)) || null;
+}
+
+/**
+ * Resolve a Windows-safe bash executable.
+ * On Windows we prefer Git Bash over bare `bash`, which may resolve to WSL.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform=process.platform]
+ * @param {(path: string) => boolean} [opts.exists=existsSync]
+ * @returns {string}
+ */
+export function resolveBashExecutable(opts = {}) {
+  return resolveGitBashExecutable(opts) || "bash";
+}
+
+function shellQuote(command) {
+  return `'${String(command).replace(/'/g, `'"'"'`)}'`;
+}
+
+/**
+ * Wrap .sh script command strings so Windows always runs them through Bash.
+ * This prevents shell:true child launches from treating a script path like an
+ * openable file association instead of an executable script.
+ *
+ * @param {string} command
+ * @param {object} [opts]
+ * @param {string} [opts.bashCommand]
+ * @returns {string}
+ */
+export function ensureBashScriptExecution(command, opts = {}) {
+  const text = String(command || "").trim();
+  if (!text) return text;
+
+  if (!/\.sh(?:\s|$)/iu.test(text)) {
+    return text;
+  }
+
+  if (
+    /^(?:\s*[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)*(?:bash(?:\.exe)?|sh)\b/iu.test(
+      text,
+    )
+  ) {
+    return text;
+  }
+
+  const bashCommand = opts.bashCommand || resolveBashExecutable();
+  return `${bashCommand} -lc ${shellQuote(text)}`;
+}

package/hub/team/dashboard-open.mjs

@@ -1,11 +1,5 @@
 import { psmuxExec } from "./psmux.mjs";
-import {
-  detectMultiplexer,
-  focusWtPane,
-  hasWindowsTerminal,
-  resolveAttachCommand,
-  tmuxExec,
-} from "./session.mjs";
+import { hasWindowsTerminal } from "./session.mjs";
 import { createWtManager } from "./wt-manager.mjs";
 
 function sanitizeWindowTitle(value, fallback = "triflux") {
@@ -81,26 +75,6 @@ async function spawnWindowsTerminal(spec, opts = {}) {
   }
 }
 
-export function focusManagedPane(target, opts = {}) {
-  const { teammateMode = "", layout = "1xN" } = opts;
-  const paneRef = String(target || "");
-
-  if (teammateMode === "wt" || paneRef.startsWith("wt:")) {
-    const paneIndex = parseWorkerNumber(paneRef);
-    return paneIndex != null && focusWtPane(paneIndex, { layout });
-  }
-
-  if (!paneRef) return false;
-  try {
-    if (detectMultiplexer() === "psmux")
-      psmuxExec(["select-pane", "-t", paneRef]);
-    else tmuxExec(`select-pane -t ${paneRef}`);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export function openHeadlessDashboardTarget(sessionName, opts = {}) {
   const { worker = null, openAll = false, cwd = process.cwd(), title } = opts;
 
@@ -126,44 +100,3 @@ export function openHeadlessDashboardTarget(sessionName, opts = {}) {
   );
   return true;
 }
-
-export function openDashboardRuntimeTarget(runtime, opts = {}) {
-  const {
-    teammateMode = "",
-    sessionName = "",
-    targetPane = "",
-    layout = "1xN",
-    openAll = false,
-    cwd = process.cwd(),
-    title = "",
-  } = { ...runtime, ...opts };
-
-  if (teammateMode === "headless") {
-    return openHeadlessDashboardTarget(sessionName, {
-      worker: openAll ? null : targetPane,
-      openAll,
-      cwd,
-      title,
-    });
-  }
-
-  if (
-    (teammateMode === "wt" || String(targetPane).startsWith("wt:")) &&
-    !openAll
-  ) {
-    return focusManagedPane(targetPane, { teammateMode: "wt", layout });
-  }
-
-  try {
-    if (!openAll && targetPane)
-      focusManagedPane(targetPane, { teammateMode, layout });
-    void spawnWindowsTerminal(resolveAttachCommand(sessionName), {
-      mode: decideDashboardOpenMode({ openAll }),
-      title: title || `▲ ${sanitizeSessionName(sessionName)}`,
-      cwd,
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}

package/hub/team/native-supervisor.mjs

@@ -9,6 +9,10 @@ import {
 } from "node:fs";
 import { createServer } from "node:http";
 import { dirname, join } from "node:path";
+import {
+  ensureBashScriptExecution,
+  resolveBashExecutable,
+} from "../lib/bash-path.mjs";
 import { verifySlimWrapperRouteExecution } from "./native.mjs";
 import { forceCleanupTeam } from "./nativeProxy.mjs";
 
@@ -149,7 +153,10 @@ function validateMemberCommand(command, memberName) {
 }
 
 function spawnMember(member) {
-  validateMemberCommand(member.command, member.name);
+  const command = ensureBashScriptExecution(member.command, {
+    bashCommand: resolveBashExecutable(),
+  });
+  validateMemberCommand(command, member.name);
 
   const outPath = join(logsDir, `${member.name}.out.log`);
   const errPath = join(logsDir, `${member.name}.err.log`);
@@ -157,7 +164,7 @@ function spawnMember(member) {
   const outWs = createWriteStream(outPath, { flags: "a" });
   const errWs = createWriteStream(errPath, { flags: "a" });
 
-  const child = spawn(member.command, {
+  const child = spawn(command, {
     shell: true,
     env: {
       ...process.env,

package/hub/team/psmux.mjs

@@ -1,10 +1,12 @@
 // hub/team/psmux.mjs — Windows psmux 세션/키바인딩/캡처/steering 관리
 // 의존성: child_process, fs, os, path (Node.js 내장)만 사용
-import * as childProcess from "../lib/spawn-trace.mjs";
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { formatPsmuxInstallGuidance } from "../../scripts/lib/psmux-info.mjs";
+import { resolveGitBashExecutable } from "../lib/bash-path.mjs";
+import childProcess from "../lib/spawn-trace.mjs";
 import { IS_WINDOWS } from "../platform.mjs";
 
 const PSMUX_BIN = (() => {
@@ -35,7 +37,7 @@ const PSMUX_BIN = (() => {
   return "psmux"; // 최종 fallback — 원래대로
 })();
 const GIT_BASH =
-  process.env.GIT_BASH_PATH || "C:\\Program Files\\Git\\bin\\bash.exe";
+  process.env.GIT_BASH_PATH || resolveGitBashExecutable() || "bash";
 
 /** Windows psmux 세션의 기본 셸을 PowerShell로 강제한다 (pwsh7 우선, ps5 fallback). */
 const PWSH_BIN = (() => {
@@ -1041,17 +1043,7 @@ export function startCapture(sessionName, paneNameOrTarget) {
 // WSL bash에서는 /c/Users/... 경로가 유효하지 않아 exit 127 발생.
 // psmux pane 용 (PowerShell → bash 실행): & "path" 형식
 // Node.js execSync 용 (직접 실행): "path" 형식
-const _gitBashPath = (() => {
-  if (!IS_WINDOWS) return null;
-  const candidates = [
-    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
-    "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe",
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
-  }
-  return null;
-})();
+const _gitBashPath = IS_WINDOWS ? resolveGitBashExecutable() : null;
 // PowerShell call operator(&)가 필요: & "C:\...\bash.exe" -c '...'
 const GIT_BASH_BIN_PS = _gitBashPath ? `& "${_gitBashPath}"` : "bash";
 // Node.js execSync에서 직접 실행할 때는 따옴표만

package/hub/team/session.mjs

@@ -1,8 +1,8 @@
 // hub/team/session.mjs — tmux/psmux/wt 세션 생명주기 관리
 // 의존성: child_process (Node.js 내장)만 사용
 import { execSync, spawnSync } from "node:child_process";
+import { resolveGitBashExecutable } from "../lib/bash-path.mjs";
 import { getEnvironment } from "../lib/env-detect.mjs";
-import { createWtManager } from "./wt-manager.mjs";
 import {
   attachPsmuxSession,
   capturePsmuxPane,
@@ -15,27 +15,7 @@ import {
   psmuxExec,
   psmuxSessionExists,
 } from "./psmux.mjs";
-
-const GIT_BASH_CANDIDATES = [
-  "C:/Program Files/Git/bin/bash.exe",
-  "C:/Program Files/Git/usr/bin/bash.exe",
-];
-
-function findGitBashExe() {
-  for (const p of GIT_BASH_CANDIDATES) {
-    try {
-      execSync(`"${p}" --version`, {
-        stdio: "ignore",
-        timeout: 3000,
-        windowsHide: true,
-      });
-      return p;
-    } catch {
-      // 다음 후보
-    }
-  }
-  return null;
-}
+import { createWtManager } from "./wt-manager.mjs";
 
 /** Windows Terminal 실행 파일 존재 여부 */
 export function hasWindowsTerminal() {
@@ -73,7 +53,7 @@ function hasWslTmux() {
 
 /** Git Bash 내 tmux 사용 가능 여부 (Windows 전용) */
 function hasGitBashTmux() {
-  const bash = findGitBashExe();
+  const bash = resolveGitBashExecutable();
   if (!bash) return false;
   try {
     const r = spawnSync(bash, ["-lc", "tmux -V"], {
@@ -184,8 +164,8 @@ export function tmuxExec(args, opts = {}) {
  * @param {string} sessionName
  * @returns {{ command: string, args: string[] }}
  */
-export function resolveAttachCommand(sessionName) {
-  const mux = detectMultiplexer();
+export function resolveAttachCommand(sessionName, opts = {}) {
+  const mux = opts.mux || detectMultiplexer();
   if (!mux) {
     throw new Error("tmux/psmux 미발견");
   }
@@ -198,7 +178,7 @@ export function resolveAttachCommand(sessionName) {
   }
 
   if (mux === "git-bash-tmux") {
-    const bash = findGitBashExe();
+    const bash = opts.bashCommand || resolveGitBashExecutable();
     if (!bash) throw new Error("git-bash-tmux 감지 실패");
     return {
       command: bash,