triflux 7.5.1 → 8.0.0

package/hub/team/backend.mjs

@@ -32,7 +32,7 @@ export class GeminiBackend {
   command() { return "gemini"; }
 
   buildArgs(prompt, resultFile, opts = {}) {
-    return `gemini --prompt ${prompt} -o text > '${resultFile}' 2>'${resultFile}.err'`;
+    return `gemini --prompt ${prompt} --output text > '${resultFile}' 2>'${resultFile}.err'`;
   }
 
   env() { return {}; }

package/hub/team/psmux.mjs

@@ -302,6 +302,13 @@ function sendLiteralToPane(paneId, text, submit = true) {
   }
 }
 
+export function sendKeysToPane(paneId, text, submit = true) {
+  psmuxExec(["send-keys", "-t", paneId, "-l", text]);
+  if (submit) {
+    psmuxExec(["send-keys", "-t", paneId, "Enter"]);
+  }
+}
+
 function toPatternRegExp(pattern) {
   if (pattern instanceof RegExp) {
     const flags = pattern.flags.includes("m") ? pattern.flags : `${pattern.flags}m`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "7.5.1",
+  "version": "8.0.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/remote-spawn.mjs

@@ -4,15 +4,34 @@
 // Usage:
 //   node remote-spawn.mjs --local [--dir <path>] [--prompt "..."] [--handoff <file>]
 //   node remote-spawn.mjs --host <ssh-host> [--dir <path>] [--prompt "..."] [--handoff <file>]
+//   node remote-spawn.mjs --send <session> "prompt"
+//   node remote-spawn.mjs --list
+//   node remote-spawn.mjs --attach <session>
+//   node remote-spawn.mjs --probe <ssh-host>
 
+import { randomUUID } from "crypto";
 import { execFileSync, spawn } from "child_process";
-import { readFileSync, existsSync, statSync } from "fs";
-import { resolve, join } from "path";
-import { homedir, platform } from "os";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { homedir, platform as getPlatform, tmpdir } from "os";
+import { join, posix as posixPath, resolve, win32 as win32Path } from "path";
+import {
+  attachPsmuxSession,
+  capturePsmuxPane,
+  createPsmuxSession,
+  hasPsmux,
+  listPsmuxSessions,
+  psmuxExec,
+  psmuxSessionExists,
+  sendKeysToPane,
+  startCapture,
+  waitForPattern,
+} from "../hub/team/psmux.mjs";
 
 const MAX_HANDOFF_BYTES = 1 * 1024 * 1024; // 1 MB
-
-// ── 입력 검증 ──
+const REMOTE_ENV_TTL_MS = 86_400_000;
+const REMOTE_ENV_CACHE_DIR = resolve(".omc", "state", "remote-env");
+const SSH_PROMPT_PATTERN = /(\$|%|#|PS |>)\s*$/;
+const IS_WINDOWS_LOCAL = getPlatform() === "win32";
 
 const SAFE_HOST_RE = /^[a-zA-Z0-9._-]+$/;
 const SAFE_DIR_RE = /^[a-zA-Z0-9_.~\/:\\-]+$/;
@@ -33,60 +52,162 @@ function validateDir(dir) {
   return dir;
 }
 
-function shellQuote(s) {
-  return "'" + s.replace(/'/g, "'\\''") + "'";
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function escapePwshSingleQuoted(value) {
+  return String(value).replace(/'/g, "''");
+}
+
+function escapePwshDoubleQuoted(value) {
+  return String(value).replace(/`/g, "``").replace(/"/g, '`"');
+}
+
+function normalizeCommandPath(value) {
+  return String(value).replace(/\\/g, "/");
 }
 
-// ── CLI 파싱 ──
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms));
+}
+
+function usageText() {
+  return `Usage:
+  remote-spawn --local [--dir <path>] [--prompt "task"] [--handoff <file>]
+  remote-spawn --host <ssh-host> [--dir <path>] [--prompt "task"] [--handoff <file>]
+  remote-spawn --send <session> "prompt"
+  remote-spawn --list
+  remote-spawn --attach <session>
+  remote-spawn --probe <ssh-host>
+
+Options:
+  --local          로컬 WT 탭에서 Claude 실행
+  --host <name>    SSH 호스트로 원격 Claude 실행
+  --dir <path>     작업 디렉토리 (기본: 현재 디렉토리 / 원격 홈)
+  --prompt "..."   Claude에 전달할 첫 메시지
+  --handoff <file> 핸드오프 파일 경로 (prompt와 결합 가능)
+  --send <session> 실행 중인 세션에 프롬프트 전송
+  --list           tfx-spawn-* psmux 세션 목록
+  --attach <name>  WT 새 탭에서 세션 attach
+  --probe <host>   SSH 원격 환경 강제 프로브 + 캐시 갱신
+  --capture <name> 세션 pane 내용 캡처 출력
+  --wait <name>    세션의 Claude 준비 완료 대기 (기본 60초)`;
+}
 
 function parseArgs(argv) {
-  const args = { host: null, dir: null, prompt: null, handoff: null, local: false };
-  for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--local") { args.local = true; continue; }
-    if (a === "--host" && argv[i + 1]) { args.host = validateHost(argv[++i]); continue; }
-    if (a === "--dir" && argv[i + 1]) { args.dir = validateDir(argv[++i]); continue; }
-    if (a === "--prompt" && argv[i + 1]) { args.prompt = argv[++i]; continue; }
-    if (a === "--handoff" && argv[i + 1]) { args.handoff = argv[++i]; continue; }
-    // 미지정 인자는 prompt로 처리
-    if (!args.prompt) args.prompt = a;
+  let command = "spawn";
+  let host = null;
+  let dir = null;
+  let prompt = null;
+  let handoff = null;
+  let local = false;
+  let sessionName = null;
+  let probeHost = null;
+  const promptParts = [];
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--local") {
+      local = true;
+      continue;
+    }
+    if (arg === "--host" && argv[index + 1]) {
+      host = validateHost(argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg === "--dir" && argv[index + 1]) {
+      dir = validateDir(argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg === "--prompt" && argv[index + 1]) {
+      prompt = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--handoff" && argv[index + 1]) {
+      handoff = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--send" && argv[index + 1]) {
+      command = "send";
+      sessionName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--list") {
+      command = "list";
+      continue;
+    }
+    if (arg === "--attach" && argv[index + 1]) {
+      command = "attach";
+      sessionName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--probe" && argv[index + 1]) {
+      command = "probe";
+      probeHost = validateHost(argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg === "--capture" && argv[index + 1]) {
+      command = "capture";
+      sessionName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--wait" && argv[index + 1]) {
+      command = "wait";
+      sessionName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    promptParts.push(arg);
   }
-  return args;
-}
 
-// ── Claude 실행 경로 감지 ──
+  const mergedPrompt = prompt ?? (promptParts.length > 0 ? promptParts.join(" ") : null);
+  return {
+    command,
+    dir,
+    handoff,
+    host,
+    local,
+    probeHost,
+    prompt: mergedPrompt,
+    sessionName,
+  };
+}
 
 function detectClaudePath() {
-  // 1. 환경변수 오버라이드
   if (process.env.CLAUDE_BIN_PATH) return process.env.CLAUDE_BIN_PATH;
 
-  // 2. WinGet Links
   const wingetPath = join(homedir(), "AppData", "Local", "Microsoft", "WinGet", "Links", "claude.exe");
   if (existsSync(wingetPath)) return wingetPath;
 
-  // 3. npm global
   const npmPath = join(process.env.APPDATA || "", "npm", "claude.cmd");
   if (existsSync(npmPath)) return npmPath;
 
-  // 3. PATH에서 찾기
   try {
-    const cmd = platform() === "win32" ? "where" : "which";
-    const result = execFileSync(cmd, ["claude"], { encoding: "utf8", timeout: 5000 }).trim();
-    if (result) return result.split("\n")[0].trim();
-  } catch { /* not found */ }
+    const command = IS_WINDOWS_LOCAL ? "where" : "which";
+    const result = execFileSync(command, ["claude"], { encoding: "utf8", timeout: 5000 }).trim();
+    if (result) return result.split(/\r?\n/u)[0].trim();
+  } catch {
+    // not found
+  }
 
-  return "claude"; // fallback — PATH에 있다고 가정
+  return "claude";
 }
 
-// ── 권한 플래그 ──
-
 function getPermissionFlag() {
-  if (process.env.TFX_CLAUDE_SAFE_MODE === "1") return [];
-  return ["--PLACEHOLDER_PERM_FLAG"];
+  return process.env.TFX_CLAUDE_SAFE_MODE === "1" ? [] : ["--dangerously-skip-permissions"];
 }
 
-// ── 핸드오프 컨텐츠 생성 ──
-
 function buildPrompt(args) {
   let content = "";
 
@@ -111,13 +232,10 @@ function buildPrompt(args) {
   return content;
 }
 
-// ── 로컬 Spawn (WT 탭) ──
-
-function spawnLocal(args, claudePath, prompt) {
+function spawnLocalFallback(args, claudePath, prompt) {
   const dir = args.dir ? resolve(args.dir) : process.cwd();
 
-  if (platform() !== "win32") {
-    // Linux/macOS: 직접 실행
+  if (!IS_WINDOWS_LOCAL) {
     const cliArgs = [...getPermissionFlag()];
     if (prompt) cliArgs.push(prompt);
 
@@ -129,15 +247,15 @@ function spawnLocal(args, claudePath, prompt) {
     return;
   }
 
-  // Windows: wt.exe new-tab
   const wtArgs = ["new-tab", "-d", dir, "--"];
   const claudeForward = claudePath.replace(/\\/g, "/");
 
   if (prompt) {
-    // pwsh single-quote: 내부 ' → '' 이스케이프
-    const psQuoted = "'" + prompt.replace(/'/g, "''") + "'";
+    const psQuoted = `'${prompt.replace(/'/g, "''")}'`;
     wtArgs.push(
-      "pwsh", "-NoProfile", "-Command",
+      "pwsh",
+      "-NoProfile",
+      "-Command",
       `& '${claudeForward}' ${getPermissionFlag().join(" ")} ${psQuoted}`,
     );
   } else {
@@ -147,15 +265,13 @@ function spawnLocal(args, claudePath, prompt) {
   try {
     spawn("wt.exe", wtArgs, { detached: true, stdio: "ignore", windowsHide: false }).unref();
     console.log(`spawned local Claude in WT tab → ${dir}`);
-  } catch (err) {
-    console.error("wt.exe spawn failed:", err.message);
+  } catch (error) {
+    console.error("wt.exe spawn failed:", error.message);
     process.exit(1);
   }
 }
 
-// ── 원격 Spawn (SSH) ──
-
-function spawnRemote(args, prompt) {
+function spawnRemoteFallback(args, prompt) {
   const { host } = args;
   if (!host) {
     console.error("--host required for remote spawn");
@@ -163,60 +279,502 @@ function spawnRemote(args, prompt) {
   }
 
   const dir = args.dir || "~";
-  const quotedDir = shellQuote(dir);
-  const permFlag = getPermissionFlag().join(" ");
-  const remoteCmd = prompt
-    ? `cd ${quotedDir} && claude ${permFlag} ${shellQuote(prompt)}`
-    : `cd ${quotedDir} && claude ${permFlag}`;
-
-  if (platform() === "win32") {
-    // WT 탭에서 SSH 세션 열기
+  const permFlags = getPermissionFlag();
+  const scriptLines = [
+    `cd '${dir.replace(/'/g, "''")}'`,
+  ];
+
+  if (prompt) {
+    const safePrompt = prompt.replace(/'/g, "''");
+    scriptLines.push(`& "$env:USERPROFILE\\.local\\bin\\claude.exe" ${permFlags.join(" ")} '${safePrompt}'`);
+  } else {
+    scriptLines.push(`& "$env:USERPROFILE\\.local\\bin\\claude.exe" ${permFlags.join(" ")}`);
+  }
+
+  const scriptContent = scriptLines.join("\n");
+  const localScript = join(tmpdir(), "tfx-remote-spawn.ps1");
+  writeFileSync(localScript, scriptContent, "utf8");
+
+  try {
+    execFileSync("scp", [localScript, `${host}:tfx-remote-spawn.ps1`], { timeout: 10000, stdio: "pipe" });
+  } catch (error) {
+    console.error("failed to copy script to remote:", error.message);
+    process.exit(1);
+  }
+
+  let remoteHome;
+  try {
+    remoteHome = execFileSync("ssh", [host, "echo", "$env:USERPROFILE"], { encoding: "utf8", timeout: 5000 }).trim();
+  } catch {
+    remoteHome = `C:\\Users\\${host}`;
+  }
+
+  const remoteScript = `${remoteHome.replace(/\\/g, "/")}/tfx-remote-spawn.ps1`;
+  const remoteCmd = `pwsh -NoExit -File ${remoteScript}`;
+
+  if (IS_WINDOWS_LOCAL) {
     const wtArgs = [
-      "new-tab", "--title", `Claude@${host}`, "--",
-      "ssh", "-t", "--", host, remoteCmd,
+      "new-tab",
+      "--title",
+      `Claude@${host}`,
+      "--",
+      "ssh",
+      "-t",
+      "--",
+      host,
+      remoteCmd,
     ];
-
     try {
       spawn("wt.exe", wtArgs, { detached: true, stdio: "ignore", windowsHide: false }).unref();
       console.log(`spawned remote Claude → ${host}:${dir}`);
-    } catch (err) {
-      console.error("wt.exe spawn failed:", err.message);
+    } catch (error) {
+      console.error("wt.exe spawn failed:", error.message);
       process.exit(1);
     }
   } else {
-    // Linux/macOS: 직접 SSH
     const child = spawn("ssh", ["-t", "--", host, remoteCmd], { stdio: "inherit" });
     child.on("exit", (code) => process.exit(code || 0));
   }
 }
 
-// ── main ──
+function shouldUsePsmux() {
+  return IS_WINDOWS_LOCAL && hasPsmux();
+}
+
+function requirePsmux() {
+  if (!hasPsmux()) {
+    throw new Error("psmux is required for this command");
+  }
+}
+
+function parseProbeLines(text) {
+  return Object.fromEntries(
+    text
+      .split(/\r?\n/u)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const separatorIndex = line.indexOf("=");
+        return separatorIndex === -1
+          ? null
+          : [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)];
+      })
+      .filter(Boolean),
+  );
+}
+
+function normalizePwshProbeEnv(host, parsed) {
+  if (parsed.shell !== "pwsh" || parsed.os !== "win32") {
+    return null;
+  }
+
+  if (!parsed.home) {
+    return null;
+  }
+
+  return Object.freeze({
+    claudePath: (!parsed.claude || parsed.claude === "notfound") ? null : parsed.claude,
+    home: parsed.home,
+    os: "win32",
+    shell: "pwsh",
+  });
+}
+
+function normalizePosixProbeEnv(host, parsed) {
+  const os = parsed.os === "darwin" ? "darwin" : parsed.os === "linux" ? "linux" : null;
+  if (!os || !parsed.home) {
+    return null;
+  }
+
+  return Object.freeze({
+    claudePath: (!parsed.claude || parsed.claude === "notfound") ? null : parsed.claude,
+    home: parsed.home,
+    os,
+    shell: parsed.shell === "zsh" ? "zsh" : "bash",
+  });
+}
+
+function getRemoteEnvCachePath(host) {
+  return join(REMOTE_ENV_CACHE_DIR, `${host}.json`);
+}
+
+function readRemoteEnvCache(host) {
+  const cachePath = getRemoteEnvCachePath(host);
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isRemoteEnvCacheFresh(cacheEntry) {
+  return Boolean(
+    cacheEntry
+    && typeof cacheEntry.cachedAt === "number"
+    && cacheEntry.env
+    && (Date.now() - cacheEntry.cachedAt) < REMOTE_ENV_TTL_MS,
+  );
+}
+
+function writeRemoteEnvCache(host, env) {
+  mkdirSync(REMOTE_ENV_CACHE_DIR, { recursive: true });
+  writeFileSync(
+    getRemoteEnvCachePath(host),
+    JSON.stringify({ cachedAt: Date.now(), env }, null, 2),
+    "utf8",
+  );
+}
+
+function probeRemoteEnvViaPwsh(host) {
+  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\' }',
+    'Write-Output "os=$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::Windows) ? \'win32\' : \'other\')"',
+  ].join("; ");
+
+  let output;
+  try {
+    output = execFileSync(
+      "ssh",
+      [host, "pwsh", "-NoProfile", "-Command", command],
+      { encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"] },
+    );
+  } catch {
+    return null;
+  }
+
+  return normalizePwshProbeEnv(host, parseProbeLines(output));
+}
+
+function probeRemoteEnvViaPosix(host) {
+  const script = [
+    "echo shell=$(basename $SHELL)",
+    "echo home=$HOME",
+    "command -v claude >/dev/null 2>&1 && echo claude=$(command -v claude) || echo claude=notfound",
+    "echo os=$(uname -s | tr A-Z a-z)",
+  ].join("\n");
+
+  let output;
+  try {
+    output = execFileSync("ssh", [host, "sh"], {
+      encoding: "utf8",
+      timeout: 15000,
+      input: script,
+    });
+  } catch {
+    return null;
+  }
+
+  return normalizePosixProbeEnv(host, parseProbeLines(output));
+}
+
+function probeRemoteEnv(host, opts = {}) {
+  const force = opts.force === true;
+
+  if (!force) {
+    const cached = readRemoteEnvCache(host);
+    if (isRemoteEnvCacheFresh(cached)) {
+      return cached.env;
+    }
+  }
+
+  const pwshEnv = probeRemoteEnvViaPwsh(host);
+  if (pwshEnv) {
+    writeRemoteEnvCache(host, pwshEnv);
+    return pwshEnv;
+  }
+
+  const posixEnv = probeRemoteEnvViaPosix(host);
+  if (posixEnv) {
+    writeRemoteEnvCache(host, posixEnv);
+    return posixEnv;
+  }
+
+  throw new Error(`remote probe failed for ${host}`);
+}
+
+function isWindowsAbsolutePath(value) {
+  return /^[a-zA-Z]:[\\/]/u.test(value) || value.startsWith("\\\\");
+}
+
+function resolveRemoteDir(dir, env) {
+  const requestedDir = dir || env.home;
+
+  if (env.os === "win32") {
+    const winDir = requestedDir.replace(/\//g, "\\");
+    if (winDir === "~") return env.home;
+    if (/^~[\\/]/u.test(winDir)) return win32Path.join(env.home, winDir.slice(2));
+    if (isWindowsAbsolutePath(winDir)) return winDir;
+    return win32Path.join(env.home, winDir);
+  }
 
-function main() {
+  if (requestedDir === "~") return env.home;
+  if (requestedDir.startsWith("~/")) return posixPath.join(env.home, requestedDir.slice(2));
+  if (requestedDir.startsWith("/")) return requestedDir;
+  return posixPath.join(env.home, requestedDir);
+}
+
+function listSessionNamesFromRawOutput(output) {
+  return output
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.split(":")[0]?.trim())
+    .filter(Boolean);
+}
+
+function listSpawnSessions() {
+  const helperSessions = listPsmuxSessions().filter((name) => name.startsWith("tfx-spawn-"));
+  if (helperSessions.length > 0) {
+    return helperSessions;
+  }
+
+  try {
+    return listSessionNamesFromRawOutput(psmuxExec(["list-sessions"]))
+      .filter((name) => name.startsWith("tfx-spawn-"));
+  } catch {
+    return [];
+  }
+}
+
+function openAttachTab(sessionName, title = null) {
+  if (IS_WINDOWS_LOCAL) {
+    const wtArgs = title
+      ? ["new-tab", "--title", title, "--", "psmux", "attach", "-t", sessionName]
+      : ["new-tab", "--", "psmux", "attach", "-t", sessionName];
+    spawn("wt.exe", wtArgs, { detached: true, stdio: "ignore", windowsHide: false }).unref();
+    return;
+  }
+
+  attachPsmuxSession(sessionName);
+}
+
+function getLastNonEmptyLine(text) {
+  const lines = String(text)
+    .split(/\r?\n/u)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0);
+  return lines.at(-1) || "";
+}
+
+async function waitForRemotePrompt(sessionName, paneId) {
+  const baseline = capturePsmuxPane(paneId, 20);
+  const capture = startCapture(sessionName, paneId);
+  const deadline = Date.now() + 15_000;
+
+  while (Date.now() <= deadline) {
+    const remainingMs = Math.max(250, deadline - Date.now());
+    await waitForPattern(
+      sessionName,
+      paneId,
+      SSH_PROMPT_PATTERN,
+      Math.min(1, remainingMs / 1000),
+      { logPath: capture.logPath },
+    );
+
+    const tail = capturePsmuxPane(paneId, 20);
+    const lastLine = getLastNonEmptyLine(tail);
+    if (tail !== baseline && SSH_PROMPT_PATTERN.test(lastLine)) {
+      return;
+    }
+  }
+
+  throw new Error(`ssh prompt wait timed out for ${sessionName}: ${capturePsmuxPane(paneId, 20)}`);
+}
+
+function spawnLocal(args, claudePath, prompt) {
+  if (!shouldUsePsmux()) {
+    spawnLocalFallback(args, claudePath, prompt);
+    return;
+  }
+
+  const dir = args.dir ? resolve(args.dir) : process.cwd();
+  const sessionName = `tfx-spawn-${randomUUID().slice(0, 8)}`;
+  const paneId = `${sessionName}:0.0`;
+  const permissionFlags = getPermissionFlag().join(" ");
+  const command = `& '${escapePwshSingleQuoted(normalizeCommandPath(claudePath))}'${permissionFlags ? ` ${permissionFlags}` : ""}`;
+
+  createPsmuxSession(sessionName, { layout: "1xN", paneCount: 1 });
+  sendKeysToPane(paneId, `cd '${escapePwshSingleQuoted(dir)}'`);
+  sleepMs(500);
+  sendKeysToPane(paneId, command);
+  if (prompt) {
+    sleepMs(2000);
+    sendKeysToPane(paneId, prompt);
+  }
+  openAttachTab(sessionName, "Claude@local");
+  console.log(sessionName);
+}
+
+async function spawnRemote(args, prompt) {
+  const { host } = args;
+  if (!host) {
+    console.error("--host required for remote spawn");
+    process.exit(1);
+  }
+
+  if (!shouldUsePsmux()) {
+    spawnRemoteFallback(args, prompt);
+    return;
+  }
+
+  const env = probeRemoteEnv(host);
+  if (!env.claudePath) {
+    console.error(`claude not found on ${host}. Install Claude Code on the remote host first.`);
+    process.exit(1);
+  }
+  const resolvedDir = resolveRemoteDir(args.dir, env);
+  const sessionName = `tfx-spawn-${host}-${randomUUID().slice(0, 8)}`;
+  const paneId = `${sessionName}:0.0`;
+  const permissionFlags = getPermissionFlag().join(" ");
+
+  createPsmuxSession(sessionName, { layout: "1xN", paneCount: 1 });
+  sendKeysToPane(paneId, `ssh -t ${host}`);
+  await waitForRemotePrompt(sessionName, paneId);
+
+  if (env.shell === "pwsh") {
+    const claudeCommand = `& "${escapePwshDoubleQuoted(env.claudePath)}"${permissionFlags ? ` ${permissionFlags}` : ""}`;
+    sendKeysToPane(paneId, `cd '${escapePwshSingleQuoted(resolvedDir)}'`);
+    sendKeysToPane(paneId, claudeCommand);
+  } else {
+    const claudeCommand = `${shellQuote(env.claudePath)}${permissionFlags ? ` ${permissionFlags}` : ""}`;
+    sendKeysToPane(paneId, `cd ${shellQuote(resolvedDir)}`);
+    sendKeysToPane(paneId, claudeCommand);
+  }
+
+  if (prompt) {
+    sleepMs(2000);
+    sendKeysToPane(paneId, prompt);
+  }
+
+  openAttachTab(sessionName, `Claude@${host}`);
+  console.log(sessionName);
+}
+
+function sendPromptToSession(sessionName, prompt) {
+  requirePsmux();
+  if (!psmuxSessionExists(sessionName)) {
+    throw new Error(`psmux session not found: ${sessionName}`);
+  }
+  sendKeysToPane(`${sessionName}:0.0`, prompt);
+}
+
+function attachSession(sessionName) {
+  requirePsmux();
+  if (!psmuxSessionExists(sessionName)) {
+    throw new Error(`psmux session not found: ${sessionName}`);
+  }
+  openAttachTab(sessionName);
+}
+
+function captureSession(sessionName, lines = 30) {
+  requirePsmux();
+  if (!psmuxSessionExists(sessionName)) {
+    throw new Error(`psmux session not found: ${sessionName}`);
+  }
+  return capturePsmuxPane(`${sessionName}:0.0`, lines);
+}
+
+async function waitForClaudeReady(sessionName, timeoutSec = 60) {
+  requirePsmux();
+  if (!psmuxSessionExists(sessionName)) {
+    throw new Error(`psmux session not found: ${sessionName}`);
+  }
+  const paneId = `${sessionName}:0.0`;
+  const readyPattern = /(\u276f|\u2795|>\s*$|bypass permissions)/;
+  const deadline = Date.now() + timeoutSec * 1000;
+
+  while (Date.now() <= deadline) {
+    const snapshot = capturePsmuxPane(paneId, 5);
+    const lastLine = snapshot.split(/\r?\n/).filter((l) => l.trim()).at(-1) || "";
+    if (readyPattern.test(lastLine)) {
+      return true;
+    }
+    sleepMs(1000);
+  }
+  throw new Error(`claude ready wait timed out after ${timeoutSec}s for ${sessionName}`);
+}
+
+async function main() {
   const args = parseArgs(process.argv);
 
-  if (!args.local && !args.host) {
-    console.log(`Usage:
-  remote-spawn --local [--dir <path>] [--prompt "task"] [--handoff <file>]
-  remote-spawn --host <ssh-host> [--dir <path>] [--prompt "task"] [--handoff <file>]
+  if (args.command === "list") {
+    console.log(listSpawnSessions().join("\n"));
+    return;
+  }
 
-Options:
-  --local          로컬 WT 탭에서 Claude 실행
-  --host <name>    SSH 호스트로 원격 Claude 실행
-  --dir <path>     작업 디렉토리 (기본: 현재 디렉토리 / ~)
-  --prompt "..."   Claude에 전달할 첫 메시지
-  --handoff <file> 핸드오프 파일 경로 (prompt와 결합 가능)`);
-    process.exit(0);
+  if (args.command === "attach") {
+    if (!args.sessionName) {
+      console.error("--attach requires a session name");
+      process.exit(1);
+    }
+    attachSession(args.sessionName);
+    return;
+  }
+
+  if (args.command === "probe") {
+    if (!args.probeHost) {
+      console.error("--probe requires a host");
+      process.exit(1);
+    }
+    console.log(JSON.stringify(probeRemoteEnv(args.probeHost, { force: true }), null, 2));
+    return;
+  }
+
+  if (args.command === "capture") {
+    if (!args.sessionName) {
+      console.error("--capture requires a session name");
+      process.exit(1);
+    }
+    console.log(captureSession(args.sessionName));
+    return;
+  }
+
+  if (args.command === "wait") {
+    if (!args.sessionName) {
+      console.error("--wait requires a session name");
+      process.exit(1);
+    }
+    await waitForClaudeReady(args.sessionName);
+    console.log("ready");
+    return;
   }
 
   const prompt = buildPrompt(args);
-  const claudePath = detectClaudePath();
+
+  if (args.command === "send") {
+    if (!args.sessionName) {
+      console.error("--send requires a session name");
+      process.exit(1);
+    }
+    if (!prompt) {
+      console.error("--send requires a prompt or --handoff");
+      process.exit(1);
+    }
+    sendPromptToSession(args.sessionName, prompt);
+    return;
+  }
+
+  if (!args.local && !args.host) {
+    console.log(usageText());
+    return;
+  }
 
   if (args.local) {
-    spawnLocal(args, claudePath, prompt);
-  } else {
-    spawnRemote(args, prompt);
+    spawnLocal(args, detectClaudePath(), prompt);
+    return;
   }
+
+  await spawnRemote(args, prompt);
 }
 
-main();
+main().catch((error) => {
+  console.error(error?.message || String(error));
+  process.exit(1);
+});

package/skills/remote-spawn/SKILL.md

@@ -1,63 +1,205 @@
 ---
 name: remote-spawn
-description: 로컬/원격 머신에 Claude 세션을 WT 탭으로 spawn합니다. 핸드오프 전달 지원.
+description: >
+  원격/로컬 머신에 Claude 세션을 psmux 기반으로 spawn하고 관리합니다.
+  자동 핸드오프, 추가 프롬프트 전송, 세션 재부착, 원격 환경 자동 감지를 지원합니다.
+  이 스킬은 다음 상황에서 반드시 사용하세요:
+  원격 실행, 세션 spawn, 다른 머신에서 작업, 원격 Claude, 세션 전달, 핸드오프 전달,
+  원격 세션에 프롬프트 보내기, 세션 목록, 세션 재부착.
+  로컬 호스트 별칭이 references/hosts.json에 등록되어 있으면 호스트명 언급만으로도 트리거됩니다.
 triggers:
   - remote-spawn
-argument-hint: "[--host <ssh-host>] [--dir <path>] <prompt>"
+argument-hint: "[--host <name>] [--send <session> <prompt>] [--list] [--attach] <prompt or natural language>"
 ---
 
-# remote-spawn — 원격/로컬 Claude 세션 Spawn
+# remote-spawn — 원격/로컬 Claude 세션 관리
 
-> 새 WT 탭에서 Claude 세션을 시작하고, 선택적으로 핸드오프 컨텍스트를 전달합니다.
+> psmux 세션 기반으로 Claude를 원격/로컬에서 실행하고 관리합니다.
+> 대화 컨텍스트를 자동으로 핸드오프하고, 자연어로 세션을 제어할 수 있습니다.
 
-## 사용법
+## 입력 해석
 
+사용자 입력을 아래 순서로 매칭한다. 매칭되면 해당 동작 실행.
+
+```
+"ultra4에서 보안 리뷰 해"       → spawn(host=ultra4, prompt="보안 리뷰 해")
+"세션 목록 보여줘"              → list
+"ultra4 세션에 테스트도 해달라고 전달해" → send(session=auto-detect, prompt="테스트도 해달라고")
+"아까 그 세션 다시 열어"         → attach(session=most-recent)
+"로컬에서 리팩터링 이어서"       → spawn(local, prompt="리팩터링 이어서")
+```
+
+### 호스트 감지
+
+1. `--host <name>` 명시 → 그대로 사용
+2. `references/hosts.json` 에 등록된 별칭/키워드 매칭 → 호스트 자동 해석
+3. "원격에서", "다른 머신에서" → hosts.json의 default 호스트 사용
+4. 매칭 없음 + --local 없음 → 사용자에게 "어떤 호스트에서 실행할까요?" 질문
+
+`references/hosts.json`이 없으면 --host를 명시적으로 요구한다.
+
+### 동작 분류
+
+| 패턴 | 동작 | 설명 |
+|------|------|------|
+| 호스트 + 프롬프트 | **spawn** | 원격 Claude 세션 생성 |
+| --local / "로컬에서" | **spawn local** | 로컬 Claude 세션 생성 |
+| "전달해", "보내줘", --send | **send** | 기존 세션에 프롬프트 전송 |
+| "목록", "세션 리스트", --list | **list** | 활성 세션 목록 |
+| "다시 열어", "재부착", --attach | **attach** | WT 탭에 세션 재부착 |
+| "환경 확인", --probe | **probe** | 원격 환경 프로브 (강제 갱신) |
+
+## 실행 워크플로우
+
+### spawn — 세션 생성 (핵심)
+
+spawn은 3단계로 동작한다:
+
+**1단계: 핸드오프 생성 (자동)**
+
+사용자가 프롬프트만 준 경우, 현재 대화 맥락에서 핸드오프를 자동 생성한다.
+핸드오프는 원격 Claude가 작업을 이해하는 데 필요한 최소 컨텍스트다.
+
+핸드오프 구조:
 ```
-/remote-spawn 리팩터링 작업 이어서 해줘
-/remote-spawn --host ultra4 보안 리뷰 진행해
-/remote-spawn --host ultra4 --dir ~/Desktop/Projects/gamma API 점검
+## 작업 컨텍스트
+- 현재 프로젝트: {프로젝트 경로}
+- 작업 중인 파일: {최근 수정 파일 목록}
+- 진행 상황: {현재 대화에서 완료한 것}
+
+## 태스크
+{사용자 프롬프트 또는 추출된 작업 지시}
+
+## 참고
+- {관련 결정 사항이나 제약}
 ```
 
-## 동작
+핸드오프 생성 후 임시 파일에 저장: `.omc/handoff-{uuid8}.md`
 
-1. **인자 파싱**: `--host`, `--dir`, 나머지는 prompt
-2. **핸드오프 생성** (선택): 현재 세션 컨텍스트에서 최소 핸드오프 생성
-3. **세션 Spawn**: `scripts/remote-spawn.mjs` 호출
+사용자가 명시적으로 `--handoff <file>` 을 준 경우, 자동 생성 대신 해당 파일 사용.
+사용자가 `/mp`로 생성한 핸드오프가 있으면 그것을 우선 사용.
 
-## 실행 규칙
+**2단계: 환경 확인**
 
-### 로컬 (--host 미지정)
+원격 호스트의 프로브 결과를 확인한다. 캐시가 있으면 캐시 사용.
 
 ```bash
-node scripts/remote-spawn.mjs --local --dir "${DIR}" --prompt "${PROMPT}"
+node scripts/remote-spawn.mjs --probe {host}
+```
+
+프로브 결과에 따른 분기:
+
+| claudePath | 동작 |
+|------------|------|
+| 유효한 경로 | 정상 진행 |
+| null | 설치 안내 출력 후 사용자 확인 대기 |
+
+**claude 미설치 시 안내 메시지:**
+
+```
+{host}에 Claude Code가 설치되어 있지 않습니다.
+
+설치 방법:
+  macOS/Linux: npm install -g @anthropic-ai/claude-code
+  Windows:     winget install Anthropic.ClaudeCode
+
+설치 후 `--probe {host}` 로 환경을 갱신하세요.
+또는 이 호스트에서 다른 CLI(codex, gemini)로 작업하시겠습니까?
 ```
-- 새 WT 탭에서 Claude 실행
-- `--dir` 미지정 시 현재 디렉토리
 
-### 원격 (--host 지정)
+**3단계: 세션 실행**
 
 ```bash
-node scripts/remote-spawn.mjs --host "${HOST}" --dir "${DIR}" --prompt "${PROMPT}"
+node scripts/remote-spawn.mjs --host {host} --dir {dir} --prompt {prompt} --handoff {handoff_file}
 ```
-- WT 탭에서 SSH 세션 열고 원격 Claude 실행
-- `--dir` 미지정 시 `~`
-- 원격 Claude는 자기 환경(CLAUDE.md, 훅, MCP)을 이미 알고 있으므로 태스크만 전달
 
-### 핸드오프 모드
+실행 후 세션 이름을 사용자에게 알려준다:
+```
+spawned: tfx-spawn-ultra4-a1b2c3d4
+WT 탭에서 Claude@ultra4 세션이 열립니다.
+추가 프롬프트: /remote-spawn --send tfx-spawn-ultra4-a1b2c3d4 "다음 작업"
+```
+
+### send — 프롬프트 전송
 
-현재 세션에서 핸드오프를 생성한 뒤 전달하려면:
+사용자가 세션 이름을 명시하지 않으면, 해당 호스트의 가장 최근 세션을 자동 감지한다.
 
-1. `/mp`로 핸드오프 파일 생성
-2. `/remote-spawn --host ultra4 --handoff .omc/handoff-xxx.md`
+```bash
+# 세션 이름 명시
+node scripts/remote-spawn.mjs --send tfx-spawn-ultra4-a1b2c3d4 --prompt "{prompt}"
+
+# 호스트명으로 자동 감지
+node scripts/remote-spawn.mjs --list  # tfx-spawn-ultra4-* 필터링
+# → 가장 최근 세션에 전송
+node scripts/remote-spawn.mjs --send {detected_session} --prompt "{prompt}"
+```
 
-또는 Claude가 직접 핸드오프를 인라인으로 구성:
+### list — 세션 목록
 
 ```bash
-node scripts/remote-spawn.mjs --host ultra4 --prompt "이전 세션에서 JWT 미들웨어 구현 완료. 남은 작업: 테스트 커버리지 80% 달성"
+node scripts/remote-spawn.mjs --list
+```
+
+결과를 표 형태로 정리해서 보여준다:
+```
+| 세션 | 호스트 | 상태 |
+|------|--------|------|
+| tfx-spawn-ultra4-a1b2c3d4 | ultra4 | active |
+| tfx-spawn-m2-e5f6g7h8 | m2 | active |
+```
+
+### attach — 재부착
+
+```bash
+node scripts/remote-spawn.mjs --attach {session_name}
+```
+
+세션 이름 미지정 시 가장 최근 세션을 사용한다.
+
+### probe — 환경 확인
+
+```bash
+node scripts/remote-spawn.mjs --probe {host}
+```
+
+결과를 사람이 읽기 좋게 정리:
+```
+ultra4 환경:
+  OS: Windows (win32)
+  Shell: pwsh
+  Home: C:\Users\SSAFY
+  Claude: C:\Users\SSAFY\.local\bin\claude.exe
 ```
 
 ## 전제 조건
 
-- `remoteControlAtStartup: true` 가 settings.json에 설정됨 (`triflux setup`으로 자동)
-- 원격 호스트: SSH config에 등록 + Claude Code 설치
-- 로컬: Windows Terminal 설치
+- **psmux** 설치 (권장, 전체 기능). 미설치 시 기존 WT+SSH fallback.
+- `remoteControlAtStartup: true` 설정 (`triflux setup` 자동)
+- 원격 호스트: SSH config 등록 + Claude Code 설치
+- 로컬: Windows Terminal
+
+## 호스트 설정
+
+`references/hosts.json`에 개인 호스트 별칭을 등록한다.
+이 파일은 프로젝트에 커밋하지 않고 로컬에서만 관리한다 (.gitignore 추가).
+
+```json
+{
+  "hosts": {
+    "ultra4": {
+      "description": "Windows 데스크탑",
+      "aliases": ["울트라", "데스크탑"],
+      "default_dir": "~/Desktop/Projects"
+    },
+    "m2": {
+      "description": "MacBook Pro",
+      "aliases": ["맥북", "맥"],
+      "default_dir": "~/projects"
+    }
+  },
+  "default_host": "ultra4",
+  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
+}
+```
+
+이 파일이 없으면 호스트 자동 감지가 비활성화되고, --host를 명시해야 한다.

package/skills/remote-spawn/references/hosts.json

@@ -0,0 +1,16 @@
+{
+  "hosts": {
+    "ultra4": {
+      "description": "Windows 데스크탑 (SSAFY)",
+      "aliases": ["울트라", "데스크탑"],
+      "default_dir": "~/Desktop/Projects"
+    },
+    "m2": {
+      "description": "MacBook Pro",
+      "aliases": ["맥북", "맥"],
+      "default_dir": "~/projects"
+    }
+  },
+  "default_host": "ultra4",
+  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
+}