triflux 3.2.0-dev.13 → 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/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/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.13",
+  "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` 전용)