triflux 10.0.0 → 10.0.2

package/scripts/gen-skill-docs.mjs

@@ -0,0 +1,111 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  buildSkillTemplateContext,
+  loadTemplatePartials,
+  parseFrontmatter,
+  renderSkillTemplate,
+} from "./lib/skill-template.mjs";
+
+function walkFiles(rootDir, currentDir = rootDir) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".")) continue;
+      files.push(...walkFiles(rootDir, fullPath));
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+    files.push(fullPath);
+  }
+
+  return files;
+}
+
+function collectSkillTemplateFiles(skillsDir) {
+  return walkFiles(skillsDir)
+    .filter((file) => file.endsWith("SKILL.md.tmpl"))
+    .filter(
+      (file) =>
+        !relative(skillsDir, file).replace(/\\/g, "/").startsWith("_templates/"),
+    )
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function resolveOutputPath(templatePath) {
+  if (!templatePath.endsWith(".tmpl")) {
+    throw new Error(`Template file must end with .tmpl: ${templatePath}`);
+  }
+  return templatePath.slice(0, -".tmpl".length);
+}
+
+function createRenderContext(templateContent, templatePath) {
+  const { data: frontmatter } = parseFrontmatter(templateContent);
+  const skillDirName = dirname(templatePath).split(/[/\\]/).pop() || "";
+  return buildSkillTemplateContext({ frontmatter, skillDirName });
+}
+
+export function generateSkillDocs({
+  skillsDir,
+  templatesDir = join(skillsDir, "_templates"),
+  write = true,
+} = {}) {
+  if (!skillsDir) throw new Error("skillsDir is required");
+
+  const partials = loadTemplatePartials(templatesDir);
+  const templateFiles = collectSkillTemplateFiles(skillsDir);
+  const generated = [];
+
+  for (const templatePath of templateFiles) {
+    const templateContent = readFileSync(templatePath, "utf8");
+    const context = createRenderContext(templateContent, templatePath);
+    const rendered = renderSkillTemplate(templateContent, context, { partials });
+    const outputPath = resolveOutputPath(templatePath);
+
+    if (write) {
+      writeFileSync(outputPath, rendered, "utf8");
+    }
+
+    generated.push({
+      templatePath,
+      outputPath,
+      relativeTemplatePath: relative(skillsDir, templatePath).replace(/\\/g, "/"),
+      context,
+      rendered,
+    });
+  }
+
+  return {
+    generated,
+    count: generated.length,
+  };
+}
+
+function runCli() {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const repoRoot = resolve(scriptDir, "..");
+  const skillsDir = join(repoRoot, "skills");
+
+  const result = generateSkillDocs({ skillsDir });
+  console.log(`Generated ${result.count} SKILL.md file(s) from templates.`);
+}
+
+const isDirectRun = process.argv[1]
+  ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  : false;
+
+if (isDirectRun) {
+  try {
+    runCli();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[gen-skill-docs] ${message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/headless-guard-fast.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# headless-guard-fast.sh — bash pre-filter for headless-guard.mjs
+# psmux 미설치(캐시 ok=false) 시 Node.js 기동을 생략하여 89ms→~2ms로 단축
+CACHE="${TMPDIR:-${TEMP:-/tmp}}/tfx-psmux-check.json"
+GUARD_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+if [[ -f "$CACHE" ]]; then
+  # jq 없이 순수 bash로 파싱
+  ok_val=$(grep -o '"ok":[[:space:]]*\(true\|false\)' "$CACHE" | grep -o 'true\|false')
+  ts_val=$(grep -o '"ts":[[:space:]]*[0-9]*' "$CACHE" | grep -o '[0-9]*')
+  now_ms=$(($(date +%s) * 1000))
+  age_ms=$((now_ms - ${ts_val:-0}))
+
+  # 캐시 유효(5분 이내) + psmux 미설치 → 즉시 통과
+  if [[ "$ok_val" == "false" && $age_ms -lt 300000 ]]; then
+    exit 0
+  fi
+fi
+
+# 캐시 미스 또는 psmux 설치됨 → Node.js 실행
+exec node "$GUARD_DIR/headless-guard.mjs"

package/scripts/headless-guard.mjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * headless-guard.mjs — PreToolUse 훅 (상시 활성 auto-route)
+ *
+ * psmux가 설치된 환경에서 Bash(tfx-route.sh) 개별 호출을
+ * 자동으로 headless 명령으로 변환한다.
+ *
+ * v2: 마커 파일 의존 제거. psmux 설치 여부만으로 판단.
+ *     Opus가 SKILL.md를 무시해도 auto-route가 작동한다.
+ *
+ * v3: A(gate) + B(nudge) — OMC 패턴 도입
+ *     A: tfx-multi 활성 시 headless dispatch 전까지 Agent 작업 위임 차단
+ *     B: dispatch 후 네이티브 드리프트 감지 시 nudge
+ *     상태: $TMPDIR/tfx-multi-state.json (tfx-multi-activate.mjs가 생성)
+ *
+ * 동작:
+ * - psmux 설치 + Bash(tfx-route.sh) → updatedInput: tfx multi --headless --assign
+ * - psmux 설치 + Bash(codex exec / gemini --prompt) → deny
+ * - psmux 설치 + Agent(codex/gemini CLI 래핑) → deny
+ * - psmux 미설치 → 전부 통과
+ * - tfx-multi 활성 + Agent(work) before dispatch → deny (A: gate)
+ * - tfx-multi 활성 + Agent(work) after dispatch → nudge (B: nudge)
+ *
+ * 성능: psmux 감지 결과를 5분간 캐시 ($TMPDIR/tfx-psmux-check.json)
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { nudge, deny } from "./lib/hook-utils.mjs";
+import { probePsmuxSupport } from "./lib/psmux-info.mjs";
+
+const CACHE_FILE = join(tmpdir(), "tfx-psmux-check.json");
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5분
+
+// ── tfx-multi 상태 관리 (A+B) ──
+const MULTI_STATE_FILE = join(tmpdir(), "tfx-multi-state.json");
+const MULTI_EXPIRE_MS = 30 * 60 * 1000; // 30분 자동 만료
+const GATE_THRESHOLD = 2;   // A: dispatch 전 허용할 Agent 호출 수
+const NUDGE_THRESHOLD = 4;  // B: dispatch 후 nudge 트리거 횟수
+
+function readMultiState() {
+  try {
+    if (!existsSync(MULTI_STATE_FILE)) return null;
+    const state = JSON.parse(readFileSync(MULTI_STATE_FILE, "utf8"));
+    if (!state.active) return null;
+    // 자동 만료
+    if (Date.now() - state.activatedAt > MULTI_EXPIRE_MS) {
+      try { unlinkSync(MULTI_STATE_FILE); } catch { /* ignore */ }
+      return null;
+    }
+    return state;
+  } catch { return null; }
+}
+
+function writeMultiState(state) {
+  try {
+    writeFileSync(MULTI_STATE_FILE, JSON.stringify(state));
+  } catch { /* ignore */ }
+}
+
+function isPsmuxInstalled() {
+  // 캐시 확인 (미래 타임스탬프 오염 방어)
+  try {
+    if (existsSync(CACHE_FILE)) {
+      const cache = JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+      const age = Date.now() - cache.ts;
+      if (age >= 0 && age < CACHE_TTL_MS) return cache.ok;
+      // age < 0 → 미래 ts (오염) → 캐시 무시하고 재검사
+    }
+  } catch { /* cache miss */ }
+
+  const probe = probePsmuxSupport({ execFileSyncFn: execFileSync });
+  const ok = probe.ok;
+
+  // 캐시 저장
+  try {
+    writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), ok, version: probe.version, missingCommands: probe.missingCommands }));
+  } catch { /* ignore */ }
+
+  return ok;
+}
+
+/**
+ * tfx-route.sh 명령에서 agent, prompt, mcp, 추가 플래그를 파싱한다.
+ * v3: 손실 없는 파싱 — 원본 명령의 모든 플래그를 보존.
+ */
+function parseRouteCommand(cmd) {
+  const MCP_PROFILES = ["implement", "analyze", "review", "docs"];
+
+  const agentMatch = cmd.match(/tfx-route\.sh\s+(\S+)\s+/);
+  if (!agentMatch) return null;
+
+  const agent = agentMatch[1];
+  const afterAgent = cmd.slice(agentMatch.index + agentMatch[0].length);
+
+  let mcp = "";
+  let promptRaw = afterAgent;
+  for (const profile of MCP_PROFILES) {
+    const profileIdx = afterAgent.lastIndexOf(` ${profile}`);
+    if (profileIdx >= 0) {
+      mcp = profile;
+      promptRaw = afterAgent.slice(0, profileIdx);
+      break;
+    }
+  }
+
+  const prompt = promptRaw
+    .replace(/^['"]/, "")
+    .replace(/['"]$/, "")
+    .replace(/'\\''/g, "'")
+    .replace(/'"'"'/g, "'")
+    .trim();
+
+  // v3: 원본 명령에서 추가 플래그 추출
+  const flags = {};
+  const afterPrompt = cmd.replace(/'.+?'/gs, "").replace(/".+?"/gs, "");
+  const timeoutMatch = afterPrompt.match(/(?:^|\s)(\d{2,4})(?:\s|$)/);  // 4번째 인자 (timeout)
+  if (timeoutMatch) flags.timeout = parseInt(timeoutMatch[1], 10);
+
+  // 환경변수 기반 글로벌 플래그
+  if (process.env.TFX_VERBOSE === "1") flags.verbose = true;
+  if (process.env.TFX_NO_AUTO_ATTACH === "1") flags.noAutoAttach = true;
+
+  return { agent, prompt, mcp, flags };
+}
+
+function autoRoute(updatedCommand, reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      updatedInput: { command: updatedCommand },
+      additionalContext: reason,
+    },
+  }));
+  process.exit(0);
+}
+
+const HEADLESS_FALLBACK_COMMAND =
+  'Bash("tfx multi --teammate-mode headless --assign \'codex:prompt:role\' ...")';
+const DIRECT_CLI_BYPASS_HINT =
+  "로컬 디버깅이 목적이면 TFX_ALLOW_DIRECT_CLI=1로 일시 우회할 수 있습니다.";
+
+async function main() {
+  // P0: TFX_ALLOW_DIRECT_CLI 환경변수 바이패스 — psmux 세션 생성 불가 시 수동 활성화
+  if (process.env.TFX_ALLOW_DIRECT_CLI === "1") {
+    nudge("[headless-guard] direct CLI mode (TFX_ALLOW_DIRECT_CLI=1)");
+  }
+
+  // psmux 미설치 → 전부 통과
+  if (!isPsmuxInstalled()) process.exit(0);
+
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+
+  if (!raw || !raw.trim()) {
+    console.error('[headless-guard] stdin이 비어있습니다 — 기본 허용');
+    process.exit(0);
+  }
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || "";
+  const toolInput = input.tool_input || {};
+
+  // ── Bash ──
+  if (toolName === "Bash") {
+    const cmd = toolInput.command || "";
+
+    // headless 명령은 통과 + dispatch 감지 (A: gate 해제)
+    if (cmd.includes("tfx multi") || cmd.includes("triflux.mjs multi")) {
+      const multiState = readMultiState();
+      if (multiState && cmd.includes("--assign")) {
+        multiState.dispatched = true;
+        multiState.nativeWorkCallsSinceDispatch = 0;
+        writeMultiState(multiState);
+      }
+      process.exit(0);
+    }
+
+    // psmux send-keys / capture-pane은 통과 (pane 내 간접 실행)
+    if (/psmux\s+(send-keys|capture-pane|list-panes|split-window|select-pane)/.test(cmd)) {
+      process.exit(0);
+    }
+
+    // codex/gemini 직접 CLI 호출 → deny (인라인 TFX_ALLOW_DIRECT_CLI=1 우회 허용)
+    // 복합 명령(&&, ||, ;) 분리 후 각 세그먼트의 커맨드 위치만 검사 (args/quotes 안의 codex는 무시)
+    const cmdParts = cmd.split(/\s*(?:&&|\|\||;)\s*/);
+    const hasDirectCli = cmdParts.some(part => {
+      const stripped = part.replace(/^\s*(?:[\w_]+=\S+\s+)*/, "");
+      return /^\s*codex\b.*\bexec\b/i.test(stripped) || /^\s*gemini\s+(-p|--prompt)\b/i.test(stripped);
+    });
+    if (hasDirectCli) {
+      if (/\bTFX_ALLOW_DIRECT_CLI=1\b/.test(cmd)) {
+        nudge("[headless-guard] direct CLI mode (inline TFX_ALLOW_DIRECT_CLI=1)");
+      }
+      deny(
+        "[headless-guard] codex/gemini 직접 호출은 spawn-session에서 차단됩니다. " +
+        `승인된 경로: ${HEADLESS_FALLBACK_COMMAND}. ` +
+        DIRECT_CLI_BYPASS_HINT,
+      );
+    }
+
+    // tfx-route.sh 실행만 감지: 명령이 bash로 시작할 때만 (커밋 메시지/echo 등 무시)
+    if (/^\s*bash\s+.*tfx-route\.sh\s/.test(cmd)) {
+      // --async, --job-status, --job-result, --job-wait는 tfx-route.sh 내부 플래그 → 통과
+      if (/tfx-route\.sh\s+--(async|job-status|job-result|job-wait)\b/.test(cmd)) {
+        process.exit(0);
+      }
+
+      const parsed = parseRouteCommand(cmd);
+      if (parsed) {
+        // P1a: 단일 워커는 headless 변환 건너뛰기 (직접 실행이 523~1173ms 절약)
+        // TFX_FORCE_HEADLESS=1이면 단일이어도 headless 변환 강제
+        if (!process.env.TFX_FORCE_HEADLESS) {
+          const isMultiWorker = /\s--(multi|parallel)\b/.test(cmd);
+          if (!isMultiWorker) {
+            process.exit(0);  // 원본 tfx-route.sh 명령 그대로 통과
+          }
+        }
+
+        const safePrompt = parsed.prompt.replace(/'/g, "'\\''");
+        const VALID_MCP = new Set(["implement", "analyze", "review", "docs"]);
+        const f = parsed.flags || {};
+
+        // v3: 플래그 빌더 — 하드코딩 제거, 원본 의도 보존
+        const parts = ["tfx multi --teammate-mode headless"];
+        if (!f.noAutoAttach) parts.push("--auto-attach");
+        if (!f.noAutoAttach) parts.push("--dashboard");  // 워커 요약 스플릿이 기본
+        if (f.verbose) parts.push("--verbose");
+        parts.push(`--assign '${parsed.agent}:${safePrompt}:${parsed.agent}'`);
+        if (parsed.mcp && VALID_MCP.has(parsed.mcp)) parts.push(`--mcp-profile ${parsed.mcp}`);
+        parts.push(`--timeout ${f.timeout || 600}`);
+
+        const builtCmd = parts.join(" ");
+        autoRoute(
+          builtCmd,
+          `[headless-guard] auto-route: tfx-route.sh ${parsed.agent} → headless. mcp=${parsed.mcp} dashboard=${!f.noAutoAttach}`,
+        );
+      }
+      deny(
+        "[headless-guard] tfx-route.sh를 headless로 변환 실패. " +
+        'Bash("tfx multi --teammate-mode headless --assign \'cli:prompt:role\' ...") 형식을 사용하세요.',
+      );
+    }
+  }
+
+  // ── Edit/Write: tfx-multi 코드 수정 게이트 ──
+  if (toolName === "Edit" || toolName === "Write") {
+    const multiState = readMultiState();
+
+    // 일반 모드(tfx-multi 비활성)에서는 기존처럼 통과
+    if (!multiState || !multiState.active) {
+      process.exit(0);
+    }
+
+    if (!multiState.dispatched) {
+      multiState.nativeWorkCalls = (multiState.nativeWorkCalls || 0) + 1;
+      writeMultiState(multiState);
+
+      if (multiState.nativeWorkCalls > GATE_THRESHOLD) {
+        deny(
+          `[headless-guard] tfx-multi gate: ${toolName} 호출 ${multiState.nativeWorkCalls}회 — headless dispatch 먼저 하세요.\n` +
+          'Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign \'codex:프롬프트:역할\' --timeout 600")',
+        );
+      }
+
+      nudge(
+        `[headless-guard] tfx-multi 활성 (${multiState.nativeWorkCalls}/${GATE_THRESHOLD}). ` +
+        "headless dispatch 후 작업을 시작하세요.",
+      );
+    }
+
+    // H3 fix: Agent gate와 동일하게 NUDGE_THRESHOLD 기반 주기적 nudge
+    multiState.nativeWorkCallsSinceDispatch = (multiState.nativeWorkCallsSinceDispatch || 0) + 1;
+    writeMultiState(multiState);
+
+    if (multiState.nativeWorkCallsSinceDispatch >= NUDGE_THRESHOLD) {
+      multiState.nativeWorkCallsSinceDispatch = 0;
+      writeMultiState(multiState);
+      nudge("[headless-guard] nudge: headless 워커가 코드 수정 중. 직접 수정은 충돌 위험.");
+    }
+    process.exit(0); // threshold 미만이면 조용히 통과
+  }
+
+  // ── Agent: A(gate) + B(nudge) + CLI 래핑 deny ──
+  if (toolName === "Agent") {
+    const subType = (toolInput.subagent_type || "").toLowerCase();
+    const NATIVE_TYPES = new Set(["explore", "plan", "general-purpose", ""]);
+    const isNative = NATIVE_TYPES.has(subType) || subType.startsWith("oh-my-claudecode:");
+
+    // ── A+B: tfx-multi 상태 기반 처리 ──
+    const multiState = readMultiState();
+    if (multiState && multiState.active && isNative) {
+      if (!multiState.dispatched) {
+        // ── A: gate — dispatch 전, Agent 작업 위임 제한 ──
+        multiState.nativeWorkCalls = (multiState.nativeWorkCalls || 0) + 1;
+        writeMultiState(multiState);
+
+        if (multiState.nativeWorkCalls > GATE_THRESHOLD) {
+          deny(
+            `[headless-guard] tfx-multi gate: Agent(${subType || "default"}) 호출 ${multiState.nativeWorkCalls}회 — headless에 먼저 dispatch하세요.\n` +
+            'Bash("tfx multi --teammate-mode headless --auto-attach --dashboard --assign \'codex:프롬프트:역할\' --timeout 600")',
+          );
+        }
+        // 허용 범위 내 → 경고 + 통과
+        nudge(
+          `[headless-guard] tfx-multi 활성 (${multiState.nativeWorkCalls}/${GATE_THRESHOLD}). ` +
+          "headless dispatch 후 작업을 시작하세요.",
+        );
+      } else {
+        // ── B: nudge — dispatch 후, 네이티브 드리프트 감지 ──
+        multiState.nativeWorkCallsSinceDispatch = (multiState.nativeWorkCallsSinceDispatch || 0) + 1;
+        writeMultiState(multiState);
+
+        if (multiState.nativeWorkCallsSinceDispatch >= NUDGE_THRESHOLD) {
+          multiState.nativeWorkCallsSinceDispatch = 0;
+          writeMultiState(multiState);
+          nudge(
+            "[headless-guard] nudge: headless 워커가 실행 중입니다. " +
+            "결과를 기다리거나 추가 --assign으로 위임하세요.",
+          );
+        }
+      }
+      // native → 통과 (gate deny 안 걸린 경우)
+      process.exit(0);
+    }
+
+    // native → 통과 (tfx-multi 비활성)
+    if (isNative) process.exit(0);
+
+    // ── CLI 래핑 체크 (기존) ──
+    const combined = `${(toolInput.prompt || "").toLowerCase()} ${(toolInput.description || "").toLowerCase()}`;
+    const cliPatterns = [
+      /codex\s+(exec|run|실행)/,
+      /gemini\s+(-p|run|실행)/,
+      /tfx-route/,
+      /bash.*codex/,
+      /bash.*gemini/,
+    ];
+
+    if (cliPatterns.some((p) => p.test(combined))) {
+      deny(
+        "[headless-guard] Codex/Gemini를 Agent()로 래핑하지 마세요. " +
+        `승인된 경로: ${HEADLESS_FALLBACK_COMMAND}. ` +
+        DIRECT_CLI_BYPASS_HINT,
+      );
+    }
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scripts/hub-ensure.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// SessionStart 훅에서 호출되는 Hub 보장 스크립트.
+// - /status 기반 헬스체크
+// - 비정상 시 Hub를 detached로 기동
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+
+function formatHostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+function buildHubBaseUrl(host, port) {
+  return `http://${formatHostForUrl(host)}:${port}`;
+}
+
+function resolveHubTarget() {
+  const envPortRaw = Number(process.env.TFX_HUB_PORT || "");
+  const envPort = Number.isFinite(envPortRaw) && envPortRaw > 0 ? envPortRaw : null;
+  const target = {
+    host: "127.0.0.1",
+    port: envPort || 27888,
+  };
+
+  if (existsSync(HUB_PID_FILE)) {
+    try {
+      const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+      if (!envPort) {
+        const pidPort = Number(info?.port);
+        if (Number.isFinite(pidPort) && pidPort > 0) target.port = pidPort;
+      }
+      if (typeof info?.host === "string") {
+        const host = info.host.trim();
+        if (LOOPBACK_HOSTS.has(host)) target.host = host;
+      }
+    } catch {
+      // ignore parse errors and use env/default
+    }
+  }
+
+  return target;
+}
+
+async function isHubHealthy(host, port) {
+  try {
+    const res = await fetch(`${buildHubBaseUrl(host, port)}/status`, {
+      signal: AbortSignal.timeout(1000),
+    });
+    if (!res.ok) return false;
+    const data = await res.json();
+    return data?.hub?.state === "healthy";
+  } catch {
+    return false;
+  }
+}
+
+function startHubDetached(port) {
+  const serverPath = join(PLUGIN_ROOT, "hub", "server.mjs");
+  if (!existsSync(serverPath)) return false;
+
+  try {
+    const env = { ...process.env, TFX_HUB_PORT: String(port) };
+    if (process.platform === "win32") {
+      // Windows: cmd.exe /c start /b → 완전 독립 프로세스 트리 생성
+      // hook timeout 시 프로세스 트리 킬에서 살아남음
+      const child = spawn("cmd.exe", ["/c", "start", "/b", "", process.execPath, serverPath], {
+        env,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.unref();
+    } else {
+      const child = spawn(process.execPath, [serverPath], {
+        env,
+        detached: true,
+        stdio: "ignore",
+      });
+      child.unref();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Hub 기동 후 ready 상태까지 대기 (최대 maxWaitMs) */
+async function waitForHubReady(host, port, maxWaitMs = 5000) {
+  const interval = 250;
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    if (await isHubHealthy(host, port)) return true;
+    await new Promise((r) => setTimeout(r, interval));
+  }
+  return false;
+}
+
+const { host, port } = resolveHubTarget();
+if (!(await isHubHealthy(host, port))) {
+  const started = startHubDetached(port);
+  if (started) {
+    const ready = await waitForHubReady(host, port, 3000);
+    if (ready) {
+      process.stdout.write("hub: ok");
+    } else {
+      // fire-and-forget: hub이 아직 기동 중일 수 있음 — 에러가 아닌 경고
+      process.stdout.write("hub: starting");
+    }
+  } else {
+    process.stderr.write("[hub-ensure] hub 시작 실패");
+  }
+} else {
+  process.stdout.write("hub: ok");
+}