triflux 3.3.0-dev.5 → 3.3.0-dev.7

package/bin/triflux.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // triflux CLI — setup, doctor, version
-import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, rmSync, statSync } from "fs";
+import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, rmSync, statSync, openSync, closeSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { execSync, execFileSync, spawn } from "child_process";
@@ -1408,7 +1408,25 @@ function stopHubForUpdate() {
     try { process.kill(info.pid, "SIGKILL"); } catch {}
   }
 
-  sleepMs(300);
+  // Windows에서 better-sqlite3.node 파일 핸들 해제 대기
+  // taskkill 후 프로세스 종료 + 파일 핸들 해제까지 최대 5초
+  const sqliteNode = join(PKG_ROOT, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node");
+  for (let i = 0; i < 10; i++) {
+    sleepMs(500);
+    try { process.kill(info.pid, 0); } catch { break; }
+  }
+  // 파일 잠금 해제 확인 (Windows EBUSY 방지)
+  if (existsSync(sqliteNode)) {
+    for (let i = 0; i < 6; i++) {
+      try {
+        const fd = openSync(sqliteNode, "r");
+        closeSync(fd);
+        break;
+      } catch {
+        sleepMs(500);
+      }
+    }
+  }
   try { unlinkSync(HUB_PID_FILE); } catch {}
   return info;
 }

package/hub/bridge.mjs

@@ -14,13 +14,18 @@ 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');
 
+function normalizeToken(raw) {
+  if (raw == null) return null;
+  const token = String(raw).trim();
+  return token || null;
+}
+
 // Hub 인증 토큰 읽기 (파일 없으면 null → 하위 호환)
 function readHubToken() {
-  if (process.env.TFX_HUB_TOKEN) {
-    return String(process.env.TFX_HUB_TOKEN).trim();
-  }
+  const envToken = normalizeToken(process.env.TFX_HUB_TOKEN);
+  if (envToken) return envToken;
   try {
-    return readFileSync(HUB_TOKEN_FILE, 'utf8').trim();
+    return normalizeToken(readFileSync(HUB_TOKEN_FILE, 'utf8'));
   } catch {
     return null;
   }

package/hub/server.mjs

@@ -16,13 +16,17 @@ import { createPipeServer } from './pipe.mjs';
 import { createAssignCallbackServer } from './assign-callbacks.mjs';
 import { createTools } from './tools.mjs';
 
+const MAX_BODY_SIZE = 1024 * 1024;
+const PUBLIC_PATHS = new Set(['/', '/status', '/health', '/healthz']);
+const LOOPBACK_REMOTE_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+const ALLOWED_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+
 function isInitializeRequest(body) {
   if (body?.method === 'initialize') return true;
   if (Array.isArray(body)) return body.some((message) => message.method === 'initialize');
   return false;
 }
 
-const MAX_BODY_SIZE = 1024 * 1024;
 async function parseBody(req) {
   const chunks = [];
   let size = 0;
@@ -40,13 +44,56 @@ 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);
 }
 
+function getRequestPath(url = '/') {
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname;
+  } catch {
+    return String(url).replace(/\?.*/, '') || '/';
+  }
+}
+
+function isLoopbackRemoteAddress(remoteAddress) {
+  return typeof remoteAddress === 'string' && LOOPBACK_REMOTE_ADDRESSES.has(remoteAddress);
+}
+
+function extractBearerToken(req) {
+  const authHeader = typeof req.headers.authorization === 'string' ? req.headers.authorization : '';
+  return authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+}
+
+function writeJson(res, statusCode, body, headers = {}) {
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json',
+    ...headers,
+  });
+  res.end(JSON.stringify(body));
+}
+
+function applyCorsHeaders(req, res) {
+  const origin = typeof req.headers.origin === 'string' ? req.headers.origin : '';
+  if (origin) {
+    res.setHeader('Vary', 'Origin');
+  }
+  if (!isAllowedOrigin(origin)) return false;
+
+  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');
+  return true;
+}
+
+function isAuthorizedRequest(req, path, hubToken) {
+  if (!hubToken) {
+    return isLoopbackRemoteAddress(req.socket.remoteAddress);
+  }
+  if (PUBLIC_PATHS.has(path)) return true;
+  return extractBearerToken(req) === hubToken;
+}
+
 function resolveTeamStatusCode(result) {
   if (result?.ok) return 200;
   const code = result?.error?.code;
@@ -76,10 +123,13 @@ 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 HUB_TOKEN = process.env.TFX_HUB_TOKEN?.trim() || null;
+  if (HUB_TOKEN) {
+    mkdirSync(join(homedir(), '.claude'), { recursive: true });
+    writeFileSync(TOKEN_FILE, HUB_TOKEN, { mode: 0o600 });
+  } else {
+    try { unlinkSync(TOKEN_FILE); } catch {}
+  }
 
   const store = createStore(dbPath);
   const router = createRouter(store);
@@ -125,66 +175,61 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
   }
 
   const httpServer = createHttpServer(async (req, res) => {
-    // 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');
-    }
+    const path = getRequestPath(req.url);
+    const corsAllowed = applyCorsHeaders(req, res);
 
     if (req.method === 'OPTIONS') {
-      res.writeHead(isAllowedOrigin(origin) ? 204 : 403);
+      const localOnlyMode = !HUB_TOKEN;
+      const isLoopbackRequest = isLoopbackRemoteAddress(req.socket.remoteAddress);
+      res.writeHead(corsAllowed && (!localOnlyMode || isLoopbackRequest) ? 204 : 403);
       return res.end();
     }
 
-    if (req.url === '/' || req.url === '/status') {
+    if (!isAuthorizedRequest(req, path, HUB_TOKEN)) {
+      if (!HUB_TOKEN) {
+        return writeJson(res, 403, { ok: false, error: 'Forbidden: localhost only' });
+      }
+      return writeJson(
+        res,
+        401,
+        { ok: false, error: 'Unauthorized' },
+        { 'WWW-Authenticate': 'Bearer realm="tfx-hub"' },
+      );
+    }
+
+    if (path === '/' || path === '/status') {
       const status = router.getStatus('hub').data;
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      return res.end(JSON.stringify({
+      return writeJson(res, 200, {
         ...status,
         sessions: transports.size,
         pid: process.pid,
         port,
+        auth_mode: HUB_TOKEN ? 'token-required' : 'localhost-only',
         pipe_path: pipe.path,
         pipe: pipe.getStatus(),
         assign_callback_pipe_path: assignCallbacks.path,
         assign_callback_pipe: assignCallbacks.getStatus(),
-      }));
+      });
     }
 
-    if (req.url === '/health' || req.url === '/healthz') {
+    if (path === '/health' || path === '/healthz') {
       const status = router.getStatus('hub').data;
       const healthy = status?.hub?.state === 'healthy';
-      res.writeHead(healthy ? 200 : 503, { 'Content-Type': 'application/json' });
-      return res.end(JSON.stringify({ ok: healthy }));
+      return writeJson(res, healthy ? 200 : 503, { ok: healthy });
     }
 
-    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 (path.startsWith('/bridge')) {
       if (req.method !== 'POST' && req.method !== 'DELETE') {
-        res.writeHead(405);
-        return res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed' }));
+        return writeJson(res, 405, { ok: false, error: 'Method Not Allowed' });
       }
 
       try {
         const body = req.method === 'POST' ? await parseBody(req) : {};
-        const path = req.url.replace(/\?.*/, '');
 
         if (path === '/bridge/register' && req.method === 'POST') {
           const { agent_id, cli, timeout_sec = 600, topics = [], capabilities = [], metadata = {} } = body;
           if (!agent_id || !cli) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'agent_id, cli 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'agent_id, cli 필수' });
           }
 
           const heartbeat_ttl_ms = (timeout_sec + 120) * 1000;
@@ -196,15 +241,13 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             heartbeat_ttl_ms,
             metadata,
           });
-          res.writeHead(200);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, 200, result);
         }
 
         if (path === '/bridge/result' && req.method === 'POST') {
           const { agent_id, topic = 'task.result', payload = {}, trace_id, correlation_id } = body;
           if (!agent_id) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'agent_id 필수' });
           }
 
           const result = await pipe.executeCommand('result', {
@@ -214,8 +257,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             trace_id,
             correlation_id,
           });
-          res.writeHead(200);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, 200, result);
         }
 
         if (path === '/bridge/control' && req.method === 'POST') {
@@ -231,8 +273,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
           } = body;
 
           if (!to_agent || !command) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'to_agent, command 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'to_agent, command 필수' });
           }
 
           const result = await pipe.executeCommand('control', {
@@ -246,8 +287,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             correlation_id,
           });
 
-          res.writeHead(200);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, 200, result);
         }
 
         if (path === '/bridge/assign/async' && req.method === 'POST') {
@@ -266,8 +306,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
           } = body;
 
           if (!supervisor_agent || !worker_agent || !task) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'supervisor_agent, worker_agent, task 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'supervisor_agent, worker_agent, task 필수' });
           }
 
           const result = await pipe.executeCommand('assign', {
@@ -283,8 +322,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             trace_id,
             correlation_id,
           });
-          res.writeHead(result.ok ? 200 : 400);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, result.ok ? 200 : 400, result);
         }
 
         if (path === '/bridge/assign/result' && req.method === 'POST') {
@@ -300,8 +338,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
           } = body;
 
           if (!job_id || !status) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'job_id, status 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'job_id, status 필수' });
           }
 
           const result = await pipe.executeCommand('assign_result', {
@@ -314,22 +351,19 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             payload,
             metadata,
           });
-          res.writeHead(result.ok ? 200 : 409);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, result.ok ? 200 : 409, result);
         }
 
         if (path === '/bridge/assign/status' && req.method === 'POST') {
           const result = await pipe.executeQuery('assign_status', body);
           const statusCode = result.ok ? 200 : (result.error?.code === 'ASSIGN_NOT_FOUND' ? 404 : 400);
-          res.writeHead(statusCode);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, statusCode, result);
         }
 
         if (path === '/bridge/assign/retry' && req.method === 'POST') {
           const { job_id, reason, requested_by } = body;
           if (!job_id) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'job_id 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'job_id 필수' });
           }
 
           const result = await pipe.executeCommand('assign_retry', {
@@ -341,8 +375,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             : result.error?.code === 'ASSIGN_NOT_FOUND' ? 404
               : result.error?.code === 'ASSIGN_RETRY_EXHAUSTED' ? 409
                 : 400;
-          res.writeHead(statusCode);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, statusCode, result);
         }
 
         if (req.method === 'POST') {
@@ -358,46 +391,39 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
           }
 
           if (teamResult) {
-            res.writeHead(resolveTeamStatusCode(teamResult));
-            return res.end(JSON.stringify(teamResult));
+            return writeJson(res, resolveTeamStatusCode(teamResult), teamResult);
           }
 
           if (path.startsWith('/bridge/team')) {
-            res.writeHead(404);
-            return res.end(JSON.stringify({ ok: false, error: `Unknown team endpoint: ${path}` }));
+            return writeJson(res, 404, { ok: false, error: `Unknown team endpoint: ${path}` });
           }
 
           // ── 파이프라인 엔드포인트 ──
           if (path === '/bridge/pipeline/state' && req.method === 'POST') {
             const result = await pipe.executeQuery('pipeline_state', body);
-            res.writeHead(resolvePipelineStatusCode(result));
-            return res.end(JSON.stringify(result));
+            return writeJson(res, resolvePipelineStatusCode(result), result);
           }
 
           if (path === '/bridge/pipeline/advance' && req.method === 'POST') {
             const result = await pipe.executeCommand('pipeline_advance', body);
-            res.writeHead(resolvePipelineStatusCode(result));
-            return res.end(JSON.stringify(result));
+            return writeJson(res, resolvePipelineStatusCode(result), result);
           }
 
           if (path === '/bridge/pipeline/init' && req.method === 'POST') {
             const result = await pipe.executeCommand('pipeline_init', body);
-            res.writeHead(resolvePipelineStatusCode(result));
-            return res.end(JSON.stringify(result));
+            return writeJson(res, resolvePipelineStatusCode(result), result);
           }
 
           if (path === '/bridge/pipeline/list' && req.method === 'POST') {
             const result = await pipe.executeQuery('pipeline_list', body);
-            res.writeHead(resolvePipelineStatusCode(result));
-            return res.end(JSON.stringify(result));
+            return writeJson(res, resolvePipelineStatusCode(result), result);
           }
         }
 
         if (path === '/bridge/context' && req.method === 'POST') {
           const { agent_id, topics, max_messages = 10, auto_ack = true } = body;
           if (!agent_id) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'agent_id 필수' });
           }
 
           const result = await pipe.executeQuery('drain', {
@@ -406,33 +432,28 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
             max_messages,
             auto_ack,
           });
-          res.writeHead(200);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, 200, result);
         }
 
         if (path === '/bridge/deregister' && req.method === 'POST') {
           const { agent_id } = body;
           if (!agent_id) {
-            res.writeHead(400);
-            return res.end(JSON.stringify({ ok: false, error: 'agent_id 필수' }));
+            return writeJson(res, 400, { ok: false, error: 'agent_id 필수' });
           }
           const result = await pipe.executeCommand('deregister', { agent_id });
-          res.writeHead(200);
-          return res.end(JSON.stringify(result));
+          return writeJson(res, 200, result);
         }
 
-        res.writeHead(404);
-        return res.end(JSON.stringify({ ok: false, error: 'Unknown bridge endpoint' }));
+        return writeJson(res, 404, { ok: false, error: 'Unknown bridge endpoint' });
       } catch (error) {
         if (!res.headersSent) {
-          res.writeHead(500);
-          res.end(JSON.stringify({ ok: false, error: error.message }));
+          writeJson(res, 500, { ok: false, error: error.message });
         }
         return;
       }
     }
 
-    if (req.url !== '/mcp') {
+    if (path !== '/mcp') {
       res.writeHead(404);
       return res.end('Not Found');
     }
@@ -534,6 +555,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         dbPath,
         pid: process.pid,
         hubToken: HUB_TOKEN,
+        authMode: HUB_TOKEN ? 'token-required' : 'localhost-only',
         url: `http://${host}:${port}/mcp`,
         pipe_path: pipe.path,
         pipePath: pipe.path,
@@ -545,6 +567,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         pid: process.pid,
         port,
         host,
+        auth_mode: HUB_TOKEN ? 'token-required' : 'localhost-only',
         url: info.url,
         pipe_path: pipe.path,
         pipePath: pipe.path,

package/hub/team/nativeProxy.mjs

@@ -1,25 +1,29 @@
 // hub/team/nativeProxy.mjs
 // Claude Native Teams 파일을 Hub tool/REST에서 안전하게 읽고 쓰기 위한 유틸.
 
-import {
-  existsSync,
-  mkdirSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-  openSync,
-  closeSync,
-} from 'node:fs';
-import { readdir, stat, readFile } from 'node:fs/promises';
+import {
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import {
+  open as openFile,
+  readdir,
+  readFile,
+  stat,
+  unlink as unlinkFile,
+} from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 
 const TEAM_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 const CLAUDE_HOME = join(homedir(), '.claude');
-const TEAMS_ROOT = join(CLAUDE_HOME, 'teams');
-const TASKS_ROOT = join(CLAUDE_HOME, 'tasks');
+const TEAMS_ROOT = join(CLAUDE_HOME, 'teams');
+const TASKS_ROOT = join(CLAUDE_HOME, 'tasks');
+const LOCK_STALE_MS = 30000;
 
 // ── 인메모리 캐시 (디렉토리 mtime 기반 무효화) ──
 const _dirCache = new Map(); // tasksDir → { mtimeMs, files: string[] }
@@ -66,29 +70,118 @@ function atomicWriteJson(path, value) {
   }
 }
 
-async function sleepMs(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-async function withFileLock(lockPath, fn, retries = 20, delayMs = 25) {
-  let fd = null;
-  for (let i = 0; i < retries; i += 1) {
-    try {
-      fd = openSync(lockPath, 'wx');
-      break;
-    } catch (e) {
-      if (e?.code !== 'EEXIST' || i === retries - 1) throw e;
-      await sleepMs(delayMs);
-    }
-  }
-
-  try {
-    return await fn();
-  } finally {
-    try { if (fd != null) closeSync(fd); } catch {}
-    try { unlinkSync(lockPath); } catch {}
-  }
-}
+async function sleepMs(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function readLockInfo(lockPath) {
+  let lockStat;
+  try {
+    lockStat = await stat(lockPath);
+  } catch {
+    return null;
+  }
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(await readFile(lockPath, 'utf8'));
+  } catch {}
+
+  const now = Date.now();
+  const createdAtMs = Number(
+    parsed?.created_at_ms
+    ?? parsed?.timestamp_ms
+    ?? parsed?.timestamp
+    ?? lockStat.mtimeMs,
+  );
+  const pid = Number(parsed?.pid);
+
+  return {
+    token: typeof parsed?.token === 'string' ? parsed.token : null,
+    pid: Number.isInteger(pid) && pid > 0 ? pid : null,
+    created_at_ms: Number.isFinite(createdAtMs) ? createdAtMs : lockStat.mtimeMs,
+    mtime_ms: lockStat.mtimeMs,
+    age_ms: Math.max(0, now - (Number.isFinite(createdAtMs) ? createdAtMs : lockStat.mtimeMs)),
+  };
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    if (e?.code === 'EPERM') return true;
+    if (e?.code === 'ESRCH') return false;
+    return false;
+  }
+}
+
+async function releaseFileLock(lockPath, token, handle) {
+  try { await handle?.close(); } catch {}
+
+  try {
+    const current = await readLockInfo(lockPath);
+    if (!current || current.token === token) {
+      await unlinkFile(lockPath);
+    }
+  } catch {}
+}
+
+async function withFileLock(lockPath, fn, retries = 20, delayMs = 25, staleMs = LOCK_STALE_MS) {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const lockOwner = {
+    pid: process.pid,
+    token: randomUUID(),
+    created_at: new Date().toISOString(),
+    created_at_ms: Date.now(),
+  };
+  let handle = null;
+  let lastError = null;
+
+  for (let i = 0; i < retries; i += 1) {
+    try {
+      handle = await openFile(lockPath, 'wx');
+      try {
+        await handle.writeFile(`${JSON.stringify(lockOwner)}\n`, 'utf8');
+      } catch (writeError) {
+        await releaseFileLock(lockPath, lockOwner.token, handle);
+        throw writeError;
+      }
+      break;
+    } catch (e) {
+      lastError = e;
+      if (e?.code !== 'EEXIST') throw e;
+
+      const current = await readLockInfo(lockPath);
+      const staleByAge = !current || current.age_ms > staleMs;
+      const staleByDeadPid = current?.pid != null && !isPidAlive(current.pid);
+      if (staleByAge || staleByDeadPid) {
+        try {
+          await unlinkFile(lockPath);
+          continue;
+        } catch (unlinkError) {
+          if (unlinkError?.code === 'ENOENT') continue;
+          lastError = unlinkError;
+        }
+      }
+
+      if (i === retries - 1) throw e;
+      await sleepMs(delayMs);
+    }
+  }
+
+  if (!handle) {
+    throw lastError || new Error(`LOCK_NOT_ACQUIRED: ${lockPath}`);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await releaseFileLock(lockPath, lockOwner.token, handle);
+  }
+}
 
 function getLeadSessionId(config) {
   return config?.leadSessionId
@@ -130,8 +223,8 @@ export async function resolveTeamPaths(teamName) {
   };
 }
 
-async function collectTaskFiles(tasksDir) {
-  if (!existsSync(tasksDir)) return [];
+async function collectTaskFiles(tasksDir) {
+  if (!existsSync(tasksDir)) return [];
 
   // 디렉토리 mtime 기반 캐시 — O(N) I/O를 반복 호출 시 O(1)로 축소
   let dirMtime;
@@ -149,9 +242,30 @@ async function collectTaskFiles(tasksDir) {
     .filter((name) => name !== '.highwatermark')
     .map((name) => join(tasksDir, name));
 
-  _dirCache.set(tasksDir, { mtimeMs: dirMtime, files });
-  return files;
-}
+  _dirCache.set(tasksDir, { mtimeMs: dirMtime, files });
+  return files;
+}
+
+async function readTaskFileCached(file) {
+  let fileMtime;
+  try {
+    fileMtime = (await stat(file)).mtimeMs;
+  } catch {
+    return { file, mtimeMs: null, json: null };
+  }
+
+  const contentCached = _taskContentCache.get(file);
+  if (contentCached && contentCached.mtimeMs === fileMtime) {
+    return { file, mtimeMs: fileMtime, json: contentCached.data };
+  }
+
+  const json = await readJsonSafe(file);
+  if (json && isObject(json)) {
+    _taskContentCache.set(file, { mtimeMs: fileMtime, data: json });
+  }
+
+  return { file, mtimeMs: fileMtime, json };
+}
 
 async function locateTaskFile(tasksDir, taskId) {
   const direct = join(tasksDir, `${taskId}.json`);
@@ -244,30 +358,17 @@ export async function teamTaskList(args = {}) {
     return err('TASKS_DIR_NOT_FOUND', `task 디렉토리를 찾지 못했습니다: ${team_name}`);
   }
 
-  const statusSet = new Set((statuses || []).map((s) => String(s)));
-  const maxCount = Math.max(1, Math.min(Number(limit) || 200, 1000));
-  let parseWarnings = 0;
-
-  const tasks = [];
-  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;
+  const statusSet = new Set((statuses || []).map((s) => String(s)));
+  const maxCount = Math.max(1, Math.min(Number(limit) || 200, 1000));
+  let parseWarnings = 0;
+  const files = await collectTaskFiles(paths.tasks_dir);
+  const records = await Promise.all(files.map((file) => readTaskFileCached(file)));
+
+  const tasks = [];
+  for (const { file, mtimeMs: fileMtime, json } of records) {
+    if (!json || !isObject(json)) {
+      parseWarnings += 1;
+      continue;
     }
 
     if (!include_internal && json?.metadata?._internal === true) continue;
@@ -440,13 +541,13 @@ export async function teamTaskUpdate(args = {}) {
         _invalidateCache(dirname(taskFile));
         // 콘텐츠 캐시 무효화
         _taskContentCache.delete(taskFile);
-      }
-
-      let afterMtime = beforeMtime;
-      try { afterMtime = statSync(taskFile).mtimeMs; } catch {}
-
-      return {
-        ok: true,
+      }
+
+      let afterMtime = beforeMtime;
+      try { afterMtime = (await stat(taskFile)).mtimeMs; } catch {}
+
+      return {
+        ok: true,
         data: {
           claimed,
           updated,

package/hub/tools.mjs

@@ -338,9 +338,9 @@ export function createTools(store, router, hitl, pipe = null) {
     },
 
     // ── 13. team_task_list ──
-    {
-      name: 'team_task_list',
-      description: 'Claude Native Teams task 목록을 owner/status 조건으로 조회합니다',
+    {
+      name: 'team_task_list',
+      description: 'Claude Native Teams task 목록을 owner/status 조건으로 조회합니다. 실패 판정은 completed + metadata.result도 함께 확인해야 합니다',
       inputSchema: {
         type: 'object',
         required: ['team_name'],
@@ -362,9 +362,9 @@ export function createTools(store, router, hitl, pipe = null) {
     },
 
     // ── 14. team_task_update ──
-    {
-      name: 'team_task_update',
-      description: 'Claude Native Teams task를 claim/update 합니다',
+    {
+      name: 'team_task_update',
+      description: 'Claude Native Teams task를 claim/update 합니다. status: "failed" 입력은 completed + metadata.result="failed"로 정규화됩니다',
       inputSchema: {
         type: 'object',
         required: ['team_name', 'task_id'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "3.3.0-dev.5",
+  "version": "3.3.0-dev.7",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -27,9 +27,9 @@
   "scripts": {
     "setup": "node scripts/setup.mjs",
     "postinstall": "node scripts/setup.mjs",
-    "test": "node --test --test-force-exit \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
-    "test:unit": "node --test --test-force-exit tests/unit/**/*.test.mjs",
-    "test:integration": "node --test --test-force-exit tests/integration/**/*.test.mjs",
+    "test": "node --test --test-force-exit --test-concurrency=1 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
+    "test:unit": "node --test --test-force-exit --test-concurrency=1 tests/unit/**/*.test.mjs",
+    "test:integration": "node --test --test-force-exit --test-concurrency=1 tests/integration/**/*.test.mjs",
     "test:route-smoke": "node --test scripts/test-tfx-route-no-claude-native.mjs"
   },
   "engines": {

package/scripts/completions/tfx.bash

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Installation: source /path/to/tfx.bash 또는 ~/.bashrc에 추가
+
+_tfx_completion() {
+    local cur prev words cword
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    words=("${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+
+    local commands="setup doctor multi hub auto codex gemini"
+    local multi_cmds="status stop kill attach list"
+    local hub_cmds="start stop status restart"
+    local flags="--thorough --quick --tmux --psmux --agents --no-attach --timeout"
+
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+        return 0
+    fi
+
+    local cmd="${words[1]}"
+    case "${cmd}" in
+        multi)
+            if [[ $cword -eq 2 && ! "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${multi_cmds}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+        hub)
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "${hub_cmds}" -- "$cur") )
+            fi
+            ;;
+        doctor)
+            COMPREPLY=( $(compgen -W "--fix --reset" -- "$cur") )
+            ;;
+        setup|auto|codex|gemini)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+    esac
+}
+
+complete -F _tfx_completion tfx

package/scripts/completions/tfx.fish

@@ -0,0 +1,44 @@
+# Installation: ~/.config/fish/completions/에 복사
+# e.g., cp /path/to/tfx.fish ~/.config/fish/completions/tfx.fish
+
+set -l commands setup doctor multi hub auto codex gemini
+set -l multi_cmds status stop kill attach list
+set -l hub_cmds start stop status restart
+
+complete -c tfx -f
+
+# Subcommands
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "setup" -d "Setup and sync files"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "doctor" -d "Diagnose CLI and issues"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "multi" -d "Multi-CLI team mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "hub" -d "MCP message bus management"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "auto" -d "Auto mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "codex" -d "Codex mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "gemini" -d "Gemini mode"
+
+# Doctor flags
+complete -c tfx -n "__fish_seen_subcommand_from doctor" -l fix -d "Auto fix issues"
+complete -c tfx -n "__fish_seen_subcommand_from doctor" -l reset -d "Reset all caches"
+
+# Multi subcommands
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "status"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "stop"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "kill"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "attach"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "list"
+
+# Hub subcommands
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "start"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "stop"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "status"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "restart"
+
+# Global or multi flags
+set -l flags_cond "__fish_seen_subcommand_from setup multi auto codex gemini"
+complete -c tfx -n "$flags_cond" -l thorough -d "Thorough execution"
+complete -c tfx -n "$flags_cond" -l quick -d "Quick execution"
+complete -c tfx -n "$flags_cond" -l tmux -d "Use tmux"
+complete -c tfx -n "$flags_cond" -l psmux -d "Use psmux"
+complete -c tfx -n "$flags_cond" -l agents -d "Specify agents"
+complete -c tfx -n "$flags_cond" -l no-attach -d "Do not attach"
+complete -c tfx -n "$flags_cond" -l timeout -d "Set timeout"

package/scripts/completions/tfx.zsh

@@ -0,0 +1,83 @@
+#compdef tfx
+# Installation: fpath에 추가 후 compinit
+# e.g., fpath=(/path/to/dir $fpath) && compinit
+
+_tfx() {
+    local line state
+    local -a commands multi_cmds hub_cmds flags
+
+    commands=(
+        'setup:Setup and sync files'
+        'doctor:Diagnose CLI and issues'
+        'multi:Multi-CLI team mode'
+        'hub:MCP message bus management'
+        'auto:Auto mode'
+        'codex:Codex mode'
+        'gemini:Gemini mode'
+    )
+
+    multi_cmds=(
+        'status:Show status'
+        'stop:Stop multi'
+        'kill:Kill multi'
+        'attach:Attach to multi'
+        'list:List multi sessions'
+    )
+
+    hub_cmds=(
+        'start:Start hub'
+        'stop:Stop hub'
+        'status:Show hub status'
+        'restart:Restart hub'
+    )
+
+    _arguments -C \
+        '1: :->cmds' \
+        '*: :->args'
+
+    case $state in
+        cmds)
+            _describe -t commands 'tfx commands' commands
+            ;;
+        args)
+            case $words[2] in
+                multi)
+                    if (( CURRENT == 3 )) && [[ $words[CURRENT] != -* ]]; then
+                        _describe -t multi_cmds 'multi commands' multi_cmds
+                    else
+                        _arguments \
+                            '--thorough[Thorough execution]' \
+                            '--quick[Quick execution]' \
+                            '--tmux[Use tmux]' \
+                            '--psmux[Use psmux]' \
+                            '--agents[Specify agents]' \
+                            '--no-attach[Do not attach]' \
+                            '--timeout[Set timeout]'
+                    fi
+                    ;;
+                hub)
+                    if (( CURRENT == 3 )); then
+                        _describe -t hub_cmds 'hub commands' hub_cmds
+                    fi
+                    ;;
+                doctor)
+                    _arguments \
+                        '--fix[Auto fix issues]' \
+                        '--reset[Reset all caches]'
+                    ;;
+                *)
+                    _arguments \
+                        '--thorough[Thorough execution]' \
+                        '--quick[Quick execution]' \
+                        '--tmux[Use tmux]' \
+                        '--psmux[Use psmux]' \
+                        '--agents[Specify agents]' \
+                        '--no-attach[Do not attach]' \
+                        '--timeout[Set timeout]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_tfx "$@"

package/scripts/lib/mcp-filter.mjs

@@ -226,7 +226,12 @@ function buildInventoryIndex(inventory = null) {
 }
 
 function getServerMetadata(server, inventoryIndex) {
-  return normalizeServerMetadata(server, inventoryIndex.get(server) || {});
+  const inventoryMetadata = inventoryIndex.get(server) || {};
+  return normalizeServerMetadata(server, {
+    // Inventory tool_count is useful for tie-breaks, but dynamic domain tags
+    // can over-broaden role policies compared to the static catalog.
+    tool_count: inventoryMetadata.tool_count,
+  });
 }
 
 function scoreServer(server, taskText = '', inventoryIndex = new Map()) {

package/scripts/tfx-route.sh

@@ -55,10 +55,69 @@ TFX_HUB_URL="${TFX_HUB_URL:-http://127.0.0.1:27888}"  # bridge.mjs HTTP fallback
 ORIGINAL_AGENT=""
 ORIGINAL_CLI_ARGS=""
 
+# JSON 문자열 이스케이프:
+# - "\", """ 필수 이스케이프
+# - 제어문자 U+0000..U+001F 이스케이프
+# - 비ASCII 문자는 \uXXXX(또는 surrogate pair)로 강제
+json_escape() {
+  local s="${1:-}"
+
+  if command -v "$NODE_BIN" &>/dev/null; then
+    "$NODE_BIN" -e '
+      const input = process.argv[1] ?? "";
+      let out = "";
+      for (const ch of input) {
+        const cp = ch.codePointAt(0);
+        if (cp === 0x22) { out += "\\\""; continue; }   // "
+        if (cp === 0x5c) { out += "\\\\"; continue; }   // \
+        if (cp <= 0x1f) {
+          if (cp === 0x08) { out += "\\b"; continue; }
+          if (cp === 0x09) { out += "\\t"; continue; }
+          if (cp === 0x0a) { out += "\\n"; continue; }
+          if (cp === 0x0c) { out += "\\f"; continue; }
+          if (cp === 0x0d) { out += "\\r"; continue; }
+          out += `\\u${cp.toString(16).padStart(4, "0")}`;
+          continue;
+        }
+        if (cp >= 0x20 && cp <= 0x7e) {
+          out += ch;
+          continue;
+        }
+        if (cp <= 0xffff) {
+          out += `\\u${cp.toString(16).padStart(4, "0")}`;
+          continue;
+        }
+        const v = cp - 0x10000;
+        const hi = 0xd800 + (v >> 10);
+        const lo = 0xdc00 + (v & 0x3ff);
+        out += `\\u${hi.toString(16).padStart(4, "0")}\\u${lo.toString(16).padStart(4, "0")}`;
+      }
+      process.stdout.write(out);
+    ' -- "$s"
+    return
+  fi
+
+  echo "[tfx-route] ERROR: node 미설치로 안전한 JSON 이스케이프를 수행할 수 없습니다." >&2
+  return 1
+}
+
 # ── Per-process 에이전트 등록 (원자적, 락 불필요) ──
 register_agent() {
   local agent_file="${TFX_TMP}/tfx-agent-$$.json"
-  echo "{\"pid\":$$,\"cli\":\"$CLI_TYPE\",\"agent\":\"$AGENT_TYPE\",\"started\":$(date +%s)}" \
+  local safe_cli safe_agent started_at
+  safe_cli=$(json_escape "$CLI_TYPE" 2>/dev/null || true)
+  safe_agent=$(json_escape "$AGENT_TYPE" 2>/dev/null || true)
+  started_at=$(date +%s)
+
+  # fail-closed: 안전 인코딩 불가 시 agent 파일을 쓰지 않는다
+  if [[ -n "$CLI_TYPE" && -z "$safe_cli" ]]; then
+    return 0
+  fi
+  if [[ -n "$AGENT_TYPE" && -z "$safe_agent" ]]; then
+    return 0
+  fi
+
+  printf '{"pid":%s,"cli":"%s","agent":"%s","started":%s}\n' "$$" "$safe_cli" "$safe_agent" "$started_at" \
     > "$agent_file" 2>/dev/null || true
 }
 
@@ -329,6 +388,16 @@ team_complete_task() {
       echo "[tfx-route] 경고: Hub result 발행 실패 (agent=$TFX_TEAM_AGENT_NAME, task=$TFX_TEAM_TASK_ID)" >&2
     fi
   fi
+
+  # 로컬 결과 파일 백업 (세션 끊김 복구용)
+  # Claude 재로그인 시 Agent 래퍼가 죽어도 이 파일로 결과 수집 가능
+  local result_dir="${TFX_RESULT_DIR:-${HOME}/.claude/tfx-results/${TFX_TEAM_NAME}}"
+  if mkdir -p "$result_dir" 2>/dev/null; then
+    cat > "${result_dir}/${TFX_TEAM_TASK_ID}.json" 2>/dev/null <<RESULT_EOF
+{"taskId":"${TFX_TEAM_TASK_ID}","agent":"${TFX_TEAM_AGENT_NAME}","team":"${TFX_TEAM_NAME}","result":"${result}","summary":$(printf '%s' "$summary_trimmed" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.stringify(d)))" 2>/dev/null || echo '""'),"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+RESULT_EOF
+    [[ $? -eq 0 ]] && echo "[tfx-route] 결과 백업: ${result_dir}/${TFX_TEAM_TASK_ID}.json" >&2
+  fi
 }
 
 capture_workspace_signature() {

package/skills/tfx-auto/SKILL.md

@@ -141,6 +141,8 @@ Agent(subagent_type="oh-my-claudecode:{agent}", model="{model}", prompt="{prompt
 
 ### 결과 파싱
 
+여기서 `failed`는 `tfx-route.sh`/CLI 종료 결과를 뜻한다. Claude Code `TaskUpdate` 상태값이 아니다.
+
 | exit_code + status | 사용할 출력 |
 |--------------------|-----------|
 | 0 + success | `=== OUTPUT ===` 섹션 |
@@ -177,11 +179,14 @@ OUTPUT 추출: `echo "$result" | sed -n '/^=== OUTPUT ===/,/^=== /{/^=== OUTPUT
 |------|------|
 | `tfx-route.sh: not found` | tfx-route.sh 생성 |
 | `codex/gemini: not found` | npm install -g |
-| timeout / failed | stderr → Claude fallback |
+| timeout / failed (`tfx-route.sh` 결과) | stderr → Claude fallback |
 | N > 10 | 10 이하로 조정 |
 | 순환 의존 | 분해 재시도 |
 | 컨텍스트 > 32KB | 비례 절삭 |
 
+> Claude Code `TaskUpdate`를 사용할 때는 `status: "failed"`를 쓰지 않는다.
+> 실패 보고는 `status: "completed"` + `metadata.result: "failed"`로 표현한다.
+
 ## Troubleshooting
 
 `/tfx-doctor` 진단 | `/tfx-doctor --fix` 자동 수정 | `/tfx-doctor --reset` 캐시 초기화