triflux 5.2.0 → 6.0.1

package/hub/team/headless.mjs

@@ -1,9 +1,12 @@
 // hub/team/headless.mjs — 헤드리스 CLI 오케스트레이션
 // psmux pane에서 CLI를 헤드리스 모드로 실행하고 결과를 수집한다.
+// v5.2.0: 기본 headless 엔진 (runHeadless, runHeadlessWithCleanup)
+// v6.0.0: Lead-direct 모드 (runHeadlessInteractive, autoAttachTerminal)
 // 의존성: psmux.mjs (Node.js 내장 모듈만 사용)
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { execSync, execFileSync } from "node:child_process";
 import {
   createPsmuxSession,
   killPsmuxSession,
@@ -11,6 +14,8 @@ import {
   dispatchCommand,
   waitForCompletion,
   capturePsmuxPane,
+  startCapture,
+  psmuxExec,
 } from "./psmux.mjs";
 
 const RESULT_DIR = join(tmpdir(), "tfx-headless");
@@ -30,7 +35,7 @@ export function buildHeadlessCommand(cli, prompt, resultFile) {
     case "codex":
       return `codex exec '${escaped}' -o '${resultFile}' --color never`;
     case "gemini":
-      return `gemini -p '${escaped}' -o text > '${resultFile}' 2>&1`;
+      return `gemini -p '${escaped}' -o text > '${resultFile}' 2>'${resultFile}.err'`;
     case "claude":
       return `claude -p '${escaped}' --output-format text > '${resultFile}' 2>&1`;
     default:
@@ -41,8 +46,7 @@ export function buildHeadlessCommand(cli, prompt, resultFile) {
 /**
  * 결과 파일 읽기 (없으면 capture-pane fallback)
  * @param {string} resultFile
- * @param {string} sessionName
- * @param {string} paneName
+ * @param {string} paneId
  * @returns {string}
  */
 function readResult(resultFile, paneId) {
@@ -62,6 +66,8 @@ function readResult(resultFile, paneId) {
  * @param {number} [opts.timeoutSec=300] — 각 워커 타임아웃
  * @param {string} [opts.layout='2x2'] — pane 레이아웃
  * @param {(event: object) => void} [opts.onProgress] — 진행 콜백
+ * @param {number} [opts.progressIntervalSec=0] — N초마다 progress 이벤트 발화 (0=비활성)
+ * @param {boolean} [opts.progressive=true] — true면 pane을 하나씩 split-window로 추가 (실시간 스플릿)
  * @returns {{ sessionName: string, results: Array<{cli: string, paneName: string, matched: boolean, exitCode: number|null, output: string, sessionDead?: boolean}> }}
  */
 export async function runHeadless(sessionName, assignments, opts = {}) {
@@ -69,29 +75,96 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     timeoutSec = 300,
     layout = "2x2",
     onProgress,
+    progressIntervalSec = 0,
+    progressive = true,
   } = opts;
 
   mkdirSync(RESULT_DIR, { recursive: true });
-  const paneCount = assignments.length + 1; // +1 for lead pane (unused but reserved)
-  const session = createPsmuxSession(sessionName, { layout, paneCount });
 
-  if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
+  let dispatches;
 
-  // 각 워커 pane에 헤드리스 명령 dispatch
-  const dispatches = assignments.map((assignment, i) => {
-    const paneName = `worker-${i + 1}`;
-    const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
-    const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
-    const dispatch = dispatchCommand(sessionName, paneName, cmd);
+  if (progressive) {
+    // ─── 실시간 스플릿 모드: lead pane만 생성 후, 워커를 하나씩 추가 ───
+    const session = createPsmuxSession(sessionName, { layout, paneCount: 1 });
+    applyTrifluxTheme(sessionName);
+    if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
 
-    if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+    dispatches = assignments.map((assignment, i) => {
+      const paneName = `worker-${i + 1}`;
+      const paneTitle = assignment.role
+        ? `${assignment.cli} (${assignment.role})`
+        : `${assignment.cli}-${i + 1}`;
 
-    return { ...dispatch, paneName, resultFile, cli: assignment.cli, role: assignment.role };
-  });
+      // split-window로 새 pane 추가 — paneId 직접 획득
+      const newPaneId = psmuxExec([
+        "split-window", "-t", sessionName, "-P", "-F",
+        "#{session_name}:#{window_index}.#{pane_index}",
+      ]);
+
+      // 타이틀 설정
+      try { psmuxExec(["select-pane", "-t", newPaneId, "-T", paneTitle]); } catch { /* 무시 */ }
+
+      if (onProgress) onProgress({ type: "worker_added", paneName, cli: assignment.cli, paneTitle });
+
+      // 캡처 시작 + 명령 dispatch (paneId 직접 사용 — resolvePane race 회피)
+      const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
+      const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
+      startCapture(sessionName, newPaneId);
+      const dispatch = dispatchCommand(sessionName, newPaneId, cmd);
+
+      if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+
+      return { ...dispatch, paneId: newPaneId, paneName, resultFile, cli: assignment.cli, role: assignment.role };
+    });
+
+    // 모든 split 완료 후 레이아웃 한 번만 정렬 (깜빡임 방지)
+    try { psmuxExec(["select-layout", "-t", sessionName, "tiled"]); } catch { /* 무시 */ }
+
+  } else {
+    // ─── 기존 모드: 모든 pane을 한 번에 생성 ───
+    const paneCount = assignments.length + 1;
+    const session = createPsmuxSession(sessionName, { layout, paneCount });
+    applyTrifluxTheme(sessionName);
+    if (onProgress) onProgress({ type: "session_created", sessionName, panes: session.panes });
+
+    dispatches = assignments.map((assignment, i) => {
+      const paneName = `worker-${i + 1}`;
+      const resultFile = join(RESULT_DIR, `${sessionName}-${paneName}.txt`).replace(/\\/g, "/");
+      const cmd = buildHeadlessCommand(assignment.cli, assignment.prompt, resultFile);
+      const dispatch = dispatchCommand(sessionName, paneName, cmd);
+
+      // P1 fix: 비-progressive에서는 pane 리네임 금지 — 캡처 로그 경로가 타이틀 기반이므로
+      // 리네임하면 waitForCompletion이 "codex (role).log"를 찾지만 실제는 "worker-N.log"로 불일치
+      // progressive 모드에서는 split-window 시 새 pane에 바로 타이틀이 설정되므로 문제없음
+
+      if (onProgress) onProgress({ type: "dispatched", paneName, cli: assignment.cli });
+
+      return { ...dispatch, paneName, resultFile, cli: assignment.cli, role: assignment.role };
+    });
+  }
 
   // 병렬 대기 (Promise.all — 모든 pane 동시 폴링, 총 시간 = max(개별 시간))
   const results = await Promise.all(dispatches.map(async (d) => {
-    const completion = await waitForCompletion(sessionName, d.paneName, d.token, timeoutSec);
+    // onPoll → onProgress 변환 (throttle by progressIntervalSec)
+    const pollOpts = {};
+    if (onProgress && progressIntervalSec > 0) {
+      let lastProgressAt = 0;
+      const intervalMs = progressIntervalSec * 1000;
+      pollOpts.onPoll = ({ content }) => {
+        const now = Date.now();
+        if (now - lastProgressAt >= intervalMs) {
+          lastProgressAt = now;
+          onProgress({
+            type: "progress",
+            paneName: d.paneName,
+            cli: d.cli,
+            snapshot: content.split("\n").slice(-15).join("\n"), // 마지막 15줄
+          });
+        }
+      };
+    }
+
+    const completion = await waitForCompletion(sessionName, d.paneName, d.token, timeoutSec, pollOpts);
 
     const output = completion.matched
       ? readResult(d.resultFile, d.paneId)
@@ -111,6 +184,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     return {
       cli: d.cli,
       paneName: d.paneName,
+      paneId: d.paneId,
       role: d.role,
       matched: completion.matched,
       exitCode: completion.exitCode,
@@ -144,3 +218,231 @@ export async function runHeadlessWithCleanup(assignments, opts = {}) {
     }
   }
 }
+
+// ─── v6.0.0: Theme + Visual ───
+
+/**
+ * psmux 세션에 triflux 테마를 적용한다.
+ * status bar + pane border 색상 + 브랜딩.
+ *
+ * @param {string} sessionName
+ */
+export function applyTrifluxTheme(sessionName) {
+  const opts = [
+    // Status bar — Catppuccin Mocha 기반
+    ["status-style", "bg=#1e1e2e,fg=#cdd6f4"],
+    ["status-left", " #[fg=#89b4fa,bold]▲ triflux#[default] "],
+    ["status-left-length", "20"],
+    ["status-right", " #[fg=#a6adc8]#{pane_title}#[default] │ #[fg=#f9e2af]%H:%M#[default] "],
+    ["status-right-length", "40"],
+    // Pane border — active/inactive 구분
+    ["pane-active-border-style", "fg=#89b4fa"],
+    ["pane-border-style", "fg=#45475a"],
+    // Status bar 위치
+    ["status-position", "bottom"],
+  ];
+  for (const [key, value] of opts) {
+    try { psmuxExec(["set-option", "-t", sessionName, key, value]); } catch { /* 무시 */ }
+  }
+}
+
+// ─── v6.0.0: Lead-Direct Interactive Mode ───
+
+/**
+ * Windows Terminal에서 psmux 세션을 자동 attach한다.
+ * 별도 창이 열리며 사용자가 실시간으로 CLI 출력을 볼 수 있다.
+ *
+ * @param {string} sessionName — attach할 psmux 세션 이름
+ * @param {object} [opts]
+ * @param {string} [opts.position] — "right" | "left" | 없으면 기본 위치
+ * @returns {boolean} 성공 여부
+ */
+export function autoAttachTerminal(sessionName, opts = {}) {
+  try {
+    // Windows Terminal이 설치되어 있는지 확인
+    execSync("where wt.exe", { stdio: "ignore" });
+  } catch {
+    return false; // wt.exe 미설치 — 사용자에게 수동 attach 안내 필요
+  }
+
+  try {
+    // Fix P2: argv 스타일 — shell injection 방지
+    execFileSync("wt.exe", ["-w", "0", "nt", "psmux", "attach", "-t", sessionName], { stdio: "ignore" });
+    return true;
+  } catch {
+    try {
+      execFileSync("wt.exe", ["psmux", "attach", "-t", sessionName], { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * 모든 워커 pane의 현재 스냅샷을 수집한다.
+ *
+ * @param {string} sessionName
+ * @param {Array<{paneId: string, paneName: string, cli: string}>} dispatches
+ * @param {number} [lines=15] — 각 pane에서 캡처할 줄 수
+ * @returns {Array<{paneName: string, cli: string, snapshot: string}>}
+ */
+export function getProgressSnapshots(sessionName, dispatches, lines = 15) {
+  if (!psmuxSessionExists(sessionName)) return [];
+  return dispatches.map((d) => {
+    try {
+      const snapshot = capturePsmuxPane(d.paneId, lines);
+      return { paneName: d.paneName, cli: d.cli, snapshot };
+    } catch {
+      return { paneName: d.paneName, cli: d.cli, snapshot: "(캡처 실패)" };
+    }
+  });
+}
+
+/**
+ * Lead-Direct Interactive 헤드리스 실행.
+ * 세션을 유지하면서 결과 수집 후에도 추가 명령을 dispatch할 수 있다.
+ * 반환된 handle의 kill()을 반드시 호출하여 세션을 정리해야 한다.
+ *
+ * @param {string} sessionName — psmux 세션 이름
+ * @param {Array<{cli: string, prompt: string, role?: string}>} assignments
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutSec=300]
+ * @param {string} [opts.layout='2x2']
+ * @param {(event: object) => void} [opts.onProgress]
+ * @param {number} [opts.progressIntervalSec=0]
+ * @param {boolean} [opts.autoAttach=false] — Windows Terminal 자동 attach
+ * @param {AbortSignal} [opts.signal] — abort 시 자동 세션 정리
+ * @param {number} [opts.maxIdleSec=0] — 유휴 시 자동 정리 (0=비활성)
+ * @returns {Promise<{
+ *   sessionName: string,
+ *   results: Array,
+ *   dispatches: Array,
+ *   dispatch: (paneName: string, command: string) => {paneId: string, paneName: string, token: string},
+ *   capture: (paneName: string, lines?: number) => string,
+ *   snapshots: (lines?: number) => Array,
+ *   waitFor: (paneName: string, token: string, timeoutSec?: number, opts?: object) => Promise,
+ *   alive: () => boolean,
+ *   kill: () => void,
+ * }>}
+ */
+export async function runHeadlessInteractive(sessionName, assignments, opts = {}) {
+  const {
+    autoAttach = false,
+    signal,
+    maxIdleSec = 0,
+    ...runOpts
+  } = opts;
+
+  // autoAttach를 session_created 시점에 트리거 (CLI 실행 전에 터미널 열림)
+  const userOnProgress = runOpts.onProgress;
+  let terminalAttached = false;
+  runOpts.onProgress = (event) => {
+    if (autoAttach && event.type === "session_created" && !terminalAttached) {
+      terminalAttached = true;
+      autoAttachTerminal(sessionName);
+    }
+    if (userOnProgress) userOnProgress(event);
+  };
+
+  // Phase 1: 세션 생성 → 즉시 터미널 팝업 → dispatch → 대기 → 결과 수집
+  const { results } = await runHeadless(sessionName, assignments, runOpts);
+
+  // Phase 2: 세션을 유지하고 interactive handle 반환
+  // Fix P2: paneId를 dispatches에 포함 (snapshots에서 필요)
+  const dispatches = results.map((r, i) => ({
+    paneName: r.paneName,
+    paneId: r.paneId || "",
+    cli: r.cli,
+    role: r.role,
+  }));
+
+  // Fix P2: maxIdleSec 리셋을 위한 타이머 관리
+  let idleTimer = null;
+  function resetIdleTimer() {
+    if (idleTimer) clearTimeout(idleTimer);
+    if (maxIdleSec > 0) {
+      idleTimer = setTimeout(() => handle.kill(), maxIdleSec * 1000);
+      if (idleTimer.unref) idleTimer.unref();
+    }
+  }
+
+  const handle = {
+    sessionName,
+    results,
+    dispatches,
+    _killed: false,
+
+    /** 특정 pane에 후속 명령 dispatch (캡처 자동 재시작) */
+    dispatch(paneName, command) {
+      if (this._killed) throw new Error("세션이 이미 종료되었습니다.");
+      try { startCapture(sessionName, paneName); } catch { /* 이미 활성 — 무시 */ }
+      resetIdleTimer();
+      return dispatchCommand(sessionName, paneName, command);
+    },
+
+    /** 특정 pane의 현재 출력 캡처 */
+    capture(paneName, lines = 30) {
+      if (this._killed) return "";
+      try {
+        // Fix P2: paneName으로 resolvePane을 경유하여 정확한 paneId 획득
+        return capturePsmuxPane(paneName, lines);
+      } catch {
+        return "(캡처 실패)";
+      }
+    },
+
+    /** 모든 pane 스냅샷 */
+    snapshots(lines = 15) {
+      if (this._killed) return [];
+      return getProgressSnapshots(sessionName, dispatches, lines);
+    },
+
+    /** 특정 pane에서 완료 대기 */
+    async waitFor(paneName, token, timeoutSec = 300, waitOpts = {}) {
+      if (this._killed) return { matched: false, sessionDead: true };
+      resetIdleTimer();
+      return waitForCompletion(sessionName, paneName, token, timeoutSec, waitOpts);
+    },
+
+    /** 세션 생존 확인 */
+    alive() {
+      if (this._killed) return false;
+      return psmuxSessionExists(sessionName);
+    },
+
+    /** 세션 종료 */
+    kill() {
+      if (this._killed) return;
+      this._killed = true;
+      try { killPsmuxSession(sessionName); } catch { /* 무시 */ }
+    },
+  };
+
+  // AbortController signal로 자동 정리
+  if (signal) {
+    if (signal.aborted) {
+      handle.kill();
+    } else {
+      signal.addEventListener("abort", () => handle.kill(), { once: true });
+    }
+  }
+
+  // 유휴 타임아웃 자동 정리
+  if (maxIdleSec > 0) {
+    const timer = setTimeout(() => handle.kill(), maxIdleSec * 1000);
+    if (timer.unref) timer.unref(); // Node.js exit를 방해하지 않음
+  }
+
+  // 프로세스 종료 시 safety net
+  const exitHandler = () => handle.kill();
+  process.on("exit", exitHandler);
+  // kill() 후 리스너 제거를 위해 참조 보관
+  const originalKill = handle.kill.bind(handle);
+  handle.kill = function () {
+    originalKill();
+    process.removeListener("exit", exitHandler);
+  };
+
+  return handle;
+}

package/hub/team/psmux.mjs

@@ -641,9 +641,11 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
  * @param {string} paneNameOrTarget
  * @param {string|RegExp} pattern
  * @param {number} timeoutSec
+ * @param {object} [opts]
+ * @param {(snapshot: {content: string, paneId: string, paneName: string, elapsed: number}) => void} [opts.onPoll] — 각 폴링 주기마다 호출
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null }}
  */
-export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300) {
+export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300, opts = {}) {
   ensurePsmuxInstalled();
 
   // E4 크래시 복구: 초기 resolvePane도 세션 사망을 감지
@@ -670,7 +672,8 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     throw new Error(`캡처 로그가 없습니다. 먼저 startCapture(${sessionName}, ${paneName})를 호출하세요.`);
   }
 
-  const deadline = Date.now() + Math.max(0, Math.trunc(timeoutSec * 1000));
+  const startTime = Date.now();
+  const deadline = startTime + Math.max(0, Math.trunc(timeoutSec * 1000));
   const regex = toPatternRegExp(pattern);
 
   while (Date.now() <= deadline) {
@@ -692,6 +695,14 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     }
 
     const content = readCaptureLog(logPath);
+
+    // onPoll 콜백 — 각 폴링 주기마다 중간 상태 전달
+    if (opts.onPoll) {
+      try {
+        opts.onPoll({ content, paneId: pane.paneId, paneName, elapsed: Date.now() - startTime });
+      } catch { /* 콜백 예외는 삼킴 — 폴링 루프 보호 */ }
+    }
+
     const match = regex.exec(content);
     if (match) {
       return {
@@ -724,14 +735,15 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
  * @param {string} paneNameOrTarget
  * @param {string} token
  * @param {number} timeoutSec
+ * @param {object} [opts] — waitForPattern에 전달할 옵션 (onPoll 등)
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, token: string, exitCode: number|null }}
  */
-export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300) {
+export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300, opts = {}) {
   const completionRegex = new RegExp(
     `${escapeRegExp(COMPLETION_PREFIX)}${escapeRegExp(token)}:(\\d+)`,
     "m",
   );
-  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec);
+  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec, opts);
   const exitMatch = result.match ? completionRegex.exec(result.match) : null;
   return {
     ...result,

package/package.json

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

package/scripts/lib/logger.mjs

@@ -93,13 +93,13 @@ export function createModuleLogger(module) {
 
 // 정상 종료 시 버퍼 flush 보장
 process.on('uncaughtException', (err) => {
-  const finalLogger = pino.final(logger);
-  finalLogger.fatal({ err }, 'process.uncaught_exception');
+  logger.fatal({ err }, 'process.uncaught_exception');
+  logger.flush();
   process.exit(1);
 });
 
 process.on('unhandledRejection', (reason) => {
-  const finalLogger = pino.final(logger);
-  finalLogger.fatal({ reason: String(reason) }, 'process.unhandled_rejection');
+  logger.fatal({ reason: String(reason) }, 'process.unhandled_rejection');
+  logger.flush();
   process.exit(1);
 });

package/scripts/preinstall.mjs

@@ -1,43 +1,80 @@
-#!/usr/bin/env node
-// npm install 전 Hub를 안전하게 중지하여 EBUSY 방지
-// better-sqlite3.node 파일이 Hub 프로세스에 의해 잠기면 npm이 덮어쓸 수 없음
-
-import { existsSync, readFileSync, unlinkSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-
-const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
-
-function stopHub() {
-  if (!existsSync(HUB_PID_FILE)) return;
-
-  try {
-    const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
-    const pid = Number(info?.pid);
-    if (!Number.isFinite(pid) || pid <= 0) return;
-
-    // 프로세스 존재 확인
-    process.kill(pid, 0);
-
-    // SIGTERM 전송
-    process.kill(pid, "SIGTERM");
-    console.log(`[triflux preinstall] Hub 중지됨 (PID ${pid}) — EBUSY 방지`);
-
-    // Windows: 프로세스 종료 + 파일 핸들 해제 대기 (최대 3초)
-    const start = Date.now();
-    while (Date.now() - start < 3000) {
-      try { process.kill(pid, 0); } catch { break; }
-    }
-
-    // PID 파일 정리
-    try { unlinkSync(HUB_PID_FILE); } catch {}
-  } catch (err) {
-    if (err.code === "ESRCH") {
-      // 프로세스 이미 종료됨 — PID 파일만 정리
-      try { unlinkSync(HUB_PID_FILE); } catch {}
-    }
-    // EPERM 등 기타 에러는 무시 (설치를 막으면 안 됨)
-  }
-}
-
-stopHub();
+#!/usr/bin/env node
+// npm install 전 Hub를 안전하게 중지하여 EBUSY 방지
+// better-sqlite3.node 파일이 Hub 프로세스에 의해 잠기면 npm이 덮어쓸 수 없음
+//
+// v6.0.0: taskkill /T /F + Atomics.wait sleep + 파일 잠금 확인
+// (bin/triflux.mjs stopHubForUpdate 패턴과 동일)
+
+import { existsSync, readFileSync, unlinkSync, openSync, closeSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, "..");
+const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function stopHub() {
+  if (!existsSync(HUB_PID_FILE)) return;
+
+  let info;
+  try {
+    info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+    const pid = Number(info?.pid);
+    if (!Number.isFinite(pid) || pid <= 0) return;
+    process.kill(pid, 0); // 프로세스 존재 확인
+  } catch {
+    // 프로세스 없음 또는 PID 파일 손상 — PID 파일만 정리
+    try { unlinkSync(HUB_PID_FILE); } catch {}
+    return;
+  }
+
+  const pid = Number(info.pid);
+
+  // 1단계: 프로세스 종료 — Windows는 taskkill, Unix는 SIGTERM
+  try {
+    if (process.platform === "win32") {
+      execFileSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        stdio: ["pipe", "pipe", "ignore"],
+        timeout: 10000,
+        windowsHide: true,
+      });
+    } else {
+      process.kill(pid, "SIGTERM");
+    }
+  } catch {
+    // taskkill 실패 시 SIGKILL fallback
+    try { process.kill(pid, "SIGKILL"); } catch {}
+  }
+
+  // 2단계: 프로세스 종료 대기 (최대 5초, 500ms 간격)
+  for (let i = 0; i < 10; i++) {
+    sleepMs(500);
+    try { process.kill(pid, 0); } catch { break; }
+  }
+
+  // 3단계: better-sqlite3.node 파일 잠금 해제 확인 (최대 3초)
+  const sqliteNode = join(PKG_ROOT, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node");
+  if (existsSync(sqliteNode)) {
+    for (let i = 0; i < 6; i++) {
+      try {
+        const fd = openSync(sqliteNode, "r");
+        closeSync(fd);
+        break; // 열림 = 잠금 해제됨
+      } catch {
+        sleepMs(500);
+      }
+    }
+  }
+
+  // 4단계: PID 파일 정리 (종료 확인 후)
+  try { unlinkSync(HUB_PID_FILE); } catch {}
+  console.log(`[triflux preinstall] Hub 중지 완료 (PID ${pid})`);
+}
+
+stopHub();