triflux 10.13.10 → 10.14.0

package/hub/team/retry-state-machine.mjs

@@ -39,8 +39,8 @@ export const MODES = Object.freeze({
 });
 
 const DEFAULT_ESCALATION_CHAIN = Object.freeze([
-  Object.freeze({ cli: "codex", model: "gpt-5-mini" }),
-  Object.freeze({ cli: "codex", model: "gpt-5" }),
+  Object.freeze({ cli: "codex", model: "gpt-5.4-mini" }),
+  Object.freeze({ cli: "codex", model: "gpt-5.5" }),
   Object.freeze({ cli: "claude", model: "sonnet-4-6" }),
   Object.freeze({ cli: "claude", model: "opus-4-7" }),
 ]);

package/package.json

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

package/scripts/lib/mcp-health.mjs

@@ -0,0 +1,771 @@
+#!/usr/bin/env node
+// scripts/lib/mcp-health.mjs
+// Dead MCP preflight — session 18 checkpoint의 P3 root-cause fix.
+// Codex config.toml 의 각 mcp_servers.* 정의를 probe 해서 응답 안하면 dead 판정.
+// 결과는 ~/.codex/mcp-health-cache.json 에 TTL 기반으로 캐시.
+// tfx-route.sh 가 swap 전에 이 결과를 읽어 dead 서버를 enabled=false 로 override.
+
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_CONFIG_PATH = path.join(homedir(), ".codex", "config.toml");
+const DEFAULT_CACHE_PATH = path.join(
+  homedir(),
+  ".codex",
+  "mcp-health-cache.json",
+);
+const DEFAULT_TTL_MS = 300_000; // 5 min
+const DEFAULT_PROBE_TIMEOUT_MS = 3_000;
+
+// ────────── TOML (mcp_servers 한정 단순 파서) ──────────
+
+function parseTomlArrayLiteral(literal) {
+  const inner = literal.trim().slice(1, -1).trim();
+  if (!inner) return [];
+  const items = [];
+  let i = 0;
+  while (i < inner.length) {
+    while (i < inner.length && /[\s,]/.test(inner[i])) i++;
+    if (i >= inner.length) break;
+    const ch = inner[i];
+    if (ch === '"' || ch === "'") {
+      let j = i + 1;
+      while (j < inner.length) {
+        if (inner[j] === "\\" && ch === '"') {
+          j += 2;
+          continue;
+        }
+        if (inner[j] === ch) break;
+        j++;
+      }
+      if (ch === '"') items.push(JSON.parse(inner.slice(i, j + 1)));
+      else items.push(inner.slice(i + 1, j));
+      i = j + 1;
+    } else {
+      let j = i;
+      while (j < inner.length && inner[j] !== ",") j++;
+      items.push(inner.slice(i, j).trim());
+      i = j;
+    }
+  }
+  return items;
+}
+
+function parseTomlScalar(raw) {
+  const v = raw.replace(/\s+#.*$/, "").trim();
+  if (/^".*"$/.test(v)) return JSON.parse(v);
+  if (/^'.*'$/.test(v)) return v.slice(1, -1);
+  if (v.startsWith("[") && v.endsWith("]")) return parseTomlArrayLiteral(v);
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  if (v === "true") return true;
+  if (v === "false") return false;
+  return v;
+}
+
+// 문자열 리터럴 밖의 `# ...` 은 라인 끝 주석. multiline buffer 에 누적하기
+// 전에 line 단위로 제거해야 parseTomlArrayLiteral 이 scalar 분기에서 주석 문자열을
+// item 으로 잘못 포함하지 않는다.
+function stripInlineComment(line) {
+  let inString = false;
+  let stringChar = null;
+  let escaped = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inString) {
+      if (ch === "\\" && stringChar === '"') {
+        escaped = true;
+        continue;
+      }
+      if (ch === stringChar) {
+        inString = false;
+        stringChar = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      continue;
+    }
+    if (ch === "#") return line.slice(0, i).trimEnd();
+  }
+  return line;
+}
+
+// 문자열 리터럴 내부를 제외한 bracket depth. 음수는 over-close.
+// Review finding A1 (commit 9298fd6 cross-review): 멀티라인 array 값
+// (예: `args = [\n  "run",\n  "server.js"\n]`) 을 single-line 파서가 `"["`
+// 문자열로 오인해 probeStdio 가 args=[] 로 실행 → 정상 서버를 dead 로 오탐.
+// Inline comment 는 newline 전까지만 무시 — 멀티라인 buffer 에서 첫 `#` 이후
+// 전체가 drop 되면 안 됨.
+function countBracketDelta(str) {
+  let depth = 0;
+  let inString = false;
+  let stringChar = null;
+  let escaped = false;
+  let inComment = false;
+  for (const ch of str) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (inComment) {
+      if (ch === "\n") inComment = false;
+      continue;
+    }
+    if (inString) {
+      if (ch === "\\" && stringChar === '"') {
+        escaped = true;
+        continue;
+      }
+      if (ch === stringChar) {
+        inString = false;
+        stringChar = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      continue;
+    }
+    if (ch === "#") {
+      inComment = true;
+      continue;
+    }
+    if (ch === "[") depth++;
+    else if (ch === "]") depth--;
+  }
+  return depth;
+}
+
+export function parseMcpServersFromToml(content = "") {
+  const servers = {};
+  const lines = content.split(/\r?\n/);
+  let name = null;
+  let scope = null; // "root" | "env"
+  let pendingKey = null;
+  let pendingBuffer = "";
+
+  function assign(key, value) {
+    if (scope === "env") servers[name].env[key] = String(value);
+    else servers[name][key] = value;
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/^\uFEFF/, "").trim();
+
+    if (pendingKey !== null) {
+      pendingBuffer += " " + stripInlineComment(line);
+      if (countBracketDelta(pendingBuffer) <= 0) {
+        assign(pendingKey, parseTomlScalar(pendingBuffer));
+        pendingKey = null;
+        pendingBuffer = "";
+      }
+      continue;
+    }
+
+    if (!line || line.startsWith("#")) continue;
+
+    const rootSection = line.match(/^\[mcp_servers\.([a-zA-Z0-9_.-]+)\]$/);
+    const envSection = line.match(/^\[mcp_servers\.([a-zA-Z0-9_.-]+)\.env\]$/);
+    const anySection = line.startsWith("[");
+
+    if (envSection) {
+      name = envSection[1];
+      scope = "env";
+      if (!servers[name]) servers[name] = {};
+      if (!servers[name].env) servers[name].env = {};
+      continue;
+    }
+    if (rootSection) {
+      name = rootSection[1];
+      scope = "root";
+      if (!servers[name]) servers[name] = {};
+      continue;
+    }
+    if (anySection) {
+      name = null;
+      scope = null;
+      continue;
+    }
+    if (!name) continue;
+
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    const cleanValue = stripInlineComment(rawValue);
+
+    if (countBracketDelta(cleanValue) > 0) {
+      pendingKey = key;
+      pendingBuffer = cleanValue;
+      continue;
+    }
+
+    assign(key, parseTomlScalar(cleanValue));
+  }
+
+  return servers;
+}
+
+export function readMcpServers(configPath = DEFAULT_CONFIG_PATH) {
+  if (!existsSync(configPath)) return {};
+  try {
+    const content = readFileSync(configPath, "utf8");
+    return parseMcpServersFromToml(content);
+  } catch {
+    return {};
+  }
+}
+
+// ────────── Binary Fingerprint (Issue #149) ──────────
+// Cache staleness 방지: config.toml mtime 만 보면 `npm i -g <mcp-bin>` 설치/제거
+// 를 감지 못해 5분간 stale dead 판정이 유지된다. 서버별 fingerprint (command,
+// args, 해석된 binary path+mtime+size 또는 url) 을 cache 에 저장하고 일치할
+// 때만 hit 으로 판정한다.
+
+function statBinary(filePath) {
+  try {
+    const st = statSync(filePath);
+    if (!st.isFile()) return null;
+    return { path: filePath, mtime: Math.floor(st.mtimeMs), size: st.size };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveBinaryPath(command) {
+  if (!command || typeof command !== "string") return null;
+  if (path.isAbsolute(command)) return statBinary(command);
+
+  const pathEntries = (process.env.PATH || "")
+    .split(path.delimiter)
+    .filter(Boolean);
+  const pathExts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+          .split(";")
+          .filter(Boolean)
+      : [""];
+  // command 에 이미 확장자가 있을 수도 있으니 빈 확장자도 시도.
+  const exts = pathExts.includes("") ? pathExts : ["", ...pathExts];
+
+  for (const dir of pathEntries) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, command + ext);
+      const result = statBinary(candidate);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+
+export function computeFingerprint(def) {
+  if (!def || typeof def !== "object") return { type: "none" };
+  if (typeof def.url === "string" && def.url) {
+    return { type: "http", url: def.url };
+  }
+  if (typeof def.command === "string" && def.command) {
+    return {
+      type: "stdio",
+      command: def.command,
+      args: Array.isArray(def.args) ? [...def.args] : [],
+      binary: resolveBinaryPath(def.command),
+    };
+  }
+  return { type: "unknown" };
+}
+
+export function fingerprintsEqual(a, b) {
+  if (!a || !b) return false;
+  if (a.type !== b.type) return false;
+  if (a.type === "http") return a.url === b.url;
+  if (a.type === "stdio") {
+    if (a.command !== b.command) return false;
+    const ax = Array.isArray(a.args) ? a.args : [];
+    const bx = Array.isArray(b.args) ? b.args : [];
+    if (ax.length !== bx.length) return false;
+    for (let i = 0; i < ax.length; i++) {
+      if (ax[i] !== bx[i]) return false;
+    }
+    if ((a.binary === null) !== (b.binary === null)) return false;
+    if (a.binary && b.binary) {
+      if (a.binary.path !== b.binary.path) return false;
+      if (a.binary.mtime !== b.binary.mtime) return false;
+      if (a.binary.size !== b.binary.size) return false;
+    }
+    return true;
+  }
+  return true; // "none"/"unknown" — 같은 type 이면 equal
+}
+
+// ────────── Probe ──────────
+
+function makeInitializeRequest() {
+  return (
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "tfx-mcp-probe", version: "1.0.0" },
+      },
+    }) + "\n"
+  );
+}
+
+function isValidInitResponse(line) {
+  const trimmed = line.trim();
+  if (!trimmed || !trimmed.startsWith("{")) return false;
+  try {
+    const msg = JSON.parse(trimmed);
+    if (msg.jsonrpc !== "2.0") return false;
+    if (msg.id !== 1 && msg.id !== "1") return false;
+    return msg.result !== undefined || msg.error !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+export function probeStdio(def, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    let settled = false;
+    let child = null;
+
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      try {
+        child?.kill("SIGKILL");
+      } catch {
+        /* best effort */
+      }
+      resolve({ ...result, ms: Date.now() - start });
+    };
+
+    const timer = setTimeout(
+      () => done({ alive: false, reason: "timeout" }),
+      timeoutMs,
+    );
+
+    try {
+      child = spawn(def.command, Array.isArray(def.args) ? def.args : [], {
+        env: { ...process.env, ...(def.env || {}) },
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      done({ alive: false, reason: `spawn:${err.code || err.message}` });
+      return;
+    }
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      done({ alive: false, reason: `error:${err.code || err.message}` });
+    });
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      done({
+        alive: false,
+        reason: signal ? `signal:${signal}` : `exit:${code}`,
+      });
+    });
+
+    let buffer = "";
+    child.stdout.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (isValidInitResponse(line)) {
+          clearTimeout(timer);
+          done({ alive: true });
+          return;
+        }
+      }
+    });
+    child.stderr.on("data", () => {
+      /* drain */
+    });
+
+    try {
+      child.stdin.write(makeInitializeRequest(), (err) => {
+        if (err)
+          done({ alive: false, reason: `stdin:${err.code || err.message}` });
+      });
+    } catch (err) {
+      done({ alive: false, reason: `write:${err.code || err.message}` });
+    }
+  });
+}
+
+// Review finding A2 (commit 9298fd6 cross-review): 기존 구현은 status 2xx-4xx
+// 전부 alive 로 취급 — 404/401 HTML 오류 페이지를 healthy 로 오판. 실제 MCP
+// endpoint 는 200 + JSON-RPC body 를 돌려줘야 살아있는 것. 2xx + JSON-RPC
+// envelope (id 일치, result|error 존재) 둘 다 검증한다.
+export async function probeHttp(url, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+  const start = Date.now();
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: makeInitializeRequest().trim(),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const ms = Date.now() - start;
+    if (res.status < 200 || res.status >= 300) {
+      return { alive: false, reason: `http:${res.status}`, ms };
+    }
+    let body;
+    try {
+      body = await res.text();
+    } catch {
+      return { alive: false, reason: "http:body-read-failed", ms };
+    }
+    // SSE / ndjson 환경 대비 — 첫 JSON-RPC envelope 하나만 찾으면 충분.
+    const envelope = body
+      .split(/\r?\n/)
+      .map((chunk) => chunk.replace(/^data:\s*/, "").trim())
+      .find((chunk) => chunk.startsWith("{"));
+    if (!envelope) {
+      return { alive: false, reason: "http:no-jsonrpc-body", ms };
+    }
+    try {
+      const msg = JSON.parse(envelope);
+      if (msg.jsonrpc !== "2.0") {
+        return { alive: false, reason: "http:not-jsonrpc", ms };
+      }
+      if (msg.id !== 1 && msg.id !== "1") {
+        return { alive: false, reason: "http:id-mismatch", ms };
+      }
+      if (msg.result === undefined && msg.error === undefined) {
+        return { alive: false, reason: "http:no-result", ms };
+      }
+      return { alive: true, ms };
+    } catch {
+      return { alive: false, reason: "http:invalid-json", ms };
+    }
+  } catch (err) {
+    const ms = Date.now() - start;
+    const reason =
+      err?.name === "AbortError" || err?.name === "TimeoutError"
+        ? "timeout"
+        : `fetch:${err?.code || err?.message || "unknown"}`;
+    return { alive: false, reason, ms };
+  }
+}
+
+export async function probeServer(def, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+  if (!def || typeof def !== "object") {
+    return { alive: false, reason: "no-definition", ms: 0 };
+  }
+  if (typeof def.url === "string" && def.url) {
+    return probeHttp(def.url, timeoutMs);
+  }
+  if (typeof def.command === "string" && def.command) {
+    return probeStdio(def, timeoutMs);
+  }
+  return { alive: false, reason: "no-transport", ms: 0 };
+}
+
+// ────────── Cache ──────────
+
+export function readCache(cachePath = DEFAULT_CACHE_PATH) {
+  if (!existsSync(cachePath)) return null;
+  try {
+    return JSON.parse(readFileSync(cachePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(cache, cachePath = DEFAULT_CACHE_PATH) {
+  // Issue #154: writeFileSync 는 non-atomic 이라 swarm/병렬 tfx-route 가 동시
+  // write 하면 reader 가 partial JSON 을 받아 SyntaxError → null 반환. tmp 파일에
+  // 쓰고 rename 으로 교체하면 reader 는 항상 완전한 파일을 본다 (POSIX atomic,
+  // Windows MoveFileEx 도 target replace 지원). pid+timestamp 가 tmp 이름에
+  // 들어가 writer 끼리도 충돌하지 않는다.
+  const tmpPath = `${cachePath}.tmp.${process.pid}.${Date.now()}`;
+  try {
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(tmpPath, JSON.stringify(cache, null, 2), "utf8");
+    renameSync(tmpPath, cachePath);
+    return true;
+  } catch {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* best effort */
+    }
+    return false;
+  }
+}
+
+export function isCacheFresh(
+  cache,
+  { now = Date.now(), configMtime = 0 } = {},
+) {
+  if (!cache || typeof cache !== "object") return false;
+  if (typeof cache.checkedAt !== "number") return false;
+  if (typeof cache.ttlMs !== "number") return false;
+  if (configMtime && cache.configMtime !== configMtime) return false;
+  return now - cache.checkedAt < cache.ttlMs;
+}
+
+// ────────── Orchestration ──────────
+
+export async function probeAll({
+  configPath = DEFAULT_CONFIG_PATH,
+  cachePath = DEFAULT_CACHE_PATH,
+  names = null,
+  timeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+  ttlMs = DEFAULT_TTL_MS,
+  useCache = true,
+  writeCacheFile = true,
+  now = Date.now(),
+} = {}) {
+  const configMtime = existsSync(configPath)
+    ? Math.floor(statSync(configPath).mtimeMs)
+    : 0;
+
+  const servers = readMcpServers(configPath);
+  const allNames = Object.keys(servers);
+  const targets =
+    Array.isArray(names) && names.length
+      ? names.filter((n) => allNames.includes(n))
+      : allNames;
+
+  // Issue #149: per-server fingerprint (binary path+mtime+size) 로 cache 를
+  // invalidate 한다. configMtime 은 여전히 meta 로 저장하지만 hit 판정에는
+  // 쓰지 않는다 — binary 설치/제거가 config.toml mtime 을 바꾸지 않기 때문.
+  const fingerprints = Object.fromEntries(
+    targets.map((name) => [name, computeFingerprint(servers[name])]),
+  );
+
+  const existingCache = useCache ? readCache(cachePath) : null;
+  const cachedResults = existingCache?.results || {};
+  const cacheWithinTtl =
+    existingCache &&
+    typeof existingCache.checkedAt === "number" &&
+    typeof existingCache.ttlMs === "number" &&
+    now - existingCache.checkedAt < existingCache.ttlMs;
+
+  const hits = {};
+  const stale = [];
+  for (const name of targets) {
+    const prior = cachedResults[name];
+    if (
+      cacheWithinTtl &&
+      prior &&
+      prior.fingerprint &&
+      fingerprintsEqual(prior.fingerprint, fingerprints[name])
+    ) {
+      hits[name] = prior;
+    } else {
+      stale.push(name);
+    }
+  }
+
+  if (stale.length === 0) {
+    return { results: hits, source: "cache", configMtime };
+  }
+
+  const probes = stale.map(async (name) => {
+    const def = servers[name] || {};
+    const result = await probeServer(def, timeoutMs);
+    return [name, { ...result, fingerprint: fingerprints[name] }];
+  });
+  const settled = await Promise.all(probes);
+  const freshResults = Object.fromEntries(settled);
+
+  const allResults = { ...hits, ...freshResults };
+
+  if (writeCacheFile) {
+    // 이번에 probe 한 서버만 결과 갱신; 이전 cache 의 다른 서버 결과는 보존.
+    const merged = { ...cachedResults, ...freshResults };
+    writeCache(
+      {
+        configMtime,
+        checkedAt: now,
+        ttlMs,
+        results: merged,
+      },
+      cachePath,
+    );
+  }
+
+  return { results: allResults, source: "probe", configMtime };
+}
+
+export function splitHealthy(results) {
+  const healthy = [];
+  const dead = [];
+  for (const [name, result] of Object.entries(results || {})) {
+    if (result?.alive) healthy.push(name);
+    else dead.push(name);
+  }
+  return { healthy, dead };
+}
+
+// ────────── CLI ──────────
+
+function parseCliArgs(argv) {
+  const args = {
+    command: "probe",
+    names: null,
+    configPath: DEFAULT_CONFIG_PATH,
+    cachePath: DEFAULT_CACHE_PATH,
+    timeoutMs:
+      Number(process.env.TFX_MCP_PROBE_TIMEOUT_MS) || DEFAULT_PROBE_TIMEOUT_MS,
+    ttlMs: Number(process.env.TFX_MCP_HEALTH_TTL_MS) || DEFAULT_TTL_MS,
+    useCache: true,
+    format: "json",
+  };
+
+  const [first] = argv;
+  if (first && !first.startsWith("-")) {
+    args.command = first;
+    argv = argv.slice(1);
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    const next = () => {
+      const val = argv[i + 1];
+      if (val === undefined) throw new Error(`${token} needs a value`);
+      i += 1;
+      return val;
+    };
+    switch (token) {
+      case "--names":
+        args.names = next()
+          .split(/[,\s]+/)
+          .filter(Boolean);
+        break;
+      case "--config":
+        args.configPath = next();
+        break;
+      case "--cache":
+        args.cachePath = next();
+        break;
+      case "--timeout-ms":
+        args.timeoutMs = Number(next());
+        break;
+      case "--ttl-ms":
+        args.ttlMs = Number(next());
+        break;
+      case "--no-cache":
+        args.useCache = false;
+        break;
+      case "--format":
+        args.format = next();
+        break;
+      case "--help":
+      case "-h":
+        args.command = "help";
+        break;
+      default:
+        throw new Error(`unknown flag: ${token}`);
+    }
+  }
+  return args;
+}
+
+function renderHelp() {
+  return `mcp-health — dead MCP preflight probe
+
+Usage:
+  node scripts/lib/mcp-health.mjs probe [--names a,b,c] [--no-cache]
+                                        [--timeout-ms 3000] [--ttl-ms 300000]
+                                        [--format json|shell|disable-flags]
+  node scripts/lib/mcp-health.mjs list
+
+Env:
+  TFX_MCP_PROBE_TIMEOUT_MS  default 3000
+  TFX_MCP_HEALTH_TTL_MS     default 300000
+
+Output formats:
+  json           full results with ms/reason
+  shell          HEALTHY=a,b DEAD=c,d
+  disable-flags  -c mcp_servers.c.enabled=false -c mcp_servers.d.enabled=false
+`;
+}
+
+function renderOutput(results, source, format) {
+  const { healthy, dead } = splitHealthy(results);
+  if (format === "shell") {
+    return [
+      `MCP_HEALTH_SOURCE=${JSON.stringify(source)}`,
+      `MCP_HEALTHY=${JSON.stringify(healthy.join(","))}`,
+      `MCP_DEAD=${JSON.stringify(dead.join(","))}`,
+    ].join("\n");
+  }
+  if (format === "disable-flags") {
+    return dead.map((name) => `-c mcp_servers.${name}.enabled=false`).join(" ");
+  }
+  return JSON.stringify({ source, healthy, dead, results }, null, 2);
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    process.stderr.write(`[mcp-health] ${err.message}\n`);
+    process.exitCode = 64;
+    return;
+  }
+
+  if (args.command === "help") {
+    process.stdout.write(renderHelp());
+    return;
+  }
+
+  if (args.command === "list") {
+    const servers = readMcpServers(args.configPath);
+    process.stdout.write(
+      JSON.stringify(Object.keys(servers).sort(), null, 2) + "\n",
+    );
+    return;
+  }
+
+  if (args.command !== "probe") {
+    process.stderr.write(`[mcp-health] unknown command: ${args.command}\n`);
+    process.exitCode = 64;
+    return;
+  }
+
+  const { results, source } = await probeAll({
+    configPath: args.configPath,
+    cachePath: args.cachePath,
+    names: args.names,
+    timeoutMs: args.timeoutMs,
+    ttlMs: args.ttlMs,
+    useCache: args.useCache,
+  });
+  process.stdout.write(renderOutput(results, source, args.format) + "\n");
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  await runCli();
+}

package/scripts/setup.mjs

@@ -49,6 +49,23 @@ const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
 const HUD_PATH = join(CLAUDE_DIR, "hud", "hud-qos-status.mjs");
 
 const REQUIRED_CODEX_PROFILES = [
+  // gpt-5.5 — 새 main 플래그십. xhigh/high/med/low 4 tier 전부 보장.
+  {
+    name: "gpt55_xhigh",
+    lines: ['model = "gpt-5.5"', 'model_reasoning_effort = "xhigh"'],
+  },
+  {
+    name: "gpt55_high",
+    lines: ['model = "gpt-5.5"', 'model_reasoning_effort = "high"'],
+  },
+  {
+    name: "gpt55_med",
+    lines: ['model = "gpt-5.5"', 'model_reasoning_effort = "medium"'],
+  },
+  {
+    name: "gpt55_low",
+    lines: ['model = "gpt-5.5"', 'model_reasoning_effort = "low"'],
+  },
   {
     name: "codex53_high",
     lines: ['model = "gpt-5.3-codex"', 'model_reasoning_effort = "high"'],
@@ -594,7 +611,7 @@ function ensureCodexHubServerConfig({
 // Only injected when the key is completely absent — existing user values are
 // never overwritten, regardless of what value was set.
 const REQUIRED_TOP_LEVEL_SETTINGS = [
-  { key: "model", value: '"gpt-5.4"' },
+  { key: "model", value: '"gpt-5.5"' },
   { key: "model_reasoning_effort", value: '"high"' },
   { key: "service_tier", value: '"fast"' },
 ];

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

@@ -25,11 +25,12 @@ function getCodexConfigPath(codexConfigPath) {
   return join(home, ...CODEX_CONFIG_FILE);
 }
 
-function getProjectMcpJsonPath(projectRoot) {
-  if (typeof projectRoot === "string" && projectRoot.length > 0) {
-    return join(projectRoot, ".claude", "mcp.json");
-  }
-  return join(process.cwd(), ".claude", "mcp.json");
+function getProjectMcpJsonPaths(projectRoot) {
+  const root =
+    typeof projectRoot === "string" && projectRoot.length > 0
+      ? projectRoot
+      : process.cwd();
+  return [join(root, ".claude", "mcp.json"), join(root, ".mcp.json")];
 }
 
 function getReason(error, fallback) {
@@ -334,7 +335,13 @@ async function syncProjectMcpFile({ filePath, hubUrl, dryRun, logger }) {
       return { kind: "error", path: filePath, reason };
     }
 
-    if (hubServer.url === hubUrl) {
+    // Claude Code 는 현재 type:"http" 만 허용. 과거 type:"url" 엔트리는 스키마 오류로
+    // project config parse 실패 → MCP 전체 연결 단절. url 일치만으로 skip 하면 legacy
+    // type 이 영원히 안 고쳐진다. syncSingleFile (user-level settings) 이 type+url
+    // 둘 다 보는 것과 동일 규약 적용.
+    const typeOk = hubServer.type === "http";
+    const urlOk = hubServer.url === hubUrl;
+    if (typeOk && urlOk) {
       log(logger, "info", `[project-mcp-sync] skipped: ${filePath}`);
       return { kind: "skipped", path: filePath };
     }
@@ -342,11 +349,12 @@ async function syncProjectMcpFile({ filePath, hubUrl, dryRun, logger }) {
     log(
       logger,
       "debug",
-      `[project-mcp-sync] ${filePath} url:${String(hubServer.url)} -> ${hubUrl}`,
+      `[project-mcp-sync] ${filePath} type:${String(hubServer.type)} url:${String(hubServer.url)} -> type:http url:${hubUrl}`,
     );
 
     if (!dryRun) {
       try {
+        hubServer.type = "http";
         hubServer.url = hubUrl;
         await writeJsonAtomic(filePath, settings);
       } catch (error) {
@@ -434,19 +442,21 @@ export async function syncProjectMcpJson({
     errors: [],
   };
 
-  const outcome = await syncProjectMcpFile({
-    filePath: getProjectMcpJsonPath(projectRoot),
-    hubUrl,
-    dryRun,
-    logger,
-  });
+  for (const filePath of getProjectMcpJsonPaths(projectRoot)) {
+    const outcome = await syncProjectMcpFile({
+      filePath,
+      hubUrl,
+      dryRun,
+      logger,
+    });
 
-  if (outcome.kind === "updated") {
-    result.updated.push(outcome.path);
-  } else if (outcome.kind === "skipped") {
-    result.skipped.push(outcome.path);
-  } else {
-    result.errors.push({ path: outcome.path, reason: outcome.reason });
+    if (outcome.kind === "updated") {
+      result.updated.push(outcome.path);
+    } else if (outcome.kind === "skipped") {
+      result.skipped.push(outcome.path);
+    } else {
+      result.errors.push({ path: outcome.path, reason: outcome.reason });
+    }
   }
 
   return result;

package/scripts/tfx-route.sh

@@ -93,6 +93,22 @@ cleanup_workers() {
   rm -f "$_PID_TRACK"
 }
 
+# ── Preflight env vars (P0 prompt-dodge): git/npm/gh 자동 응답 ──
+# 워커가 dispatch 직후 git credential / npm install / gh auth prompt에서
+# stall하지 않도록 환경변수를 선주입한다. 사용자 값이 있으면 존중.
+export GIT_TERMINAL_PROMPT="${GIT_TERMINAL_PROMPT:-0}"
+export GIT_ASKPASS="${GIT_ASKPASS:-false}"
+export npm_config_yes="${npm_config_yes:-true}"
+
+_preflight_check_gh_auth() {
+  command -v gh >/dev/null 2>&1 || return 0
+  [[ -n "${GH_TOKEN:-}" || -n "${GITHUB_TOKEN:-}" ]] && return 0
+  if ! gh auth status >/dev/null 2>&1; then
+    echo "[tfx-route] 경고: gh 인증 미설정 (GH_TOKEN/GITHUB_TOKEN 미설정 + 'gh auth status' 실패). gh 명령 실행 시 prompt 발생 가능" >&2
+  fi
+}
+_preflight_check_gh_auth
+
 # ── config.toml sandbox/approval_mode 감지 ──
 # config.toml에 이미 설정되어 있으면 CLI 플래그 중복 시 Codex가 에러를 던짐.
 # 단, [mcp_servers.*.tools.*] 섹션 내부의 approval_mode는 tool 단위 승인 설정으로
@@ -1471,6 +1487,123 @@ resolve_codex_mcp_script() {
     "$sd/hub/workers/codex-mcp.mjs" "$sd/../hub/workers/codex-mcp.mjs"
 }
 
+## ── MCP Preflight: dead 서버 감지 후 CODEX_CONFIG_FLAGS 에서 제거 ──
+# Session 18 체크포인트 P3 root-cause fix. dead MCP 가 allowed_pat 에 포함되면
+# _codex_config_swap 이 section 을 유지 → Codex 가 init 시도 → -32000 으로 죽는다.
+# Preflight 가 각 서버를 probe (initialize 요청) 한 뒤 응답 없는 서버의
+# enabled=true 플래그를 제거해서 swap 이 그 section 을 자동으로 drop 하게 만든다.
+# Opt-out: TFX_MCP_HEALTH_CHECK=0
+_mcp_preflight_filter_dead() {
+  local opt="${TFX_MCP_HEALTH_CHECK:-1}"
+  if [[ "$opt" == "0" || "$opt" == "false" || "$opt" == "off" ]]; then
+    return 0
+  fi
+  if [[ "${#CODEX_CONFIG_FLAGS[@]}" -eq 0 ]]; then
+    return 0
+  fi
+
+  local sd; sd="$(_get_script_dir)"
+  local health_script
+  health_script="$(_resolve_script "${TFX_MCP_HEALTH_SCRIPT:-}" \
+    ${TFX_PKG_ROOT:+"$TFX_PKG_ROOT/scripts/lib/mcp-health.mjs"} \
+    "$sd/lib/mcp-health.mjs" "$sd/../scripts/lib/mcp-health.mjs")" || return 0
+  [[ -n "$health_script" && -f "$health_script" ]] || return 0
+  command -v "$NODE_BIN" &>/dev/null || return 0
+
+  # CODEX_CONFIG_FLAGS 에서 enabled=true 항목으로부터 후보 서버 이름 수집.
+  # #153: parseMcpServersFromToml 은 section 이름에 dot 을 허용 (`[a-zA-Z0-9_.-]+`).
+  # `[mcp_servers.foo.bar]` 같은 dotted 서버가 `mcp_servers.foo.bar.enabled=true`
+  # 플래그로 전달될 때 과거 `[^.]+` 정규식은 `foo` 만 captur 해 suffix 매치 실패
+  # → dotted 서버가 preflight candidate 에서 통째로 누락됐다. `\.enabled=true$`
+  # 로 끝 anchor 가 고정돼 있어 `(.+)` greedy 가 반복 보장한다.
+  local names=""
+  local i=0
+  local n="${#CODEX_CONFIG_FLAGS[@]}"
+  while (( i < n )); do
+    local flag="${CODEX_CONFIG_FLAGS[$i]}"
+    if [[ "$flag" == "-c" ]] && (( i + 1 < n )); then
+      local value="${CODEX_CONFIG_FLAGS[$((i+1))]}"
+      if [[ "$value" =~ ^mcp_servers\.(.+)\.enabled=true$ ]]; then
+        [[ -n "$names" ]] && names="${names},"
+        names="${names}${BASH_REMATCH[1]}"
+      fi
+      i=$((i+2))
+    else
+      i=$((i+1))
+    fi
+  done
+  [[ -z "$names" ]] && return 0
+
+  # Probe — TTL cache 로 재호출 부하 억제
+  local probe_output
+  if ! probe_output=$("$NODE_BIN" "$health_script" probe \
+      --names "$names" --format shell 2>/dev/null); then
+    echo "[tfx-route] MCP preflight probe 실패 — 스킵" >&2
+    return 0
+  fi
+
+  local dead_list=""
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^MCP_DEAD=\"(.*)\"$ ]]; then
+      dead_list="${BASH_REMATCH[1]}"
+    fi
+  done <<< "$probe_output"
+  [[ -z "$dead_list" ]] && return 0
+
+  # dead 서버의 모든 mcp_servers.<dead>.* override 를 CODEX_CONFIG_FLAGS 에서 제거
+  local -a dead_names=()
+  IFS=',' read -ra dead_names <<< "$dead_list"
+  local -a new_flags=()
+  i=0
+  while (( i < n )); do
+    local flag="${CODEX_CONFIG_FLAGS[$i]}"
+    if [[ "$flag" == "-c" ]] && (( i + 1 < n )); then
+      local value="${CODEX_CONFIG_FLAGS[$((i+1))]}"
+      local drop=false
+      local dead
+      for dead in "${dead_names[@]}"; do
+        [[ -z "$dead" ]] && continue
+        if [[ "$value" == "mcp_servers.${dead}."* ]]; then
+          drop=true
+          break
+        fi
+      done
+      if [[ "$drop" == "false" ]]; then
+        new_flags+=("-c" "$value")
+      fi
+      i=$((i+2))
+    else
+      new_flags+=("$flag")
+      i=$((i+1))
+    fi
+  done
+
+  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).
+  local remaining_alive=0
+  local rflag
+  for rflag in "${CODEX_CONFIG_FLAGS[@]}"; do
+    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
+    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
+  fi
+}
+
 ## ── Config Swap: 프로필별 MCP 서버 필터링 ──
 # codex exec는 -c flag로 MCP enabled/disabled를 제어할 수 없다.
 # config.toml을 원자적으로 교체하여 불필요한 서버 시작을 방지한다.
@@ -1633,10 +1766,12 @@ run_codex_exec() {
   # -c flags는 codex exec에서 MCP enabled 제어 불가 — config swap으로 대체
   # config swap은 codex 블록 최상단(_codex_config_swap "filter")에서 실행됨
 
+  # `--` end-of-options: prompt가 '--'/'---' (front-matter 등)로 시작하면
+  # clap이 flag로 파싱하는 것을 방지. fallback path에서 특히 중요.
   if [[ "$use_tee_flag" == "true" ]]; then
-    "$TIMEOUT_BIN" "$TIMEOUT_SEC" "$CLI_CMD" "${codex_args[@]}" "$prompt" < /dev/null 2>"$STDERR_LOG" | tee "$STDOUT_LOG" &
+    "$TIMEOUT_BIN" "$TIMEOUT_SEC" "$CLI_CMD" "${codex_args[@]}" -- "$prompt" < /dev/null 2>"$STDERR_LOG" | tee "$STDOUT_LOG" &
   else
-    "$TIMEOUT_BIN" "$TIMEOUT_SEC" "$CLI_CMD" "${codex_args[@]}" "$prompt" < /dev/null >"$STDOUT_LOG" 2>"$STDERR_LOG" &
+    "$TIMEOUT_BIN" "$TIMEOUT_SEC" "$CLI_CMD" "${codex_args[@]}" -- "$prompt" < /dev/null >"$STDOUT_LOG" 2>"$STDERR_LOG" &
   fi
   worker_pid=$!
   _wait_with_heartbeat "$worker_pid" || exit_code_local=$?
@@ -1830,6 +1965,22 @@ FALLBACK_EOF
     exit 0
   fi
 
+  # Issue #156: hub-ensure 무조건 호출 — codex/gemini 가 tfx-hub MCP 를 쓸 수
+  # 있도록 사전 보장. Claude 세션 SessionStart 훅 외부에서 (Windows 재부팅 후
+  # codex 단독 실행, hub crash 후 Claude 미오픈, WSL/SSH 등) 도 hub 가 자동
+  # 기동된다. hub 가 이미 alive 면 /health 1회 호출로 no-op (저비용).
+  # best-effort: 실패해도 tfx-route 진행 차단하지 않음.
+  if command -v "$NODE_BIN" &>/dev/null; then
+    local _sd_he; _sd_he="$(_get_script_dir)"
+    local _hub_ensure_script
+    _hub_ensure_script="$(_resolve_script "${TFX_HUB_ENSURE_SCRIPT:-}" \
+      ${TFX_PKG_ROOT:+"$TFX_PKG_ROOT/scripts/hub-ensure.mjs"} \
+      "$_sd_he/hub-ensure.mjs" "$_sd_he/../scripts/hub-ensure.mjs" 2>/dev/null)" || _hub_ensure_script=""
+    if [[ -n "$_hub_ensure_script" && -f "$_hub_ensure_script" ]]; then
+      "$NODE_BIN" "$_hub_ensure_script" >/dev/null 2>&1 || true
+    fi
+  fi
+
   local FULL_PROMPT="$PROMPT"
   [[ -n "$MCP_HINT" ]] && FULL_PROMPT="${PROMPT}. ${MCP_HINT}"
   local codex_transport_effective="n/a"
@@ -1880,6 +2031,15 @@ FALLBACK_EOF
   fi
 
   if [[ "$CLI_TYPE" == "codex" ]]; then
+    # Preflight: dead MCP 감지 후 CODEX_CONFIG_FLAGS 에서 제거.
+    # swap 이 allowed_pat 을 이 배열에서 계산하므로, 여기서 제거하면
+    # dead section 이 config.toml 에서 자동으로 drop 된다.
+    # #148: preflight 가 78 반환 시 all-dead → Codex 호출 중단 (early fail).
+    local _preflight_rc=0
+    _mcp_preflight_filter_dead || _preflight_rc=$?
+    if [[ "$_preflight_rc" -eq 78 ]]; then
+      exit 78
+    fi
     # Config swap: 프로필에 맞는 MCP 서버만 남긴 임시 config 적용
     # run_codex_mcp / run_codex_exec 어느 경로든 적용되도록 최상단에서 실행
     _codex_config_swap "filter"
@@ -1892,8 +2052,12 @@ FALLBACK_EOF
       if [[ "$exit_code" -eq 0 ]]; then
         codex_transport_effective="mcp"
       elif [[ "$exit_code" -eq "$CODEX_MCP_TRANSPORT_EXIT_CODE" && "$TFX_CODEX_TRANSPORT" == "auto" ]]; then
-        echo "[tfx-route] Codex MCP bootstrap 실패(exit=${exit_code}). exec fallback 비활성(stdin 블록 위험)." >&2
-        codex_transport_effective="mcp-failed"
+        # 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
+        exit_code=0
+        run_codex_exec "$FULL_PROMPT" "$use_tee" || exit_code=$?
+        codex_transport_effective="exec-fallback"
       else
         codex_transport_effective="mcp"
       fi

package/skills/tfx-auto/SKILL.md

@@ -158,7 +158,7 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 | `--retry` | `0` | 자동 재시도 없음 | — |
 | `--retry` | `1` (기본) | bounded verify → fix loop 3회 | — |
 | `--retry` | `ralph` | **Phase 3** — true ralph state machine (unlimited, stuck detector 3회 중단) | retry-state-machine.mjs |
-| `--retry` | `auto-escalate` | **Phase 3** — 체인 승격 (codex:mini → codex:gpt-5 → claude:sonnet → claude:opus) | retry-state-machine.mjs |
+| `--retry` | `auto-escalate` | **Phase 3** — 체인 승격 (codex:5.4-mini → codex:gpt-5.5 → claude:sonnet → claude:opus) | retry-state-machine.mjs |
 | `--isolation` | `none` (기본) | cwd 공유 | — |
 | `--isolation` | `worktree` | shard별 `.codex-swarm/wt-*/` 격리 | `--parallel swarm` 자동 강제 |
 | `--remote` | `none` (기본) | 로컬만 | — |
@@ -214,8 +214,8 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 - `--retry auto-escalate` 는 `DEFAULT_ESCALATION_CHAIN` 을 기본으로 사용한다. 커스텀 체인이 필요하면 `.claude/rules/tfx-escalation-chain.md` 로 override 한다.
 
 `DEFAULT_ESCALATION_CHAIN`
-1. codex : gpt-5-mini
-2. codex : gpt-5
+1. codex : gpt-5.4-mini
+2. codex : gpt-5.5
 3. claude : sonnet-4-6
 4. claude : opus-4-7
 

package/skills/tfx-profile/SKILL.md

@@ -45,7 +45,7 @@ options:
 ```
 | 프로파일 | 모델 | Effort |
 |----------|------|--------|
-| fast | gpt-5.3-codex | low |
+| gpt55_high | gpt-5.5 | high |
 | ...  | ...           | ...  |
 ```
 
@@ -75,8 +75,10 @@ options:
 2. AskUserQuestion으로 모델 선택:
    ```
    options:
-     - label: "gpt-5.4"         → 최신 플래그십
-     - label: "gpt-5.3-codex"   → 코딩 특화 (Recommended)
+     - label: "gpt-5.5"         → 최신 플래그십 (Recommended)
+     - label: "gpt-5.4"         → 이전 플래그십
+     - label: "gpt-5.4-mini"    → 경량 (mini)
+     - label: "gpt-5.3-codex"   → 코딩 특화
      - label: "gpt-5.1-codex-mini" → 경량 Spark
      - label: "o3"              → 추론 특화
      - label: "o4-mini"         → 추론 경량
@@ -183,7 +185,9 @@ options:
 
 | 모델 | 용도 |
 |------|------|
-| gpt-5.4 | 최신 플래그십 |
+| gpt-5.5 | 최신 플래그십 (default) |
+| gpt-5.4 | 이전 플래그십 |
+| gpt-5.4-mini | 경량 (mini) |
 | gpt-5.3-codex | 코딩 특화 |
 | gpt-5.1-codex-mini | 경량 Spark |
 | o3 | 추론 특화 |