triflux 4.2.8 → 4.2.10

package/hub/middleware/request-logger.mjs

@@ -0,0 +1,81 @@
+/**
+ * Hub HTTP 서버 요청 로깅 미들웨어.
+ *
+ * raw http.createServer에 맞춘 래퍼. Express가 아닌 triflux Hub 전용.
+ *
+ * 사용법 (server.mjs에서):
+ *   import { wrapRequestHandler } from './middleware/request-logger.mjs';
+ *   const httpServer = createHttpServer(wrapRequestHandler(originalHandler));
+ *
+ * 각 요청에 correlationId를 할당하고, 응답 완료 시 구조화 로그를 남긴다.
+ * health/status 체크는 로깅을 건너뛴다.
+ */
+import { withRequestContext, getCorrelationId } from '../../scripts/lib/context.mjs';
+import { createModuleLogger } from '../../scripts/lib/logger.mjs';
+
+const log = createModuleLogger('hub');
+
+const SKIP_PATHS = new Set(['/health', '/healthz', '/status', '/ready']);
+
+/**
+ * 원본 request handler를 래핑하여 로깅 + 컨텍스트 전파를 추가한다.
+ *
+ * @param {function(import('http').IncomingMessage, import('http').ServerResponse): void} handler
+ * @returns {function(import('http').IncomingMessage, import('http').ServerResponse): void}
+ */
+export function wrapRequestHandler(handler) {
+  return (req, res) => {
+    const path = getRequestPath(req.url);
+
+    if (SKIP_PATHS.has(path)) {
+      return handler(req, res);
+    }
+
+    const correlationId =
+      req.headers['x-correlation-id'] ||
+      req.headers['x-request-id'] ||
+      undefined; // withRequestContext will generate one
+
+    withRequestContext(
+      {
+        correlationId,
+        method: req.method,
+        path,
+      },
+      () => {
+        const startTime = process.hrtime.bigint();
+
+        // 응답 헤더에 상관 ID 포함
+        const cid = getCorrelationId();
+        if (cid) res.setHeader('X-Correlation-ID', cid);
+
+        // 응답 완료 시 로깅
+        res.on('finish', () => {
+          const duration = Number(process.hrtime.bigint() - startTime) / 1_000_000;
+          const level = res.statusCode >= 500 ? 'error'
+            : res.statusCode >= 400 ? 'warn'
+            : 'info';
+
+          log[level](
+            {
+              status: res.statusCode,
+              duration: Math.round(duration * 100) / 100,
+              contentLength: res.getHeader('content-length') || 0,
+            },
+            'http.response',
+          );
+        });
+
+        handler(req, res);
+      },
+    );
+  };
+}
+
+function getRequestPath(url = '/') {
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname;
+  } catch {
+    return String(url).replace(/\?.*/, '') || '/';
+  }
+}

package/hub/server.mjs

@@ -19,6 +19,10 @@ import { createTools } from './tools.mjs';
 import { ensurePipelineStateDbPath } from './pipeline/state.mjs';
 import { DelegatorService } from './delegator/index.mjs';
 import { createDelegatorMcpWorker } from './workers/delegator-mcp.mjs';
+import { createModuleLogger } from '../scripts/lib/logger.mjs';
+import { wrapRequestHandler } from './middleware/request-logger.mjs';
+
+const hubLog = createModuleLogger('hub');
 
 const MAX_BODY_SIZE = 1024 * 1024;
 const PUBLIC_PATHS = new Set(['/', '/status', '/health', '/healthz']);
@@ -230,7 +234,7 @@ function servePublicFile(res, path) {
 
   mkdirSync(PUBLIC_DIR, { recursive: true });
   if (!existsSync(filePath)) {
-    console.warn(`[tfx-hub] 정적 파일 없음: ${filePath}`);
+    hubLog.warn({ filePath }, 'static.not_found');
     res.writeHead(404);
     res.end('Not Found (static file missing)');
     return true;
@@ -326,7 +330,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
     return mcp;
   }
 
-  const httpServer = createHttpServer(async (req, res) => {
+  const httpServer = createHttpServer(wrapRequestHandler(async (req, res) => {
     const path = getRequestPath(req.url);
     const corsAllowed = applyCorsHeaders(req, res);
 
@@ -685,7 +689,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         res.end('Method Not Allowed');
       }
     } catch (error) {
-      console.error('[tfx-hub] 요청 처리 에러:', error.message);
+      hubLog.error({ err: error }, 'http.error');
       if (!res.headersSent) {
         const code = error.statusCode === 413 ? 413
           : error instanceof SyntaxError ? 400 : 500;
@@ -699,7 +703,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         }));
       }
     }
-  });
+  }));
 
   router.startSweeper();
 
@@ -751,8 +755,8 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         started: Date.now(),
       }));
 
-      console.log(`[tfx-hub] MCP 서버 시작: ${info.url} / pipe ${pipe.path} / assign-callback ${assignCallbacks.path} (PID ${process.pid})`);
-      console.log(`[tfx-hub] PUBLIC_DIR: ${PUBLIC_DIR} (exists: ${existsSync(PUBLIC_DIR)}, dashboard: ${existsSync(resolve(PUBLIC_DIR, 'dashboard.html'))})`);
+      hubLog.info({ url: info.url, pipePath: pipe.path, assignCallbackPath: assignCallbacks.path, pid: process.pid }, 'hub.started');
+      hubLog.debug({ publicDir: PUBLIC_DIR, exists: existsSync(PUBLIC_DIR), hasDashboard: existsSync(resolve(PUBLIC_DIR, 'dashboard.html')) }, 'hub.public_dir');
 
       const stopFn = async () => {
         router.stopSweeper();
@@ -805,14 +809,14 @@ if (selfRun) {
 
   startHub({ port, dbPath }).then((info) => {
     const shutdown = async (signal) => {
-      console.log(`\n[tfx-hub] ${signal} 수신, 종료 중...`);
+      hubLog.info({ signal }, 'hub.stopping');
       await info.stop();
       process.exit(0);
     };
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
   }).catch((error) => {
-    console.error('[tfx-hub] 시작 실패:', error.message);
+    hubLog.fatal({ err: error }, 'hub.start_failed');
     process.exit(1);
   });
 }

package/hub/team/native.mjs

@@ -126,9 +126,10 @@ function getRouteTimeout(role, _mcpProfile) {
 }
 
 /**
- * v2.2 슬림 래퍼 프롬프트 생성
- * Agent spawn으로 네비게이션에 등록하되, 실제 작업은 tfx-route.sh가 수행.
- * 프롬프트 ~100 토큰 목표 (v2의 ~500 대비 80% 감소).
+ * v3 슬림 래퍼 프롬프트 생성 (async 모드)
+ * --async로 즉시 시작 → --job-wait로 내부 폴링 → --job-result로 결과 수집.
+ * Claude Code Bash 도구 600초 제한을 우회하여 scientist(24분), scientist-deep(60분) 등
+ * 장시간 워커를 안정적으로 실행한다.
  *
  * @param {'codex'|'gemini'} cli — CLI 타입
  * @param {object} opts
@@ -141,7 +142,7 @@ function getRouteTimeout(role, _mcpProfile) {
  * @param {string} [opts.mcp_profile] — MCP 프로필
  * @param {number} [opts.workerIndex] — 검색 힌트 회전에 사용할 워커 인덱스(1-based)
  * @param {string} [opts.searchTool] — 전용 검색 도구 힌트(brave-search|tavily|exa)
- * @param {number} [opts.bashTimeout] — Bash timeout(ms). 미지정 시 role/profile 기반 자동 산출.
+ * @param {number} [opts.bashTimeout] — (deprecated, async에서는 무시됨)
  * @returns {string} 슬림 래퍼 프롬프트
  */
 export function buildSlimWrapperPrompt(cli, opts = {}) {
@@ -156,23 +157,25 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     workerIndex,
     searchTool = "",
     pipelinePhase = "",
-    bashTimeout,
   } = opts;
 
-  // role/profile 기반 timeout 산출 (기본 timeout + 60초 여유, ms 변환)
-  const bashTimeoutMs = bashTimeout ?? (getRouteTimeout(role, mcp_profile) + 60) * 1000;
-
-  // 셸 이스케이프
+  const routeTimeoutSec = getRouteTimeout(role, mcp_profile);
   const escaped = subtask.replace(/'/g, "'\\''");
   const pipelineHint = pipelinePhase
     ? `\n파이프라인 단계: ${pipelinePhase}`
     : '';
   const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
 
-  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}"):
-1. Bash(command, timeout: ${bashTimeoutMs}) — 아래 명령 1회만 실행
-2. Bash 종료 후 TaskUpdate + SendMessage로 Claude Code 태스크 동기화
-3. 종료${pipelineHint}
+  // Bash 도구 timeout (모두 600초 이내)
+  const launchTimeoutMs = 15000;   // Step 1: fork + job_id 반환
+  const waitTimeoutMs = 570000;    // Step 2: 내부 폴링 (540초 대기 + 여유)
+  const resultTimeoutMs = 30000;   // Step 3: 결과 읽기
+
+  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async):
+1. --async로 백그라운드 시작 → JOB_ID 수신
+2. --job-wait로 완료 대기 (내부 15초 간격 폴링, 최대 540초)
+3. "still_running"이면 Step 2 반복, "done"이면 --job-result로 결과 수집
+4. TaskUpdate + SendMessage → 종료${pipelineHint}
 
 [HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
 Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
@@ -182,21 +185,33 @@ Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
 
-Step 1 — Bash 실행:
-Bash(command: 'TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}"${routeEnvPrefix} bash ${ROUTE_SCRIPT} "${role}" '"'"'${escaped}'"'"' ${mcp_profile}', timeout: ${bashTimeoutMs})
+Step 1 — Async 시작 (즉시 리턴, <1초):
+Bash(command: 'TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}"${routeEnvPrefix} bash ${ROUTE_SCRIPT} --async "${role}" '"'"'${escaped}'"'"' ${mcp_profile} ${routeTimeoutSec}', timeout: ${launchTimeoutMs})
+→ 출력 한 줄이 JOB_ID이다. 반드시 기억하라.
+
+Step 2 — 완료 대기 (내부 폴링, 최대 540초):
+Bash(command: 'bash ${ROUTE_SCRIPT} --job-wait JOB_ID 540', timeout: ${waitTimeoutMs})
+→ 주기적 "waiting elapsed=Ns progress=NB" 출력 후 최종 상태:
+  "done" → Step 3으로
+  "timeout" 또는 "failed ..." → Step 4로 (실패 보고)
+  "still_running ..." → Step 2 반복 (같은 명령 재실행)
+
+Step 3 — 결과 수집:
+Bash(command: 'bash ${ROUTE_SCRIPT} --job-result JOB_ID', timeout: ${resultTimeoutMs})
+→ 출력이 워커 실행 결과이다.
 
-Step 2 — Claude Code 태스크 동기화 (Bash 완료 후 반드시 실행):
-exit_code=0이면:
+Step 4 — Claude Code 태스크 동기화 (반드시 실행):
+"done"이면:
   TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"})
   SendMessage(type: "message", recipient: "${leadName}", content: "완료: ${agentName}", summary: "task ${taskId} success")
-exit_code≠0이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "exit_code=N"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (exit=N)", summary: "task ${taskId} failed")
+"timeout" 또는 "failed"이면:
+  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "상태 메시지"})
+  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (상태)", summary: "task ${taskId} failed")
 TFX_NEEDS_FALLBACK 출력 감지 시:
   TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "fallback", reason: "claude-native"})
   SendMessage(type: "message", recipient: "${leadName}", content: "fallback 필요: ${agentName} — claude-native 역할은 Claude Agent로 위임 필요", summary: "task ${taskId} fallback")
 
-Step 3 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
+Step 5 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
 }
 
 /**

package/hud/hud-qos-status.mjs

@@ -151,12 +151,33 @@ function getGeminiRpmLimit(model) {
   return 300; // Flash 기본
 }
 
-// Gemini 모델 ID → HUD 표시 라벨
+// Gemini 모델 ID → HUD 표시 라벨 (동적 매핑)
 function getGeminiModelLabel(model) {
   if (!model) return "";
-  if (model.includes("pro")) return "[Pro3.1]";
-  if (model.includes("flash")) return "[Flash3]";
-  return "";
+  // 버전 + 티어 추출: gemini-3.1-pro-preview → [3.1Pro], gemini-2.5-flash → [2.5Flash]
+  const m = model.match(/gemini-(\d+(?:\.\d+)?)-(\w+)/);
+  if (!m) return "";
+  const ver = m[1];
+  const tier = m[2].charAt(0).toUpperCase() + m[2].slice(1);
+  return `[${ver}${tier}]`;
+}
+
+// Gemini Pro 풀 공유 그룹: 같은 remainingFraction을 공유하는 모델 ID들
+const GEMINI_PRO_POOL = new Set(["gemini-2.5-pro", "gemini-3-pro-preview", "gemini-3.1-pro-preview"]);
+const GEMINI_FLASH_POOL = new Set(["gemini-2.5-flash", "gemini-3-flash-preview"]);
+
+// remainingFraction → 사용 퍼센트 변환 (remainingAmount가 있으면 절대값도 제공)
+function deriveGeminiLimits(bucket) {
+  if (!bucket || bucket.remainingFraction == null) return null;
+  const fraction = bucket.remainingFraction;
+  const usedPct = clampPercent(Math.round((1 - fraction) * 100));
+  // remainingAmount가 API에서 오면 절대값 역산 (Gemini CLI 방식)
+  if (bucket.remainingAmount != null) {
+    const remaining = parseInt(bucket.remainingAmount, 10);
+    const limit = fraction > 0 ? Math.round(remaining / fraction) : 0;
+    return { usedPct, remaining, limit, resetTime: bucket.resetTime, modelId: bucket.modelId };
+  }
+  return { usedPct, remaining: null, limit: null, resetTime: bucket.resetTime, modelId: bucket.modelId };
 }
 // rows 임계값 상수 (selectTier 에서 tier 결정에 사용)
 const ROWS_BUDGET_FULL = 40;
@@ -493,10 +514,11 @@ function getMicroLine(stdin, claudeUsage, codexBuckets, geminiSession, geminiBuc
     }
   }
 
-  // Gemini
+  // Gemini (일간 쿼터 — P/F/L 3풀)
   let gVal;
   if (geminiBucket) {
-    const gU = clampPercent(geminiBucket.usedPercent ?? 0);
+    const gl = deriveGeminiLimits(geminiBucket);
+    const gU = gl ? gl.usedPct : clampPercent((1 - (geminiBucket.remainingFraction ?? 1)) * 100);
     gVal = colorByProvider(gU, `${gU}`, geminiBlue);
   } else if ((geminiSession?.total || 0) > 0) {
     gVal = geminiBlue("\u221E");
@@ -536,7 +558,7 @@ function normalizeTimeToken(value) {
   }
   const dayHour = text.match(/^(\d+)d(\d+)h$/);
   if (dayHour) {
-    return `${Number(dayHour[1])}d${String(Number(dayHour[2])).padStart(2, "0")}h`;
+    return `${String(Number(dayHour[1])).padStart(2, "0")}d${String(Number(dayHour[2])).padStart(2, "0")}h`;
   }
   return text;
 }
@@ -923,7 +945,7 @@ function formatResetRemainingDayHour(isoOrUnix, cycleMs = 0) {
   const totalMinutes = Math.floor(diffMs / 60000);
   const days = Math.floor(totalMinutes / (60 * 24));
   const hours = Math.floor((totalMinutes % (60 * 24)) / 60);
-  return `${days}d${hours}h`;
+  return `${String(days).padStart(2, "0")}d${String(hours).padStart(2, "0")}h`;
 }
 
 function calcCooldownLeftSeconds(isoDatetime) {
@@ -1511,13 +1533,16 @@ function getProviderRow(provider, marker, markerColor, qosProfile, accountsConfi
       }
     }
     if (realQuota?.type === "gemini") {
-      const bucket = realQuota.quotaBucket;
-      if (bucket) {
-        const usedP = clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
-        return { prefix: minPrefix, left: `${colorByProvider(usedP, `${usedP}%`, provFn)}${dim("/")}${dim("\u221E%")}`, right: "" };
+      const pools = realQuota.pools || {};
+      if (pools.pro || pools.flash) {
+        const pP = pools.pro ? clampPercent(Math.round((1 - (pools.pro.remainingFraction ?? 1)) * 100)) : null;
+        const pF = pools.flash ? clampPercent(Math.round((1 - (pools.flash.remainingFraction ?? 1)) * 100)) : null;
+        const pStr = pP != null ? colorByProvider(pP, `${pP}`, provFn) : dim("--");
+        const fStr = pF != null ? colorByProvider(pF, `${pF}`, provFn) : dim("--");
+        return { prefix: minPrefix, left: `${pStr}${dim("/")}${fStr}`, right: "" };
       }
     }
-    return { prefix: minPrefix, left: dim("--%/--%"), right: "" };
+    return { prefix: minPrefix, left: dim("--/--"), right: "" };
   }
 
   if (CURRENT_TIER === "minimal") {
@@ -1532,12 +1557,17 @@ function getProviderRow(provider, marker, markerColor, qosProfile, accountsConfi
       }
     }
     if (realQuota?.type === "gemini") {
-      const bucket = realQuota.quotaBucket;
-      if (bucket) {
-        const usedP = clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
-        quotaSection = `${dim("1d:")}${colorByProvider(usedP, formatPercentCell(usedP), provFn)} ${dim("1w:")}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))}`;
+      const pools = realQuota.pools || {};
+      if (pools.pro || pools.flash) {
+        const slot = (bucket, label) => {
+          if (!bucket) return `${dim(label + ":")}${dim(formatPlaceholderPercentCell())}`;
+          const gl = deriveGeminiLimits(bucket);
+          const usedP = gl ? gl.usedPct : clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
+          return `${dim(label + ":")}${colorByProvider(usedP, formatPercentCell(usedP), provFn)}`;
+        };
+        quotaSection = `${slot(pools.pro, "Pr")} ${slot(pools.flash, "Fl")}`;
       } else {
-        quotaSection = `${dim("1d:")}${dim("--%".padStart(PERCENT_CELL_WIDTH))} ${dim("1w:")}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))}`;
+        quotaSection = `${dim("Pr:")}${dim(formatPlaceholderPercentCell())} ${dim("Fl:")}${dim(formatPlaceholderPercentCell())}`;
       }
     }
     if (!quotaSection) {
@@ -1561,17 +1591,23 @@ function getProviderRow(provider, marker, markerColor, qosProfile, accountsConfi
       }
     }
     if (realQuota?.type === "gemini") {
-      const bucket = realQuota.quotaBucket;
-      if (bucket) {
-        const usedP = clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
-        const rstRemaining = formatResetRemaining(bucket.resetTime, ONE_DAY_MS) || "n/a";
-        quotaSection = `${dim("1d:")}${colorByProvider(usedP, formatPercentCell(usedP), provFn)} ${dim(formatTimeCell(rstRemaining))} ${dim("1w:")}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))} ${dim(formatTimeCellDH("-d--h"))}`;
+      const pools = realQuota.pools || {};
+      const hasAnyPool = pools.pro || pools.flash;
+      if (hasAnyPool) {
+        const slot = (bucket, label) => {
+          if (!bucket) return `${dim(label + ":")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))}`;
+          const gl = deriveGeminiLimits(bucket);
+          const usedP = gl ? gl.usedPct : clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
+          const rstRemaining = formatResetRemaining(bucket.resetTime, ONE_DAY_MS) || "n/a";
+          return `${dim(label + ":")}${colorByProvider(usedP, formatPercentCell(usedP), provFn)} ${dim(formatTimeCell(rstRemaining))}`;
+        };
+        quotaSection = `${slot(pools.pro, "Pr")} ${slot(pools.flash, "Fl")}`;
       } else {
-        quotaSection = `${dim("1d:")}${dim("--%".padStart(PERCENT_CELL_WIDTH))} ${dim(formatTimeCell("n/a"))} ${dim("1w:")}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))} ${dim(formatTimeCellDH("-d--h"))}`;
+        quotaSection = `${dim("Pr:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ${dim("Fl:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))}`;
       }
     }
     if (!quotaSection) {
-      quotaSection = `${dim("5h:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ${dim("1w:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCellDH("-d--h"))}`;
+      quotaSection = `${dim("5h:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ${dim("1w:")}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCellDH("--d--h"))}`;
     }
     const prefix = `${bold(markerColor(`${marker}`))}:`;
     const compactRight = [svStr ? `${dim("sv:")}${svStr}` : "", accountLabel ? markerColor(accountLabel) : ""].filter(Boolean).join(" ");
@@ -1598,21 +1634,31 @@ function getProviderRow(provider, marker, markerColor, qosProfile, accountsConfi
   }
 
   if (realQuota?.type === "gemini") {
-    const bucket = realQuota.quotaBucket;
-    if (bucket) {
-      const usedP = clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
-      const rstRemaining = formatResetRemaining(bucket.resetTime, ONE_DAY_MS) || "n/a";
-      quotaSection = `${dim("1d:")}${tierBar(usedP, provAnsi)}${colorByProvider(usedP, formatPercentCell(usedP), provFn)} ${dim(formatTimeCell(rstRemaining))} ` +
-        `${dim("1w:")}${tierInfBar()}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))} ${dim(formatTimeCellDH("-d--h"))}`;
+    const pools = realQuota.pools || {};
+    const hasAnyPool = pools.pro || pools.flash;
+
+    if (hasAnyPool) {
+      // C/X와 동일한 2슬롯 구조: P:gauge %% (time) F:gauge %% (time)
+      const slot = (bucket, label) => {
+        if (!bucket) {
+          return `${dim(label + ":")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))}`;
+        }
+        const gl = deriveGeminiLimits(bucket);
+        const usedP = gl ? gl.usedPct : clampPercent((1 - (bucket.remainingFraction ?? 1)) * 100);
+        const rstRemaining = formatResetRemaining(bucket.resetTime, ONE_DAY_MS) || "n/a";
+        return `${dim(label + ":")}${tierBar(usedP, provAnsi)}${colorByProvider(usedP, formatPercentCell(usedP), provFn)} ${dim(formatTimeCell(rstRemaining))}`;
+      };
+
+      quotaSection = `${slot(pools.pro, "Pr")} ${slot(pools.flash, "Fl")}`;
     } else {
-      quotaSection = `${dim("1d:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ` +
-        `${dim(formatTimeCell("n/a"))} ${dim("1w:")}${tierInfBar()}${dim("\u221E%".padStart(PERCENT_CELL_WIDTH))} ${dim(formatTimeCellDH("-d--h"))}`;
+      quotaSection = `${dim("Pr:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ` +
+        `${dim("Fl:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))}`;
     }
   }
 
   // 폴백: 쿼터 데이터 없을 때
   if (!quotaSection) {
-    quotaSection = `${dim("5h:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ${dim("1w:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCellDH("-d--h"))}`;
+    quotaSection = `${dim("5h:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCell("n/a"))} ${dim("1w:")}${tierDimBar()}${dim(formatPlaceholderPercentCell())} ${dim(formatTimeCellDH("--d--h"))}`;
   }
 
   const prefix = `${bold(markerColor(`${marker}`))}:`;
@@ -1710,11 +1756,15 @@ async function main() {
     geminiSv = geminiTokens ? geminiTokens / ctxCapacity : null;
   }
 
-  // Gemini: 사용 중인 모델의 쿼터 버킷 찾기
+  // Gemini: 3풀 버킷 추출 (Pro/Flash/Lite — 각 풀 내 모델들은 쿼터 공유)
   const geminiModel = geminiSession?.model || "gemini-3-flash-preview";
-  const geminiBucket = geminiQuota?.buckets?.find((b) => b.modelId === geminiModel)
-    || geminiQuota?.buckets?.find((b) => b.modelId === "gemini-3-flash-preview")
+  const geminiBuckets = geminiQuota?.buckets || [];
+  const geminiBucket = geminiBuckets.find((b) => b.modelId === geminiModel)
+    || geminiBuckets.find((b) => b.modelId === "gemini-3-flash-preview")
     || null;
+  const geminiProBucket = geminiBuckets.find((b) => GEMINI_PRO_POOL.has(b.modelId)) || null;
+  const geminiFlashBucket = geminiBuckets.find((b) => GEMINI_FLASH_POOL.has(b.modelId)) || null;
+  const geminiLiteBucket = geminiBuckets.find((b) => b.modelId?.includes("flash-lite")) || null;
 
   // 합산 절약: Codex+Gemini sv% 합산 (컨텍스트 대비 위임 토큰 비율)
   const combinedSvPct = Math.round(((codexSv ?? 0) + (geminiSv ?? 0)) * 100);
@@ -1731,7 +1781,12 @@ async function main() {
   }
 
   const codexQuotaData = codexBuckets ? { type: "codex", buckets: codexBuckets } : null;
-  const geminiQuotaData = { type: "gemini", quotaBucket: geminiBucket, session: geminiSession };
+  const geminiQuotaData = {
+    type: "gemini",
+    quotaBucket: geminiBucket,
+    pools: { pro: geminiProBucket, flash: geminiFlashBucket, lite: geminiLiteBucket },
+    session: geminiSession,
+  };
 
   const rows = [
     ...getClaudeRows(stdin, claudeUsageSnapshot.data, combinedSvPct),
@@ -1747,7 +1802,8 @@ async function main() {
 
   // 비활성 프로바이더 dim 처리: 데이터 없으면 전체 줄 dim
   const codexActive = codexBuckets != null;
-  const geminiActive = (geminiSession?.total || 0) > 0 || geminiBucket != null;
+  const geminiActive = (geminiSession?.total || 0) > 0 || geminiBucket != null
+    || geminiProBucket != null || geminiFlashBucket != null;
 
   let outputLines = renderAlignedRows(rows);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "4.2.8",
+  "version": "4.2.10",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -47,6 +47,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "better-sqlite3": "^12.6.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
     "systray2": "^2.1.4"
   },
   "keywords": [

package/scripts/lib/context.mjs

@@ -0,0 +1,67 @@
+/**
+ * 요청별 로그 컨텍스트 전파 (AsyncLocalStorage 기반).
+ *
+ * Hub HTTP 서버의 요청마다 correlationId를 자동 할당하여,
+ * 하나의 요청에서 발생한 모든 로그를 추적할 수 있다.
+ *
+ * 사용법:
+ *   import { getLogger, getCorrelationId, withRequestContext } from './lib/context.mjs';
+ *
+ *   // 미들웨어에서 컨텍스트 생성
+ *   withRequestContext({ method: 'POST', path: '/bridge/result' }, () => {
+ *     const log = getLogger();
+ *     log.info({ agentId }, 'bridge.result_received');
+ *   });
+ *
+ *   // 내부 함수에서 자동 상관 ID
+ *   function processResult() {
+ *     const log = getLogger();
+ *     log.info('result.processed'); // correlationId 자동 포함
+ *   }
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+import { logger } from './logger.mjs';
+
+/** @type {AsyncLocalStorage<{logger: import('pino').Logger, correlationId: string}>} */
+export const asyncLocalStorage = new AsyncLocalStorage();
+
+/**
+ * 현재 요청 컨텍스트의 로거를 반환한다.
+ * 요청 컨텍스트 밖에서 호출하면 기본 로거를 반환한다.
+ *
+ * @returns {import('pino').Logger}
+ */
+export function getLogger() {
+  return asyncLocalStorage.getStore()?.logger || logger;
+}
+
+/**
+ * 현재 요청의 상관 ID를 반환한다.
+ *
+ * @returns {string|undefined}
+ */
+export function getCorrelationId() {
+  return asyncLocalStorage.getStore()?.correlationId;
+}
+
+/**
+ * 요청 컨텍스트를 생성하고 콜백을 실행한다.
+ *
+ * @param {object} context — 컨텍스트 필드 (method, path 등)
+ * @param {string} [context.correlationId] — 외부에서 전달된 상관 ID (없으면 자동 생성)
+ * @param {function} callback — 컨텍스트 내에서 실행할 함수
+ * @returns {*}
+ */
+export function withRequestContext(context, callback) {
+  const correlationId = context.correlationId || randomUUID();
+  const { correlationId: _, ...rest } = context;
+
+  const store = {
+    correlationId,
+    logger: logger.child({ correlationId, ...rest }),
+  };
+
+  return asyncLocalStorage.run(store, callback);
+}

package/scripts/lib/logger.mjs

@@ -0,0 +1,105 @@
+/**
+ * Logify — triflux 구조화 로깅 설정
+ *
+ * 사용법:
+ *   import { logger, createModuleLogger } from './lib/logger.mjs';
+ *
+ *   // 기본 로거
+ *   logger.info({ taskId: 'abc' }, 'task.started');
+ *
+ *   // 모듈별 로거
+ *   const log = createModuleLogger('hub');
+ *   log.info({ port: 27888 }, 'server.started');
+ *   log.error({ err }, 'server.error');
+ *
+ * 이벤트 네이밍: {도메인}.{액션} 형식
+ *   hub.started, hub.stopped, route.started, route.completed,
+ *   worker.spawned, worker.completed, worker.timeout,
+ *   mcp.connected, mcp.disconnected, mcp.error,
+ *   team.created, team.deleted, task.claimed, task.completed,
+ *   pipe.connected, pipe.message, pipe.error,
+ *   http.request, http.response, http.error
+ *
+ * 로그 레벨 가이드:
+ *   debug  — 개발/트러블슈팅용 (변수 값, MCP 메시지, 캐시 키)
+ *   info   — 정상 흐름 상태 변경 (서버 시작, 워커 완료, 팀 생성)
+ *   warn   — 위험 신호 (재시도 발생, 쿼타 임박, 느린 워커)
+ *   error  — 작업 실패 (CLI 실행 실패, MCP 연결 끊김)
+ *   fatal  — 프로세스 위협 (DB 연결 불가, 포트 충돌)
+ */
+import pino from 'pino';
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || (isDev ? 'debug' : 'info'),
+
+  // 모든 로그에 포함되는 기본 필드
+  base: {
+    service: process.env.SERVICE_NAME || 'triflux',
+    env: process.env.NODE_ENV || 'development',
+  },
+
+  // 레벨을 대문자로 출력 (AI 파싱 용이)
+  formatters: {
+    level: (label) => ({ level: label.toUpperCase() }),
+  },
+
+  // ISO 8601 타임스탬프
+  timestamp: pino.stdTimeFunctions.isoTime,
+
+  // 민감정보 자동 필터링
+  redact: {
+    paths: [
+      'password',
+      'token',
+      'apiKey',
+      'secret',
+      'authorization',
+      '*.password',
+      '*.token',
+      '*.apiKey',
+      '*.secret',
+      'req.headers.authorization',
+      'req.headers.cookie',
+      'hubToken',
+    ],
+    remove: true,
+  },
+
+  // 개발 환경: 컬러 콘솔 출력
+  transport: isDev
+    ? {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'yyyy-mm-dd HH:MM:ss',
+          ignore: 'pid,hostname',
+        },
+      }
+    : undefined,
+});
+
+/**
+ * 모듈별 Child Logger 생성.
+ * 모듈 이름이 모든 로그에 자동 포함된다.
+ *
+ * @param {string} module — 모듈 이름 (hub, route, worker, mcp, team 등)
+ * @returns {import('pino').Logger}
+ */
+export function createModuleLogger(module) {
+  return logger.child({ module });
+}
+
+// 정상 종료 시 버퍼 flush 보장
+process.on('uncaughtException', (err) => {
+  const finalLogger = pino.final(logger);
+  finalLogger.fatal({ err }, 'process.uncaught_exception');
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  const finalLogger = pino.final(logger);
+  finalLogger.fatal({ reason: String(reason) }, 'process.unhandled_rejection');
+  process.exit(1);
+});

package/scripts/tfx-route.sh

@@ -9,17 +9,111 @@
 #   - Gemini health check 지수 백오프 (30×1s → 5×exp)
 #   - 컨텍스트 파일 5번째 인자 지원
 #
-VERSION="2.4"
+VERSION="2.5"
 #
 # 사용법:
 #   tfx-route.sh <agent_type> <prompt> [mcp_profile] [timeout_sec] [context_file]
+#   tfx-route.sh --async <agent_type> <prompt> [mcp_profile] [timeout_sec] [context_file]
+#   tfx-route.sh --job-status <job_id>
+#   tfx-route.sh --job-result <job_id>
+#
+# --async: 백그라운드 실행, 즉시 job_id 반환 (Claude Code Bash 600초 제한 우회)
+# --job-status: running | done | timeout | failed
+# --job-result: 완료된 잡의 전체 출력
 #
 # 예시:
 #   tfx-route.sh executor "코드 구현" implement
-#   tfx-route.sh architect "아키텍처 분석" analyze '' context.md
+#   tfx-route.sh --async scientist "딥 리서치" auto 1440
+#   tfx-route.sh --job-status 1742400000-12345-9876
+#   tfx-route.sh --job-result 1742400000-12345-9876
 
 set -euo pipefail
 
+# ── Async Job 디렉토리 ──
+TFX_JOBS_DIR="${TMPDIR:-/tmp}/tfx-jobs"
+
+# ── --job-status / --job-result 핸들러 (인자 파싱 전에 처리) ──
+if [[ "${1:-}" == "--job-status" ]]; then
+  job_id="${2:?job_id 필수}"
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+
+  if [[ -f "$job_dir/done" ]]; then
+    exit_code=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+    if [[ "$exit_code" -eq 0 ]]; then
+      echo "done"
+    elif [[ "$exit_code" -eq 124 ]]; then
+      echo "timeout"
+    else
+      echo "failed"
+    fi
+  elif [[ -f "$job_dir/pid" ]]; then
+    pid=$(cat "$job_dir/pid")
+    if kill -0 "$pid" 2>/dev/null; then
+      # 진행 상황 힌트
+      local_bytes=$(wc -c < "$job_dir/stdout.log" 2>/dev/null || echo 0)
+      elapsed=$(( $(date +%s) - $(cat "$job_dir/start_time" 2>/dev/null || date +%s) ))
+      echo "running elapsed=${elapsed}s output=${local_bytes}B"
+    else
+      # 프로세스 종료됐는데 done 마커 없음 → 비정상 종료
+      echo "failed"
+    fi
+  else
+    echo "error: invalid job state"
+    exit 1
+  fi
+  exit 0
+fi
+
+if [[ "${1:-}" == "--job-result" ]]; then
+  job_id="${2:?job_id 필수}"
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+  [[ -f "$job_dir/done" ]] || { echo "error: job still running"; exit 1; }
+
+  cat "$job_dir/result.log" 2>/dev/null
+  exit_code=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+  exit "$exit_code"
+fi
+
+# ── --job-wait: 내부 폴링으로 완료 대기 (Bash 도구 호출 횟수 최소화) ──
+# 사용법: tfx-route.sh --job-wait <job_id> [max_seconds=540]
+# 출력: 주기적 "waiting elapsed=Ns" + 최종 "done"|"timeout"|"failed"|"still_running"
+if [[ "${1:-}" == "--job-wait" ]]; then
+  job_id="${2:?job_id 필수}"
+  max_wait="${3:-540}"  # 기본 540초 (9분, Bash 도구 600초 제한 이내)
+  poll_interval=15
+  job_dir="$TFX_JOBS_DIR/$job_id"
+  [[ -d "$job_dir" ]] || { echo "error: job not found"; exit 1; }
+
+  elapsed=0
+  while [[ "$elapsed" -lt "$max_wait" ]]; do
+    if [[ -f "$job_dir/done" ]]; then
+      ec=$(cat "$job_dir/exit_code" 2>/dev/null || echo 1)
+      if [[ "$ec" -eq 0 ]]; then echo "done"
+      elif [[ "$ec" -eq 124 ]]; then echo "timeout"
+      else echo "failed (exit=$ec)"
+      fi
+      exit 0
+    fi
+    sleep "$poll_interval"
+    elapsed=$((elapsed + poll_interval))
+    stderr_bytes=$(wc -c < "$job_dir/stderr.log" 2>/dev/null || echo 0)
+    echo "waiting elapsed=${elapsed}s progress=${stderr_bytes}B"
+  done
+
+  # max_wait 도달했지만 아직 실행 중
+  echo "still_running elapsed=${elapsed}s"
+  exit 0
+fi
+
+# ── --async 플래그 감지 ──
+TFX_ASYNC_MODE=0
+if [[ "${1:-}" == "--async" ]]; then
+  TFX_ASYNC_MODE=1
+  shift
+fi
+
 # ── 인자 파싱 ──
 AGENT_TYPE="${1:?에이전트 타입 필수 (executor, debugger, designer 등)}"
 PROMPT="${2:?프롬프트 필수}"
@@ -1518,4 +1612,40 @@ EOF
   return "$exit_code"
 }
 
+# ── Async 모드: 백그라운드 실행 + 즉시 job_id 반환 ──
+if [[ "$TFX_ASYNC_MODE" -eq 1 ]]; then
+  mkdir -p "$TFX_JOBS_DIR"
+  JOB_ID="$TIMESTAMP-$$-${RANDOM}"
+  JOB_DIR="$TFX_JOBS_DIR/$JOB_ID"
+  mkdir -p "$JOB_DIR"
+  echo "$AGENT_TYPE" > "$JOB_DIR/agent_type"
+  date +%s > "$JOB_DIR/start_time"
+
+  # 백그라운드 서브쉘: main 실행 → 결과 저장
+  (
+    set +e  # main 내부 에러가 exit_code 기록 전에 서브쉘을 죽이는 것 방지
+    exec > "$JOB_DIR/result.log" 2>"$JOB_DIR/stderr.log"
+    main
+    echo $? > "$JOB_DIR/exit_code"
+    touch "$JOB_DIR/done"
+  ) &
+  bg_pid=$!
+  echo "$bg_pid" > "$JOB_DIR/pid"
+
+  # 종료 감지 데몬 (main이 signal/crash로 죽어도 done 마커 생성)
+  (
+    wait "$bg_pid" 2>/dev/null
+    ec=$?
+    if [[ ! -f "$JOB_DIR/done" ]]; then
+      echo "$ec" > "$JOB_DIR/exit_code"
+      touch "$JOB_DIR/done"
+    fi
+  ) &
+  disown
+
+  # 즉시 리턴: 1초 이내에 Claude Code Bash 도구 완료
+  echo "$JOB_ID"
+  exit 0
+fi
+
 main

package/skills/tfx-multi/SKILL.md

@@ -170,7 +170,7 @@ status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 
 | 항목 | 설명 |
 |------|------|
-| `scripts/tfx-route.sh` | 팀 통합 라우터 |
+| `scripts/tfx-route.sh` | 팀 통합 라우터 (v2.5: `--async`/`--job-wait`/`--job-status`/`--job-result`) |
 | `hub/team/native.mjs` | Native Teams 래퍼 (프롬프트 템플릿) |
 | `hub/pipeline/` | 파이프라인 상태 기계 (`--thorough` 모드) |
 | `tfx-auto` | one-shot 실행 오케스트레이터 |

package/skills/tfx-multi/references/agent-wrapper-rules.md

@@ -58,12 +58,25 @@ codex-worker는 반드시 tfx-route.sh를 통해 Codex에 위임하고, gemini-w
 
 리드는 워커의 Step 2, Step 4 시점에 턴 경계를 인식하고, 방향 전환/추가 지시/재실행 요청을 보낼 수 있다.
 
-## Bash timeout 동적 상속
+## Async 실행 프로토콜 (v2.5+)
 
-Bash timeout은 tfx-route.sh의 role/profile별 timeout + 60초 여유를 ms로 변환하여 동적 상속한다.
-`getRouteTimeout(role, mcpProfile)` 기준:
-- analyze/review 프로필 또는 architect/analyst 역할: 3600초
-- 그 외 기본: 1080초(18분)
+Claude Code Bash 도구는 최대 600초(10분) 하드코딩 제한이 있다.
+scientist(24분), scientist-deep(60분) 등 장시간 워커는 이 제한에 걸린다.
+
+**해결: `--async` 3단계 패턴**
+
+| 단계 | 명령 | Bash timeout | 소요 |
+|------|------|-------------|------|
+| 시작 | `tfx-route.sh --async {role} '{task}' {profile} {timeout}` | 15초 | <1초 |
+| 대기 | `tfx-route.sh --job-wait {job_id} 540` | 570초 | 최대 540초/회 |
+| 결과 | `tfx-route.sh --job-result {job_id}` | 30초 | <1초 |
+
+- `--job-wait`는 내부에서 15초 간격으로 폴링하며 `done`/`timeout`/`failed`/`still_running` 반환
+- `still_running` 시 같은 `--job-wait` 명령을 반복 (무한 반복 가능)
+- 실제 워커 timeout은 tfx-route.sh의 `timeout` 명령으로 관리 (Bash 도구와 무관)
+
+**이전 방식 (deprecated):**
+Bash timeout을 role/profile별 timeout + 60초로 설정했으나, 600초 초과 시 Bash 도구가 강제 종료했다.
 
 ## tfx-route.sh 팀 통합 동작