triflux 10.14.2 → 10.15.0

package/CLAUDE.md

@@ -159,3 +159,11 @@ background로 실행한 headless 결과는 **반드시 task-notification 완료
 | `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
 
 Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.
+
+## GBrain Configuration (configured by /setup-gbrain)
+- Engine: pglite
+- Config file: ~/.gbrain/config.json (mode 0600)
+- Setup date: 2026-04-25
+- MCP registered: yes (user scope, absolute path)
+- Memory sync: artifacts-only (repo: github.com/tellang/gstack-brain-tellang)
+- Current repo policy: read-write (github.com/tellang/triflux)

package/hub/intent.mjs

@@ -61,17 +61,22 @@ function _tryCodexClassify(prompt) {
  * triflux 특화 의도 카테고리 (10개)
  */
 export const INTENT_CATEGORIES = {
-  implement: { agent: "executor", mcp: "implement", effort: "codex53_high" },
-  debug: { agent: "debugger", mcp: "implement", effort: "codex53_high" },
-  analyze: { agent: "analyst", mcp: "analyze", effort: "gpt54_xhigh" },
-  design: { agent: "architect", mcp: "analyze", effort: "gpt54_xhigh" },
-  review: { agent: "code-reviewer", mcp: "review", effort: "codex53_high" },
+  // 모델 정책 (2026-04-25):
+  // - gpt-5.5 = 메인 (코드 포함 모든 메인 직무, fast tier 가능)
+  // - gpt-5.4-mini = 자잘/부가/가성비 (fast tier 가능)
+  // - gpt-5.3-codex = escalation 가성비 중간 (fast 미지원)
+  // - gpt-5.4 폐기, gpt-5.5 로 격상
+  implement: { agent: "executor", mcp: "implement", effort: "gpt55_high" },
+  debug: { agent: "debugger", mcp: "implement", effort: "gpt55_xhigh" },
+  analyze: { agent: "analyst", mcp: "analyze", effort: "gpt55_xhigh" },
+  design: { agent: "architect", mcp: "analyze", effort: "gpt55_xhigh" },
+  review: { agent: "code-reviewer", mcp: "review", effort: "gpt55_high" },
   document: { agent: "writer", mcp: "docs", effort: "pro" },
-  research: { agent: "scientist", mcp: "analyze", effort: "codex53_high" },
+  research: { agent: "scientist", mcp: "analyze", effort: "gpt55_high" },
   "quick-fix": {
     agent: "build-fixer",
     mcp: "implement",
-    effort: "codex53_low",
+    effort: "gpt55_low",
   },
   explain: { agent: "writer", mcp: "docs", effort: "flash" },
   test: { agent: "test-engineer", mcp: null, effort: null },

package/hub/lib/hosts-compat.mjs

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 const HOSTS_LOCATIONS = [
   ["references", "hosts.json"],
@@ -7,13 +8,70 @@ const HOSTS_LOCATIONS = [
   ["packages", "triflux", "references", "hosts.json"],
 ];
 
+let migrated = false;
+
 function readJsonFile(path) {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 
+export function userStateHostsPath() {
+  if (process.env.TFX_HOSTS_USER_STATE_DISABLE === "1") return null;
+  if (process.env.TFX_HOSTS_USER_STATE) return process.env.TFX_HOSTS_USER_STATE;
+  if (process.platform === "win32") {
+    return join(
+      process.env.APPDATA || join(homedir(), "AppData", "Roaming"),
+      "triflux",
+      "hosts.json",
+    );
+  }
+  return join(homedir(), ".config", "triflux", "hosts.json");
+}
+
 function candidatePaths(repoRoot) {
   const root = repoRoot || process.cwd();
-  return HOSTS_LOCATIONS.map((segments) => join(root, ...segments));
+  const repoRootCandidates = HOSTS_LOCATIONS.map((segments) =>
+    join(root, ...segments),
+  );
+  const userPath = userStateHostsPath();
+  return userPath ? [userPath, ...repoRootCandidates] : repoRootCandidates;
+}
+
+export function migrateLegacyHosts(repoRoot) {
+  const to = userStateHostsPath();
+  let from = null;
+  if (!to) {
+    return {
+      migrated: false,
+      from: null,
+      to: null,
+      reason: "user-state-disabled",
+    };
+  }
+  try {
+    if (existsSync(to)) {
+      return { migrated: false, from: null, to, reason: "already-exists" };
+    }
+
+    const root = repoRoot || process.cwd();
+    from =
+      HOSTS_LOCATIONS.map((segments) => join(root, ...segments)).find((path) =>
+        existsSync(path),
+      ) || null;
+    if (!from) {
+      return { migrated: false, from: null, to, reason: "not-found" };
+    }
+
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(from, to);
+    return { migrated: true, from, to };
+  } catch (error) {
+    return {
+      migrated: false,
+      from,
+      to,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
 function canonicalOs(rawOs) {
@@ -123,6 +181,11 @@ export function normalizeHost(rawHost = {}, name = "") {
 }
 
 export function readHosts(repoRoot) {
+  if (!migrated) {
+    migrateLegacyHosts(repoRoot);
+    migrated = true;
+  }
+
   for (const path of candidatePaths(repoRoot)) {
     if (!existsSync(path)) continue;
     const parsed = readJsonFile(path);

package/hub/team/check-mcp-hub.mjs

@@ -0,0 +1,49 @@
+// hub/team/check-mcp-hub.mjs — health-probe L2 용 hub /health ping 체커.
+// health-probe.mjs 의 checkMcp 로 주입되어 `mcp_initializing` state 판정에 사용.
+// hub /health 가 200 이면 OK (MCP transport 인프라 살아있음), 그 외는 fail.
+
+const DEFAULT_HUB_URL = "http://127.0.0.1:27888";
+const DEFAULT_TIMEOUT_MS = 3000;
+
+function resolveHubHealthUrl(hubUrl) {
+  const base = hubUrl || process.env.TFX_HUB_URL || DEFAULT_HUB_URL;
+  // `/mcp` suffix 제거 (triflux convention — bridge.mjs:54, hub-client.mjs,
+  // lead-control.mjs, session-sync.mjs 전부 TFX_HUB_URL 을 MCP transport URL
+  // 로 쓰고 base URL 이 필요할 때 `/mcp$` 를 strip 한다). 제거하지 않으면
+  // `.../mcp/health` 가 되어 hub 가 404 로 응답 → L2 영구 fail → heartbeat
+  // 이 지속적으로 `mcp_initializing` 로 grace — #173 Codex P2 review.
+  return base.replace(/\/mcp\/?$/, "").replace(/\/+$/, "") + "/health";
+}
+
+/**
+ * Hub /health 기반 L2 checker factory.
+ * @param {object} [opts]
+ * @param {string} [opts.hubUrl] — override. 미지정 시 TFX_HUB_URL env 또는 default.
+ * @param {number} [opts.timeoutMs=3000] — fetch timeout (ms).
+ * @param {typeof fetch} [opts.fetchFn] — fetch 오버라이드 (테스트용).
+ * @returns {() => Promise<boolean>} — true = hub healthy, false = degraded/down/timeout.
+ */
+export function createHubHealthChecker(opts = {}) {
+  const url = resolveHubHealthUrl(opts.hubUrl);
+  const timeoutMs = Number.isFinite(opts.timeoutMs)
+    ? opts.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+  const fetchFn = opts.fetchFn || globalThis.fetch;
+
+  return async function checkMcpHubHealth() {
+    if (typeof fetchFn !== "function") return false;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchFn(url, {
+        method: "GET",
+        signal: controller.signal,
+      });
+      return res.ok === true;
+    } catch {
+      return false;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}

package/hub/team/conductor.mjs

@@ -22,6 +22,7 @@ import { createRegistry } from "../../mesh/mesh-registry.mjs";
 import { broker } from "../account-broker.mjs";
 import { execFile, spawn } from "../lib/spawn-trace.mjs";
 import { killProcess } from "../platform.mjs";
+import { createHubHealthChecker } from "./check-mcp-hub.mjs";
 import { createConductorMeshBridge } from "./conductor-mesh-bridge.mjs";
 import {
   ensureConductorRegistry,
@@ -700,6 +701,16 @@ export function createConductor(opts = {}) {
         // opt-out: TFX_PROBE_WRITE_STATE=0 명시.
         writeStateFile:
           probeOpts.writeStateFile ?? process.env.TFX_PROBE_WRITE_STATE !== "0",
+        // #168 P3: L2 (hub /health) checker wiring. probeOpts 가 명시 주입하면
+        // 그걸 우선. 아니면 TFX_PROBE_L2=0 로 opt-out. 나머지 경우 hub URL 기반
+        // default checker 주입 → deriveState 가 `mcp_initializing` 라벨을 생산 →
+        // heartbeat (read_probe_state) 가 probe-grace 분기로 감.
+        enableL2: probeOpts.enableL2 ?? process.env.TFX_PROBE_L2 !== "0",
+        checkMcp:
+          probeOpts.checkMcp ||
+          (process.env.TFX_PROBE_L2 === "0"
+            ? undefined
+            : createHubHealthChecker({ hubUrl: process.env.TFX_HUB_URL })),
         onProbe: (result) => handleProbeResult(session, result),
       },
     );

package/hub/team/health-probe.mjs

@@ -28,7 +28,10 @@ export const PROBE_DEFAULTS = Object.freeze({
   l1ThresholdMs: 30_000,
   l2ThresholdMs: 30_000,
   l3ThresholdMs: 120_000,
-  enableL2: false,
+  // #168 P3: default off → on. checkMcp 미주입 시에도 probeL2 가 skip 반환하므로
+  // safe. conductor wiring 이 checkMcp 를 주입하면 실제 L2 판정이 활성화된다.
+  // opt-out: TFX_PROBE_L2=0 (conductor 에서 false 주입).
+  enableL2: true,
   writeStateFile: false,
   stateDir: join(tmpdir(), "tfx-probe"),
 });

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

@@ -38,10 +38,17 @@ export const MODES = Object.freeze({
   ESCALATE: "auto-escalate",
 });
 
+// Escalation chain (2026-04-25 정책):
+//   1. gpt-5.4-mini   — 비용 최저, fast tier, 단순 task 대부분 해결
+//   2. gpt-5.3-codex  — 가성비 중간, code specialized (Plus/free 모두 OK, fast 미지원)
+//   3. gpt-5.5         — top reasoning + 코드 강함, fast tier
+//   4. claude opus-4-7 — 최종 수단
+// sonnet-4-6 단계는 제거: gpt-5.5 가 코드/추론/비용 모두 우위 + 5.3-codex 가성비
+// 단계가 더 적합한 중간 격상.
 const DEFAULT_ESCALATION_CHAIN = Object.freeze([
   Object.freeze({ cli: "codex", model: "gpt-5.4-mini" }),
+  Object.freeze({ cli: "codex", model: "gpt-5.3-codex" }),
   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/hub/team/swarm-hypervisor.mjs

@@ -855,7 +855,14 @@ export function createSwarmHypervisor(opts) {
    * @returns {{ ok: boolean, violations: Array }}
    */
   function validateResult(shardName, changedFiles) {
-    const violations = lockManager.validateChanges(shardName, changedFiles);
+    // Pass the shard's own lease so validateChanges can flag out-of-lease
+    // writes to distribution-critical paths (regression of #115/#34 —
+    // recovery patches were carrying `+++ /dev/null` deletions of
+    // .claude-plugin/marketplace.json, undetected by lease-only checks).
+    const ownLease = plan.leaseMap.get(shardName) || [];
+    const violations = lockManager.validateChanges(shardName, changedFiles, {
+      ownLease,
+    });
 
     eventLog.append("validate_result", {
       shard: shardName,

package/hub/team/swarm-locks.mjs

@@ -8,6 +8,26 @@ import { dirname, relative, resolve } from "node:path";
 
 const LOCK_TTL_MS = 10 * 60_000; // 10 minutes default TTL
 
+// Distribution-critical paths. A swarm worker that modifies these without
+// having them explicitly listed in its shard lease is almost certainly a
+// recovery-patch fallout (worker exited before commit, hypervisor saved
+// patch with destructive `+++ /dev/null` deletions). Block by default;
+// override via validateChanges options.sensitiveDeny.
+//
+// Paths use POSIX separators (matches normalizePath output).
+const SENSITIVE_PATH_PREFIXES = [
+  ".claude-plugin/",
+  "bin/",
+  ".github/workflows/",
+];
+const SENSITIVE_PATH_FILES = [
+  ".gitignore",
+  ".npmignore",
+  "package.json",
+  "package-lock.json",
+  "biome.json",
+];
+
 /**
  * Swarm lock manager factory.
  * @param {object} [opts]
@@ -205,20 +225,52 @@ export function createSwarmLocks(opts = {}) {
   /**
    * Validate a set of changed files against the lease map.
    * Returns all violations found.
+   *
+   * Beyond the basic cross-lease check, when `options.ownLease` is supplied
+   * (the caller's known lease set), this also flags out-of-lease writes to
+   * distribution-critical paths — e.g. recovery-patch fallouts where a
+   * worker's recorded diff carries `+++ /dev/null` deletions of files like
+   * `.claude-plugin/marketplace.json` (regression of #115 / #34).
+   *
+   * `options.ownLease` is opt-in to preserve existing callers; when omitted,
+   * legacy behavior (cross-lease check only) is kept.
+   *
    * @param {string} workerId
    * @param {string[]} changedFiles
-   * @returns {Array<{ file: string, holder: string }>}
+   * @param {{ ownLease?: string[], sensitiveDeny?: { prefixes?: string[], files?: string[] } }} [options]
+   * @returns {Array<{ file: string, holder?: string, kind: "other-lease" | "sensitive-out-of-lease" }>}
    */
-  function validateChanges(workerId, changedFiles) {
+  function validateChanges(workerId, changedFiles, options = {}) {
     pruneExpired();
     const violations = [];
+    const ownLeaseSet = Array.isArray(options.ownLease)
+      ? new Set(options.ownLease.map((path) => normalizePath(path)))
+      : null;
+    const sensitivePrefixes =
+      options.sensitiveDeny?.prefixes ?? SENSITIVE_PATH_PREFIXES;
+    const sensitiveFiles = new Set(
+      options.sensitiveDeny?.files ?? SENSITIVE_PATH_FILES,
+    );
 
     for (const file of changedFiles) {
       const path = normalizePath(file);
       const entry = locks.get(path);
 
       if (entry && entry.workerId !== workerId && !isExpired(entry)) {
-        violations.push({ file, holder: entry.workerId });
+        violations.push({ file, holder: entry.workerId, kind: "other-lease" });
+        continue;
+      }
+
+      // Sensitive-path guard only runs when caller supplied ownLease.
+      // We only flag when the worker did NOT explicitly lease the file —
+      // an explicit lease means the shard intentionally owns it.
+      if (ownLeaseSet && !ownLeaseSet.has(path)) {
+        const isSensitive =
+          sensitiveFiles.has(path) ||
+          sensitivePrefixes.some((prefix) => path.startsWith(prefix));
+        if (isSensitive) {
+          violations.push({ file, kind: "sensitive-out-of-lease" });
+        }
       }
     }
 

package/hub/team/tui-remote-adapter.mjs

@@ -5,16 +5,12 @@
 // 완료/실패 시 notify.mjs 자동 호출.
 
 import { EventEmitter } from "node:events";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 
+import { readHosts } from "../lib/hosts-compat.mjs";
 import { STATES } from "./conductor.mjs";
 
 // ── 상수 ─────────────────────────────────────────────────────────────────────
 
-const HOSTS_JSON_REL = "../../references/hosts.json";
-
 const CONDUCTOR_STATE_TO_TUI_STATUS = Object.freeze({
   [STATES.INIT]: "pending",
   [STATES.STARTING]: "pending",
@@ -31,21 +27,6 @@ const SESSION_PREFIX = "tfx-spawn-";
 
 // ── 유틸 ─────────────────────────────────────────────────────────────────────
 
-function loadHostsJson(hostsJsonPath) {
-  try {
-    const raw = readFileSync(hostsJsonPath, "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return { hosts: {} };
-  }
-}
-
-function resolveHostsJsonPath(overridePath) {
-  if (overridePath) return overridePath;
-  const thisDir = fileURLToPath(new URL(".", import.meta.url));
-  return join(thisDir, HOSTS_JSON_REL);
-}
-
 function resolveSshUser(hostsData, host) {
   if (!host || !hostsData?.hosts) return null;
   return hostsData.hosts[host]?.ssh_user || null;
@@ -144,7 +125,7 @@ function buildWatcherOnlyWorkerData(watcherRecord, hostsData) {
  * @param {object} opts.conductor — createConductor() 인스턴스
  * @param {object} [opts.watcher] — createRemoteWatcher() 인스턴스 (nullable)
  * @param {object} [opts.notifier] — createNotifier() 인스턴스 (nullable)
- * @param {string} [opts.hostsJsonPath] — hosts.json 경로 override
+ * @param {string} [opts.repoRoot] — hosts fallback 탐색용 repo root override
  * @param {number} [opts.pollMs=10000] — conductor snapshot 폴링 간격
  * @param {object} [opts.deps] — 테스트용 의존성 주입
  * @returns {{ start, stop, getWorkers, on, off }}
@@ -160,14 +141,13 @@ export function createRemoteAdapter(opts = {}) {
 
   if (!conductor) throw new Error("conductor is required");
 
-  const hostsJsonPath = resolveHostsJsonPath(opts.hostsJsonPath);
-  const loadHosts = deps.loadHostsJson || loadHostsJson;
+  const loadHosts = deps.readHosts || readHosts;
   const setIntervalFn = deps.setInterval || setInterval;
   const clearIntervalFn = deps.clearInterval || clearInterval;
   const _nowFn = deps.now || Date.now;
 
   const emitter = new EventEmitter();
-  let hostsData = loadHosts(hostsJsonPath);
+  let hostsData = loadHosts(opts.repoRoot);
   let workers = new Map();
   let pollHandle = null;
   let running = false;
@@ -343,7 +323,7 @@ export function createRemoteAdapter(opts = {}) {
     running = true;
 
     // hosts.json 리로드
-    hostsData = loadHosts(hostsJsonPath);
+    hostsData = loadHosts(opts.repoRoot);
 
     // conductor stateChange 구독
     conductor.on("stateChange", handleStateChange);

package/hub/workers/codex-mcp.mjs

@@ -533,13 +533,28 @@ export async function runCodexMcpCli(argv = process.argv.slice(2)) {
 
   try {
     const result = await worker.execute(options.prompt, options);
-    if (result.output) {
+    const hasOutput =
+      typeof result.output === "string" && result.output.trim().length > 0;
+    if (hasOutput) {
       process.stdout.write(result.output);
       if (!result.output.endsWith("\n")) {
         process.stdout.write("\n");
       }
     }
-    process.exitCode = result.exitCode;
+    // Silent-success regression guard (codex 0.124.0+):
+    // codex MCP can return exitCode=0 with empty/whitespace `output` when the
+    // result-extraction path fails to read the assistant content from the MCP
+    // response. Without this guard, tfx-route.sh sees STDOUT_LOG=0 bytes and
+    // treats it as success — caller gets nothing back.
+    // Promote to a transport failure so the wrapper falls back to `codex exec`.
+    if (!hasOutput && result.exitCode === 0) {
+      console.error(
+        "[codex-mcp] WARNING: empty output with exit 0 — treating as transport failure (codex 0.124.0 silent-flush regression). Wrapper will fall back to exec path.",
+      );
+      process.exitCode = CODEX_MCP_TRANSPORT_EXIT_CODE;
+    } else {
+      process.exitCode = result.exitCode;
+    }
   } catch (error) {
     const lines = [error instanceof Error ? error.message : String(error)];
     if (error instanceof CodexMcpTransportError && error.stderr) {

package/package.json

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

package/scripts/__tests__/mcp-guard-engine.test.mjs

@@ -101,14 +101,16 @@ describe("mcp guard engine", () => {
     );
   });
 
-  it("replaces stdio MCP entries with tfx-hub and writes a backup", () => {
+  it("replaces stdio MCP entries with tfx-hub and writes a backup (TFX_HUB_PORT env overrides)", () => {
     const homeDir = createHomeDir();
     withHome(homeDir);
+    process.env.TFX_HUB_PORT = "30123";
 
+    // hub.pid port 는 무시되어야 한다 (PR #158: pid = host hint only).
     const pidPath = join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid");
     writeFileSync(
       pidPath,
-      JSON.stringify({ host: "127.0.0.1", port: 30123 }),
+      JSON.stringify({ host: "127.0.0.1", port: 40404 }),
       "utf8",
     );
 
@@ -141,9 +143,18 @@ describe("mcp guard engine", () => {
     assert.equal(Object.hasOwn(updated.mcpServers, "unsafe-stdio"), false);
   });
 
-  it("uses hub.pid port before registry fallback when resolving Hub URL", () => {
+  it("uses TFX_HUB_PORT env as single source when resolving Hub URL", () => {
     const homeDir = createHomeDir();
     withHome(homeDir);
+    process.env.TFX_HUB_PORT = "29991";
+
+    assert.equal(resolveHubUrl(), "http://127.0.0.1:29991/mcp");
+  });
+
+  it("ignores hub.pid port (pid is host hint only, PR #158 policy)", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+    delete process.env.TFX_HUB_PORT;
 
     writeFileSync(
       join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid"),
@@ -151,6 +162,8 @@ describe("mcp guard engine", () => {
       "utf8",
     );
 
-    assert.equal(resolveHubUrl(), "http://127.0.0.1:29991/mcp");
+    // env 없음 + hub.pid port 존재 → registry/default 27888 fallback.
+    // pid port cascade 가 제거되어 29991 이 쓰이면 안 됨.
+    assert.equal(resolveHubUrl(), "http://127.0.0.1:27888/mcp");
   });
 });

package/scripts/headless-guard.mjs

@@ -277,11 +277,15 @@ async function main() {
           cmdSanitized,
         );
       } else {
+        // $()/${} 와 eval 직후 첫 토큰만 검사한다.
+        // .* 매칭은 `result=$(grep "codex exec" file)` 같은 grep 인자 패턴까지
+        // 차단하는 오탐을 일으킨다. 진짜 위협은 `$(codex exec ...)` 처럼
+        // command substitution / eval 의 첫 명령이 codex/gemini 인 경우뿐이다.
         hasDirectCli =
-          /\beval\b.*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(
+          /\beval\s+(?:["']\s*)?(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(
             cmdSanitized,
           ) ||
-          /\$[({].*\b(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(
+          /\$[({]\s*(codex\s+exec|gemini\s+(-p|--prompt))\b/i.test(
             cmdSanitized,
           );
       }

package/scripts/lib/mcp-guard-engine.mjs

@@ -851,14 +851,13 @@ export function resolveHubUrl() {
         : DEFAULT_HUB_PATH,
   };
 
+  // PR #158 정책: port = TFX_HUB_PORT env (없으면 registry/default 27888) single source.
+  // hub.pid 는 loopback host 힌트 전용. 과거 pid port cascade 는 오염된 port 영속화의
+  // 원인이었고 hub-ensure.resolveHubTarget 에서 이미 제거됨. 여기도 일관 적용.
   const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
   if (existsSync(hubPidPath)) {
     try {
       const info = readJsonFile(hubPidPath);
-      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/setup.mjs

@@ -117,6 +117,11 @@ const REQUIRED_CODEX_PROFILES = [
 ];
 
 const HUD_SYNC_EXCLUDES = new Set(["omc-hud.mjs", "omc-hud.mjs.bak"]);
+const SETUP_USER_STATE_FILES = new Set(["hosts.json"]);
+
+function isSetupUserStateFile(fileName) {
+  return SETUP_USER_STATE_FILES.has(fileName);
+}
 
 /**
  * scripts/lib/*.mjs 자동 스캔.
@@ -409,6 +414,7 @@ function syncAliasedSkillDir(srcDir, dstDir, { alias, source }) {
   for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
     const srcPath = join(srcDir, entry.name);
     const dstPath = join(dstDir, entry.name);
+    if (isSetupUserStateFile(entry.name)) continue;
 
     if (entry.isDirectory()) {
       count += syncAliasedSkillDir(srcPath, dstPath, { alias, source });
@@ -762,6 +768,64 @@ function buildWindowsHubAutostartCommand({
   ].join(" ");
 }
 
+// #161 P2: schtasks /Query 실패 시 stderr 를 해석해 미등록/권한거부/기타 실패를 구분한다.
+// 기존 구현은 stdio=ignore + catch 후 항상 registered:false 였기 때문에
+// Access Denied 같은 해결 가능한 문제가 "미등록" 으로 묻혔다.
+const WINDOWS_SCHTASKS_NOT_FOUND_PATTERNS = [
+  "cannot find the file",
+  "does not exist",
+  "지정된 파일",
+  "찾을 수 없",
+];
+const WINDOWS_SCHTASKS_ACCESS_DENIED_PATTERNS = [
+  "access is denied",
+  "access denied",
+  "permission",
+  "액세스가 거부",
+  "권한",
+];
+
+// #161 P3: schtasks /TR 인자는 실질적으로 262자 미만으로 제한된다.
+// 초과 시 Create 자체는 성공해도 task 실행에서 인자 잘림/실행 실패 재발.
+// 따라서 Create 전에 사전 검증해 조기 실패를 보장한다.
+const SCHTASKS_TR_MAX_LENGTH = 261;
+
+// #161 P3: /TR 길이 검증 공용 함수.
+// schtasks 는 Windows 내부에서 wide-char 문자 수로 제한하므로 UTF-8 byte 가 아닌
+// JavaScript string .length (UTF-16 code units) 기준으로 비교한다.
+// Codex Round 1 P1 반영: UTF-8 byte 검증은 한글 경로에서 정상 명령을 오차단했다
+// (예: ~218자 한글 경로 = 578 bytes → false positive throw).
+// Codex Round 3 P2 반영: 테스트가 실행 경로와 동일한 이 함수를 exercise 하므로
+// 내부 구현이 회귀해 byte 기반으로 돌아가면 테스트가 즉시 포착한다.
+function validateSchtasksTrLength(command) {
+  const commandChars = command.length;
+  if (commandChars > SCHTASKS_TR_MAX_LENGTH) {
+    throw new Error(
+      `schtasks /TR 인자가 ${SCHTASKS_TR_MAX_LENGTH} 문자를 초과합니다 ` +
+        `(${commandChars} chars): ${command}`,
+    );
+  }
+}
+
+function classifySchtasksStderr(stderr) {
+  const lower = String(stderr || "").toLowerCase();
+  if (
+    WINDOWS_SCHTASKS_NOT_FOUND_PATTERNS.some((p) =>
+      lower.includes(p.toLowerCase()),
+    )
+  ) {
+    return "not_registered";
+  }
+  if (
+    WINDOWS_SCHTASKS_ACCESS_DENIED_PATTERNS.some((p) =>
+      lower.includes(p.toLowerCase()),
+    )
+  ) {
+    return "access_denied";
+  }
+  return "unknown";
+}
+
 function getWindowsHubAutostartStatus({
   taskName = WINDOWS_HUB_AUTOSTART_TASK,
 } = {}) {
@@ -770,12 +834,20 @@ function getWindowsHubAutostartStatus({
   }
   try {
     execFileSync("schtasks.exe", ["/Query", "/TN", taskName], {
-      stdio: "ignore",
+      stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
     });
     return { supported: true, registered: true, taskName };
-  } catch {
-    return { supported: true, registered: false, taskName };
+  } catch (error) {
+    const stderr = String(error?.stderr || "").trim();
+    const reason = classifySchtasksStderr(stderr);
+    return {
+      supported: true,
+      registered: false,
+      taskName,
+      reason,
+      stderr: stderr.slice(0, 200),
+    };
   }
 }
 
@@ -796,6 +868,10 @@ function ensureWindowsHubAutostart({
   }
 
   const command = buildWindowsHubAutostartCommand({ nodePath, pluginRoot });
+
+  // #161 P3: /TR 262자 제한 사전 검증을 공용 함수로 위임해 테스트/실행 로직 일관성 보장.
+  validateSchtasksTrLength(command);
+
   const args = [
     "/Create",
     "/TN",
@@ -809,10 +885,23 @@ function ensureWindowsHubAutostart({
   ];
   if (force) args.push("/F");
 
-  execFileSync("schtasks.exe", args, {
-    stdio: ["ignore", "pipe", "pipe"],
-    windowsHide: true,
-  });
+  try {
+    execFileSync("schtasks.exe", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch (error) {
+    // #161 P3: stderr 를 error.message 에 노출해 호출자가 원인을 볼 수 있게 한다.
+    const stderr = String(error?.stderr || "").trim();
+    if (stderr) {
+      const wrapped = new Error(
+        `schtasks /Create 실패: ${stderr.slice(0, 200)}`,
+      );
+      wrapped.cause = error;
+      throw wrapped;
+    }
+    throw error;
+  }
 
   return {
     supported: true,
@@ -1058,6 +1147,7 @@ export {
   BREADCRUMB_PATH,
   buildWindowsHubAutostartCommand,
   CLAUDE_DIR,
+  classifySchtasksStderr,
   cleanupStaleSkills,
   DEPRECATED_SKILLS,
   detectDevMode,
@@ -1070,17 +1160,21 @@ export {
   getVersion,
   getWindowsHubAutostartStatus,
   hasProfileSection,
+  isSetupUserStateFile,
   LEGACY_CODEX_MODELS,
   PLUGIN_ROOT,
   REQUIRED_CODEX_PROFILES,
   REQUIRED_TOP_LEVEL_SETTINGS,
   readMarker,
   replaceProfileSection,
+  SCHTASKS_TR_MAX_LENGTH,
   SETUP_MARKER_PATH,
+  SETUP_USER_STATE_FILES,
   SKILL_ALIASES,
   SYNC_MAP,
   scanHudFiles,
   syncAliasedSkillDir,
+  validateSchtasksTrLength,
   WINDOWS_HUB_AUTOSTART_TASK,
   writeMarker,
 };
@@ -1291,7 +1385,8 @@ export async function runDeferred(stdinData) {
   }
 
   // ── 스킬 동기화 ──
-  // SKILL.md + 하위 디렉토리(references/ 등)를 재귀적으로 동기화
+  // SKILL.md + 하위 디렉토리(references/ 등)를 재귀적으로 동기화.
+  // hosts.json 같은 user-state 파일은 설치/동기화 대상이 아니다.
 
   const skillsSrc = join(PLUGIN_ROOT, "skills");
   const skillsDst = join(CLAUDE_DIR, "skills");
@@ -1303,6 +1398,7 @@ export async function runDeferred(stdinData) {
     for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
       const srcPath = join(srcDir, entry.name);
       const dstPath = join(dstDir, entry.name);
+      if (isSetupUserStateFile(entry.name)) continue;
 
       if (entry.isDirectory()) {
         count += syncSkillDir(srcPath, dstPath);

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

@@ -82,30 +82,89 @@ async function fileExists(filePath) {
 }
 
 async function writeTextAtomic(filePath, payload) {
+  // #164 MEDIUM 1: rename fallback 비원자성 개선.
+  // 기존: rename 실패 시 원본을 먼저 rm → rename(tmp, dest) 이므로 2차 실패/프로세스 중단 시 원본 유실.
+  // 개선: 원본을 backup 경로로 먼저 옮기고 (atomic rename), tmp → dest 성공 후에만 backup 삭제.
+  //       tmp → dest 실패 시 backup 을 다시 dest 로 복원해 원자성 보장.
+  //       backup 복원 자체가 실패하면 backup 을 **절대 삭제하지 않는다** (수동 복구용 보존).
   const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  const backupPath = `${filePath}.bak-${process.pid}-${Date.now()}`;
+  let hasBackup = false;
 
   try {
     await writeFile(tmpPath, payload, "utf8");
 
+    // 1) 원본이 있으면 backup 으로 rename (원본 유실 위험 제거)
+    try {
+      await rename(filePath, backupPath);
+      hasBackup = true;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+
+    // 2) tmp → dest
     try {
       await rename(tmpPath, filePath);
     } catch (error) {
+      // Windows 에서 dest 에 stale lock 이 남아있으면 EEXIST/EPERM/EACCES 가 여전히 발생 가능.
+      // 이 경우 dest 를 제거한 뒤 재시도. backup 은 아직 살아있으므로 복원 가능.
       if (
-        error?.code !== "EEXIST" &&
-        error?.code !== "EPERM" &&
-        error?.code !== "EACCES"
+        error?.code === "EEXIST" ||
+        error?.code === "EPERM" ||
+        error?.code === "EACCES"
       ) {
+        await rm(filePath, { force: true }).catch(() => {});
+        await rename(tmpPath, filePath);
+      } else {
         throw error;
       }
+    }
 
-      await rm(filePath, { force: true });
-      await rename(tmpPath, filePath);
+    // 3) 성공 — backup 정리
+    if (hasBackup) {
+      await rm(backupPath, { force: true }).catch(() => {});
+      hasBackup = false;
     }
+  } catch (error) {
+    // 실패 — backup 복원 시도. 복원 성공 시에만 hasBackup=false 로 내려 cleanup 경로 진입 허용.
+    // 복원 실패 시에는 hasBackup=true 유지 → finally 에서도 backup 을 **삭제하지 않아** 수동 복구 가능.
+    if (hasBackup) {
+      try {
+        await rename(backupPath, filePath);
+        hasBackup = false;
+      } catch (rollbackError) {
+        // eslint-disable-next-line no-console — 사용자가 backup 존재를 인지해야 복구 가능
+        console.warn(
+          `[sync-hub-mcp-settings] atomic write rollback failed for ${filePath}: ${rollbackError?.message || rollbackError}. ` +
+            `Original content preserved at: ${backupPath}`,
+        );
+      }
+    }
+    throw error;
   } finally {
+    // tmp 는 항상 정리. backup 은 성공 경로/복원 경로에서만 명시적으로 rm 한다
+    // (rollback 실패 시 hasBackup=true 상태로 남음 → 이 블록에서 절대 삭제하지 않음)
     await rm(tmpPath, { force: true }).catch(() => {});
   }
 }
 
+// #164 MEDIUM 2: TOML write 후 유효성 검증.
+// write 직전 nextRaw 가 최소 구조 (섹션 헤더 + url= 키) 를 만족하는지 확인해
+// 깨진 TOML 을 filesystem 에 반영하지 않는다.
+function validateCodexTomlPayload(raw, sectionName) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return { ok: false, reason: "empty payload" };
+  }
+  const section = findMcpServerSection(raw, sectionName);
+  if (!section) {
+    return { ok: false, reason: "missing section header" };
+  }
+  if (!/^\s*url\s*=\s*.+$/m.test(section.body)) {
+    return { ok: false, reason: "missing url key" };
+  }
+  return { ok: true };
+}
+
 async function writeJsonAtomic(filePath, value) {
   const payload = `${JSON.stringify(value, null, 2)}\n`;
   await writeTextAtomic(filePath, payload);
@@ -261,6 +320,16 @@ async function syncCodexConfigFile({ filePath, hubUrl, dryRun, logger }) {
       );
 
       if (!dryRun) {
+        const validation = validateCodexTomlPayload(nextRaw, TFX_HUB_SECTION);
+        if (!validation.ok) {
+          const reason = `invalid toml payload: ${validation.reason}`;
+          log(
+            logger,
+            "error",
+            `[codex-mcp-sync] error: ${filePath} (${reason})`,
+          );
+          return { kind: "error", path: filePath, reason };
+        }
         try {
           await writeTextAtomic(filePath, nextRaw);
         } catch (error) {
@@ -311,6 +380,12 @@ async function syncCodexConfigFile({ filePath, hubUrl, dryRun, logger }) {
     );
 
     if (!dryRun) {
+      const validation = validateCodexTomlPayload(nextRaw, TFX_HUB_SECTION);
+      if (!validation.ok) {
+        const reason = `invalid toml payload: ${validation.reason}`;
+        log(logger, "error", `[codex-mcp-sync] error: ${filePath} (${reason})`);
+        return { kind: "error", path: filePath, reason };
+      }
       try {
         await writeTextAtomic(filePath, nextRaw);
       } catch (error) {

package/scripts/tfx-route.sh

@@ -911,38 +911,45 @@ route_agent() {
   case "$agent" in
     # ─── 구현 레인 ───
     executor|codex)
-      CLI_ARGS="exec --profile codex53_high ${codex_base}"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1080; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1080; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     build-fixer)
-      CLI_ARGS="exec --profile codex53_low ${codex_base}"
-      CLI_EFFORT="codex53_low"; DEFAULT_TIMEOUT=540; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+      # 빌드 수정 — npm/biome/test-lock 등 도메인 지식 필요. base capability 우위로 gpt55_low (fast tier).
+      CLI_ARGS="exec --profile gpt55_low ${codex_base}"
+      CLI_EFFORT="gpt55_low"; DEFAULT_TIMEOUT=540; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+    cleanup|deslop)
+      # 슬롭/정리 — 패턴 매칭 위주. 가성비 mini (gpt-5.4-mini, fast tier).
+      CLI_ARGS="exec --profile mini54_med ${codex_base}"
+      CLI_EFFORT="mini54_med"; DEFAULT_TIMEOUT=540; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     debugger)
-      CLI_ARGS="exec --profile codex53_high ${codex_base}"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      # 디버깅 — 깊은 코드 추적 필요, gpt-5.5 xhigh
+      CLI_ARGS="exec --profile gpt55_xhigh ${codex_base}"
+      CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
-    # ─── 설계/분석 레인 (5.4: 1M 컨텍스트, 에이전틱) ───
+    # ─── 설계/분석 레인 (gpt-5.5 xhigh — 5.4 폐기, 5.5 격상) ───
     deep-executor|architect|critic)
-      CLI_ARGS="exec --profile gpt54_xhigh ${codex_base}"
-      CLI_EFFORT="gpt54_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="bg"; OPUS_OVERSIGHT="true" ;;
+      CLI_ARGS="exec --profile gpt55_xhigh ${codex_base}"
+      CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="bg"; OPUS_OVERSIGHT="true" ;;
     planner|analyst)
-      CLI_ARGS="exec --profile gpt54_xhigh ${codex_base}"
-      CLI_EFFORT="gpt54_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="fg"; OPUS_OVERSIGHT="true" ;;
+      CLI_ARGS="exec --profile gpt55_xhigh ${codex_base}"
+      CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="fg"; OPUS_OVERSIGHT="true" ;;
 
-    # ─── 리뷰 레인 (5.3-codex: SWE-Bench 72%) ───
+    # ─── 리뷰 레인 (gpt-5.5 — 코드 리뷰도 5.5가 강함) ───
     code-reviewer|quality-reviewer)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1800; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base} review"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1800; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
     security-reviewer)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1800; RUN_MODE="bg"; OPUS_OVERSIGHT="true" ;;
+      # 보안 = 깊은 사고 → xhigh
+      CLI_ARGS="exec --profile gpt55_xhigh ${codex_base} review"
+      CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=1800; RUN_MODE="bg"; OPUS_OVERSIGHT="true" ;;
 
     # ─── 리서치 레인 ───
     scientist|document-specialist)
-      CLI_ARGS="exec --profile codex53_high ${codex_base}"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1440; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1440; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
     scientist-deep)
-      CLI_ARGS="exec --profile gpt54_high ${codex_base}"
-      CLI_EFFORT="gpt54_high"; DEFAULT_TIMEOUT=3600; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_xhigh ${codex_base}"
+      CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
     # ─── UI/문서 레인 ───
     designer|gemini)
@@ -958,14 +965,14 @@ route_agent() {
 
     # ─── 검증/테스트 ───
     verifier)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base} review"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
     test-engineer)
-      CLI_ARGS="exec --profile codex53_high ${codex_base}"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
     qa-tester)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+      CLI_ARGS="exec --profile gpt55_high ${codex_base} review"
+      CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1200; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
     # ─── 경량 ───
     spark)
@@ -975,8 +982,8 @@ route_agent() {
     *)
       case "$CLI_TYPE" in
         codex)
-          CLI_ARGS="exec --profile codex53_high ${codex_base}"
-          CLI_EFFORT="codex53_high"; DEFAULT_TIMEOUT=1080; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
+          CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+          CLI_EFFORT="gpt55_high"; DEFAULT_TIMEOUT=1080; RUN_MODE="fg"; OPUS_OVERSIGHT="false" ;;
         gemini)
           CLI_ARGS="-m $(resolve_gemini_profile pro31) -y --prompt"
           CLI_EFFORT="pro31"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
@@ -1143,9 +1150,9 @@ apply_plan_guard() {
   if [[ "$CLI_EFFORT" == spark53_* ]]; then
     local codex_base
     codex_base="$(build_codex_base)"
-    CLI_ARGS="exec --profile codex53_high ${codex_base}"
-    CLI_EFFORT="codex53_high"
-    echo "[tfx-route] TFX_CODEX_PLAN=$TFX_CODEX_PLAN: spark → codex53_high로 다운그레이드 (Pro 전용)" >&2
+    CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+    CLI_EFFORT="gpt55_high"
+    echo "[tfx-route] TFX_CODEX_PLAN=$TFX_CODEX_PLAN: spark → gpt55_high로 다운그레이드 (Pro 전용)" >&2
   fi
 }
 
@@ -1168,29 +1175,29 @@ apply_no_claude_native_mode() {
 
   case "$AGENT_TYPE" in
     explore)
-      CLI_ARGS="exec --profile codex53_low ${codex_base}"
-      CLI_EFFORT="codex53_low"
+      CLI_ARGS="exec --profile gpt55_low ${codex_base}"
+      CLI_EFFORT="gpt55_low"
       DEFAULT_TIMEOUT=600
       RUN_MODE="fg"
       OPUS_OVERSIGHT="false"
       ;;
     verifier)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"
+      CLI_ARGS="exec --profile gpt55_high ${codex_base} review"
+      CLI_EFFORT="gpt55_high"
       DEFAULT_TIMEOUT=1200
       RUN_MODE="fg"
       OPUS_OVERSIGHT="false"
       ;;
     test-engineer)
-      CLI_ARGS="exec --profile codex53_high ${codex_base}"
-      CLI_EFFORT="codex53_high"
+      CLI_ARGS="exec --profile gpt55_high ${codex_base}"
+      CLI_EFFORT="gpt55_high"
       DEFAULT_TIMEOUT=1200
       RUN_MODE="bg"
       OPUS_OVERSIGHT="false"
       ;;
     qa-tester)
-      CLI_ARGS="exec --profile codex53_high ${codex_base} review"
-      CLI_EFFORT="codex53_high"
+      CLI_ARGS="exec --profile gpt55_high ${codex_base} review"
+      CLI_EFFORT="gpt55_high"
       DEFAULT_TIMEOUT=1200
       RUN_MODE="bg"
       OPUS_OVERSIGHT="false"

package/skills/tfx-remote/SKILL.md

@@ -41,10 +41,17 @@ argument-hint: "[setup|spawn|list|attach|send|resume|kill|probe] ..."
 - `setup --probe-all`
 - `setup --diagnose`
 
+`hosts.json` 은 user-state 경로 한 곳만 읽고 쓴다.
+- macOS/Linux: `~/.config/triflux/hosts.json`
+- Windows: `%APPDATA%\triflux\hosts.json`
+
+기존 `references/hosts.json` 및 source/packages/global 3곳 fan-out 단계는 더 이상 사용하지 않는다.
+첫 실행 시 legacy `references/hosts.json` 이 발견되면 lazy auto-migration으로 user-state 경로에 자동 이동된다.
+
 ### `tfx-remote spawn`
 
 기존 `tfx-remote-spawn` 플로우를 사용하되 아래 preflight를 먼저 수행한다.
-1. `hosts.json` 존재 확인
+1. user-state `hosts.json` 존재 확인
 2. 호스트명/alias 해석
 3. probe TTL 확인
 4. SSH 실패 시 `setup diagnose` 또는 `setup edit` 복귀 경로 제시
@@ -70,6 +77,7 @@ preflight 실패 시 중단만 하지 말고 아래 중 하나로 복귀시킨
 ## hosts.json contract
 
 신규 코드는 가능하면 `hub/lib/hosts-compat.mjs`를 기준으로 해석한다.
+저장 위치는 macOS/Linux `~/.config/triflux/hosts.json`, Windows `%APPDATA%\triflux\hosts.json` 이다.
 - v1 legacy 필드 유지: `os`, `ssh_user`, `tailscale.ip`, `tailscale.dns`, `capabilities`
 - v2 additive 필드 허용: `ssh.user`, `capabilities_v2`, `last_probe`
 

package/skills/tfx-remote-setup/SKILL.md.tmpl

@@ -341,6 +341,17 @@ options:
 
 저장 후 결과 보고.
 
+**2-7-b. 소스 트리 동기화 (fan-out)**
+
+`references/hosts.json` 은 skill reference 폴더에 위치하므로, 글로벌 (`~/.claude/skills/...`) 만 수정하면 triflux 소스 트리와 drift 가 발생한다. 수정 직후 아래 두 경로도 동일 내용으로 덮어쓴다 — 파일이 존재할 때만, 각 위치별로 `hosts.json.bak.<timestamp>` 백업 포함:
+
+- `<triflux repo>/skills/tfx-remote-spawn/references/hosts.json`
+- `<triflux repo>/packages/triflux/skills/tfx-remote-spawn/references/hosts.json`
+
+triflux 소스 트리가 감지되지 않으면 이 단계를 건너뛴다. Edit 모드에서도 동일한 fan-out 을 적용한다.
+
+> 이것은 임시 패치다. 근본 해결은 hosts.json 위치를 user-state 경로로 옮기는 것 (issue #178) 또는 `tfx setup` 의 user-state 파일 skip 로직 (issue #179).
+
 **2-8. MCP 고아 프로세스 정리 훅 배포 (Windows 원격 호스트)**
 
 원격 호스트가 Windows인 경우, MCP 고아 프로세스 정리 훅을 자동 배포한다.
@@ -436,6 +447,8 @@ options:
 
 선택된 항목에 대해 순차 AskUserQuestion으로 새 값 입력받아 Edit 도구로 hosts.json 수정.
 
+수정 후 **2-7-b 소스 트리 동기화 (fan-out)** 단계를 동일하게 적용한다.
+
 #### 전체 프로브 (Probe All)
 
 등록된 모든 호스트를 순회하며 프로브:

package/skills/tfx-remote-spawn/SKILL.md

@@ -12,6 +12,15 @@ argument-hint: "[spawn|list|attach|send|resume|kill|probe] ..."
 
 이 스킬은 Phase 4b thin alias다. 새 표면은 `tfx-remote` 명령군이다.
 
+## hosts.json location
+
+호스트 별칭/설정은 canonical `tfx-remote` 와 동일하게 user-state 경로 한 곳만 사용한다.
+- macOS/Linux: `~/.config/triflux/hosts.json`
+- Windows: `%APPDATA%\triflux\hosts.json`
+
+기존 `references/hosts.json` 및 source/packages/global fan-out는 더 이상 사용하지 않는다.
+첫 실행 시 legacy `references/hosts.json` 이 발견되면 lazy auto-migration으로 user-state 경로에 자동 이동된다.
+
 ## Deprecation logging (alias 호출 즉시 실행 필수)
 
 canonical 위임 **이전** 에 아래 bash 블록을 한 번 실행한다. Phase 5 (v11) 물리 삭제 게이트는 `.omc/state/alias-usage.log` 의 7일 zero-usage 검증에 의존.

package/skills/tfx-remote-spawn/references/hosts.json

@@ -1,16 +1,41 @@
 {
   "hosts": {
-    "ultra4": {
-      "description": "Windows 데스크탑 (SSAFY)",
-      "aliases": ["울트라", "데스크탑"],
-      "default_dir": "~/Desktop/Projects"
-    },
     "m2": {
-      "description": "MacBook Pro",
+      "description": "MacBook Air (tellang M2)",
       "aliases": ["맥북", "맥"],
-      "default_dir": "~/projects"
+      "default_dir": "~/projects",
+      "os": "darwin",
+      "ssh_user": "tellang",
+      "tailscale": {
+        "ip": "100.104.61.126",
+        "dns": "m2.sole-hexatonic.ts.net",
+        "ssh_mode": "ssh-over-vpn"
+      },
+      "capabilities": {
+        "ssh_active": true,
+        "claude": true,
+        "node": "v25.9.0"
+      },
+      "last_probe": "2026-04-24T19:04:48Z"
+    },
+    "fold7": {
+      "description": "Samsung Z Fold 7 (Termux)",
+      "aliases": ["폴드", "폰", "fold"],
+      "default_dir": "~",
+      "os": "android",
+      "ssh_user": "",
+      "tailscale": {
+        "ip": "100.107.139.115",
+        "dns": "fold7.sole-hexatonic.ts.net",
+        "ssh_mode": "ssh-over-vpn"
+      },
+      "capabilities": {
+        "ssh_active": false,
+        "note": "Termux sshd 미실행 — Fold7에서 'pkg install openssh && sshd -p 8022' 후 probe 재실행"
+      },
+      "last_probe": "2026-04-24T19:04:48Z"
     }
   },
-  "default_host": "ultra4",
+  "default_host": "m2",
   "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
 }

package/skills/tfx-remote-spawn/references/hosts.json.bak.20260425_040814

@@ -0,0 +1,16 @@
+{
+  "hosts": {
+    "ultra4": {
+      "description": "Windows 데스크탑 (SSAFY)",
+      "aliases": ["울트라", "데스크탑"],
+      "default_dir": "~/Desktop/Projects"
+    },
+    "m2": {
+      "description": "MacBook Pro",
+      "aliases": ["맥북", "맥"],
+      "default_dir": "~/projects"
+    }
+  },
+  "default_host": "ultra4",
+  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
+}

package/skills/tfx-setup/SKILL.md

@@ -44,7 +44,7 @@ options:
 Bash("triflux setup")
 ```
 
-스크립트/HUD/스킬을 `~/.claude/`에 배포. 결과 표시.
+스크립트/HUD/스킬을 `~/.claude/`에 배포. 결과 표시. `tfx setup` 은 user-state 파일(예: macOS/Linux `~/.config/triflux/hosts.json`, Windows `%APPDATA%\triflux\hosts.json`)을 덮어쓰지 않는다.
 
 #### 단계 1.5: 훅 등록 확인
 
@@ -254,7 +254,11 @@ options:
 
 #### 단계 3.8: 원격 기기 프로빙 (Swarm Multi-Machine)
 
-`references/hosts.json` 또는 `~/.triflux/hosts.json` 존재 여부 확인.
+user-state `hosts.json` 존재 여부 확인.
+- macOS/Linux: `~/.config/triflux/hosts.json`
+- Windows: `%APPDATA%\triflux\hosts.json`
+
+기존 source-tree `references/hosts.json` 은 더 이상 사용하지 않는다. legacy 파일이 남아 있으면 첫 원격 실행 시 lazy auto-migration으로 user-state 경로에 자동 이동된다.
 
 - 파일 없음 → AskUserQuestion:
   ```