triflux 10.14.0 → 10.14.2

package/bin/triflux.mjs

@@ -61,6 +61,7 @@ import {
   probePsmuxSupport,
 } from "../scripts/lib/psmux-info.mjs";
 import {
+  buildWindowsHubAutostartCommand,
   cleanupStaleSkills,
   ensureCodexHubServerConfig,
   ensureCodexProfiles,
@@ -68,6 +69,7 @@ import {
   extractManagedHookFilename,
   getManagedRegistryHooks,
   getVersion,
+  getWindowsHubAutostartStatus,
   hasProfileSection,
   LEGACY_CODEX_MODELS,
   REQUIRED_CODEX_PROFILES,
@@ -123,7 +125,7 @@ const NORMALIZED_ARGS = RAW_ARGS.filter((arg) => arg !== "--json");
 
 const CLI_COMMAND_SCHEMAS = Object.freeze({
   setup: {
-    usage: "tfx setup [--dry-run]",
+    usage: "tfx setup [--dry-run] [--enable-hub-autostart]",
     description: "파일 동기화 + HUD/MCP 설정",
     options: [
       {
@@ -131,6 +133,12 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
         type: "boolean",
         description: "실제 변경 없이 예정 작업을 JSON으로 출력",
       },
+      {
+        name: "--enable-hub-autostart",
+        type: "boolean",
+        description:
+          "Windows 로그인 시 tfx-hub를 보장하는 Task Scheduler 항목 등록",
+      },
     ],
   },
   doctor: {
@@ -1115,6 +1123,16 @@ function buildSetupDryRunPlan() {
   const defaultHubUrl = `http://127.0.0.1:${process.env.TFX_HUB_PORT || "27888"}/mcp`;
   actions.push(...previewMcpRegistrationActions(defaultHubUrl));
   actions.push(previewStatusLineAction());
+  const autostart = getWindowsHubAutostartStatus();
+  actions.push({
+    type: "hub-autostart",
+    platform: process.platform,
+    taskName: autostart.taskName,
+    change: autostart.supported && !autostart.registered ? "available" : "noop",
+    registered: autostart.registered,
+    command: autostart.supported ? buildWindowsHubAutostartCommand() : null,
+    enableWith: "tfx setup --enable-hub-autostart",
+  });
 
   return {
     dry_run: true,
@@ -1123,7 +1141,12 @@ function buildSetupDryRunPlan() {
 }
 
 function cmdSetup(options = {}) {
-  const { dryRun = false, overrideVersion, skipClaudeMdSync = false } = options;
+  const {
+    dryRun = false,
+    overrideVersion,
+    skipClaudeMdSync = false,
+    enableHubAutostart = false,
+  } = options;
   if (dryRun) {
     printJson(buildSetupDryRunPlan());
     return;
@@ -1351,6 +1374,67 @@ function cmdSetup(options = {}) {
     console.log("");
   }
 
+  if (process.platform === "win32") {
+    const status = getWindowsHubAutostartStatus();
+    if (enableHubAutostart) {
+      try {
+        const script = join(PKG_ROOT, "scripts", "setup.mjs");
+        execFileSync(
+          process.execPath,
+          [script, "--enable-hub-autostart", "--sync"],
+          {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10000,
+            windowsHide: true,
+          },
+        );
+        // subprocess silent-catch 회귀 가드: schtasks /Query 로 실제 등록 재검증.
+        const verified = getWindowsHubAutostartStatus();
+        if (verified.registered) {
+          ok(`Hub autostart: ${verified.taskName} 등록됨`);
+          summary.push({
+            item: "Hub autostart",
+            status: "✅",
+            detail: `${verified.taskName} 등록됨`,
+          });
+        } else {
+          warn(
+            "Hub autostart 등록 실패: subprocess 성공했으나 /Query 에서 미발견",
+          );
+          summary.push({
+            item: "Hub autostart",
+            status: "⚠️",
+            detail: "등록 실패 (subprocess silent catch 의심)",
+          });
+        }
+      } catch (error) {
+        warn(`Hub autostart 등록 실패: ${renderErrorMessage(error.message)}`);
+        summary.push({
+          item: "Hub autostart",
+          status: "⚠️",
+          detail: "등록 실패",
+        });
+      }
+    } else if (status.registered) {
+      ok(`Hub autostart: ${status.taskName} 이미 등록됨`);
+      summary.push({
+        item: "Hub autostart",
+        status: "✅",
+        detail: "이미 등록됨",
+      });
+    } else {
+      warn(
+        "Hub autostart 미등록 — Codex 단독 시작 전 hub가 죽어 있으면 MCP가 실패할 수 있음",
+      );
+      info("등록: tfx setup --enable-hub-autostart");
+      summary.push({
+        item: "Hub autostart",
+        status: "⏭️",
+        detail: "미등록",
+      });
+    }
+  }
+
   // HUD statusLine 설정
   console.log(`${CYAN}[HUD 설정]${RESET}`);
   const settingsPath = join(CLAUDE_DIR, "settings.json");
@@ -5579,7 +5663,10 @@ async function main() {
 
   switch (cmd) {
     case "setup":
-      cmdSetup({ dryRun: cmdArgs.includes("--dry-run") });
+      cmdSetup({
+        dryRun: cmdArgs.includes("--dry-run"),
+        enableHubAutostart: cmdArgs.includes("--enable-hub-autostart"),
+      });
       return;
     case "doctor": {
       if (cmdArgs.includes("--audit")) {

package/hub/team/conductor.mjs

@@ -696,6 +696,10 @@ export function createConductor(opts = {}) {
       },
       {
         ...probeOpts,
+        // #165: default off → on. atomic write (#162) 로 race 제거됨.
+        // opt-out: TFX_PROBE_WRITE_STATE=0 명시.
+        writeStateFile:
+          probeOpts.writeStateFile ?? process.env.TFX_PROBE_WRITE_STATE !== "0",
         onProbe: (result) => handleProbeResult(session, result),
       },
     );

package/hub/team/health-probe.mjs

@@ -2,6 +2,10 @@
 // 기존 cli-adapter-base.mjs:stallThresholdMs(30s)와 headless.mjs:STALL_DEFAULTS(120s)를
 // 4단계 probe 모델로 교체. stdout+stderr 통합 스트림으로 평가 (F3 해결).
 
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
 /**
  * Health probe level 정의.
  * L0: Process alive (PID 존재 + exit code 없음)
@@ -25,6 +29,8 @@ export const PROBE_DEFAULTS = Object.freeze({
   l2ThresholdMs: 30_000,
   l3ThresholdMs: 120_000,
   enableL2: false,
+  writeStateFile: false,
+  stateDir: join(tmpdir(), "tfx-probe"),
 });
 
 /**
@@ -78,6 +84,16 @@ export function createHealthProbe(session, opts = {}) {
   const config = { ...PROBE_DEFAULTS, ...opts };
   let timer = null;
   let started = false;
+  // stopped flag는 in-flight probe()가 stop() 사이의 await 점에서
+  // writeState/unlink 와 race 하는 것을 막는다. start() 시 false 로 reset.
+  let stopped = false;
+  // P0 (#167 review): start() 마다 증가. probe() 가 시작 시 캡처 → writeState() 가 epoch
+  // 비교로 stop()→start() 사이의 in-flight 가 새 run 의 state 를 덮는 race 차단.
+  // stopped flag 만으로는 start() 가 stopped=false 로 reset 한 직후 race 못 막음.
+  let runEpoch = 0;
+  // P1-1 (#167 review): Set 으로 모든 in-flight probe 추적. interval 이 빨라 N+1 이 N 끝나기
+  // 전에 시작되면 단일 var 는 N 을 덮어써 stopAndDrain() 시 N 이 누락된다.
+  const inFlightProbes = new Set();
 
   // L1 tracking
   let lastOutputBytes = 0;
@@ -96,6 +112,97 @@ export function createHealthProbe(session, opts = {}) {
     inputWaitPattern: null,
   };
 
+  function getStateFilePath() {
+    if (typeof config.stateFile === "string" && config.stateFile.length > 0) {
+      return config.stateFile;
+    }
+    const pid = session.pid;
+    if (pid == null || pid <= 0) return null;
+    return join(config.stateDir, `${pid}.json`);
+  }
+
+  function deriveState(result) {
+    if (result.l0 === "fail") return "exited";
+    if (result.l1 === "input_wait") return "input_wait";
+    if (result.l2 === "fail") return "mcp_initializing";
+    if (result.l1 === "stall") return "stalled";
+    if (result.l3 === "timeout") return "reasoning";
+    return "active";
+  }
+
+  function writeState(result, probeEpoch) {
+    // stop() 직후 in-flight probe()의 재생성 방지.
+    // P0 (#167): probeEpoch !== runEpoch 면 이전 run 의 stale probe 가 새 run 의 state 를
+    // 덮으려는 시도 → skip.
+    if (stopped) return;
+    if (probeEpoch !== undefined && probeEpoch !== runEpoch) return;
+    if (!config.writeStateFile && !config.stateFile) return;
+    const stateFile = getStateFilePath();
+    if (!stateFile) return;
+    const payload =
+      JSON.stringify(
+        {
+          pid: session.pid ?? null,
+          state: deriveState(result),
+          result,
+          updatedAt: new Date(result.ts).toISOString(),
+        },
+        null,
+        2,
+      ) + "\n";
+    // tmp+rename 으로 atomic write — heartbeat 의 sed 가 부분 파일을 읽는 race 제거.
+    // tmp 는 같은 디렉토리에 둬야 EXDEV (cross-device link) 가 안 난다.
+    const tmpPath = `${stateFile}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+      mkdirSync(dirname(stateFile), { recursive: true });
+      writeFileSync(tmpPath, payload, "utf8");
+      try {
+        renameSync(tmpPath, stateFile);
+      } catch (renameErr) {
+        // Windows: 대상이 존재할 때 EPERM/EACCES.
+        // P1-2 (#167 review): backup-then-swap 으로 기존 파일 보존. 옛 unlinkSync→renameSync
+        // 패턴은 1차 unlink 후 2차 rename 실패 시 기존 파일과 tmp 둘 다 잃었다.
+        if (
+          renameErr?.code === "EEXIST" ||
+          renameErr?.code === "EPERM" ||
+          renameErr?.code === "EACCES"
+        ) {
+          const backupPath = `${stateFile}.old-${process.pid}-${Date.now()}`;
+          let backupCreated = false;
+          try {
+            renameSync(stateFile, backupPath);
+            backupCreated = true;
+          } catch {
+            // backup 실패 (대상 없음/잠김) — 그래도 진행 (tmp→stateFile 시도)
+          }
+          try {
+            renameSync(tmpPath, stateFile);
+            if (backupCreated) {
+              try {
+                unlinkSync(backupPath);
+              } catch {}
+            }
+          } catch (secondErr) {
+            // 2차도 실패 → backup 복구해서 기존 파일 보존
+            if (backupCreated) {
+              try {
+                renameSync(backupPath, stateFile);
+              } catch {}
+            }
+            throw secondErr;
+          }
+        } else {
+          throw renameErr;
+        }
+      }
+    } catch {
+      // probe state is advisory only — tmp cleanup
+      try {
+        unlinkSync(tmpPath);
+      } catch {}
+    }
+  }
+
   /**
    * L0: Process alive check.
    */
@@ -215,29 +322,44 @@ export function createHealthProbe(session, opts = {}) {
 
   /**
    * 전체 probe 실행 (L0→L1→L2→L3).
-   * @returns {Promise<object>} probe 결과
+   * @returns {Promise<object|null>} probe 결과. stop() 이후 호출이면 null.
    */
   async function probe() {
-    const result = {
-      l0: probeL0(),
-      l1: probeL1(),
-      l2: await probeL2(),
-      l3: probeL3(),
-      inputWaitPattern: status.inputWaitPattern,
-      ts: Date.now(),
-    };
-    status.lastProbeAt = result.ts;
-
-    if (typeof config.onProbe === "function") {
-      config.onProbe(result);
-    }
+    if (stopped) return null;
+    // P0 (#167): probe 시작 시 epoch 캡처. start() 가 새 epoch 로 바꾸면 이 probe 의
+    // writeState 는 stale 로 판정 → skip.
+    const probeEpoch = runEpoch;
+    const promise = (async () => {
+      const result = {
+        l0: probeL0(),
+        l1: probeL1(),
+        l2: await probeL2(),
+        l3: probeL3(),
+        inputWaitPattern: status.inputWaitPattern,
+        ts: Date.now(),
+      };
+      status.lastProbeAt = result.ts;
+      writeState(result, probeEpoch);
+
+      if (typeof config.onProbe === "function") {
+        config.onProbe(result);
+      }
 
-    return result;
+      return result;
+    })();
+    // P1-1 (#167): Set 으로 모든 in-flight 추적. 단일 var 패턴은 N+1 이 N 끝나기 전에
+    // 시작되면 N 을 덮어써 stopAndDrain() 시 N 이 누락된다.
+    inFlightProbes.add(promise);
+    promise.finally(() => inFlightProbes.delete(promise));
+    return promise;
   }
 
   function start() {
     if (started) return;
     started = true;
+    stopped = false;
+    // P0 (#167): epoch 증가 — 이전 run 의 in-flight probe 가 새 run 의 state 를 덮지 못하게.
+    runEpoch += 1;
     spawnedAt = Date.now();
     lastOutputChangeAt = Date.now();
     lastOutputBytes = 0;
@@ -255,10 +377,32 @@ export function createHealthProbe(session, opts = {}) {
   function stop() {
     if (!started) return;
     started = false;
+    // stopped 를 먼저 set 해야 in-flight probe()의 writeState() 가 skip 된다.
+    // 이후 unlink — in-flight 가 끝나도 writeState 가 no-op 이므로 재생성 없음.
+    stopped = true;
     if (timer) {
       clearInterval(timer);
       timer = null;
     }
+    if (config.writeStateFile || config.stateFile) {
+      try {
+        const stateFile = getStateFilePath();
+        if (stateFile) unlinkSync(stateFile);
+      } catch {}
+    }
+  }
+
+  /**
+   * stop() 후 in-flight probe() 가 완료될 때까지 대기.
+   * 결정적 종료가 필요한 테스트/teardown 용. conductor 의 sync stop() 호출자는
+   * 그대로 stop() 만 호출하면 stopped flag 가 race 를 막는다.
+   */
+  async function stopAndDrain() {
+    stop();
+    // P1-1 (#167): 모든 in-flight probe 대기. allSettled 로 unhandled rejection 방지.
+    if (inFlightProbes.size > 0) {
+      await Promise.allSettled(Array.from(inFlightProbes));
+    }
   }
 
   /** L1 tracking 리셋 (restart 후 호출) */
@@ -277,6 +421,7 @@ export function createHealthProbe(session, opts = {}) {
   return Object.freeze({
     start,
     stop,
+    stopAndDrain,
     probe,
     resetTracking,
     getStatus: () => ({ ...status }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.14.0",
+  "version": "10.14.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

@@ -13,6 +13,7 @@ import { fileURLToPath } from "url";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
 const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+const HUB_DEFAULT_PORT = 27888;
 
 function formatHostForUrl(host) {
   return host.includes(":") ? `[${host}]` : host;
@@ -34,29 +35,33 @@ async function syncHubConfigsIfAvailable({ hubUrl }) {
       await mod.syncCodexHubUrl({ hubUrl });
     }
     if (typeof mod?.syncProjectMcpJson === "function") {
-      await mod.syncProjectMcpJson({ hubUrl, projectRoot: PLUGIN_ROOT });
+      // 사용자 작업 디렉토리의 .mcp.json 을 sync 대상으로 한다.
+      // 이전에는 PLUGIN_ROOT(triflux 설치 경로)를 넘겨서 설치 경로의 .mcp.json
+      // 만 sync 되고 사용자 실제 프로젝트는 drift 되던 증상이 있었다.
+      await mod.syncProjectMcpJson({ hubUrl, projectRoot: process.cwd() });
     }
   } catch {
     // sync는 best-effort이며 hub-ensure 성공/실패를 좌우하지 않는다.
   }
 }
 
-function resolveHubTarget() {
+export function resolveHubTarget() {
   const envPortRaw = Number(process.env.TFX_HUB_PORT || "");
   const envPort =
     Number.isFinite(envPortRaw) && envPortRaw > 0 ? envPortRaw : null;
   const target = {
     host: "127.0.0.1",
-    port: envPort || 27888,
+    port: envPort ?? HUB_DEFAULT_PORT,
   };
 
+  // PID 파일의 port는 source of truth가 아니다. host 힌트만 재사용한다.
+  // 과거에는 `!envPort`일 때 PID file의 port로 target.port를 덮었으나,
+  // 이는 이전 세션의 오염된 port(비표준 포트)가 cascade로 영속화되는 버그 원인이었다.
+  // 포트는 오직 TFX_HUB_PORT env(없으면 HUB_DEFAULT_PORT=27888)만 source of truth다.
+  // client config 는 sync-hub-mcp-settings.mjs가 이 hubUrl로 재동기화한다.
   if (existsSync(HUB_PID_FILE)) {
     try {
       const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
-      if (!envPort) {
-        const pidPort = Number(info?.port);
-        if (Number.isFinite(pidPort) && pidPort > 0) target.port = pidPort;
-      }
       if (typeof info?.host === "string") {
         const host = info.host.trim();
         if (LOOPBACK_HOSTS.has(host)) target.host = host;

package/scripts/lib/mcp-health.mjs

@@ -334,7 +334,7 @@ function makeInitializeRequest() {
 
 function isValidInitResponse(line) {
   const trimmed = line.trim();
-  if (!trimmed || !trimmed.startsWith("{")) return false;
+  if (!trimmed?.startsWith("{")) return false;
   try {
     const msg = JSON.parse(trimmed);
     if (msg.jsonrpc !== "2.0") return false;
@@ -576,8 +576,7 @@ export async function probeAll({
     const prior = cachedResults[name];
     if (
       cacheWithinTtl &&
-      prior &&
-      prior.fingerprint &&
+      prior?.fingerprint &&
       fingerprintsEqual(prior.fingerprint, fingerprints[name])
     ) {
       hits[name] = prior;

package/scripts/setup.mjs

@@ -47,6 +47,7 @@ function detectDevMode(root = PLUGIN_ROOT) {
 const BREADCRUMB_PATH = join(CLAUDE_DIR, "scripts", ".tfx-pkg-root");
 const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
 const HUD_PATH = join(CLAUDE_DIR, "hud", "hud-qos-status.mjs");
+const WINDOWS_HUB_AUTOSTART_TASK = "TrifluxHubEnsure";
 
 const REQUIRED_CODEX_PROFILES = [
   // gpt-5.5 — 새 main 플래그십. xhigh/high/med/low 4 tier 전부 보장.
@@ -747,6 +748,81 @@ function getSetupArgv(stdinData) {
   return Array.isArray(stdinData?.argv) ? stdinData.argv : [];
 }
 
+function quoteWindowsTaskArg(value) {
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+function buildWindowsHubAutostartCommand({
+  nodePath = process.execPath,
+  pluginRoot = PLUGIN_ROOT,
+} = {}) {
+  return [
+    quoteWindowsTaskArg(nodePath),
+    quoteWindowsTaskArg(join(pluginRoot, "scripts", "hub-ensure.mjs")),
+  ].join(" ");
+}
+
+function getWindowsHubAutostartStatus({
+  taskName = WINDOWS_HUB_AUTOSTART_TASK,
+} = {}) {
+  if (process.platform !== "win32") {
+    return { supported: false, registered: false, taskName };
+  }
+  try {
+    execFileSync("schtasks.exe", ["/Query", "/TN", taskName], {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    return { supported: true, registered: true, taskName };
+  } catch {
+    return { supported: true, registered: false, taskName };
+  }
+}
+
+function ensureWindowsHubAutostart({
+  taskName = WINDOWS_HUB_AUTOSTART_TASK,
+  nodePath = process.execPath,
+  pluginRoot = PLUGIN_ROOT,
+  force = true,
+} = {}) {
+  if (process.platform !== "win32") {
+    return {
+      supported: false,
+      changed: false,
+      registered: false,
+      taskName,
+      reason: "non-windows",
+    };
+  }
+
+  const command = buildWindowsHubAutostartCommand({ nodePath, pluginRoot });
+  const args = [
+    "/Create",
+    "/TN",
+    taskName,
+    "/SC",
+    "ONLOGON",
+    "/TR",
+    command,
+    "/RL",
+    "LIMITED",
+  ];
+  if (force) args.push("/F");
+
+  execFileSync("schtasks.exe", args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  return {
+    supported: true,
+    changed: true,
+    registered: true,
+    taskName,
+    command,
+  };
+}
+
 function loadSettings() {
   if (!existsSync(SETTINGS_PATH)) return {};
 
@@ -980,6 +1056,7 @@ function ensureCriticalSetup() {
 
 export {
   BREADCRUMB_PATH,
+  buildWindowsHubAutostartCommand,
   CLAUDE_DIR,
   cleanupStaleSkills,
   DEPRECATED_SKILLS,
@@ -987,9 +1064,11 @@ export {
   ensureCodexHubServerConfig,
   ensureCodexProfiles,
   ensureHooksInSettings,
+  ensureWindowsHubAutostart,
   extractManagedHookFilename,
   getManagedRegistryHooks,
   getVersion,
+  getWindowsHubAutostartStatus,
   hasProfileSection,
   LEGACY_CODEX_MODELS,
   PLUGIN_ROOT,
@@ -1002,6 +1081,7 @@ export {
   SYNC_MAP,
   scanHudFiles,
   syncAliasedSkillDir,
+  WINDOWS_HUB_AUTOSTART_TASK,
   writeMarker,
 };
 
@@ -1032,6 +1112,9 @@ export async function runDeferred(stdinData) {
   const argv = getSetupArgv(stdinData);
   const isSync = argv.includes("--sync");
   const isForce = argv.includes("--force");
+  const enableHubAutostart =
+    argv.includes("--enable-hub-autostart") ||
+    process.env.TFX_HUB_AUTOSTART === "1";
   const isDev = detectDevMode();
 
   if (isDev) {
@@ -1668,6 +1751,22 @@ export async function runDeferred(stdinData) {
     synced++;
   }
 
+  // ── Windows Codex 단독 실행 보호: 로그인 시 hub-ensure 등록 ──
+  // Claude SessionStart 훅이 없는 순수 Codex 시작 경로에서도 tfx-hub가 살아있게 한다.
+  if (enableHubAutostart) {
+    try {
+      const result = ensureWindowsHubAutostart();
+      if (result.registered) {
+        io.log(`  \x1b[32m✓\x1b[0m Windows hub autostart: ${result.taskName}`);
+        synced++;
+      }
+    } catch (error) {
+      io.log(
+        `  \x1b[33m⚠\x1b[0m Windows hub autostart 등록 실패: ${error.message}`,
+      );
+    }
+  }
+
   // ── CLAUDE.md 라우팅 섹션 자동 동기화 ──
 
   try {

package/scripts/sync-hub-mcp-settings.mjs

@@ -25,7 +25,7 @@ function getCodexConfigPath(codexConfigPath) {
   return join(home, ...CODEX_CONFIG_FILE);
 }
 
-function getProjectMcpJsonPaths(projectRoot) {
+export function getProjectMcpJsonPaths(projectRoot) {
   const root =
     typeof projectRoot === "string" && projectRoot.length > 0
       ? projectRoot
@@ -132,8 +132,11 @@ function parseTomlScalar(rawValue) {
 }
 
 function findMcpServerSection(raw, sectionName) {
+  // TOML 동치 표현 지원: [mcp_servers.name] / [mcp_servers."name"] / [mcp_servers . name]
+  // 미검출 시 appendCodexMcpServerSection이 중복 테이블 생성 → TOMLDecodeError 회귀 방지.
+  const escaped = escapeRegExp(sectionName);
   const headerRegex = new RegExp(
-    `^\\[mcp_servers\\.${escapeRegExp(sectionName)}\\]\\s*$`,
+    `^\\[\\s*mcp_servers\\s*\\.\\s*(?:${escaped}|"${escaped}"|'${escaped}')\\s*\\]\\s*$`,
     "m",
   );
   const headerMatch = headerRegex.exec(raw);
@@ -153,6 +156,13 @@ function findMcpServerSection(raw, sectionName) {
   };
 }
 
+function appendCodexMcpServerSection(raw, sectionName, hubUrl) {
+  const normalized = raw.length > 0 && !raw.endsWith("\n") ? `${raw}\n` : raw;
+  const separator =
+    normalized.length > 0 && !normalized.endsWith("\n\n") ? "\n" : "";
+  return `${normalized}${separator}[mcp_servers.${sectionName}]\nurl = ${formatTomlString(hubUrl)}\n`;
+}
+
 async function syncSingleFile({ filePath, hubUrl, dryRun, logger }) {
   return withFileLock(filePath, async () => {
     if (!(await fileExists(filePath))) {
@@ -243,8 +253,29 @@ async function syncCodexConfigFile({ filePath, hubUrl, dryRun, logger }) {
 
     const section = findMcpServerSection(raw, TFX_HUB_SECTION);
     if (!section) {
-      log(logger, "info", `[codex-mcp-sync] skipped: ${filePath}`);
-      return { kind: "skipped", path: filePath };
+      const nextRaw = appendCodexMcpServerSection(raw, TFX_HUB_SECTION, hubUrl);
+      log(
+        logger,
+        "debug",
+        `[codex-mcp-sync] ${filePath} add ${TFX_HUB_SECTION}: ${hubUrl}`,
+      );
+
+      if (!dryRun) {
+        try {
+          await writeTextAtomic(filePath, nextRaw);
+        } catch (error) {
+          const reason = getReason(error, "write failed");
+          log(
+            logger,
+            "error",
+            `[codex-mcp-sync] error: ${filePath} (${reason})`,
+          );
+          return { kind: "error", path: filePath, reason };
+        }
+      }
+
+      log(logger, "info", `[codex-mcp-sync] updated: ${filePath}`);
+      return { kind: "updated", path: filePath };
     }
 
     const urlMatch = /^(\s*url\s*=\s*)(.+?)(\s*(?:#.*)?)$/m.exec(section.body);

package/scripts/tfx-route.sh

@@ -262,7 +262,7 @@ if [[ "$MCP_PROFILE" == --* ]]; then
 fi
 
 # ── CLI 경로 해석 (Windows npm global 대응) ──
-NODE_BIN="${NODE_BIN:-$(command -v node 2>/dev/null || echo node)}"
+NODE_BIN="${NODE_BIN:-$(command -v node 2>/dev/null || command -v node.exe 2>/dev/null || echo node)}"
 CODEX_BIN="${CODEX_BIN:-$(command -v codex 2>/dev/null || echo codex)}"
 GEMINI_BIN="${GEMINI_BIN:-$(command -v gemini 2>/dev/null || echo gemini)}"
 CLAUDE_BIN="${CLAUDE_BIN:-$(command -v claude 2>/dev/null || echo claude)}"
@@ -278,6 +278,56 @@ GEMINI_PROFILES_PATH="${GEMINI_PROFILES_PATH:-${HOME}/.gemini/triflux-profiles.j
 # ── 상수 ──
 MAX_STDOUT_BYTES=51200  # 50KB — Claude 컨텍스트 절약
 TIMESTAMP=$(date +%s)
+TFX_PROBE_DIR="${TFX_PROBE_DIR:-${TFX_TMP}/tfx-probe}"
+mkdir -p "$TFX_PROBE_DIR" 2>/dev/null || true
+
+estimate_expected_duration_sec() {
+  local agent="${1:-}" profile="${2:-}" prompt="${3:-}"
+  local text="${prompt,,}"
+  local expected=30
+
+  case "$agent" in
+    explore|style-reviewer) expected=30 ;;
+    writer|verifier|qa-tester) expected=90 ;;
+    executor|debugger|test-engineer) expected=300 ;;
+    code-reviewer|security-reviewer|architect|planner|critic|analyst) expected=600 ;;
+    scientist|scientist-deep|deep-executor|document-specialist) expected=900 ;;
+  esac
+
+  case "$profile" in
+    minimal|default) [[ "$expected" -lt 60 ]] && expected=60 ;;
+    analyze|review|full) [[ "$expected" -lt 300 ]] && expected=300 ;;
+    implement|executor) [[ "$expected" -lt 300 ]] && expected=300 ;;
+  esac
+
+  if [[ "$text" =~ (deep|research|analy[sz]e|분석|리서치|조사|전체|전부|싹다|comprehensive) ]]; then
+    [[ "$expected" -lt 600 ]] && expected=600
+  fi
+  if [[ "$text" =~ (refactor|migration|migrate|리팩터|마이그레이션|대규모|rewrite) ]]; then
+    [[ "$expected" -lt 900 ]] && expected=900
+  fi
+  if [[ "$text" =~ (test|lint|build|npm|pnpm|pytest|검증|테스트) ]]; then
+    [[ "$expected" -lt 180 ]] && expected=180
+  fi
+  if [[ "$text" =~ (mcp|browser|playwright|context7|exa|tavily|brave) ]]; then
+    [[ "$expected" -lt 120 ]] && expected=120
+  fi
+
+  printf '%s\n' "$expected"
+}
+
+read_probe_state() {
+  local pid="$1"
+  local state_file="${TFX_PROBE_STATE_FILE:-${TFX_PROBE_DIR}/${pid}.json}"
+  [[ -f "$state_file" ]] || return 1
+  # 2-step read (#162): health-probe.mjs 의 atomic write (tmp+rename) 가 도입되었지만
+  # writer 쪽 OS race 또는 race-free 보장을 못 받는 환경 (예: 일부 FS) 에서 빈/부분 파일
+  # 을 sed 가 읽고 stale state 를 반환하는 것을 방지하기 위해 size 가 너무 작으면 무시.
+  local size
+  size=$(wc -c < "$state_file" 2>/dev/null || printf '0')
+  [[ "$size" -ge 20 ]] || return 1
+  sed -n 's/.*"state"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$state_file" 2>/dev/null | head -1
+}
 RUN_ID="${TIMESTAMP}-$$-${RANDOM}"
 STDERR_LOG="${TFX_TMP}/tfx-route-${AGENT_TYPE}-${RUN_ID}-stderr.log"
 STDOUT_LOG="${TFX_TMP}/tfx-route-${AGENT_TYPE}-${RUN_ID}-stdout.log"
@@ -833,7 +883,7 @@ route_agent() {
 
   # ── CLI_TYPE: 단일 소스 (agent-map.json) ──
   local _raw_type
-  _raw_type=$(node -e "
+  _raw_type=$("$NODE_BIN" -e "
     const p=require('path').resolve(process.argv[1]);
     const m=JSON.parse(require('fs').readFileSync(p,'utf8'));
     const t=m[process.argv[2]];
@@ -842,7 +892,7 @@ route_agent() {
 
   if [[ -z "$_raw_type" ]]; then
     echo "ERROR: 알 수 없는 에이전트 타입: $agent" >&2
-    echo "사용 가능: $(node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync(require('path').resolve(process.argv[1]),'utf8'))).join(', '))" "$map_file" 2>/dev/null)" >&2
+    echo "사용 가능: $("$NODE_BIN" -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync(require('path').resolve(process.argv[1]),'utf8'))).join(', '))" "$map_file" 2>/dev/null)" >&2
     exit 1
   fi
 
@@ -1299,7 +1349,9 @@ heartbeat_monitor() {
   [[ "${TFX_HEARTBEAT:-1}" -eq 0 ]] && return 0
   local pid="$1"
   local interval="${2:-${TFX_HEARTBEAT_INTERVAL:-10}}"
-  local stall_threshold="${3:-${TFX_STALL_THRESHOLD:-60}}"
+  # 땜빵(PLANNING P4 구현 전): 60 → 300. MCP init/재시도 여유 + false STALL 감소.
+  local stall_threshold="${3:-${TFX_STALL_THRESHOLD:-300}}"
+  local expected_duration="${TFX_EXPECTED_DURATION_SEC:-}"
   local last_size=0 stall_count=0
   local pid_gone=false
   local post_exit_checks=0
@@ -1330,18 +1382,27 @@ heartbeat_monitor() {
     [[ -f "$STDERR_LOG" ]] && stderr_size=$(wc -c < "$STDERR_LOG" 2>/dev/null || echo 0)
     current_size=$((current_size + stderr_size))
     local elapsed=$(($(date +%s) - TIMESTAMP))
+    local expected_suffix=""
+    if [[ -n "$expected_duration" && "$expected_duration" =~ ^[0-9]+$ && "$expected_duration" -gt 0 ]]; then
+      expected_suffix=" expected=${expected_duration}s"
+      if [[ "$elapsed" -gt $((expected_duration * 2)) ]]; then
+        expected_suffix="${expected_suffix} anomaly=slow"
+      fi
+    fi
 
     if [[ "$current_size" -gt "$last_size" ]]; then
       stall_count=0
       if [[ "$pid_gone" == "true" ]]; then
         local _fi="forked"; [[ -n "$last_known_forks" ]] && _fi="forks:${last_known_forks// /,}"
-        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=active(${_fi})" >&2
+        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=active(${_fi})" >&2
         post_exit_checks=0  # reset — still producing output
       else
-        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=active" >&2
+        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=active" >&2
       fi
     else
       stall_count=$((stall_count + interval))
+      local probe_state=""
+      probe_state="$(read_probe_state "$pid" 2>/dev/null || true)"
       if [[ "$pid_gone" == "true" ]]; then
         if [[ -n "$last_known_forks" ]]; then
           # Direct fork tracking — terminate when all forks are dead
@@ -1350,26 +1411,43 @@ heartbeat_monitor() {
             kill -0 "$_fp" 2>/dev/null && _alive=true && break
           done
           if [[ "$_alive" == "false" ]]; then
-            echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=terminated(forks-exited)" >&2
+            echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=terminated(forks-exited)" >&2
             break
           fi
-          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=fork-idle(${last_known_forks// /,})" >&2
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=fork-idle(${last_known_forks// /,})" >&2
         else
           # Fallback: output-based drain (no fork PIDs found)
           post_exit_checks=$((post_exit_checks + 1))
           if [[ "$post_exit_checks" -ge "$max_post_exit_checks" ]]; then
-            echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=terminated(drain-done)" >&2
+            echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=terminated(drain-done)" >&2
             break
           fi
-          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=draining(${post_exit_checks}/${max_post_exit_checks})" >&2
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=draining(${post_exit_checks}/${max_post_exit_checks})" >&2
         fi
+      elif [[ "$probe_state" =~ ^(mcp_initializing|input_wait)$ ]]; then
+        stall_count=0
+        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=${probe_state}(probe-grace)" >&2
       elif [[ "$stall_count" -ge "$stall_threshold" ]]; then
-        # STALL kill (#144/#66 regression guard): stall=threshold+grace 이상 지속 시 SIGTERM→SIGKILL.
-        # 기본 활성화. TFX_STALL_KILL=0 으로 opt-out. grace=30s (기본) 은 SSE/MCP 정상 handshake 여유.
-        local kill_on_stall="${TFX_STALL_KILL:-1}"
+        # STALL 판정 modes (#165 PLANNING P4):
+        #   off  (alias: 0, disabled)  — silent. kill 안 함, STALL_CLASSIFY 로그도 없음
+        #   classify (default)          — kill 안 함. STALL_CLASSIFY 로그로 evidence 노출
+        #   kill (alias: 1, on)         — threshold+grace 초과 시 SIGTERM→SIGKILL
+        # PR #160 에서 default 1 → 0 으로 임시 후퇴 (false kill 방지). 본 PR(#165) 에서
+        # classify 로 승격 — evidence 는 남기되 false kill 리스크 없음.
+        local kill_on_stall="${TFX_STALL_KILL:-classify}"
+        [[ -z "$kill_on_stall" ]] && kill_on_stall="classify"
         local kill_grace="${TFX_STALL_KILL_GRACE:-30}"
-        if [[ "$kill_on_stall" -eq 1 && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
-          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=STALL_KILL stall=${stall_count}s — SIGTERM" >&2
+        local _should_kill=0
+        case "$kill_on_stall" in
+          1|on|kill) _should_kill=1 ;;
+          classify|0|off|disabled) ;;
+          *)
+            echo "[tfx-heartbeat] pid=$pid warning TFX_STALL_KILL=$kill_on_stall unknown, fallback classify" >&2
+            kill_on_stall="classify"
+            ;;
+        esac
+        if [[ "$_should_kill" -eq 1 && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL_KILL stall=${stall_count}s — SIGTERM" >&2
           # Snapshot child PIDs before SIGTERM — wrapper 가 SIGTERM 을 수용해 죽으면
           # 부모 소멸 후 taskkill /T 가 자식 트리를 탐색하지 못해 codex 자식이 orphan 으로 남는다.
           # 사용자 보고(2026-04-22): "tfx-route 래퍼 exit 이후에도 Codex 자식이 살아있음".
@@ -1417,9 +1495,12 @@ heartbeat_monitor() {
           fi
           break
         fi
-        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=STALL stall=${stall_count}s" >&2
+        if [[ "$kill_on_stall" == "classify" && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL_CLASSIFY stall=${stall_count}s (no-kill — TFX_STALL_KILL=classify)" >&2
+        fi
+        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL stall=${stall_count}s" >&2
       else
-        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=quiet stall=${stall_count}s" >&2
+        echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=quiet stall=${stall_count}s" >&2
       fi
     fi
     last_size=$current_size
@@ -1581,26 +1662,32 @@ _mcp_preflight_filter_dead() {
   CODEX_CONFIG_FLAGS=("${new_flags[@]}")
   echo "[tfx-route] MCP preflight: ${#dead_names[@]}개 dead MCP 제외 (${dead_list})" >&2
 
-  # #148: profile-allowed 전부 dead 인 all-dead 엣지케이스 조기 실패.
-  # 빈 allowed_pat 은 _codex_config_swap fail-safe (#132) 에 의해 원본 config
-  # 전체를 유지 → 비필요 MCP 까지 전부 spawn → 역효과.
-  # TFX_MCP_ALLOW_ALL_DEAD=1 로 명시적 opt-in 시 MCP 없이 진행 (degraded).
+  # #170 graceful degradation (회귀 fix):
+  # all-dead 시 default 는 exec mode 자동 fallback. TFX_MCP_FAIL_ON_ALL_DEAD=1 로
+  # 명시 opt-in 시만 #148 기존 동작 (early fail). TFX_MCP_ALLOW_ALL_DEAD=1 은 호환성
+  # 유지 (alias for graceful default). 단 transport 가 auto 인 채로 run_codex_mcp 를
+  # 호출하면 dead MCP 와 connect 시도 → stall → 본 fix 의 _TFX_MCP_DEGRADED=1 marker
+  # 가 호출자 에서 transport=exec 강제 + MCP_HINT 자동 주입 skip 을 유발한다.
   local remaining_alive=0
   local rflag
   for rflag in "${CODEX_CONFIG_FLAGS[@]}"; do
-    if [[ "$rflag" =~ ^mcp_servers\.[^.]+\.enabled=true$ ]]; then
+    # #153 + #170 P1: candidate 추출 정규식 (line 1607) 과 일관 — dotted server 이름
+    # (e.g. mcp_servers.foo.bar.enabled=true) 도 alive 로 카운트한다. `[^.]+` 는 첫 dot
+    # 에서 끊겨 dotted alive 만 남은 경우 false all-dead 판정 → 불필요 degraded.
+    if [[ "$rflag" =~ ^mcp_servers\..+\.enabled=true$ ]]; then
       remaining_alive=$((remaining_alive + 1))
     fi
   done
 
   if [[ "$remaining_alive" -eq 0 ]]; then
-    if [[ "${TFX_MCP_ALLOW_ALL_DEAD:-0}" == "1" ]]; then
-      echo "[tfx-route] TFX_MCP_ALLOW_ALL_DEAD=1 — MCP 없이 계속 진행 (degraded)" >&2
-      return 0
+    if [[ "${TFX_MCP_FAIL_ON_ALL_DEAD:-0}" == "1" ]]; then
+      echo "[tfx-route] 조기 실패: TFX_MCP_FAIL_ON_ALL_DEAD=1 + MCP 전부 dead — Codex 호출 중단" >&2
+      echo "  복구: (1) dead MCP 복구 (2) TFX_MCP_HEALTH_CHECK=0 preflight 비활성 (3) TFX_MCP_FAIL_ON_ALL_DEAD=0 graceful degradation" >&2
+      return 78
     fi
-    echo "[tfx-route] 조기 실패: profile 에서 허용한 MCP 전부 dead — Codex 호출 중단" >&2
-    echo "  복구: (1) dead MCP 복구 (2) TFX_MCP_HEALTH_CHECK=0 preflight 비활성 (3) TFX_MCP_ALLOW_ALL_DEAD=1 MCP 없이 진행" >&2
-    return 78
+    export _TFX_MCP_DEGRADED=1
+    echo "[tfx-route] graceful degradation: MCP 전부 dead → exec mode 자동 전환 (set TFX_MCP_FAIL_ON_ALL_DEAD=1 to revert to early-fail)" >&2
+    return 0
   fi
 }
 
@@ -1922,6 +2009,9 @@ main() {
     TIMEOUT_SEC="$DEFAULT_TIMEOUT"
   fi
 
+  TFX_EXPECTED_DURATION_SEC="${TFX_EXPECTED_DURATION_SEC:-$(estimate_expected_duration_sec "$AGENT_TYPE" "$MCP_PROFILE" "$PROMPT")}"
+  export TFX_EXPECTED_DURATION_SEC
+
   # 컨텍스트 파일 → 프롬프트에 주입
   if [[ -n "$CONTEXT_FILE" && -f "$CONTEXT_FILE" ]]; then
     local ctx_content
@@ -2046,6 +2136,19 @@ FALLBACK_EOF
     # swap 후 config override 플래그 클리어 — 제거된 서버에 override 보내면 "invalid transport" 에러
     CODEX_CONFIG_FLAGS=()
     CODEX_CONFIG_JSON="{}"
+    # #170 graceful degradation: MCP 전부 dead 면 transport 무관 exec 강제.
+    # _mcp_preflight_filter_dead 가 _TFX_MCP_DEGRADED=1 를 export 했으면 이미 stall 보장 안 됨.
+    # 사용자가 TFX_CODEX_TRANSPORT=mcp 명시했더라도 dead MCP 와 connect 시도 = stall →
+    # warning + exec 강제 (transport 명시는 사용자 의도지만 stall 회피가 우선).
+    # MCP_HINT (e.g. "context7으로 조회하세요") 도 prompt 에서 제거 — degraded 환경에서
+    # 모델이 사용 불가 도구를 시도하면 stall/실패 trigger.
+    if [[ "${_TFX_MCP_DEGRADED:-0}" == "1" ]]; then
+      if [[ "$TFX_CODEX_TRANSPORT" == "mcp" ]]; then
+        echo "[tfx-route] WARNING: TFX_CODEX_TRANSPORT=mcp + all-MCP-dead → exec 강제 (stall 회피)" >&2
+      fi
+      TFX_CODEX_TRANSPORT="exec"
+      FULL_PROMPT="$PROMPT"
+    fi
     codex_transport_effective="exec"
     if [[ "$TFX_CODEX_TRANSPORT" != "exec" ]]; then
       run_codex_mcp "$FULL_PROMPT" "$use_tee" || exit_code=$?
@@ -2055,6 +2158,11 @@ FALLBACK_EOF
         # MCP 실패 → exec fallback. run_codex_exec는 < /dev/null 로 stdin 블록 회피 (line 1639).
         # 정책: codex/gemini 강건성 — MCP 가용 시 MCP, 실패 시 그래도 워커 자체는 굴러간다.
         echo "[tfx-route] Codex MCP 실패(exit=${exit_code}). exec fallback 시도." >&2
+        local _sd
+        _sd="$(_get_script_dir)"
+        if [[ -f "$_sd/hub-ensure.mjs" ]]; then
+          "$NODE_BIN" "$_sd/hub-ensure.mjs" >/dev/null 2>&1 || true
+        fi
         exit_code=0
         run_codex_exec "$FULL_PROMPT" "$use_tee" || exit_code=$?
         codex_transport_effective="exec-fallback"