triflux 9.7.14 → 9.8.1

package/README.ko.md

@@ -319,6 +319,8 @@ tfx setup
 /tfx-multi "refactor auth + update UI + add tests"
 ```
 > **참고**: Deep 스킬(`/tfx-deep-*`, `/tfx-persist`, `/tfx-ralph`)은 완전한 Tri-CLI 합의(Tier 1)를 위해 **psmux**(또는 tmux), **triflux Hub**, **Codex CLI**, **Gemini CLI**가 필요합니다. 전제조건이 충족되지 않으면 Tier 3(Claude 단독, single-model) 모드로 자동 전환됩니다. `tfx doctor`로 환경을 확인하세요.
+>
+> **Serena 참고**: Serena MCP는 stateful합니다. 따라서 **같은 프로젝트**를 다루는 에이전트끼리만 하나의 Serena 인스턴스를 공유하는 것이 안전합니다. 서로 다른 프로젝트를 병렬로 작업할 때는 Serena 인스턴스를 분리하세요. Serena가 `No active project`를 보고하면 Codex Serena 설정의 `--project-from-cwd`(또는 `--project <path>`)를 확인하고 `tfx doctor`를 다시 실행하세요.
 
 ---
 

package/README.md

@@ -319,6 +319,8 @@ tfx setup
 /tfx-multi "refactor auth + update UI + add tests"
 ```
 > **Note**: Deep skills (`/tfx-deep-*`, `/tfx-persist`, `/tfx-ralph`) require **psmux** (or tmux), **triflux Hub**, **Codex CLI**, and **Gemini CLI** for full Tri-CLI consensus (Tier 1). Without these prerequisites, skills automatically degrade to Tier 3 (Claude-only, single-model) mode. Run `tfx doctor` to check your environment.
+>
+> **Serena note**: Serena MCP is stateful. Share one Serena instance only across agents working on the **same project**. For parallel work across different projects, prefer separate Serena instances. If Serena reports `No active project`, check your Codex Serena config for `--project-from-cwd` (or `--project <path>`) and rerun `tfx doctor`.
 
 ---
 

package/bin/triflux.mjs

@@ -2,7 +2,7 @@
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, readSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, statSync, openSync, closeSync } from "fs";
 import { join, dirname, basename } from "path";
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
 import { execSync, execFileSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
 import { setTimeout as delay } from "node:timers/promises";
@@ -12,6 +12,7 @@ import { forceCleanupTeam } from "../hub/team/nativeProxy.mjs";
 import { cleanupStaleOmcTeams, inspectStaleOmcTeams } from "../hub/team/staleState.mjs";
 import { getPipelineStateDbPath } from "../hub/pipeline/state.mjs";
 import { ensureGeminiProfiles } from "../scripts/lib/gemini-profiles.mjs";
+import { probePsmuxSupport, formatPsmuxInstallGuidance, formatPsmuxUpdateGuidance } from "../scripts/lib/psmux-info.mjs";
 import {
   addRegistryServer,
   inspectRegistry,
@@ -25,6 +26,7 @@ import {
   syncAliasedSkillDir, hasProfileSection, replaceProfileSection,
   ensureCodexProfiles, getVersion, cleanupStaleSkills, DEPRECATED_SKILLS,
   extractManagedHookFilename, getManagedRegistryHooks, ensureHooksInSettings,
+  ensureCodexHubServerConfig,
 } from "../scripts/setup.mjs";
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -809,7 +811,7 @@ function cmdSetup(options = {}) {
   // hub MCP 사전 등록 (서버 미실행이어도 설정만 등록 — hub start 시 즉시 사용 가능)
   if (existsSync(join(PKG_ROOT, "hub", "server.mjs"))) {
     const defaultHubUrl = `http://127.0.0.1:${process.env.TFX_HUB_PORT || "27888"}/mcp`;
-    autoRegisterMcp(defaultHubUrl);
+    autoRegisterMcp(defaultHubUrl, { codexEnabled: false });
     summary.push({ item: "Hub MCP", status: "✅", detail: "등록됨" });
     console.log("");
   }
@@ -954,11 +956,41 @@ function computeHookCoverage(settings, managedHooks) {
     total: managedHooks.length,
     registered: 0,
     missing: [],
+    duplicates: [],
   };
 
   const hooksByEvent = settings?.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+
+  // 이벤트별 orchestrator 존재 여부를 캐시
+  const orchestratorByEvent = {};
+  for (const [event, entries] of Object.entries(hooksByEvent)) {
+    orchestratorByEvent[event] = Array.isArray(entries) && entries.some((entry) =>
+      Array.isArray(entry?.hooks) &&
+      entry.hooks.some((hook) =>
+        typeof hook?.command === "string" && hook.command.includes("hook-orchestrator"),
+      ),
+    );
+  }
+
   for (const spec of managedHooks) {
     const eventEntries = Array.isArray(hooksByEvent[spec.event]) ? hooksByEvent[spec.event] : [];
+
+    // orchestrator가 있으면 registry 훅을 체이닝하므로 "registered"로 간주
+    if (orchestratorByEvent[spec.event]) {
+      coverage.registered++;
+
+      // 동시에 개별 훅도 직접 등록되어 있으면 → 이중 실행 (duplicate)
+      const directlyRegistered = eventEntries.some((entry) =>
+        Array.isArray(entry?.hooks) &&
+        entry.hooks.some((hook) => extractManagedHookFilename(hook?.command) === spec.fileName),
+      );
+      if (directlyRegistered) {
+        coverage.duplicates.push(toHookCoverageName(spec.fileName, spec.id));
+      }
+      continue;
+    }
+
+    // orchestrator 없으면 기존 방식: 개별 훅 직접 등록 확인
     const found = eventEntries.some((entry) =>
       Array.isArray(entry?.hooks) &&
       entry.hooks.some((hook) => extractManagedHookFilename(hook?.command) === spec.fileName),
@@ -1004,6 +1036,48 @@ function getOptionValue(args, optionName) {
   return args[index + 1] ?? null;
 }
 
+function extractTomlSection(content, sectionName) {
+  const lines = String(content ?? "").split(/\r?\n/);
+  const header = `[${sectionName}]`;
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) return "";
+  const collected = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*\[.+\]\s*$/.test(line)) break;
+    collected.push(line);
+  }
+  return collected.join("\n");
+}
+
+function inspectSerenaMcpConfig(configContent) {
+  const section = extractTomlSection(configContent, "mcp_servers.serena");
+  if (!section.trim()) {
+    return {
+      present: false,
+      hasProjectBinding: false,
+      hasContextCodex: false,
+      startupTimeoutSec: null,
+      timeoutRecommended: false,
+    };
+  }
+
+  const hasProjectBinding = section.includes("--project-from-cwd")
+    || /--project(?:\s|=|")/.test(section);
+  const hasContextCodex = /--context(?:\s|",\s*")?codex/i.test(section) || /"codex"/i.test(section);
+  const timeoutMatch = section.match(/startup_timeout_sec\s*=\s*([0-9.]+)/i);
+  const startupTimeoutSec = timeoutMatch ? Number(timeoutMatch[1]) : null;
+  const timeoutRecommended = startupTimeoutSec !== null && startupTimeoutSec >= 30;
+
+  return {
+    present: true,
+    hasProjectBinding,
+    hasContextCodex,
+    startupTimeoutSec,
+    timeoutRecommended,
+  };
+}
+
 function statusBadge(status) {
   switch (status) {
     case "present":
@@ -1348,6 +1422,69 @@ async function cmdDoctor(options = {}) {
       }
     }
 
+    // 4.5 Serena MCP
+    section("Serena MCP");
+    if (existsSync(CODEX_CONFIG_PATH)) {
+      const codexConfig = readFileSync(CODEX_CONFIG_PATH, "utf8");
+      const serenaConfig = inspectSerenaMcpConfig(codexConfig);
+      if (!serenaConfig.present) {
+        warn("serena MCP 설정 없음");
+        info("권장: [mcp_servers.serena]에 --project-from-cwd, --context codex, startup_timeout_sec=30+ 설정");
+        addDoctorCheck(report, {
+          name: "serena-mcp",
+          status: "missing",
+          path: CODEX_CONFIG_PATH,
+          fix: "Codex config에 Serena MCP 설정을 추가하세요.",
+        });
+        issues++;
+      } else {
+        const hasSerenaIssues = !serenaConfig.hasProjectBinding || !serenaConfig.timeoutRecommended;
+
+        if (serenaConfig.hasProjectBinding) ok("project binding: 정상");
+        else {
+          warn("project binding 없음");
+          info("권장: --project-from-cwd 또는 --project <path>");
+          issues++;
+        }
+
+        if (serenaConfig.hasContextCodex) info("context codex: 설정됨");
+        else info("context codex: 미설정");
+
+        if (serenaConfig.startupTimeoutSec === null) {
+          warn("startup_timeout_sec 미설정");
+          info("권장: startup_timeout_sec = 30 이상");
+          issues++;
+        } else if (serenaConfig.timeoutRecommended) {
+          ok(`startup timeout: ${serenaConfig.startupTimeoutSec}s`);
+        } else {
+          warn(`startup timeout 낮음: ${serenaConfig.startupTimeoutSec}s`);
+          info("권장: startup_timeout_sec = 30 이상");
+          issues++;
+        }
+
+        addDoctorCheck(report, {
+          name: "serena-mcp",
+          status: hasSerenaIssues ? "issues" : "ok",
+          path: CODEX_CONFIG_PATH,
+          project_binding: serenaConfig.hasProjectBinding,
+          context_codex: serenaConfig.hasContextCodex,
+          startup_timeout_sec: serenaConfig.startupTimeoutSec,
+          ...(hasSerenaIssues
+            ? { fix: "Serena MCP에 --project-from-cwd 와 startup_timeout_sec=30+ 를 설정하세요." }
+            : {}),
+        });
+      }
+    } else {
+      addDoctorCheck(report, {
+        name: "serena-mcp",
+        status: "missing",
+        path: CODEX_CONFIG_PATH,
+        fix: "Codex config를 생성하고 Serena MCP 설정을 추가하세요.",
+      });
+      warn("config.toml 미존재 — Serena MCP 진단 건너뜀");
+      issues++;
+    }
+
     // 5. Gemini CLI
     section(`Gemini CLI ${BLUE}●${RESET}`);
     const geminiCli = checkCliCrossShell("gemini", "npm install -g @google/gemini-cli");
@@ -1394,6 +1531,29 @@ async function cmdDoctor(options = {}) {
       const psmuxPath = which("psmux");
       if (psmuxPath) {
         ok("설치됨");
+        const psmuxSupport = probePsmuxSupport({ execFileSyncFn: execFileSync });
+        const supportOk = psmuxSupport.ok;
+        info(`버전: ${psmuxSupport.version || "unknown"}`);
+        if (!supportOk) {
+          warn(`capability 부족: ${psmuxSupport.missingCommands.join(", ")}`);
+          info(`업데이트 권장:\n${formatPsmuxUpdateGuidance("  ")}`);
+          addDoctorCheck(report, {
+            name: "psmux",
+            status: "issues",
+            path: psmuxPath,
+            version: psmuxSupport.version || "unknown",
+            missing_commands: psmuxSupport.missingCommands,
+            fix: "tfx setup 또는 psmux 업그레이드",
+          });
+          issues++;
+        } else if (!psmuxSupport.recommended) {
+          warn(`권장 버전 미만: v${psmuxSupport.version || "unknown"} (권장: v${psmuxSupport.recommendedVersion}+)`);
+          info(`업데이트 권장:\n${formatPsmuxUpdateGuidance("  ")}`);
+        }
+        if (psmuxSupport.missingOptionalCommands?.length > 0) {
+          info(`선택 capability 미지원: ${psmuxSupport.missingOptionalCommands.join(", ")} (detach-first hardening 경로에서만 사용)`);
+        }
+
         // 기본 셸 확인: psmux 세션의 기본 셸이 PowerShell인지 cmd.exe인지
         let shellOk = false;
         try {
@@ -1403,7 +1563,7 @@ async function cmdDoctor(options = {}) {
           // show-options 실패 시 pwsh/powershell 존재 여부로 판단
           shellOk = !!which("pwsh") || !!which("powershell.exe");
         }
-        if (shellOk) {
+        if (supportOk && shellOk) {
           ok("기본 셸: PowerShell");
           addDoctorCheck(report, { name: "psmux", status: "ok", path: psmuxPath, shell: "powershell" });
         } else {
@@ -1429,7 +1589,7 @@ async function cmdDoctor(options = {}) {
         }
       } else {
         info(`미설치 ${GRAY}(선택 — 멀티모델 병렬 실행에 필요)${RESET}`);
-        info(`설치: winget install marlocarlo.psmux`);
+        info(`설치 방법:\n${formatPsmuxInstallGuidance("  ")}`);
         addDoctorCheck(report, { name: "psmux", status: "skipped", detail: "미설치 (선택)", fix: "winget install marlocarlo.psmux" });
       }
     }
@@ -2190,20 +2350,68 @@ async function cmdDoctor(options = {}) {
           }
         }
 
+        // 중복 훅 감지 + 자동 수정 (orchestrator와 개별 훅이 동시 등록된 경우)
+        if (coverage.duplicates && coverage.duplicates.length > 0) {
+          if (fix) {
+            try {
+              const fixedSettings = JSON.parse(readFileSync(settingsPath, "utf8"));
+              let removed = 0;
+              for (const [event, entries] of Object.entries(fixedSettings.hooks || {})) {
+                if (!Array.isArray(entries)) continue;
+                const hasOrch = entries.some((e) =>
+                  Array.isArray(e?.hooks) &&
+                  e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("hook-orchestrator")),
+                );
+                if (!hasOrch) continue;
+                // 패턴 A: orchestrator 없는 별도 엔트리 제거
+                const before = entries.length;
+                fixedSettings.hooks[event] = entries.filter((e) =>
+                  Array.isArray(e?.hooks) &&
+                  e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("hook-orchestrator")),
+                );
+                removed += before - fixedSettings.hooks[event].length;
+                // 패턴 B: orchestrator 엔트리 내부의 개별 훅 제거
+                for (const entry of fixedSettings.hooks[event]) {
+                  if (!Array.isArray(entry.hooks) || entry.hooks.length <= 1) continue;
+                  const beforeInner = entry.hooks.length;
+                  entry.hooks = entry.hooks.filter(
+                    (h) => typeof h?.command === "string" && h.command.includes("hook-orchestrator"),
+                  );
+                  removed += beforeInner - entry.hooks.length;
+                }
+              }
+              if (removed > 0) {
+                writeFileSync(settingsPath, JSON.stringify(fixedSettings, null, 2) + "\n", "utf8");
+                ok(`중복 훅 ${removed}개 엔트리 제거됨 (orchestrator가 체이닝)`);
+                const rechecked = JSON.parse(readFileSync(settingsPath, "utf8"));
+                coverage = computeHookCoverage(rechecked, managedHooks);
+              }
+            } catch (error) {
+              warn(`중복 훅 자동 제거 실패: ${error.message}`);
+            }
+          } else {
+            warn(`중복 훅 ${coverage.duplicates.length}개 감지 (이중 실행됨): ${coverage.duplicates.join(", ")}`);
+            warn("tfx doctor --fix 로 자동 제거하세요.");
+            issues += coverage.duplicates.length;
+          }
+        }
+
         report.hook_coverage = coverage;
-        const coverageStatus = coverage.missing.length === 0 ? "ok" : "issues";
+        const coverageStatus = coverage.missing.length === 0 && (!coverage.duplicates || coverage.duplicates.length === 0) ? "ok" : "issues";
         addDoctorCheck(report, {
           name: "hook-coverage",
           status: coverageStatus,
           total: coverage.total,
           registered: coverage.registered,
           missing: coverage.missing,
+          duplicates: coverage.duplicates || [],
           ...(coverage.missing.length > 0 ? { fix: "tfx doctor --fix 또는 tfx setup" } : {}),
+          ...(coverage.duplicates?.length > 0 ? { fix: "tfx doctor --fix 로 중복 훅 제거" } : {}),
         });
 
-        if (coverage.missing.length === 0) {
+        if (coverage.missing.length === 0 && (!coverage.duplicates || coverage.duplicates.length === 0)) {
           ok(`Hook Coverage: ${coverage.registered}/${coverage.total} registered`);
-        } else {
+        } else if (coverage.missing.length > 0) {
           fail(`Missing hooks: ${coverage.missing.join(", ")}`);
           issues += coverage.missing.length;
         }
@@ -2382,26 +2590,94 @@ function cmdUpdate() {
       ok(`버전: v${oldVer} (이미 최신)`);
     }
 
-    // setup 재실행 — 개선된 cmdSetup()이 Gemini 프로필, CLI 확인, 요약 테이블 포함
+    // ── Post-update: 캐시 갱신 (삭제 → 재생성) ──
+    console.log(`\n${CYAN}── 캐시 갱신 ──${RESET}`);
+    {
+      const cacheDir = join(CLAUDE_DIR, "cache");
+      // stale 캐시 삭제
+      for (const name of ["tfx-preflight.json", "mcp-inventory.json"]) {
+        const p = join(cacheDir, name);
+        if (existsSync(p)) { try { unlinkSync(p); } catch {} }
+      }
+      // tmpdir 상태 파일 정리
+      for (const name of ["tfx-multi-state.json"]) {
+        const p = join(tmpdir(), name);
+        if (existsSync(p)) { try { unlinkSync(p); } catch {} }
+      }
+
+      // preflight 캐시 재생성
+      const preflightScript = join(PKG_ROOT, "scripts", "preflight-cache.mjs");
+      if (existsSync(preflightScript)) {
+        try {
+          execSync(`node "${preflightScript}"`, { encoding: "utf8", timeout: 15000, windowsHide: true, stdio: "pipe" });
+          ok("preflight 캐시 재생성 완료");
+        } catch (e) {
+          warn(`preflight 캐시 재생성 실패: ${e.message?.split(/\r?\n/)[0] || "unknown"}`);
+        }
+      }
+
+      // MCP 인벤토리 캐시 재생성
+      const mcpCheckScript = join(PKG_ROOT, "scripts", "mcp-check.mjs");
+      if (existsSync(mcpCheckScript)) {
+        try {
+          execSync(`node "${mcpCheckScript}"`, { encoding: "utf8", timeout: 10000, windowsHide: true, stdio: "pipe" });
+          ok("MCP 인벤토리 캐시 재생성 완료");
+        } catch (e) {
+          warn(`MCP 인벤토리 재생성 실패: ${e.message?.split(/\r?\n/)[0] || "unknown"}`);
+        }
+      }
+    }
+
+    // ── Post-update: 핵심 파일 무결성 검증 ──
+    console.log(`\n${CYAN}── 무결성 검증 ──${RESET}`);
+    {
+      const criticalFiles = [
+        { path: join(PKG_ROOT, "hooks", "hook-orchestrator.mjs"), label: "hook-orchestrator" },
+        { path: join(PKG_ROOT, "hooks", "hook-registry.json"), label: "hook-registry" },
+        { path: join(PKG_ROOT, "hooks", "safety-guard.mjs"), label: "safety-guard" },
+        { path: join(PKG_ROOT, "scripts", "keyword-detector.mjs"), label: "keyword-detector" },
+        { path: join(PKG_ROOT, "scripts", "setup.mjs"), label: "setup" },
+        { path: join(PKG_ROOT, "bin", "triflux.mjs"), label: "triflux CLI" },
+      ];
+      let missing = 0;
+      for (const { path: fp, label } of criticalFiles) {
+        if (!existsSync(fp)) {
+          fail(`누락: ${label} (${formatPathForDisplay(fp)})`);
+          missing++;
+        }
+      }
+      if (missing > 0) {
+        fail(`핵심 파일 ${missing}개 누락 — npm install -g triflux@latest 재설치 필요`);
+      } else {
+        ok(`핵심 파일 ${criticalFiles.length}개 확인 완료`);
+      }
+    }
+
+    // ── Post-update: 설정 동기화 ──
     console.log(`\n${CYAN}── 설정 동기화 ──${RESET}`);
     cmdSetup({ fromUpdate: true, overrideVersion: newVer });
 
-    // hook-orchestrator apply — settings.json 훅 경로를 올바른 절대경로로 갱신
-    try {
+    // ── Post-update: 훅 오케스트레이터 적용 ──
+    {
       const hookMgrPath = join(PKG_ROOT, "hooks", "hook-manager.mjs");
       if (existsSync(hookMgrPath)) {
-        const result = execSync(`node "${hookMgrPath}" apply`, {
-          encoding: "utf8",
-          timeout: 10000,
-          windowsHide: true,
-        }).trim();
-        const parsed = JSON.parse(result);
-        if (parsed?.status === "applied") {
-          ok(`훅 오케스트레이터 적용 (${parsed.events?.length || 0}개 이벤트)`);
+        try {
+          const result = execSync(`node "${hookMgrPath}" apply`, {
+            encoding: "utf8",
+            timeout: 10000,
+            windowsHide: true,
+          }).trim();
+          const parsed = JSON.parse(result);
+          if (parsed?.status === "applied") {
+            ok(`훅 오케스트레이터 적용 (${parsed.events?.length || 0}개 이벤트)`);
+          }
+        } catch (e) {
+          warn(`훅 오케스트레이터 적용 실패: ${e.message?.split(/\r?\n/)[0] || "unknown"}`);
+          warn("tfx hooks apply 로 수동 적용하세요.");
         }
+      } else {
+        fail("hook-manager.mjs 누락 — 훅 오케스트레이터 적용 불가");
       }
-    } catch {
-      // apply 실패 시 무시 — ensureHooksInSettings이 개별 훅을 이미 등록함
     }
 
     if (stoppedHubInfo) {
@@ -2951,38 +3227,20 @@ function startHubAfterUpdate(info) {
 }
 
 // 설치된 CLI에 tfx-hub MCP 서버 자동 등록 (1회 설정, 이후 재실행 불필요)
-function autoRegisterMcp(mcpUrl) {
+function autoRegisterMcp(mcpUrl, { codexEnabled = false } = {}) {
   section("MCP 자동 등록");
 
-  // Codex — codex mcp add
+  // Codex — config.json에 기본 disabled 엔트리로 등록
   if (which("codex")) {
     try {
-      // 이미 등록됐는지 확인
-      const list = execSync("codex mcp list 2>&1", { encoding: "utf8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
-      if (list.includes("tfx-hub")) {
-        ok("Codex: 이미 등록됨");
+      const result = ensureCodexHubServerConfig({ mcpUrl, createIfMissing: true, enabled: codexEnabled });
+      if (!result.ok) throw new Error(result.reason || "unknown");
+      if (result.changed) {
+        ok(`Codex: config.json에 등록 완료 (${codexEnabled ? "enabled" : "기본 disabled"})`);
       } else {
-        execFileSync("codex", ["mcp", "add", "tfx-hub", "--url", mcpUrl], { timeout: 10000, stdio: "ignore", windowsHide: true });
-        ok("Codex: MCP 등록 완료");
+        ok(`Codex: 이미 등록됨 (${codexEnabled ? "enabled" : "기본 disabled"})`);
       }
-    } catch {
-      // mcp list/add 미지원 → 설정 파일 직접 수정
-      try {
-        const codexDir = join(homedir(), ".codex");
-        const configFile = join(codexDir, "config.json");
-        let config = {};
-        if (existsSync(configFile)) config = JSON.parse(readFileSync(configFile, "utf8"));
-        if (!config.mcpServers) config.mcpServers = {};
-        if (!config.mcpServers["tfx-hub"]) {
-          config.mcpServers["tfx-hub"] = { url: mcpUrl };
-          if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
-          writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
-          ok("Codex: config.json에 등록 완료");
-        } else {
-          ok("Codex: 이미 등록됨");
-        }
-      } catch (e) { warn(`Codex 등록 실패: ${e.message}`); }
-    }
+    } catch (e) { warn(`Codex 등록 실패: ${e.message}`); }
   } else {
     info("Codex: 미설치 (건너뜀)");
   }
@@ -3072,6 +3330,7 @@ async function cmdHub(args = [], options = {}) {
         try {
           const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
           process.kill(info.pid, 0); // 프로세스 존재 확인
+          autoRegisterMcp(info.url, { codexEnabled: true });
           console.log(`\n  ${YELLOW}⚠${RESET} hub 이미 실행 중 (PID ${info.pid}, ${info.url})\n`);
           return;
         } catch {
@@ -3115,7 +3374,7 @@ async function cmdHub(args = [], options = {}) {
         console.log(`    PID:  ${hubInfo.pid}`);
         console.log(`    DB:   ${DIM}${getPipelineStateDbPath(PKG_ROOT)}${RESET}`);
         console.log("");
-        autoRegisterMcp(hubInfo.url);
+        autoRegisterMcp(hubInfo.url, { codexEnabled: true });
         console.log("");
       } else {
         // 직접 포그라운드 모드로 안내

package/hooks/hook-registry.json

@@ -190,7 +190,7 @@
         "matcher": "*",
         "command": "powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \"${HOME}/.claude/scripts/mcp-cleanup.ps1\"",
         "priority": 100,
-        "enabled": false,
+        "enabled": true,
         "timeout": 8,
         "blocking": false,
         "description": "MCP 고아 프로세스 정리"

package/hub/fullcycle.mjs

@@ -0,0 +1,96 @@
+// hub/fullcycle.mjs — tfx-fullcycle runtime artifact/state helpers
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ensureTfxDirs, TFX_FULLCYCLE_DIR, TFX_PLANS_DIR } from './paths.mjs';
+
+function safeResolve(baseDir, relativePath) {
+  const base = resolve(baseDir);
+  const target = resolve(join(baseDir, relativePath));
+  if (!target.startsWith(base)) {
+    throw new Error('Invalid fullcycle path: path traversal detected');
+  }
+  return target;
+}
+
+export function createFullcycleRunId(now = new Date()) {
+  return now
+    .toISOString()
+    .replace(/[:.]/g, '-')
+    .replace('T', '_')
+    .replace('Z', 'Z');
+}
+
+export function getFullcycleRunDir(runId, baseDir = process.cwd()) {
+  return safeResolve(baseDir, join(TFX_FULLCYCLE_DIR, runId));
+}
+
+export function ensureFullcycleRunDir(runId, baseDir = process.cwd()) {
+  ensureTfxDirs(baseDir);
+  const dir = getFullcycleRunDir(runId, baseDir);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function saveFullcycleArtifact(runId, filename, content, baseDir = process.cwd()) {
+  if (!filename || typeof filename !== 'string') {
+    throw new Error('Artifact filename is required');
+  }
+
+  const dir = ensureFullcycleRunDir(runId, baseDir);
+  const path = safeResolve(dir, filename);
+  writeFileSync(path, content, 'utf8');
+  return path;
+}
+
+export function readFullcycleArtifact(runId, filename, baseDir = process.cwd()) {
+  const dir = getFullcycleRunDir(runId, baseDir);
+  const path = safeResolve(dir, filename);
+  if (!existsSync(path)) return null;
+  return readFileSync(path, 'utf8');
+}
+
+export function writeFullcycleState(runId, state, baseDir = process.cwd()) {
+  const payload = typeof state === 'object' && state !== null ? state : {};
+  const serialized = JSON.stringify(payload, null, 2);
+  return saveFullcycleArtifact(runId, 'state.json', serialized, baseDir);
+}
+
+export function readFullcycleState(runId, baseDir = process.cwd()) {
+  const content = readFullcycleArtifact(runId, 'state.json', baseDir);
+  if (!content) return null;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function findLatestInterviewPlan(baseDir = process.cwd()) {
+  const plansDir = safeResolve(baseDir, TFX_PLANS_DIR);
+  if (!existsSync(plansDir)) return null;
+
+  const candidates = readdirSync(plansDir)
+    .filter((name) => /^interview-.*\.md$/i.test(name))
+    .map((name) => {
+      const path = join(plansDir, name);
+      const stats = statSync(path);
+      return { name, path, mtimeMs: stats.mtimeMs };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  return candidates[0]?.path || null;
+}
+
+export function shouldStopQaLoop(failureHistory = [], maxRepeats = 3) {
+  if (!Array.isArray(failureHistory) || maxRepeats <= 1) return false;
+
+  const normalized = failureHistory
+    .map((entry) => String(entry ?? '').trim())
+    .filter(Boolean);
+
+  if (normalized.length < maxRepeats) return false;
+  const target = normalized.at(-1);
+  const tail = normalized.slice(-maxRepeats);
+  return tail.every((entry) => entry === target);
+}

package/hub/paths.mjs

@@ -1,28 +1,30 @@
-// hub/paths.mjs — triflux 워킹 디렉토리 경로 상수
-
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-
-export const TFX_WORK_DIR = '.tfx';
-export const TFX_PLANS_DIR = join(TFX_WORK_DIR, 'plans');
-export const TFX_REPORTS_DIR = join(TFX_WORK_DIR, 'reports');
-export const TFX_HANDOFFS_DIR = join(TFX_WORK_DIR, 'handoffs');
-export const TFX_LOGS_DIR = join(TFX_WORK_DIR, 'logs');
-export const TFX_STATE_DIR = join(TFX_WORK_DIR, 'state');
-
-/**
- * triflux 워킹 디렉토리 구조를 보장한다.
- * @param {string} baseDir
- */
-export function ensureTfxDirs(baseDir) {
-  for (const relativeDir of [
-    TFX_WORK_DIR,
-    TFX_PLANS_DIR,
-    TFX_REPORTS_DIR,
-    TFX_HANDOFFS_DIR,
-    TFX_LOGS_DIR,
-    TFX_STATE_DIR,
-  ]) {
-    mkdirSync(join(baseDir, relativeDir), { recursive: true });
-  }
-}
+// hub/paths.mjs — triflux 워킹 디렉토리 경로 상수
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const TFX_WORK_DIR = '.tfx';
+export const TFX_PLANS_DIR = join(TFX_WORK_DIR, 'plans');
+export const TFX_REPORTS_DIR = join(TFX_WORK_DIR, 'reports');
+export const TFX_HANDOFFS_DIR = join(TFX_WORK_DIR, 'handoffs');
+export const TFX_LOGS_DIR = join(TFX_WORK_DIR, 'logs');
+export const TFX_STATE_DIR = join(TFX_WORK_DIR, 'state');
+export const TFX_FULLCYCLE_DIR = join(TFX_WORK_DIR, 'fullcycle');
+
+/**
+ * triflux 워킹 디렉토리 구조를 보장한다.
+ * @param {string} baseDir
+ */
+export function ensureTfxDirs(baseDir) {
+  for (const relativeDir of [
+    TFX_WORK_DIR,
+    TFX_PLANS_DIR,
+    TFX_REPORTS_DIR,
+    TFX_HANDOFFS_DIR,
+    TFX_LOGS_DIR,
+    TFX_STATE_DIR,
+    TFX_FULLCYCLE_DIR,
+  ]) {
+    mkdirSync(join(baseDir, relativeDir), { recursive: true });
+  }
+}