triflux 10.18.1 → 10.19.0

package/hooks/hook-registry.json

@@ -206,10 +206,11 @@
       {
         "id": "ext-session-vault-start",
         "source": "session-vault",
+        "requires": "$HOME/Desktop/Projects/tools/session-vault",
         "matcher": "*",
         "command": "bash \"${HOME}/Desktop/Projects/tools/session-vault/scripts/start_hook.sh\"",
         "priority": 100,
-        "enabled": true,
+        "enabled": false,
         "timeout": 10,
         "blocking": false,
         "description": "세션 볼트 로깅 시작"
@@ -230,10 +231,11 @@
       {
         "id": "ext-session-vault-export",
         "source": "session-vault",
+        "requires": "$HOME/Desktop/Projects/tools/session-vault",
         "matcher": "*",
         "command": "bash \"${HOME}/Desktop/Projects/tools/session-vault/scripts/export_hook.sh\"",
         "priority": 100,
-        "enabled": true,
+        "enabled": false,
         "timeout": 30,
         "blocking": false,
         "description": "세션 트랜스크립트 내보내기"

package/hub/account-broker.mjs

@@ -66,9 +66,17 @@ const TIER_PRIORITY = { pro: 0, plus: 1, unknown: 2, free: 3 };
 const LEASE_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const CIRCUIT_WINDOW_MS = 10 * 60_000; // 10 minutes
 const CIRCUIT_MAX_FAILURES = 3;
-const AUTH_BASE_PATH = join(homedir(), ".claude", "cache", "tfx-hub");
-const CODEX_AUTH_SOURCE_PATH = join(homedir(), ".codex", "auth.json");
-const STATE_PERSIST_PATH = join(AUTH_BASE_PATH, "broker-state.json");
+function getAuthBasePath() {
+  return join(homedir(), ".claude", "cache", "tfx-hub");
+}
+
+function getCodexAuthSourcePath() {
+  return join(homedir(), ".codex", "auth.json");
+}
+
+function getStatePersistPath() {
+  return join(getAuthBasePath(), "broker-state.json");
+}
 const AUTH_SYNC_LOCK_TIMEOUT_MS = 5_000;
 const AUTH_SYNC_LOCK_RETRY_MS = 25;
 const AUTH_SYNC_LOCK_STALE_MS = 30_000;
@@ -78,6 +86,8 @@ const AUTH_SYNC_SAB = new Int32Array(new SharedArrayBuffer(4));
 
 function persistState(stateMap) {
   try {
+    const authBasePath = getAuthBasePath();
+    const statePersistPath = getStatePersistPath();
     const now = Date.now();
     const entries = {};
     for (const [id, acct] of stateMap) {
@@ -96,8 +106,8 @@ function persistState(stateMap) {
         };
       }
     }
-    mkdirSync(AUTH_BASE_PATH, { recursive: true });
-    writeFileSync(STATE_PERSIST_PATH, JSON.stringify({ ts: now, entries }));
+    mkdirSync(authBasePath, { recursive: true });
+    writeFileSync(statePersistPath, JSON.stringify({ ts: now, entries }));
   } catch (err) {
     try {
       console.error("[account-broker] persistState failed:", err.message);
@@ -107,8 +117,9 @@ function persistState(stateMap) {
 
 function loadPersistedState() {
   try {
-    if (!existsSync(STATE_PERSIST_PATH)) return null;
-    return JSON.parse(readFileSync(STATE_PERSIST_PATH, "utf8"));
+    const statePersistPath = getStatePersistPath();
+    if (!existsSync(statePersistPath)) return null;
+    return JSON.parse(readFileSync(statePersistPath, "utf8"));
   } catch {
     return null;
   }
@@ -239,6 +250,19 @@ function withLockFile(lockPath, opts, task) {
 
 // ── AccountBroker ────────────────────────────────────────────────
 
+/**
+ * AccountBroker는 codex/gemini 계정 풀 + lease/cooldown/circuit breaker 를 관리한다.
+ *
+ * **Resolved-at-construction 정책 (lazy/eager mix 주의)**
+ *
+ * `getAuthBasePath()` / `getCodexAuthSourcePath()` 는 호출 시점에 `homedir()` 를
+ * 다시 평가하는 lazy getter 다. 그러나 default 파라미터 (`_authBasePath = getAuthBasePath()`)
+ * 는 생성자 호출 시점에 한 번만 평가되고 결과가 `#authBasePath` 등 private field 에 박힌다.
+ *
+ * 결과: 생성자 이후 process.env.HOME 변경은 broker 가 보는 경로에 전파되지 않는다.
+ * 테스트에서 HOME 을 갈아끼우려면 `new AccountBroker(config, { _authBasePath, _codexAuthSourcePath })`
+ * 로 오버라이드를 직접 주입하거나, broker 자체를 재생성해야 한다.
+ */
 class AccountBroker extends EventEmitter {
   #config;
   #state; // Map<accountId, accountState>
@@ -253,8 +277,8 @@ class AccountBroker extends EventEmitter {
     config,
     {
       _skipPersistence = false,
-      _authBasePath = AUTH_BASE_PATH,
-      _codexAuthSourcePath = CODEX_AUTH_SOURCE_PATH,
+      _authBasePath = getAuthBasePath(),
+      _codexAuthSourcePath = getCodexAuthSourcePath(),
       _authSyncLockTimeoutMs = AUTH_SYNC_LOCK_TIMEOUT_MS,
       _authSyncLockRetryMs = AUTH_SYNC_LOCK_RETRY_MS,
       _authSyncLockStaleMs = AUTH_SYNC_LOCK_STALE_MS,

package/hub/cli-adapter-base.mjs

@@ -2,7 +2,7 @@
 // Phase 2: codex-adapter.mjs에서 추출한 재사용 가능 유틸리티
 
 import { execSync, spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 
 import { IS_WINDOWS, killProcess } from "./platform.mjs";
 
@@ -391,7 +391,18 @@ export async function runProcess(command, workdir, timeout, opts = {}) {
     });
   }
 
+  const resultFileSignature = () => {
+    if (!resultFile) return "";
+    try {
+      const info = statSync(resultFile);
+      return `${info.size}:${info.mtimeMs}`;
+    } catch {
+      return "";
+    }
+  };
+
   let lastBytes = 0;
+  let lastResultFileSignature = resultFileSignature();
   let lastChange = Date.now();
   const touch = () => {
     lastChange = Date.now();
@@ -420,8 +431,14 @@ export async function runProcess(command, workdir, timeout, opts = {}) {
   }, timeout);
   const stallTimer = setInterval(() => {
     const size = Buffer.byteLength(stdout) + Buffer.byteLength(stderr);
-    if (size !== lastBytes) {
+    const currentResultFileSignature = resultFileSignature();
+    if (
+      size !== lastBytes ||
+      currentResultFileSignature !== lastResultFileSignature
+    ) {
       lastBytes = size;
+      lastResultFileSignature = currentResultFileSignature;
+      touch();
       return;
     }
     if (Date.now() - lastChange >= stallThresholdMs)

package/hub/team/dashboard-open.mjs

@@ -1,25 +1,9 @@
-import { psmuxExec } from "./psmux.mjs";
-import { detectMultiplexer, hasWindowsTerminal, tmuxExec } from "./session.mjs";
-import { createWtManager } from "./wt-manager.mjs";
-
-function sanitizeWindowTitle(value, fallback = "triflux") {
-  const text = String(value || "")
-    .replace(/[\r\n]+/g, " ")
-    .trim();
-  return text || fallback;
-}
+import { createTerminalOpener } from "./terminal-opener.mjs";
 
 function sanitizeSessionName(value) {
   return String(value || "").replace(/[^a-zA-Z0-9_-]/g, "") || "tfx-session";
 }
 
-function sanitizeWorkingDirectory(value) {
-  const text = String(value || "")
-    .replace(/[\r\n\x00-\x1f]/g, "")
-    .trim();
-  return text || process.cwd();
-}
-
 export function parseWorkerNumber(value) {
   const text = String(value || "").trim();
   const workerMatch = text.match(/^worker-(\d+)$/i);
@@ -29,118 +13,43 @@ export function parseWorkerNumber(value) {
   return null;
 }
 
-export function decideDashboardOpenMode({
-  openAll = false,
-  hasWtSession = !!process.env.WT_SESSION,
-} = {}) {
-  if (openAll) return hasWtSession ? "tab" : "window";
-  return hasWtSession ? "split" : "window";
+function ignoreAsyncFailure(value) {
+  if (value && typeof value.then === "function") void value.catch(() => {});
 }
 
-async function spawnWindowsTerminal(spec, opts = {}) {
-  if (!hasWindowsTerminal()) return false;
-
-  const wt = createWtManager();
-  const {
-    mode = "window",
-    title = "triflux",
-    cwd = process.cwd(),
-    split = { orientation: "H", size: 0.5 },
-  } = opts;
-
-  const safeTitle = sanitizeWindowTitle(title);
-  const safeCwd = sanitizeWorkingDirectory(cwd);
-
-  try {
-    if (mode === "split") {
-      await wt.splitPane({
-        direction: split?.orientation === "V" ? "V" : "H",
-        size: (split?.size || 0.5) * 100,
-        title: safeTitle,
-        cwd: safeCwd,
-        command: spec.args
-          ? `${spec.command} ${spec.args.join(" ")}`
-          : spec.command,
-        profile: "triflux",
-      });
-    } else {
-      await wt.createTab({
-        title: safeTitle,
-        cwd: safeCwd,
-        command: spec.args
-          ? `${spec.command} ${spec.args.join(" ")}`
-          : spec.command,
-        profile: "triflux",
-      });
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
+export async function openHeadlessDashboardTarget(sessionName, opts = {}) {
+  const { openAll = false, cwd = process.cwd(), title } = opts;
+  const safeSession = sanitizeSessionName(sessionName);
+  const workerNumber =
+    opts.workerNumber ??
+    (opts.worker == null ? null : parseWorkerNumber(opts.worker));
 
-async function spawnMacTerminal(spec, opts = {}) {
-  const mux = detectMultiplexer();
-  if (mux === "tmux") {
-    try {
-      const title = sanitizeWindowTitle(opts.title);
-      const command = spec.args
-        ? `${spec.command} ${spec.args.join(" ")}`
-        : spec.command;
-      tmuxExec(`new-window -n "${title}" "${command}"`);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  // tmux 없으면 기본 터미널
+  let opener;
   try {
-    const { exec } = await import("node:child_process");
-    exec(`open -a Terminal`, { timeout: 5000 });
-    return true;
+    const deps = opts._deps ?? {};
+    const openerFactory = deps.createTerminalOpener ?? createTerminalOpener;
+    opener = openerFactory(deps);
   } catch {
-    return false;
+    return !openAll && workerNumber != null;
   }
-}
-
-export function openHeadlessDashboardTarget(sessionName, opts = {}) {
-  const { worker = null, openAll = false, cwd = process.cwd(), title } = opts;
-
-  const safeSession = sanitizeSessionName(sessionName);
-  const workerNumber = worker == null ? null : parseWorkerNumber(worker);
 
   // 선택 워커 → pane focus만 (새 창 열지 않음)
   if (!openAll && workerNumber != null) {
     try {
-      const mux = detectMultiplexer();
-      if (mux === "psmux") {
-        psmuxExec(["select-pane", "-t", `${safeSession}:0.${workerNumber}`]);
-      } else if (
-        mux === "tmux" ||
-        mux === "wsl-tmux" ||
-        mux === "git-bash-tmux"
-      ) {
-        tmuxExec(`select-pane -t ${safeSession}:0.${workerNumber}`);
-      }
+      ignoreAsyncFailure(opener.focusPane(safeSession, workerNumber));
     } catch {}
     return true;
   }
 
   // 전체 열기 (Shift+Enter) → 새 창으로 세션 attach
-  if (process.platform === "win32") {
-    void spawnWindowsTerminal(
-      { command: "psmux", args: ["attach-session", "-t", safeSession] },
-      {
-        mode: decideDashboardOpenMode({ openAll }),
-        title: title || `▲ ${safeSession}`,
-        cwd,
-      },
-    );
-  } else {
-    void spawnMacTerminal(
-      { command: "tmux", args: ["attach-session", "-t", safeSession] },
-      { title: title || `▲ ${safeSession}`, cwd },
-    );
+  try {
+    const opened = opener.openSession(safeSession, {
+      title: title || `▲ ${safeSession}`,
+      cwd,
+      profile: opts.profile ?? "triflux",
+    });
+    return await opened;
+  } catch {
+    return false;
   }
-  return true;
 }

package/hub/team/headless.mjs

@@ -1370,6 +1370,7 @@ export async function autoAttachTerminal(
   opts = {},
   workerCount = 2,
 ) {
+  if (process.platform !== "win32") return false;
   if (!process.env.WT_SESSION) return false;
 
   const wt = createWtManager();

package/hub/team/notify.mjs

@@ -18,6 +18,13 @@ function escapePowerShellSingleQuoted(value) {
   return String(value ?? "").replaceAll("'", "''");
 }
 
+function escapeAppleScriptString(value) {
+  return String(value ?? "")
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replace(/\r?\n/g, " ");
+}
+
 function normalizeTimestamp(value) {
   if (value instanceof Date) return value.toISOString();
   if (value == null || value === "") return new Date().toISOString();
@@ -215,8 +222,8 @@ async function sendToast(event, config, deps) {
   if ((deps.platform || process.platform) === "darwin") {
     const title = formatEventTitle(event);
     const body = formatEventBody(event);
-    const safeTitle = title.replace(/\\/g, "\\\\").replace(/'/g, "'\"'\"'");
-    const safeBody = body.replace(/\\/g, "\\\\").replace(/'/g, "'\"'\"'");
+    const safeTitle = escapeAppleScriptString(title);
+    const safeBody = escapeAppleScriptString(body);
     try {
       await execFileAsync(
         "osascript",

package/hub/team/runtime-strategy.mjs

@@ -60,9 +60,25 @@ export function createPsmuxRuntime(adapter = defaultPsmuxAdapter) {
 // tmux 어댑터
 // ---------------------------------------------------------------------------
 
+// tmux 세션 이름은 tmuxExec 명령 문자열에 직접 보간되므로 shell 메타문자가 들어오면 위험.
+// 현 호출처는 모두 safe identifier (slug/uuid 류) 이지만 어댑터 export 가 contract 를
+// 강제하지 않아 외부 호출자가 임의 문자열을 주입할 수 있다 → 보수적으로 검증.
+const TMUX_SAFE_SESSION_NAME = /^[A-Za-z0-9_.:-]+$/;
+
+function assertSafeTmuxSessionName(sessionName) {
+  const value = String(sessionName ?? "");
+  if (!TMUX_SAFE_SESSION_NAME.test(value)) {
+    throw new Error(
+      `Unsafe tmux session name: ${JSON.stringify(value)} (allowed: A-Za-z0-9_.:-)`,
+    );
+  }
+  return value;
+}
+
 function tmuxSessionExists(sessionName) {
+  const safe = assertSafeTmuxSessionName(sessionName);
   try {
-    tmuxExec(`has-session -t ${sessionName}`);
+    tmuxExec(`has-session -t ${safe}`);
     return true;
   } catch {
     return false;
@@ -70,12 +86,25 @@ function tmuxSessionExists(sessionName) {
 }
 
 function createTmuxSession(sessionName, opts = {}) {
-  tmuxExec(`new-session -d -s ${sessionName} -x 220 -y 55`);
+  const safe = assertSafeTmuxSessionName(sessionName);
+  tmuxExec(`new-session -d -s ${safe} -x 220 -y 55`);
+}
+
+function sendPromptToTmuxSession(sessionName, prompt) {
+  const safe = assertSafeTmuxSessionName(sessionName);
+  const quotedPrompt = String(prompt).replace(/'/g, "'\\''");
+  tmuxExec(`send-keys -t ${safe}:0.0 '${quotedPrompt}' Enter`);
 }
 
 function killTmuxSessionByName(sessionName) {
+  let safe;
   try {
-    tmuxExec(`kill-session -t ${sessionName}`);
+    safe = assertSafeTmuxSessionName(sessionName);
+  } catch {
+    return;
+  }
+  try {
+    tmuxExec(`kill-session -t ${safe}`);
   } catch {
     // 이미 종료된 세션 — 무시
   }
@@ -83,6 +112,7 @@ function killTmuxSessionByName(sessionName) {
 
 const defaultTmuxAdapter = {
   createSession: createTmuxSession,
+  sendPrompt: sendPromptToTmuxSession,
   killSession: killTmuxSessionByName,
   hasSession: tmuxSessionExists,
 };
@@ -90,28 +120,55 @@ const defaultTmuxAdapter = {
 /**
  * @param {{
  *   createSession: typeof createTmuxSession,
+ *   sendPrompt: typeof sendPromptToTmuxSession,
  *   killSession: typeof killTmuxSessionByName,
  *   hasSession: typeof tmuxSessionExists,
- * }} [adapter]
- * @returns {TeamRuntime & { name: "tmux" }}
+ * }} [opts.adapter]
+ * @param {string} [opts.sessionName]
+ * @returns {{
+ *   name: "tmux",
+ *   kind: "tmux",
+ *   sessionName: string,
+ *   createSession: (opts?: object) => unknown,
+ *   sendPrompt: (prompt: string) => unknown,
+ *   start: (sessionName: string, opts?: object) => unknown,
+ *   stop: (sessionName: string) => void,
+ *   isAlive: (sessionName: string) => boolean,
+ *   getStatus: (sessionName: string) => RuntimeStatus,
+ * }}
  */
-export function createTmuxRuntime(adapter = defaultTmuxAdapter) {
+export function createTmuxRuntime(opts = {}) {
+  const { adapter = defaultTmuxAdapter, sessionName = "" } = opts;
+
   return {
     name: "tmux",
-    start(sessionName, opts = {}) {
-      return adapter.createSession(sessionName, opts);
+    kind: "tmux",
+    sessionName,
+    // start() 와 동일하게 첫 인자로 sessionName override 를 받는다.
+    // 첫 인자가 string 이 아니면 (옵션 객체 등) closure sessionName 을 사용하는 legacy 형태로 폴백.
+    createSession(sessionNameArg, opts) {
+      if (typeof sessionNameArg === "string") {
+        return adapter.createSession(sessionNameArg, opts ?? {});
+      }
+      return adapter.createSession(sessionName, sessionNameArg ?? {});
     },
-    stop(sessionName) {
-      adapter.killSession(sessionName);
+    sendPrompt(prompt, sessionNameArg = sessionName) {
+      return adapter.sendPrompt(sessionNameArg, prompt);
     },
-    isAlive(sessionName) {
-      return adapter.hasSession(sessionName);
+    start(sessionNameArg = sessionName, opts = {}) {
+      return adapter.createSession(sessionNameArg, opts);
     },
-    getStatus(sessionName) {
+    stop(sessionNameArg = sessionName) {
+      adapter.killSession(sessionNameArg);
+    },
+    isAlive(sessionNameArg = sessionName) {
+      return adapter.hasSession(sessionNameArg);
+    },
+    getStatus(sessionNameArg = sessionName) {
       return {
         name: "tmux",
-        sessionName,
-        alive: adapter.hasSession(sessionName),
+        sessionName: sessionNameArg,
+        alive: adapter.hasSession(sessionNameArg),
       };
     },
   };
@@ -119,9 +176,10 @@ export function createTmuxRuntime(adapter = defaultTmuxAdapter) {
 
 /**
  * @param {string} mode
+ * @param {object} [opts]
  * @returns {TeamRuntime & { name: string }}
  */
-export function createRuntime(mode) {
+export function createRuntime(mode, opts = {}) {
   const normalizedMode = String(mode || "")
     .trim()
     .toLowerCase();
@@ -131,7 +189,7 @@ export function createRuntime(mode) {
   }
 
   if (normalizedMode === "tmux") {
-    return createTmuxRuntime();
+    return createTmuxRuntime(opts);
   }
 
   if (normalizedMode === "native" || normalizedMode === "wt") {

package/hub/team/terminal-opener.mjs

@@ -0,0 +1,178 @@
+import { exec as defaultExec } from "node:child_process";
+import { platform as osPlatform } from "node:os";
+import { psmuxExec as defaultPsmuxExec } from "./psmux.mjs";
+import { tmuxExec as defaultTmuxExec, detectMultiplexer } from "./session.mjs";
+import { createWtManager as defaultCreateWtManager } from "./wt-manager.mjs";
+
+const TMUX_LIKE_MUXES = new Set(["tmux", "wsl-tmux", "git-bash-tmux"]);
+
+export function sanitizeTerminalTitle(value, fallback = "triflux") {
+  const title = String(value ?? "")
+    .replace(/\s+/gu, " ")
+    .trim();
+  return title || fallback;
+}
+
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+export function powershellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+export function buildCommandString({ cwd, command }) {
+  const commandString = String(command ?? "");
+  if (!cwd) return commandString;
+  return `cd ${shellQuote(cwd)} && ${commandString}`;
+}
+
+function resolvePlatform(deps) {
+  if (typeof deps.platform === "function") return deps.platform();
+  return deps.platform || osPlatform();
+}
+
+function resolveMux(deps) {
+  if (Object.hasOwn(deps, "mux")) return deps.mux;
+  if (typeof deps.detectMultiplexer === "function")
+    return deps.detectMultiplexer();
+  return detectMultiplexer();
+}
+
+function createTabSpec(spec, title) {
+  return {
+    title,
+    command: String(spec.command ?? ""),
+    cwd: spec.cwd,
+    profile: spec.profile ?? "triflux",
+  };
+}
+
+function execOpenTerminal(execFn) {
+  return new Promise((resolve) => {
+    execFn("open -a Terminal", { timeout: 5000 }, (error) => {
+      resolve(!error);
+    });
+  });
+}
+
+// psmux는 Windows에서 wt-manager 경유 (createTab/splitPane 등) — tmux 호환 unix 명령군과 다른 표면.
+// 비-Windows(macOS/Linux) 환경에서는 psmux가 tmux-compatible new-window/select-pane 명령을 받아주므로
+// tmux 어댑터와 동일하게 취급한다.
+function isTmuxLikeMux(mux, platform) {
+  return TMUX_LIKE_MUXES.has(mux) || (platform !== "win32" && mux === "psmux");
+}
+
+function shellCommandName(value) {
+  const command = String(value);
+  return /^[A-Za-z0-9_./:-]+$/u.test(command) ? command : shellQuote(command);
+}
+
+function buildAttachCommand(mux, sessionName) {
+  if (mux === "psmux") {
+    return `${shellCommandName(process.env.PSMUX_BIN || "psmux")} attach-session -t ${shellQuote(sessionName)}`;
+  }
+  return `tmux attach-session -t ${shellQuote(sessionName)}`;
+}
+
+// wt-manager.createTab은 (a) undefined/void 반환 — legacy success 의미 (b) {success:true|false, ...} 객체 반환의 두 형태가 공존.
+// `result?.success !== false`는 undefined/null/{}을 모두 success로 취급하고 명시적 {success:false}만 실패로 본다.
+function wtResultSucceeded(result) {
+  return result?.success !== false;
+}
+
+export function createTerminalOpener(deps = {}) {
+  const platform = resolvePlatform(deps);
+  const tmuxExec = deps.tmuxExec || defaultTmuxExec;
+  const psmuxExec = deps.psmuxExec || defaultPsmuxExec;
+  const exec = deps.exec || defaultExec;
+  const createWtManager = deps.createWtManager || defaultCreateWtManager;
+
+  async function openCommand(spec = {}) {
+    const title = sanitizeTerminalTitle(spec.title);
+
+    if (platform === "win32") {
+      const wt = createWtManager();
+      try {
+        return wtResultSucceeded(
+          await wt.createTab(createTabSpec(spec, title)),
+        );
+      } catch {
+        return false;
+      }
+    }
+
+    const mux = resolveMux(deps);
+    if (isTmuxLikeMux(mux, platform)) {
+      tmuxExec(
+        `new-window -n ${shellQuote(title)} ${shellQuote(
+          buildCommandString(spec),
+        )}`,
+      );
+      return true;
+    }
+
+    if (platform === "darwin") {
+      return execOpenTerminal(exec);
+    }
+
+    return false;
+  }
+
+  async function openSession(sessionName, opts = {}) {
+    if (platform === "win32") {
+      const wt = createWtManager();
+      try {
+        return wtResultSucceeded(
+          await wt.createTab({
+            title: sanitizeTerminalTitle(opts.title ?? sessionName),
+            command: `psmux attach-session -t ${powershellSingleQuote(sessionName)}`,
+            cwd: opts.cwd,
+            profile: opts.profile ?? "triflux",
+          }),
+        );
+      } catch {
+        return false;
+      }
+    }
+
+    const mux = resolveMux(deps);
+    if (isTmuxLikeMux(mux, platform)) {
+      tmuxExec(
+        `new-window -n ${shellQuote(opts.title ?? sessionName)} ${shellQuote(
+          buildAttachCommand(mux, sessionName),
+        )}`,
+      );
+      return true;
+    }
+
+    return false;
+  }
+
+  function focusPane(sessionName, workerNumber) {
+    const target = `${sessionName}:0.${workerNumber}`;
+    const mux = resolveMux(deps);
+
+    if (mux === "psmux") {
+      psmuxExec(["select-pane", "-t", target]);
+      return true;
+    }
+
+    if (isTmuxLikeMux(mux, platform)) {
+      tmuxExec(`select-pane -t ${shellQuote(target)}`);
+      return true;
+    }
+
+    return false;
+  }
+
+  return { openCommand, openSession, focusPane };
+}
+
+export function openSessionTarget(sessionName, opts = {}) {
+  return createTerminalOpener(opts._deps).openSession(sessionName, opts);
+}
+
+export function focusSessionPane(sessionName, workerNumber, opts = {}) {
+  return createTerminalOpener(opts._deps).focusPane(sessionName, workerNumber);
+}

package/hub/team/worktree-lifecycle.mjs

@@ -4,7 +4,7 @@
 // Remote support: host option → SSH-based git operations via remote-session.mjs.
 
 import { execFile } from "node:child_process";
-import { access, mkdir, readdir, rm } from "node:fs/promises";
+import { access, mkdir, readdir, realpath, rm } from "node:fs/promises";
 import { join, normalize, relative, resolve } from "node:path";
 import { remoteGit, validateHost } from "./remote-session.mjs";
 
@@ -117,6 +117,14 @@ function normPath(p) {
   return normalize(p).replace(/\\/g, "/");
 }
 
+async function normExistingPath(p) {
+  try {
+    return normPath(await realpath(p));
+  } catch {
+    return normPath(p);
+  }
+}
+
 function resolveCleanupTarget(worktreePath, rootDir) {
   const resolvedRoot = resolve(rootDir);
   const resolvedWorktree = resolve(worktreePath);
@@ -562,10 +570,12 @@ export async function pruneOrphanWorktrees({ rootDir = process.cwd() } = {}) {
   try {
     const raw = await git(["worktree", "list", "--porcelain"], rootDir);
     registeredPaths = new Set(
-      raw
-        .split("\n")
-        .filter((l) => l.startsWith("worktree "))
-        .map((l) => normPath(l.slice("worktree ".length))),
+      await Promise.all(
+        raw
+          .split("\n")
+          .filter((l) => l.startsWith("worktree "))
+          .map((l) => normExistingPath(l.slice("worktree ".length))),
+      ),
     );
   } catch {
     return removed; // git worktree list failed → don't remove anything
@@ -573,7 +583,7 @@ export async function pruneOrphanWorktrees({ rootDir = process.cwd() } = {}) {
 
   for (const dir of wtDirs) {
     const fullPath = resolve(swarmDir, dir);
-    const normalized = normPath(fullPath);
+    const normalized = await normExistingPath(fullPath);
     if (!registeredPaths.has(normalized)) {
       try {
         await stopFsmonitorDaemon(fullPath).catch(() => null);

package/hub/team/wt-manager.mjs

@@ -170,12 +170,34 @@ function atomicWriteSync(filePath, data) {
  * @param {number} [opts.tabCreateDelayMs=500]
  * @param {object} [opts.deps] — 테스트용 의존성 주입
  */
+function createNonWindowsStubManager() {
+  const asyncFalse = async () => false;
+  return Object.freeze({
+    ensureWtProfile: () => {},
+    createTab: asyncFalse,
+    renameTab: asyncFalse,
+    closeTab: asyncFalse,
+    listTabs: async () => [],
+    closeStale: async () => 0,
+    createSession: asyncFalse,
+    splitPane: asyncFalse,
+    applySplitLayout: asyncFalse,
+    getEnvironmentInfo: () => ({
+      platform: process.platform,
+      hasWindowsTerminal: false,
+      hasWt: false,
+      isWindowsTerminalSession: false,
+    }),
+    getTabCount: () => 0,
+  });
+}
+
 export function createWtManager(opts = {}) {
   const deps = opts.deps || {};
   const platform = deps.platform || osPlatform;
 
   if (platform() !== "win32") {
-    throw new Error("wt-manager.mjs is Windows-only");
+    return createNonWindowsStubManager();
   }
 
   const now = deps.now || Date.now;

package/hub/workers/codex-mcp.mjs

@@ -16,6 +16,7 @@ const REQUIRED_TOOLS = ["codex", "codex-reply"];
 export { CODEX_MCP_EXECUTION_EXIT_CODE, CODEX_MCP_TRANSPORT_EXIT_CODE };
 export const DEFAULT_CODEX_MCP_TIMEOUT_MS = 10 * 60 * 1000;
 export const DEFAULT_CODEX_MCP_BOOTSTRAP_TIMEOUT_MS = 120 * 1000;
+export const DEFAULT_CODEX_MCP_SHUTDOWN_TIMEOUT_MS = 2_000;
 
 /**
  * Codex MCP transport/bootstrap 계층 오류
@@ -40,6 +41,34 @@ function cloneEnv(env = process.env) {
   );
 }
 
+async function closeWithin(label, closeFn, timeoutMs) {
+  let timer = null;
+  try {
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        resolve({ timedOut: true });
+      }, timeoutMs);
+    });
+    const closed = Promise.resolve()
+      .then(closeFn)
+      .then(() => ({ timedOut: false }));
+    const result = await Promise.race([closed, timeout]);
+    if (result.timedOut) {
+      console.error(
+        `[codex-mcp] WARNING: ${label} did not close within ${timeoutMs}ms; continuing shutdown.`,
+      );
+    }
+    return result;
+  } catch (error) {
+    console.error(
+      `[codex-mcp] WARNING: ${label} close failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return { timedOut: false };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 function collectTextContent(content = []) {
   return content
     .filter((item) => item?.type === "text" && typeof item.text === "string")
@@ -388,7 +417,7 @@ export class CodexMcpWorker {
     this.ready = true;
   }
 
-  async stop() {
+  async stop(options = {}) {
     this.ready = false;
     this.availableTools.clear();
 
@@ -397,10 +426,26 @@ export class CodexMcpWorker {
     this.transport = null;
     this.client = null;
 
+    const shutdownTimeoutMs = Number.isFinite(options.shutdownTimeoutMs)
+      ? options.shutdownTimeoutMs
+      : DEFAULT_CODEX_MCP_SHUTDOWN_TIMEOUT_MS;
+
+    let clientCloseTimedOut = false;
     if (client) {
-      await client.close().catch(() => {});
-    } else if (transport) {
-      await transport.close().catch(() => {});
+      const result = await closeWithin(
+        "client.close",
+        () => client.close(),
+        shutdownTimeoutMs,
+      );
+      clientCloseTimedOut = Boolean(result.timedOut);
+    }
+
+    if (transport && (!client || clientCloseTimedOut)) {
+      await closeWithin(
+        "transport.close",
+        () => transport.close(),
+        shutdownTimeoutMs,
+      );
     }
 
     transport?.stderr?.destroy?.();

package/package.json

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

package/scripts/setup.mjs

@@ -18,7 +18,7 @@ import {
   writeFileSync,
 } from "fs";
 import { homedir } from "os";
-import { dirname, join, relative } from "path";
+import { dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import {
   ensureGlobalClaudeRoutingSection,
@@ -498,10 +498,22 @@ function extractManagedHookFilename(command) {
   return match ? match[1] : null;
 }
 
+function expandRequiresPath(value) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  return resolve(
+    value.replace(/\$\{HOME\}/g, _TFX_HOME).replace(/\$HOME\b/g, _TFX_HOME),
+  );
+}
+
+function isRequiredPathAvailable(value) {
+  const expanded = expandRequiresPath(value);
+  return expanded ? existsSync(expanded) : true;
+}
+
 /**
  * hook-registry.json에서 관리 대상 훅 목록을 플랫 배열로 반환한다.
  * @param {string} registryPath - hook-registry.json 경로
- * @returns {Array<{ event: string, id: string, fileName: string, matcher: string, command: string, priority: number, enabled: boolean }>}
+ * @returns {Array<{ event: string, id: string, fileName: string, matcher: string, command: string, priority: number, enabled: boolean, requires?: string }>}
  */
 function getManagedRegistryHooks(registryPath) {
   if (!existsSync(registryPath)) return [];
@@ -513,6 +525,7 @@ function getManagedRegistryHooks(registryPath) {
       if (!Array.isArray(hooks)) continue;
       for (const hook of hooks) {
         if (!hook.enabled) continue;
+        if (!isRequiredPathAvailable(hook.requires)) continue;
         const fileName = extractManagedHookFilename(hook.command);
         result.push({
           event,
@@ -522,6 +535,7 @@ function getManagedRegistryHooks(registryPath) {
           command: hook.command || "",
           priority: hook.priority ?? 100,
           enabled: hook.enabled,
+          requires: hook.requires,
         });
       }
     }

package/scripts/tfx-route-worker.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // tfx-route-worker.mjs — tfx-route.sh용 subprocess worker 러너
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -133,8 +133,18 @@ function parseJsonArray(raw, label) {
   }
 }
 
-function readPromptFromStdin() {
-  return readFileSync(0, "utf8");
+async function readPromptFromStdin() {
+  // Stream-based async read avoids EAGAIN race on Node v25 + background pipe stdin.
+  // readFileSync(0, "utf8") raised EAGAIN when stdin pipe was non-blocking and
+  // data hadn't fully arrived (Node v25 timing change vs v22), causing the
+  // tfx-route.sh wrapper to fall back to claude-native silently.
+  if (process.stdin.isTTY) return "";
+  process.stdin.setEncoding("utf8");
+  let data = "";
+  for await (const chunk of process.stdin) {
+    data += chunk;
+  }
+  return data;
 }
 
 function resolveDefaultMcpConfig(cwd) {
@@ -197,7 +207,7 @@ async function runWorker(worker, type, prompt) {
 }
 
 const args = parseArgs(process.argv.slice(2));
-const prompt = readPromptFromStdin();
+const prompt = await readPromptFromStdin();
 
 const worker = await createWorker(args.type, {
   command: args.command,

package/scripts/tfx-route.sh

@@ -365,7 +365,8 @@ mkdir -p "$TFX_PROBE_DIR" 2>/dev/null || true
 
 estimate_expected_duration_sec() {
   local agent="${1:-}" profile="${2:-}" prompt="${3:-}"
-  local text="${prompt,,}"
+  local text
+  text=$(printf '%s' "$prompt" | tr '[:upper:]' '[:lower:]')
   local expected=30
 
   case "$agent" in
@@ -939,9 +940,9 @@ resolve_gemini_profile() {
       }
     }
 
-    process.stdout.write(defaults[name] || defaults.pro31);
+    process.stdout.write(defaults[name] || defaults[process.env.TFX_GEMINI_DEFAULT_PROFILE] || defaults.pro25);
   " "$profile" "$_GEMINI_PROFILE_CACHE" "$settings_cache" 2>/dev/null)
-  echo "${result:-gemini-3.1-pro-preview}"
+  echo "${result:-gemini-2.5-pro}"
 }
 
 # ── 라우팅 테이블 ──

package/skills/tfx-wt/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: tfx-wt
+description: >
+  Windows Terminal 탭/패인 자연어 조작. 사용자가 "새 탭 열어줘", "패인 분할",
+  "탭 목록", "탭 닫아" 같은 한국어/영어 표현을 쓰면 wt-cli.mjs 경유로 wt-manager API 호출.
+  safety-guard가 wt.exe 직접 호출을 차단하므로 이 스킬이 유일한 경로다.
+  Use when: 새 탭, tab open, 패인, pane split, 탭 목록, 탭 닫아, wt 탭, wt 패인
+triggers:
+  - tfx-wt
+  - wt-tab-route
+  - wt-tab-rename
+  - wt-tab-list
+  - wt-tab-close
+argument-hint: "<create-tab|split-pane|layout|list|close|close-stale|rename> [json-opts]"
+---
+
+# tfx-wt — Windows Terminal 자연어 조작
+
+> **ARGUMENTS 처리**: 이 스킬이 `ARGUMENTS: <값>`과 함께 호출되면, 해당 값을 사용자 입력으로 취급한다.
+> ARGUMENTS가 비어있거나 없으면 사용자에게 의도 확인 후 적절한 action 으로 라우팅한다.
+
+> **인프라**: keyword-rules.json 의 `wt-tab-*` 4 규칙이 이 스킬로 라우팅한다.
+> 사용자는 보통 자연어로 호출 ("탭 열어줘") 하므로 의도 → action 매핑이 첫 단계.
+
+## OS 정책
+
+이 스킬은 **Windows 전용**. macOS/Linux 의 탭/패인 자연어 라우팅은 본 스킬 범위 외다.
+
+| OS | 동작 | 라우팅 |
+|----|------|--------|
+| Windows | `wt.exe` 실제 호출 (wt-manager 경유). safety-guard 차단 우회 | **tfx-wt 가 담당** |
+| macOS / Linux | `createWtManager()` 가 stub 반환 (PR #241). 모든 action no-op | **`terminal-opener.mjs` 가 tmux 경로로 담당** (PR #236). tfx-wt 는 사용자에게 안내만 |
+
+### 분리 정신 (PR #236, #241)
+
+| 레이어 | 역할 |
+|--------|------|
+| `hub/team/wt-manager.mjs` | Windows-only (non-Windows 에서 stub). tfx-wt 가 사용 |
+| `hub/team/terminal-opener.mjs` | Cross-platform abstraction. Windows→wt-manager, macOS/Linux→tmux |
+| `hub/team/runtime-strategy.mjs` | `psmux` (Windows) 와 `tmux` (macOS/Linux) runtime identity 분리 유지 |
+
+macOS 사용자가 "탭 열어"라고 했는데 본 스킬로 들어오면 잘못된 라우팅. 사용자에게 다음을 안내한 뒤 종료:
+- "Windows Terminal 은 macOS 에 없습니다."
+- "macOS 에서 새 탭/패인 자동 생성이 필요하면 `terminal-opener.mjs` 의 tmux 경로를 사용하세요."
+- "오케스트레이션 (swarm worker 배치, dashboard) 은 자동으로 OS 분기됩니다."
+
+`wt-manager.mjs` 자체가 OS-aware 이므로 스킬 코드에서 platform 분기 불필요.
+
+## 의도 → action 매핑
+
+| 자연어 입력 | action | 예시 |
+|------------|--------|------|
+| 새 탭, tab open, 탭 추가/생성/열어/띄워, 터미널 탭 | `create-tab` | "새 탭 열어줘" |
+| 패인 분할, pane split, 화면 나눠 | `split-pane` | "패인 가로로 분할" |
+| 탭 + 여러 개 동시 배치, layout, dashboard | `layout` | "워커 3개 가로로 배치" |
+| 탭 목록, 탭 리스트, 열린 탭, 현재 탭 | `list` | "지금 탭 뭐있어" |
+| 탭 닫아, 탭 종료, tab close, 탭 정리 | `close` | "worker 탭 닫아" |
+| 오래된 탭 정리, stale 탭, idle 탭 정리 | `close-stale` | "1시간 넘은 탭 정리해" |
+| 탭 이름 변경, 탭 제목 바꿔, rename | `rename` | "이 탭 이름 backend 로 바꿔" |
+
+## wt + psmux 통합 패턴 (Windows 기본 사용 흐름)
+
+triflux 의 WT `triflux` 프로파일은 **commandline = psmux** (wt-manager:319 의 `ensureWtProfile`). 즉 wt 의 새 탭/패인 = wt 가 컨테이너, **그 안에서 psmux 가 멀티플렉서로 도는 구조**. swarm worker, dashboard, 장기 세션 모두 이 형태.
+
+| 레이어 | 역할 |
+|--------|------|
+| wt | 윈도우 / 탭 / 패인 컨테이너 |
+| psmux (탭 내부 default 셸) | 세션 호스팅. detach → wt 닫혀도 살아있음 → 재첨부 가능 |
+
+전형적인 `wt sp` 한 줄 (`.claude/rules/tfx-psmux.md` RULE 5-3 인용):
+
+```bash
+wt.exe -w 0 sp -H -p triflux --title "worker" psmux attach-session -t SESSION
+```
+
+이걸 본 스킬에서 호출하려면 `split-pane` 또는 `create-tab` 의 `command` 에 `psmux attach-session -t <session>` 을 넣는다. 다중 worker 동시 배치는 `layout`.
+
+### Swarm worker 다중 배치 (전형)
+
+```bash
+node scripts/wt-cli.mjs layout '[
+  {"title":"w1","command":"psmux attach-session -t s1","direction":"H"},
+  {"title":"w2","command":"psmux attach-session -t s2","direction":"V"},
+  {"title":"w3","command":"psmux attach-session -t s3","direction":"V"}
+]'
+```
+
+각 패인이 미리 띄워둔 psmux session (s1/s2/s3) 에 attach. wt 패인 닫혀도 psmux session 은 살아있어 재시작 후 reattach 가능.
+
+### 일반 명령 실행 (psmux 통합 불필요한 경우)
+
+장기 세션이 아니고 단발 명령이면 psmux 우회 가능:
+
+```bash
+node scripts/wt-cli.mjs create-tab '{"title":"build","command":"npm run build","profile":"triflux"}'
+```
+
+`profile: "triflux"` 가 자동으로 psmux 를 셸로 띄우긴 하지만, `command` 가 즉시 종료되면 `closeOnExit: "always"` (wt-manager:331) 로 패인도 닫힘.
+
+## 실행
+
+`scripts/wt-cli.mjs` 가 `wt-manager` 의 thin wrapper. json-opts 는 단일 인자로 전달.
+
+```bash
+node scripts/wt-cli.mjs <action> '<json-opts>'
+```
+
+### create-tab — 새 탭 생성
+
+```bash
+node scripts/wt-cli.mjs create-tab '{"title":"backend","command":"npm run dev","profile":"triflux","cwd":"C:\\path"}'
+```
+
+| 옵션 | 필수 | 기본 |
+|------|------|------|
+| `title` | 권장 | 자동 |
+| `command` | 권장 | shell |
+| `profile` | 선택 | "triflux" |
+| `cwd` | 선택 | 현재 |
+
+반환: `{ success, title, id? }`
+
+### split-pane — 패인 분할
+
+```bash
+node scripts/wt-cli.mjs split-pane '{"direction":"H","title":"logs","command":"tail -f log"}'
+```
+
+| 옵션 | 값 | 의미 |
+|------|-----|------|
+| `direction` | `"H"` / `"V"` | 가로 / 세로 |
+| `title` | string | 패인 제목 |
+| `command` | string | 실행할 명령 |
+
+### layout — 다중 패인 배치
+
+```bash
+node scripts/wt-cli.mjs layout '[{"title":"w1","command":"...","direction":"H"},{"title":"w2","command":"...","direction":"V"}]'
+```
+
+또는 객체 형태: `'{"panes":[...]}'`. dashboard / swarm worker 배치에 사용.
+
+### list — 탭 목록
+
+```bash
+node scripts/wt-cli.mjs list
+```
+
+반환: `[{ title, id, ... }]`. macOS/Linux 에서는 `[]`.
+
+### close — 탭 닫기
+
+```bash
+node scripts/wt-cli.mjs close '{"title":"worker-1"}'
+```
+
+`title` 은 정확 일치 또는 prefix. **단일 탭** 닫기.
+
+### close-stale — 오래된 탭 정리
+
+```bash
+node scripts/wt-cli.mjs close-stale '{"olderThanMs":3600000,"titlePattern":"worker-"}'
+```
+
+| 옵션 | 의미 |
+|------|------|
+| `olderThanMs` | 이 ms 이상 idle 탭만 |
+| `titlePattern` | title prefix 또는 regex 매칭만 |
+| `dryRun` | true 시 닫을 후보만 반환 |
+
+반환: `{ success, closed: ["title-1", ...] }`
+
+### rename — 탭 이름 변경
+
+```bash
+node scripts/wt-cli.mjs rename '{"title":"old","newTitle":"backend"}'
+```
+
+## CLAUDE.md 규칙 준수
+
+CLAUDE.md `psmux-wt > wt.exe → wt-manager 경유` 섹션:
+
+| 차단되는 직접 호출 | 이 스킬 경유 |
+|-------------------|-------------|
+| `wt.exe new-tab ...` | `create-tab` |
+| `wt.exe split-pane ...` | `split-pane` |
+| `wt.exe -w 0 sp -H ...` | `layout` (다중) 또는 `split-pane` (단일) |
+| `Start-Process wt.exe ...` (PowerShell) | `create-tab` |
+
+safety-guard 가 위 4 패턴을 모두 차단하므로 자연어 라우팅 → `tfx-wt` → `wt-cli.mjs` 가 유일한 안전 경로.
+
+## 안티패턴
+
+| 패턴 | 문제 | 대체 |
+|------|------|------|
+| `Bash("wt.exe new-tab ...")` | safety-guard 차단 | `node scripts/wt-cli.mjs create-tab '{...}'` |
+| macOS 에서 "탭 열어" 받고 강제 실행 시도 | wt-manager stub 반환 → 효과 없음 + 혼란 | "Windows Terminal 미설치 환경 — no-op" 명시 후 종료 |
+| `wt.exe -w 0 nt` (새 창) | CLAUDE.md tfx-psmux.md RULE 5-3 금지 | `sp -H` / `sp -V` (split) 사용 |
+| 다중 패인을 `create-tab` N회 호출 | 새 창 N개 띄우기 | `layout` 한 번 호출 |
+
+## 관련
+
+- `scripts/wt-cli.mjs` — CLI wrapper (이 스킬이 호출)
+- `hub/team/wt-manager.mjs` — 실제 구현체 (`createTab`, `splitPane`, `applySplitLayout`, `closeTab`, `closeStale`, `renameTab`, `listTabs`)
+- CLAUDE.md `psmux-wt` 섹션 — wt-manager API 가이드
+- `.claude/rules/tfx-psmux.md` — psmux/WT 정책 RULE 5/6
+- `hooks/keyword-rules.json` `wt-tab-*` 4 규칙 — 자연어 라우팅 진입점
+
+## 메모
+
+- PR #241 (5/8) 이후 macOS/Linux 에서도 안전. wt-manager 가 stub 반환하므로 crash 없이 no-op.
+- 4/11 b313c648 커밋이 keyword-rules + wt-cli.mjs 만 추가하고 SKILL.md 를 빠뜨려 한 달간 dead 라우팅. issue #248 로 발견 후 본 스킬 추가.