triflux 10.17.3 → 10.18.0

package/CLAUDE.md

@@ -0,0 +1,169 @@
+# triflux — Claude Code 운영 가이드
+
+<core-systems>
+## 핵심 스킬 시스템 (항상 인지)
+
+이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
+
+| 시스템 | 접두사 | 용도 | 스킬 수 |
+|--------|--------|------|---------|
+| **triflux** | `/tfx-*` | CLI 라우팅, 멀티모델 오케스트레이션, 스웜, 원격 실행 | ~40개 |
+| **gstack** | `/` (접두사 없음) | QA, ship, investigate, design, review, checkpoint | ~35개 |
+| **omc** | `/oh-my-claudecode:*` | autopilot, ralph, team, ultrawork, ccg | ~25개 |
+
+스킬을 모르면 자연어 라우팅(`.claude/rules/tfx-routing.md`)으로 자동 매핑된다.
+세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+</core-systems>
+
+<psmux-wt>
+## psmux/WT 규칙
+
+psmux 세션·WT 패인을 생성/조작/정리할 때 `tfx-psmux-rules` 스킬을 참조한다.
+WT 프리징 방지: exit → sleep 2 → kill 순서. 바로 kill하지 않는다.
+
+### wt.exe → wt-manager 경유
+
+safety-guard가 `wt.exe`, `wt new-tab`, `wt split-pane`, `Start-Process wt`를 차단한다.
+`hub/team/wt-manager.mjs`의 API를 사용한다.
+
+| 용도 | API |
+|------|-----|
+| 새 탭 | `createTab({ title, command, profile, cwd })` |
+| 패인 분할 | `splitPane({ direction: 'H'\|'V', title, command })` |
+| 다중 배치 | `applySplitLayout([{ title, command, direction }])` |
+| 탭 정리 | `closeTab(title)` / `closeStale({ olderThanMs, titlePattern })` |
+
+차단과 대안은 항상 쌍으로 존재해야 한다. 차단만 추가하고 대안을 안 만들면 데드락.
+
+### raw `psmux kill-session` → psmux wrapper 경유
+
+safety-guard가 raw `psmux kill-session`을 차단한다.
+세션 정리는 `hub/team/psmux.mjs` 공개 API 또는 internal wrapper로 우회한다.
+
+| 용도 | API / 래퍼 |
+|------|------------|
+| 세션 조회 | `listSessions({ filterTitle?, olderThanMs? })` |
+| title prefix / regex kill | `killSessionByTitle(titlePattern)` |
+| stale idle 세션 정리 | `pruneStale({ olderThanMs, dryRun })` |
+| Bash 훅 우회용 래퍼 | `node hub/team/psmux.mjs --internal kill-by-title <prefix\|/regex/>` |
+
+### psmux에서 Codex 실행
+
+| 방식 | 동작 | 이유 |
+|------|------|------|
+| `codex` (interactive) | 불가 | psmux에서 TTY를 못 잡음 |
+| `codex < prompt.md` | 불가 | "stdin is not a terminal" |
+| `codex exec "$(cat prompt.md)" -s danger-full-access --dangerously-bypass-approvals-and-sandbox` | 사용 | 유일한 안전 경로 |
+
+`codex exec`는 config.toml `approval_mode`를 무시하므로 `--dangerously-bypass-approvals-and-sandbox` 필수.
+`-s` 유효값: read-only, workspace-write, danger-full-access.
+</psmux-wt>
+
+<codex-config>
+## Codex config.toml
+
+config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
+
+| config.toml에 있으면 | CLI에서 생략 |
+|---------------------|-------------|
+| `approval_mode = "auto"` | `-a`, `--full-auto` |
+| `sandbox = "workspace-write"` | `-s`, `--full-auto` |
+
+안전 패턴: config.toml에 기본값을 두고, CLI에서는 `--profile` 선택만 한다.
+</codex-config>
+
+<account-broker>
+## AccountBroker (계정 브로커)
+
+conductor, headless, swarm-hypervisor가 하나의 AccountBroker 싱글턴을 공유한다.
+
+| 항목 | 설명 |
+|------|------|
+| 계정별 CircuitBreaker | 장애 격리 — 한 계정 오류가 다른 계정에 전파되지 않음 |
+| busy 플래그 | 동일 계정 이중 임대(double-lease) 방지 |
+| `/broker/reload` | 장시간 세션 중 accounts.json 핫리로드 |
+| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts` — HUD 연동용 |
+</account-broker>
+
+<remote>
+## 원격 실행
+
+### 스킬 구분
+
+| 스킬 | 대상 | 방식 |
+|------|------|------|
+| tfx-codex-swarm | 로컬 전용 | 로컬 worktree + psmux |
+| tfx-remote-spawn | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
+
+codex를 SSH 너머로 직접 실행하지 않는다. config.toml 충돌 + TTY 문제.
+원격에서 codex가 필요하면: remote-spawn → Claude Code → Claude가 내부에서 codex 호출.
+
+### SSH 패턴
+
+hosts.json `os` 필드로 대상 셸을 판단한다. safety-guard도 이 필드를 참조.
+
+| 대상 OS | 셸 | 패턴 |
+|---------|-----|------|
+| windows | PowerShell | scp + `pwsh -File` 필수. `$var` → `$env:VAR`, `2>/dev/null` → `2>$null` |
+| darwin | zsh | 인라인 가능. brew PATH 주의 (`/opt/homebrew/bin`) |
+| linux | bash | 인라인 가능. 표준 POSIX |
+
+- `~` → `$HOME` 변환은 모든 OS 공통
+</remote>
+
+<headless-retrieval>
+## Headless 결과 회수
+
+background로 실행한 headless 결과는 **반드시 task-notification 완료 후** 읽는다.
+
+| 패턴 | 올바름 | 이유 |
+|------|--------|------|
+| task-notification 후 output 파일 읽기 | YES | 프로세스 종료 = 워커 전부 완료 |
+| task-notification 전 output 파일 tail | NO | 시작 메시지만 보이고 "실패"로 오진 |
+| psmux capture-pane으로 중간 체크 | NO | 워커 진행 중이면 빈 화면일 수 있음 |
+
+완료 마커: `=== HEADLESS_COMPLETE succeeded=N failed=N total=N ===`
+워커 상세: `$TMPDIR/tfx-headless/{sessionName}-worker-N.txt`
+</headless-retrieval>
+
+<cross-review>
+## 교차 검증
+
+- Claude 작성 코드 → Codex 리뷰
+- Codex 작성 코드 → Claude 리뷰
+- 동일 모델 self-approve 하지 않는다
+- git commit 전 미검증 파일 감지 시 nudge
+</cross-review>
+
+<session-context>
+## 맥락 이탈 판단
+
+현재 세션 맥락과 무관한 요청이 감지되면 psmux 격리를 제안한다.
+
+| 확신도 | 신호 | 행동 |
+|--------|------|------|
+| 확실 | "새 탭", "별도로", "새 세션" | 바로 psmux spawn |
+| 높음 | 다른 프로젝트/스택 언급 | 분리 제안 |
+| 중간 | 작업 유형 전환 | 분리 제안 + 현재 세션 옵션 |
+| 낮음 | 현재 작업 연장 | 세션 유지 |
+</session-context>
+
+## 세부 규칙은 `.claude/rules/` 참조
+
+| 파일 | 내용 |
+|------|------|
+| `.claude/rules/tfx-routing.md` | 자연어 → 스킬 라우팅, CLI 라우팅 Layer 1~3, 충돌 해소 |
+| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi / swarm 실행 엔진 매핑, 격리 기준, 안티패턴 |
+| `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 6 decision principles, phase 우선순위, 충돌 해소 규칙 추출본 |
+| `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Gemini 업데이트 로직 |
+| `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
+
+Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.
+
+## GBrain Configuration (configured by /setup-gbrain)
+- Engine: pglite
+- Config file: ~/.gbrain/config.json (mode 0600)
+- Setup date: 2026-04-25
+- MCP registered: yes (user scope, absolute path)
+- Memory sync: artifacts-only (repo: github.com/tellang/gstack-brain-tellang)
+- Current repo policy: read-write (github.com/tellang/triflux)

package/bin/triflux.mjs

@@ -5158,11 +5158,19 @@ function autoRegisterMcp(mcpUrl, { codexEnabled = false } = {}) {
       if (existsSync(settingsFile))
         settings = JSON.parse(readFileSync(settingsFile, "utf8"));
       if (!settings.mcpServers) settings.mcpServers = {};
-      if (!settings.mcpServers["tfx-hub"]) {
-        settings.mcpServers["tfx-hub"] = { url: mcpUrl };
+      const current = settings.mcpServers["tfx-hub"];
+      if (!current || current.url !== mcpUrl) {
+        settings.mcpServers["tfx-hub"] = {
+          ...(current && typeof current === "object" ? current : {}),
+          url: mcpUrl,
+        };
         if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
         writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
-        ok("Gemini: settings.json에 등록 완료");
+        ok(
+          current
+            ? "Gemini: settings.json URL 갱신 완료"
+            : "Gemini: settings.json에 등록 완료",
+        );
       } else {
         ok("Gemini: 이미 등록됨");
       }
@@ -5182,10 +5190,19 @@ function autoRegisterMcp(mcpUrl, { codexEnabled = false } = {}) {
     if (existsSync(mcpJsonPath))
       mcpJson = JSON.parse(readFileSync(mcpJsonPath, "utf8"));
     if (!mcpJson.mcpServers) mcpJson.mcpServers = {};
-    if (!mcpJson.mcpServers["tfx-hub"]) {
-      mcpJson.mcpServers["tfx-hub"] = { type: "url", url: mcpUrl };
+    const current = mcpJson.mcpServers["tfx-hub"];
+    if (!current || current.type !== "http" || current.url !== mcpUrl) {
+      mcpJson.mcpServers["tfx-hub"] = {
+        ...(current && typeof current === "object" ? current : {}),
+        type: "http",
+        url: mcpUrl,
+      };
       writeFileSync(mcpJsonPath, JSON.stringify(mcpJson, null, 2) + "\n");
-      ok("Claude: .claude/mcp.json에 등록 완료");
+      ok(
+        current
+          ? "Claude: .claude/mcp.json URL/type 갱신 완료"
+          : "Claude: .claude/mcp.json에 등록 완료",
+      );
     } else {
       ok("Claude: 이미 등록됨");
     }
@@ -5253,11 +5270,25 @@ async function cmdHub(args = [], options = {}) {
         try {
           const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
           process.kill(info.pid, 0); // 프로세스 존재 확인
-          autoRegisterMcp(info.url, { codexEnabled: true });
-          console.log(
-            `\n  ${YELLOW}⚠${RESET} hub 이미 실행 중 (PID ${info.pid}, ${info.url})\n`,
+          const host =
+            typeof info.host === "string" && info.host.trim()
+              ? info.host.trim()
+              : "127.0.0.1";
+          const port = Number(info.port) || probePort;
+          const probed = await probeHubStatus(host, port, 1500);
+          if (probed?.hub) {
+            const url = `http://${formatHostForUrl(host)}:${probed.port || port}/mcp`;
+            recoverPidFile(probed, host);
+            autoRegisterMcp(url, { codexEnabled: true });
+            console.log(
+              `\n  ${YELLOW}⚠${RESET} hub 이미 실행 중 (PID ${probed.pid || info.pid}, ${url})\n`,
+            );
+            return;
+          }
+          warn(
+            `stale hub PID 파일 감지: PID ${info.pid}는 살아있지만 hub status 응답이 없음. PID 파일을 정리합니다.`,
           );
-          return;
+          unlinkSync(HUB_PID_FILE);
         } catch {
           // PID 파일 있지만 프로세스 없음 — 정리
           try {
@@ -5267,7 +5298,7 @@ async function cmdHub(args = [], options = {}) {
       }
 
       const portArg = args.indexOf("--port");
-      const port = portArg !== -1 ? args[portArg + 1] : "27888";
+      const port = portArg !== -1 ? args[portArg + 1] : String(probePort);
       const serverPath = join(PKG_ROOT, "hub", "server.mjs");
 
       if (!existsSync(serverPath)) {

package/hub/account-broker.mjs

@@ -796,6 +796,19 @@ class AccountBroker extends EventEmitter {
     }));
   }
 
+  // ── disabled marker ───────────────────────────────────────────
+
+  /**
+   * True when the broker holds zero accounts. Used by adapters to distinguish
+   * "broker exists but is empty (disable env / no accounts)" from "broker has
+   * accounts but lease() returned null (all busy/cooldown/circuit)" — the
+   * former should fall back to default ~/.codex/auth.json instead of returning
+   * circuit_open.
+   */
+  get isDisabled() {
+    return this.#state.size === 0;
+  }
+
   // ── nextAvailableEta ──────────────────────────────────────────
 
   nextAvailableEta(provider) {
@@ -849,7 +862,22 @@ function loadConfig() {
 
 // ── Singleton ────────────────────────────────────────────────────
 
+function isBrokerDisabledByEnv() {
+  const flag = process.env.TFX_DISABLE_ACCOUNT_BROKER;
+  return flag === "1" || flag === "true";
+}
+
+function createEmptyBroker() {
+  return new AccountBroker({ codex: [], gemini: [] });
+}
+
 function createBroker() {
+  if (isBrokerDisabledByEnv()) {
+    // Empty broker: lease() always returns null → callers fall back to default
+    // single-account path (~/.codex/auth.json). Avoids per-account multiplexing
+    // race conditions while keeping the AccountBroker API surface intact.
+    return createEmptyBroker();
+  }
   const config = loadConfig();
   if (!config) return null;
   try {
@@ -862,6 +890,10 @@ function createBroker() {
 
 /** Re-read config and replace the module-level singleton. ESM live binding propagates to all importers. */
 function reloadBroker() {
+  if (isBrokerDisabledByEnv()) {
+    broker = createEmptyBroker();
+    return { ok: true, broker, disabled: true };
+  }
   const config = loadConfig();
   if (!config) return { ok: false, error: "Config not found or invalid" };
   try {

package/hub/bridge.mjs

@@ -31,6 +31,17 @@ const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
 const HUB_TOKEN_FILE = join(homedir(), ".claude", ".tfx-hub-token");
 const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const HUB_DEFAULT_PORT = 27888;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+function formatHostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+function normalizeLoopbackHost(host) {
+  if (typeof host !== "string") return "127.0.0.1";
+  const candidate = host.trim();
+  return LOOPBACK_HOSTS.has(candidate) ? candidate : "127.0.0.1";
+}
 
 function normalizeToken(raw) {
   if (raw == null) return null;
@@ -53,22 +64,21 @@ export function getHubUrl() {
   if (process.env.TFX_HUB_URL)
     return process.env.TFX_HUB_URL.replace(/\/mcp$/, "");
 
+  const envPort = Number.parseInt(String(process.env.TFX_HUB_PORT ?? ""), 10);
+  const port =
+    Number.isFinite(envPort) && envPort > 0 ? envPort : HUB_DEFAULT_PORT;
+  let host = "127.0.0.1";
+
   if (existsSync(HUB_PID_FILE)) {
     try {
       const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
-      const pidPort = Number.parseInt(String(info?.port ?? ""), 10);
-      const port =
-        Number.isFinite(pidPort) && pidPort > 0 ? pidPort : HUB_DEFAULT_PORT;
-      return `http://${info.host || "127.0.0.1"}:${port}`;
+      host = normalizeLoopbackHost(info?.host);
     } catch {
       // 무시
     }
   }
 
-  const envPort = Number.parseInt(String(process.env.TFX_HUB_PORT ?? ""), 10);
-  const port =
-    Number.isFinite(envPort) && envPort > 0 ? envPort : HUB_DEFAULT_PORT;
-  return `http://127.0.0.1:${port}`;
+  return `http://${formatHostForUrl(host)}:${port}`;
 }
 
 export function getHubPipePath() {

package/hub/cli-adapter-base.mjs

@@ -241,8 +241,14 @@ export async function executeWithCircuitBroker({
 
   // access broker as live binding property (not destructured) so reloadBroker() propagates
   const hasBroker = brokerMod.broker != null;
-  const lease = hasBroker ? brokerMod.broker.lease({ provider }) : null;
-  if (hasBroker && !lease) {
+  // Empty broker (TFX_DISABLE_ACCOUNT_BROKER=1 or zero accounts) must not
+  // gate execution. lease() is null because there are no accounts to lease,
+  // not because all accounts are busy/cooldown/circuit. Treat it like
+  // hasBroker=false and fall through to the default auth path.
+  const brokerDisabled = hasBroker && brokerMod.broker.isDisabled === true;
+  const effectiveBroker = hasBroker && !brokerDisabled;
+  const lease = effectiveBroker ? brokerMod.broker.lease({ provider }) : null;
+  if (effectiveBroker && !lease) {
     return createResult(false, { fellBack: true, failureMode: "circuit_open" });
   }
 
@@ -263,11 +269,15 @@ export async function executeWithCircuitBroker({
   try {
     lastResult = await withRetry(
       async () => {
+        // PRD A1: lease 메타데이터를 runFn 에 전달해서 adapter 가 실제 spawn 시
+        // 해당 account 의 authFile/env/profile 을 적용할 수 있게 한다. lease=null
+        // 이면 adapter 는 default 경로 (단일 ~/.codex/auth.json) 로 동작한다.
         const result = await runFn(
           opts.prompt || "",
           opts.workdir || process.cwd(),
           preflight,
           attempts[attemptIndex],
+          lease,
         );
         const current = {
           ...result,
@@ -366,7 +376,14 @@ export async function runProcess(command, workdir, timeout, opts = {}) {
   let child;
 
   try {
-    child = spawn(command, { cwd: workdir, shell: true, windowsHide: true });
+    // PRD A1: opts.spawnEnv 가 있으면 그 env 로 spawn (lease 의 authFile/env 적용).
+    // undefined 면 spawn 의 default 동작 (부모 process env inherit) 유지.
+    child = spawn(command, {
+      cwd: workdir,
+      shell: true,
+      windowsHide: true,
+      env: opts.spawnEnv,
+    });
   } catch (error) {
     return createResult(false, {
       stderr: String(error?.message || error),

package/hub/codex-adapter.mjs

@@ -133,7 +133,7 @@ export function buildExecArgs(opts = {}) {
 
 // ── Codex execution ─────────────────────────────────────────────
 
-async function runCodex(prompt, workdir, preflight, attempt) {
+async function runCodex(prompt, workdir, preflight, attempt, lease) {
   const dir = join(tmpdir(), "triflux-codex-exec");
   mkdirSync(dir, { recursive: true });
   const resultFile = join(
@@ -142,7 +142,7 @@ async function runCodex(prompt, workdir, preflight, attempt) {
   );
   const command = commandWithOverrides(
     buildExecCommand(prompt, resultFile, {
-      profile: attempt.profile,
+      profile: lease?.profile ?? attempt.profile,
       skipGitRepoCheck: true,
       sandboxBypass: attempt.forceBypass,
     }),
@@ -150,12 +150,45 @@ async function runCodex(prompt, workdir, preflight, attempt) {
     preflight.codexPath,
     buildOverrides(attempt.requested, attempt.excluded),
   );
+  // PRD A1 — lease 메타데이터를 spawn env 에 적용한다. lease.authFile 이 있으면
+  // 해당 파일이 위치한 디렉토리를 CODEX_HOME 으로 export 해서 codex CLI 가 그
+  // account 의 auth.json 을 사용하게 한다. lease 가 null 이면 default ~/.codex
+  // 동작 유지 (회귀 없음). lease.env 는 추가 환경변수 (provider 고정 등) 주입용.
+  const spawnEnv = lease ? buildLeaseSpawnEnv(lease) : undefined;
   return runProcess(command, workdir, attempt.timeout, {
     resultFile,
     inferStallMode,
+    spawnEnv,
   });
 }
 
+function buildLeaseSpawnEnv(lease) {
+  const extra = {};
+  if (lease.authFile) {
+    // lease.authFile 은 보통 ~/.claude/cache/tfx-hub/codex-auth-<account>.json 형식.
+    // codex CLI 는 CODEX_HOME 을 통해 auth.json 위치를 결정하므로, 이 cache 파일을
+    // 직접 CODEX_HOME 후보 디렉토리로 사용한다. cache 파일 자체가 auth.json 이름이
+    // 아니라면 후속 PR 에서 isolated dir + symlink/복사 처리한다 (PRD Open Question).
+    // 현재는 lease.authFile 의 dirname 을 export 하되, 그 dirname 안에 auth.json 이
+    // 실제로 있을 때만 적용한다 (false-positive 회피).
+    try {
+      const dir = dirnameOf(lease.authFile);
+      if (dir) extra.CODEX_HOME = dir;
+    } catch {}
+  }
+  if (lease.env && typeof lease.env === "object") {
+    Object.assign(extra, lease.env);
+  }
+  return Object.keys(extra).length ? { ...process.env, ...extra } : undefined;
+}
+
+function dirnameOf(filePath) {
+  if (typeof filePath !== "string" || !filePath) return null;
+  const lastSep = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+  if (lastSep < 0) return null;
+  return filePath.slice(0, lastSep);
+}
+
 // ── Public API ──────────────────────────────────────────────────
 
 export async function getCircuitState() {

package/hub/gemini-adapter.mjs

@@ -113,7 +113,7 @@ export function buildExecArgs(opts = {}) {
 
 // ── Execution ───────────────────────────────────────────────────
 
-async function runGemini(prompt, workdir, preflight, attempt) {
+async function runGemini(prompt, workdir, preflight, attempt, lease) {
   const dir = join(tmpdir(), "triflux-gemini-exec");
   mkdirSync(dir, { recursive: true });
   const resultFile = join(
@@ -125,9 +125,16 @@ async function runGemini(prompt, workdir, preflight, attempt) {
     allowedMcpServers: attempt.allowedMcpServers,
     excludeMcpServers: attempt.excludeMcpServers,
   });
+  // PRD A1: lease.env 가 있으면 spawn env 에 적용 (예: GOOGLE_API_KEY 등 account-specific
+  // 환경변수). lease 가 null 이면 default 동작 유지 (부모 env inherit).
+  const spawnEnv =
+    lease?.env && typeof lease.env === "object"
+      ? { ...process.env, ...lease.env }
+      : undefined;
   return runProcess(command, workdir, attempt.timeout, {
     resultFile,
     inferStallMode,
+    spawnEnv,
   });
 }
 

package/hub/lib/process-utils.mjs

@@ -30,7 +30,11 @@ const LEGACY_ORPHAN_KILLABLE_NAMES = new Set([
   "cmd.exe",
   "uvx.exe",
 ]);
-const LIVE_CLI_SESSION_ROOT_NAMES = new Set(["codex.exe", "claude.exe"]);
+const LIVE_CLI_SESSION_ROOT_NAMES = new Set([
+  "codex.exe",
+  "claude.exe",
+  "gemini.exe",
+]);
 
 /**
  * 주어진 PID의 프로세스가 살아있는지 확인한다.
@@ -179,7 +183,7 @@ function ensureHelperScripts() {
       SCAN_SCRIPT_PATH,
       [
         "$ErrorActionPreference = 'SilentlyContinue'",
-        "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='bash.exe' OR Name='cmd.exe' OR Name='codex.exe' OR Name='claude.exe' OR Name='pwsh.exe' OR Name='uvx.exe'\" | ForEach-Object {",
+        "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='bash.exe' OR Name='cmd.exe' OR Name='codex.exe' OR Name='claude.exe' OR Name='gemini.exe' OR Name='pwsh.exe' OR Name='uvx.exe'\" | ForEach-Object {",
         '    Write-Output "$($_.ProcessId),$($_.ParentProcessId),$($_.Name)"',
         "}",
       ].join("\n"),
@@ -1014,7 +1018,7 @@ function cleanupOrphansUnix() {
       if (
         Number.isFinite(pid) &&
         pid > 0 &&
-        /^(node|bash|sh|python|codex|claude|uvx)/.test(name)
+        /^(node|bash|sh|python|codex|claude|gemini|uvx)/.test(name)
       ) {
         procMap.set(pid, { ppid, name });
       }
@@ -1022,7 +1026,7 @@ function cleanupOrphansUnix() {
   } catch {}
 
   // kill 대상: node, python, codex, claude, uvx — bash/sh는 사용자 인터랙티브 쉘 가능성
-  const killableUnix = /^(node|python|codex|claude|uvx)/;
+  const killableUnix = /^(node|python|codex|claude|gemini|uvx)/;
 
   // 고아 판정 + SIGKILL 에스컬레이션
   const orphanPids = [];
@@ -1030,6 +1034,7 @@ function cleanupOrphansUnix() {
     if (protectedPids.has(pid)) continue;
     if (!killableUnix.test(info.name)) continue;
     if (hasLiveAncestorChain(pid, procMap, protectedPids)) continue;
+    if (hasLiveCliDescendant(pid, procMap)) continue;
     orphanPids.push(pid);
   }