triflux 4.2.9 → 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/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.9",
+  "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);
+});