triflux 10.15.0 → 10.16.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;
@@ -5211,7 +5227,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 +5245,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 +5259,11 @@ async function cmdHub(args = [], options = {}) {
           _closeSync(errFd);
         } catch {}
       }
+      if (logFd !== undefined) {
+        try {
+          _closeSync(logFd);
+        } catch {}
+      }
 
       // PID 파일 확인 (최대 3초 대기, 100ms 폴링)
       let started = false;

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/server.mjs

@@ -140,7 +140,7 @@ export async function tryReuseExistingHub({
 } = {}) {
   const existing = readCurrentState();
   const existingPort = Number(existing?.port);
-  const requestedPort = parseHubPort(port);
+  const requestedPort = parseHubPort(port) ?? HUB_DEFAULT_PORT;
   const livePeer = detectPeer();
   const livePidPort = parseHubPort(livePeer?.port);
   if (
@@ -150,11 +150,7 @@ export async function tryReuseExistingHub({
   ) {
     return null;
   }
-  if (requestedPort && existingPort !== requestedPort) {
-    if (portSpecified) return null;
-    if (!livePeer?.alive || !livePidPort || existingPort !== livePidPort) {
-      return null;
-    }
+  if (existingPort !== requestedPort) {
     log.warn(
       {
         requestedPort,
@@ -162,8 +158,9 @@ export async function tryReuseExistingHub({
         pid: livePeer.pid,
         livePidPort,
       },
-      "hub.port_mismatch_reusing_live_pid",
+      "hub.port_mismatch_not_reusing_live_pid",
     );
+    return null;
   }
   if (!(await checkHealth(existingPort))) return null;
 
@@ -237,18 +234,9 @@ function readHubPidFile(
 }
 
 export function resolveHubPort(env = process.env, opts = {}) {
-  const {
-    preferLivePid = true,
-    detectPeer = detectLivePeer,
-    pidFilePath = PID_FILE,
-  } = opts;
+  void opts;
   const envPort = parseHubPort(env?.TFX_HUB_PORT);
   if (envPort) return envPort;
-  if (preferLivePid) {
-    const peer = detectPeer(pidFilePath);
-    const peerPort = parseHubPort(peer?.port);
-    if (peer?.alive && peerPort) return peerPort;
-  }
   return HUB_DEFAULT_PORT;
 }
 

package/hub/team/swarm-cli.mjs

@@ -14,12 +14,18 @@ const YELLOW = "\u001b[93m";
 const GRAY = "\u001b[90m";
 
 /**
- * #116-C: non-TTY background 환경에서 `tfx swarm` 실행은 codex worker spawn 이
- * 무한 hang 한다 (stdin TTY 대기 또는 hub MCP lease race).
+ * #116-C: non-TTY background 환경에서 `tfx swarm` 실행 시 codex worker spawn 이
+ * 무한 hang 가능성이 있다 (stdin TTY 대기 또는 hub MCP lease race).
  *
- * - stdout/stdin 모두 non-TTY 이면 fail-fast — 명시 복구 경로 안내.
- * - `TFX_ALLOW_NON_TTY_SWARM=1` opt-in 시 경고만 남기고 통과 (테스트/CI).
- * - pure function — 테스트하기 쉽게 deps 주입 가능.
+ * Policy (v10.15+):
+ * - stdout 또는 stdin 중 하나라도 TTY → silent OK (기존 동작).
+ * - 양측 non-TTY → warning + 진행 (기본, 사용자 친화 + CI/background 호환).
+ * - `TFX_BLOCK_NON_TTY_SWARM=1` opt-out → fail-fast + 복구 경로 안내 (안전 망).
+ * - `TFX_ALLOW_NON_TTY_SWARM=1` 은 silent OK (호환 유지, warning suppress).
+ *
+ * 기존 fail-fast 정책은 첫 사용자에게 묻기 효과 (실제 user terminal 은 TTY 인데
+ * Claude Code run_in_background 같은 spawn 환경에서 child stdio 는 non-TTY).
+ * 다른 사용자도 동일 마찰 → 기본 동작을 "proceed with warning" 으로 변경.
  *
  * @param {{
  *   stdoutIsTTY?: boolean,
@@ -44,21 +50,25 @@ export function assertTtyForSwarm(deps = {}) {
     return { ok: true, optIn: false, warnings };
   }
 
+  // 양측 non-TTY 부터 적용되는 정책.
+  if (env.TFX_BLOCK_NON_TTY_SWARM === "1") {
+    const reason =
+      "tfx swarm 이 차단됨 — non-TTY 환경 + TFX_BLOCK_NON_TTY_SWARM=1 (#116-C).\n" +
+      "  복구 경로:\n" +
+      "    1) 터미널에서 직접 실행: tfx swarm <prd>\n" +
+      "    2) TFX_BLOCK_NON_TTY_SWARM=0 (또는 unset) 으로 차단 해제 후 재시도";
+    return { ok: false, optIn: false, warnings, reason };
+  }
+
   if (env.TFX_ALLOW_NON_TTY_SWARM === "1") {
-    warnings.push(
-      "non-TTY 환경 감지 — TFX_ALLOW_NON_TTY_SWARM=1 opt-in 으로 진행합니다. codex worker spawn hang 가능성 존재 (#116-C).",
-    );
+    // 명시 opt-in — silent OK (기존 호환, warning 미출력).
     return { ok: true, optIn: true, warnings };
   }
 
-  const reason =
-    "tfx swarm 은 TTY 가 필요합니다 — non-TTY 환경 (run_in_background, nohup 등) 에서 codex worker spawn 이 hang 합니다 (#116-C).\n" +
-    "  복구 경로:\n" +
-    "    1) 터미널에서 직접 실행: tfx swarm <prd>\n" +
-    "    2) tmux 경로: tfx multi --teammate-mode tmux --auto-attach --dashboard --assign ...\n" +
-    "    3) opt-in (위험): TFX_ALLOW_NON_TTY_SWARM=1 tfx swarm <prd>";
-
-  return { ok: false, optIn: false, warnings, reason };
+  warnings.push(
+    "non-TTY 환경 감지 — codex worker spawn hang 가능성 존재 (#116-C). 차단하려면 TFX_BLOCK_NON_TTY_SWARM=1.",
+  );
+  return { ok: true, optIn: true, warnings };
 }
 
 export function parseFlags(args) {