@triflux/remote 10.1.0 → 10.26.0

package/hub/team/psmux.mjs

@@ -1,21 +1,51 @@
-// hub/team/psmux.mjs — Windows psmux 세션/키바인딩/캡처/steering 관리
+// hub/team/psmux.mjs — terminal multiplexer 세션/키바인딩/캡처/steering 관리
+//
+// 역사: psmux 는 Windows pwsh7 환경용 tmux 호환 클론 (Windows 에서 tmux 가
+// 깔리지 않거나 ConPTY 호환이 부족할 때 대안). triflux 는 원래 Windows 첫
+// 운영 환경이었고 그래서 변수 명에 `PSMUX_` prefix 가 남아있다. 실제 의미는
+// "OS 별 primary multiplexer" 다:
+//   - mac/Linux: tmux 가 primary (POSIX 표준)
+//   - Windows: psmux 가 primary (Windows pwsh7 전용)
+// 이전 코드는 mac 에서 psmux 를 시도하고 tmux 로 silent fallback 했는데,
+// 운영 fact 는 mac 표준이 tmux 라 fallback 이 아닌 정식 primary 다.
+// (PSMUX_BIN 변수 명은 backward-compat 위해 유지)
+//
 // 의존성: child_process, fs, os, path (Node.js 내장)만 사용
-import childProcess from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir, homedir } from "node:os";
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { formatPsmuxInstallGuidance } from "../../scripts/lib/psmux-info.mjs";
+import { resolveGitBashExecutable } from "@triflux/core/hub/lib/bash-path.mjs";
+import childProcess from "@triflux/core/hub/lib/spawn-trace.mjs";
 import { IS_WINDOWS } from "@triflux/core/hub/platform.mjs";
 
+// OS 별 primary multiplexer 를 명시적으로 결정한다.
+//   - PSMUX_BIN env 가 있으면 user override (가장 우선)
+//   - Windows: psmux 가 primary. PATH + 기본 설치 경로에서 탐색.
+//   - mac/Linux: tmux 가 primary. PATH 에서만 찾는다 (HomeBrew, apt 등 표준 위치).
+// silent fallback 은 두지 않는다 — primary 가 없으면 의도된 fail.
 const PSMUX_BIN = (() => {
   if (process.env.PSMUX_BIN) return process.env.PSMUX_BIN;
-  // PATH에서 찾기
-  try {
-    childProcess.execFileSync("psmux", ["-V"], { stdio: "ignore", timeout: 2000, windowsHide: true });
-    return "psmux";
-  } catch { /* not in PATH */ }
-  // Windows 기본 설치 경로 탐색
+
   if (IS_WINDOWS) {
+    // Windows primary: psmux
+    try {
+      childProcess.execFileSync("psmux", ["-V"], {
+        stdio: "ignore",
+        timeout: 2000,
+        windowsHide: true,
+      });
+      return "psmux";
+    } catch {
+      /* not in PATH */
+    }
     const candidates = [
       join(process.env.LOCALAPPDATA || "", "psmux", "psmux.exe"),
       join(process.env.APPDATA || "", "npm", "psmux.cmd"),
@@ -25,10 +55,23 @@ const PSMUX_BIN = (() => {
     for (const p of candidates) {
       if (existsSync(p)) return p;
     }
+    return "psmux"; // 최종 — hasPsmux/hasMultiplexer 가 검증
+  }
+
+  // mac/Linux primary: tmux (POSIX 표준). silent fallback 아님 — 정식 primary.
+  try {
+    childProcess.execFileSync("tmux", ["-V"], {
+      stdio: "ignore",
+      timeout: 2000,
+    });
+    return "tmux";
+  } catch {
+    /* tmux not in PATH — hasMultiplexer 가 false 반환할 것 */
   }
-  return "psmux"; // 최종 fallback — 원래대로
+  return "tmux";
 })();
-const GIT_BASH = process.env.GIT_BASH_PATH || "C:\\Program Files\\Git\\bin\\bash.exe";
+const GIT_BASH =
+  process.env.GIT_BASH_PATH || resolveGitBashExecutable() || "bash";
 
 /** Windows psmux 세션의 기본 셸을 PowerShell로 강제한다 (pwsh7 우선, ps5 fallback). */
 const PWSH_BIN = (() => {
@@ -36,26 +79,46 @@ const PWSH_BIN = (() => {
   if (process.env.PSMUX_SHELL) return process.env.PSMUX_SHELL;
   // pwsh 7 우선
   try {
-    childProcess.execFileSync("pwsh", ["-NoLogo", "-NoProfile", "-Command", "exit 0"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+    childProcess.execFileSync(
+      "pwsh",
+      ["-NoLogo", "-NoProfile", "-Command", "exit 0"],
+      { stdio: "ignore", timeout: 3000, windowsHide: true },
+    );
     return "pwsh";
-  } catch { /* not found */ }
+  } catch {
+    /* not found */
+  }
   // powershell 5 fallback
   try {
-    childProcess.execFileSync("powershell.exe", ["-NoLogo", "-NoProfile", "-Command", "exit 0"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+    childProcess.execFileSync(
+      "powershell.exe",
+      ["-NoLogo", "-NoProfile", "-Command", "exit 0"],
+      { stdio: "ignore", timeout: 3000, windowsHide: true },
+    );
     return "powershell.exe";
-  } catch { /* not found */ }
+  } catch {
+    /* not found */
+  }
   return ""; // 둘 다 없으면 psmux 기본 셸 사용
 })();
 const PSMUX_TIMEOUT_MS = 10000;
 const COMPLETION_PREFIX = "__TRIFLUX_DONE__:";
-const CAPTURE_ROOT = process.env.PSMUX_CAPTURE_ROOT || join(tmpdir(), "psmux-steering");
-const CAPTURE_HELPER_PATH = join(CAPTURE_ROOT, "pipe-pane-capture.ps1");
+const CAPTURE_ROOT =
+  process.env.PSMUX_CAPTURE_ROOT || join(tmpdir(), "psmux-steering");
+const CAPTURE_HELPER_PATH = join(
+  CAPTURE_ROOT,
+  IS_WINDOWS ? "pipe-pane-capture.ps1" : "pipe-pane-capture.sh",
+);
 const POLL_INTERVAL_MS = (() => {
   const ms = Number.parseInt(process.env.PSMUX_POLL_INTERVAL_MS || "", 10);
   if (Number.isFinite(ms) && ms > 0) return ms;
   const sec = Number.parseFloat(process.env.PSMUX_POLL_INTERVAL_SEC || "1");
-  return Number.isFinite(sec) && sec > 0 ? Math.max(100, Math.trunc(sec * 1000)) : 1000;
+  return Number.isFinite(sec) && sec > 0
+    ? Math.max(100, Math.trunc(sec * 1000))
+    : 1000;
 })();
+const PSMUX_SESSION_LIST_FORMAT =
+  "#{session_name}\t#{session_created}\t#{session_activity}\t#{session_attached}";
 
 function quoteArg(value) {
   const str = String(value);
@@ -67,6 +130,12 @@ function sanitizePathPart(value) {
   return String(value).replace(/[<>:"/\\|?*\u0000-\u001f']/gu, "_");
 }
 
+// session names retain regex metacharacters (`.`, `-`, `+`, …) even after
+// sanitizePathPart, so escape before embedding into a pgrep regex.
+export function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function toPaneTitle(index) {
   return index === 0 ? "lead" : `worker-${index}`;
 }
@@ -126,7 +195,7 @@ function tokenizeCommand(command) {
       continue;
     }
 
-    if (char === "\\" && next && (/[\s"'\\;]/u.test(next))) {
+    if (char === "\\" && next && /[\s"'\\;]/u.test(next)) {
       current += next;
       index += 1;
       continue;
@@ -165,10 +234,10 @@ function ensurePsmuxInstalled() {
   if (!hasPsmux()) {
     throw new Error(
       "psmux가 설치되어 있지 않습니다.\n\n" +
-      "psmux는 Codex/Gemini CLI를 병렬 세션으로 실행하는 터미널 멀티플렉서입니다.\n" +
-      "설치 방법 (택 1):\n" +
-      `${formatPsmuxInstallGuidance("  ")}\n\n` +
-      "설치 후 터미널을 재시작하세요."
+        "psmux는 Codex/Antigravity CLI를 병렬 세션으로 실행하는 터미널 멀티플렉서입니다.\n" +
+        "설치 방법 (택 1):\n" +
+        `${formatPsmuxInstallGuidance("  ")}\n\n` +
+        "설치 후 터미널을 재시작하세요.",
     );
   }
 }
@@ -178,39 +247,57 @@ function getCaptureSessionDir(sessionName) {
 }
 
 function getCaptureLogPath(sessionName, paneName) {
-  return join(getCaptureSessionDir(sessionName), `${sanitizePathPart(paneName)}.log`);
+  return join(
+    getCaptureSessionDir(sessionName),
+    `${sanitizePathPart(paneName)}.log`,
+  );
 }
 
 function ensureCaptureHelper() {
   mkdirSync(CAPTURE_ROOT, { recursive: true });
-  writeFileSync(
-    CAPTURE_HELPER_PATH,
-    [
-      "param(",
-      "  [Parameter(Mandatory = $true)][string]$Path",
-      ")",
-      "",
-      "$parent = Split-Path -Parent $Path",
-      "if ($parent) {",
-      "  New-Item -ItemType Directory -Force -Path $parent | Out-Null",
-      "}",
-      "",
-      "# Force UTF-8 encoding — CP949 등 non-UTF-8 codepage에서 Gemini stdout 캡처 실패 방지",
-      "# InputEncoding: pipe-pane에서 읽어들이는 바이트 해석",
-      "# OutputEncoding: 네이티브 명령(gemini/codex CLI)의 stdout 디코딩",
-      "# $OutputEncoding: PowerShell 파이프라인 기본 인코딩 (BOM 없는 UTF-8)",
-      "[Console]::InputEncoding = [System.Text.Encoding]::UTF8",
-      "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
-      "$OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
-      "",
-      "$reader = [Console]::In",
-      "while (($line = $reader.ReadLine()) -ne $null) {",
-      "  Add-Content -LiteralPath $Path -Value $line -Encoding utf8",
-      "}",
-      "",
-    ].join("\n"),
-    "utf8",
-  );
+  if (IS_WINDOWS) {
+    writeFileSync(
+      CAPTURE_HELPER_PATH,
+      [
+        "param(",
+        "  [Parameter(Mandatory = $true)][string]$Path",
+        ")",
+        "",
+        "$parent = Split-Path -Parent $Path",
+        "if ($parent) {",
+        "  New-Item -ItemType Directory -Force -Path $parent | Out-Null",
+        "}",
+        "",
+        "# Force UTF-8 encoding — CP949 등 non-UTF-8 codepage에서 Gemini stdout 캡처 실패 방지",
+        "# InputEncoding: pipe-pane에서 읽어들이는 바이트 해석",
+        "# OutputEncoding: 네이티브 명령(gemini/codex CLI)의 stdout 디코딩",
+        "# $OutputEncoding: PowerShell 파이프라인 기본 인코딩 (BOM 없는 UTF-8)",
+        "[Console]::InputEncoding = [System.Text.Encoding]::UTF8",
+        "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+        "$OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
+        "",
+        "$reader = [Console]::In",
+        "while (($line = $reader.ReadLine()) -ne $null) {",
+        "  Add-Content -LiteralPath $Path -Value $line -Encoding utf8",
+        "}",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+  } else {
+    // macOS/Linux: bash 스크립트로 pipe-pane 캡처
+    writeFileSync(
+      CAPTURE_HELPER_PATH,
+      [
+        "#!/bin/bash",
+        'mkdir -p "$(dirname "$1")" 2>/dev/null',
+        'exec tee -a "$1"',
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    chmodSync(CAPTURE_HELPER_PATH, 0o755);
+  }
   return CAPTURE_HELPER_PATH;
 }
 
@@ -235,33 +322,114 @@ function parsePaneList(output) {
     .map((entry) => entry.target);
 }
 
-function parseSessionSummaries(output) {
+function parsePsmuxEpoch(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return null;
+  const numeric = Number.parseInt(raw, 10);
+  if (!Number.isFinite(numeric) || numeric <= 0) return null;
+  return numeric >= 1_000_000_000_000 ? numeric : numeric * 1000;
+}
+
+function normalizeOlderThanMs(value, fallback = 0) {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.trunc(value));
+}
+
+function toTitleMatcher(pattern) {
+  if (!pattern) return () => true;
+  if (pattern instanceof RegExp) return (title) => pattern.test(title);
+
+  const raw = String(pattern).trim();
+  if (!raw) return () => true;
+  const regexMatch = raw.match(/^\/(.+)\/([a-z]*)$/i);
+  if (regexMatch) {
+    const [, source, flags] = regexMatch;
+    const regex = new RegExp(source, flags);
+    return (title) => regex.test(title);
+  }
+
+  return (title) => String(title).startsWith(raw);
+}
+
+function parseLegacySessionInventory(output) {
   return output
     .split("\n")
     .map((line) => line.trim())
     .filter(Boolean)
     .map((line) => {
       const colonIndex = line.indexOf(":");
-      if (colonIndex === -1) {
-        return null;
-      }
+      if (colonIndex === -1) return null;
 
       const sessionName = line.slice(0, colonIndex).trim();
-      const flags = [...line.matchAll(/\(([^)]*)\)/g)].map((match) => match[1]).join(", ");
+      const flags = [...line.matchAll(/\(([^)]*)\)/g)]
+        .map((match) => match[1])
+        .join(", ");
       const attachedMatch = flags.match(/(\d+)\s+attached/);
       const attachedCount = attachedMatch
-        ? parseInt(attachedMatch[1], 10)
+        ? Number.parseInt(attachedMatch[1], 10)
         : /\battached\b/.test(flags)
           ? 1
           : 0;
 
-      return sessionName
-        ? { sessionName, attachedCount }
-        : null;
+      if (!sessionName) return null;
+      return Object.freeze({
+        sessionName,
+        title: sessionName,
+        createdAt: null,
+        lastActivityAt: null,
+        attachedCount: Number.isFinite(attachedCount) ? attachedCount : 0,
+        isAttached: Number.isFinite(attachedCount) ? attachedCount > 0 : false,
+        ageMs: null,
+        idleMs: null,
+      });
+    })
+    .filter(Boolean);
+}
+
+function parseSessionInventory(output, now = Date.now()) {
+  return output
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [
+        sessionName = "",
+        createdText = "",
+        activityText = "",
+        attached = "0",
+      ] = line.split("\t");
+      const createdAt = parsePsmuxEpoch(createdText);
+      const lastActivityAt = parsePsmuxEpoch(activityText) ?? createdAt;
+      const attachedCount = Number.parseInt(attached, 10);
+      const ageMs = createdAt == null ? null : Math.max(0, now - createdAt);
+      const idleMs =
+        lastActivityAt == null ? ageMs : Math.max(0, now - lastActivityAt);
+
+      if (!sessionName) return null;
+      return Object.freeze({
+        sessionName,
+        title: sessionName,
+        createdAt,
+        lastActivityAt,
+        attachedCount: Number.isFinite(attachedCount) ? attachedCount : 0,
+        isAttached: Number.isFinite(attachedCount) ? attachedCount > 0 : false,
+        ageMs,
+        idleMs,
+      });
     })
     .filter(Boolean);
 }
 
+function listSessionInventoryRaw() {
+  const output = psmuxExec(["list-sessions", "-F", PSMUX_SESSION_LIST_FORMAT]);
+  const hasStructuredRows = output
+    .split("\n")
+    .some((line) => line.trim().includes("\t"));
+  return hasStructuredRows
+    ? parseSessionInventory(output)
+    : parseLegacySessionInventory(output);
+}
+
 function parsePaneDetails(output) {
   return output
     .split("\n")
@@ -269,20 +437,29 @@ function parsePaneDetails(output) {
     .filter(Boolean)
     .map((line) => {
       const parts = line.split("\t");
-      const hasPaneIndex = parts.length >= 5;
-      const [paneIndexText = "", title = "", paneId = "", dead = "0", deadStatus = ""] = hasPaneIndex
-        ? parts
-        : ["", ...parts];
-      const exitCode = dead === "1"
-        ? Number.parseInt(deadStatus, 10)
-        : null;
+      // tmux는 마지막 필드가 빈 문자열이면 trailing tab을 생략할 수 있음 (4개 필드)
+      // psmux는 항상 5개 필드를 반환
+      // paneId 패턴(session:N.N)이 parts[2]에 있으면 pane_index 포함 형식
+      const hasPaneIndex = parts.length >= 4 && /\S+:\d+\.\d+$/.test(parts[2]);
+      const [
+        paneIndexText = "",
+        title = "",
+        paneId = "",
+        dead = "0",
+        deadStatus = "",
+      ] = hasPaneIndex ? parts : ["", ...parts];
+      const exitCode = dead === "1" ? Number.parseInt(deadStatus, 10) : null;
       const paneIndex = Number.parseInt(paneIndexText, 10);
       return {
         title,
         paneId,
         paneIndex: Number.isFinite(paneIndex) ? paneIndex : null,
         isDead: dead === "1",
-        exitCode: Number.isFinite(exitCode) ? exitCode : dead === "1" ? 0 : null,
+        exitCode: Number.isFinite(exitCode)
+          ? exitCode
+          : dead === "1"
+            ? 0
+            : null,
       };
     })
     .filter((entry) => entry.paneId);
@@ -325,7 +502,9 @@ function resolvePane(sessionName, paneNameOrTarget) {
   const panes = listPaneDetails(sessionName);
 
   // 1차: title 또는 paneId 직접 매칭
-  const direct = panes.find((entry) => entry.title === wanted || entry.paneId === wanted);
+  const direct = panes.find(
+    (entry) => entry.title === wanted || entry.paneId === wanted,
+  );
   if (direct) return direct;
 
   // 2차: psmux title 미설정 fallback — "lead"→0, "worker-N"→N 인덱스 매칭
@@ -340,7 +519,14 @@ function refreshCaptureSnapshot(sessionName, paneNameOrTarget) {
   const paneName = pane.title || paneNameOrTarget;
   const logPath = getCaptureLogPath(sessionName, paneName);
   mkdirSync(getCaptureSessionDir(sessionName), { recursive: true });
-  const snapshot = psmuxExec(["capture-pane", "-t", pane.paneId, "-p", "-S", "-"]);
+  const snapshot = psmuxExec([
+    "capture-pane",
+    "-t",
+    pane.paneId,
+    "-p",
+    "-S",
+    "-",
+  ]);
   writeFileSync(logPath, snapshot, "utf8");
   return { paneId: pane.paneId, paneName, logPath, snapshot };
 }
@@ -369,7 +555,9 @@ export function sendKeysToPane(paneId, text, submit = true) {
 
 function toPatternRegExp(pattern) {
   if (pattern instanceof RegExp) {
-    const flags = pattern.flags.includes("m") ? pattern.flags : `${pattern.flags}m`;
+    const flags = pattern.flags.includes("m")
+      ? pattern.flags
+      : `${pattern.flags}m`;
     return new RegExp(pattern.source, flags);
   }
   return new RegExp(String(pattern), "m");
@@ -394,20 +582,24 @@ function psmux(args, opts = {}) {
     });
     return result != null ? String(result).trim() : "";
   } catch (error) {
-    const stderr = typeof error?.stderr === "string"
-      ? error.stderr
-      : error?.stderr?.toString?.("utf8") || "";
-    const stdout = typeof error?.stdout === "string"
-      ? error.stdout
-      : error?.stdout?.toString?.("utf8") || "";
-    const wrapped = new Error((stderr || stdout || error.message || "psmux command failed").trim());
+    const stderr =
+      typeof error?.stderr === "string"
+        ? error.stderr
+        : error?.stderr?.toString?.("utf8") || "";
+    const stdout =
+      typeof error?.stdout === "string"
+        ? error.stdout
+        : error?.stdout?.toString?.("utf8") || "";
+    const wrapped = new Error(
+      (stderr || stdout || error.message || "psmux command failed").trim(),
+    );
     wrapped.status = error.status;
     throw wrapped;
   }
 }
 
-/** psmux 실행 가능 여부 확인 */
-export function hasPsmux() {
+/** primary terminal multiplexer (Windows=psmux, mac/Linux=tmux) 실행 가능 여부 */
+export function hasMultiplexer() {
   try {
     childProcess.execFileSync(PSMUX_BIN, ["-V"], {
       stdio: "ignore",
@@ -420,6 +612,22 @@ export function hasPsmux() {
   }
 }
 
+/**
+ * backward-compat alias — historical 이름 `hasPsmux` 는 OS 별 primary 의 의미를
+ * 가린다. 외부 caller (scripts/remote-spawn.mjs, scripts/session-spawn-helper.mjs,
+ * tests) 호환을 위해 alias 로 보존. 신규 코드는 hasMultiplexer 사용.
+ */
+export const hasPsmux = hasMultiplexer;
+
+/**
+ * 현재 resolved multiplexer 종류 — "psmux" | "tmux" | <user override path>.
+ * isTmuxFallback() 의 후속 — mac/Linux 에서 tmux 는 fallback 이 아닌 primary 라
+ * "fallback" 표현이 부정확해서 type 으로 정정.
+ */
+export function getMultiplexerType() {
+  return PSMUX_BIN;
+}
+
 /**
  * psmux 커맨드 실행 래퍼
  * @param {string|string[]} args
@@ -439,12 +647,14 @@ export function psmuxExec(args, opts = {}) {
  * @returns {{ sessionName: string, panes: string[] }}
  */
 export function createPsmuxSession(sessionName, opts = {}) {
-  const layout = opts.layout === "1xN" || opts.layout === "Nx1" ? opts.layout : "2x2";
+  const layout =
+    opts.layout === "1xN" || opts.layout === "Nx1" ? opts.layout : "2x2";
   const paneCount = Math.max(
     1,
     Number.isFinite(opts.paneCount) ? Math.trunc(opts.paneCount) : 4,
   );
-  const limitedPaneCount = layout === "2x2" ? Math.min(paneCount, 4) : paneCount;
+  const limitedPaneCount =
+    layout === "2x2" ? Math.min(paneCount, 4) : paneCount;
   const sessionTarget = `${sessionName}:0`;
 
   const newSessionArgs = [
@@ -461,12 +671,24 @@ export function createPsmuxSession(sessionName, opts = {}) {
     "55",
   ];
   // Windows: psmux 기본 셸이 cmd.exe일 수 있으므로 PowerShell 강제
-  if (PWSH_BIN) newSessionArgs.push(PWSH_BIN, "-NoLogo", "-NoProfile");
+  // macOS/Linux: 기본 셸 사용 (PowerShell 플래그 불필요)
+  if (PWSH_BIN && IS_WINDOWS)
+    newSessionArgs.push(PWSH_BIN, "-NoLogo", "-NoProfile");
   const leadPane = psmuxExec(newSessionArgs);
 
-  // split-window로 생성되는 pane도 동일 셸 사용
-  if (PWSH_BIN) {
-    try { psmuxExec(["set-option", "-t", sessionName, "default-command", `${PWSH_BIN} -NoLogo -NoProfile`]); } catch { /* 미지원 시 무시 */ }
+  // split-window로 생성되는 pane도 동일 셸 사용 (Windows: PowerShell 강제)
+  if (PWSH_BIN && IS_WINDOWS) {
+    try {
+      psmuxExec([
+        "set-option",
+        "-t",
+        sessionName,
+        "default-command",
+        `${PWSH_BIN} -NoLogo -NoProfile`,
+      ]);
+    } catch {
+      /* 미지원 시 무시 */
+    }
   }
 
   if (layout === "2x2" && limitedPaneCount >= 3) {
@@ -516,7 +738,11 @@ export function createPsmuxSession(sessionName, opts = {}) {
 
   const panes = collectSessionPanes(sessionName).slice(0, limitedPaneCount);
   panes.forEach((pane, index) => {
-    psmuxExec(["select-pane", "-t", pane, "-T", toPaneTitle(index)]);
+    try {
+      psmuxExec(["select-pane", "-t", pane, "-T", toPaneTitle(index)]);
+    } catch {
+      // tmux 2.6 미만: select-pane -T 미지원 — pane title 없이 계속 진행
+    }
   });
 
   // CP949 등 non-UTF-8 codepage 환경에서 CLI stdout 깨짐 방지:
@@ -547,7 +773,11 @@ export function createPsmuxSession(sessionName, opts = {}) {
 function collectPanePids(sessionName) {
   try {
     const output = psmuxExec([
-      "list-panes", "-t", sessionName, "-F", "#{pane_pid}",
+      "list-panes",
+      "-t",
+      sessionName,
+      "-F",
+      "#{pane_pid}",
     ]);
     return output
       .split(/\r?\n/)
@@ -563,7 +793,64 @@ function collectPanePids(sessionName) {
  * @param {number} pid
  */
 function killProcessTree(pid) {
-  if (!IS_WINDOWS || !pid) return;
+  if (!pid) return;
+  if (!IS_WINDOWS) {
+    // macOS/Linux: BFS로 전체 자손 수집 → SIGTERM → SIGKILL 에스컬레이션
+    const collectChildren = (parentPid) => {
+      try {
+        return childProcess
+          .execFileSync("pgrep", ["-P", String(parentPid)], {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+          })
+          .trim()
+          .split("\n")
+          .filter(Boolean)
+          .map(Number);
+      } catch {
+        return [];
+      }
+    };
+    const allDesc = [];
+    const queue = [pid];
+    const seen = new Set([pid]);
+    while (queue.length > 0) {
+      const cur = queue.shift();
+      for (const child of collectChildren(cur)) {
+        if (!seen.has(child)) {
+          seen.add(child);
+          allDesc.push(child);
+          queue.push(child);
+        }
+      }
+    }
+    // SIGTERM 먼저
+    for (const c of allDesc) {
+      try {
+        process.kill(c, "SIGTERM");
+      } catch {}
+    }
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {}
+    // 1초 대기 후 생존자 SIGKILL
+    try {
+      childProcess.execFileSync("sleep", ["1"], {
+        timeout: 2000,
+        stdio: "ignore",
+      });
+    } catch {}
+    for (const c of allDesc) {
+      try {
+        process.kill(c, "SIGKILL");
+      } catch {}
+    }
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {}
+    return;
+  }
   try {
     childProcess.execSync(`taskkill /T /F /PID ${pid}`, {
       stdio: "ignore",
@@ -596,14 +883,51 @@ function disableAllPipeCaptures(sessionName, paneIds) {
  * @param {string} sessionName
  */
 function killOrphanPipeHelpers(sessionName) {
-  if (!IS_WINDOWS) return;
-  const safeSession = sanitizePathPart(sessionName);
+  if (!IS_WINDOWS) {
+    // macOS/Linux: pipe-pane helper cmdline contains
+    // `<CAPTURE_ROOT>/<session>/<pane>.log`, so anchor on `/<session>/`.
+    const safeSessionUnix = escapeRegex(sanitizePathPart(sessionName));
+    try {
+      const pids = childProcess
+        .execFileSync(
+          "pgrep",
+          ["-f", `pipe-pane-capture.*/${safeSessionUnix}/`],
+          {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+          },
+        )
+        .trim();
+      if (pids) {
+        for (const p of pids.split("\n").filter(Boolean)) {
+          try {
+            process.kill(Number(p), "SIGTERM");
+          } catch {}
+        }
+      }
+    } catch {
+      /* 프로세스 없으면 pgrep exit 1 — 무시 */
+    }
+    return;
+  }
+  // Windows: escape regex metacharacters and require a trailing path
+  // boundary so sibling sessions (e.g. `<session>2-...`) don't match.
+  const safeSession = escapeRegex(sanitizePathPart(sessionName));
   try {
     const output = childProcess.execSync(
-      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'pipe-pane-capture' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
-      { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'pipe-pane-capture' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}[-./\\\\]' } | Select-Object -ExpandProperty ProcessId"`,
+      {
+        encoding: "utf8",
+        timeout: 8000,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      },
     );
-    const pids = output.split(/\r?\n/).map((l) => Number.parseInt(l.trim(), 10)).filter((p) => Number.isFinite(p) && p > 0);
+    const pids = output
+      .split(/\r?\n/)
+      .map((l) => Number.parseInt(l.trim(), 10))
+      .filter((p) => Number.isFinite(p) && p > 0);
     for (const pid of pids) {
       killProcessTree(pid);
     }
@@ -619,13 +943,61 @@ function killOrphanPipeHelpers(sessionName) {
  * @param {string} sessionName
  */
 function killOrphanMcpProcesses(sessionName) {
-  if (!IS_WINDOWS) return;
-  const safeSession = sanitizePathPart(sessionName);
+  if (!IS_WINDOWS) {
+    // macOS/Linux: 세션별 스코핑 + Hub PID 보호
+    const safeSessionUnix = sanitizePathPart(sessionName);
+    let hubPidUnix = 0;
+    try {
+      const hubPidFile = join(
+        homedir(),
+        ".claude",
+        "cache",
+        "tfx-hub",
+        "hub.pid",
+      );
+      if (existsSync(hubPidFile)) {
+        const info = JSON.parse(readFileSync(hubPidFile, "utf8"));
+        hubPidUnix = Number(info.pid) || 0;
+      }
+    } catch {}
+    try {
+      // MCP/result files live under `tfx-headless/<session>-<pane>.txt`, so
+      // match `tfx-headless/<session>` with a trailing boundary to avoid
+      // killing sibling sessions whose names share a prefix
+      // (e.g. `<session>2-worker-1.txt`).
+      const escSession = escapeRegex(safeSessionUnix);
+      const pids = childProcess
+        .execFileSync("pgrep", ["-f", `tfx-headless/${escSession}[-./]`], {
+          encoding: "utf8",
+          timeout: 5000,
+          stdio: ["ignore", "pipe", "ignore"],
+        })
+        .trim();
+      if (pids) {
+        for (const p of pids.split("\n").filter(Boolean)) {
+          const numPid = Number(p);
+          if (numPid === hubPidUnix || numPid <= 0) continue;
+          try {
+            process.kill(numPid, "SIGTERM");
+          } catch {}
+        }
+      }
+    } catch {}
+    return;
+  }
+  // Windows: escape + trailing boundary (mirror of the macOS branch).
+  const safeSession = escapeRegex(sanitizePathPart(sessionName));
 
   // Hub PID 보호 — Hub 프로세스를 고아로 잘못 식별하지 않도록
   let hubPid = null;
   try {
-    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    const hubPidPath = join(
+      homedir(),
+      ".claude",
+      "cache",
+      "tfx-hub",
+      "hub.pid",
+    );
     if (existsSync(hubPidPath)) {
       const hubInfo = JSON.parse(readFileSync(hubPidPath, "utf8"));
       hubPid = Number(hubInfo?.pid);
@@ -635,10 +1007,18 @@ function killOrphanMcpProcesses(sessionName) {
   try {
     // 세션 결과 디렉토리 패턴으로 MCP 서버 프로세스 식별
     const output = childProcess.execSync(
-      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'node.exe' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}' } | Select-Object -ExpandProperty ProcessId"`,
-      { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+      `powershell -NoProfile -WindowStyle Hidden -Command "$ErrorActionPreference='SilentlyContinue'; Get-CimInstance Win32_Process | Where-Object { $_.Name -eq 'node.exe' -and $_.CommandLine -match 'tfx-headless[/\\\\]${safeSession}[-./\\\\]' } | Select-Object -ExpandProperty ProcessId"`,
+      {
+        encoding: "utf8",
+        timeout: 8000,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      },
     );
-    const pids = output.split(/\r?\n/).map((l) => Number.parseInt(l.trim(), 10)).filter((p) => Number.isFinite(p) && p > 0 && p !== hubPid);
+    const pids = output
+      .split(/\r?\n/)
+      .map((l) => Number.parseInt(l.trim(), 10))
+      .filter((p) => Number.isFinite(p) && p > 0 && p !== hubPid);
     for (const pid of pids) {
       killProcessTree(pid);
     }
@@ -661,12 +1041,15 @@ function detachAttachedClients(sessionName, waitMs = 750) {
 
 function findFallbackPane(sessionName, excludedPaneId) {
   try {
-    const panes = listPaneDetails(sessionName)
-      .filter((pane) => pane.paneId !== excludedPaneId && !pane.isDead);
+    const panes = listPaneDetails(sessionName).filter(
+      (pane) => pane.paneId !== excludedPaneId && !pane.isDead,
+    );
     if (panes.length === 0) return null;
-    return panes.find((pane) => pane.title === "lead")
-      || panes.find((pane) => pane.paneIndex === 0)
-      || panes[0];
+    return (
+      panes.find((pane) => pane.title === "lead") ||
+      panes.find((pane) => pane.paneIndex === 0) ||
+      panes[0]
+    );
   } catch {
     return null;
   }
@@ -711,6 +1094,94 @@ export function killPsmuxSession(sessionName) {
   killOrphanMcpProcesses(sessionName);
 }
 
+/**
+ * 활성 psmux 세션 메타데이터 조회
+ * @param {object} [opts]
+ * @param {string|RegExp} [opts.filterTitle] - 세션명 prefix 또는 /regex/flags
+ * @param {number} [opts.olderThanMs] - 생성 후 경과 시간 필터
+ * @returns {Array<{sessionName: string, title: string, createdAt: number|null, lastActivityAt: number|null, attachedCount: number, isAttached: boolean, ageMs: number|null, idleMs: number|null}>}
+ */
+export function listSessions(opts = {}) {
+  ensurePsmuxInstalled();
+  const matcher = toTitleMatcher(opts.filterTitle);
+  const olderThanMs = normalizeOlderThanMs(opts.olderThanMs, 0);
+
+  return listSessionInventoryRaw().filter((session) => {
+    if (!matcher(session.title)) return false;
+    if (olderThanMs <= 0) return true;
+    return Number.isFinite(session.ageMs) && session.ageMs >= olderThanMs;
+  });
+}
+
+/**
+ * 세션명 prefix/regex 역조회 후 세션 종료
+ * @param {string|RegExp} titlePattern
+ * @returns {{ matchedCount: number, killedCount: number, sessions: string[] }}
+ */
+export function killSessionByTitle(titlePattern) {
+  ensurePsmuxInstalled();
+  const sessions = listSessions({ filterTitle: titlePattern });
+  const killed = [];
+  for (const session of sessions) {
+    psmuxExec(["kill-session", "-t", session.sessionName], { stdio: "ignore" });
+    killed.push(session.sessionName);
+  }
+  return {
+    matchedCount: sessions.length,
+    killedCount: killed.length,
+    sessions: killed,
+  };
+}
+
+/**
+ * 오래 idle 상태인 detached 세션 일괄 정리
+ * @param {object} [opts]
+ * @param {number} [opts.olderThanMs=3600000]
+ * @param {boolean} [opts.dryRun=false]
+ * @returns {{ dryRun: boolean, matchedCount: number, killedCount: number, sessions: string[] }}
+ */
+export function pruneStale(opts = {}) {
+  ensurePsmuxInstalled();
+  const olderThanMs = normalizeOlderThanMs(opts.olderThanMs, 3600000);
+  const dryRun = opts.dryRun === true;
+  const sessions = listSessionInventoryRaw().filter((session) => {
+    if (session.isAttached) return false;
+    return Number.isFinite(session.idleMs) && session.idleMs >= olderThanMs;
+  });
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      matchedCount: sessions.length,
+      killedCount: 0,
+      sessions: sessions.map((session) => session.sessionName),
+    };
+  }
+
+  if (sessions.length === 0) {
+    return {
+      dryRun: false,
+      matchedCount: 0,
+      killedCount: 0,
+      sessions: [],
+    };
+  }
+
+  const result = killSessionByTitle(
+    new RegExp(
+      `^(?:${sessions
+        .map((session) => escapeRegExp(session.title))
+        .join("|")})$`,
+    ),
+  );
+  return {
+    dryRun: false,
+    matchedCount: sessions.length,
+    killedCount: result.killedCount,
+    sessions: result.sessions,
+  };
+}
+
 /**
  * psmux 세션 존재 확인
  * @param {string} sessionName
@@ -731,7 +1202,7 @@ export function psmuxSessionExists(sessionName) {
  */
 export function listPsmuxSessions() {
   try {
-    return parseSessionSummaries(psmuxExec(["list-sessions"]))
+    return listSessionInventoryRaw()
       .map((session) => session.sessionName)
       .filter((sessionName) => sessionName.startsWith("tfx-multi-"));
   } catch {
@@ -760,11 +1231,15 @@ export function capturePsmuxPane(target, lines = 5) {
  * @param {string} sessionName
  */
 export function attachPsmuxSession(sessionName) {
-  const result = childProcess.spawnSync(PSMUX_BIN, ["attach-session", "-t", sessionName], {
-    stdio: "inherit",
-    timeout: 0,
-    windowsHide: false,
-  });
+  const result = childProcess.spawnSync(
+    PSMUX_BIN,
+    ["attach-session", "-t", sessionName],
+    {
+      stdio: "inherit",
+      timeout: 0,
+      windowsHide: false,
+    },
+  );
   if ((result.status ?? 1) !== 0) {
     throw new Error(`psmux attach 실패 (exit=${result.status})`);
   }
@@ -777,8 +1252,9 @@ export function attachPsmuxSession(sessionName) {
  */
 export function getPsmuxSessionAttachedCount(sessionName) {
   try {
-    const session = parseSessionSummaries(psmuxExec(["list-sessions"]))
-      .find((entry) => entry.sessionName === sessionName);
+    const session = listSessionInventoryRaw().find(
+      (entry) => entry.sessionName === sessionName,
+    );
     return session ? session.attachedCount : null;
   } catch {
     return null;
@@ -812,12 +1288,78 @@ export function configurePsmuxKeybindings(sessionName, opts = {}) {
     }
   };
 
-  bindSafe(["bind-key", "-T", "root", "-n", "S-Down", "if-shell", "-F", cond, bindNext, "send-keys S-Down"]);
-  bindSafe(["bind-key", "-T", "root", "-n", "S-Up", "if-shell", "-F", cond, bindPrev, "send-keys S-Up"]);
-  bindSafe(["bind-key", "-T", "root", "-n", "S-Right", "if-shell", "-F", cond, bindNext, "send-keys S-Right"]);
-  bindSafe(["bind-key", "-T", "root", "-n", "S-Left", "if-shell", "-F", cond, bindPrev, "send-keys S-Left"]);
-  bindSafe(["bind-key", "-T", "root", "-n", "BTab", "if-shell", "-F", cond, bindPrev, "send-keys BTab"]);
-  bindSafe(["bind-key", "-T", "root", "-n", "Escape", "if-shell", "-F", cond, "send-keys C-c", "send-keys Escape"]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "S-Down",
+    "if-shell",
+    "-F",
+    cond,
+    bindNext,
+    "send-keys S-Down",
+  ]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "S-Up",
+    "if-shell",
+    "-F",
+    cond,
+    bindPrev,
+    "send-keys S-Up",
+  ]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "S-Right",
+    "if-shell",
+    "-F",
+    cond,
+    bindNext,
+    "send-keys S-Right",
+  ]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "S-Left",
+    "if-shell",
+    "-F",
+    cond,
+    bindPrev,
+    "send-keys S-Left",
+  ]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "BTab",
+    "if-shell",
+    "-F",
+    cond,
+    bindPrev,
+    "send-keys BTab",
+  ]);
+  bindSafe([
+    "bind-key",
+    "-T",
+    "root",
+    "-n",
+    "Escape",
+    "if-shell",
+    "-F",
+    cond,
+    "send-keys C-c",
+    "send-keys Escape",
+  ]);
 
   if (taskListCommand) {
     bindSafe([
@@ -853,12 +1395,10 @@ export function startCapture(sessionName, paneNameOrTarget) {
   writeFileSync(logPath, "", "utf8");
 
   disablePipeCapture(pane.paneId);
-  psmuxExec([
-    "pipe-pane",
-    "-t",
-    pane.paneId,
-    `powershell.exe -NoLogo -NoProfile -File ${quoteArg(helperPath)} ${quoteArg(logPath)}`,
-  ]);
+  const pipePaneCmd = IS_WINDOWS
+    ? `powershell.exe -NoLogo -NoProfile -File ${quoteArg(helperPath)} ${quoteArg(logPath)}`
+    : `${quoteArg(helperPath)} ${quoteArg(logPath)}`;
+  psmuxExec(["pipe-pane", "-t", pane.paneId, pipePaneCmd]);
 
   refreshCaptureSnapshot(sessionName, pane.paneId);
   return { paneId: pane.paneId, paneName, logPath };
@@ -872,10 +1412,10 @@ export function startCapture(sessionName, paneNameOrTarget) {
  * @returns {{ paneId: string, paneName: string, token: string, logPath: string }}
  */
 /**
- * CLI 명령(codex/gemini)이 psmux pane의 PowerShell 환경에서 단축 플래그 충돌을
+ * CLI 명령(codex/legacy Gemini)이 psmux pane의 PowerShell 환경에서 단축 플래그 충돌을
  * 일으키는 문제를 방지하기 위해 bash -c '...' 로 감싼다.
  * - codex -o flag → PS -OutVariable/OutBuffer 충돌
- * - gemini --prompt flag (v8.6.0: -p → --prompt, PS 충돌 해소)
+ * - legacy Gemini prompt flag (v8.6.0: -p → long-form prompt flag, PS 충돌 해소)
  * @param {string} cmd
  * @returns {string}
  */
@@ -883,17 +1423,7 @@ export function startCapture(sessionName, paneNameOrTarget) {
 // WSL bash에서는 /c/Users/... 경로가 유효하지 않아 exit 127 발생.
 // psmux pane 용 (PowerShell → bash 실행): & "path" 형식
 // Node.js execSync 용 (직접 실행): "path" 형식
-const _gitBashPath = (() => {
-  if (!IS_WINDOWS) return null;
-  const candidates = [
-    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
-    "C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe",
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
-  }
-  return null;
-})();
+const _gitBashPath = IS_WINDOWS ? resolveGitBashExecutable() : null;
 // PowerShell call operator(&)가 필요: & "C:\...\bash.exe" -c '...'
 const GIT_BASH_BIN_PS = _gitBashPath ? `& "${_gitBashPath}"` : "bash";
 // Node.js execSync에서 직접 실행할 때는 따옴표만
@@ -905,7 +1435,10 @@ function resolveCliAbsPath(name) {
   if (_cliPathCache.has(name)) return _cliPathCache.get(name);
   try {
     const resolved = childProcess
-      .execSync(`${GIT_BASH_BIN_EXEC} -c "which ${name}"`, { encoding: "utf8", timeout: 3000 })
+      .execSync(`${GIT_BASH_BIN_EXEC} -c "which ${name}"`, {
+        encoding: "utf8",
+        timeout: 3000,
+      })
       .trim();
     if (resolved) _cliPathCache.set(name, resolved);
     return resolved || name;
@@ -922,9 +1455,10 @@ function wrapCliForBash(cmd) {
   if (!cliMatch) return cmd;
   // Node.js 측에서 절대 경로 resolve → psmux pane의 bash PATH 불일치 문제 해결 (exit 127)
   const absPath = resolveCliAbsPath(cliMatch[1]);
-  const resolved = absPath !== cliMatch[1]
-    ? trimmed.replace(new RegExp(`^${cliMatch[1]}\\b`), absPath)
-    : trimmed;
+  const resolved =
+    absPath !== cliMatch[1]
+      ? trimmed.replace(new RegExp(`^${cliMatch[1]}\\b`), absPath)
+      : trimmed;
   // 단일 따옴표 이스케이프: ' → '\''
   const escaped = resolved.replace(/'/g, "'\\''");
   return `${GIT_BASH_BIN_PS} -c '${escaped}'`;
@@ -941,10 +1475,17 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
   }
 
   const token = randomToken(paneName);
-  const safeCommand = wrapCliForBash(commandText);
-  // CP949 등 non-UTF-8 codepage 환경에서 CLI stdout이 깨지는 문제 방지 (belt-and-suspenders)
-  const chcpPrefix = IS_WINDOWS ? "chcp 65001 > $null; " : "";
-  const wrapped = `${chcpPrefix}try { ${safeCommand} } finally { $trifluxExit = if ($null -ne $LASTEXITCODE) { [int]$LASTEXITCODE } else { 0 }; Write-Output "${COMPLETION_PREFIX}${token}:$trifluxExit" }`;
+  const safeCommand = IS_WINDOWS ? wrapCliForBash(commandText) : commandText;
+
+  let wrapped;
+  if (IS_WINDOWS) {
+    // CP949 등 non-UTF-8 codepage 환경에서 CLI stdout이 깨지는 문제 방지 (belt-and-suspenders)
+    const chcpPrefix = "chcp 65001 > $null; ";
+    wrapped = `${chcpPrefix}try { ${safeCommand} } finally { $trifluxExit = if ($null -ne $LASTEXITCODE) { [int]$LASTEXITCODE } else { 0 }; Write-Output "${COMPLETION_PREFIX}${token}:$trifluxExit" }`;
+  } else {
+    // macOS/Linux: bash 구문으로 완료 토큰 출력
+    wrapped = `{ ${safeCommand}; __ec=$?; echo "${COMPLETION_PREFIX}${token}:$__ec"; }`;
+  }
 
   sendLiteralToPane(pane.paneId, wrapped, true);
 
@@ -962,7 +1503,13 @@ export function dispatchCommand(sessionName, paneNameOrTarget, commandText) {
  * @param {AbortSignal} [opts.signal] — 외부에서 폴링 중단 요청 시 사용
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, aborted?: boolean }}
  */
-export async function waitForPattern(sessionName, paneNameOrTarget, pattern, timeoutSec = 300, opts = {}) {
+export async function waitForPattern(
+  sessionName,
+  paneNameOrTarget,
+  pattern,
+  timeoutSec = 300,
+  opts = {},
+) {
   ensurePsmuxInstalled();
 
   // E4 크래시 복구: 초기 resolvePane도 세션 사망을 감지
@@ -985,11 +1532,14 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
 
   const paneName = pane.title || paneNameOrTarget;
   // opts.logPath: dispatch 시 확정된 캡처 로그 경로 직접 지정 (타이틀 변경 내성)
-  const logPath = (opts.logPath && existsSync(opts.logPath))
-    ? opts.logPath
-    : getCaptureLogPath(sessionName, paneName);
+  const logPath =
+    opts.logPath && existsSync(opts.logPath)
+      ? opts.logPath
+      : getCaptureLogPath(sessionName, paneName);
   if (!existsSync(logPath)) {
-    throw new Error(`캡처 로그가 없습니다. 먼저 startCapture(${sessionName}, ${paneName})를 호출하세요.`);
+    throw new Error(
+      `캡처 로그가 없습니다. 먼저 startCapture(${sessionName}, ${paneName})를 호출하세요.`,
+    );
   }
 
   const startTime = Date.now();
@@ -997,18 +1547,39 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
   const regex = toPatternRegExp(pattern);
 
   if (opts?.signal?.aborted) {
-    return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+    return {
+      matched: false,
+      paneId: pane.paneId,
+      paneName,
+      logPath,
+      match: null,
+      aborted: true,
+    };
   }
 
   while (Date.now() <= deadline) {
     if (opts?.signal?.aborted) {
-      return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+      return {
+        matched: false,
+        paneId: pane.paneId,
+        paneName,
+        logPath,
+        match: null,
+        aborted: true,
+      };
     }
     // E4 크래시 복구: capture 실패 시 세션 생존 체크
     try {
       if (opts.logPath) {
         // logPath 직접 지정 시 — 셸 타이틀 변경과 무관하게 올바른 파일에 기록
-        const snapshot = psmuxExec(["capture-pane", "-t", pane.paneId, "-p", "-S", "-"]);
+        const snapshot = psmuxExec([
+          "capture-pane",
+          "-t",
+          pane.paneId,
+          "-p",
+          "-S",
+          "-",
+        ]);
         writeFileSync(logPath, snapshot, "utf8");
       } else {
         refreshCaptureSnapshot(sessionName, pane.paneId);
@@ -1032,8 +1603,15 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     // onPoll 콜백 — 각 폴링 주기마다 중간 상태 전달
     if (opts.onPoll) {
       try {
-        opts.onPoll({ content, paneId: pane.paneId, paneName, elapsed: Date.now() - startTime });
-      } catch { /* 콜백 예외는 삼킴 — 폴링 루프 보호 */ }
+        opts.onPoll({
+          content,
+          paneId: pane.paneId,
+          paneName,
+          elapsed: Date.now() - startTime,
+        });
+      } catch {
+        /* 콜백 예외는 삼킴 — 폴링 루프 보호 */
+      }
     }
 
     const match = regex.exec(content);
@@ -1052,7 +1630,14 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
     }
     await sleepMsAsync(POLL_INTERVAL_MS);
     if (opts?.signal?.aborted) {
-      return { matched: false, paneId: pane.paneId, paneName, logPath, match: null, aborted: true };
+      return {
+        matched: false,
+        paneId: pane.paneId,
+        paneName,
+        logPath,
+        match: null,
+        aborted: true,
+      };
     }
   }
 
@@ -1067,6 +1652,7 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
 
 /**
  * 완료 토큰이 찍힐 때까지 대기하고 exit code를 파싱한다.
+ * NOTE: 주 채널은 headless.waitForCompletionWithStallDetect이며, 본 함수는 fallback 채널이다.
  * @param {string} sessionName
  * @param {string} paneNameOrTarget
  * @param {string} token
@@ -1074,19 +1660,38 @@ export async function waitForPattern(sessionName, paneNameOrTarget, pattern, tim
  * @param {object} [opts] — waitForPattern에 전달할 옵션 (onPoll 등)
  * @returns {{ matched: boolean, paneId: string, paneName: string, logPath: string, match: string|null, token: string, exitCode: number|null }}
  */
-export async function waitForCompletion(sessionName, paneNameOrTarget, token, timeoutSec = 300, opts = {}) {
+export async function waitForCompletion(
+  sessionName,
+  paneNameOrTarget,
+  token,
+  timeoutSec = 300,
+  opts = {},
+) {
   const completionRegex = new RegExp(
     `${escapeRegExp(COMPLETION_PREFIX)}${escapeRegExp(token)}:(\\d+)`,
     "m",
   );
-  const result = await waitForPattern(sessionName, paneNameOrTarget, completionRegex, timeoutSec, opts);
+  const result = await waitForPattern(
+    sessionName,
+    paneNameOrTarget,
+    completionRegex,
+    timeoutSec,
+    opts,
+  );
 
   // 타이밍 이슈 대응: matched=false인 경우 500ms 대기 후 최종 1회 캡처 재시도
   if (!result.matched && !result.sessionDead && result.logPath) {
     await new Promise((r) => setTimeout(r, 500));
     try {
       const pane = resolvePane(sessionName, paneNameOrTarget);
-      const snapshot = psmuxExec(["capture-pane", "-t", pane.paneId, "-p", "-S", "-"]);
+      const snapshot = psmuxExec([
+        "capture-pane",
+        "-t",
+        pane.paneId,
+        "-p",
+        "-S",
+        "-",
+      ]);
       writeFileSync(result.logPath, snapshot, "utf8");
       const content = readCaptureLog(result.logPath);
       const retryMatch = completionRegex.exec(content);
@@ -1125,7 +1730,7 @@ export function spawnWorker(sessionName, workerName, cmd) {
   if (!hasPsmux()) {
     throw new Error(
       "psmux가 설치되어 있지 않습니다.\n" +
-      `설치 방법:\n${formatPsmuxInstallGuidance("  ")}`
+        `설치 방법:\n${formatPsmuxInstallGuidance("  ")}`,
     );
   }
 
@@ -1152,10 +1757,16 @@ export function spawnWorker(sessionName, workerName, cmd) {
       "#{session_name}:#{window_index}.#{pane_index}",
       shellCmd,
     ]);
-    psmuxExec(["select-pane", "-t", paneTarget, "-T", workerName]);
+    try {
+      psmuxExec(["select-pane", "-t", paneTarget, "-T", workerName]);
+    } catch {
+      // tmux 2.6 미만: select-pane -T 미지원 — 무시
+    }
     return { paneId: paneTarget, workerName };
   } catch (err) {
-    throw new Error(`워커 생성 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+    throw new Error(
+      `워커 생성 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`,
+    );
   }
 }
 
@@ -1167,7 +1778,9 @@ export function spawnWorker(sessionName, workerName, cmd) {
  */
 export function getWorkerStatus(sessionName, workerName) {
   if (!hasPsmux()) {
-    throw new Error(`psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`);
+    throw new Error(
+      `psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`,
+    );
   }
   try {
     const pane = resolvePane(sessionName, workerName);
@@ -1180,7 +1793,9 @@ export function getWorkerStatus(sessionName, workerName) {
     if (err.message.includes("Pane을 찾을 수 없습니다")) {
       throw new Error(`워커를 찾을 수 없습니다: ${workerName}`);
     }
-    throw new Error(`워커 상태 조회 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+    throw new Error(
+      `워커 상태 조회 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`,
+    );
   }
 }
 
@@ -1192,14 +1807,15 @@ export function getWorkerStatus(sessionName, workerName) {
  */
 export function killWorker(sessionName, workerName) {
   if (!hasPsmux()) {
-    throw new Error(`psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`);
+    throw new Error(
+      `psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`,
+    );
   }
   try {
     const { paneId, status } = getWorkerStatus(sessionName, workerName);
     const attachedCount = getPsmuxSessionAttachedCount(sessionName);
-    const fallbackPane = attachedCount > 0
-      ? findFallbackPane(sessionName, paneId)
-      : null;
+    const fallbackPane =
+      attachedCount > 0 ? findFallbackPane(sessionName, paneId) : null;
 
     if (fallbackPane?.paneId) {
       try {
@@ -1214,7 +1830,13 @@ export function killWorker(sessionName, workerName) {
 
     // pane PID 수집 → 프로세스 트리 정리 (MCP 서버 좀비 방지)
     try {
-      const pidOutput = psmuxExec(["list-panes", "-t", paneId, "-F", "#{pane_pid}"]);
+      const pidOutput = psmuxExec([
+        "list-panes",
+        "-t",
+        paneId,
+        "-F",
+        "#{pane_pid}",
+      ]);
       const pid = Number.parseInt(pidOutput.trim(), 10);
       if (Number.isFinite(pid) && pid > 0) killProcessTree(pid);
     } catch {
@@ -1266,7 +1888,9 @@ export function killWorker(sessionName, workerName) {
     if (err.message.includes("워커를 찾을 수 없습니다")) {
       return { killed: true };
     }
-    throw new Error(`워커 종료 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+    throw new Error(
+      `워커 종료 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`,
+    );
   }
 }
 
@@ -1279,14 +1903,18 @@ export function killWorker(sessionName, workerName) {
  */
 export function captureWorkerOutput(sessionName, workerName, lines = 50) {
   if (!hasPsmux()) {
-    throw new Error(`psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`);
+    throw new Error(
+      `psmux 미설치. 설치 방법:\n${formatPsmuxInstallGuidance("  ")}`,
+    );
   }
   try {
     const { paneId } = getWorkerStatus(sessionName, workerName);
     return psmuxExec(["capture-pane", "-t", paneId, "-p", "-S", `-${lines}`]);
   } catch (err) {
     if (err.message.includes("워커를 찾을 수 없습니다")) throw err;
-    throw new Error(`출력 캡처 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`);
+    throw new Error(
+      `출력 캡처 실패 (session=${sessionName}, worker=${workerName}): ${err.message}`,
+    );
   }
 }
 
@@ -1294,123 +1922,236 @@ export function captureWorkerOutput(sessionName, workerName, lines = 50) {
 
 if (process.argv[1]?.endsWith("psmux.mjs")) {
   (async () => {
-  const [, , cmd, ...args] = process.argv;
-
-  // CLI 인자 파싱 헬퍼
-  function getArg(name) {
-    const idx = args.indexOf(`--${name}`);
-    return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
-  }
+    const rawArgs = process.argv.slice(2);
+    const internalMode = rawArgs[0] === "--internal";
+    const cmd = internalMode ? rawArgs[1] : rawArgs[0];
+    const args = internalMode ? rawArgs.slice(2) : rawArgs.slice(1);
+
+    // CLI 인자 파싱 헬퍼
+    function getArg(name) {
+      const idx = args.indexOf(`--${name}`);
+      return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+    }
 
-  try {
-    switch (cmd) {
-      case "spawn": {
-        const session = getArg("session");
-        const name = getArg("name");
-        const workerCmd = getArg("cmd");
-        if (!session || !name || !workerCmd) {
-          console.error("사용법: node psmux.mjs spawn --session <세션> --name <워커명> --cmd <커맨드>");
-          process.exit(1);
+    try {
+      if (internalMode) {
+        switch (cmd) {
+          case "list": {
+            const olderThanMs = getArg("olderThanMs");
+            const filterTitle = getArg("filterTitle");
+            console.log(
+              JSON.stringify(
+                listSessions({
+                  filterTitle,
+                  olderThanMs:
+                    olderThanMs == null
+                      ? undefined
+                      : Number.parseInt(olderThanMs, 10),
+                }),
+                null,
+                2,
+              ),
+            );
+            break;
+          }
+          case "kill-by-title": {
+            const pattern = args[0];
+            if (!pattern) {
+              console.error(
+                "사용법: node psmux.mjs --internal kill-by-title <title-prefix|/regex/>",
+              );
+              process.exit(1);
+            }
+            console.log(JSON.stringify(killSessionByTitle(pattern), null, 2));
+            break;
+          }
+          case "prune-stale": {
+            const olderThanMs = getArg("olderThanMs");
+            const dryRun = args.includes("--dry-run");
+            console.log(
+              JSON.stringify(
+                pruneStale({
+                  olderThanMs:
+                    olderThanMs == null
+                      ? undefined
+                      : Number.parseInt(olderThanMs, 10),
+                  dryRun,
+                }),
+                null,
+                2,
+              ),
+            );
+            break;
+          }
+          default:
+            console.error(
+              "사용법: node psmux.mjs --internal list [--filterTitle <prefix|/regex/>] [--olderThanMs <ms>]",
+            );
+            console.error(
+              "    또는: node psmux.mjs --internal kill-by-title <prefix|/regex/>",
+            );
+            console.error(
+              "    또는: node psmux.mjs --internal prune-stale [--olderThanMs <ms>] [--dry-run]",
+            );
+            process.exit(1);
         }
-        console.log(JSON.stringify(spawnWorker(session, name, workerCmd), null, 2));
-        break;
+        return;
       }
-      case "status": {
-        const session = getArg("session");
-        const name = getArg("name");
-        if (!session || !name) {
-          console.error("사용법: node psmux.mjs status --session <세션> --name <워커명>");
-          process.exit(1);
+
+      switch (cmd) {
+        case "spawn": {
+          const session = getArg("session");
+          const name = getArg("name");
+          const workerCmd = getArg("cmd");
+          if (!session || !name || !workerCmd) {
+            console.error(
+              "사용법: node psmux.mjs spawn --session <세션> --name <워커명> --cmd <커맨드>",
+            );
+            process.exit(1);
+          }
+          console.log(
+            JSON.stringify(spawnWorker(session, name, workerCmd), null, 2),
+          );
+          break;
         }
-        console.log(JSON.stringify(getWorkerStatus(session, name), null, 2));
-        break;
-      }
-      case "kill": {
-        const session = getArg("session");
-        const name = getArg("name");
-        if (!session || !name) {
-          console.error("사용법: node psmux.mjs kill --session <세션> --name <워커명>");
-          process.exit(1);
+        case "status": {
+          const session = getArg("session");
+          const name = getArg("name");
+          if (!session || !name) {
+            console.error(
+              "사용법: node psmux.mjs status --session <세션> --name <워커명>",
+            );
+            process.exit(1);
+          }
+          console.log(JSON.stringify(getWorkerStatus(session, name), null, 2));
+          break;
         }
-        console.log(JSON.stringify(killWorker(session, name), null, 2));
-        break;
-      }
-      case "output": {
-        const session = getArg("session");
-        const name = getArg("name");
-        const lines = parseInt(getArg("lines") || "50", 10);
-        if (!session || !name) {
-          console.error("사용법: node psmux.mjs output --session <세션> --name <워커명> [--lines <줄수>]");
-          process.exit(1);
+        case "kill": {
+          const session = getArg("session");
+          const name = getArg("name");
+          if (!session || !name) {
+            console.error(
+              "사용법: node psmux.mjs kill --session <세션> --name <워커명>",
+            );
+            process.exit(1);
+          }
+          console.log(JSON.stringify(killWorker(session, name), null, 2));
+          break;
         }
-        console.log(captureWorkerOutput(session, name, lines));
-        break;
-      }
-      case "capture-start": {
-        const session = getArg("session");
-        const name = getArg("name");
-        if (!session || !name) {
-          console.error("사용법: node psmux.mjs capture-start --session <세션> --name <pane>");
-          process.exit(1);
+        case "output": {
+          const session = getArg("session");
+          const name = getArg("name");
+          const lines = parseInt(getArg("lines") || "50", 10);
+          if (!session || !name) {
+            console.error(
+              "사용법: node psmux.mjs output --session <세션> --name <워커명> [--lines <줄수>]",
+            );
+            process.exit(1);
+          }
+          console.log(captureWorkerOutput(session, name, lines));
+          break;
         }
-        console.log(JSON.stringify(startCapture(session, name), null, 2));
-        break;
-      }
-      case "dispatch": {
-        const session = getArg("session");
-        const name = getArg("name");
-        const commandText = getArg("command");
-        if (!session || !name || !commandText) {
-          console.error("사용법: node psmux.mjs dispatch --session <세션> --name <pane> --command <PowerShell 명령>");
-          process.exit(1);
+        case "capture-start": {
+          const session = getArg("session");
+          const name = getArg("name");
+          if (!session || !name) {
+            console.error(
+              "사용법: node psmux.mjs capture-start --session <세션> --name <pane>",
+            );
+            process.exit(1);
+          }
+          console.log(JSON.stringify(startCapture(session, name), null, 2));
+          break;
         }
-        console.log(JSON.stringify(dispatchCommand(session, name, commandText), null, 2));
-        break;
-      }
-      case "wait-pattern": {
-        const session = getArg("session");
-        const name = getArg("name");
-        const pattern = getArg("pattern");
-        const timeoutSec = parseInt(getArg("timeout") || "300", 10);
-        if (!session || !name || !pattern) {
-          console.error("사용법: node psmux.mjs wait-pattern --session <세션> --name <pane> --pattern <정규식> [--timeout <초>]");
-          process.exit(1);
+        case "dispatch": {
+          const session = getArg("session");
+          const name = getArg("name");
+          const commandText = getArg("command");
+          if (!session || !name || !commandText) {
+            console.error(
+              "사용법: node psmux.mjs dispatch --session <세션> --name <pane> --command <PowerShell 명령>",
+            );
+            process.exit(1);
+          }
+          console.log(
+            JSON.stringify(
+              dispatchCommand(session, name, commandText),
+              null,
+              2,
+            ),
+          );
+          break;
         }
-        const result = await waitForPattern(session, name, pattern, timeoutSec);
-        console.log(JSON.stringify(result, null, 2));
-        if (!result.matched) process.exit(2);
-        break;
-      }
-      case "wait-completion": {
-        const session = getArg("session");
-        const name = getArg("name");
-        const token = getArg("token");
-        const timeoutSec = parseInt(getArg("timeout") || "300", 10);
-        if (!session || !name || !token) {
-          console.error("사용법: node psmux.mjs wait-completion --session <세션> --name <pane> --token <토큰> [--timeout <초>]");
-          process.exit(1);
+        case "wait-pattern": {
+          const session = getArg("session");
+          const name = getArg("name");
+          const pattern = getArg("pattern");
+          const timeoutSec = parseInt(getArg("timeout") || "300", 10);
+          if (!session || !name || !pattern) {
+            console.error(
+              "사용법: node psmux.mjs wait-pattern --session <세션> --name <pane> --pattern <정규식> [--timeout <초>]",
+            );
+            process.exit(1);
+          }
+          const result = await waitForPattern(
+            session,
+            name,
+            pattern,
+            timeoutSec,
+          );
+          console.log(JSON.stringify(result, null, 2));
+          if (!result.matched) process.exit(2);
+          break;
+        }
+        case "wait-completion": {
+          const session = getArg("session");
+          const name = getArg("name");
+          const token = getArg("token");
+          const timeoutSec = parseInt(getArg("timeout") || "300", 10);
+          if (!session || !name || !token) {
+            console.error(
+              "사용법: node psmux.mjs wait-completion --session <세션> --name <pane> --token <토큰> [--timeout <초>]",
+            );
+            process.exit(1);
+          }
+          const result = await waitForCompletion(
+            session,
+            name,
+            token,
+            timeoutSec,
+          );
+          console.log(JSON.stringify(result, null, 2));
+          if (!result.matched) process.exit(2);
+          break;
         }
-        const result = await waitForCompletion(session, name, token, timeoutSec);
-        console.log(JSON.stringify(result, null, 2));
-        if (!result.matched) process.exit(2);
-        break;
+        default:
+          console.error(
+            "사용법: node psmux.mjs spawn|status|kill|output|capture-start|dispatch|wait-pattern|wait-completion [args]",
+          );
+          console.error("");
+          console.error(
+            "  spawn            --session <세션> --name <워커명> --cmd <커맨드>",
+          );
+          console.error("  status           --session <세션> --name <워커명>");
+          console.error("  kill             --session <세션> --name <워커명>");
+          console.error(
+            "  output           --session <세션> --name <워커명> [--lines <줄수>]",
+          );
+          console.error("  capture-start    --session <세션> --name <pane>");
+          console.error(
+            "  dispatch         --session <세션> --name <pane> --command <PowerShell 명령>",
+          );
+          console.error(
+            "  wait-pattern     --session <세션> --name <pane> --pattern <정규식> [--timeout <초>]",
+          );
+          console.error(
+            "  wait-completion  --session <세션> --name <pane> --token <토큰> [--timeout <초>]",
+          );
+          process.exit(1);
       }
-      default:
-        console.error("사용법: node psmux.mjs spawn|status|kill|output|capture-start|dispatch|wait-pattern|wait-completion [args]");
-        console.error("");
-        console.error("  spawn            --session <세션> --name <워커명> --cmd <커맨드>");
-        console.error("  status           --session <세션> --name <워커명>");
-        console.error("  kill             --session <세션> --name <워커명>");
-        console.error("  output           --session <세션> --name <워커명> [--lines <줄수>]");
-        console.error("  capture-start    --session <세션> --name <pane>");
-        console.error("  dispatch         --session <세션> --name <pane> --command <PowerShell 명령>");
-        console.error("  wait-pattern     --session <세션> --name <pane> --pattern <정규식> [--timeout <초>]");
-        console.error("  wait-completion  --session <세션> --name <pane> --token <토큰> [--timeout <초>]");
-        process.exit(1);
+    } catch (err) {
+      console.error(`오류: ${err.message}`);
+      process.exit(1);
     }
-  } catch (err) {
-    console.error(`오류: ${err.message}`);
-    process.exit(1);
-  }
   })();
 }