triflux 3.2.0-dev.12 → 3.2.0-dev.14

package/hooks/hooks.json

@@ -9,6 +9,11 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/setup.mjs\"",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/preflight-cache.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/hub/bridge.mjs

@@ -12,6 +12,16 @@ import { parseArgs as nodeParseArgs } from 'node:util';
 import { randomUUID } from 'node:crypto';
 
 const HUB_PID_FILE = join(homedir(), '.claude', 'cache', 'tfx-hub', 'hub.pid');
+const HUB_TOKEN_FILE = join(homedir(), '.claude', '.tfx-hub-token');
+
+// Hub 인증 토큰 읽기 (파일 없으면 null → 하위 호환)
+function readHubToken() {
+  try {
+    return readFileSync(HUB_TOKEN_FILE, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
 
 export function getHubUrl() {
   if (process.env.TFX_HUB_URL) return process.env.TFX_HUB_URL.replace(/\/mcp$/, '');
@@ -46,9 +56,15 @@ export async function post(path, body, timeoutMs = 5000) {
   const timer = setTimeout(() => controller.abort(), timeoutMs);
 
   try {
+    const headers = { 'Content-Type': 'application/json' };
+    const token = readHubToken();
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
     const res = await fetch(`${getHubUrl()}${path}`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers,
       body: JSON.stringify(body),
       signal: controller.signal,
     });
@@ -316,7 +332,7 @@ async function cmdTeamInfo(args) {
   }
   // Hub 미실행 fallback — nativeProxy 직접 호출
   const { teamInfo } = await import('./team/nativeProxy.mjs');
-  console.log(JSON.stringify(teamInfo(body)));
+  console.log(JSON.stringify(await teamInfo(body)));
 }
 
 async function cmdTeamTaskList(args) {
@@ -334,7 +350,7 @@ async function cmdTeamTaskList(args) {
   }
   // Hub 미실행 fallback — nativeProxy 직접 호출
   const { teamTaskList } = await import('./team/nativeProxy.mjs');
-  console.log(JSON.stringify(teamTaskList(body)));
+  console.log(JSON.stringify(await teamTaskList(body)));
 }
 
 async function cmdTeamTaskUpdate(args) {
@@ -360,7 +376,7 @@ async function cmdTeamTaskUpdate(args) {
   }
   // Hub 미실행 fallback — nativeProxy 직접 호출
   const { teamTaskUpdate } = await import('./team/nativeProxy.mjs');
-  console.log(JSON.stringify(teamTaskUpdate(body)));
+  console.log(JSON.stringify(await teamTaskUpdate(body)));
 }
 
 async function cmdTeamSendMessage(args) {
@@ -379,7 +395,7 @@ async function cmdTeamSendMessage(args) {
   }
   // Hub 미실행 fallback — nativeProxy 직접 호출
   const { teamSendMessage } = await import('./team/nativeProxy.mjs');
-  console.log(JSON.stringify(teamSendMessage(body)));
+  console.log(JSON.stringify(await teamSendMessage(body)));
 }
 
 function getHubDbPath() {

package/hub/server.mjs

@@ -52,6 +52,14 @@ async function parseBody(req) {
 
 const PID_DIR = join(homedir(), '.claude', 'cache', 'tfx-hub');
 const PID_FILE = join(PID_DIR, 'hub.pid');
+const TOKEN_FILE = join(homedir(), '.claude', '.tfx-hub-token');
+
+// localhost 계열 Origin만 허용
+const ALLOWED_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+
+function isAllowedOrigin(origin) {
+  return origin && ALLOWED_ORIGIN_RE.test(origin);
+}
 
 /**
  * tfx-hub 시작
@@ -66,6 +74,11 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
     dbPath = join(PID_DIR, 'state.db');
   }
 
+  // 인증 토큰 생성 (환경변수 우선, 없으면 자동 생성)
+  const HUB_TOKEN = process.env.TFX_HUB_TOKEN || randomUUID();
+  mkdirSync(join(homedir(), '.claude'), { recursive: true });
+  writeFileSync(TOKEN_FILE, HUB_TOKEN, { mode: 0o600 });
+
   const store = createStore(dbPath);
   const router = createRouter(store);
   const pipe = createPipeServer({ router, store, sessionId });
@@ -109,12 +122,16 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
   }
 
   const httpServer = createHttpServer(async (req, res) => {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id, Last-Event-ID');
+    // CORS: localhost 계열 Origin만 허용
+    const origin = req.headers['origin'];
+    if (isAllowedOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, mcp-session-id, Last-Event-ID');
+    }
 
     if (req.method === 'OPTIONS') {
-      res.writeHead(204);
+      res.writeHead(isAllowedOrigin(origin) ? 204 : 403);
       return res.end();
     }
 
@@ -141,6 +158,14 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
     if (req.url.startsWith('/bridge')) {
       res.setHeader('Content-Type', 'application/json');
 
+      // Bearer 토큰 인증
+      const authHeader = req.headers['authorization'] || '';
+      const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+      if (bearerToken !== HUB_TOKEN) {
+        res.writeHead(401);
+        return res.end(JSON.stringify({ ok: false, error: 'Unauthorized' }));
+      }
+
       if (req.method !== 'POST' && req.method !== 'DELETE') {
         res.writeHead(405);
         return res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
@@ -223,13 +248,13 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         if (req.method === 'POST') {
           let teamResult = null;
           if (path === '/bridge/team/info' || path === '/bridge/team-info') {
-            teamResult = teamInfo(body);
+            teamResult = await teamInfo(body);
           } else if (path === '/bridge/team/task-list' || path === '/bridge/team-task-list') {
-            teamResult = teamTaskList(body);
+            teamResult = await teamTaskList(body);
           } else if (path === '/bridge/team/task-update' || path === '/bridge/team-task-update') {
-            teamResult = teamTaskUpdate(body);
+            teamResult = await teamTaskUpdate(body);
           } else if (path === '/bridge/team/send-message' || path === '/bridge/team-send-message') {
-            teamResult = teamSendMessage(body);
+            teamResult = await teamSendMessage(body);
           }
 
           if (teamResult) {
@@ -452,6 +477,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         await pipe.stop();
         store.close();
         try { unlinkSync(PID_FILE); } catch {}
+        try { unlinkSync(TOKEN_FILE); } catch {}
         await new Promise((resolveClose) => httpServer.close(resolveClose));
       };
 

package/hub/team/native.mjs

@@ -8,6 +8,19 @@
 
 const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
 
+/**
+ * role/mcp_profile별 tfx-route.sh 기본 timeout (초)
+ * analyze/review 프로필이나 설계·분석 역할은 더 긴 timeout을 부여한다.
+ * @param {string} role — 워커 역할
+ * @param {string} mcpProfile — MCP 프로필
+ * @returns {number} timeout(초)
+ */
+function getRouteTimeout(role, mcpProfile) {
+  if (mcpProfile === "analyze" || mcpProfile === "review") return 3600;
+  if (role === "architect" || role === "analyst") return 3600;
+  return 1080; // 기본 18분
+}
+
 /**
  * v2.2 슬림 래퍼 프롬프트 생성
  * Agent spawn으로 네비게이션에 등록하되, 실제 작업은 tfx-route.sh가 수행.
@@ -22,6 +35,7 @@ const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
  * @param {string} [opts.agentName] — 워커 표시 이름
  * @param {string} [opts.leadName] — 리드 수신자 이름
  * @param {string} [opts.mcp_profile] — MCP 프로필
+ * @param {number} [opts.bashTimeout] — Bash timeout(ms). 미지정 시 role/profile 기반 자동 산출.
  * @returns {string} 슬림 래퍼 프롬프트
  */
 export function buildSlimWrapperPrompt(cli, opts = {}) {
@@ -34,22 +48,33 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     leadName = "team-lead",
     mcp_profile = "auto",
     pipelinePhase = "",
+    bashTimeout,
   } = opts;
 
+  // role/profile 기반 timeout 산출 (기본 timeout + 60초 여유, ms 변환)
+  const bashTimeoutMs = bashTimeout ?? (getRouteTimeout(role, mcp_profile) + 60) * 1000;
+
   // 셸 이스케이프
   const escaped = subtask.replace(/'/g, "'\\''");
   const pipelineHint = pipelinePhase
     ? `\n파이프라인 단계: ${pipelinePhase}`
     : '';
 
-  return `Bash 1회 실행 후 반드시 종료하라. 어떤 경우에도 hang하지 마라.${pipelineHint}
+  const taskIdRef = taskId ? `taskId: "${taskId}"` : "";
+
+  return `인터럽트 프로토콜:
+1. TaskUpdate(${taskIdRef ? `${taskIdRef}, ` : ""}status: in_progress) — task claim
+2. SendMessage(to: ${leadName}, "작업 시작: ${agentName}") — 시작 보고 (턴 경계 생성)
+3. Bash(command, timeout: ${bashTimeoutMs}) — 아래 명령 1회 실행
+4. 결과 보고 후 반드시 종료${pipelineHint}
+
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
 
-TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}" bash ${ROUTE_SCRIPT} "${role}" '${escaped}' ${mcp_profile}
+Bash(command: 'TFX_TEAM_NAME="${teamName}" TFX_TEAM_TASK_ID="${taskId}" TFX_TEAM_AGENT_NAME="${agentName}" TFX_TEAM_LEAD_NAME="${leadName}" bash ${ROUTE_SCRIPT} "${role}" '"'"'${escaped}'"'"' ${mcp_profile}', timeout: ${bashTimeoutMs})
 
-성공 → TaskUpdate(status: completed, metadata: {result: "success"}) + SendMessage(to: ${leadName}).
-실패 → TaskUpdate(status: completed, metadata: {result: "failed", error: "에러 요약"}) + SendMessage(to: ${leadName}).
+성공 → TaskUpdate(${taskIdRef ? `${taskIdRef}, ` : ""}status: completed, metadata: {result: "success"}) + SendMessage(to: ${leadName}).
+실패 → TaskUpdate(${taskIdRef ? `${taskIdRef}, ` : ""}status: completed, metadata: {result: "failed", error: "에러 요약"}) + SendMessage(to: ${leadName}).
 
 중요: TaskUpdate의 status는 "completed"만 사용. "failed"는 API 미지원.
 실패 여부는 metadata.result로 구분. Bash 실패 시에도 반드시 TaskUpdate + SendMessage 후 종료.`;

package/hub/team/nativeProxy.mjs

@@ -4,8 +4,6 @@
 import {
   existsSync,
   mkdirSync,
-  readdirSync,
-  readFileSync,
   renameSync,
   statSync,
   unlinkSync,
@@ -13,6 +11,7 @@ import {
   openSync,
   closeSync,
 } from 'node:fs';
+import { readdir, stat, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
@@ -25,6 +24,7 @@ const TASKS_ROOT = join(CLAUDE_HOME, 'tasks');
 // ── 인메모리 캐시 (디렉토리 mtime 기반 무효화) ──
 const _dirCache = new Map(); // tasksDir → { mtimeMs, files: string[] }
 const _taskIdIndex = new Map(); // taskId → filePath
+const _taskContentCache = new Map(); // filePath → { mtimeMs, data }
 
 function _invalidateCache(tasksDir) {
   _dirCache.delete(tasksDir);
@@ -40,9 +40,9 @@ function validateTeamName(teamName) {
   }
 }
 
-function readJsonSafe(path) {
+async function readJsonSafe(path) {
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    return JSON.parse(await readFile(path, 'utf8'));
   } catch {
     return null;
   }
@@ -66,12 +66,11 @@ function atomicWriteJson(path, value) {
   }
 }
 
-function sleepMs(ms) {
-  // busy-wait를 피하고 Atomics.wait로 동기 대기 (CPU 점유 최소화)
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+async function sleepMs(ms) {
+  return new Promise((r) => setTimeout(r, ms));
 }
 
-function withFileLock(lockPath, fn, retries = 20, delayMs = 25) {
+async function withFileLock(lockPath, fn, retries = 20, delayMs = 25) {
   let fd = null;
   for (let i = 0; i < retries; i += 1) {
     try {
@@ -79,12 +78,12 @@ function withFileLock(lockPath, fn, retries = 20, delayMs = 25) {
       break;
     } catch (e) {
       if (e?.code !== 'EEXIST' || i === retries - 1) throw e;
-      sleepMs(delayMs);
+      await sleepMs(delayMs);
     }
   }
 
   try {
-    return fn();
+    return await fn();
   } finally {
     try { if (fd != null) closeSync(fd); } catch {}
     try { unlinkSync(lockPath); } catch {}
@@ -99,13 +98,13 @@ function getLeadSessionId(config) {
     || null;
 }
 
-export function resolveTeamPaths(teamName) {
+export async function resolveTeamPaths(teamName) {
   validateTeamName(teamName);
 
   const teamDir = join(TEAMS_ROOT, teamName);
   const configPath = join(teamDir, 'config.json');
   const inboxesDir = join(teamDir, 'inboxes');
-  const config = readJsonSafe(configPath);
+  const config = await readJsonSafe(configPath);
   const leadSessionId = getLeadSessionId(config);
 
   const byTeam = join(TASKS_ROOT, teamName);
@@ -131,19 +130,20 @@ export function resolveTeamPaths(teamName) {
   };
 }
 
-function collectTaskFiles(tasksDir) {
+async function collectTaskFiles(tasksDir) {
   if (!existsSync(tasksDir)) return [];
 
   // 디렉토리 mtime 기반 캐시 — O(N) I/O를 반복 호출 시 O(1)로 축소
   let dirMtime;
-  try { dirMtime = statSync(tasksDir).mtimeMs; } catch { return []; }
+  try { dirMtime = (await stat(tasksDir)).mtimeMs; } catch { return []; }
 
   const cached = _dirCache.get(tasksDir);
   if (cached && cached.mtimeMs === dirMtime) {
     return cached.files;
   }
 
-  const files = readdirSync(tasksDir)
+  const entries = await readdir(tasksDir);
+  const files = entries
     .filter((name) => name.endsWith('.json'))
     .filter((name) => !name.endsWith('.lock'))
     .filter((name) => name !== '.highwatermark')
@@ -153,7 +153,7 @@ function collectTaskFiles(tasksDir) {
   return files;
 }
 
-function locateTaskFile(tasksDir, taskId) {
+async function locateTaskFile(tasksDir, taskId) {
   const direct = join(tasksDir, `${taskId}.json`);
   if (existsSync(direct)) return direct;
 
@@ -162,13 +162,13 @@ function locateTaskFile(tasksDir, taskId) {
   if (indexed && existsSync(indexed)) return indexed;
 
   // 캐시된 collectTaskFiles로 풀 스캔
-  const files = collectTaskFiles(tasksDir);
+  const files = await collectTaskFiles(tasksDir);
   for (const file of files) {
     if (basename(file, '.json') === taskId) {
       _taskIdIndex.set(taskId, file);
       return file;
     }
-    const json = readJsonSafe(file);
+    const json = await readJsonSafe(file);
     if (json && String(json.id || '') === taskId) {
       _taskIdIndex.set(taskId, file);
       return file;
@@ -181,7 +181,7 @@ function isObject(v) {
   return !!v && typeof v === 'object' && !Array.isArray(v);
 }
 
-export function teamInfo(args = {}) {
+export async function teamInfo(args = {}) {
   const { team_name, include_members = true, include_paths = true } = args;
   try {
     validateTeamName(team_name);
@@ -189,7 +189,7 @@ export function teamInfo(args = {}) {
     return err('INVALID_TEAM_NAME', 'team_name 형식이 올바르지 않습니다');
   }
 
-  const paths = resolveTeamPaths(team_name);
+  const paths = await resolveTeamPaths(team_name);
   if (!existsSync(paths.team_dir)) {
     return err('TEAM_NOT_FOUND', `팀 디렉토리가 없습니다: ${paths.team_dir}`);
   }
@@ -224,7 +224,7 @@ export function teamInfo(args = {}) {
   };
 }
 
-export function teamTaskList(args = {}) {
+export async function teamTaskList(args = {}) {
   const {
     team_name,
     owner,
@@ -239,7 +239,7 @@ export function teamTaskList(args = {}) {
     return err('INVALID_TEAM_NAME', 'team_name 형식이 올바르지 않습니다');
   }
 
-  const paths = resolveTeamPaths(team_name);
+  const paths = await resolveTeamPaths(team_name);
   if (paths.tasks_dir_resolution === 'not_found') {
     return err('TASKS_DIR_NOT_FOUND', `task 디렉토리를 찾지 못했습니다: ${team_name}`);
   }
@@ -249,8 +249,22 @@ export function teamTaskList(args = {}) {
   let parseWarnings = 0;
 
   const tasks = [];
-  for (const file of collectTaskFiles(paths.tasks_dir)) {
-    const json = readJsonSafe(file);
+  for (const file of await collectTaskFiles(paths.tasks_dir)) {
+    // mtime 기반 task 콘텐츠 캐시 — 변경 없으면 파일 읽기 생략
+    let fileMtime = Date.now();
+    try { fileMtime = (await stat(file)).mtimeMs; } catch {}
+
+    const contentCached = _taskContentCache.get(file);
+    let json;
+    if (contentCached && contentCached.mtimeMs === fileMtime) {
+      json = contentCached.data;
+    } else {
+      json = await readJsonSafe(file);
+      if (json && isObject(json)) {
+        _taskContentCache.set(file, { mtimeMs: fileMtime, data: json });
+      }
+    }
+
     if (!json || !isObject(json)) {
       parseWarnings += 1;
       continue;
@@ -260,13 +274,10 @@ export function teamTaskList(args = {}) {
     if (owner && String(json.owner || '') !== String(owner)) continue;
     if (statusSet.size > 0 && !statusSet.has(String(json.status || ''))) continue;
 
-    let mtime = Date.now();
-    try { mtime = statSync(file).mtimeMs; } catch {}
-
     tasks.push({
       ...json,
       task_file: file,
-      mtime_ms: mtime,
+      mtime_ms: fileMtime,
     });
   }
 
@@ -288,7 +299,7 @@ export function teamTaskList(args = {}) {
 // status 화이트리스트 (Claude Code API 호환)
 const VALID_STATUSES = new Set(['pending', 'in_progress', 'completed', 'deleted']);
 
-export function teamTaskUpdate(args = {}) {
+export async function teamTaskUpdate(args = {}) {
   // "failed" → "completed" + metadata.result 자동 매핑
   if (String(args.status || '') === 'failed') {
     args = {
@@ -326,12 +337,12 @@ export function teamTaskUpdate(args = {}) {
     return err('INVALID_TASK_ID', 'task_id가 필요합니다');
   }
 
-  const paths = resolveTeamPaths(team_name);
+  const paths = await resolveTeamPaths(team_name);
   if (paths.tasks_dir_resolution === 'not_found') {
     return err('TASKS_DIR_NOT_FOUND', `task 디렉토리를 찾지 못했습니다: ${team_name}`);
   }
 
-  const taskFile = locateTaskFile(paths.tasks_dir, String(task_id));
+  const taskFile = await locateTaskFile(paths.tasks_dir, String(task_id));
   if (!taskFile) {
     return err('TASK_NOT_FOUND', `task를 찾지 못했습니다: ${task_id}`);
   }
@@ -339,14 +350,14 @@ export function teamTaskUpdate(args = {}) {
   const lockFile = `${taskFile}.lock`;
 
   try {
-    return withFileLock(lockFile, () => {
-      const before = readJsonSafe(taskFile);
+    return await withFileLock(lockFile, async () => {
+      const before = await readJsonSafe(taskFile);
       if (!before || !isObject(before)) {
         return err('INVALID_TASK_FILE', `task 파일 파싱 실패: ${taskFile}`);
       }
 
       let beforeMtime = Date.now();
-      try { beforeMtime = statSync(taskFile).mtimeMs; } catch {}
+      try { beforeMtime = (await stat(taskFile)).mtimeMs; } catch {}
 
       if (if_match_mtime_ms != null && Number(if_match_mtime_ms) !== Number(beforeMtime)) {
         return err('MTIME_CONFLICT', 'if_match_mtime_ms가 일치하지 않습니다', {
@@ -427,6 +438,8 @@ export function teamTaskUpdate(args = {}) {
       if (updated) {
         atomicWriteJson(taskFile, after);
         _invalidateCache(dirname(taskFile));
+        // 콘텐츠 캐시 무효화
+        _taskContentCache.delete(taskFile);
       }
 
       let afterMtime = beforeMtime;
@@ -453,7 +466,7 @@ function sanitizeRecipientName(v) {
   return String(v || 'team-lead').replace(/[\\/:*?"<>|]/g, '_');
 }
 
-export function teamSendMessage(args = {}) {
+export async function teamSendMessage(args = {}) {
   const {
     team_name,
     from,
@@ -472,7 +485,7 @@ export function teamSendMessage(args = {}) {
   if (!String(from || '').trim()) return err('INVALID_FROM', 'from이 필요합니다');
   if (!String(text || '').trim()) return err('INVALID_TEXT', 'text가 필요합니다');
 
-  const paths = resolveTeamPaths(team_name);
+  const paths = await resolveTeamPaths(team_name);
   if (!existsSync(paths.team_dir)) {
     return err('TEAM_NOT_FOUND', `팀 디렉토리가 없습니다: ${paths.team_dir}`);
   }
@@ -483,8 +496,8 @@ export function teamSendMessage(args = {}) {
   let message;
 
   try {
-    const unreadCount = withFileLock(lockFile, () => {
-      const queue = readJsonSafe(inboxFile);
+    const unreadCount = await withFileLock(lockFile, async () => {
+      const queue = await readJsonSafe(inboxFile);
       const list = Array.isArray(queue) ? queue : [];
 
       message = {

package/hub/team/psmux.mjs

@@ -295,3 +295,188 @@ export function configurePsmuxKeybindings(sessionName, opts = {}) {
     );
   }
 }
+
+// ─── 하이브리드 모드 워커 관리 함수 ───
+
+/**
+ * psmux 세션의 새 pane에서 워커 실행
+ * @param {string} sessionName - 대상 psmux 세션 이름
+ * @param {string} workerName - 워커 식별용 pane 타이틀
+ * @param {string} cmd - 실행할 커맨드
+ * @returns {{ paneId: string, workerName: string }}
+ */
+export function spawnWorker(sessionName, workerName, cmd) {
+  if (!hasPsmux()) {
+    throw new Error("psmux가 설치되어 있지 않습니다. psmux를 먼저 설치하세요.");
+  }
+  try {
+    const paneId = psmuxExec(
+      `split-window -t ${quoteArg(sessionName)} -P -F "#{pane_id}" ${quoteArg(cmd)}`
+    );
+    psmuxExec(`select-pane -t ${quoteArg(paneId)} -T ${quoteArg(workerName)}`);
+    return { paneId, workerName };
+  } catch (err) {
+    throw new Error(`워커 생성 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+  }
+}
+
+/**
+ * 워커 pane 실행 상태 확인
+ * @param {string} sessionName - 대상 psmux 세션 이름
+ * @param {string} workerName - 워커 pane 타이틀
+ * @returns {{ status: "running"|"exited", exitCode: number|null, paneId: string }}
+ */
+export function getWorkerStatus(sessionName, workerName) {
+  if (!hasPsmux()) {
+    throw new Error("psmux가 설치되어 있지 않습니다.");
+  }
+  try {
+    const output = psmuxExec(
+      `list-panes -t ${quoteArg(sessionName)} -F "#{pane_title}\t#{pane_id}\t#{pane_dead}\t#{pane_dead_status}"`
+    );
+    const lines = output.split("\n").filter(Boolean);
+    for (const line of lines) {
+      const [title, paneId, dead, deadStatus] = line.split("\t");
+      if (title === workerName) {
+        const isDead = dead === "1";
+        return {
+          status: isDead ? "exited" : "running",
+          exitCode: isDead ? parseInt(deadStatus, 10) || 0 : null,
+          paneId,
+        };
+      }
+    }
+    throw new Error(`워커를 찾을 수 없습니다: ${workerName}`);
+  } catch (err) {
+    if (err.message.includes("워커를 찾을 수 없습니다")) throw err;
+    throw new Error(`워커 상태 조회 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+  }
+}
+
+/**
+ * 워커 pane 프로세스 강제 종료
+ * @param {string} sessionName - 대상 psmux 세션 이름
+ * @param {string} workerName - 워커 pane 타이틀
+ * @returns {{ killed: boolean }}
+ */
+export function killWorker(sessionName, workerName) {
+  if (!hasPsmux()) {
+    throw new Error("psmux가 설치되어 있지 않습니다.");
+  }
+  try {
+    // paneId 찾기
+    const { paneId } = getWorkerStatus(sessionName, workerName);
+    // C-c로 우아한 종료 시도
+    try {
+      psmuxExec(`send-keys -t ${quoteArg(paneId)} C-c`);
+    } catch {
+      // send-keys 실패 무시
+    }
+    // 1초 대기 후 pane 강제 종료
+    spawnSync("sleep", ["1"], { stdio: "ignore", windowsHide: true });
+    try {
+      psmuxExec(`kill-pane -t ${quoteArg(paneId)}`);
+    } catch {
+      // 이미 종료된 pane — 무시
+    }
+    return { killed: true };
+  } catch (err) {
+    if (err.message.includes("워커를 찾을 수 없습니다")) {
+      return { killed: false };
+    }
+    throw new Error(`워커 종료 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+  }
+}
+
+/**
+ * 워커 pane 출력 마지막 N줄 캡처
+ * @param {string} sessionName - 대상 psmux 세션 이름
+ * @param {string} workerName - 워커 pane 타이틀
+ * @param {number} lines - 캡처할 줄 수 (기본 50)
+ * @returns {string} 캡처된 출력
+ */
+export function captureWorkerOutput(sessionName, workerName, lines = 50) {
+  if (!hasPsmux()) {
+    throw new Error("psmux가 설치되어 있지 않습니다.");
+  }
+  try {
+    const { paneId } = getWorkerStatus(sessionName, workerName);
+    return psmuxExec(`capture-pane -t ${quoteArg(paneId)} -p -S -${lines}`);
+  } catch (err) {
+    if (err.message.includes("워커를 찾을 수 없습니다")) throw err;
+    throw new Error(`출력 캡처 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+  }
+}
+
+// ─── CLI 진입점 ───
+
+if (process.argv[1] && process.argv[1].endsWith("psmux.mjs")) {
+  const [,, cmd, ...args] = process.argv;
+
+  // CLI 인자 파싱 헬퍼
+  function getArg(name) {
+    const idx = args.indexOf(`--${name}`);
+    return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+  }
+
+  try {
+    switch (cmd) {
+      case "spawn": {
+        const session = getArg("session");
+        const name = getArg("name");
+        const workerCmd = getArg("cmd");
+        if (!session || !name || !workerCmd) {
+          console.error("사용법: node psmux.mjs spawn --session <세션> --name <워커명> --cmd <커맨드>");
+          process.exit(1);
+        }
+        const result = spawnWorker(session, name, workerCmd);
+        console.log(JSON.stringify(result, null, 2));
+        break;
+      }
+      case "status": {
+        const session = getArg("session");
+        const name = getArg("name");
+        if (!session || !name) {
+          console.error("사용법: node psmux.mjs status --session <세션> --name <워커명>");
+          process.exit(1);
+        }
+        const result = getWorkerStatus(session, name);
+        console.log(JSON.stringify(result, null, 2));
+        break;
+      }
+      case "kill": {
+        const session = getArg("session");
+        const name = getArg("name");
+        if (!session || !name) {
+          console.error("사용법: node psmux.mjs kill --session <세션> --name <워커명>");
+          process.exit(1);
+        }
+        const result = killWorker(session, name);
+        console.log(JSON.stringify(result, null, 2));
+        break;
+      }
+      case "output": {
+        const session = getArg("session");
+        const name = getArg("name");
+        const lines = parseInt(getArg("lines") || "50", 10);
+        if (!session || !name) {
+          console.error("사용법: node psmux.mjs output --session <세션> --name <워커명> [--lines <줄수>]");
+          process.exit(1);
+        }
+        console.log(captureWorkerOutput(session, name, lines));
+        break;
+      }
+      default:
+        console.error("사용법: node psmux.mjs spawn|status|kill|output [args]");
+        console.error("");
+        console.error("  spawn   --session <세션> --name <워커명> --cmd <커맨드>");
+        console.error("  status  --session <세션> --name <워커명>");
+        console.error("  kill    --session <세션> --name <워커명>");
+        console.error("  output  --session <세션> --name <워커명> [--lines <줄수>]");
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`오류: ${err.message}`);
+    process.exit(1);
+  }
+}

package/package.json

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

package/scripts/preflight-cache.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// scripts/preflight-cache.mjs — 세션 시작 시 preflight 점검 캐싱
+
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+
+const CACHE_DIR = join(homedir(), ".claude", "cache");
+const CACHE_FILE = join(CACHE_DIR, "tfx-preflight.json");
+const CACHE_TTL_MS = 30_000; // 30초
+
+function checkHub() {
+  try {
+    const res = execSync("curl -sf http://127.0.0.1:27888/status", { timeout: 3000, encoding: "utf8" });
+    const data = JSON.parse(res);
+    return { ok: true, state: data?.hub?.state || "unknown", pid: data?.pid };
+  } catch {
+    return { ok: false, state: "unreachable" };
+  }
+}
+
+function checkRoute() {
+  const routePath = join(homedir(), ".claude", "scripts", "tfx-route.sh");
+  return { ok: existsSync(routePath), path: routePath };
+}
+
+function checkCli(name) {
+  try {
+    const path = execSync(`which ${name} 2>/dev/null || where ${name} 2>nul`, { encoding: "utf8", timeout: 2000 }).trim();
+    return { ok: !!path, path };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function runPreflight() {
+  const result = {
+    timestamp: Date.now(),
+    hub: checkHub(),
+    route: checkRoute(),
+    codex: checkCli("codex"),
+    gemini: checkCli("gemini"),
+    ok: false,
+  };
+  result.ok = result.hub.ok && result.route.ok;
+  return result;
+}
+
+// 캐시 읽기 (TTL 검증 포함)
+export function readPreflightCache() {
+  try {
+    const data = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+    if (Date.now() - data.timestamp < CACHE_TTL_MS) return data;
+  } catch {}
+  return null;
+}
+
+// 메인 실행
+if (process.argv[1]?.endsWith("preflight-cache.mjs")) {
+  const result = runPreflight();
+  mkdirSync(CACHE_DIR, { recursive: true });
+  writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2));
+  // 간결 출력 (hook stdout)
+  const summary = result.ok ? "preflight: ok" : "preflight: FAIL";
+  const details = [];
+  if (!result.hub.ok) details.push("hub:" + result.hub.state);
+  if (!result.route.ok) details.push("route:missing");
+  console.log(details.length ? `${summary} (${details.join(", ")})` : summary);
+}
+
+export { runPreflight, CACHE_FILE, CACHE_TTL_MS };

package/skills/tfx-multi/SKILL.md

@@ -192,8 +192,23 @@ status는 "completed"만 사용. 실패 여부는 `metadata.result`로 구분.
 > Windows 호환 경로, 타임아웃, 후처리(토큰 추적/이슈 로깅)가 모두 누락된다.
 > 반드시 `bash ~/.claude/scripts/tfx-route.sh {role} '{subtask}' {mcp_profile}`을 통해 실행해야 한다.
 
+**Bash timeout 동적 상속:** Bash timeout은 tfx-route.sh의 role/profile별 timeout + 60초 여유를 ms로 변환하여 동적 상속한다. `getRouteTimeout(role, mcpProfile)` 기준: analyze/review 프로필 또는 architect/analyst 역할은 3600초, 그 외 기본 1080초(18분).
+
 **핵심 차이 vs v2:** 프롬프트 ~100 토큰 (v2의 ~500), task claim/complete/report는 tfx-route.sh가 Named Pipe(우선)/HTTP(fallback) 경유로 수행.
 
+#### 인터럽트 프로토콜
+
+워커가 Bash 실행 전에 SendMessage로 시작을 보고하면 턴 경계가 생겨 리드가 방향 전환 메시지를 보낼 수 있다.
+
+```
+1. TaskUpdate(taskId, status: in_progress) — task claim
+2. SendMessage(to: team-lead, "작업 시작: {agentName}") — 시작 보고 (턴 경계 생성)
+3. Bash(command: tfx-route.sh ..., timeout: {bashTimeoutMs}) — 1회 실행
+4. TaskUpdate(status: completed, metadata: {result}) + SendMessage → 종료
+```
+
+리드는 워커의 Step 2 시점에 턴 경계를 인식하고, 필요 시 방향 전환/중단 메시지를 보낼 수 있다.
+
 `tfx-route.sh` 팀 통합 동작(이미 구현됨, `TFX_TEAM_*` 기반):
 - `TFX_TEAM_NAME`: 팀 식별자
 - `TFX_TEAM_TASK_ID`: 작업 식별자
@@ -235,8 +250,7 @@ Agent({
 ```
 "팀 '{teamName}' 생성 완료.
 Codex/Gemini 워커가 슬림 래퍼 Agent로 네비게이션에 등록되었습니다.
-Shift+Down으로 다음 워커 (마지막→리드 wrap), Shift+Tab으로 이전 워커 전환이 가능합니다.
-(Shift+Up은 Claude Code 미지원 — 대부분 터미널에서 scroll-up으로 먹힘)"
+Shift+Down으로 다음 워커로 전환 (마지막→리드 wrap). Shift+Tab으로 이전 워커 전환."
 ```
 
 ### Phase 3.5–3.7: Verify/Fix Loop (`--thorough` 전용)