triflux 4.2.9 → 5.0.0

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) {
@@ -1024,15 +1046,15 @@ function expireStaleCodexBuckets(buckets) {
 // ============================================================================
 // Codex 세션 JSONL에서 실제 rate limits 추출
 // 한계: rate_limits는 세션별 스냅샷이므로 여러 세션 간 토큰 합산은 불가.
-// 오늘 날짜의 모든 세션 파일을 스캔해 가장 최신 rate_limits 버킷을 수집한다.
-// (단일 파일 즉시 return 방식에서 → 당일 전체 스캔 후 최신 데이터 우선 병합으로 변경)
+// 최근 7일간 세션 파일을 스캔해 가장 최신 rate_limits 버킷을 수집한다.
+// 합성 버킷(token_count 기반)은 2일 이내 데이터만 허용하여 stale 방지.
 // ============================================================================
 function getCodexRateLimits() {
   const now = new Date();
-  let syntheticBucket = null; // 오늘 token_count에서 합성 (행 활성화 + 토큰 데이터용)
+  let syntheticBucket = null; // 최근 token_count에서 합성 (행 활성화 + 토큰 데이터용)
 
-  // 2일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
-  for (let dayOffset = 0; dayOffset <= 1; dayOffset++) {
+  // 7일간 스캔: 실제 rate_limits 우선, 합성 버킷은 폴백
+  for (let dayOffset = 0; dayOffset <= 6; dayOffset++) {
     const d = new Date(now.getTime() - dayOffset * 86_400_000);
     const sessDir = join(
       homedir(), ".codex", "sessions",
@@ -1064,8 +1086,8 @@ function getCodexRateLimits() {
                 contextWindow: evt.payload?.info?.model_context_window,
                 timestamp: evt.timestamp,
               };
-            } else if (dayOffset === 0 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
-              // 오늘 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용)
+            } else if (dayOffset <= 1 && !rl && evt?.payload?.info?.total_token_usage && !syntheticBucket) {
+              // 2일 이내 token_count: 합성 버킷 (rate_limits가 null일 때 행 활성화용, stale 방지)
               syntheticBucket = {
                 limitId: "codex", limitName: "codex-session",
                 primary: null, secondary: null,
@@ -1080,7 +1102,7 @@ function getCodexRateLimits() {
         }
       } catch { /* 파일 읽기 실패 무시 */ }
     }
-    // 실제 rate_limits 발견 → 오늘 토큰 데이터 병합 후 즉시 반환
+    // 실제 rate_limits 발견 → 토큰 데이터 병합 후 즉시 반환
     if (Object.keys(mergedBuckets).length > 0) {
       if (syntheticBucket) {
         const main = mergedBuckets.codex || mergedBuckets[Object.keys(mergedBuckets)[0]];
@@ -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.9",
+  "version": "5.0.0",
   "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/lib/mcp-filter.mjs

@@ -127,6 +127,31 @@ const PROFILE_DEFINITIONS = Object.freeze({
   }),
 });
 
+/**
+ * 파이프라인 단계별 MCP 서버/도구 제한 (post-filter).
+ * role-based 프로필 위에 추가 적용. 빈 배열 = 전체 차단, 미정의 = 제한 없음.
+ */
+export const PHASE_OVERRIDES = Object.freeze({
+  plan: Object.freeze({
+    description: '계획 단계: 읽기 전용 탐색만 허용',
+    allowedServers: Object.freeze(['context7']),
+    blockedServers: Object.freeze(['playwright', 'tavily', 'exa']),
+  }),
+  prd: Object.freeze({
+    description: 'PRD 단계: 읽기 전용 탐색 + 문서 조회',
+    allowedServers: Object.freeze(['context7', 'brave-search']),
+    blockedServers: Object.freeze(['playwright']),
+  }),
+  exec: Object.freeze({
+    description: '실행 단계: 프로필 기반 전체 허용 (제한 없음)',
+  }),
+  verify: Object.freeze({
+    description: '검증 단계: 읽기 전용 + 분석 도구',
+    allowedServers: Object.freeze(['context7', 'brave-search', 'exa']),
+    blockedServers: Object.freeze(['playwright']),
+  }),
+});
+
 export const LEGACY_PROFILE_ALIASES = Object.freeze({
   implement: 'executor',
   analyze: 'analyze',
@@ -553,13 +578,23 @@ export function buildMcpPolicy(options = {}) {
   const inventoryIndex = buildInventoryIndex(inventory);
   const resolvedOptions = { ...options, inventory, inventoryIndex };
   const resolvedProfile = resolveMcpProfile(options.agentType, options.requestedProfile);
-  const allowedServers = resolveAllowedServers(resolvedOptions);
+  let allowedServers = resolveAllowedServers(resolvedOptions);
   const hint = buildPromptHint(resolvedOptions);
+
+  // Phase-aware post-filter: 파이프라인 단계별 서버 제한 적용
+  const phase = options.phase;
+  const phaseOverride = phase && PHASE_OVERRIDES[phase];
+  if (phaseOverride && phaseOverride.blockedServers) {
+    const blocked = new Set(phaseOverride.blockedServers);
+    allowedServers = allowedServers.filter((s) => !blocked.has(s));
+  }
+
   return {
     requestedProfile: typeof options.requestedProfile === 'string' && options.requestedProfile
       ? options.requestedProfile
       : 'auto',
     resolvedProfile,
+    resolvedPhase: phase || null,
     allowedServers,
     hint,
     geminiAllowedServers: getGeminiAllowedServers(resolvedOptions),
@@ -577,14 +612,18 @@ function shellArray(name, values) {
 }
 
 export function toShellExports(policy) {
-  return [
+  const lines = [
     `MCP_PROFILE_REQUESTED=${shellEscape(policy.requestedProfile)}`,
     `MCP_RESOLVED_PROFILE=${shellEscape(policy.resolvedProfile)}`,
     `MCP_HINT=${shellEscape(policy.hint)}`,
     shellArray('GEMINI_ALLOWED_SERVERS', policy.geminiAllowedServers),
     shellArray('CODEX_CONFIG_FLAGS', policy.codexConfigOverrides.flatMap((override) => ['-c', override])),
     `CODEX_CONFIG_JSON=${shellEscape(JSON.stringify(policy.codexConfig))}`,
-  ].join('\n');
+  ];
+  if (policy.resolvedPhase) {
+    lines.push(`MCP_PIPELINE_PHASE=${shellEscape(policy.resolvedPhase)}`);
+  }
+  return lines.join('\n');
 }
 
 function parseCliArgs(argv) {
@@ -636,6 +675,9 @@ function parseCliArgs(argv) {
       case '--worker-index':
         args.workerIndex = Number.parseInt(next(), 10);
         break;
+      case '--phase':
+        args.phase = next();
+        break;
       default:
         throw new Error(`알 수 없는 옵션: ${token}`);
     }

package/skills/tfx-auto/SKILL.md

@@ -32,14 +32,20 @@ argument-hint: "<command|task> [args...]"
 > 2. **비용**: Codex 우선 → Gemini → Claude 최후 수단. `claude` 선택 전 "Codex로 가능한가?" 재확인.
 > 3. **DAG**: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. `.omc/context/{sid}/` 생성, context_output 저장, 실패 시 후속 SKIP.
 > 4. **트리아지**: Codex `--full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
+> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
 
 ## 모드
 
 | 입력 형식 | 모드 | 트리아지 |
 |-----------|------|----------|
-| `/implement JWT 추가` | 커맨드 숏컷 | 없음 (즉시 실행) |
-| `/tfx-auto "리팩터링 + UI"` | 자동 | Codex 분류 → Opus 분해 |
-| `/tfx-auto 3:codex "리뷰"` | 수동 | Opus 분해만 |
+| `/implement JWT 추가` | 커맨드 숏컷 (quick) | 없음 (즉시 실행) |
+| `/tfx-auto "리팩터링 + UI"` | 자동 (quick) | Codex 분류 → Opus 분해 |
+| `/tfx-auto -t "리팩터링 + UI"` | 자동 (thorough) | Codex 분류 → Opus 분해 → Pipeline |
+| `/tfx-auto --thorough "리팩터링"` | 자동 (thorough) | `-t` 동일 |
+| `/tfx-auto 3:codex "리뷰"` | 수동 (quick) | Opus 분해만 |
+
+> **tfx-auto는 `--quick`이 기본.** 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문.
+> 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(`--thorough`)이 적용된다.
 
 ## 커맨드 숏컷
 
@@ -100,25 +106,77 @@ argument-hint: "<command|task> [args...]"
 
 **수동 모드 (`N:agent_type`):** Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.
 
+## --thorough 모드
+
+`-t` 또는 `--thorough` 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.
+
+```
+분기점은 "실행 전략"이지 "계획"이 아님:
+
+TRIAGE
+  │
+  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
+  │                                                      │
+  │                                      ┌───────────────┤
+  │                                      │               │
+  │                                  [1 task]        [2+ tasks]
+  │                                      │               │
+  │                                  AUTO 직접 실행   TEAM EXEC (multi Phase 3)
+  │                                      │               │
+  │                                      └───────┬───────┘
+  │                                              │
+  │                                          VERIFY → FIX loop → COMPLETE
+  │
+  └─ [quick] → [1 task] → fire-and-forget
+               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
+```
+
+### 단일 태스크 thorough
+
+1. `Bash("node hub/bridge.mjs pipeline-init --team ${sid}")` — 파이프라인 초기화 (phase: plan)
+2. Plan: Codex architect → 결과를 `pipeline.writePlanFile()` 저장
+3. PRD: Codex analyst → acceptance criteria 확정
+4. `pipeline_advance_gated` → [Approval Gate] → 사용자 승인 대기
+5. Exec: tfx-auto 직접 실행 (아래 "실행" 섹션)
+6. Verify: Codex verifier → 검증
+7. 실패 시 Fix loop (최대 3회) → Exec 재실행
+8. Complete
+
+### 멀티 태스크 thorough
+
+Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
+서브태스크 배열 + `thorough: true` 신호를 함께 전달하여 multi 측에서 verify/fix를 수행.
+
 ## 멀티 태스크 라우팅 (트리아지 후)
 
-> **트리아지 결과 서브태스크가 2개 이상이면 tfx-multi Native Teams 모드로 자동 전환한다.**
+> **트리아지 결과에 따라 실행 경로 결정.**
 
-| 서브태스크 수 | 실행 경로 | 이유 |
-|--------------|----------|------|
-| 1개 | tfx-auto 직접 실행 (아래 "실행" 섹션) | 팀 오버헤드 불필요, 경량 fire-and-forget |
-| 2개+ | **tfx-multi Phase 3** (TeamCreate → TaskCreate → Agent 래퍼) | Shift+Down 네비게이션, 상태 추적, fallback |
+| 조건 | 실행 경로 | 이유 |
+|------|----------|------|
+| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | 팀 오버헤드 불필요 |
+| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | plan→exec→verify 단일 경로 |
+| 2개+ + quick | tfx-multi Phase 3 (TeamCreate 직행) | Shift+Down, 상태 추적 |
+| 2개+ + thorough | Plan/PRD/Approval 후 → tfx-multi Phase 3 + verify/fix | 전체 파이프라인 |
 
-**전환 방법:** 트리아지 완료 후 서브태스크 배열을 그대로 tfx-multi Phase 3에 전달한다.
-tfx-multi의 Phase 2(트리아지)는 건너뛰고 Phase 3a(TeamCreate)부터 시작한다.
+**전환 방법:** 트리아지 완료 후 서브태스크 배열 + thorough 플래그를 tfx-multi Phase 3에 전달.
+tfx-multi의 Phase 2(트리아지)는 건너뛰고, thorough 시 Phase 2.5-2.6도 건너뛴다 (auto에서 이미 수행).
 
 ```
+thorough = args에 -t 또는 --thorough 포함
+
 if subtasks.length >= 2:
-  → tfx-multi Phase 3 실행 (트리아지 결과 재사용)
-  → TeamCreate → TaskCreate × N → Agent 래퍼 spawn (Phase 3a~3c)
-  → Phase 4 결과 수집 → Phase 5 정리
+  if thorough:
+    → Pipeline init → Plan → PRD → Approval (tfx-auto에서 수행)
+    → tfx-multi Phase 3 실행 ({ subtasks, thorough: true })
+    → Phase 3.5 verify → Phase 3.6 fix loop → Phase 5 정리
+  else:
+    → tfx-multi Phase 3 실행 ({ subtasks, thorough: false })
+    → Phase 4 결과 수집 → Phase 5 정리
 else:
-  → tfx-auto 직접 실행 (아래)
+  if thorough:
+    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
+  else:
+    → tfx-auto 직접 실행 (아래)
 ```
 
 ## 실행