triflux 10.9.0 → 10.9.2

package/bin/triflux.mjs

@@ -1047,14 +1047,13 @@ function cmdSetup(options = {}) {
   }
   {
     const claudeGuide = ensureGlobalClaudeRoutingSection(CLAUDE_DIR);
-    if (claudeGuide.skipped)
+    if (claudeGuide.skipped && claudeGuide.reason !== "global_sync_disabled")
       warn(`CLAUDE.md 라우팅 섹션 확인 실패: ${claudeGuide.reason}`);
     else if (
       claudeGuide.action === "created" ||
       claudeGuide.action === "updated"
     )
       ok("CLAUDE.md: 전역 triflux 라우팅 요약 갱신");
-    else ok("CLAUDE.md: 전역 triflux 라우팅 요약 유지");
   }
 
   // 스킬 동기화 (~/.claude/skills/{name}/SKILL.md)
@@ -1847,7 +1846,7 @@ async function cmdDoctor(options = {}) {
       }
       {
         const claudeGuide = ensureGlobalClaudeRoutingSection(CLAUDE_DIR);
-        if (claudeGuide.skipped)
+        if (claudeGuide.skipped && claudeGuide.reason !== "global_sync_disabled")
           warn(`CLAUDE.md 라우팅 섹션 확인 실패: ${claudeGuide.reason}`);
         else if (
           claudeGuide.action === "created" ||

package/hooks/hook-registry.json

@@ -167,8 +167,8 @@
         "priority": 2,
         "enabled": true,
         "timeout": 8,
-        "blocking": false,
-        "description": "tfx-hub 서비스 헬스체크 및 시작"
+        "blocking": true,
+        "description": "tfx-hub 서비스 헬스체크 및 시작 (BLOCKING — 세션 시작 전 Hub 준비 보장)"
       },
       {
         "id": "tfx-preflight-cache",

package/hooks/session-start-fast.mjs

@@ -4,8 +4,8 @@
 // 6개 훅을 1개 node 프로세스 안에서 실행하여 콜드스타트 7회 → 1회로 줄인다.
 //
 // 분류:
-//   BLOCKING  (직렬, stdout 반환 전 완료): setup.runCritical, mcp-safety-guard.run
-//   DEFERRED  (병렬, 실패해도 안 죽음):   hub-ensure.run, mcp-gateway-ensure.run, setup.runDeferred
+//   BLOCKING  (직렬, stdout 반환 전 완료): setup.runCritical, mcp-safety-guard.run, hub-ensure.run
+//   DEFERRED  (병렬, 실패해도 안 죽음):   mcp-gateway-ensure.run, setup.runDeferred
 //   BACKGROUND (fire-and-forget):          preflight-cache.run
 //
 // external source 훅 (session-vault 등)은 여전히 execFile로 실행된다.
@@ -55,6 +55,24 @@ async function runBlocking(stdinData) {
     log.error({ hook: "mcp-safety-guard", err: String(err.message || err) }, "hook.failed");
   }
 
+  // 3. hub-ensure — Hub 필수 인프라, BLOCKING으로 실행
+  try {
+    const t0 = performance.now();
+    const hubMod = await importMod(join(SCRIPTS, "hub-ensure.mjs"));
+    const result = await hubMod.run(stdinData);
+    const dur = performance.now() - t0;
+    timings.push({ hook: "hub-ensure", dur_ms: Math.round(dur) });
+    if (result?.stdout) output.stdout += result.stdout + "\n";
+    if (result?.stderr) output.stderr += result.stderr + "\n";
+    if (result?.code !== 0) {
+      log.warn({ hook: "hub-ensure", dur_ms: Math.round(dur), code: result?.code }, "hook.warn");
+    } else {
+      log.info({ hook: "hub-ensure", dur_ms: Math.round(dur) }, "hook.completed");
+    }
+  } catch (err) {
+    log.error({ hook: "hub-ensure", err: String(err.message || err) }, "hook.failed");
+  }
+
   return { ...output, timings };
 }
 
@@ -65,13 +83,6 @@ async function runBlocking(stdinData) {
  */
 function runDeferred(stdinData) {
   const tasks = [
-    {
-      name: "hub-ensure",
-      fn: async () => {
-        const mod = await importMod(join(SCRIPTS, "hub-ensure.mjs"));
-        return mod.run(stdinData);
-      },
-    },
     {
       name: "mcp-gateway-ensure",
       fn: async () => {
@@ -134,7 +145,7 @@ export async function execute(stdinData, externalHooks = []) {
   runBackground(stdinData);
 
   const totalDur = performance.now() - totalStart;
-  log.info({ total_ms: Math.round(totalDur), blocking_count: 2, deferred_count: 3, bg_count: 1 }, "session-start.done");
+  log.info({ total_ms: Math.round(totalDur), blocking_count: 3, deferred_count: 2, bg_count: 1 }, "session-start.done");
 
   return {
     stdout: blocking.stdout,

package/hub/pipe.mjs

@@ -125,6 +125,7 @@ export function createPipeServer({
   heartbeatTtlMs = DEFAULT_HEARTBEAT_TTL_MS,
   delegatorService = null,
   hitlManager = null,
+  onActivity = null,
 } = {}) {
   if (!router) {
     throw new Error("router is required");
@@ -164,6 +165,7 @@ export function createPipeServer({
 
   function touchClient(client) {
     client.lastHeartbeatMs = Date.now();
+    if (onActivity) onActivity();
   }
 
   function resolveAgentId(client, payload) {

package/hub/server.mjs

@@ -580,6 +580,7 @@ export async function startHub({
     sessionId,
     delegatorService,
     hitlManager: hitl,
+    onActivity: markRequestActivity,
   });
   const assignCallbacks = createAssignCallbackServer({ store, sessionId });
   const tools = createTools(store, router, hitl, pipe);
@@ -1660,6 +1661,23 @@ if (selfRun) {
   const port = parseInt(process.env.TFX_HUB_PORT || "27888", 10);
   const dbPath = process.env.TFX_HUB_DB || undefined;
 
+  const cleanupPidFile = () => {
+    try {
+      unlinkSync(PID_FILE);
+    } catch {}
+  };
+
+  process.on("unhandledRejection", (err) => {
+    hubLog.fatal({ err }, "hub.unhandledRejection");
+    cleanupPidFile();
+    process.exit(1);
+  });
+  process.on("uncaughtException", (err) => {
+    hubLog.fatal({ err }, "hub.uncaughtException");
+    cleanupPidFile();
+    process.exit(1);
+  });
+
   startHub({ port, dbPath })
     .then((info) => {
       const shutdown = async (signal) => {
@@ -1678,6 +1696,7 @@ if (selfRun) {
     })
     .catch((error) => {
       hubLog.fatal({ err: error }, "hub.start_failed");
+      cleanupPidFile();
       process.exit(1);
     });
 }

package/hub/state.mjs

@@ -256,8 +256,9 @@ export async function acquireLock(options = {}) {
         const raw = readFileSync(lockPath, "utf8");
         const data = parseJson(raw, {});
         const stats = statSync(lockPath);
+        const STALE_LOCK_AGE_MS = 60_000;
         const staleByPid = !isPidAlive(data?.pid);
-        const staleByAge = Date.now() - stats.mtimeMs > timeoutMs;
+        const staleByAge = Date.now() - stats.mtimeMs > STALE_LOCK_AGE_MS;
         if (staleByPid || staleByAge) {
           try {
             unlinkSync(lockPath);

package/hud/hud-qos-status.mjs

@@ -138,9 +138,7 @@ async function main() {
   // 실측 데이터 추출
   const stdin = await stdinPromise;
   const contextView = buildContextUsageView(stdin, contextSnapshot);
-  const claudeUsage = claudeUsageSnapshot.isStale
-    ? { ...(claudeUsageSnapshot.data || {}), stale: true }
-    : claudeUsageSnapshot.data;
+  const claudeUsage = claudeUsageSnapshot.data;
   const codexEmail = getCodexEmail();
   const geminiEmail = getGeminiEmail();
   const codexBuckets = codexSnapshot.buckets;

package/hud/renderers.mjs

@@ -263,8 +263,6 @@ export function getMicroLine(
   combinedSvPct,
 ) {
   const ctxView = contextView || buildContextUsageView({}, null);
-  const staleMarker = claudeUsage?.stale ? ` ${dim("[stale]")}` : "";
-
   // Claude 5h/1w
   const cF =
     claudeUsage?.fiveHourPercent != null
@@ -319,7 +317,7 @@ export function getMicroLine(
     `${bold(codexWhite("x"))}${dim(":")}${xVal} ` +
     `${bold(geminiBlue("g"))}${dim(":")}${gVal} ` +
     `${dim("sv:")}${sv} ` +
-    `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}${staleMarker}`;
+    `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
   return truncateAnsi(line, cols);
 }
 
@@ -334,8 +332,6 @@ export function getClaudeRows(
 ) {
   const ctxView = contextView || buildContextUsageView({}, null);
   const prefix = `${bold(claudeOrange("c"))}:`;
-  const staleMarker = claudeUsage?.stale ? ` ${dim("[stale]")}` : "";
-
   // 절약 퍼센트
   const svStr = formatSvPct(combinedSvPct || 0);
   const svSuffix = `${dim("sv:")}${svStr}`;
@@ -388,18 +384,18 @@ export function getClaudeRows(
       hasData && weeklyPercent != null
         ? colorByProvider(weeklyPercent, `${weeklyPercent}%`, claudeOrange)
         : dim("--");
-    const quotaSection = `${fShort}${dim("/")}${wShort}${staleMarker}`;
+    const quotaSection = `${fShort}${dim("/")}${wShort}`;
     return [{ prefix, left: quotaSection, right: "" }];
   }
 
   if (currentTier === "minimal") {
-    const quotaSection = `${dim("5h:")}${fStr} ${dim("1w:")}${wStr}${staleMarker}`;
+    const quotaSection = `${dim("5h:")}${fStr} ${dim("1w:")}${wStr}`;
     const right = `${dim("CTX:")}${colorByPercent(ctxView.percent, ctxView.display)}`;
     return [{ prefix, left: quotaSection, right }];
   }
 
   if (currentTier === "compact") {
-    const quotaSection = `${dim("5h:")}${fStr} ${dim(fTime)} ${dim("1w:")}${wStr} ${dim(wTime)}${staleMarker}`;
+    const quotaSection = `${dim("5h:")}${fStr} ${dim(fTime)} ${dim("1w:")}${wStr} ${dim(wTime)}`;
     const warning = ctxView.warningTag
       ? ` ${dim("|")} ${yellow(ctxView.warningTag)}`
       : "";
@@ -408,7 +404,7 @@ export function getClaudeRows(
   }
 
   // full tier (>= 120 cols)
-  const quotaSection = `${dim("5h:")}${fBar}${fStr} ${dim(fTime)} ${dim("1w:")}${wBar}${wStr} ${dim(wTime)}${staleMarker}`;
+  const quotaSection = `${dim("5h:")}${fBar}${fStr} ${dim(fTime)} ${dim("1w:")}${wBar}${wStr} ${dim(wTime)}`;
   const warning = ctxView.warningTag
     ? ` ${dim("|")} ${yellow(ctxView.warningTag)}`
     : "";

package/package.json

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

package/scripts/hub-ensure.mjs

@@ -52,12 +52,12 @@ function resolveHubTarget() {
 
 async function isHubHealthy(host, port) {
   try {
-    const res = await fetch(`${buildHubBaseUrl(host, port)}/status`, {
+    const res = await fetch(`${buildHubBaseUrl(host, port)}/health`, {
       signal: AbortSignal.timeout(1000),
     });
     if (!res.ok) return false;
     const data = await res.json();
-    return data?.hub?.state === "healthy";
+    return data?.ok === true;
   } catch {
     return false;
   }
@@ -69,25 +69,13 @@ function startHubDetached(port) {
 
   try {
     const env = { ...process.env, TFX_HUB_PORT: String(port) };
-    if (process.platform === "win32") {
-      const child = spawn(
-        "cmd.exe",
-        ["/c", "start", "/b", "", process.execPath, serverPath],
-        {
-          env,
-          stdio: "ignore",
-          windowsHide: true,
-        },
-      );
-      child.unref();
-    } else {
-      const child = spawn(process.execPath, [serverPath], {
-        env,
-        detached: true,
-        stdio: "ignore",
-      });
-      child.unref();
-    }
+    const child = spawn(process.execPath, [serverPath], {
+      env,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
     return true;
   } catch {
     return false;
@@ -114,13 +102,13 @@ export async function run(stdinData) {
 
   const started = startHubDetached(port);
   if (!started) {
-    return { code: 0, stdout: "", stderr: "[hub-ensure] hub 시작 실패" };
+    return { code: 1, stdout: "", stderr: "[hub-ensure] hub 시작 실패" };
   }
 
-  const ready = await waitForHubReady(host, port, 3000);
+  const ready = await waitForHubReady(host, port, 5000);
   return {
-    code: 0,
-    stdout: ready ? "hub: ok" : "hub: starting",
+    code: ready ? 0 : 2,
+    stdout: ready ? "hub: ok" : "hub: starting (timeout)",
     stderr: "",
   };
 }

package/scripts/tfx-route.sh

@@ -920,7 +920,7 @@ route_agent() {
 TFX_CLI_MODE="${TFX_CLI_MODE:-auto}"
 TFX_NO_CLAUDE_NATIVE="${TFX_NO_CLAUDE_NATIVE:-0}"
 TFX_VERIFIER_OVERRIDE="${TFX_VERIFIER_OVERRIDE:-auto}"
-TFX_CODEX_TRANSPORT="${TFX_CODEX_TRANSPORT:-exec}"
+TFX_CODEX_TRANSPORT="${TFX_CODEX_TRANSPORT:-auto}"
 # Preflight 캐시 일괄 로드 — CLI/Hub 가용성 + Codex 요금제를 환경변수로 내보냄
 # 하위 프로세스(스킬 포함)가 TFX_CODEX_OK, TFX_GEMINI_OK, TFX_HUB_OK로 즉시 참조 가능
 if [[ -z "${TFX_PREFLIGHT_LOADED:-}" ]]; then

package/skills/tfx-auto/SKILL.md

@@ -93,21 +93,22 @@ dispatch 시 해당 스킬을 Skill 도구로 호출하고 **이 워크플로우
 > 2. **비용**: Codex 우선 → Gemini → Claude 최후 수단. `claude` 선택 전 "Codex로 가능한가?" 재확인.
 > 3. **DAG**: SEQUENTIAL/DAG이면 레벨 기반 순차 실행. `.omc/context/{sid}/` 생성, context_output 저장, 실패 시 후속 SKIP.
 > 4. **트리아지**: Codex `exec --full-auto` 분류 + Opus 인라인 분해. Agent 스폰 금지.
-> 5. **thorough**: `-t`/`--thorough` 시 파이프라인 init 필수. 커맨드 숏컷은 항상 quick.
+> 5. **thorough 기본**: `--thorough`가 기본. Opus가 규모(S/M)·커맨드 숏컷 판단 시 자동 경량화 가능. `--quick`은 명시적 옵트아웃.
 > 6. **직접 수정 금지**: implement/review/analyze 등 커맨드 숏컷 실행 시 절대로 Edit/Write 도구로 직접 코드를 수정하지 마라. 반드시 Bash(tfx-route.sh)를 통해 Codex/Gemini에 위임하라. 작업이 아무리 사소해도 예외 없음.
 
 ## 모드
 
 | 입력 형식 | 모드 | 트리아지 |
 |-----------|------|----------|
-| `/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 분해만 |
+| `/implement JWT 추가` | 커맨드 숏컷 (thorough) | Opus 판단 → 규모 S면 자동 경량화 |
+| `/tfx-auto "리팩터링 + UI"` | 자동 (thorough) | Codex 분류 → Opus 분해 → Pipeline |
+| `/tfx-auto -q "빠르게 수정"` | 자동 (quick) | Opus 분해만, plan/verify 생략 |
+| `/tfx-auto --quick "빠르게"` | 자동 (quick) | `-q` 동일 |
+| `/tfx-auto 3:codex "리뷰"` | 수동 (thorough) | Opus 분해 + Pipeline |
 
-> **tfx-auto는 `--quick`이 기본.** 커맨드 숏컷·단일 실행에서 plan/verify 오버헤드가 불필요하기 때문.
-> 멀티 태스크 시 tfx-multi로 전환되면 tfx-multi의 기본값(`--thorough`)이 적용된다.
+> **tfx-auto는 `--thorough`가 기본.** 모든 작업에 plan/verify 파이프라인을 적용한다.
+> Opus가 규모(S)·단순 커맨드 숏컷으로 판단하면 자동 경량화(plan/verify 생략)한다.
+> 명시적 `--quick`/`-q`로 강제 경량화 가능.
 
 ## 커맨드 숏컷
 
@@ -168,16 +169,16 @@ dispatch 시 해당 스킬을 Skill 도구로 호출하고 **이 워크플로우
 
 **수동 모드 (`N:agent_type`):** Codex 분류 건너뜀 → Opus가 N개 서브태스크 분해. N > 10 거부.
 
-## --thorough 모드
+## 파이프라인 (기본: thorough)
 
-`-t` 또는 `--thorough` 플래그 시 파이프라인 기반 실행. 커맨드 숏컷에서는 무시된다.
+`--thorough`가 기본. `--quick`/`-q` 명시 시 경량화. Opus가 규모 S·단순 숏컷으로 판단 시 자동 경량화.
 
 ```
 분기점은 "실행 전략"이지 "계획"이 아님:
 
 TRIAGE
   │
-  ├─ [thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
+  ├─ [기본/thorough] → PIPELINE INIT(plan) → PLAN → PRD → [APPROVAL]
   │                                                      │
   │                                      ┌───────────────┤
   │                                      │               │
@@ -189,8 +190,10 @@ TRIAGE
   │                                              │
   │                                          VERIFY → FIX loop → COMPLETE
   │
-  └─ [quick] → [1 task] → fire-and-forget
-               [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
+  ├─ [Opus 자동 경량화] → 규모 S + 단일 파일 → fire-and-forget (plan/verify 생략)
+  │
+  └─ [--quick 명시] → [1 task] → fire-and-forget
+                      [2+ tasks] → TEAM EXEC → COLLECT → CLEANUP
 ```
 
 ### 단일 태스크 thorough
@@ -216,10 +219,11 @@ Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
 
 | 조건 | 실행 경로 | 엔진 |
 |------|----------|------|
-| 1개 + quick | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
-| 1개 + thorough | tfx-auto 직접 실행 + verify/fix loop | tfx-route.sh |
-| 2개+ + quick | **headless 직접 실행** (WT 자동 팝업) | headless.mjs |
-| 2개+ + thorough | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
+| 1개 (기본 thorough) | tfx-auto 직접 실행 + verify/fix loop | tfx-route.sh |
+| 1개 + Opus 자동 경량화 | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
+| 1개 + `--quick` 명시 | tfx-auto 직접 실행 (fire-and-forget) | tfx-route.sh |
+| 2개+ (기본 thorough) | Plan/PRD/Approval 후 → headless + verify/fix | headless.mjs |
+| 2개+ + `--quick` 명시 | **headless 직접 실행** (WT 자동 팝업) | headless.mjs |
 | psmux 미설치 fallback | Native Teams (Agent slim wrapper) | native.mjs |
 
 > **MANDATORY: 2개+ 서브태스크 시 headless 엔진 필수**
@@ -229,19 +233,19 @@ Plan/PRD/Approval은 tfx-auto에서 실행, 그 후 tfx-multi Phase 3로 전환.
 **전환 방법:**
 
 ```
-thorough = args에 -t 또는 --thorough 포함
+quick = args에 -q 또는 --quick 명시, 또는 Opus 자동 경량화 판단
 
 if subtasks.length >= 2:
   if psmux 설치됨:
     → Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign 'cli:prompt:role' ...")
-    → if thorough: verify → fix loop
+    → if !quick: verify → fix loop
   else:
     → fallback: tfx-multi Phase 3 Native Teams (Agent slim wrapper)
 else:
-  if thorough:
-    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
+  if quick:
+    → tfx-auto 직접 실행 (fire-and-forget)
   else:
-    → tfx-auto 직접 실행 (아래)
+    → Pipeline init → Plan → PRD → Approval → 직접 실행 → Verify → Fix loop
 ```
 
 ## 실행

package/skills/tfx-hub/SKILL.md

@@ -1,70 +1,124 @@
 ---
 name: tfx-hub
 description: >
-  tfx-hub MCP 메시지 버스 관리. CLI 에이전트 간 실시간 통신 허브를 시작/중지/상태확인하고,
-  hub 도메인의 자유형 작업도 처리합니다.
+  tfx-hub MCP 메시지 버스 관리. AskUserQuestion 기반 인터랙티브 UI로
+  허브 시작/중지/상태확인, MCP 서버 관리, 에이전트 조회, 파이프라인 조회를 수행합니다.
   Use when: hub, 허브, 메시지 버스, message bus, 브릿지, bridge, MCP 서버 관리, 에이전트 통신
 triggers:
   - tfx-hub
-argument-hint: "<start|stop|status|자유형 작업 설명>"
+argument-hint: "<start|stop|status|mcp|자유형 작업 설명>"
 ---
 
-# tfx-hub — MCP 메시지 버스 관리 + 개방형 작업
+# tfx-hub — MCP 메시지 버스 관리
 
-> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여
-> 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.
-
-
-> **인프라**: 다른 스킬이 내부적으로 사용. 직접 호출할 필요 없음.
-> CLI 에이전트(Codex/Gemini/Claude) 간 실시간 메시지 허브를 관리합니다.
-> **커맨드 매칭 + fallthrough**: start/stop/status에 매칭되면 즉시 실행,
-> 매칭 안 되면 **hub 도메인 컨텍스트를 활용한 범용 작업**으로 처리합니다.
+> **ARGUMENTS 처리**: `ARGUMENTS: <값>`과 함께 호출되면 해당 값을 입력으로 사용한다.
+> start/stop/status/mcp에 매칭되면 즉시 실행, 나머지는 메인 메뉴를 표시한다.
 
 ## 입력 해석 규칙
 
 ```
-/tfx-hub start          → 커맨드 매칭 → 허브 시작
-/tfx-hub stop           → 커맨드 매칭 → 허브 중지
-/tfx-hub status         → 커맨드 매칭 → 상태 확인
-/tfx-hub 테스트해줘      → fallthrough → hub 관련 범용 작업으로 처리
-/tfx-hub 문서 저장해     → fallthrough → hub 관련 범용 작업으로 처리
-/tfx-hub 브릿지 분석해   → fallthrough → hub 관련 범용 작업으로 처리
+/tfx-hub start   → 즉시 실행: 허브 시작
+/tfx-hub stop    → 즉시 실행: 허브 중지
+/tfx-hub status  → 즉시 실행: 상태 확인
+/tfx-hub mcp     → 즉시 실행: MCP 서버 목록
+/tfx-hub         → 메인 메뉴 표시
+/tfx-hub 뭔가    → fallthrough: hub 도메인 범용 작업
 ```
 
-**fallthrough 규칙**: 인자가 start/stop/status/--port 등 커맨드 키워드에 매칭되지 않으면,
-사용자의 입력을 **hub/브릿지/메시지버스 도메인의 자유형 작업**으로 해석한다.
+## 워크플로우
+
+### Step 0: 허브 상태 사전 확인
+
+메뉴 표시 전 허브 실행 상태를 먼저 확인한다:
 
-fallthrough 라우팅:
 ```bash
-# tfx-route.sh 경유 (권장)
-Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{hub 컨텍스트 + 작업}' {mcp_profile}")
+Bash("curl -sf http://127.0.0.1:27888/status 2>/dev/null | node -e \"const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(JSON.stringify({running:true, uptime_ms:d.hub.uptime_ms, sessions:d.sessions, queues:d.queues, assigns:d.assigns}))\" 2>/dev/null || echo '{\"running\":false}'")
+```
 
-# codex 직접 호출 시 — 반드시 exec 서브커맨드 포함
-Bash("codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
-Bash("codex --profile gpt54_xhigh exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check '{작업}'")
-#          ↑ --profile은 exec 앞에, --skip-git-repo-check은 exec 뒤에
+결과를 `hubState` 변수로 저장한다.
+
+### Step 1: 메인 메뉴 (AskUserQuestion)
 
-# Claude 네이티브 (탐색/검증)
-Agent(subagent_type="oh-my-claudecode:explore", prompt="{작업}")
 ```
+question: "tfx-hub 관리 — 어떤 작업을 수행하시겠습니까?"
+header: "tfx-hub {hubState.running ? '● 실행 중' : '○ 중지됨'} | 세션: {sessions} | 큐: urgent {queues.urgent_depth} / normal {queues.normal_depth} / DLQ {queues.dlq_depth}"
+options:
+  - label: "허브 상태 보기"
+    description: "상세 상태 — 에이전트, 큐, 파이프라인, assign 현황"
+  - label: "허브 시작"
+    description: "MCP 서버를 :27888에서 시작"
+  - label: "허브 중지"
+    description: "실행 중인 허브 프로세스 종료"
+  - label: "MCP 서버 관리"
+    description: "등록된 MCP 서버 목록 조회, 추가, 제거"
+  - label: "파이프라인 조회"
+    description: "활성 파이프라인 목록 + 상태"
+  - label: "Assign 작업 조회"
+    description: "비동기 작업 목록 + 상태"
+  - label: "DLQ 관리"
+    description: "Dead Letter Queue 조회 + 재시도/삭제"
+```
+
+허브가 중지됨 상태라면 "허브 시작" 외 항목 선택 시 "허브가 실행 중이 아닙니다. 먼저 시작하시겠습니까?" 확인을 표시한다.
 
-## 커맨드
+### Step 2: 선택에 따른 분기
 
-### start — 허브 시작
+#### "허브 상태 보기"
+
+```bash
+Bash("curl -s http://127.0.0.1:27888/status 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+```
+
+결과를 파싱하여 표시:
+
+```markdown
+## Hub Status
+
+| 항목 | 값 |
+|------|-----|
+| 상태 | ● healthy |
+| Uptime | 22m 3s |
+| PID | 24504 |
+| 포트 | 27888 |
+| 인증 | localhost-only |
+| 세션 | 0 |
+
+### 큐
+| urgent | normal | DLQ |
+|--------|--------|-----|
+| 0      | 0      | 10  |
+
+### Assign
+| queued | running | failed | timed_out |
+|--------|---------|--------|-----------|
+| 0      | 0       | 0      | 1         |
+```
+
+표시 후 메인 메뉴로 돌아갈지 AskUserQuestion:
+```
+question: "추가 작업이 있으십니까?"
+options:
+  - label: "메인 메뉴로"
+  - label: "종료"
+```
+
+#### "허브 시작"
 
 ```bash
 Bash("node hub/server.mjs", run_in_background=true)
 ```
 
-- Streamable HTTP MCP 서버를 `http://127.0.0.1:27888/mcp` 에서 시작
-- SQLite WAL DB: `~/.claude/cache/tfx-hub/state.db`
-- PID 파일: `~/.claude/cache/tfx-hub/hub.pid`
-- 환경변수: `TFX_HUB_PORT` (포트), `TFX_HUB_DB` (DB 경로)
+시작 후 2초 대기하여 상태 확인:
+```bash
+Bash("sleep 2 && curl -sf http://127.0.0.1:27888/status >/dev/null 2>&1 && echo 'OK' || echo 'FAIL'")
+```
+
+- OK → "허브가 시작되었습니다. http://127.0.0.1:27888"
+- FAIL → "허브 시작에 실패했습니다. `node hub/server.mjs`를 직접 실행해 보세요."
 
-### stop — 허브 중지
+#### "허브 중지"
 
 ```bash
-# PID 파일에서 프로세스 ID 읽어서 종료
 Bash("node -e \"
   const fs = require('fs');
   const path = require('path');
@@ -79,31 +133,179 @@ Bash("node -e \"
 \"")
 ```
 
-### status — 상태 확인
+#### "MCP 서버 관리"
+
+먼저 현재 등록된 MCP 서버 목록을 수집:
 
 ```bash
-# HTTP 상태 엔드포인트 조회
-Bash("curl -s http://127.0.0.1:27888/status 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+Bash("claude mcp list 2>/dev/null")
+```
+
+결과를 파싱하여 테이블로 표시:
+
+```markdown
+## 등록된 MCP 서버
+
+| # | 이름 | 상태 | 명령어 |
+|---|------|------|--------|
+| 1 | context7 | ✓ Connected | cmd /c npx -y @upstash/context7-mcp@latest |
+| 2 | exa | ✓ Connected | cmd /c npx -y exa-mcp-server |
+| 3 | powerpoint | ✓ Connected | uvx ppt-mcp |
+| ... | ... | ... | ... |
+```
+
+그 후 AskUserQuestion:
+```
+question: "MCP 서버 관리 — 어떤 작업을 하시겠습니까?"
+header: "MCP Servers ({connected}개 연결 / {failed}개 실패 / {disabled}개 비활성)"
+options:
+  - label: "서버 제거"
+    description: "등록된 서버를 선택하여 제거"
+  - label: "서버 추가"
+    description: "새 MCP 서버 등록"
+  - label: "실패한 서버 재시작"
+    description: "연결 실패 서버를 재시작 시도"
+  - label: "뒤로"
+    description: "메인 메뉴로 돌아가기"
+```
+
+##### "서버 제거" 선택 시
+
+AskUserQuestion (multiSelect):
+```
+question: "제거할 서버를 선택하세요"
+header: "MCP 서버 제거"
+options:
+  (등록된 서버를 각각 옵션으로 나열)
+  - label: "powerpoint"
+    description: "[local] uvx ppt-mcp — ✓ Connected"
+  - label: "stability-ai"
+    description: "[local] npx -y mcp-server-stability-ai — ✘ Failed"
+  ...
+multiSelect: true
+```
+
+선택된 서버들을 제거:
+```bash
+Bash("claude mcp remove '{서버명}' -s {scope}")
+```
+
+제거 후 결과 표시.
+
+##### "서버 추가" 선택 시
+
+AskUserQuestion:
+```
+question: "추가할 서버 유형을 선택하세요"
+header: "MCP 서버 추가"
+options:
+  - label: "stdio (npx/uvx)"
+    description: "npx, uvx 등 stdio 기반 서버"
+  - label: "SSE/HTTP"
+    description: "URL 기반 원격 서버"
+```
+
+stdio 선택 시 AskUserQuestion:
+```
+question: "서버 이름과 명령어를 입력하세요 (예: myserver -- cmd /c npx -y my-mcp-server)"
+header: "stdio 서버 추가"
+```
+
+입력값을 파싱하여:
+```bash
+Bash("claude mcp add '{name}' -s local -- {command}")
+```
+
+SSE/HTTP 선택 시 AskUserQuestion:
+```
+question: "서버 이름과 URL을 입력하세요 (예: myserver http://localhost:8080/mcp)"
+header: "HTTP 서버 추가"
+```
+
+입력값을 파싱하여:
+```bash
+Bash("claude mcp add --transport http '{name}' '{url}' -s local")
+```
+
+##### "실패한 서버 재시작" 선택 시
+
+`claude mcp list` 결과에서 Failed 서버만 필터:
+
+```
+question: "재시작할 서버를 선택하세요"
+header: "실패한 MCP 서버"
+options:
+  (Failed 서버만 나열)
+multiSelect: true
+```
+
+선택된 서버를 제거 후 재등록하여 재시작.
+
+#### "파이프라인 조회"
+
+```bash
+Bash("curl -s http://127.0.0.1:27888/bridge/pipeline/list -X POST -H 'Content-Type: application/json' -d '{}' 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+```
+
+결과를 테이블로 표시.
+
+#### "Assign 작업 조회"
+
+```bash
+Bash("curl -s http://127.0.0.1:27888/bridge/assign/status -X POST -H 'Content-Type: application/json' -d '{\"list\":true}' 2>/dev/null || echo '{\"error\":\"hub 미실행\"}'")
+```
+
+결과를 테이블로 표시. 실패 작업이 있으면 재시도 옵션 제공.
+
+#### "DLQ 관리"
+
+```bash
+Bash("curl -s http://127.0.0.1:27888/status 2>/dev/null | node -e \"const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log('DLQ depth: '+d.queues.dlq_depth)\"")
 ```
 
-## 각 CLI 등록 방법
+DLQ가 비어있으면 "DLQ가 비어있습니다." 표시.
+내용이 있으면 AskUserQuestion:
+```
+question: "DLQ 처리 — 어떻게 하시겠습니까?"
+header: "Dead Letter Queue ({count}건)"
+options:
+  - label: "전체 조회"
+    description: "DLQ 메시지 목록 표시"
+  - label: "전체 재시도"
+    description: "모든 DLQ 메시지를 다시 큐에 넣기"
+  - label: "전체 삭제"
+    description: "DLQ 비우기"
+  - label: "뒤로"
+```
+
+## fallthrough 라우팅
+
+메인 메뉴 항목에 매칭되지 않는 자유형 입력은 hub 도메인 컨텍스트 범용 작업으로 처리:
+
+```bash
+# tfx-route.sh 경유 (권장)
+Bash("bash ~/.claude/scripts/tfx-route.sh {에이전트} '{hub 컨텍스트 + 작업}' {mcp_profile}")
+
+# Claude 네이티브 (탐색/검증)
+Agent(subagent_type="oh-my-claudecode:explore", prompt="{작업}")
+```
+
+## CLI 등록 방법
 
 허브 시작 후 각 CLI에 MCP 서버로 등록:
 
 ```bash
-# Codex (수동 opt-in 예시)
-# triflux는 config.json을 자동 관리하며, standalone Codex 노이즈 방지를 위해
-# 사전 등록은 disabled로 두고 `tfx hub start` 이후에만 enabled로 전환한다.
+# Claude
+claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
+
+# Codex
 codex mcp add tfx-hub --url http://127.0.0.1:27888/mcp
 
 # Gemini (settings.json)
 # mcpServers.tfx-hub.url = "http://127.0.0.1:27888/mcp"
-
-# Claude
-claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
 ```
 
-## MCP 도구 (20개)
+## MCP 도구 레퍼런스 (20개)
 
 ### Core — 기본 통신
 
@@ -150,14 +352,25 @@ claude mcp add --transport http tfx-hub http://127.0.0.1:27888/mcp
 | `request_human_input` | 사용자 입력 요청 (CAPTCHA/승인/자격증명/선택/텍스트) |
 | `submit_human_input` | 사용자 입력 응답 (accept/decline/cancel) |
 
-## 브릿지 REST 엔드포인트 (4개)
+## CLI 대응
 
-| 엔드포인트 | 설명 |
-|-----------|------|
-| `POST /bridge/register` | 에이전트 등록 (프로세스 수명 기반 lease) |
-| `POST /bridge/result` | 결과 발행 (topic fanout) |
-| `POST /bridge/context` | 선행 컨텍스트 폴링 (auto_ack) |
-| `POST /bridge/deregister` | 에이전트 offline 마킹 |
+| 스킬 UI | CLI 명령 |
+|---------|---------|
+| 허브 상태 보기 | `curl http://127.0.0.1:27888/status` |
+| 허브 시작 | `node hub/server.mjs` |
+| 허브 중지 | PID 파일에서 kill |
+| MCP 서버 목록 | `claude mcp list` |
+| MCP 서버 추가 | `claude mcp add ...` |
+| MCP 서버 제거 | `claude mcp remove ...` |
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| 허브 미실행 상태에서 조회 | "허브가 실행 중이 아닙니다. 시작하시겠습니까?" AskUserQuestion |
+| curl 타임아웃 | "허브가 응답하지 않습니다. PID 파일을 확인하세요." |
+| MCP 서버 추가 실패 | 에러 메시지 표시 + "다시 시도" 옵션 |
+| PID 파일 없음 | "허브가 실행 중이 아닙니다." |
 
 ## 프로젝트 구조
 
@@ -170,41 +383,16 @@ hub/
 ├── hitl.mjs              # Human-in-the-Loop 매니저
 ├── bridge.mjs            # tfx-route.sh ↔ hub 브릿지 CLI
 ├── schema.sql            # DB 스키마
-├── paths.mjs             # 경로 상수 (PID 파일, DB 경로 등)
-├── pipe.mjs              # Named Pipe 서버 (push 구독 채널)
-├── assign-callbacks.mjs  # assign job 콜백 처리
-├── intent.mjs            # 인텐트 파싱
-├── reflexion.mjs         # reflexion 루프
-├── research.mjs          # 리서치 프록시
-├── token-mode.mjs        # 토큰 모드 관리
+├── paths.mjs             # 경로 상수
+├── pipe.mjs              # Named Pipe 서버
+├── assign-callbacks.mjs  # assign job 콜백
 ├── pipeline/             # 파이프라인 엔진
-│   ├── index.mjs         # createPipeline() 팩토리
-│   ├── state.mjs         # 파이프라인 상태 CRUD
-│   ├── transitions.mjs   # 전이 규칙
-│   └── gates/            # HITL 게이트 (selfcheck, confidence)
 ├── delegator/            # 작업 위임 레이어
-│   ├── index.mjs
-│   ├── service.mjs
-│   ├── contracts.mjs
-│   └── tool-definitions.mjs
 ├── team/                 # Claude Native Teams 통합
-│   ├── nativeProxy.mjs   # Teams MCP 프록시
-│   ├── orchestrator.mjs  # 팀 오케스트레이터
-│   ├── session.mjs       # 세션 관리
-│   ├── dashboard.mjs     # TUI 대시보드
-│   ├── tui.mjs           # TUI 렌더러
-│   └── cli/              # tfx team CLI 커맨드
 ├── workers/              # CLI 워커 어댑터
-│   ├── factory.mjs
-│   ├── claude-worker.mjs
-│   ├── codex-mcp.mjs
-│   ├── gemini-worker.mjs
-│   └── delegator-mcp.mjs
-├── middleware/           # 요청 미들웨어
-│   └── request-logger.mjs
+├── middleware/            # 요청 미들웨어
 ├── quality/              # 품질 검사
-│   └── deslop.mjs
-└── public/               # 정적 자산 (대시보드 HTML, 트레이 아이콘)
+└── public/               # 정적 자산
 ```
 
 ## 상태

package/skills/tfx-hub/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "tfx-hub",
-  "description": "tfx-hub MCP 메시지 버스 관리. CLI 에이전트 간 실시간 통신 허브를 시작/중지/상태확인하고, hub 도메인의 자유형 작업도 처리합니다. Use when: hub, 허브, 메시지 버스, message bus, 브릿지, bridge, MCP 서버 관리, 에이전트 통신",
+  "description": "tfx-hub MCP 메시지 버스 관리. AskUserQuestion 기반 인터랙티브 UI로 허브 시작/중지/상태확인, MCP 서버 관리, 에이전트 조회, 파이프라인 조회를 수행합니다. Use when: hub, 허브, 메시지 버스, message bus, 브릿지, bridge, MCP 서버 관리, 에이전트 통신",
   "triggers": ["tfx-hub"],
-  "argument_hint": "<start|stop|status|자유형 작업 설명>"
+  "argument_hint": "<start|stop|status|mcp|자유형 작업 설명>"
 }