triflux 10.0.0 → 10.0.2

package/hub/lib/process-utils.mjs

@@ -0,0 +1,361 @@
+// hub/lib/process-utils.mjs
+// 프로세스 관련 공유 유틸리티
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { IS_WINDOWS, killProcess } from "../platform.mjs";
+
+const CLEANUP_SCRIPT_DIR = join(tmpdir(), "tfx-process-utils");
+const SCAN_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "scan-processes.ps1");
+const TREE_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "get-ancestor-tree.ps1");
+
+// 스크립트 버전 — 내용 변경 시 증가하여 캐시된 스크립트를 갱신
+const SCRIPT_VERSION = 3;
+const VERSION_FILE = join(CLEANUP_SCRIPT_DIR, ".version");
+
+/**
+ * 주어진 PID의 프로세스가 살아있는지 확인한다.
+ * EPERM: 프로세스는 존재하지만 signal 권한 없음 → alive
+ * ESRCH: 프로세스가 존재하지 않음 → dead
+ */
+export 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;
+  }
+}
+
+/**
+ * 동기적 sleep. Atomics.wait 우선, 불가 시 busy-wait 폴백.
+ */
+function sleepSyncMs(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* spin */ }
+  }
+}
+
+/**
+ * 고아 PID 목록에 SIGTERM → 3초 대기 → SIGKILL 에스컬레이션을 적용한다.
+ * PID 재사용 레이스 방어: SIGTERM 전 alive 확인, SIGKILL 전 재검증.
+ * @param {number[]} orphanPids
+ * @param {Map<number, {ppid: number, name: string}>} [procMap] PID 재사용 감지용 스냅샷
+ * @returns {number} killed count
+ */
+function killWithEscalation(orphanPids, procMap) {
+  if (orphanPids.length === 0) return 0;
+
+  // SIGTERM 전 alive 스냅샷 — 이미 죽은 PID는 카운트에서 제외
+  const aliveBeforeKill = new Set(orphanPids.filter(pid => isPidAlive(pid)));
+
+  for (const pid of aliveBeforeKill) {
+    killProcess(pid, { signal: "SIGTERM" });
+  }
+
+  sleepSyncMs(3000);
+
+  let killed = 0;
+  for (const pid of aliveBeforeKill) {
+    if (isPidAlive(pid)) {
+      // PID 재사용 방어: procMap이 있으면 스캔 시점의 ppid와 현재 ppid 비교
+      // ppid가 변경되었으면 PID가 재사용된 것이므로 kill하지 않���
+      if (procMap) {
+        const snapshot = procMap.get(pid);
+        if (snapshot) {
+          try {
+            const current = execSync(
+              IS_WINDOWS
+                ? `powershell -NoProfile -WindowStyle Hidden -Command "(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction SilentlyContinue).ParentProcessId"`
+                : `ps -o ppid= -p ${pid}`,
+              { encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+            );
+            const currentPpid = Number.parseInt(current.trim(), 10);
+            if (Number.isFinite(currentPpid) && currentPpid !== snapshot.ppid) {
+              continue; // PID 재사용 감지 — skip
+            }
+          } catch {
+            // 조회 실패 시 안전하게 skip
+            continue;
+          }
+        }
+      }
+      killProcess(pid, { signal: "SIGKILL", force: true });
+    }
+    if (!isPidAlive(pid)) killed++;
+  }
+  return killed;
+}
+
+/**
+ * PowerShell 헬퍼 스크립트를 임시 디렉토리에 생성한다.
+ * bash의 $_ 이스케이핑 문제를 피하기 위해 -File로 실행.
+ */
+function ensureHelperScripts() {
+  mkdirSync(CLEANUP_SCRIPT_DIR, { recursive: true });
+
+  // 버전 체크 — 스크립트 갱신 필요 여부
+  let needsUpdate = true;
+  try {
+    if (existsSync(VERSION_FILE)) {
+      const cached = Number.parseInt(readFileSync(VERSION_FILE, "utf8").trim(), 10);
+      if (cached === SCRIPT_VERSION) needsUpdate = false;
+    }
+  } catch {}
+
+  if (needsUpdate) {
+    // 기존 스크립트 삭제 후 재생성
+    try { unlinkSync(SCAN_SCRIPT_PATH); } catch {}
+    try { unlinkSync(TREE_SCRIPT_PATH); } catch {}
+  }
+
+  if (!existsSync(TREE_SCRIPT_PATH)) {
+    writeFileSync(TREE_SCRIPT_PATH, [
+      "param([int]$StartPid)",
+      "$p = $StartPid",
+      "for ($i = 0; $i -lt 10; $i++) {",
+      "    if ($p -le 0) { break }",
+      "    Write-Output $p",
+      '    $parent = (Get-CimInstance Win32_Process -Filter "ProcessId=$p" -ErrorAction SilentlyContinue).ParentProcessId',
+      "    if ($null -eq $parent -or $parent -le 0) { break }",
+      "    $p = $parent",
+      "}",
+    ].join("\n"), "utf8");
+  }
+
+  if (!existsSync(SCAN_SCRIPT_PATH)) {
+    // CLI + 쉘 + 런타임 전체를 스캔하여 PID,ParentPID,Name 출력
+    // codex/claude/pwsh/uvx 누락 시 중간 프로세스가 alive 판정되어 고아 트리 전체가 보호됨
+    // 예: WT(dead)→pwsh(alive,미스캔)→codex→cmd→node — pwsh에서 isPidAlive=true로 끊김
+    writeFileSync(SCAN_SCRIPT_PATH, [
+      "$ErrorActionPreference = 'SilentlyContinue'",
+      "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='bash.exe' OR Name='cmd.exe' OR Name='codex.exe' OR Name='claude.exe' OR Name='pwsh.exe' OR Name='uvx.exe'\" | ForEach-Object {",
+      '    Write-Output "$($_.ProcessId),$($_.ParentProcessId),$($_.Name)"',
+      "}",
+    ].join("\n"), "utf8");
+  }
+
+  if (needsUpdate) {
+    writeFileSync(VERSION_FILE, String(SCRIPT_VERSION), "utf8");
+  }
+}
+
+/**
+ * PID → 루트 조상까지의 체인에서 살아있는 조상이 있는지 확인한다.
+ * 프로세스 맵을 사용하여 O(depth) 탐색.
+ * @param {number} pid
+ * @param {Map<number, {ppid: number, name: string}>} procMap
+ * @param {Set<number>} protectedPids
+ * @returns {boolean} true = 보호됨 (활성 조상 체인이 있음)
+ */
+function hasLiveAncestorChain(pid, procMap, protectedPids) {
+  const visited = new Set();
+  let current = pid;
+
+  while (current > 0 && !visited.has(current)) {
+    visited.add(current);
+
+    if (protectedPids.has(current)) return true;
+
+    const info = procMap.get(current);
+    if (!info) {
+      // 프로세스 맵에 없음 → 살아있는지 직접 확인
+      return isPidAlive(current);
+    }
+
+    const ppid = info.ppid;
+    if (!Number.isFinite(ppid) || ppid <= 0) {
+      // 루트 프로세스 (ppid=0) — 시스템 프로세스이므로 보호
+      return true;
+    }
+
+    // 부모가 맵에 없고 죽었으면 → 고아 체인
+    if (!procMap.has(ppid) && !isPidAlive(ppid)) return false;
+
+    current = ppid;
+  }
+
+  return false;
+}
+
+// kill 대상 프로세스 이름 (Windows)
+// codex/claude도 포함: protectedPids + hasLiveAncestorChain이 활성 인스턴스를 보호하므로
+// 고아(부모 dead + 자식 dead)만 kill됨. pwsh.exe는 사용자 인터랙티브 쉘이므로 제외.
+const KILLABLE_NAMES = new Set([
+  "node.exe", "bash.exe", "cmd.exe", "uvx.exe",
+  "codex.exe", "claude.exe",
+]);
+
+/**
+ * 고아 프로세스 트리를 정리한다 (node.exe + bash.exe + cmd.exe + uvx.exe).
+ * Windows 전용 — Agent 서브프로세스가 MCP 서버, bash 래퍼, cmd 래퍼를 남기는 문제 대응.
+ *
+ * 전략: 부모 체인을 루트까지 추적하여, 체인 중간에 죽은 프로세스가 있으면
+ * 해당 프로세스 아래의 전체 트리를 고아로 판정하고 정리.
+ * 스캔 범위에는 codex/claude/pwsh도 포함하여 체인 추적 정확도를 높인다.
+ *
+ * 보호 대상: 현재 프로세스 조상 트리, Hub PID
+ * @returns {{ killed: number, remaining: number }}
+ */
+export function cleanupOrphanNodeProcesses() {
+  if (!IS_WINDOWS) return cleanupOrphansUnix();
+
+  ensureHelperScripts();
+
+  const myPid = process.pid;
+
+  // Hub PID 보호
+  let hubPid = null;
+  try {
+    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    if (existsSync(hubPidPath)) {
+      const hubInfo = JSON.parse(readFileSync(hubPidPath, "utf8"));
+      hubPid = Number(hubInfo?.pid);
+    }
+  } catch {}
+
+  // 보호 PID 세트: 현재 프로세스 + Hub + 현재 프로세스의 조상 트리
+  const protectedPids = new Set();
+  protectedPids.add(myPid);
+  if (Number.isFinite(hubPid) && hubPid > 0) protectedPids.add(hubPid);
+
+  try {
+    const treeOutput = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${TREE_SCRIPT_PATH}" -StartPid ${myPid}`,
+      { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    for (const line of treeOutput.split(/\r?\n/)) {
+      const pid = Number.parseInt(line.trim(), 10);
+      if (Number.isFinite(pid) && pid > 0) protectedPids.add(pid);
+    }
+  } catch {}
+
+  // 전체 프로세스 맵 구축 (node + bash + cmd + codex + claude + pwsh + uvx)
+  const procMap = new Map();
+  try {
+    const output = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "${SCAN_SCRIPT_PATH}"`,
+      { encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+
+    for (const line of output.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [pidStr, ppidStr, name] = trimmed.split(",");
+      const pid = Number.parseInt(pidStr, 10);
+      const ppid = Number.parseInt(ppidStr, 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        procMap.set(pid, { ppid, name: name || "unknown" });
+      }
+    }
+  } catch {}
+
+  // 고아 판정 + 정리 (SIGTERM → 3s → SIGKILL 에스컬레이션)
+  // CLI 도구(codex/claude/pwsh)는 체인 추적용으로만 스캔 — kill 대상에서 제외
+  const orphanPids = [];
+  for (const [pid, info] of procMap) {
+    if (protectedPids.has(pid)) continue;
+    if (!KILLABLE_NAMES.has(info.name?.toLowerCase())) continue;
+    if (hasLiveAncestorChain(pid, procMap, protectedPids)) continue;
+    orphanPids.push(pid);
+  }
+
+  const killed = killWithEscalation(orphanPids, procMap);
+
+  // 남은 프로세스 수 확인
+  let remaining = 0;
+  try {
+    const countOutput = execSync(
+      `powershell -NoProfile -WindowStyle Hidden -Command "(Get-Process node -ErrorAction SilentlyContinue).Count"`,
+      { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    remaining = Number.parseInt(countOutput.trim(), 10) || 0;
+  } catch {}
+
+  return { killed, remaining };
+}
+
+/**
+ * Unix/macOS 고아 프로세스 정리.
+ * `ps -eo pid,ppid,comm` 기반 프로세스 맵 → 동일한 조상 체인 판정 → SIGKILL 에스컬레이션.
+ * @returns {{ killed: number, remaining: number }}
+ */
+function cleanupOrphansUnix() {
+  const myPid = process.pid;
+
+  // Hub PID 보호
+  const protectedPids = new Set();
+  protectedPids.add(myPid);
+  try {
+    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    if (existsSync(hubPidPath)) {
+      const hubPid = Number(JSON.parse(readFileSync(hubPidPath, "utf8"))?.pid);
+      if (Number.isFinite(hubPid) && hubPid > 0) protectedPids.add(hubPid);
+    }
+  } catch {}
+
+  // 현재 프로세스의 조상 트리 보호
+  try {
+    let current = myPid;
+    for (let i = 0; i < 10; i++) {
+      protectedPids.add(current);
+      const output = execSync(`ps -o ppid= -p ${current}`, {
+        encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+      });
+      const ppid = Number.parseInt(output.trim(), 10);
+      if (!Number.isFinite(ppid) || ppid <= 1) break;
+      current = ppid;
+    }
+  } catch {}
+
+  // 프로세스 맵 구축 (런타임 + CLI — 체인 추적 정확도를 위해 CLI도 포함)
+  const procMap = new Map();
+  try {
+    const output = execSync("ps -eo pid,ppid,comm", {
+      encoding: "utf8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"],
+    });
+    for (const line of output.split("\n").slice(1)) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 3) continue;
+      const pid = Number.parseInt(parts[0], 10);
+      const ppid = Number.parseInt(parts[1], 10);
+      const name = parts.slice(2).join(" ");
+      if (Number.isFinite(pid) && pid > 0 && /^(node|bash|sh|python|codex|claude|uvx)/.test(name)) {
+        procMap.set(pid, { ppid, name });
+      }
+    }
+  } catch {}
+
+  // kill 대상: node, python, codex, claude, uvx — bash/sh는 사용자 인터랙티브 쉘 가능성
+  const killableUnix = /^(node|python|codex|claude|uvx)/;
+
+  // 고아 판정 + SIGKILL 에스컬레이션
+  const orphanPids = [];
+  for (const [pid, info] of procMap) {
+    if (protectedPids.has(pid)) continue;
+    if (!killableUnix.test(info.name)) continue;
+    if (hasLiveAncestorChain(pid, procMap, protectedPids)) continue;
+    orphanPids.push(pid);
+  }
+
+  const killed = killWithEscalation(orphanPids, procMap);
+
+  let remaining = 0;
+  try {
+    const output = execSync("ps -eo comm | grep -c '^node$'", {
+      encoding: "utf8", timeout: 3000, stdio: ["pipe", "pipe", "pipe"],
+    });
+    remaining = Number.parseInt(output.trim(), 10) || 0;
+  } catch {}
+
+  return { killed, remaining };
+}

package/hub/lib/ssh-command.mjs

@@ -0,0 +1,211 @@
+// hub/lib/ssh-command.mjs — OS-aware SSH command builder
+// PowerShell 호스트에 bash 문법(2>/dev/null, &&, $())을 보내는 사고를 방지한다.
+// 모든 SSH 명령 생성 코드에서 이 유틸리티를 사용할 것.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** hosts.json 캐시 (프로세스 수명 동안 유지) */
+let hostsCache = null;
+
+/**
+ * hosts.json을 로드하여 캐시한다.
+ * @param {string} [repoRoot] — 프로젝트 루트 경로
+ */
+function loadHostsCache(repoRoot) {
+  if (hostsCache) return;
+  try {
+    const hostsPath = repoRoot
+      ? join(repoRoot, "references", "hosts.json")
+      : join(process.cwd(), "references", "hosts.json");
+    hostsCache = JSON.parse(readFileSync(hostsPath, "utf8"));
+  } catch {
+    hostsCache = { hosts: {} };
+  }
+}
+
+/**
+ * hosts.json에서 호스트 OS를 조회한다.
+ * @param {string} hostAlias — hosts.json의 키 (e.g. "ultra4")
+ * @param {string} [repoRoot] — 프로젝트 루트 경로
+ * @returns {"windows"|"posix"} 호스트 OS 유형
+ */
+export function detectHostOs(hostAlias, repoRoot) {
+  loadHostsCache(repoRoot);
+
+  const hostCfg = hostsCache.hosts?.[hostAlias];
+  if (hostCfg?.os === "windows") return "windows";
+  if (hostCfg?.os) return "posix";
+
+  // IP 주소나 unknown alias → posix 기본값
+  return "posix";
+}
+
+/**
+ * OS에 맞는 셸 쿼팅을 적용한다.
+ * - posix: 싱글쿼트 래핑 + 내부 싱글쿼트 이스케이프
+ * - windows: PowerShell 싱글쿼트 래핑 + 내부 싱글쿼트 더블링
+ * @param {string} value
+ * @param {"windows"|"posix"} os
+ * @returns {string}
+ */
+export function shellQuoteForHost(value, os) {
+  const s = String(value);
+  if (os === "windows") {
+    // PowerShell: 싱글쿼트 내부에서 '' 로 이스케이프
+    return `'${s.replace(/'/g, "''")}'`;
+  }
+  // POSIX: 싱글쿼트 내부에서 '\'' 로 이스케이프
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * OS에 맞는 stderr 억제 구문을 반환한다.
+ * @param {"windows"|"posix"} os
+ * @returns {string} "2>$null" 또는 "2>/dev/null"
+ */
+export function suppressStderr(os) {
+  return os === "windows" ? "2>$null" : "2>/dev/null";
+}
+
+/**
+ * OS에 맞는 명령 연결자를 반환한다.
+ * @param {"windows"|"posix"} os
+ * @returns {string} "; " (PowerShell) 또는 " && " (bash)
+ */
+export function commandJoin(os) {
+  return os === "windows" ? "; " : " && ";
+}
+
+/**
+ * OS에 맞는 null 디바이스 경로를 반환한다.
+ * @param {"windows"|"posix"} os
+ * @returns {string}
+ */
+export function nullDevice(os) {
+  return os === "windows" ? "$null" : "/dev/null";
+}
+
+/**
+ * SSH execFileSync 인자 배열을 안전하게 구성한다.
+ * psmux 명령처럼 원격 셸에서 실행할 명령을 배열로 받아
+ * 적절한 쿼팅을 적용한 SSH 인자 배열을 반환한다.
+ *
+ * @param {string} host — SSH 호스트 (user@ip 또는 alias)
+ * @param {string[]} remoteCmd — 원격에서 실행할 명령 + 인자
+ * @param {object} [opts]
+ * @param {number} [opts.connectTimeout=5] — SSH 연결 타임아웃(초)
+ * @param {boolean} [opts.keepalive=true] — ServerAliveInterval/CountMax 활성화
+ * @param {"windows"|"posix"} [opts.os] — 호스트 OS (미지정 시 자동 감지)
+ * @param {string} [opts.repoRoot] — hosts.json 탐색 경로
+ * @returns {string[]} execFileSync('ssh', returnValue) 형태로 사용
+ */
+export function buildSshArgs(host, remoteCmd, opts = {}) {
+  const connectTimeout = opts.connectTimeout ?? 5;
+  const keepalive = opts.keepalive !== false;
+  const hostAlias = host.includes("@") ? host.split("@").pop() : host;
+  const os = opts.os ?? detectHostOs(hostAlias, opts.repoRoot);
+
+  // 명령어(첫 요소)는 쿼팅하지 않고, 인자만 쿼팅
+  const [cmd, ...args] = remoteCmd;
+  const quotedArgs = args.map((a) => shellQuoteForHost(a, os));
+  const remoteCmdStr = [cmd, ...quotedArgs].join(" ");
+
+  const sshArgs = [
+    "-o", `ConnectTimeout=${connectTimeout}`,
+    "-o", "BatchMode=yes",
+  ];
+
+  if (keepalive) {
+    sshArgs.push("-o", "ServerAliveInterval=30", "-o", "ServerAliveCountMax=3");
+  }
+
+  sshArgs.push(host, remoteCmdStr);
+  return sshArgs;
+}
+
+/**
+ * 검증: 문자열에 호스트 OS와 맞지 않는 셸 문법이 포함되었는지 검사한다.
+ * SSH 명령 생성 시 안전 게이트로 사용.
+ *
+ * @param {string} command — 원격 실행할 명령 문자열
+ * @param {"windows"|"posix"} os — 대상 호스트 OS
+ * @returns {{ safe: boolean, violations: string[] }}
+ */
+export function validateCommandForOs(command, os) {
+  const violations = [];
+
+  if (os === "windows") {
+    // PowerShell에서 해석 불가능한 bash 문법 검출
+    if (/2>\/dev\/null/.test(command)) {
+      violations.push("2>/dev/null → PowerShell에서는 2>$null 사용");
+    }
+    if (/\$\(/.test(command) && !/\$\(/.test(command) === false) {
+      // $() bash substitution vs PowerShell $() — 문맥 의존
+      // PowerShell도 $()를 사용하므로 여기선 경고만
+    }
+    if (/\s&&\s/.test(command)) {
+      violations.push("&& → PowerShell에서는 ; 또는 -and 사용");
+    }
+    if (/\s\|\|\s/.test(command)) {
+      violations.push("|| → PowerShell에서는 ; 또는 -or 사용");
+    }
+    if (/>\s*\/dev\/null/.test(command)) {
+      violations.push(">/dev/null → PowerShell에서는 >$null 사용");
+    }
+  }
+
+  return { safe: violations.length === 0, violations };
+}
+
+/**
+ * hosts.json에서 호스트 전체 설정을 조회한다.
+ * @param {string} hostAlias — hosts.json의 키 (e.g. "ultra4")
+ * @param {string} [repoRoot]
+ * @returns {object|null}
+ */
+export function getHostConfig(hostAlias, repoRoot) {
+  loadHostsCache(repoRoot);
+  return hostsCache.hosts?.[hostAlias] ?? null;
+}
+
+/**
+ * 별칭(alias)으로 호스트 키를 찾는다.
+ * @param {string} alias — 호스트 키 또는 aliases 배열 내 값
+ * @param {string} [repoRoot]
+ * @returns {string|null} 호스트 키 (e.g. "ultra4") 또는 null
+ */
+export function resolveHostAlias(alias, repoRoot) {
+  loadHostsCache(repoRoot);
+
+  if (hostsCache.hosts?.[alias]) return alias;
+
+  for (const [name, cfg] of Object.entries(hostsCache.hosts || {})) {
+    if (cfg.aliases?.includes(alias)) return name;
+  }
+
+  return null;
+}
+
+/**
+ * 특정 capability를 보유한 호스트 목록을 반환한다.
+ * @param {string} capability — e.g. "codex", "claude", "gpu"
+ * @param {string} [repoRoot]
+ * @returns {Array<{ name: string, config: object }>}
+ */
+export function selectHostForCapability(capability, repoRoot) {
+  loadHostsCache(repoRoot);
+
+  const matches = [];
+  for (const [name, cfg] of Object.entries(hostsCache.hosts || {})) {
+    if (cfg.capabilities?.includes(capability)) {
+      matches.push({ name, config: cfg });
+    }
+  }
+  return matches;
+}
+
+/** hosts.json 캐시 초기화 (테스트용) */
+export function resetHostsCache() {
+  hostsCache = null;
+}

package/hub/lib/ssh-retry.mjs

@@ -0,0 +1,59 @@
+// hub/lib/ssh-retry.mjs — SSH command retry with exponential backoff
+// transient SSH 에러(connection reset, broken pipe 등)를 감지하여 자동 재시도한다.
+
+import { execFileSync } from "node:child_process";
+
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BASE_DELAY_MS = 1000;
+
+/** transient SSH 에러 패턴 */
+const TRANSIENT_RE =
+  /connection (reset|refused|timed out)|broken pipe|network is unreachable|ssh_exchange_identification|kex_exchange_identification/i;
+
+/**
+ * execFileSync('ssh', args) 를 retry 래핑한다.
+ * transient 에러만 재시도하고, 그 외 에러는 즉시 throw.
+ *
+ * @param {string[]} args — ssh 인자 배열
+ * @param {object} [opts] — execFileSync 옵션 + retry 설정
+ * @param {number} [opts.maxRetries=2]
+ * @param {number} [opts.baseDelayMs=1000]
+ * @returns {string|Buffer} ssh stdout
+ */
+export function execSshWithRetry(args, opts = {}) {
+  const { maxRetries = DEFAULT_MAX_RETRIES, baseDelayMs = DEFAULT_BASE_DELAY_MS, ...execOpts } = opts;
+
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return execFileSync("ssh", args, execOpts);
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries && isTransientSshError(err)) {
+        sleepSync(baseDelayMs * 2 ** attempt);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * transient SSH 에러인지 판별한다.
+ * @param {Error} err
+ * @returns {boolean}
+ */
+export function isTransientSshError(err) {
+  const msg = String(err.stderr || err.message || "");
+  return TRANSIENT_RE.test(msg);
+}
+
+/**
+ * 동기 sleep (Atomics.wait 기반).
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/hub/lib/uuidv7.mjs

@@ -0,0 +1,44 @@
+// hub/lib/uuidv7.mjs — UUIDv7 generator (RFC 9562, monotonic)
+import { randomBytes } from 'node:crypto';
+
+let _rndPool = Buffer.alloc(0), _rndOff = 0;
+
+function pooledRandom(n) {
+  if (_rndOff + n > _rndPool.length) {
+    _rndPool = randomBytes(256);
+    _rndOff = 0;
+  }
+  const out = Buffer.from(_rndPool.subarray(_rndOff, _rndOff + n));
+  _rndOff += n;
+  return out;
+}
+
+let _lastMs = 0n;
+let _seq = 0;
+
+/** UUIDv7 생성 (RFC 9562, 단조 증가 보장) */
+export function uuidv7() {
+  let now = BigInt(Date.now());
+  if (now <= _lastMs) {
+    _seq++;
+    if (_seq > 0xfff) {
+      now = _lastMs + 1n;
+      _seq = 0;
+    }
+  } else {
+    _seq = 0;
+  }
+  _lastMs = now;
+  const buf = pooledRandom(16);
+  buf[0] = Number((now >> 40n) & 0xffn);
+  buf[1] = Number((now >> 32n) & 0xffn);
+  buf[2] = Number((now >> 24n) & 0xffn);
+  buf[3] = Number((now >> 16n) & 0xffn);
+  buf[4] = Number((now >> 8n) & 0xffn);
+  buf[5] = Number(now & 0xffn);
+  buf[6] = ((_seq >> 8) & 0x0f) | 0x70;
+  buf[7] = _seq & 0xff;
+  buf[8] = (buf[8] & 0x3f) | 0x80;
+  const h = buf.toString('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}