triflux 10.17.4 → 10.18.0

package/CLAUDE.md

@@ -0,0 +1,169 @@
+# 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개 |
+
+스킬을 모르면 자연어 라우팅(`.claude/rules/tfx-routing.md`)으로 자동 매핑된다.
+세션 종료 전 메모리 파일이 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 })` |
+
+차단과 대안은 항상 쌍으로 존재해야 한다. 차단만 추가하고 대안을 안 만들면 데드락.
+
+### raw `psmux kill-session` → psmux wrapper 경유
+
+safety-guard가 raw `psmux kill-session`을 차단한다.
+세션 정리는 `hub/team/psmux.mjs` 공개 API 또는 internal wrapper로 우회한다.
+
+| 용도 | API / 래퍼 |
+|------|------------|
+| 세션 조회 | `listSessions({ filterTitle?, olderThanMs? })` |
+| title prefix / regex kill | `killSessionByTitle(titlePattern)` |
+| stale idle 세션 정리 | `pruneStale({ olderThanMs, dryRun })` |
+| Bash 훅 우회용 래퍼 | `node hub/team/psmux.mjs --internal kill-by-title <prefix\|/regex/>` |
+
+### 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>
+
+## 세부 규칙은 `.claude/rules/` 참조
+
+| 파일 | 내용 |
+|------|------|
+| `.claude/rules/tfx-routing.md` | 자연어 → 스킬 라우팅, CLI 라우팅 Layer 1~3, 충돌 해소 |
+| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi / swarm 실행 엔진 매핑, 격리 기준, 안티패턴 |
+| `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 6 decision principles, phase 우선순위, 충돌 해소 규칙 추출본 |
+| `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Gemini 업데이트 로직 |
+| `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
+
+Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.
+
+## GBrain Configuration (configured by /setup-gbrain)
+- Engine: pglite
+- Config file: ~/.gbrain/config.json (mode 0600)
+- Setup date: 2026-04-25
+- MCP registered: yes (user scope, absolute path)
+- Memory sync: artifacts-only (repo: github.com/tellang/gstack-brain-tellang)
+- Current repo policy: read-write (github.com/tellang/triflux)

package/hub/account-broker.mjs

@@ -796,6 +796,19 @@ class AccountBroker extends EventEmitter {
     }));
   }
 
+  // ── disabled marker ───────────────────────────────────────────
+
+  /**
+   * True when the broker holds zero accounts. Used by adapters to distinguish
+   * "broker exists but is empty (disable env / no accounts)" from "broker has
+   * accounts but lease() returned null (all busy/cooldown/circuit)" — the
+   * former should fall back to default ~/.codex/auth.json instead of returning
+   * circuit_open.
+   */
+  get isDisabled() {
+    return this.#state.size === 0;
+  }
+
   // ── nextAvailableEta ──────────────────────────────────────────
 
   nextAvailableEta(provider) {
@@ -849,7 +862,22 @@ function loadConfig() {
 
 // ── Singleton ────────────────────────────────────────────────────
 
+function isBrokerDisabledByEnv() {
+  const flag = process.env.TFX_DISABLE_ACCOUNT_BROKER;
+  return flag === "1" || flag === "true";
+}
+
+function createEmptyBroker() {
+  return new AccountBroker({ codex: [], gemini: [] });
+}
+
 function createBroker() {
+  if (isBrokerDisabledByEnv()) {
+    // Empty broker: lease() always returns null → callers fall back to default
+    // single-account path (~/.codex/auth.json). Avoids per-account multiplexing
+    // race conditions while keeping the AccountBroker API surface intact.
+    return createEmptyBroker();
+  }
   const config = loadConfig();
   if (!config) return null;
   try {
@@ -862,6 +890,10 @@ function createBroker() {
 
 /** Re-read config and replace the module-level singleton. ESM live binding propagates to all importers. */
 function reloadBroker() {
+  if (isBrokerDisabledByEnv()) {
+    broker = createEmptyBroker();
+    return { ok: true, broker, disabled: true };
+  }
   const config = loadConfig();
   if (!config) return { ok: false, error: "Config not found or invalid" };
   try {

package/hub/cli-adapter-base.mjs

@@ -241,8 +241,14 @@ export async function executeWithCircuitBroker({
 
   // access broker as live binding property (not destructured) so reloadBroker() propagates
   const hasBroker = brokerMod.broker != null;
-  const lease = hasBroker ? brokerMod.broker.lease({ provider }) : null;
-  if (hasBroker && !lease) {
+  // Empty broker (TFX_DISABLE_ACCOUNT_BROKER=1 or zero accounts) must not
+  // gate execution. lease() is null because there are no accounts to lease,
+  // not because all accounts are busy/cooldown/circuit. Treat it like
+  // hasBroker=false and fall through to the default auth path.
+  const brokerDisabled = hasBroker && brokerMod.broker.isDisabled === true;
+  const effectiveBroker = hasBroker && !brokerDisabled;
+  const lease = effectiveBroker ? brokerMod.broker.lease({ provider }) : null;
+  if (effectiveBroker && !lease) {
     return createResult(false, { fellBack: true, failureMode: "circuit_open" });
   }
 
@@ -263,11 +269,15 @@ export async function executeWithCircuitBroker({
   try {
     lastResult = await withRetry(
       async () => {
+        // PRD A1: lease 메타데이터를 runFn 에 전달해서 adapter 가 실제 spawn 시
+        // 해당 account 의 authFile/env/profile 을 적용할 수 있게 한다. lease=null
+        // 이면 adapter 는 default 경로 (단일 ~/.codex/auth.json) 로 동작한다.
         const result = await runFn(
           opts.prompt || "",
           opts.workdir || process.cwd(),
           preflight,
           attempts[attemptIndex],
+          lease,
         );
         const current = {
           ...result,
@@ -366,7 +376,14 @@ export async function runProcess(command, workdir, timeout, opts = {}) {
   let child;
 
   try {
-    child = spawn(command, { cwd: workdir, shell: true, windowsHide: true });
+    // PRD A1: opts.spawnEnv 가 있으면 그 env 로 spawn (lease 의 authFile/env 적용).
+    // undefined 면 spawn 의 default 동작 (부모 process env inherit) 유지.
+    child = spawn(command, {
+      cwd: workdir,
+      shell: true,
+      windowsHide: true,
+      env: opts.spawnEnv,
+    });
   } catch (error) {
     return createResult(false, {
       stderr: String(error?.message || error),

package/hub/codex-adapter.mjs

@@ -133,7 +133,7 @@ export function buildExecArgs(opts = {}) {
 
 // ── Codex execution ─────────────────────────────────────────────
 
-async function runCodex(prompt, workdir, preflight, attempt) {
+async function runCodex(prompt, workdir, preflight, attempt, lease) {
   const dir = join(tmpdir(), "triflux-codex-exec");
   mkdirSync(dir, { recursive: true });
   const resultFile = join(
@@ -142,7 +142,7 @@ async function runCodex(prompt, workdir, preflight, attempt) {
   );
   const command = commandWithOverrides(
     buildExecCommand(prompt, resultFile, {
-      profile: attempt.profile,
+      profile: lease?.profile ?? attempt.profile,
       skipGitRepoCheck: true,
       sandboxBypass: attempt.forceBypass,
     }),
@@ -150,12 +150,45 @@ async function runCodex(prompt, workdir, preflight, attempt) {
     preflight.codexPath,
     buildOverrides(attempt.requested, attempt.excluded),
   );
+  // PRD A1 — lease 메타데이터를 spawn env 에 적용한다. lease.authFile 이 있으면
+  // 해당 파일이 위치한 디렉토리를 CODEX_HOME 으로 export 해서 codex CLI 가 그
+  // account 의 auth.json 을 사용하게 한다. lease 가 null 이면 default ~/.codex
+  // 동작 유지 (회귀 없음). lease.env 는 추가 환경변수 (provider 고정 등) 주입용.
+  const spawnEnv = lease ? buildLeaseSpawnEnv(lease) : undefined;
   return runProcess(command, workdir, attempt.timeout, {
     resultFile,
     inferStallMode,
+    spawnEnv,
   });
 }
 
+function buildLeaseSpawnEnv(lease) {
+  const extra = {};
+  if (lease.authFile) {
+    // lease.authFile 은 보통 ~/.claude/cache/tfx-hub/codex-auth-<account>.json 형식.
+    // codex CLI 는 CODEX_HOME 을 통해 auth.json 위치를 결정하므로, 이 cache 파일을
+    // 직접 CODEX_HOME 후보 디렉토리로 사용한다. cache 파일 자체가 auth.json 이름이
+    // 아니라면 후속 PR 에서 isolated dir + symlink/복사 처리한다 (PRD Open Question).
+    // 현재는 lease.authFile 의 dirname 을 export 하되, 그 dirname 안에 auth.json 이
+    // 실제로 있을 때만 적용한다 (false-positive 회피).
+    try {
+      const dir = dirnameOf(lease.authFile);
+      if (dir) extra.CODEX_HOME = dir;
+    } catch {}
+  }
+  if (lease.env && typeof lease.env === "object") {
+    Object.assign(extra, lease.env);
+  }
+  return Object.keys(extra).length ? { ...process.env, ...extra } : undefined;
+}
+
+function dirnameOf(filePath) {
+  if (typeof filePath !== "string" || !filePath) return null;
+  const lastSep = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+  if (lastSep < 0) return null;
+  return filePath.slice(0, lastSep);
+}
+
 // ── Public API ──────────────────────────────────────────────────
 
 export async function getCircuitState() {

package/hub/gemini-adapter.mjs

@@ -113,7 +113,7 @@ export function buildExecArgs(opts = {}) {
 
 // ── Execution ───────────────────────────────────────────────────
 
-async function runGemini(prompt, workdir, preflight, attempt) {
+async function runGemini(prompt, workdir, preflight, attempt, lease) {
   const dir = join(tmpdir(), "triflux-gemini-exec");
   mkdirSync(dir, { recursive: true });
   const resultFile = join(
@@ -125,9 +125,16 @@ async function runGemini(prompt, workdir, preflight, attempt) {
     allowedMcpServers: attempt.allowedMcpServers,
     excludeMcpServers: attempt.excludeMcpServers,
   });
+  // PRD A1: lease.env 가 있으면 spawn env 에 적용 (예: GOOGLE_API_KEY 등 account-specific
+  // 환경변수). lease 가 null 이면 default 동작 유지 (부모 env inherit).
+  const spawnEnv =
+    lease?.env && typeof lease.env === "object"
+      ? { ...process.env, ...lease.env }
+      : undefined;
   return runProcess(command, workdir, attempt.timeout, {
     resultFile,
     inferStallMode,
+    spawnEnv,
   });
 }
 

package/hub/lib/trace-recorder.mjs

@@ -0,0 +1,153 @@
+const VALID_CLIENTS = new Set(["codex", "claude", "gemini", "unknown"]);
+const VALID_PHASES = new Set(["ingress", "handler", "store", "event-loop"]);
+const SAMPLE_LIMIT = 1000;
+
+const categories = new Map();
+const workerDurations = [];
+const workerCounts = {
+  spawned: 0,
+  exited: 0,
+};
+
+function debugInvalid(kind, details) {
+  if (process.env.TFX_TRACE_DEBUG !== "1") return;
+  console.debug(`[trace-recorder] ignored invalid ${kind}`, details);
+}
+
+function normalizeClient(client) {
+  const value = String(client || "unknown").toLowerCase();
+  return VALID_CLIENTS.has(value) ? value : "unknown";
+}
+
+function normalizePhase(phase) {
+  const value = String(phase || "handler");
+  return VALID_PHASES.has(value) ? value : "handler";
+}
+
+function validDuration(durMs) {
+  return Number.isFinite(durMs) && durMs >= 0;
+}
+
+function emptyStats() {
+  return {
+    count: 0,
+    total: 0,
+    min: null,
+    max: null,
+    samples: [],
+    phases: {},
+  };
+}
+
+function addDuration(stats, durMs, phase) {
+  stats.count += 1;
+  stats.total += durMs;
+  stats.min = stats.min == null ? durMs : Math.min(stats.min, durMs);
+  stats.max = stats.max == null ? durMs : Math.max(stats.max, durMs);
+  stats.samples.push(durMs);
+  if (stats.samples.length > SAMPLE_LIMIT) {
+    stats.samples.splice(0, stats.samples.length - SAMPLE_LIMIT);
+  }
+
+  const phaseStats = stats.phases[phase] || emptyPhaseStats();
+  phaseStats.count += 1;
+  phaseStats.total += durMs;
+  phaseStats.min =
+    phaseStats.min == null ? durMs : Math.min(phaseStats.min, durMs);
+  phaseStats.max =
+    phaseStats.max == null ? durMs : Math.max(phaseStats.max, durMs);
+  stats.phases[phase] = phaseStats;
+}
+
+function emptyPhaseStats() {
+  return { count: 0, total: 0, min: null, max: null };
+}
+
+function percentile(samples, percentileValue) {
+  if (!samples.length) return null;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const index = Math.ceil((percentileValue / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(sorted.length - 1, index))];
+}
+
+function publicStats(stats) {
+  return {
+    count: stats.count,
+    total: stats.total,
+    min: stats.min,
+    max: stats.max,
+    p50: percentile(stats.samples, 50),
+    p95: percentile(stats.samples, 95),
+    p99: percentile(stats.samples, 99),
+    phases: stats.phases,
+  };
+}
+
+export function recordRequest(
+  category,
+  durMs,
+  client = "unknown",
+  phase = "handler",
+) {
+  if (!category || typeof category !== "string") return;
+  if (!validDuration(durMs)) {
+    debugInvalid("request duration", { category, durMs, client, phase });
+    return;
+  }
+
+  const clientKey = normalizeClient(client);
+  const phaseKey = normalizePhase(phase);
+  const bucket = categories.get(category) || new Map();
+  const stats = bucket.get(clientKey) || emptyStats();
+  addDuration(stats, durMs, phaseKey);
+  bucket.set(clientKey, stats);
+  categories.set(category, bucket);
+}
+
+export function recordWorker(workerId, kind, command, durMs) {
+  if (!workerId || typeof workerId !== "string") return;
+  if (kind === "spawned") {
+    workerCounts.spawned += 1;
+    return;
+  }
+  if (kind !== "exited") return;
+
+  workerCounts.exited += 1;
+  if (durMs == null) return;
+  if (!validDuration(durMs)) {
+    debugInvalid("worker duration", { workerId, kind, command, durMs });
+    return;
+  }
+  workerDurations.push(durMs);
+  if (workerDurations.length > SAMPLE_LIMIT) {
+    workerDurations.splice(0, workerDurations.length - SAMPLE_LIMIT);
+  }
+}
+
+export function snapshot() {
+  const categorySnapshot = {};
+  for (const [category, bucket] of categories.entries()) {
+    categorySnapshot[category] = {};
+    for (const [client, stats] of bucket.entries()) {
+      categorySnapshot[category][client] = publicStats(stats);
+    }
+  }
+
+  return {
+    categories: categorySnapshot,
+    workers: {
+      spawned: workerCounts.spawned,
+      exited: workerCounts.exited,
+      p50: percentile(workerDurations, 50),
+      p95: percentile(workerDurations, 95),
+      p99: percentile(workerDurations, 99),
+    },
+  };
+}
+
+export function reset() {
+  categories.clear();
+  workerDurations.length = 0;
+  workerCounts.spawned = 0;
+  workerCounts.exited = 0;
+}