@triflux/remote 10.74.0 → 10.76.0

package/hub/team/cli/commands/start/parse-args.mjs

@@ -46,7 +46,8 @@ export function parseTeamArgs(args = []) {
   let teammateMode = "auto";
   const taskParts = [];
   const assigns = [];
-  let autoAttach = true;
+  // null 이면 start-headless 가 플랫폼으로 정한다: Windows 만 켬 (ADR-0040)
+  let autoAttach = null;
   let progressive = true;
   let timeoutSec = 0;
   let verbose = false;
@@ -82,6 +83,8 @@ export function parseTeamArgs(args = []) {
     } else if (current === "--assign" && args[index + 1]) {
       const parsed = parseAssignValue(args[++index]);
       if (parsed) assigns.push(parsed);
+    } else if (current === "--auto-attach") {
+      autoAttach = true;
     } else if (current === "--no-auto-attach") {
       autoAttach = false;
     } else if (current === "--verbose") {
@@ -143,7 +146,7 @@ export function parseTeamArgs(args = []) {
         p = p[1].toUpperCase() + ":" + p.slice(2);
       }
       cwd = resolve(p);
-    } else if (current === "--auto-attach" || current === "--dashboard") {
+    } else if (current === "--dashboard") {
       // 이전 설치 스킬이 넘기는 기본값 플래그는 무시한다.
     } else if (current.startsWith("-")) {
       console.warn(`  ⚠ 미인식 플래그 무시: ${current}`);

package/hub/team/cli/commands/start/start-headless.mjs

@@ -107,13 +107,23 @@ export async function startHeadlessTeam({
     );
   }
 
+  // macOS/Linux 는 claude agents 행이 관전 창이라 호출자 tmux 창을 나누지 않는다.
+  // Windows 는 그 행이 없어 WT 탭 attach 를 켠다 (ADR-0040).
+  const platform = _deps.platform || process.platform;
+  const effectiveAutoAttach = autoAttach ?? platform === "win32";
+  if (effectiveAutoAttach && platform !== "win32" && process.env.TMUX_PANE) {
+    ok(
+      "--auto-attach: 호출자 tmux 창을 아래로 30% 나눠 워커 방에 attach 함 (끄기: --no-auto-attach)",
+    );
+  }
+
   let handle;
   try {
     const run = _deps.runHeadlessInteractive || runHeadlessInteractive;
     handle = await run(sessionId, assignments, {
       timeoutSec: timeoutSec || 900,
       layout,
-      autoAttach: !!autoAttach,
+      autoAttach: effectiveAutoAttach,
       leadPane: process.env.TMUX_PANE,
       leadTmux: process.env.TMUX,
       dashboard: !!dashboard,

package/hub/team/cli/help.mjs

@@ -9,6 +9,7 @@ export function renderTeamHelp() {
     ${WHITE}tfx multi --agents codex,antigravity --lead claude "작업"${RESET}
     ${WHITE}tfx multi --teammate-mode tmux "작업"${RESET}
     ${WHITE}tfx multi --teammate-mode headless "작업"${RESET}
+    ${WHITE}tfx multi --auto-attach "작업"${RESET}               ${DIM}(headless: 호출자 tmux 창을 나눠 attach. Windows 는 기본 켬)${RESET}
     ${WHITE}tfx multi --layout 1xN "작업"${RESET}               ${DIM}(세로 분할 컬럼)${RESET}
     ${WHITE}tfx multi --layout Nx1 "작업"${RESET}               ${DIM}(가로 분할 스택)${RESET}
     ${WHITE}tfx multi --dashboard-layout lite "작업"${RESET}    ${DIM}(dashboard-lite 기본 뷰)${RESET}

package/hub/team/cli/services/runtime-mode.mjs

@@ -13,12 +13,14 @@ export function normalizeTeammateMode(mode = "auto", deps = {}) {
       `지원하지 않는 teammate mode: ${mode}; auto, headless, tmux${platform === "win32" ? ", psmux" : ""}를 사용하세요.`,
     );
   }
+  // 비TTY 호출자(파이프, Claude Code Bash 도구, CI)는 대화형 팀에 입력할 수 없고
+  // 결과 색인도 headless 에서만 나온다. tmux 안이라도 headless 로 간다 (ADR-0040).
+  if (!(deps.isTTY ?? Boolean(process.stdout.isTTY))) return "headless";
   if (env.TMUX) return "tmux";
   const mux = detectMux();
   if (mux === "tmux") return "tmux";
   if (platform === "win32" && mux === "psmux") return "psmux";
   if (platform === "win32" && mux === "git-bash-tmux") return "tmux";
-  if (!(deps.isTTY ?? Boolean(process.stdout.isTTY))) return "headless";
   return ensureTmuxOrExit(deps);
 }
 

package/hub/team/psmux.mjs

@@ -997,11 +997,18 @@ function killOrphanMcpProcesses(sessionName) {
 function detachAttachedClients(sessionName, waitMs = 750) {
   const attachedCount = getPsmuxSessionAttachedCount(sessionName);
   if (!Number.isFinite(attachedCount) || attachedCount <= 0) return false;
+  // -t 는 클라이언트 이름이다. 세션에 붙은 클라이언트 전부를 떼려면 -s 로 세션을 주고,
+  // tmux 의 접두사 매칭이 같은 접두사의 다른 세션을 떼지 않게 정확한 타깃을 쓴다.
   try {
-    psmuxExec(["detach-client", "-t", sessionName], { stdio: "ignore" });
+    psmuxExec(["detach-client", "-s", exactSessionTarget(sessionName)], {
+      stdio: "ignore",
+    });
     sleepMs(waitMs);
     return true;
-  } catch {
+  } catch (error) {
+    process.stderr.write(
+      `[psmux] detach-client 실패 (${sessionName}): ${error?.message || error}\n`,
+    );
     return false;
   }
 }

package/hub/team/remote-session.mjs

@@ -1,8 +1,15 @@
 // Remote session primitives.
 // Pure functions + SSH operations. No psmux, no WT, no CLI arg parsing.
 
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync, execSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import {
   basename,
@@ -17,6 +24,45 @@ const REMOTE_ENV_TTL_MS = 86_400_000; // 24h
 const REMOTE_STAGE_ROOT = "tfx-remote";
 const SAFE_HOST_RE = /^[a-zA-Z0-9._-]+$/;
 
+let sshControlDir = null;
+if (process.platform !== "win32" && typeof process.getuid === "function") {
+  // macOS Unix 소켓 경로의 104바이트 제한 때문에 $TMPDIR 대신 /tmp를 쓴다.
+  const dir = `/tmp/tfx-cm-${process.getuid()}`;
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(dir);
+    if (stat.isDirectory() && stat.uid === process.getuid()) {
+      chmodSync(dir, 0o700);
+      sshControlDir = dir;
+    }
+  } catch {}
+}
+
+export function buildSshOptions({
+  interactive = false,
+  platform = process.platform,
+} = {}) {
+  const options = [
+    "-o",
+    "ServerAliveInterval=15",
+    "-o",
+    "ServerAliveCountMax=4",
+  ];
+  if (!interactive)
+    options.push("-o", "BatchMode=yes", "-o", "ConnectTimeout=10");
+  if (platform !== "win32" && sshControlDir) {
+    options.push(
+      "-o",
+      "ControlMaster=auto",
+      "-o",
+      `ControlPath=${sshControlDir}/%C`,
+      "-o",
+      "ControlPersist=60",
+    );
+  }
+  return options;
+}
+
 // ── Shell quoting utilities ─────────────────────────────────────
 
 export function shellQuote(value) {
@@ -76,19 +122,107 @@ function parseProbeLines(text) {
 function normalizePwshProbeEnv(parsed) {
   if (parsed.shell !== "pwsh" || parsed.os !== "win32") return null;
   if (!parsed.home) return null;
+  const psmuxVersion = parsed.psmuxVersion || null;
+  const version = psmuxVersion && parseVersion(psmuxVersion);
   return Object.freeze({
     claudePath:
       !parsed.claude || parsed.claude === "notfound" ? null : parsed.claude,
+    psmuxPath:
+      !parsed.psmux || parsed.psmux === "notfound" ? null : parsed.psmux,
+    psmuxVersion,
+    // tfx-psmux.md 규칙 5의 3.3.x detach 미지원 범위를 제외한다. 3.4.0은 일반 이름도 정확 매칭한다.
+    psmuxSupported: Boolean(
+      parsed.psmux &&
+        parsed.psmux !== "notfound" &&
+        version &&
+        compareVersions(version, [3, 4, 0]) >= 0,
+    ),
     home: parsed.home,
     os: "win32",
     shell: "pwsh",
   });
 }
 
-function normalizePosixProbeEnv(parsed) {
+function parseVersion(versionStr) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(versionStr);
+  if (!match) return null;
+  return [
+    parseInt(match[1], 10),
+    parseInt(match[2], 10),
+    parseInt(match[3], 10),
+  ];
+}
+
+export function compareVersions(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+export function probeVersion(binPath) {
+  try {
+    if (/\.(cmd|bat)$/iu.test(binPath)) {
+      // .cmd/.bat → execSync로 shell 경유 (execFileSync EINVAL 회피)
+      const out = execSync(`"${binPath}" --version`, {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      return parseVersion(out);
+    }
+    const out = execFileSync(binPath, ["--version"], {
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return parseVersion(out);
+  } catch {
+    return null;
+  }
+}
+
+export function normalizePosixProbeEnv(parsed, localVersions = null) {
   const os =
     parsed.os === "darwin" ? "darwin" : parsed.os === "linux" ? "linux" : null;
-  if (!os || !parsed.home) return null;
+  if (!os || !parsed.home) {
+    return null;
+  }
+
+  const versions = Object.fromEntries(
+    ["node", "codex", "agy", "claude", "triflux"].map((name) => [
+      name,
+      parsed[`${name}Version`] || null,
+    ]),
+  );
+  const warnings = [];
+  const memoryPressureLevel =
+    os === "darwin" ? Number(parsed.memoryPressureLevel) || null : null;
+  const memoryFreePct =
+    parsed.memoryFreePct && Number.isFinite(Number(parsed.memoryFreePct))
+      ? Number(parsed.memoryFreePct)
+      : null;
+  const loadAvgValues = parsed.loadAvg?.split(",").map(Number);
+  const loadAvg =
+    loadAvgValues?.length === 3 && loadAvgValues.every(Number.isFinite)
+      ? loadAvgValues
+      : null;
+  const diskFreeHome = parsed.diskFreeHome ? Number(parsed.diskFreeHome) : null;
+
+  if (memoryPressureLevel >= 2) {
+    warnings.push(`memory pressure level ${memoryPressureLevel}`);
+  }
+  if (diskFreeHome !== null && diskFreeHome < 5 * 1024 ** 3) {
+    warnings.push("home disk free below 5 GiB");
+  }
+  for (const [name, remote] of Object.entries(versions)) {
+    const local = localVersions?.[name];
+    const remoteVersion = remote && parseVersion(remote);
+    if (local && remoteVersion && compareVersions(local, remoteVersion) !== 0) {
+      warnings.push(`${name} version differs`);
+    }
+  }
+
   return Object.freeze({
     claudePath:
       !parsed.claude || parsed.claude === "notfound" ? null : parsed.claude,
@@ -96,26 +230,36 @@ function normalizePosixProbeEnv(parsed) {
       !parsed.codex || parsed.codex === "notfound" ? null : parsed.codex,
     geminiPath:
       !parsed.gemini || parsed.gemini === "notfound" ? null : parsed.gemini,
+    tmuxPath: !parsed.tmux || parsed.tmux === "notfound" ? null : parsed.tmux,
+    node: parsed.node || parsed.nodeVersion || null,
+    cores: parsed.cores ? Number(parsed.cores) : null,
+    ramGb: parsed.ram_gb ? Number(parsed.ram_gb) : null,
     home: parsed.home,
+    codexAuthExists: parsed.codexAuthExists === "true",
+    diskFreeHome,
+    loadAvg,
+    memoryFreePct,
+    memoryPressureLevel,
     os,
+    ready: memoryPressureLevel !== 4,
     shell: parsed.shell === "zsh" ? "zsh" : "bash",
-    node: parsed.node || null,
-    cores: parsed.cores ? Number(parsed.cores) : null,
-    ramGb: parsed.ram_gb ? Number(parsed.ram_gb) : null,
+    versions,
+    warnings,
   });
 }
 
-function probeRemoteEnvViaPwsh(host) {
+function probeRemoteEnvViaPwsh(host, execSsh) {
   const command = [
     "Write-Output 'shell=pwsh'",
     'Write-Output "home=$env:USERPROFILE"',
     'if (Test-Path "$env:USERPROFILE\\.local\\bin\\claude.exe") { Write-Output "claude=$env:USERPROFILE\\.local\\bin\\claude.exe" } elseif (Get-Command claude -ErrorAction SilentlyContinue) { Write-Output "claude=$((Get-Command claude).Source)" } else { Write-Output \'claude=notfound\' }',
+    'if (Get-Command psmux -ErrorAction SilentlyContinue) { Write-Output "psmux=$((Get-Command psmux).Source)"; $psmuxVersion = psmux -V 2>$null; if ($LASTEXITCODE -eq 0) { Write-Output "psmuxVersion=$psmuxVersion" } } else { Write-Output \'psmux=notfound\' }',
     "Write-Output \"os=$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::Windows) ? 'win32' : 'other')\"",
   ].join("; ");
 
   try {
-    const output = execSshWithRetry(
-      [host, "pwsh", "-NoProfile", "-Command", command],
+    const output = execSsh(
+      [...buildSshOptions(), host, pwshRemoteCommand(command)],
       {
         encoding: "utf8",
         timeout: 15000,
@@ -130,7 +274,7 @@ function probeRemoteEnvViaPwsh(host) {
   }
 }
 
-function probeRemoteEnvViaPosix(host) {
+function probeRemoteEnvViaPosix(host, execSsh, localVersions) {
   const script = [
     '[ -f "$HOME/.zshenv" ] && . "$HOME/.zshenv" 2>/dev/null || true',
     "export PATH=/opt/homebrew/bin:/opt/homebrew/sbin:$HOME/.local/bin:$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node 2>/dev/null | sort -V | tail -1)/bin:$PATH 2>/dev/null",
@@ -140,22 +284,40 @@ function probeRemoteEnvViaPosix(host) {
     "command -v codex >/dev/null 2>&1 && echo codex=$(command -v codex) || echo codex=notfound",
     "command -v gemini >/dev/null 2>&1 && echo gemini=$(command -v gemini) || echo gemini=notfound",
     "echo os=$(uname -s | tr A-Z a-z)",
-    "node --version 2>/dev/null && echo node=$(node --version) || echo node=notfound",
     // darwin: sysctl, linux: nproc + /proc/meminfo
     "if [ $(uname -s) = Darwin ]; then echo cores=$(sysctl -n hw.ncpu); echo ram_gb=$(($(sysctl -n hw.memsize) / 1073741824)); else echo cores=$(nproc 2>/dev/null || echo 0); echo ram_gb=$(($(grep MemTotal /proc/meminfo 2>/dev/null | awk '{print $2}') / 1048576)); fi",
+    "command -v tmux >/dev/null 2>&1 && echo tmux=$(command -v tmux) || echo tmux=notfound",
+    'if [ "$(uname -s)" = Darwin ]; then',
+    "  printf 'memoryPressureLevel=%s\\n' \"$(sysctl -n kern.memorystatus_vm_pressure_level 2>/dev/null)\"",
+    '  vm_stat | awk -v total="$(sysctl -n hw.memsize 2>/dev/null)" -v pageSize="$(sysctl -n hw.pagesize 2>/dev/null)" \'/Pages free:|Pages inactive:|Pages speculative:/ {gsub(/[^0-9]/, "", $3); pages += $3} END {if (total > 0 && pageSize > 0) printf "memoryFreePct=%.1f\\n", pages * pageSize / total * 100}\'',
+    '  sysctl -n vm.loadavg 2>/dev/null | tr -d \'{}\' | awk \'{print "loadAvg=" $1 "," $2 "," $3}\'',
+    "else",
+    "  awk '/MemTotal:/ {total=$2} /MemAvailable:/ {available=$2} END {if (total > 0) printf \"memoryFreePct=%.1f\\n\", available / total * 100}' /proc/meminfo 2>/dev/null",
+    '  awk \'{print "loadAvg=" $1 "," $2 "," $3}\' /proc/loadavg 2>/dev/null',
+    "fi",
+    'df -Pk "$HOME" 2>/dev/null | awk \'NR==2 {printf "diskFreeHome=%.0f\\n", $4 * 1024}\'',
+    'if [ -f "${CODEX_HOME:-$HOME/.codex}/auth.json" ]; then echo codexAuthExists=true; else echo codexAuthExists=false; fi',
+    ...(localVersions
+      ? [
+          'probe_version() { command -v "$1" >/dev/null 2>&1 && "$1" --version </dev/null 2>/dev/null | head -n 1; }',
+          'for cli in node codex agy claude triflux; do printf \'%sVersion=%s\\n\' "$cli" "$(probe_version "$cli")"; done',
+        ]
+      : []),
   ].join("\n");
 
   try {
-    const output = execSshWithRetry([host, "sh"], {
+    const output = execSsh([...buildSshOptions(), host, "sh"], {
       encoding: "utf8",
       timeout: 15000,
       input: script,
       maxRetries: 2,
       baseDelayMs: 1000,
     });
-    return normalizePosixProbeEnv(parseProbeLines(output));
-  } catch {
-    return null;
+    return normalizePosixProbeEnv(parseProbeLines(output), localVersions);
+  } catch (error) {
+    throw new Error(`remote probe failed for ${host}: ${error.message}`, {
+      cause: error,
+    });
   }
 }
 
@@ -223,22 +385,35 @@ function writeEnvCache(host, env, cacheDir) {
 export function probeRemoteEnv(host, opts = {}) {
   validateHost(host);
   const force = opts.force === true;
+  const execSsh = opts.execSsh || execSshWithRetry;
   const cacheDir = opts.cacheDir || remoteEnvCacheDir();
 
   if (!force) {
     const cached = readEnvCache(host, cacheDir);
-    if (isEnvCacheFresh(cached)) return cached.env;
+    if (
+      isEnvCacheFresh(cached) &&
+      cached.env.claudePath &&
+      (!opts.osHint ||
+        cached.env.os === opts.osHint ||
+        (opts.osHint === "windows" && cached.env.os === "win32")) &&
+      (cached.env.os === "win32"
+        ? "psmuxVersion" in cached.env && "psmuxSupported" in cached.env
+        : "tmuxPath" in cached.env && "versions" in cached.env)
+    )
+      return cached.env;
   }
 
-  const pwshEnv = probeRemoteEnvViaPwsh(host);
+  const pwshEnv = ["darwin", "linux"].includes(opts.osHint)
+    ? null
+    : probeRemoteEnvViaPwsh(host, execSsh);
   if (pwshEnv) {
-    writeEnvCache(host, pwshEnv, cacheDir);
+    if (pwshEnv.claudePath) writeEnvCache(host, pwshEnv, cacheDir);
     return pwshEnv;
   }
 
-  const posixEnv = probeRemoteEnvViaPosix(host);
+  const posixEnv = probeRemoteEnvViaPosix(host, execSsh, opts.localVersions);
   if (posixEnv) {
-    writeEnvCache(host, posixEnv, cacheDir);
+    if (posixEnv.claudePath) writeEnvCache(host, posixEnv, cacheDir);
     return posixEnv;
   }
 
@@ -303,7 +478,10 @@ export function ensureRemoteStageDir(host, env, remoteStageDir) {
           `New-Item -ItemType Directory -Path '${escapePwshSingleQuoted(remoteStageDir)}' -Force | Out-Null`,
         )
       : posixRemoteCommand(`mkdir -p ${shellQuote(remoteStageDir)}`);
-  execFileSync("ssh", [host, command], { timeout: 10000, stdio: "pipe" });
+  execFileSync("ssh", [...buildSshOptions(), host, command], {
+    timeout: 10000,
+    stdio: "pipe",
+  });
 }
 
 /**
@@ -313,10 +491,14 @@ export function ensureRemoteStageDir(host, env, remoteStageDir) {
  * @param {string} remotePath
  */
 export function uploadFileToRemote(host, localPath, remotePath) {
-  execFileSync("scp", [localPath, `${host}:${remotePath}`], {
-    timeout: 15000,
-    stdio: "pipe",
-  });
+  execFileSync(
+    "scp",
+    [...buildSshOptions(), localPath, `${host}:${remotePath}`],
+    {
+      timeout: 15000,
+      stdio: "pipe",
+    },
+  );
 }
 
 /**
@@ -372,7 +554,7 @@ export function remoteGit(host, env, gitArgs, cwd) {
       : posixRemoteCommand(
           `cd ${shellQuote(cwd)} && ${["git", ...gitArgs].map(shellQuote).join(" ")}`,
         );
-  return execFileSync("ssh", [host, command], {
+  return execFileSync("ssh", [...buildSshOptions(), host, command], {
     encoding: "utf8",
     timeout: 30_000,
     stdio: ["pipe", "pipe", "pipe"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflux/remote",
-  "version": "10.74.0",
+  "version": "10.76.0",
   "description": "triflux remote — team mode, psmux, MCP workers.",
   "type": "module",
   "main": "hub/index.mjs",