triflux 10.7.1 → 10.8.0

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에서 생략 |
+|---------------------|-------------|
+| `sandbox = "elevated"` | `--full-auto` |
+| `approval_mode = "full-auto"` | `--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/cli-adapter-base.mjs

@@ -152,78 +152,6 @@ export function appendWarnings(stderr, warnings = []) {
   return [stderr, text].filter(Boolean).join("\n");
 }
 
-// ── Circuit breaker factory ─────────────────────────────────────
-
-/**
- * @deprecated Use per-account circuit breakers in account-broker.mjs instead.
- * Kept for backward compatibility with code that hasn't migrated yet.
- */
-export function createCircuitBreaker(opts = {}) {
-  const state = {
-    failures: [],
-    maxFailures: opts.maxFailures ?? 3,
-    windowMs: opts.windowMs ?? 10 * 60_000,
-    openedAt: 0,
-    trialInFlight: false,
-  };
-
-  function pruneFailures(now = Date.now()) {
-    state.failures = state.failures.filter(
-      (stamp) => now - stamp < state.windowMs,
-    );
-  }
-
-  function reset() {
-    state.failures = [];
-    state.openedAt = 0;
-    state.trialInFlight = false;
-  }
-
-  function recordFailure(isHalfOpen, now = Date.now()) {
-    pruneFailures(now);
-    state.failures = [...state.failures, now];
-    state.trialInFlight = false;
-    if (isHalfOpen || state.failures.length >= state.maxFailures) {
-      state.openedAt = now;
-    }
-  }
-
-  function getState(now = Date.now()) {
-    pruneFailures(now);
-    const withinWindow =
-      state.openedAt && now - state.openedAt < state.windowMs;
-    const current = withinWindow
-      ? "open"
-      : state.openedAt
-        ? "half-open"
-        : "closed";
-    return {
-      state: current,
-      failures: [...state.failures],
-      maxFailures: state.maxFailures,
-      windowMs: state.windowMs,
-      openedAt: state.openedAt || null,
-      trialInFlight: state.trialInFlight,
-    };
-  }
-
-  function canExecute() {
-    const circuit = getState();
-    if (circuit.state === "open") return { allowed: false, halfOpen: false };
-    if (circuit.state === "half-open" && state.trialInFlight)
-      return { allowed: false, halfOpen: true };
-    const halfOpen = circuit.state === "half-open";
-    if (halfOpen) state.trialInFlight = true;
-    return { allowed: true, halfOpen };
-  }
-
-  function clearTrial() {
-    state.trialInFlight = false;
-  }
-
-  return { getState, recordFailure, reset, canExecute, clearTrial };
-}
-
 // ── Broker-integrated execution ─────────────────────────────────
 
 /**

package/hub/lib/spawn-trace.mjs

@@ -2,18 +2,11 @@ import * as childProcess from "node:child_process";
 import { EventEmitter } from "node:events";
 import { createWriteStream, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { join } from "node:path";
 
 const LOG_DIR = join(homedir(), ".triflux", "logs");
 const DEDUPE_WINDOW_MS = 5_000;
 const RATE_WINDOW_MS = 1_000;
-const WINDOWS_TERMINAL_COMMANDS = new Set([
-  "wt",
-  "wt.exe",
-  "windowsterminal.exe",
-]);
-
-export const MAX_WT_TABS = 8;
 export const MAX_SPAWN_PER_SEC = resolvePositiveInteger(
   process.env.TRIFLUX_MAX_SPAWN_RATE,
   10,
@@ -30,7 +23,6 @@ let traceSequence = 0;
 const recentSpawnTimes = [];
 const dedupeEntries = new Map();
 const activeChildren = new Map();
-const activeWtChildren = new Set();
 
 function resolvePositiveInteger(...values) {
   for (const value of values) {
@@ -149,14 +141,6 @@ function getCwd(options) {
   return options.cwd || process.cwd();
 }
 
-function getCommandBasename(command) {
-  return basename(String(command || "")).toLowerCase();
-}
-
-function isWindowsTerminalSpawn(command) {
-  return WINDOWS_TERMINAL_COMMANDS.has(getCommandBasename(command));
-}
-
 function createPolicyError(reasonCode, message, meta = {}) {
   const error = new Error(message);
   error.code = "TRIFLUX_SPAWN_BLOCKED";
@@ -212,14 +196,6 @@ function enforceGuards(command, args, options) {
     );
   }
 
-  if (isWindowsTerminalSpawn(command) && activeWtChildren.size >= MAX_WT_TABS) {
-    return createPolicyError(
-      "wt_tab_cap",
-      `spawn-trace Windows Terminal cap exceeded (${MAX_WT_TABS})`,
-      { maxWtTabs: MAX_WT_TABS },
-    );
-  }
-
   recentSpawnTimes.push(now);
   if (dedupeKey) {
     dedupeEntries.set(dedupeKey, now);
@@ -234,9 +210,6 @@ function trackChild(child, meta) {
   }
 
   activeChildren.set(child, meta);
-  if (meta.isWindowsTerminalSpawn) {
-    activeWtChildren.add(child);
-  }
 
   let finalized = false;
   const finalize = (event, payload = {}) => {
@@ -246,7 +219,6 @@ function trackChild(child, meta) {
 
     finalized = true;
     activeChildren.delete(child);
-    activeWtChildren.delete(child);
 
     appendTrace({
       event,
@@ -381,7 +353,6 @@ export function spawn(command, args, options) {
     args: argsList,
     cwd: getCwd(normalizedOptions),
     reason: getReason(normalizedOptions),
-    isWindowsTerminalSpawn: isWindowsTerminalSpawn(command),
   });
 }
 
@@ -432,7 +403,6 @@ export function execFile(file, args, options, callback) {
     args: normalized.argsList,
     cwd: getCwd(normalized.options),
     reason: getReason(normalized.options),
-    isWindowsTerminalSpawn: isWindowsTerminalSpawn(file),
   });
 }
 
@@ -521,7 +491,6 @@ export default {
   spawn,
   execFile,
   execFileSync,
-  MAX_WT_TABS,
   MAX_SPAWN_PER_SEC,
   MAX_TOTAL_DESCENDANTS,
 };

package/hub/server.mjs

@@ -21,6 +21,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { createModuleLogger } from "../scripts/lib/logger.mjs";
+import { reloadBroker } from "./account-broker.mjs";
 import { createAdaptiveEngine } from "./adaptive.mjs";
 import { createAssignCallbackServer } from "./assign-callbacks.mjs";
 import { DelegatorService } from "./delegator/index.mjs";
@@ -706,6 +707,17 @@ export async function startHub({
         return writeJson(res, 200, getQosStatsPayload());
       }
 
+      if (path === "/broker/reload" && req.method === "POST") {
+        const result = reloadBroker();
+        if (!result.ok) {
+          return writeJson(res, 200, { ok: false, error: result.error });
+        }
+        const accounts = result.broker
+          ? [...result.broker.snapshot()].length
+          : 0;
+        return writeJson(res, 200, { ok: true, accounts });
+      }
+
       if (path.startsWith("/bridge")) {
         const isBridgeStatusGet =
           path === "/bridge/status" && req.method === "GET";

package/hub/team/conductor.mjs

@@ -332,7 +332,11 @@ export function createConductor(opts = {}) {
         `restart_${session.restarts + 1}/${maxRestarts}`,
       );
       session.restarts += 1;
-      void respawnSession(session);
+      const backoffMs = Math.min(1000 * 2 ** (session.restarts - 1), 30_000);
+      session._respawnTimer = setTimeout(() => {
+        session._respawnTimer = null;
+        void respawnSession(session);
+      }, backoffMs);
     } else {
       transition(session, STATES.DEAD, `maxRestarts(${maxRestarts})_exceeded`);
       emitter.emit("dead", { sessionId: session.id, reason });
@@ -681,6 +685,10 @@ export function createConductor(opts = {}) {
     if (!session) return;
     if (TERMINAL_STATES.has(session.state)) return;
 
+    if (session._respawnTimer) {
+      clearTimeout(session._respawnTimer);
+      session._respawnTimer = null;
+    }
     eventLog.append("kill", { session: id, reason });
     await cleanupChild(session);
     transition(session, STATES.FAILED, reason);
@@ -744,6 +752,10 @@ export function createConductor(opts = {}) {
     const cleanups = [...sessions.values()]
       .filter((s) => !TERMINAL_STATES.has(s.state))
       .map(async (s) => {
+        if (s._respawnTimer) {
+          clearTimeout(s._respawnTimer);
+          s._respawnTimer = null;
+        }
         s.probe?.stop();
         await cleanupChild(s);
         if (!TERMINAL_STATES.has(s.state)) {

package/hub/team/remote-session.mjs

@@ -118,7 +118,8 @@ function probeRemoteEnvViaPwsh(host) {
 
 function probeRemoteEnvViaPosix(host) {
   const script = [
-    "export PATH=/opt/homebrew/bin:/opt/homebrew/sbin:$HOME/.local/bin:$PATH",
+    '[ -f "$HOME/.zshenv" ] && . "$HOME/.zshenv" 2>/dev/null || true',
+    "export PATH=/opt/homebrew/bin:/opt/homebrew/sbin:$HOME/.local/bin:$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node 2>/dev/null | sort -V | tail -1)/bin:$PATH 2>/dev/null",
     "echo shell=$(basename $SHELL)",
     "echo home=$HOME",
     "command -v claude >/dev/null 2>&1 && echo claude=$(command -v claude) || echo claude=notfound",