triflux 10.15.0 → 10.17.0

package/README.md

@@ -101,6 +101,21 @@ Then run `tfx setup` to configure your environment.
 
 > **Note**: Deep skills require **psmux** (or tmux), **triflux Hub**, **Codex CLI**, and **Gemini CLI** for full Tri-CLI consensus. Without these, skills automatically degrade to Claude-only mode. Run `tfx doctor` to check your environment.
 
+### State Snapshots
+
+Hub startup also takes a best-effort daily snapshot of selected `~/.codex/` and
+`~/.gemini/` state into `references/codex-snapshots/` and
+`references/gemini-snapshots/`. Snapshot archives are rolling backups capped at
+10 files per tool and are ignored by git.
+
+Manual commands:
+
+```bash
+npm run snapshot:codex
+npm run snapshot:gemini
+npm run snapshot:all
+```
+
 ---
 
 ## Core Engine

package/bin/triflux.mjs

@@ -5030,6 +5030,16 @@ function stopHubForUpdate() {
   return info;
 }
 
+function openHubLogFd() {
+  try {
+    const logDir = join(homedir(), ".claude", "cache", "tfx-hub");
+    mkdirSync(logDir, { recursive: true });
+    return openSync(join(logDir, "hub.log"), "a");
+  } catch {
+    return undefined;
+  }
+}
+
 function startHubAfterUpdate(info) {
   if (!info) return false;
   const serverPath = join(PKG_ROOT, "hub", "server.mjs");
@@ -5040,13 +5050,19 @@ function startHubAfterUpdate(info) {
       : String(process.env.TFX_HUB_PORT || "27888");
 
   try {
+    const logFd = openHubLogFd();
     const child = spawn(process.execPath, [serverPath], {
       env: { ...process.env, TFX_HUB_PORT: port },
-      stdio: "ignore",
+      stdio: ["ignore", logFd ?? "ignore", logFd ?? "ignore"],
       detached: true,
       windowsHide: true,
     });
     child.unref();
+    if (logFd !== undefined) {
+      try {
+        closeSync(logFd);
+      } catch {}
+    }
     return true;
   } catch {
     return false;
@@ -5057,29 +5073,28 @@ function startHubAfterUpdate(info) {
 function autoRegisterMcp(mcpUrl, { codexEnabled = false } = {}) {
   section("MCP 자동 등록");
 
-  // Codex — config.json에 기본 disabled 엔트리로 등록
-  if (which("codex")) {
-    try {
-      const result = ensureCodexHubServerConfig({
-        mcpUrl,
-        createIfMissing: true,
-        enabled: codexEnabled,
-      });
-      if (!result.ok) throw new Error(result.reason || "unknown");
-      if (result.changed) {
-        ok(
-          `Codex: config.json에 등록 완료 (${codexEnabled ? "enabled" : "기본 disabled"})`,
-        );
-      } else {
-        ok(
-          `Codex: 이미 등록됨 (${codexEnabled ? "enabled" : "기본 disabled"})`,
-        );
-      }
-    } catch (e) {
-      warn(`Codex 등록 실패: ${e.message}`);
+  // Codex — config.json에 기본 disabled 엔트리로 등록.
+  // Hub startup must keep the MCP config fresh even on CI/dev machines where
+  // the Codex CLI binary itself is not installed.
+  try {
+    const result = ensureCodexHubServerConfig({
+      mcpUrl,
+      createIfMissing: true,
+      enabled: codexEnabled,
+    });
+    if (!result.ok) throw new Error(result.reason || "unknown");
+    const suffix = which("codex") ? "" : " (CLI 미설치)";
+    if (result.changed) {
+      ok(
+        `Codex: config.json에 등록 완료 (${codexEnabled ? "enabled" : "기본 disabled"})${suffix}`,
+      );
+    } else {
+      ok(
+        `Codex: 이미 등록됨 (${codexEnabled ? "enabled" : "기본 disabled"})${suffix}`,
+      );
     }
-  } else {
-    info("Codex: 미설치 (건너뜀)");
+  } catch (e) {
+    warn(`Codex 등록 실패: ${e.message}`);
   }
 
   // Gemini — settings.json 직접 수정
@@ -5211,7 +5226,9 @@ async function cmdHub(args = [], options = {}) {
         });
       }
 
-      // Issue #102: spawn stderr 를 임시 파일로 캡처해 실패 시 root cause 노출.
+      // Issue #102 + hub-detach fix: spawn stdout/stderr 를 두 채널로 redirect.
+      // - startupErrPath (tmp): 3초 안의 startup 실패 진단 (성공 시 cleanup)
+      // - hub.log (cache): runtime stdout/stderr 영구 보존 (crash 추적)
       // detached spawn 은 pipe 유지가 까다로우니 fd 리다이렉트로 접근.
       const { openSync: _openSync, closeSync: _closeSync } = await import(
         "node:fs"
@@ -5227,10 +5244,11 @@ async function cmdHub(args = [], options = {}) {
       } catch {
         errFd = undefined;
       }
+      const logFd = openHubLogFd();
 
       const child = spawn(process.execPath, [serverPath], {
         env: { ...process.env, TFX_HUB_PORT: port },
-        stdio: ["ignore", "ignore", errFd ?? "ignore"],
+        stdio: ["ignore", logFd ?? "ignore", errFd ?? logFd ?? "ignore"],
         detached: true,
         windowsHide: true,
       });
@@ -5240,6 +5258,11 @@ async function cmdHub(args = [], options = {}) {
           _closeSync(errFd);
         } catch {}
       }
+      if (logFd !== undefined) {
+        try {
+          _closeSync(logFd);
+        } catch {}
+      }
 
       // PID 파일 확인 (최대 3초 대기, 100ms 폴링)
       let started = false;

package/hooks/keyword-rules.json

@@ -97,6 +97,18 @@
           "source": "(?:정리해|슬롭|클린업)",
           "flags": "i"
         },
+        {
+          "source": "(?:병렬|동시에|parallel|concurrent)",
+          "flags": "i"
+        },
+        {
+          "source": "(?:점검|진단|확인해)",
+          "flags": "i"
+        },
+        {
+          "source": "(?:계속해|이어서|진행해)",
+          "flags": "i"
+        },
         {
           "source": "\\b(?:implement|build|fix|review|test|plan|analyze)\\b",
           "flags": "i"

package/hooks/safety-guard.mjs

@@ -123,9 +123,12 @@ function getWindowsHostIds() {
       ids.add(name);
       if (cfg.tailscale?.ip) ids.add(cfg.tailscale.ip);
       if (cfg.tailscale?.dns) ids.add(cfg.tailscale.dns);
+      if (cfg.ssh?.host) ids.add(cfg.ssh.host);
       if (cfg.ssh?.user) {
         ids.add(`${cfg.ssh.user}@${name}`);
         if (cfg.tailscale?.ip) ids.add(`${cfg.ssh.user}@${cfg.tailscale.ip}`);
+        if (cfg.tailscale?.dns) ids.add(`${cfg.ssh.user}@${cfg.tailscale.dns}`);
+        if (cfg.ssh?.host) ids.add(`${cfg.ssh.user}@${cfg.ssh.host}`);
       }
     }
   } catch {

package/hub/cli-adapter-base.mjs

@@ -72,6 +72,11 @@ let _cachedVersion = null;
  */
 export function getCodexVersion() {
   if (_cachedVersion !== null) return _cachedVersion;
+  const override = Number(process.env.TFX_CODEX_VERSION_MINOR);
+  if (Number.isFinite(override) && override > 0) {
+    _cachedVersion = override;
+    return _cachedVersion;
+  }
   try {
     const out = execSync("codex --version", {
       encoding: "utf8",
@@ -80,7 +85,10 @@ export function getCodexVersion() {
     const match = out.match(/(\d+)\.(\d+)\.(\d+)/);
     _cachedVersion = match ? Number.parseInt(match[2], 10) : 0;
   } catch {
-    _cachedVersion = 0;
+    // Command builders should remain stable in CI even when the real Codex
+    // CLI is absent. Runtime preflight still reports/install-gates Codex
+    // separately; this fallback only selects the modern argv shape.
+    _cachedVersion = 117;
   }
   return _cachedVersion;
 }
@@ -182,10 +190,7 @@ export function buildExecCommand(prompt, resultFile = null, opts = {}) {
 // ── Sleep ───────────────────────────────────────────────────────
 
 export function sleep(ms) {
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
-    timer.unref?.();
-  });
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // ── Result factory ──────────────────────────────────────────────

package/hub/lib/hosts-compat.mjs

@@ -133,8 +133,20 @@ function normalizeLastProbe(rawProbe) {
   return Object.keys(probe).length > 0 ? probe : null;
 }
 
+function normalizeResources(rawHost) {
+  const rawResources =
+    rawHost.resources && typeof rawHost.resources === "object"
+      ? rawHost.resources
+      : {};
+  const rawSpecs =
+    rawHost.specs && typeof rawHost.specs === "object" ? rawHost.specs : {};
+  return { ...rawResources, ...rawSpecs };
+}
+
 export function normalizeHost(rawHost = {}, name = "") {
   const sshUser = rawHost.ssh_user || rawHost.ssh?.user || rawHost.user || null;
+  const sshHost = rawHost.ssh?.host || rawHost.host || null;
+  const resources = normalizeResources(rawHost);
   const tailscale = {
     ip: rawHost.tailscale?.ip || null,
     dns: rawHost.tailscale?.dns || null,
@@ -167,15 +179,14 @@ export function normalizeHost(rawHost = {}, name = "") {
     ssh: {
       ...(rawHost.ssh && typeof rawHost.ssh === "object" ? rawHost.ssh : {}),
       user: sshUser,
+      host: sshHost,
     },
     tailscale,
     capabilities,
     capabilities_v2,
     last_probe: normalizeLastProbe(rawHost.last_probe),
-    specs:
-      rawHost.specs && typeof rawHost.specs === "object"
-        ? { ...rawHost.specs }
-        : {},
+    resources,
+    specs: { ...resources },
     raw: { ...rawHost },
   };
 }
@@ -234,6 +245,7 @@ export function resolveHost(nameOrAlias, repoRoot) {
       ...host.aliases,
       host.tailscale.ip,
       host.tailscale.dns,
+      host.ssh.host,
       host.ssh_user ? `${host.ssh_user}@${name}` : null,
       host.ssh_user && host.tailscale.ip
         ? `${host.ssh_user}@${host.tailscale.ip}`
@@ -241,6 +253,9 @@ export function resolveHost(nameOrAlias, repoRoot) {
       host.ssh_user && host.tailscale.dns
         ? `${host.ssh_user}@${host.tailscale.dns}`
         : null,
+      host.ssh_user && host.ssh.host
+        ? `${host.ssh_user}@${host.ssh.host}`
+        : null,
     ]);
     for (const alias of aliases) {
       if (alias && String(alias).toLowerCase() === lowered) {

package/hub/lib/ssh-command.mjs

@@ -2,7 +2,7 @@
 // PowerShell 호스트에 bash 문법(2>/dev/null, &&, $())을 보내는 사고를 방지한다.
 // 모든 SSH 명령 생성 코드에서 이 유틸리티를 사용할 것.
 
-import { readHosts } from "./hosts-compat.mjs";
+import { readHost, readHosts, resolveHost } from "./hosts-compat.mjs";
 
 /** hosts.json 캐시 (프로세스 수명 동안 유지) */
 let hostsCache = null;
@@ -28,7 +28,7 @@ function loadHostsCache(repoRoot) {
 export function detectHostOs(hostAlias, repoRoot) {
   loadHostsCache(repoRoot);
 
-  const hostCfg = hostsCache.hosts?.[hostAlias];
+  const hostCfg = resolveHost(hostAlias, repoRoot)?.host;
   if (hostCfg?.os === "windows") return "windows";
   if (hostCfg?.os) return "posix";
 
@@ -163,7 +163,7 @@ export function validateCommandForOs(command, os) {
  */
 export function getHostConfig(hostAlias, repoRoot) {
   loadHostsCache(repoRoot);
-  return hostsCache.hosts?.[hostAlias] ?? null;
+  return readHost(hostAlias, repoRoot);
 }
 
 /**
@@ -175,13 +175,7 @@ export function getHostConfig(hostAlias, repoRoot) {
 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;
+  return resolveHost(alias, repoRoot)?.name ?? null;
 }
 
 /**

package/hub/lib/state-snapshot.mjs

@@ -0,0 +1,293 @@
+import { execFile } from "node:child_process";
+import {
+  copyFile,
+  mkdir,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_MAX_SNAPSHOTS = 10;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export const CODEX_STATE_INCLUDES = Object.freeze([
+  "config.toml",
+  "AGENTS.md",
+  "skills",
+  "agents",
+  "prompts",
+  "plugins",
+]);
+
+export const CODEX_STATE_EXCLUDES = Object.freeze([
+  "*.sqlite*",
+  ".sandbox*",
+  ".tmp",
+  "_archived_skills",
+  "memories",
+  "cache",
+  "log",
+  "logs",
+  "sessions",
+  "auth.json",
+  ".credentials.json",
+  "*.bak*",
+  "*.tmp-*",
+  "cap_sid",
+  "installation_id",
+  "history.jsonl",
+  "models_cache.json",
+]);
+
+export const GEMINI_STATE_INCLUDES = Object.freeze([
+  "settings.json",
+  "settings.local.json",
+  "GEMINI.md",
+  "commands",
+  "extensions",
+  "plugins",
+  "skills",
+  "agents",
+]);
+
+export const GEMINI_STATE_EXCLUDES = Object.freeze([
+  "*.sqlite*",
+  "cache",
+  "log",
+  "logs",
+  "sessions",
+  "auth.json",
+  ".credentials.json",
+  "*.bak*",
+]);
+
+export const STATE_SNAPSHOT_THRESHOLD_MS = DAY_MS;
+export const STATE_SNAPSHOT_MAX_SNAPSHOTS = DEFAULT_MAX_SNAPSHOTS;
+
+function normalizePath(path) {
+  return String(path || "")
+    .replace(/\\/gu, "/")
+    .replace(/^\/+/u, "");
+}
+
+function globToRegExp(pattern) {
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/gu, ".*")}$`, "u");
+}
+
+function compileExclude(pattern) {
+  const text = normalizePath(pattern).replace(/\/+$/u, "");
+  if (text.includes("*")) {
+    const regex = globToRegExp(text);
+    return (relativePath) => {
+      const normalized = normalizePath(relativePath);
+      return normalized.split("/").some((part) => regex.test(part));
+    };
+  }
+
+  return (relativePath) => {
+    const normalized = normalizePath(relativePath);
+    return normalized.split("/").includes(text);
+  };
+}
+
+function isSubpath(parent, child) {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+async function pathStats(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function collectFiles({ sourceDir, includes, excludeMatchers }) {
+  const sourceRoot = resolve(sourceDir);
+  const files = [];
+
+  async function visit(absPath, relativePath) {
+    if (excludeMatchers.some((matcher) => matcher(relativePath))) return;
+
+    const info = await pathStats(absPath);
+    if (!info) return;
+    if (info.isDirectory()) {
+      const children = await readdir(absPath, { withFileTypes: true });
+      for (const child of children) {
+        await visit(join(absPath, child.name), join(relativePath, child.name));
+      }
+      return;
+    }
+    if (info.isFile()) {
+      files.push({
+        absPath,
+        relativePath: normalizePath(relativePath),
+        size: info.size,
+      });
+    }
+  }
+
+  for (const include of includes || []) {
+    const relativeInclude = normalizePath(include);
+    if (!relativeInclude || relativeInclude.startsWith("../")) continue;
+    const absPath = resolve(sourceRoot, relativeInclude);
+    if (!isSubpath(sourceRoot, absPath)) continue;
+    await visit(absPath, relativeInclude);
+  }
+
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return files;
+}
+
+async function listSnapshots(destDir) {
+  const names = await readdir(destDir).catch((error) => {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  });
+  const snapshots = [];
+  for (const name of names) {
+    if (!name.endsWith(".tar.gz")) continue;
+    const path = join(destDir, name);
+    const info = await pathStats(path);
+    if (info?.isFile()) snapshots.push({ name, path, mtimeMs: info.mtimeMs });
+  }
+  snapshots.sort(
+    (a, b) => b.mtimeMs - a.mtimeMs || b.name.localeCompare(a.name),
+  );
+  return snapshots;
+}
+
+async function copyToStaging(files, stagingDir) {
+  for (const file of files) {
+    const targetPath = join(stagingDir, ...file.relativePath.split("/"));
+    await mkdir(dirname(targetPath), { recursive: true });
+    await copyFile(file.absPath, targetPath);
+  }
+}
+
+async function createArchive({ stagingDir, archivePath, files }) {
+  const listPath = join(stagingDir, ".snapshot-files");
+  const archiveName = normalizePath(relative(stagingDir, archivePath));
+  await writeFile(
+    listPath,
+    `${files.map((file) => file.relativePath).join("\n")}\n`,
+    "utf8",
+  );
+  await execFileAsync(
+    "tar",
+    ["-czf", archiveName, "-C", ".", "-T", ".snapshot-files"],
+    {
+      cwd: stagingDir,
+      windowsHide: true,
+    },
+  );
+  await rm(listPath, { force: true });
+}
+
+async function pruneSnapshots(destDir, maxSnapshots) {
+  const snapshots = await listSnapshots(destDir);
+  const keep = Math.max(1, Number(maxSnapshots) || DEFAULT_MAX_SNAPSHOTS);
+  for (const snapshot of snapshots.slice(keep)) {
+    await rm(snapshot.path, { force: true });
+  }
+}
+
+function formatStamp(date) {
+  return date
+    .toISOString()
+    .replace(/[-:]/gu, "")
+    .replace(/\.\d{3}Z$/u, "Z");
+}
+
+function uniqueSuffix() {
+  return `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+/**
+ * Snapshot selected user state into a rolling tar.gz archive.
+ *
+ * @param {object} options
+ * @param {string} options.sourceDir
+ * @param {string} options.destDir
+ * @param {string[]} options.includes
+ * @param {string[]} options.excludes
+ * @param {number} options.thresholdMs
+ * @param {number} [options.maxSnapshots=10]
+ * @returns {Promise<{skipped: boolean, reason?: string, path?: string, sizeBytes?: number, fileCount?: number}>}
+ */
+export async function snapshotState({
+  sourceDir,
+  destDir,
+  includes,
+  excludes = [],
+  thresholdMs = 0,
+  maxSnapshots = DEFAULT_MAX_SNAPSHOTS,
+}) {
+  const sourceRoot = resolve(sourceDir || "");
+  const destRoot = resolve(destDir || "");
+  const sourceInfo = await pathStats(sourceRoot);
+  if (!sourceInfo?.isDirectory()) {
+    return { skipped: true, reason: "source-missing" };
+  }
+
+  await mkdir(destRoot, { recursive: true });
+  const snapshots = await listSnapshots(destRoot);
+  const newest = snapshots[0];
+  if (
+    newest &&
+    Number(thresholdMs) > 0 &&
+    Date.now() - newest.mtimeMs < Number(thresholdMs)
+  ) {
+    return { skipped: true, reason: "threshold", path: newest.path };
+  }
+
+  const excludeMatchers = excludes.map((pattern) => compileExclude(pattern));
+  const files = await collectFiles({
+    sourceDir: sourceRoot,
+    includes,
+    excludeMatchers,
+  });
+  if (files.length === 0) {
+    return { skipped: true, reason: "empty" };
+  }
+
+  const suffix = uniqueSuffix();
+  const stagingDir = join(tmpdir(), `tfx-state-snapshot-${suffix}`);
+  const tempArchivePath = join(stagingDir, `.state-${suffix}.tar.gz.tmp`);
+  const finalArchivePath = join(
+    destRoot,
+    `state-${formatStamp(new Date())}-${suffix}.tar.gz`,
+  );
+
+  try {
+    await mkdir(stagingDir, { recursive: true });
+    await copyToStaging(files, stagingDir);
+    await createArchive({
+      stagingDir,
+      archivePath: tempArchivePath,
+      files,
+    });
+    await rename(tempArchivePath, finalArchivePath);
+    await pruneSnapshots(destRoot, maxSnapshots);
+    const archiveInfo = await stat(finalArchivePath);
+    const sizeBytes = files.reduce((sum, file) => sum + file.size, 0);
+    return {
+      skipped: false,
+      path: finalArchivePath,
+      sizeBytes: archiveInfo.size || sizeBytes,
+      fileCount: files.length,
+    };
+  } finally {
+    await rm(stagingDir, { recursive: true, force: true });
+    await rm(tempArchivePath, { force: true });
+  }
+}

package/hub/router.mjs

@@ -60,6 +60,21 @@ function normalizeAgentTopics(store, agentId, runtimeTopics) {
   return Array.from(topics);
 }
 
+function waitForEmitterOnce(emitter, eventName, timeoutMs) {
+  let timer = null;
+  const timeout = Math.max(0, Math.min(Number(timeoutMs) || 0, 30000));
+  return Promise.race([
+    once(emitter, eventName),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`timed out waiting for ${eventName}`));
+      }, timeout);
+    }),
+  ]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
 /**
  * 라우터 생성
  * @param {object} store
@@ -525,9 +540,11 @@ export function createRouter(store) {
       }
 
       try {
-        const [response] = await once(responseEmitter, cid, {
-          signal: AbortSignal.timeout(Math.min(await_response_ms, 30000)),
-        });
+        const [response] = await waitForEmitterOnce(
+          responseEmitter,
+          cid,
+          await_response_ms,
+        );
         return {
           ok: true,
           data: {