triflux 10.3.3 → 10.3.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.3.2",
+  "version": "10.3.4",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "author": {
     "name": "tellang"

package/hub/lib/path-utils.mjs

@@ -0,0 +1,167 @@
+// hub/lib/path-utils.mjs — Windows/POSIX 경로 변환 유틸리티
+
+import { platform } from 'node:os';
+
+/**
+ * Windows 경로를 Git Bash 스타일 POSIX 경로로 변환한다.
+ * C:\foo\bar → /c/foo/bar
+ * 이미 POSIX 경로면 그대로 반환.
+ * null/undefined → 빈 문자열
+ * @param {string|null|undefined} windowsPath
+ * @returns {string}
+ */
+export function toPosixPath(windowsPath) {
+  if (windowsPath == null) return '';
+  const p = String(windowsPath);
+  if (!p) return '';
+
+  // 이미 POSIX 경로 (/ 로 시작하거나 드라이브 레터 없음)
+  const winDriveMatch = p.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!winDriveMatch) {
+    // 백슬래시만 있는 상대 경로도 forward slash로 변환
+    return p.replace(/\\/g, '/');
+  }
+
+  const drive = winDriveMatch[1].toLowerCase();
+  const rest = winDriveMatch[2].replace(/\\/g, '/');
+  return `/${drive}/${rest}`;
+}
+
+/**
+ * POSIX 경로(Git Bash 스타일)를 Windows 경로로 변환한다.
+ * /c/foo/bar → C:\foo\bar
+ * 이미 Windows 경로면 그대로 반환.
+ * null/undefined → 빈 문자열
+ * @param {string|null|undefined} posixPath
+ * @returns {string}
+ */
+export function toWindowsPath(posixPath) {
+  if (posixPath == null) return '';
+  const p = String(posixPath);
+  if (!p) return '';
+
+  // 이미 Windows 경로
+  if (/^[A-Za-z]:/.test(p)) {
+    return p.replace(/\//g, '\\');
+  }
+
+  // Git Bash 스타일: /c/foo/bar
+  const gitBashMatch = p.match(/^\/([a-zA-Z])(\/.*)?$/);
+  if (gitBashMatch) {
+    const drive = gitBashMatch[1].toUpperCase();
+    const rest = gitBashMatch[2] ? gitBashMatch[2].replace(/\//g, '\\') : '\\';
+    return `${drive}:${rest}`;
+  }
+
+  return p;
+}
+
+/**
+ * 현재 OS에 맞게 경로를 정규화한다.
+ * win32: backslash, 그 외: forward slash
+ * @param {string|null|undefined} p
+ * @returns {string}
+ */
+export function normalizePath(p) {
+  if (p == null) return '';
+  const str = String(p);
+  if (process.platform === 'win32') {
+    return str.replace(/\//g, '\\');
+  }
+  return str.replace(/\\/g, '/');
+}
+
+/**
+ * 쉘 타입에 맞는 경로로 변환한다.
+ * @param {string|null|undefined} path
+ * @param {'git-bash'|'wsl'|'cmd'|'powershell'} shellType
+ * @returns {string}
+ */
+export function resolveShellPath(path, shellType) {
+  if (path == null) return '';
+  const p = String(path);
+
+  switch (shellType) {
+    case 'git-bash':
+      return toPosixPath(p);
+
+    case 'wsl': {
+      // Git Bash 경로를 먼저 Windows로 변환 후 WSL 형식으로
+      let winPath = /^[A-Za-z]:/.test(p) ? p : toWindowsPath(p);
+      const wslDriveMatch = winPath.match(/^([A-Za-z]):[/\\](.*)/);
+      if (wslDriveMatch) {
+        const drive = wslDriveMatch[1].toLowerCase();
+        const rest = wslDriveMatch[2].replace(/\\/g, '/');
+        return rest ? `/mnt/${drive}/${rest}` : `/mnt/${drive}`;
+      }
+      // 이미 /mnt/ 형식이면 그대로
+      if (p.startsWith('/mnt/')) return p;
+      return p.replace(/\\/g, '/');
+    }
+
+    case 'cmd':
+    case 'powershell':
+      return toWindowsPath(p);
+
+    default:
+      return p;
+  }
+}
+
+/**
+ * 환경 변수와 플랫폼 정보로 현재 쉘 타입을 추론한다.
+ * @returns {'git-bash'|'wsl'|'cmd'|'powershell'|'unix'}
+ */
+export function detectShellType() {
+  // WSL 감지: WSL_DISTRO_NAME 또는 WSLENV
+  if (process.env.WSL_DISTRO_NAME || process.env.WSLENV) {
+    return 'wsl';
+  }
+
+  // Windows 플랫폼
+  if (process.platform === 'win32') {
+    const shell = process.env.SHELL || '';
+    const term = process.env.TERM || '';
+    const msystem = process.env.MSYSTEM || '';
+
+    // Git Bash 감지: SHELL=/usr/bin/bash + MSYSTEM=MINGW64 등
+    if (
+      shell.includes('bash') ||
+      msystem.startsWith('MINGW') ||
+      msystem.startsWith('MSYS') ||
+      term === 'xterm'
+    ) {
+      return 'git-bash';
+    }
+
+    // PowerShell 감지
+    if (process.env.PSModulePath || process.env.PSHOME) {
+      return 'powershell';
+    }
+
+    return 'cmd';
+  }
+
+  // 비-Windows
+  return 'unix';
+}
+
+/**
+ * WSL 경로 여부를 확인한다 (/mnt/ 시작).
+ * @param {string|null|undefined} p
+ * @returns {boolean}
+ */
+export function isWslPath(p) {
+  if (p == null) return false;
+  return String(p).startsWith('/mnt/');
+}
+
+/**
+ * Git Bash 경로 여부를 확인한다 (/c/ 또는 /d/ 등 단일 소문자 드라이브 레터).
+ * @param {string|null|undefined} p
+ * @returns {boolean}
+ */
+export function isGitBashPath(p) {
+  if (p == null) return false;
+  return /^\/[a-zA-Z](\/|$)/.test(String(p));
+}

package/hub/team/runtime-strategy.mjs

@@ -0,0 +1,74 @@
+import {
+  createPsmuxSession,
+  killPsmuxSession,
+  psmuxSessionExists,
+} from "./psmux.mjs";
+
+/**
+ * @typedef {object} RuntimeStatus
+ * @property {string} name
+ * @property {string} sessionName
+ * @property {boolean} alive
+ */
+
+/**
+ * @typedef {object} TeamRuntime
+ * @property {(sessionName: string, opts?: object) => unknown} start
+ * @property {(sessionName: string) => void} stop
+ * @property {(sessionName: string) => boolean} isAlive
+ * @property {(sessionName: string) => RuntimeStatus} getStatus
+ */
+
+const defaultPsmuxAdapter = {
+  createSession: createPsmuxSession,
+  killSession: killPsmuxSession,
+  hasSession: psmuxSessionExists,
+};
+
+/**
+ * @param {{
+ *   createSession: typeof createPsmuxSession,
+ *   killSession: typeof killPsmuxSession,
+ *   hasSession: typeof psmuxSessionExists,
+ * }} [adapter]
+ * @returns {TeamRuntime & { name: "psmux" }}
+ */
+export function createPsmuxRuntime(adapter = defaultPsmuxAdapter) {
+  return {
+    name: "psmux",
+    start(sessionName, opts = {}) {
+      return adapter.createSession(sessionName, opts);
+    },
+    stop(sessionName) {
+      adapter.killSession(sessionName);
+    },
+    isAlive(sessionName) {
+      return adapter.hasSession(sessionName);
+    },
+    getStatus(sessionName) {
+      return {
+        name: "psmux",
+        sessionName,
+        alive: adapter.hasSession(sessionName),
+      };
+    },
+  };
+}
+
+/**
+ * @param {string} mode
+ * @returns {TeamRuntime & { name: string }}
+ */
+export function createRuntime(mode) {
+  const normalizedMode = String(mode || "").trim().toLowerCase();
+
+  if (normalizedMode === "psmux") {
+    return createPsmuxRuntime();
+  }
+
+  if (normalizedMode === "native" || normalizedMode === "wt") {
+    throw new Error(`Runtime mode "${normalizedMode}" is not implemented yet.`);
+  }
+
+  throw new Error(`Unsupported runtime mode: ${mode}`);
+}

package/hub/team/worktree-lifecycle.mjs

@@ -4,8 +4,8 @@
 // Remote support: host option → SSH-based git operations via remote-session.mjs.
 
 import { execFile } from 'node:child_process';
-import { resolve, normalize } from 'node:path';
-import { mkdir, rm, access } from 'node:fs/promises';
+import { resolve, normalize, join } from 'node:path';
+import { mkdir, rm, access, readdir } from 'node:fs/promises';
 import { remoteGit, validateHost } from './remote-session.mjs';
 
 const SWARM_ROOT = '.codex-swarm';
@@ -92,6 +92,10 @@ export async function ensureWorktree({ slug, runId, rootDir = process.cwd(), bas
     await git(['worktree', 'add', wtDir, branchName], rootDir);
   }
 
+  // #34 L2: worktree에 복사된 .claude-plugin 제거 (하네스가 PLUGIN_ROOT를 오인하는 것 방지)
+  const pluginDir = join(wtDir, '.claude-plugin');
+  try { await rm(pluginDir, { recursive: true, force: true }); } catch { /* absent → ok */ }
+
   return { worktreePath: normPath(wtDir), branchName, remote: false };
 }
 
@@ -192,6 +196,61 @@ export async function pruneWorktree({ worktreePath, branchName, rootDir = proces
   }
 }
 
+/**
+ * #34 L3: Detect and remove orphan worktree directories.
+ * Compares .codex-swarm/wt-* directories against `git worktree list`.
+ * Directories not registered as worktrees are removed.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir=process.cwd()]
+ * @returns {Promise<string[]>} removed directory names
+ */
+export async function pruneOrphanWorktrees({ rootDir = process.cwd() } = {}) {
+  const swarmDir = resolve(rootDir, SWARM_ROOT);
+  const removed = [];
+
+  let entries;
+  try {
+    entries = await readdir(swarmDir);
+  } catch {
+    return removed; // .codex-swarm/ doesn't exist → nothing to clean
+  }
+
+  const wtDirs = entries.filter(e => e.startsWith('wt-'));
+  if (wtDirs.length === 0) return removed;
+
+  // Get registered worktree paths from git
+  let registeredPaths;
+  try {
+    const raw = await git(['worktree', 'list', '--porcelain'], rootDir);
+    registeredPaths = new Set(
+      raw.split('\n')
+        .filter(l => l.startsWith('worktree '))
+        .map(l => normPath(l.slice('worktree '.length))),
+    );
+  } catch {
+    return removed; // git worktree list failed → don't remove anything
+  }
+
+  for (const dir of wtDirs) {
+    const fullPath = resolve(swarmDir, dir);
+    const normalized = normPath(fullPath);
+    if (!registeredPaths.has(normalized)) {
+      try {
+        await rm(fullPath, { recursive: true, force: true });
+        removed.push(dir);
+      } catch { /* best-effort */ }
+    }
+  }
+
+  // Prune stale git references
+  if (removed.length > 0) {
+    try { await git(['worktree', 'prune'], rootDir); } catch { /* best-effort */ }
+  }
+
+  return removed;
+}
+
 /**
  * Fetch a remote shard's branch to the local repo via SSH.
  * Workaround for hosts that cannot push to GitHub (e.g. Ultra4).

package/hud/hud-qos-status.mjs

@@ -16,6 +16,7 @@ import {
   readJson, readStdinJson, getProviderAccountId, getCliArgValue,
 } from "./utils.mjs";
 import { selectTier } from "./terminal.mjs";
+import { getMissionBoardState } from "./mission-board.mjs";
 
 // Claude provider
 import {
@@ -41,7 +42,7 @@ import {
 // Renderers
 import {
   getClaudeRows, getProviderRow, getTeamRow,
-  renderAlignedRows, getMicroLine,
+  renderAlignedRows, getMicroLine, renderMissionBoard,
   readLatestBenchmarkDiff, formatTokenSummary,
   readTokenSavings, readSvAccumulator,
 } from "./renderers.mjs";
@@ -103,11 +104,15 @@ async function main() {
   // 실측 데이터 추출
   const stdin = await stdinPromise;
   const contextView = buildContextUsageView(stdin, contextSnapshot);
+  const claudeUsage = claudeUsageSnapshot.isStale
+    ? { ...(claudeUsageSnapshot.data || {}), stale: true }
+    : claudeUsageSnapshot.data;
   const codexEmail = getCodexEmail();
   const geminiEmail = getGeminiEmail();
   const codexBuckets = codexSnapshot.buckets;
   const geminiSession = geminiSessionSnapshot.session;
   const geminiQuota = geminiQuotaSnapshot.quota;
+  const missionBoardState = await getMissionBoardState();
 
   // 누적 절약 데이터 읽기
   const svSavings = readTokenSavings();
@@ -149,7 +154,7 @@ async function main() {
 
   // nano tier: 1줄 모드 (극소 폭 또는 알림 배너 대응)
   if (CURRENT_TIER === "nano") {
-    const microLine = getMicroLine(contextView, claudeUsageSnapshot.data, codexBuckets,
+    const microLine = getMicroLine(contextView, claudeUsage, codexBuckets,
       geminiSession, geminiBucket, combinedSvPct);
     process.stdout.write(`\x1b[0m${microLine}\n`);
     return;
@@ -164,7 +169,7 @@ async function main() {
   };
 
   const rows = [
-    ...getClaudeRows(CURRENT_TIER, contextView, claudeUsageSnapshot.data, combinedSvPct),
+    ...getClaudeRows(CURRENT_TIER, contextView, claudeUsage, combinedSvPct),
     getProviderRow(CURRENT_TIER, "codex", "x", codexWhite, qosProfile, accountsConfig, accountsState,
       codexQuotaData, codexEmail, codexSv, null),
     getProviderRow(CURRENT_TIER, "gemini", "g", geminiBlue, qosProfile, accountsConfig, accountsState,
@@ -175,6 +180,15 @@ async function main() {
   const teamRow = getTeamRow(CURRENT_TIER);
   if (teamRow) rows.push(teamRow);
 
+  const missionBoard = renderMissionBoard(missionBoardState);
+  if (missionBoard) {
+    rows.push({
+      prefix: bold(claudeOrange("\u25B2")),
+      left: missionBoard,
+      right: "",
+    });
+  }
+
   // 최근 벤치마크 diff → 토큰 요약 행 추가
   const latestDiff = readLatestBenchmarkDiff();
   if (latestDiff) {

package/hud/mission-board.mjs

@@ -0,0 +1,53 @@
+// ============================================================================
+// HUD Mission Board — .omc/state/sessions/ 기반 에이전트 진행률 집계
+// ============================================================================
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SESSIONS_DIR = join(homedir(), ".omc", "state", "sessions");
+
+/**
+ * .omc/state/sessions/ 디렉토리를 읽어 팀 상태를 반환한다.
+ * @returns {{ agents: Array<{name: string, status: string, progress: number}>, dagLevel: number, totalProgress: number } | null}
+ */
+export async function getMissionBoardState(sessionsDir = SESSIONS_DIR) {
+  let entries;
+  try {
+    entries = await readdir(sessionsDir);
+  } catch {
+    return null;
+  }
+
+  const jsonFiles = entries.filter((f) => f.endsWith(".json"));
+  if (jsonFiles.length === 0) return null;
+
+  const agents = [];
+  for (const file of jsonFiles) {
+    let data;
+    try {
+      const raw = await readFile(join(sessionsDir, file), "utf8");
+      data = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+
+    const name = data.name ?? file.replace(/\.json$/, "");
+    const status = data.status ?? "idle";
+    const progress = typeof data.progress === "number" ? data.progress : 0;
+    agents.push({ name, status, progress });
+  }
+
+  if (agents.length === 0) return null;
+
+  const totalProgress = agents.length > 0
+    ? Math.round(agents.reduce((sum, a) => sum + a.progress, 0) / agents.length)
+    : 0;
+
+  return {
+    agents,
+    // TODO: derive dagLevel from real mission dependency metadata instead of hardcoding 0.
+    dagLevel: 0,
+    totalProgress,
+  };
+}

package/hud/providers/claude.mjs

@@ -16,6 +16,16 @@ import {
 import { readJson, writeJsonSafe, clampPercent, advanceToNextCycle } from "../utils.mjs";
 import { readContextMonitorSnapshot } from "../context-monitor.mjs";
 
+export const CLAUDE_USAGE_POLL_BASE_MS = 5_000;
+export const CLAUDE_USAGE_POLL_JITTER_RATIO = 0.2;
+export const CLAUDE_USAGE_RATE_LIMIT_BACKOFF_MS = [
+  CLAUDE_USAGE_POLL_BASE_MS,
+  10_000,
+  30_000,
+  60_000,
+  120_000,
+];
+
 // OMC 활성 여부에 따라 캐시 TTL 동적 결정
 function getClaudeUsageStaleMs() {
   return existsSync(OMC_PLUGIN_USAGE_CACHE_PATH)
@@ -23,6 +33,49 @@ function getClaudeUsageStaleMs() {
     : CLAUDE_USAGE_STALE_MS_SOLO;
 }
 
+export function computeClaudeUsagePollState({
+  consecutive429s = 0,
+  outcome = "success",
+  random = Math.random,
+  jitterRatio = CLAUDE_USAGE_POLL_JITTER_RATIO,
+} = {}) {
+  const current429s = Number.isFinite(consecutive429s) ? Math.max(0, consecutive429s) : 0;
+  const next429s = outcome === "rate_limit" ? current429s + 1 : 0;
+  const stepIndex = outcome === "rate_limit"
+    ? Math.min(next429s, CLAUDE_USAGE_RATE_LIMIT_BACKOFF_MS.length - 1)
+    : 0;
+  const baseDelayMs = CLAUDE_USAGE_RATE_LIMIT_BACKOFF_MS[stepIndex];
+  const sample = Number(random?.());
+  const normalized = Number.isFinite(sample) ? Math.min(1, Math.max(0, sample)) : 0.5;
+  const jitterFactor = 1 + ((normalized * 2) - 1) * jitterRatio;
+  return {
+    consecutive429s: next429s,
+    baseDelayMs,
+    delayMs: Math.max(1, Math.round(baseDelayMs * jitterFactor)),
+  };
+}
+
+function getSnapshotSchedule(cache) {
+  const timestamp = Number(cache?.timestamp);
+  const nextRefreshAt = Number(cache?.nextRefreshAt);
+  if (Number.isFinite(nextRefreshAt)) {
+    return {
+      nextRefreshAt,
+      shouldRefresh: Date.now() >= nextRefreshAt,
+    };
+  }
+
+  const ageMs = Number.isFinite(timestamp) ? Date.now() - timestamp : Number.MAX_SAFE_INTEGER;
+  const fallbackMs = cache?.error
+    ? (cache.errorType === "rate_limit" ? CLAUDE_USAGE_429_BACKOFF_MS : CLAUDE_USAGE_ERROR_BACKOFF_MS)
+    : getClaudeUsageStaleMs();
+
+  return {
+    nextRefreshAt: Number.isFinite(timestamp) ? timestamp + fallbackMs : null,
+    shouldRefresh: ageMs >= fallbackMs,
+  };
+}
+
 export function readClaudeCredentials() {
   const data = readJson(CLAUDE_CREDENTIALS_PATH, null);
   if (!data) return null;
@@ -154,18 +207,21 @@ export function stripStaleResets(data) {
 export function readClaudeUsageSnapshot() {
   const cache = readJson(CLAUDE_USAGE_CACHE_PATH, null);
   const ts = Number(cache?.timestamp);
-  const ageMs = Number.isFinite(ts) ? Date.now() - ts : Number.MAX_SAFE_INTEGER;
+  const schedule = getSnapshotSchedule(cache);
+  const staleBackoffActive = cache?.errorType === "rate_limit"
+    && Number.isFinite(schedule.nextRefreshAt)
+    && Date.now() < schedule.nextRefreshAt;
 
   // 1차: 자체 캐시에 유효 데이터가 있는 경우
   if (cache?.data) {
     // 에러 상태에서 보존된 stale 데이터 → backoff 존중하되 표시용 데이터 반환
     if (cache.error) {
-      const backoffMs = cache.errorType === "rate_limit"
-        ? CLAUDE_USAGE_429_BACKOFF_MS
-        : CLAUDE_USAGE_ERROR_BACKOFF_MS;
-      return { data: stripStaleResets(cache.data), shouldRefresh: ageMs >= backoffMs };
+      return {
+        data: stripStaleResets(cache.data),
+        shouldRefresh: schedule.shouldRefresh,
+        isStale: staleBackoffActive,
+      };
     }
-    const isFresh = ageMs < getClaudeUsageStaleMs();
     // resets_at이 지난 윈도우의 percent를 0으로 보정 (stale 캐시 방지)
     const data = { ...cache.data };
     const now = Date.now();
@@ -175,24 +231,21 @@ export function readClaudeUsageSnapshot() {
     if (data.weeklyResetsAt && new Date(data.weeklyResetsAt).getTime() <= now) {
       data.weeklyPercent = 0;
     }
-    return { data, shouldRefresh: !isFresh };
+    return { data, shouldRefresh: schedule.shouldRefresh, isStale: false };
   }
 
   // 2차: 에러 backoff — 최근 에러 시 재시도 억제 (무한 spawn 방지)
   if (cache?.error && Number.isFinite(ts)) {
-    const backoffMs = cache.errorType === "rate_limit"
-      ? CLAUDE_USAGE_429_BACKOFF_MS
-      : CLAUDE_USAGE_ERROR_BACKOFF_MS;
-    if (ageMs < backoffMs) {
+    if (!schedule.shouldRefresh) {
       const omcCache = readJson(OMC_PLUGIN_USAGE_CACHE_PATH, null);
       // OMC 캐시가 에러 이후 갱신되었으면 → 에러 캐시 덮어쓰고 그 데이터 사용
       if (omcCache?.data?.fiveHourPercent != null && omcCache.timestamp > ts) {
         writeClaudeUsageCache(omcCache.data);
-        return { data: omcCache.data, shouldRefresh: false };
+        return { data: omcCache.data, shouldRefresh: false, isStale: false };
       }
       // stale OMC fallback 또는 null (--% 플레이스홀더 표시, 가짜 0% 방지)
       const staleData = omcCache?.data?.fiveHourPercent != null ? stripStaleResets(omcCache.data) : null;
-      return { data: staleData, shouldRefresh: false };
+      return { data: staleData, shouldRefresh: false, isStale: staleBackoffActive };
     }
   }
 
@@ -203,23 +256,37 @@ export function readClaudeUsageSnapshot() {
     const omcAge = Number.isFinite(omcCache.timestamp) ? Date.now() - omcCache.timestamp : Number.MAX_SAFE_INTEGER;
     if (omcAge < OMC_CACHE_MAX_AGE_MS) {
       writeClaudeUsageCache(omcCache.data);
-      return { data: omcCache.data, shouldRefresh: omcAge > getClaudeUsageStaleMs() };
+      return { data: omcCache.data, shouldRefresh: omcAge > getClaudeUsageStaleMs(), isStale: false };
     }
     // stale이어도 data: null보다는 오래된 데이터를 fallback으로 표시
-    return { data: stripStaleResets(omcCache.data), shouldRefresh: true };
+    return { data: stripStaleResets(omcCache.data), shouldRefresh: true, isStale: false };
   }
 
   // 캐시/fallback 모두 없음: null 반환 → --% 플레이스홀더 + 리프레시 시도
-  return { data: null, shouldRefresh: true };
+  return { data: null, shouldRefresh: true, isStale: false };
 }
 
-export function writeClaudeUsageCache(data, errorInfo = null) {
+export function writeClaudeUsageCache(data, errorInfo = null, pollState = null) {
+  const state = pollState || (errorInfo
+    ? {
+      consecutive429s: errorInfo.type === "rate_limit" ? 1 : 0,
+      baseDelayMs: errorInfo.type === "rate_limit"
+        ? CLAUDE_USAGE_429_BACKOFF_MS
+        : CLAUDE_USAGE_ERROR_BACKOFF_MS,
+      delayMs: errorInfo.type === "rate_limit"
+        ? CLAUDE_USAGE_429_BACKOFF_MS
+        : CLAUDE_USAGE_ERROR_BACKOFF_MS,
+    }
+    : computeClaudeUsagePollState({ outcome: "success" }));
   const entry = {
     timestamp: Date.now(),
     data,
     error: !!errorInfo,
     errorType: errorInfo?.type || null,   // "rate_limit" | "auth" | "network" | "unknown"
     errorStatus: errorInfo?.status || null, // HTTP 상태 코드
+    consecutive429s: state.consecutive429s,
+    nextRefreshBaseMs: state.baseDelayMs,
+    nextRefreshAt: Date.now() + state.delayMs,
   };
   // 에러 시 기존 유효 데이터 보존 (--% n/a 방지)
   if (errorInfo && data == null) {
@@ -234,9 +301,11 @@ export function writeClaudeUsageCache(data, errorInfo = null) {
 
 export async function fetchClaudeUsage(forceRefresh = false) {
   const existingSnapshot = readClaudeUsageSnapshot();
-  if (!forceRefresh && !existingSnapshot.shouldRefresh && existingSnapshot.data) {
-    return existingSnapshot.data;
+  if (!forceRefresh && !existingSnapshot.shouldRefresh) {
+    return existingSnapshot.data || null;
   }
+  const cache = readJson(CLAUDE_USAGE_CACHE_PATH, null);
+  const consecutive429s = Number.isFinite(cache?.consecutive429s) ? cache.consecutive429s : 0;
   let creds = readClaudeCredentials();
   if (!creds) {
     writeClaudeUsageCache(null, { type: "auth", status: 0 });
@@ -262,11 +331,15 @@ export async function fetchClaudeUsage(forceRefresh = false) {
       : result.status === 401 || result.status === 403 ? "auth"
       : result.error === "timeout" || result.error === "network" ? "network"
       : "unknown";
-    writeClaudeUsageCache(existingSnapshot.data, { type: errorType, status: result.status });
+    const pollState = errorType === "rate_limit"
+      ? computeClaudeUsagePollState({ consecutive429s, outcome: "rate_limit" })
+      : null;
+    writeClaudeUsageCache(existingSnapshot.data, { type: errorType, status: result.status }, pollState);
     return existingSnapshot.data || null;
   }
   const usage = parseClaudeUsageResponse(result.data);
-  writeClaudeUsageCache(usage, usage ? null : { type: "unknown", status: 0 });
+  const pollState = usage ? computeClaudeUsagePollState({ outcome: "success" }) : null;
+  writeClaudeUsageCache(usage, usage ? null : { type: "unknown", status: 0 }, pollState);
   return usage;
 }
 
@@ -291,7 +364,7 @@ export function scheduleClaudeUsageRefresh() {
   try {
     if (existsSync(lockPath)) {
       const lockAge = Date.now() - readJson(lockPath, {}).t;
-      if (lockAge < 30000) return; // 30초 이내 스폰 이력 → 건너뜀
+      if (lockAge < 1000) return; // 짧은 중복 스폰만 억제, 실제 폴링 주기는 nextRefreshAt가 제어
     }
     writeJsonSafe(lockPath, { t: Date.now() });
   } catch { /* 락 실패 무시 — 스폰 진행 */ }

package/hud/renderers.mjs

@@ -122,6 +122,38 @@ export function getTeamRow(currentTier) {
   };
 }
 
+// ============================================================================
+// Mission Board 렌더러
+// ============================================================================
+
+const STATUS_ICON = {
+  active: "*",
+  idle: ".",
+  done: "+",
+  failed: "!",
+};
+
+/**
+ * Mission Board 상태를 1줄 compact 포맷으로 렌더링한다.
+ * 예: "MB: exec:+ ui:* perf:. [2/3 67%]"
+ * @param {{ agents: Array<{name: string, status: string, progress: number}>, dagLevel: number, totalProgress: number } | null} state
+ * @returns {string}
+ */
+export function renderMissionBoard(state) {
+  if (!state) return "";
+
+  const { agents, totalProgress } = state;
+  const done = agents.filter((a) => a.status === "done").length;
+  const total = agents.length;
+
+  const parts = agents.map((a) => {
+    const icon = STATUS_ICON[a.status] ?? "?";
+    return `${a.name}:${icon}`;
+  });
+
+  return `MB: ${parts.join(" ")} [${done}/${total} ${totalProgress}%]`;
+}
+
 // ============================================================================
 // 행 정렬 렌더링
 // ============================================================================
@@ -159,6 +191,7 @@ export function renderAlignedRows(rows) {
 // ============================================================================
 export function getMicroLine(contextView, claudeUsage, codexBuckets, geminiSession, geminiBucket, combinedSvPct) {
   const ctxView = contextView || buildContextUsageView({}, null);
+  const staleMarker = claudeUsage?.stale ? ` ${dim("[stale]")}` : "";
 
   // Claude 5h/1w
   const cF = claudeUsage?.fiveHourPercent != null ? clampPercent(claudeUsage.fiveHourPercent) : null;
@@ -198,7 +231,7 @@ export function getMicroLine(contextView, claudeUsage, codexBuckets, geminiSessi
     `${bold(codexWhite("x"))}${dim(":")}${xVal} ` +
     `${bold(geminiBlue("g"))}${dim(":")}${gVal} ` +
     `${dim("sv:")}${sv} ` +
-    `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
+    `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${staleMarker}`;
   return truncateAnsi(line, cols);
 }
 
@@ -208,6 +241,7 @@ export function getMicroLine(contextView, claudeUsage, codexBuckets, geminiSessi
 export function getClaudeRows(currentTier, contextView, claudeUsage, combinedSvPct) {
   const ctxView = contextView || buildContextUsageView({}, null);
   const prefix = `${bold(claudeOrange("c"))}:`;
+  const staleMarker = claudeUsage?.stale ? ` ${dim("[stale]")}` : "";
 
   // 절약 퍼센트
   const svStr = formatSvPct(combinedSvPct || 0);
@@ -235,25 +269,25 @@ export function getClaudeRows(currentTier, contextView, claudeUsage, combinedSvP
   if (currentTier === "nano" || currentTier === "micro") {
     const fShort = hasData && fiveHourPercent != null ? colorByProvider(fiveHourPercent, `${fiveHourPercent}%`, claudeOrange) : dim("--");
     const wShort = hasData && weeklyPercent != null ? colorByProvider(weeklyPercent, `${weeklyPercent}%`, claudeOrange) : dim("--");
-    const quotaSection = `${fShort}${dim("/")}${wShort}`;
+    const quotaSection = `${fShort}${dim("/")}${wShort}${staleMarker}`;
     return [{ prefix, left: quotaSection, right: "" }];
   }
 
   if (currentTier === "minimal") {
-    const quotaSection = `${dim("5h:")}${fStr} ${dim("1w:")}${wStr}`;
+    const quotaSection = `${dim("5h:")}${fStr} ${dim("1w:")}${wStr}${staleMarker}`;
     const right = `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
     return [{ prefix, left: quotaSection, right }];
   }
 
   if (currentTier === "compact") {
-    const quotaSection = `${dim("5h:")}${fStr} ${dim(fTime)} ${dim("1w:")}${wStr} ${dim(wTime)}`;
+    const quotaSection = `${dim("5h:")}${fStr} ${dim(fTime)} ${dim("1w:")}${wStr} ${dim(wTime)}${staleMarker}`;
     const warning = ctxView.warningTag ? ` ${dim("|")} ${yellow(ctxView.warningTag)}` : "";
     const contextSection = `${svSuffix} ${dim("|")} ${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${warning}`;
     return [{ prefix, left: quotaSection, right: contextSection }];
   }
 
   // full tier (>= 120 cols)
-  const quotaSection = `${dim("5h:")}${fBar}${fStr} ${dim(fTime)} ${dim("1w:")}${wBar}${wStr} ${dim(wTime)}`;
+  const quotaSection = `${dim("5h:")}${fBar}${fStr} ${dim(fTime)} ${dim("1w:")}${wBar}${wStr} ${dim(wTime)}${staleMarker}`;
   const warning = ctxView.warningTag ? ` ${dim("|")} ${yellow(ctxView.warningTag)}` : "";
   const contextSection = `${svSuffix} ${dim("|")} ${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${warning}`;
   return [{ prefix, left: quotaSection, right: contextSection }];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.3.3",
+  "version": "10.3.4",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/demo.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import childProcess from "node:child_process";
+import { parseArgs } from "node:util";
+
+const { values: flags } = parseArgs({
+  options: {
+    "dry-run": { type: "boolean", default: false },
+    keep: { type: "boolean", default: false },
+  },
+  strict: false,
+});
+
+const SESSION_NAME = "triflux-demo";
+
+const WORKERS = [
+  {
+    pane: 0,
+    agent: "codex",
+    messages: [
+      "[codex] Analyzing auth module...",
+      "[codex] Refactoring JWT validation...",
+      "[codex] Done ✓",
+    ],
+  },
+  {
+    pane: 1,
+    agent: "gemini",
+    messages: [
+      "[gemini] Reviewing UI components...",
+      "[gemini] Optimizing render cycle...",
+      "[gemini] Done ✓",
+    ],
+  },
+  {
+    pane: 2,
+    agent: "claude",
+    messages: [
+      "[claude] Security audit in progress...",
+      "[claude] Found 0 vulnerabilities",
+      "[claude] Done ✓",
+    ],
+  },
+];
+
+export function checkPsmux(opts = {}) {
+  if (opts.dryRun) return false;
+  try {
+    childProcess.execFileSync("psmux", ["-V"], { encoding: "utf8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createDemoSession(sessionName, opts = {}) {
+  if (opts.dryRun) {
+    console.log(`[dry-run] psmux new-session -d -s ${sessionName}`);
+    console.log(`[dry-run] psmux split-window -h -t ${sessionName}`);
+    console.log(`[dry-run] psmux split-window -h -t ${sessionName}`);
+    return;
+  }
+  childProcess.execFileSync("psmux", ["new-session", "-d", "-s", sessionName], { stdio: "pipe" });
+  childProcess.execFileSync("psmux", ["split-window", "-h", "-t", sessionName], { stdio: "pipe" });
+  childProcess.execFileSync("psmux", ["split-window", "-h", "-t", sessionName], { stdio: "pipe" });
+}
+
+export function simulateWorker(pane, agentName, messages, opts = {}) {
+  const sessionName = opts.sessionName || SESSION_NAME;
+  for (const msg of messages) {
+    const escapedMsg = msg.replace(/'/g, "'\\''");
+    if (opts.dryRun) {
+      console.log(`[dry-run] psmux send-keys -t ${sessionName}:0.${pane} "echo '${escapedMsg}'" Enter`);
+    } else {
+      childProcess.execFileSync(
+        "psmux",
+        ["send-keys", "-t", `${sessionName}:0.${pane}`, `echo '${escapedMsg}'`, "Enter"],
+        { stdio: "pipe" },
+      );
+    }
+  }
+}
+
+export function showSummary() {
+  const lines = [
+    "",
+    "=== triflux demo summary ===",
+    "  codex  → JWT auth refactor    [done]",
+    "  gemini → UI render optimize   [done]",
+    "  claude → Security audit       [done]",
+    "============================",
+    "",
+  ];
+  for (const line of lines) {
+    console.log(line);
+  }
+}
+
+export function cleanup(sessionName, opts = {}) {
+  if (opts.dryRun) {
+    console.log(`[dry-run] psmux kill-session -t ${sessionName}`);
+    return;
+  }
+  try {
+    childProcess.execFileSync("psmux", ["kill-session", "-t", sessionName], { stdio: "pipe" });
+  } catch {
+    // session may already be gone
+  }
+}
+
+async function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main() {
+  const { values: flags } = parseArgs({
+    options: {
+      "dry-run": { type: "boolean", default: false },
+      keep: { type: "boolean", default: false },
+    },
+    strict: false,
+  });
+
+  const psmuxAvailable = checkPsmux({ dryRun: flags["dry-run"] });
+  const dryRun = flags["dry-run"] || !psmuxAvailable;
+
+  if (!psmuxAvailable && !flags["dry-run"]) {
+    console.log("[demo] psmux not found — switching to dry-run mode");
+  }
+
+  const opts = {
+    dryRun,
+    keep: flags.keep,
+    sessionName: SESSION_NAME,
+  };
+
+  createDemoSession(SESSION_NAME, opts);
+
+  for (const { pane, agent, messages } of WORKERS) {
+    simulateWorker(pane, agent, messages, opts);
+  }
+
+  if (!opts.dryRun) {
+    await wait(2000);
+  }
+  
+  showSummary();
+
+  if (!opts.keep) {
+    cleanup(SESSION_NAME, opts);
+  }
+}
+
+// Only run main when executed directly (not imported as a module)
+// Normalize both paths to forward-slash for cross-platform comparison
+function isDirectExec() {
+  if (!process.argv[1]) return false;
+  const scriptPath = new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1");
+  const argv1 = process.argv[1].replace(/\\/g, "/");
+  const norm = scriptPath.replace(/\\/g, "/");
+  return argv1 === norm || argv1.endsWith(norm);
+}
+
+if (isDirectExec()) {
+  main().catch((err) => {
+    console.error("demo error:", err.message);
+    process.exit(1);
+  });
+}

package/scripts/headless-guard.mjs

@@ -202,8 +202,12 @@ async function main() {
     // codex/gemini 직접 CLI 호출 → deny (인라인 TFX_ALLOW_DIRECT_CLI=1 우회 허용)
     // 복합 명령(&&, ||, ;, |) 분리 후 각 세그먼트의 커맨드 위치만 검사 (args/quotes 안의 codex는 무시)
     // NOTE: || 는 | 보다 먼저 매칭되므로 logical OR이 단일 pipe로 잘못 분리되지 않음
+    // #37 Bug4: gh/git 명령은 본문에 codex/gemini 문자열이 있어도 차단하지 않음
+    const SAFE_CMD_RE = /^\s*(?:[\w_]+=\S+\s+)*\s*(gh|git)\b/;
     const cmdParts = cmd.split(/\s*(?:&&|\|\||\||;)\s*/);
     let hasDirectCli = cmdParts.some(part => {
+      // gh/git 세그먼트는 건너뜀 (이슈 본문/커밋 메시지 내 codex/gemini 언급은 정상)
+      if (SAFE_CMD_RE.test(part)) return false;
       // 1단계: env var prefix 제거 (FOO=bar ...)
       // 2단계: wrapper prefix 제거 (env, command, nohup, timeout N, 절대경로, bash -c/-lc "...")
       const stripped = part
@@ -216,11 +220,19 @@ async function main() {
     });
     // 2차 휴리스틱: 1차 세그먼트 검사를 통과한 간접 실행 패턴 탐지
     // full AST 파서 대신 현실적 위협 벡터만 커버 — eval, subshell, variable 확장
+    // 2차 휴리스틱: 간접 실행 패턴 탐지 (eval, subshell, variable 확장)
     if (!hasDirectCli) {
-      hasDirectCli = (
-        /\beval\b.*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(cmd) ||
-        /\$[({].*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(cmd)
-      );
+      const isAllSafeCmd = cmdParts.every(p => SAFE_CMD_RE.test(p));
+      if (isAllSafeCmd) {
+        // gh/git 전용: $(codex exec ...) 직접 명령 치환만 차단
+        // $(cat <<'EOF'\n...codex exec text...\nEOF) 같은 heredoc 텍스트는 허용
+        hasDirectCli = /\$\(\s*(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(cmd);
+      } else {
+        hasDirectCli = (
+          /\beval\b.*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(cmd) ||
+          /\$[({].*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(cmd)
+        );
+      }
     }
 
     if (hasDirectCli) {

package/scripts/lib/skill-state.mjs

@@ -0,0 +1,220 @@
+import {
+  access,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, join } from "node:path";
+
+const DEFAULT_STATE_DIR = join(process.cwd(), ".tfx", "state");
+const STOP_HOOKS = new Map();
+
+function stateFilePath(stateDir, skillName) {
+  return join(stateDir, `${skillName}-active.json`);
+}
+
+function assertValidSkillName(skillName) {
+  if (basename(skillName) !== skillName) {
+    throw new Error(`Invalid skill name: ${skillName}`);
+  }
+}
+
+function assertValidOnStop(onStop) {
+  if (onStop !== undefined && typeof onStop !== "function") {
+    throw new TypeError("onStop must be a function");
+  }
+}
+
+async function readStateFile(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function rememberStopHook(filePath, onStop) {
+  if (typeof onStop === "function") {
+    STOP_HOOKS.set(filePath, onStop);
+    return;
+  }
+  STOP_HOOKS.delete(filePath);
+}
+
+function logStopHookWarning(message, error) {
+  if (error) {
+    console.warn(message, error);
+    return;
+  }
+  console.warn(message);
+}
+
+async function runStopHook(filePath, state, onStop) {
+  if (!state?.hasStopHook) {
+    STOP_HOOKS.delete(filePath);
+    return;
+  }
+
+  const hook = onStop ?? STOP_HOOKS.get(filePath);
+  STOP_HOOKS.delete(filePath);
+
+  if (typeof hook !== "function") {
+    return;
+  }
+
+  try {
+    await hook({
+      skillName: state.skillName,
+      filePath,
+      state,
+    });
+  } catch (error) {
+    logStopHookWarning(
+      `Failed to run stop-hook for skill: ${state.skillName}`,
+      error,
+    );
+  }
+}
+
+/**
+ * Activate a skill by writing its state file.
+ * Throws if the skill is already active.
+ *
+ * @param {string} skillName
+ * @param {{ stateDir?: string, onStop?: (() => Promise<void> | void) }} options
+ */
+export async function activateSkill(
+  skillName,
+  { stateDir = DEFAULT_STATE_DIR, onStop } = {},
+) {
+  assertValidSkillName(skillName);
+  assertValidOnStop(onStop);
+
+  await mkdir(stateDir, { recursive: true });
+
+  const filePath = stateFilePath(stateDir, skillName);
+  const lockPath = `${filePath}.lock`;
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let lockHandle;
+
+  try {
+    lockHandle = await open(lockPath, "wx");
+    try {
+      await access(filePath);
+      throw new Error(`Skill already active: ${skillName}`);
+    } catch (error) {
+      if (error?.message === `Skill already active: ${skillName}`) {
+        throw error;
+      }
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    const state = {
+      skillName,
+      pid: process.pid,
+      activatedAt: Date.now(),
+      hasStopHook: typeof onStop === "function",
+    };
+    await writeFile(tmpPath, JSON.stringify(state), "utf8");
+    await rename(tmpPath, filePath);
+    rememberStopHook(filePath, onStop);
+  } finally {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    if (lockHandle) {
+      await lockHandle.close().catch(() => {});
+    }
+    await rm(lockPath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Deactivate a skill by removing its state file.
+ * Does not throw if the file does not exist.
+ *
+ * @param {string} skillName
+ * @param {{ stateDir?: string, onStop?: (() => Promise<void> | void) }} options
+ */
+export async function deactivateSkill(
+  skillName,
+  { stateDir = DEFAULT_STATE_DIR, onStop } = {},
+) {
+  assertValidOnStop(onStop);
+
+  const filePath = stateFilePath(stateDir, skillName);
+  const state = await readStateFile(filePath);
+
+  try {
+    await runStopHook(filePath, state, onStop);
+  } finally {
+    STOP_HOOKS.delete(filePath);
+    await rm(filePath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Return all currently active skills by scanning *-active.json files.
+ *
+ * @param {{ stateDir?: string }} options
+ * @returns {Promise<Array<{ skillName: string, pid: number, activatedAt: number, hasStopHook?: boolean }>>}
+ */
+export async function getActiveSkills({ stateDir = DEFAULT_STATE_DIR } = {}) {
+  let entries;
+  try {
+    entries = await readdir(stateDir);
+  } catch {
+    return [];
+  }
+
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.endsWith("-active.json")) continue;
+    const state = await readStateFile(join(stateDir, entry));
+    if (state) {
+      results.push(state);
+    }
+  }
+  return results;
+}
+
+/**
+ * Remove state files for skills whose processes are no longer alive.
+ *
+ * @param {{ stateDir?: string }} options
+ * @returns {Promise<string[]>} list of pruned skill names
+ */
+export async function pruneOrphanSkillStates({
+  stateDir = DEFAULT_STATE_DIR,
+} = {}) {
+  const active = await getActiveSkills({ stateDir });
+  const pruned = [];
+
+  for (const state of active) {
+    let alive = true;
+    try {
+      process.kill(state.pid, 0);
+    } catch {
+      alive = false;
+    }
+
+    if (!alive) {
+      const filePath = stateFilePath(stateDir, state.skillName);
+      STOP_HOOKS.delete(filePath);
+      if (state.hasStopHook) {
+        logStopHookWarning(
+          `Skipping stop-hook for orphaned skill state: ${state.skillName}`,
+        );
+      }
+      await rm(filePath, { force: true }).catch(() => {});
+      pruned.push(state.skillName);
+    }
+  }
+
+  return pruned;
+}