triflux 10.3.1 → 10.3.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "triflux",
       "description": "CLI-first multi-model orchestrator for Claude Code. Routes tasks to Codex, Gemini, and Claude CLIs with automatic triage, DAG-based parallel execution, headless psmux sessions, and cost-optimized routing. Includes 41 skills, HUD status bar, hook orchestrator, and shell-based CLI routing.",
-      "version": "9.7.14",
+      "version": "10.3.2",
       "author": {
         "name": "tellang"
       },
@@ -30,5 +30,5 @@
       ]
     }
   ],
-  "version": "9.7.14"
+  "version": "10.3.2"
 }

package/.claude-plugin/plugin.json

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

package/README.ko.md

@@ -39,6 +39,14 @@
 
 ### 1. 설치
 
+**Claude Code 플러그인** (권장):
+
+```bash
+claude plugin add triflux
+```
+
+**npm 글로벌**:
+
 ```bash
 npm install -g triflux
 ```
@@ -286,6 +294,14 @@ graph TD
 
 ### 1. 설치
 
+**Claude Code 플러그인** (권장):
+
+```bash
+claude plugin add triflux
+```
+
+**npm 글로벌**:
+
 ```bash
 npm install -g triflux
 ```

package/README.md

@@ -63,6 +63,14 @@ You don't need to memorize commands. Say what you want in natural language — t
 
 ### 1. Install
 
+**Claude Code Plugin** (recommended):
+
+```bash
+claude plugin add triflux
+```
+
+**npm global**:
+
 ```bash
 npm install -g triflux
 ```

package/hub/team/ansi.mjs

@@ -249,39 +249,55 @@ export function padRight(str, len) {
   return str + " ".repeat(pad);
 }
 
-// wcwidth-aware truncate: wide char 경계에서 자름
-export function truncate(str, maxLen) {
-  const plain = stripAnsi(str);
-  const w = wcswidth(plain);
-  if (w <= maxLen) return str;
-
-  let acc = 0;
+// ANSI-preserving slice: ANSI escape를 보존하면서 visible width만큼 자름
+function ansiSlice(str, maxWidth) {
+  let result = "";
+  let visWidth = 0;
+  let hasAnsi = false;
   let i = 0;
-  for (const char of plain) {
-    const cw = charWidth(char.codePointAt(0));
-    if (acc + cw > maxLen - 1) break;
-    acc += cw;
-    i += char.length;
+
+  while (i < str.length) {
+    if (str.charCodeAt(i) === 0x1B) {
+      const rest = str.slice(i);
+      const m = rest.match(/^(\x1b(?:\[[0-9;]*[a-zA-Z]|\].*?(?:\x07|\x1b\\)))/);
+      if (m) {
+        result += m[1];
+        hasAnsi = true;
+        i += m[1].length;
+        continue;
+      }
+    }
+
+    const cp = str.codePointAt(i);
+    const charLen = cp > 0xFFFF ? 2 : 1;
+    const cw = charWidth(cp);
+
+    if (visWidth + cw > maxWidth) break;
+
+    result += str.slice(i, i + charLen);
+    visWidth += cw;
+    i += charLen;
   }
-  return plain.slice(0, i) + "…";
+
+  return { result, visWidth, hasAnsi };
 }
 
-// wcwidth-aware clip: 정확히 width 셀에 맞게 자르고 패딩 (wide char 경계 보정)
+// wcwidth-aware truncate: wide char 경계에서 자름 (ANSI 보존)
+export function truncate(str, maxLen) {
+  if (wcswidth(str) <= maxLen) return str;
+
+  const { result, hasAnsi } = ansiSlice(str, maxLen - 1);
+  return hasAnsi ? result + RESET + "…" : result + "…";
+}
+
+// wcwidth-aware clip: 정확히 width 셀에 맞게 자르고 패딩 (ANSI 보존, wide char 경계 보정)
 export function clip(str, width) {
-  const plain = stripAnsi(str);
-  let acc = 0;
-  let i = 0;
-  for (const char of plain) {
-    const cw = charWidth(char.codePointAt(0));
-    if (acc + cw > width) {
-      // wide char이 경계를 넘으면 공백으로 채움
-      const result = plain.slice(0, i) + " ".repeat(width - acc);
-      return result;
-    }
-    acc += cw;
-    i += char.length;
-  }
-  return str + " ".repeat(width - acc);
+  const vis = wcswidth(str);
+  if (vis <= width) return str + " ".repeat(width - vis);
+
+  const { result, visWidth, hasAnsi } = ansiSlice(str, width);
+  const suffix = hasAnsi ? RESET : "";
+  return result + suffix + " ".repeat(Math.max(0, width - visWidth));
 }
 
 // ── Catppuccin Mocha 색상 상수 ──

package/hub/team/conductor.mjs

@@ -22,7 +22,7 @@ import { createRegistry } from "../../mesh/mesh-registry.mjs";
 import { broker } from "../account-broker.mjs";
 import { killProcess } from "../platform.mjs";
 import { createConductorMeshBridge } from "./conductor-mesh-bridge.mjs";
-import { getConductorRegistry } from "./conductor-registry.mjs";
+import { ensureConductorRegistry, getConductorRegistry } from "./conductor-registry.mjs";
 import { createEventLog } from "./event-log.mjs";
 import { createHealthProbe } from "./health-probe.mjs";
 import { buildLauncher } from "./launcher-template.mjs";
@@ -797,6 +797,6 @@ export function createConductor(opts = {}) {
   }
 
   const frozenApi = Object.freeze(conductor);
-  getConductorRegistry().register(frozenApi);
+  ensureConductorRegistry();
   return frozenApi;
 }

package/hub/team/tui-lite.mjs

@@ -265,12 +265,12 @@ export function createLiteDashboard(opts = {}) {
       return;
     }
     if (key === "\r" || key === "\n") {
-      if (typeof onOpenSelectedWorker !== "function") {
-        // 콜백 없으면 탭 순환 (기본 동작)
+      if (typeof onOpenSelectedWorker === "function" && selectedWorker && workers.has(selectedWorker)) {
+        triggerOpenSelected();
+      } else {
+        // 콜백 없거나 선택 워커 없으면 탭 순환
         const tabs = ["log", "detail", "files"];
         focusTab = tabs[(tabs.indexOf(focusTab) + 1) % tabs.length];
-      } else {
-        triggerOpenSelected();
       }
       render();
       return;

package/hub/team/tui.mjs

@@ -1148,15 +1148,19 @@ export function createLogDashboard(opts = {}) {
     }
 
     // 하단 상태바
-    const statusBar = truncate(
-      color(`  세션 종료됨 — 아무 키나 누르면 닫힘`, MOCHA.subtext),
-      totalCols,
-    );
+    const allDone = names.every((n) => {
+      const s = runtimeStatus(workers.get(n));
+      return s === "ok" || s === "completed" || s === "failed";
+    });
+    const statusText = allDone
+      ? "  Enter: attach • q: 종료"
+      : "  Enter: attach • Tab: 포커스 • j/k: 이동 • h: 도움말";
+    const statusBar = truncate(color(statusText, MOCHA.subtext), totalCols);
 
     return [...tier1, ...composedRows, statusBar];
   }
 
-  // ── altScreen diff render ─────────────────────────────────────────────
+  // ── altScreen diff render (batched single write → 깜빡임 방지) ───────
   function renderAltScreen() {
     const newRows = buildRows();
     rowBuf.set(newRows);
@@ -1165,16 +1169,16 @@ export function createLogDashboard(opts = {}) {
 
     if (dirty.length === 0 && newRows.length === prevLen) return;
 
-    const toErase = prevLen > newRows.length
-      ? Array.from({ length: prevLen - newRows.length }, (_, i) => newRows.length + i)
-      : [];
-
+    let buf = "";
     for (const i of dirty) {
-      write(moveTo(i + 1, 1) + clearLine + (newRows[i] || ""));
+      buf += moveTo(i + 1, 1) + clearLine + (newRows[i] || "");
     }
-    for (const i of toErase) {
-      write(moveTo(i + 1, 1) + clearLine);
+    if (prevLen > newRows.length) {
+      for (let i = newRows.length; i < prevLen; i++) {
+        buf += moveTo(i + 1, 1) + clearLine;
+      }
     }
+    if (buf) write(buf);
 
     rowBuf.commit();
   }

package/hud/constants.mjs

@@ -39,9 +39,15 @@ export const DEFAULT_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 
 export const CODEX_AUTH_PATH = join(homedir(), ".codex", "auth.json");
 export const CODEX_QUOTA_CACHE_PATH = join(homedir(), ".claude", "cache", "codex-rate-limits-cache.json");
-export const CODEX_QUOTA_STALE_MS = 15 * 1000; // 15초
+export const CODEX_QUOTA_STALE_MS = 30 * 1000; // 30초
 export const CODEX_MIN_BUCKETS = 2;
 
+// Spawn lock (중복 refresh 방지)
+export const CODEX_REFRESH_LOCK_PATH = join(homedir(), ".claude", "cache", ".codex-refresh-lock");
+export const GEMINI_QUOTA_REFRESH_LOCK_PATH = join(homedir(), ".claude", "cache", ".gemini-quota-refresh-lock");
+export const GEMINI_SESSION_REFRESH_LOCK_PATH = join(homedir(), ".claude", "cache", ".gemini-session-refresh-lock");
+export const SPAWN_LOCK_TTL_MS = 30 * 1000; // 30초 spawn dedup
+
 // Gemini 쿼터 API 관련
 export const GEMINI_OAUTH_PATH = join(homedir(), ".gemini", "oauth_creds.json");
 export const GEMINI_QUOTA_CACHE_PATH = join(homedir(), ".claude", "cache", "gemini-quota-cache.json");
@@ -58,7 +64,7 @@ export const LEGACY_SV_ACCUMULATOR = join(homedir(), ".omc", "state", "sv-accumu
 
 export const GEMINI_RPM_WINDOW_MS = 60 * 1000; // 60초 슬라이딩 윈도우
 export const GEMINI_QUOTA_STALE_MS = 5 * 60 * 1000; // 5분
-export const GEMINI_SESSION_STALE_MS = 15 * 1000; // 15초
+export const GEMINI_SESSION_STALE_MS = 30 * 1000; // 30초
 export const GEMINI_API_TIMEOUT_MS = 3000; // 3초
 
 export const ACCOUNT_LABEL_WIDTH = 10;

package/hud/providers/codex.mjs

@@ -8,6 +8,7 @@ import { spawn } from "node:child_process";
 import {
   CODEX_AUTH_PATH, CODEX_QUOTA_CACHE_PATH, CODEX_QUOTA_STALE_MS,
   CODEX_MIN_BUCKETS, CODEX_REFRESH_FLAG,
+  CODEX_REFRESH_LOCK_PATH, SPAWN_LOCK_TTL_MS,
 } from "../constants.mjs";
 import { readJson, writeJsonSafe, decodeJwtEmail } from "../utils.mjs";
 
@@ -154,6 +155,16 @@ export function refreshCodexRateLimitsCache() {
 export function scheduleCodexRateLimitRefresh() {
   const scriptPath = process.argv[1];
   if (!scriptPath) return;
+
+  // 스폰 락: 30초 내 이미 스폰했으면 중복 방지
+  try {
+    if (existsSync(CODEX_REFRESH_LOCK_PATH)) {
+      const lockAge = Date.now() - readJson(CODEX_REFRESH_LOCK_PATH, {}).t;
+      if (lockAge < SPAWN_LOCK_TTL_MS) return;
+    }
+    writeJsonSafe(CODEX_REFRESH_LOCK_PATH, { t: Date.now() });
+  } catch { /* 락 실패 무시 — 스폰 진행 */ }
+
   try {
     const child = spawn(process.execPath, [scriptPath, CODEX_REFRESH_FLAG], {
       detached: true,

package/hud/providers/gemini.mjs

@@ -14,6 +14,7 @@ import {
   GEMINI_RPM_WINDOW_MS, GEMINI_QUOTA_STALE_MS, GEMINI_SESSION_STALE_MS,
   GEMINI_API_TIMEOUT_MS,
   GEMINI_REFRESH_FLAG, GEMINI_SESSION_REFRESH_FLAG,
+  GEMINI_QUOTA_REFRESH_LOCK_PATH, GEMINI_SESSION_REFRESH_LOCK_PATH, SPAWN_LOCK_TTL_MS,
 } from "../constants.mjs";
 import {
   readJson, writeJsonSafe, readJsonMigrate, makeHash, clampPercent,
@@ -233,6 +234,16 @@ export function readGeminiQuotaSnapshot(accountId, authContext) {
 export function scheduleGeminiQuotaRefresh(accountId) {
   const scriptPath = process.argv[1];
   if (!scriptPath) return;
+
+  // 스폰 락: 30초 내 이미 스폰했으면 중복 방지
+  try {
+    if (existsSync(GEMINI_QUOTA_REFRESH_LOCK_PATH)) {
+      const lockAge = Date.now() - readJson(GEMINI_QUOTA_REFRESH_LOCK_PATH, {}).t;
+      if (lockAge < SPAWN_LOCK_TTL_MS) return;
+    }
+    writeJsonSafe(GEMINI_QUOTA_REFRESH_LOCK_PATH, { t: Date.now() });
+  } catch { /* 락 실패 무시 — 스폰 진행 */ }
+
   try {
     const child = spawn(
       process.execPath,
@@ -275,6 +286,16 @@ export function refreshGeminiSessionCache() {
 export function scheduleGeminiSessionRefresh() {
   const scriptPath = process.argv[1];
   if (!scriptPath) return;
+
+  // 스폰 락: 30초 내 이미 스폰했으면 중복 방지
+  try {
+    if (existsSync(GEMINI_SESSION_REFRESH_LOCK_PATH)) {
+      const lockAge = Date.now() - readJson(GEMINI_SESSION_REFRESH_LOCK_PATH, {}).t;
+      if (lockAge < SPAWN_LOCK_TTL_MS) return;
+    }
+    writeJsonSafe(GEMINI_SESSION_REFRESH_LOCK_PATH, { t: Date.now() });
+  } catch { /* 락 실패 무시 — 스폰 진행 */ }
+
   try {
     const child = spawn(process.execPath, [scriptPath, GEMINI_SESSION_REFRESH_FLAG], {
       detached: true,

package/mesh/index.mjs

@@ -0,0 +1,63 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export { MSG_TYPES, createMessage, serialize, deserialize, validate } from "./mesh-protocol.mjs";
+export { createRegistry } from "./mesh-registry.mjs";
+export { createMeshBudget } from "./mesh-budget.mjs";
+export { routeMessage, routeOrDeadLetter } from "./mesh-router.mjs";
+export { createMessageQueue } from "./mesh-queue.mjs";
+export { createHeartbeatMonitor } from "./mesh-heartbeat.mjs";
+
+/**
+ * Loads skills assigned to a specific agent from a skills directory.
+ * Reuses the same directory-scan approach as generateSkillDocs().
+ *
+ * @param {string} agentId - The agent identifier
+ * @param {string} skillsDir - Path to the skills directory
+ * @returns {Promise<string[]>} Array of skill names available to this agent
+ */
+export async function loadSkillsForAgent(agentId, skillsDir) {
+  if (!agentId || typeof agentId !== "string") {
+    throw new TypeError("agentId must be a non-empty string");
+  }
+  if (!skillsDir || typeof skillsDir !== "string") {
+    throw new TypeError("skillsDir must be a non-empty string");
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillName = entry.name;
+    const skillPath = join(skillsDir, skillName, "SKILL.md");
+    let skillContent = null;
+    try {
+      const { readFileSync } = await import("node:fs");
+      skillContent = readFileSync(skillPath, "utf8");
+    } catch {
+      // Skill has no SKILL.md — include it anyway
+    }
+
+    // If SKILL.md mentions the agentId or no agent restriction, include it
+    const isRestricted = skillContent
+      ? /^agents?\s*:/im.test(skillContent)
+      : false;
+
+    if (!isRestricted) {
+      skills.push(skillName);
+      continue;
+    }
+
+    if (skillContent && skillContent.includes(agentId)) {
+      skills.push(skillName);
+    }
+  }
+
+  return skills;
+}

package/mesh/mesh-budget.mjs

@@ -0,0 +1,128 @@
+/**
+ * Warning level thresholds mirroring context-monitor.mjs classifyContextThreshold().
+ * Reproduced here to avoid cross-module dependency.
+ */
+const WARNING_LEVELS = Object.freeze({
+  critical: 90,
+  warn: 80,
+  info: 60,
+  ok: 0,
+});
+
+/**
+ * Clamps a percentage value to [0, 100].
+ * @param {number} value
+ * @returns {number}
+ */
+function clampPercent(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return 0;
+  return Math.min(100, Math.max(0, n));
+}
+
+/**
+ * Classifies a usage percentage into a warning level.
+ * Mirrors context-monitor.mjs classifyContextThreshold().
+ * @param {number} percent
+ * @returns {{ level: string, message: string }}
+ */
+function classifyLevel(percent) {
+  const p = clampPercent(percent);
+  if (p >= WARNING_LEVELS.critical) return { level: "critical", message: "에이전트 분할 또는 세션 교체 권장" };
+  if (p >= WARNING_LEVELS.warn) return { level: "warn", message: "압축 권장" };
+  if (p >= WARNING_LEVELS.info) return { level: "info", message: "컨텍스트 절반 이상 사용" };
+  return { level: "ok", message: "" };
+}
+
+/**
+ * Creates a per-agent token budget manager.
+ * @returns {object} Budget API
+ */
+export function createMeshBudget() {
+  // Map<agentId, { allocated: number, consumed: number }>
+  const budgets = new Map();
+
+  /**
+   * Allocates a token budget to an agent.
+   * @param {string} agentId
+   * @param {number} tokenLimit
+   */
+  function allocate(agentId, tokenLimit) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    const limit = Math.max(0, Math.round(Number(tokenLimit) || 0));
+    const existing = budgets.get(agentId);
+    budgets.set(agentId, {
+      allocated: limit,
+      consumed: existing?.consumed ?? 0,
+    });
+  }
+
+  /**
+   * Records token consumption for an agent.
+   * @param {string} agentId
+   * @param {number} tokens
+   * @returns {{ remaining: number, percent: number, level: string }}
+   */
+  function consume(agentId, tokens) {
+    const budget = budgets.get(agentId);
+    if (!budget) {
+      throw new Error(`No budget allocated for agent: ${agentId}`);
+    }
+    const amount = Math.max(0, Math.round(Number(tokens) || 0));
+    const updated = {
+      allocated: budget.allocated,
+      consumed: budget.consumed + amount,
+    };
+    budgets.set(agentId, updated);
+
+    const remaining = Math.max(0, updated.allocated - updated.consumed);
+    const percent = updated.allocated > 0
+      ? clampPercent((updated.consumed / updated.allocated) * 100)
+      : 100;
+    const { level } = classifyLevel(percent);
+    return { remaining, percent, level };
+  }
+
+  /**
+   * Returns the budget status for an agent.
+   * @param {string} agentId
+   * @returns {{ allocated: number, consumed: number, remaining: number, level: string }}
+   */
+  function getStatus(agentId) {
+    const budget = budgets.get(agentId);
+    if (!budget) {
+      return { allocated: 0, consumed: 0, remaining: 0, level: "ok" };
+    }
+    const remaining = Math.max(0, budget.allocated - budget.consumed);
+    const percent = budget.allocated > 0
+      ? clampPercent((budget.consumed / budget.allocated) * 100)
+      : 0;
+    const { level } = classifyLevel(percent);
+    return { allocated: budget.allocated, consumed: budget.consumed, remaining, level };
+  }
+
+  /**
+   * Resets consumed tokens for all agents (keeps allocations).
+   */
+  function resetAll() {
+    for (const [agentId, budget] of budgets) {
+      budgets.set(agentId, { allocated: budget.allocated, consumed: 0 });
+    }
+  }
+
+  /**
+   * Returns a snapshot of all current allocations.
+   * @returns {Map<string, { allocated: number, consumed: number }>}
+   */
+  function listAllocations() {
+    const snap = new Map();
+    for (const [id, b] of budgets) {
+      snap.set(id, Object.freeze({ ...b }));
+    }
+    return snap;
+  }
+
+  return { allocate, consume, getStatus, resetAll, listAllocations };
+}

package/mesh/mesh-heartbeat.mjs

@@ -0,0 +1,100 @@
+const DEFAULT_INTERVAL_MS = 30_000;
+const DEFAULT_THRESHOLD_MS = 60_000;
+
+/**
+ * Creates a heartbeat monitor that tracks agent liveness.
+ *
+ * @param {object} registry - A mesh-registry instance
+ * @param {object} [opts]
+ * @param {number} [opts.intervalMs=30000]   - Scan interval
+ * @param {number} [opts.thresholdMs=60000]  - Stale threshold
+ * @param {function} [opts.onStale]          - Called with agentId when stale detected
+ * @returns {object} HeartbeatMonitor API
+ */
+export function createHeartbeatMonitor(registry, opts = {}) {
+  const {
+    intervalMs = DEFAULT_INTERVAL_MS,
+    thresholdMs = DEFAULT_THRESHOLD_MS,
+    onStale,
+  } = opts;
+
+  /** @type {Map<string, number>} agentId → last heartbeat timestamp */
+  const heartbeats = new Map();
+  let timer = null;
+
+  /**
+   * Records a heartbeat for an agent.
+   * @param {string} agentId
+   */
+  function recordHeartbeat(agentId) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    heartbeats.set(agentId, Date.now());
+  }
+
+  /**
+   * Returns agent IDs whose last heartbeat exceeds the threshold.
+   * Only considers agents currently registered in the registry.
+   *
+   * @param {number} [customThresholdMs] - Override default threshold
+   * @returns {string[]}
+   */
+  function getStaleAgents(customThresholdMs) {
+    const threshold = customThresholdMs ?? thresholdMs;
+    const now = Date.now();
+    const registered = registry.listAll();
+    const stale = [];
+
+    for (const agent of registered) {
+      const lastBeat = heartbeats.get(agent.agentId);
+      if (lastBeat === undefined || (now - lastBeat) >= threshold) {
+        stale.push(agent.agentId);
+      }
+    }
+    return stale;
+  }
+
+  /**
+   * Runs a single scan: finds stale agents and invokes onStale callback.
+   */
+  function scan() {
+    const stale = getStaleAgents();
+    if (typeof onStale === "function") {
+      for (const agentId of stale) {
+        onStale(agentId);
+      }
+    }
+  }
+
+  /**
+   * Starts periodic heartbeat scanning.
+   * @param {number} [customIntervalMs]
+   */
+  function start(customIntervalMs) {
+    stop();
+    const interval = customIntervalMs ?? intervalMs;
+    timer = setInterval(scan, interval);
+    timer.unref?.();
+  }
+
+  /**
+   * Stops periodic scanning.
+   */
+  function stop() {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+
+  /**
+   * Removes heartbeat record for an agent.
+   * @param {string} agentId
+   */
+  function remove(agentId) {
+    heartbeats.delete(agentId);
+  }
+
+  return { recordHeartbeat, getStaleAgents, start, stop, scan, remove };
+}

package/mesh/mesh-protocol.mjs

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+
+export const MSG_TYPES = Object.freeze({
+  REQUEST: "request",
+  RESPONSE: "response",
+  EVENT: "event",
+  HEARTBEAT: "heartbeat",
+});
+
+const VALID_TYPES = new Set(Object.values(MSG_TYPES));
+
+/**
+ * Creates an immutable mesh message.
+ * @param {string} type - One of MSG_TYPES values
+ * @param {string} from - Sender agent ID
+ * @param {string} to - Recipient agent ID (or "*" for broadcast)
+ * @param {unknown} payload - Message payload
+ * @returns {Readonly<object>}
+ */
+export function createMessage(type, from, to, payload = null) {
+  if (!VALID_TYPES.has(type)) {
+    throw new TypeError(`Invalid message type: ${type}`);
+  }
+  if (!from || typeof from !== "string") {
+    throw new TypeError("from must be a non-empty string");
+  }
+  if (!to || typeof to !== "string") {
+    throw new TypeError("to must be a non-empty string");
+  }
+  return Object.freeze({
+    type,
+    from,
+    to,
+    payload,
+    timestamp: new Date().toISOString(),
+    correlationId: randomUUID(),
+  });
+}
+
+/**
+ * Serializes a message to a JSON string.
+ * @param {object} message
+ * @returns {string}
+ */
+export function serialize(message) {
+  return JSON.stringify(message);
+}
+
+/**
+ * Deserializes a JSON string to a message object.
+ * @param {string} raw
+ * @returns {object}
+ */
+export function deserialize(raw) {
+  if (typeof raw !== "string") {
+    throw new TypeError("raw must be a string");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new SyntaxError(`Failed to parse message: ${raw}`);
+  }
+  return parsed;
+}
+
+/**
+ * Validates a message object.
+ * @param {unknown} message
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validate(message) {
+  const errors = [];
+
+  if (!message || typeof message !== "object") {
+    return { valid: false, errors: ["message must be an object"] };
+  }
+
+  if (!VALID_TYPES.has(message.type)) {
+    errors.push(`Invalid type: ${message.type}`);
+  }
+  if (!message.from || typeof message.from !== "string") {
+    errors.push("from must be a non-empty string");
+  }
+  if (!message.to || typeof message.to !== "string") {
+    errors.push("to must be a non-empty string");
+  }
+  if (!message.timestamp || typeof message.timestamp !== "string") {
+    errors.push("timestamp must be a non-empty string");
+  }
+  if (!message.correlationId || typeof message.correlationId !== "string") {
+    errors.push("correlationId must be a non-empty string");
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/mesh/mesh-queue.mjs

@@ -0,0 +1,165 @@
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+const DEFAULT_TTL_MS = 0; // 0 = no expiry
+
+/**
+ * Creates a per-agent message queue with TTL and size limits.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.maxQueueSize=100] - Max messages per agent queue
+ * @param {number} [opts.ttlMs=0]         - Message TTL in ms (0 = no expiry)
+ * @returns {object} Queue API
+ */
+export function createMessageQueue(opts = {}) {
+  const {
+    maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+    ttlMs = DEFAULT_TTL_MS,
+  } = opts;
+
+  /** @type {Map<string, Array<{ message: object, enqueuedAt: number }>>} */
+  const queues = new Map();
+
+  /**
+   * Returns the queue array for an agent (creates if absent).
+   * @param {string} agentId
+   * @returns {Array}
+   */
+  function getQueue(agentId) {
+    let q = queues.get(agentId);
+    if (!q) {
+      q = [];
+      queues.set(agentId, q);
+    }
+    return q;
+  }
+
+  /**
+   * Removes expired messages from the front of a queue.
+   * @param {Array} q
+   * @param {number} now
+   */
+  function purgeExpired(q, now) {
+    if (ttlMs <= 0) return;
+    while (q.length > 0 && (now - q[0].enqueuedAt) > ttlMs) {
+      q.shift();
+    }
+  }
+
+  /**
+   * Adds a message to the target agent's queue.
+   * If queue exceeds maxQueueSize, the oldest message is dropped.
+   *
+   * @param {string} agentId - Target agent
+   * @param {object} message - Mesh message
+   * @returns {{ queued: boolean, dropped: boolean }}
+   */
+  function enqueue(agentId, message) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    const q = getQueue(agentId);
+    const now = Date.now();
+
+    purgeExpired(q, now);
+
+    let dropped = false;
+    if (q.length >= maxQueueSize) {
+      q.shift();
+      dropped = true;
+    }
+
+    q.push({ message, enqueuedAt: now });
+    return { queued: true, dropped };
+  }
+
+  /**
+   * Removes and returns the next message for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object | null} The message, or null if queue is empty
+   */
+  function dequeue(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q.shift().message;
+  }
+
+  /**
+   * Returns the next message without removing it.
+   *
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function peek(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q[0].message;
+  }
+
+  /**
+   * Returns the number of (non-expired) messages in an agent's queue.
+   *
+   * @param {string} agentId
+   * @returns {number}
+   */
+  function size(agentId) {
+    const q = queues.get(agentId);
+    if (!q) return 0;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    return q.length;
+  }
+
+  /**
+   * Drains all messages for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object[]} Array of messages
+   */
+  function drain(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return [];
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    const messages = q.map((entry) => entry.message);
+    q.length = 0;
+    return messages;
+  }
+
+  /**
+   * Removes an agent's queue entirely.
+   * @param {string} agentId
+   */
+  function clear(agentId) {
+    queues.delete(agentId);
+  }
+
+  /**
+   * Returns total message count across all agent queues.
+   * @returns {number}
+   */
+  function totalSize() {
+    let total = 0;
+    const now = Date.now();
+    for (const [, q] of queues) {
+      purgeExpired(q, now);
+      total += q.length;
+    }
+    return total;
+  }
+
+  return { enqueue, dequeue, peek, size, drain, clear, totalSize };
+}

package/mesh/mesh-registry.mjs

@@ -0,0 +1,78 @@
+/**
+ * Creates an agent registry for the mesh network.
+ * Agents register with capabilities; registry enables discovery.
+ * @returns {object} Registry API
+ */
+export function createRegistry() {
+  // Map<agentId, AgentInfo>
+  const agents = new Map();
+
+  /**
+   * Registers an agent with the registry.
+   * @param {string} agentId
+   * @param {string[]} capabilities
+   */
+  function register(agentId, capabilities = []) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    if (!Array.isArray(capabilities)) {
+      throw new TypeError("capabilities must be an array");
+    }
+    const info = Object.freeze({
+      agentId,
+      capabilities: Object.freeze([...capabilities]),
+      registeredAt: new Date().toISOString(),
+    });
+    agents.set(agentId, info);
+  }
+
+  /**
+   * Unregisters an agent from the registry.
+   * @param {string} agentId
+   */
+  function unregister(agentId) {
+    agents.delete(agentId);
+  }
+
+  /**
+   * Discovers agents that have a specific capability.
+   * @param {string} capability
+   * @returns {string[]} Array of agentIds
+   */
+  function discover(capability) {
+    const result = [];
+    for (const [agentId, info] of agents) {
+      if (info.capabilities.includes(capability)) {
+        result.push(agentId);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Gets agent info by ID.
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function getAgent(agentId) {
+    return agents.get(agentId) ?? null;
+  }
+
+  /**
+   * Lists all registered agents.
+   * @returns {object[]}
+   */
+  function listAll() {
+    return [...agents.values()];
+  }
+
+  /**
+   * Clears all registered agents.
+   */
+  function clear() {
+    agents.clear();
+  }
+
+  return { register, unregister, discover, getAgent, listAll, clear };
+}

package/mesh/mesh-router.mjs

@@ -0,0 +1,76 @@
+import { validate } from "./mesh-protocol.mjs";
+
+/**
+ * Routes a mesh message to target agent(s) based on the `to` field.
+ *
+ * Addressing modes:
+ *   - "agent-id"       → direct delivery (registry lookup)
+ *   - "*"              → broadcast to all registered agents
+ *   - "capability:X"   → discover agents with capability X
+ *
+ * @param {object} message  - A mesh-protocol message
+ * @param {object} registry - A mesh-registry instance
+ * @returns {{ routed: boolean, targets?: string[], reason?: string }}
+ */
+export function routeMessage(message, registry) {
+  const { valid, errors } = validate(message);
+  if (!valid) {
+    return { routed: false, reason: `invalid message: ${errors.join(", ")}` };
+  }
+
+  const { to, from } = message;
+
+  // Broadcast
+  if (to === "*") {
+    const all = registry.listAll();
+    const targets = all
+      .map((a) => a.agentId)
+      .filter((id) => id !== from);
+    if (targets.length === 0) {
+      return { routed: false, reason: "broadcast: no agents registered" };
+    }
+    return { routed: true, targets };
+  }
+
+  // Capability-based routing
+  if (to.startsWith("capability:")) {
+    const capability = to.slice("capability:".length);
+    if (!capability) {
+      return { routed: false, reason: "capability: empty capability name" };
+    }
+    const targets = registry.discover(capability);
+    if (targets.length === 0) {
+      return { routed: false, reason: `capability: no agents with "${capability}"` };
+    }
+    return { routed: true, targets };
+  }
+
+  // Direct addressing
+  const agent = registry.getAgent(to);
+  if (!agent) {
+    return { routed: false, reason: `agent not found: "${to}"` };
+  }
+  return { routed: true, targets: [to] };
+}
+
+/**
+ * Routes a message and collects dead-letter info when delivery fails.
+ *
+ * @param {object} message
+ * @param {object} registry
+ * @returns {{ routed: boolean, targets?: string[], deadLetter?: object }}
+ */
+export function routeOrDeadLetter(message, registry) {
+  const result = routeMessage(message, registry);
+  if (!result.routed) {
+    return {
+      ...result,
+      deadLetter: {
+        originalMessage: message,
+        reason: result.reason,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.3.1",
+  "version": "10.3.3",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "scripts",
     "hooks",
     "hud",
+    "mesh",
     ".claude-plugin",
     "README.md",
     "README.ko.md",

package/scripts/claudemd-sync.mjs

@@ -1,21 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 import { TFX_START, OMC_END, writeSection } from "./lib/claudemd-scanner.mjs";
 
-import { execFileSync } from "node:child_process";
-
-function resolveProjectRoot() {
-  // 1. git root (가장 신뢰)
-  try {
-    return execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
-  } catch { /* not a git repo */ }
-  // 2. cwd fallback (npm 사용자 등)
-  return process.cwd();
-}
-
-const PROJECT_ROOT = resolveProjectRoot();
-const PROJECT_CLAUDE_MD_PATH = join(PROJECT_ROOT, "CLAUDE.md");
+const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const GLOBAL_CLAUDE_MD_PATH = join(homedir(), ".claude", "CLAUDE.md");
+const PKG_CLAUDE_MD_PATH = join(PKG_ROOT, "CLAUDE.md");
 const ROUTING_TAG_OPEN = "<routing>";
 const ROUTING_TAG_CLOSE = "</routing>";
 // Legacy heading fallback
@@ -84,18 +75,14 @@ function toSkippedResult(path, reason) {
 }
 
 export function getLatestRoutingTable() {
-  if (!existsSync(PROJECT_CLAUDE_MD_PATH)) {
-    throw new Error(`project CLAUDE.md not found: ${PROJECT_CLAUDE_MD_PATH}`);
+  // 1차: 사용자 글로벌 ~/.claude/CLAUDE.md (어디서든 접근 가능한 공통 경로)
+  for (const candidate of [GLOBAL_CLAUDE_MD_PATH, PKG_CLAUDE_MD_PATH]) {
+    if (!existsSync(candidate)) continue;
+    const section = findRoutingSection(readFileSync(candidate, "utf8"));
+    if (section.found) return section.section.trim();
   }
-
-  const projectMarkdown = readFileSync(PROJECT_CLAUDE_MD_PATH, "utf8");
-  const section = findRoutingSection(projectMarkdown);
-
-  if (!section.found) {
-    throw new Error(`routing section not found in: ${PROJECT_CLAUDE_MD_PATH}`);
-  }
-
-  return section.section.trim();
+  // 2차 fallback: 패키지 CLAUDE.md도 없으면 에러
+  throw new Error(`routing section not found in: ${GLOBAL_CLAUDE_MD_PATH} or ${PKG_CLAUDE_MD_PATH}`);
 }
 
 export function ensureTfxSection(claudeMdPath, routingTable) {

package/scripts/setup.mjs

@@ -968,6 +968,29 @@ if (settingsChanged) {
   }
 }
 
+// ── HUD 캐시 pre-warm (백그라운드) ──
+
+const preWarmHudPath = join(CLAUDE_DIR, "hud", "hud-qos-status.mjs");
+if (existsSync(preWarmHudPath)) {
+  const refreshFlags = [
+    ["--refresh-claude-usage"],
+    ["--refresh-codex-rate-limits"],
+    ["--refresh-gemini-quota", "--account", "gemini-main"],
+    ["--refresh-gemini-session"],
+  ];
+  for (const args of refreshFlags) {
+    try {
+      const child = spawn(process.execPath, [preWarmHudPath, ...args], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.unref();
+    } catch { /* pre-warm 실패 무시 */ }
+  }
+  console.log("  \x1b[32m✓\x1b[0m HUD cache pre-warm (background)");
+}
+
 // ── Stale PID 파일 정리 (hub 좀비 방지) ──
 
 const HUB_PID_FILE = join(CLAUDE_DIR, "cache", "tfx-hub", "hub.pid");