triflux 10.9.31 → 10.10.0

package/CLAUDE.md

@@ -0,0 +1,159 @@
+# 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-update-logic.md` | triflux / OMC / gstack / Codex / Gemini 업데이트 로직 |
+
+Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.

package/hooks/keyword-rules.json

@@ -664,6 +664,45 @@
       "exclusive": false,
       "state": null,
       "mcp_route": null
+    },
+    {
+      "id": "tfx-ship",
+      "patterns": [
+        {
+          "source": "\\btfx[\\s-]?ship\\b",
+          "flags": "i"
+        },
+        {
+          "source": "/ship\\b",
+          "flags": "i"
+        },
+        {
+          "source": "\\brelease\\b",
+          "flags": "i"
+        },
+        {
+          "source": "\\bpublish\\b",
+          "flags": "i"
+        },
+        {
+          "source": "배포(?!자|사|장|처)",
+          "flags": ""
+        },
+        {
+          "source": "릴리[즈스]",
+          "flags": ""
+        },
+        {
+          "source": "쉽\\s*(?:해|하자|가자|쳐)",
+          "flags": ""
+        }
+      ],
+      "skill": "tfx-ship",
+      "priority": 3,
+      "supersedes": ["gstack-ship"],
+      "exclusive": false,
+      "state": null,
+      "mcp_route": null
     }
   ]
 }

package/hooks/safety-guard.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 // hooks/safety-guard.mjs — PreToolUse:Bash 훅
 //
 // 위험한 Bash 명령을 사전 차단(exit 2)하거나 경고(additionalContext)한다.
@@ -8,6 +9,7 @@
 //   BLOCK (exit 2)  — 복구 불가능한 파괴적 명령
 //   WARN  (allow + context) — 주의가 필요한 명령
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -251,6 +253,60 @@ function hasSegmentInvocation(cmd, patterns) {
   });
 }
 
+function isGitCommitInvocation(command) {
+  const lines = command.split(/\n/);
+  let heredocDelimiter = null;
+  return lines.some((line) => {
+    if (heredocDelimiter !== null) {
+      if (line.trim() === heredocDelimiter) heredocDelimiter = null;
+      return false;
+    }
+
+    const heredocMatch = line.match(/<<['"]?(\w+)['"]?/);
+    if (heredocMatch) {
+      heredocDelimiter = heredocMatch[1];
+    }
+
+    return line
+      .split(/\s*(?:&&|;|\|\|)\s*/)
+      .some((segment) => /^\s*git\s+commit\b/i.test(segment.trim()));
+  });
+}
+
+function resolveHookCwd(input) {
+  return String(
+    input?.cwd ||
+      input?.tool_input?.cwd ||
+      process.env.CLAUDE_CWD ||
+      process.cwd() ||
+      process.env.PWD,
+  );
+}
+
+function getCurrentGitBranch(cwd) {
+  try {
+    const result = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0) return "";
+    return String(result.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function isProtectedMainBranch(branch) {
+  return /^(main|master)$/i.test(String(branch || "").trim());
+}
+
+function isSwarmWorktreeCwd(cwd) {
+  return /(?:^|\/)\.codex-swarm\/wt-[^/]+(?:\/|$)/.test(
+    String(cwd || "").replace(/\\/g, "/"),
+  );
+}
+
 function blockCommand(message, command) {
   process.stderr.write(
     `${message}\n` +
@@ -275,6 +331,7 @@ function main() {
 
   const command = (input.tool_input?.command || "").trim();
   if (!command) process.exit(0);
+  const hookCwd = resolveHookCwd(input);
 
   // psmux 명령이 실제 CLI 호출인지 판별 (오탐 방지)
   // git commit 메시지, echo, grep, cat, heredoc 안의 텍스트는 무시
@@ -298,6 +355,20 @@ function main() {
     process.exit(0);
   }
 
+  const codexPrdActive = process.env.CODEX_PRD_ACTIVE === "1";
+  if (codexPrdActive && isGitCommitInvocation(command)) {
+    const branch = getCurrentGitBranch(hookCwd);
+    if (isProtectedMainBranch(branch)) {
+      const locationHint = isSwarmWorktreeCwd(hookCwd)
+        ? "swarm worktree 내부에서도 main/master 직접 commit은 금지됩니다."
+        : "현재 PWD가 swarm worktree가 아닙니다.";
+      blockCommand(
+        `[safety-guard] Codex PRD 실행 중 ${branch} 직접 commit 차단됨. ${locationHint}`,
+        command,
+      );
+    }
+  }
+
   // 0.1. reflexion 적응형 패널티 — 이전 세션에서 차단된 패턴 사전 경고
   const penalties = loadReflexionPenalties();
   if (penalties.length > 0) {

package/hub/cli-adapter-base.mjs

@@ -147,7 +147,6 @@ export function buildExecCommand(prompt, resultFile = null, opts = {}) {
     profile,
     skipGitRepoCheck = true,
     sandboxBypass = true,
-    cwd,
     mcpServers,
   } = opts;
 

package/hub/lib/process-utils.mjs

@@ -102,7 +102,11 @@ function killWithEscalation(orphanPids, procMap) {
           }
         }
       }
-      killProcess(pid, { signal: "SIGKILL", force: true });
+      killProcess(pid, {
+        signal: "SIGKILL",
+        force: true,
+        tree: IS_WINDOWS,
+      });
     }
     if (!isPidAlive(pid)) killed++;
   }

package/hub/middleware/quota-middleware.mjs

@@ -0,0 +1,70 @@
+const FAILURE_STATUSES = new Set(["quota_hit", "error"]);
+
+function buildFailureRecord(result = {}) {
+  const failure = {
+    id: result.id ?? "unknown",
+    status: result.status ?? "unknown",
+  };
+
+  if (Number.isFinite(result.http)) {
+    failure.http = result.http;
+  }
+
+  if (typeof result.message === "string" && result.message.length > 0) {
+    failure.message = result.message;
+  }
+
+  if (result.headers && Object.keys(result.headers).length > 0) {
+    failure.headers = result.headers;
+  }
+
+  return failure;
+}
+
+export function summarizeQuotaResults(results = []) {
+  const metrics = {
+    checked: results.length,
+    ok: 0,
+    quotaHit: 0,
+    error: 0,
+    failed: 0,
+  };
+  const failures = [];
+
+  for (const result of results) {
+    const status = result?.status ?? "unknown";
+
+    if (status === "ok") {
+      metrics.ok += 1;
+    } else if (status === "quota_hit") {
+      metrics.quotaHit += 1;
+    } else if (status === "error") {
+      metrics.error += 1;
+    }
+
+    if (FAILURE_STATUSES.has(status)) {
+      failures.push(buildFailureRecord(result));
+    }
+  }
+
+  metrics.failed = failures.length;
+  return { metrics, failures };
+}
+
+export function logQuotaRefreshFailures(logger, results = []) {
+  const { metrics, failures } = summarizeQuotaResults(results);
+  if (failures.length === 0) {
+    return { logged: false, metrics, failures };
+  }
+
+  logger.warn(
+    {
+      tag: "hub-quota",
+      metrics,
+      failures,
+    },
+    "broker.quota_refresh_degraded",
+  );
+
+  return { logged: true, metrics, failures };
+}

package/hub/server.mjs

@@ -29,6 +29,7 @@ import { DelegatorService } from "./delegator/index.mjs";
 import { createHitlManager } from "./hitl.mjs";
 import { cleanupOrphanNodeProcesses } from "./lib/process-utils.mjs";
 import * as spawnTrace from "./lib/spawn-trace.mjs";
+import { logQuotaRefreshFailures } from "./middleware/quota-middleware.mjs";
 import { wrapRequestHandler } from "./middleware/request-logger.mjs";
 import { createPipeServer } from "./pipe.mjs";
 import { createRouter } from "./router.mjs";
@@ -299,6 +300,9 @@ async function syncHubMcpSettingsIfAvailable({ hubUrl }) {
       return;
     }
     await mod.syncHubMcpSettings({ hubUrl });
+    if (typeof mod?.syncCodexHubUrl === "function") {
+      await mod.syncCodexHubUrl({ hubUrl });
+    }
   } catch (error) {
     const message = error?.message || String(error);
     if (error?.code === "ERR_MODULE_NOT_FOUND") {
@@ -988,6 +992,7 @@ export async function startHub({
       ) {
         try {
           const results = await refreshAllAccountQuotas();
+          logQuotaRefreshFailures(hubLog, results);
           return writeJson(res, 200, { ok: true, results, ts: Date.now() });
         } catch (err) {
           hubLog.error(

package/hub/team/conductor.mjs

@@ -28,6 +28,7 @@ import {
   getConductorRegistry,
 } from "./conductor-registry.mjs";
 import { createEventLog } from "./event-log.mjs";
+import { buildSpawnSpecForMode, MODES } from "./execution-mode.mjs";
 import { createHealthProbe } from "./health-probe.mjs";
 import { buildLauncher } from "./launcher-template.mjs";
 import {
@@ -490,6 +491,14 @@ export function createConductor(opts = {}) {
     let recentOutput = "";
 
     const spawnCwd = session.config.workdir || launcher.cwd || undefined;
+    const spawnSpec = buildSpawnSpecForMode(MODES.HEADLESS, {
+      cli: session.config.agent,
+      prompt: session.config.prompt,
+      profile: session.config.profile,
+      model: session.config.model,
+      mcpServers: session.config.mcpServers,
+      resolveCommand: opts.deps?.resolveCliExecutable,
+    });
 
     // #90 branch guard: shard spawn cwd가 main 브랜치면 즉시 abort.
     // swarm shard는 반드시 shard 전용 worktree 브랜치에서 실행되어야 한다.
@@ -524,8 +533,8 @@ export function createConductor(opts = {}) {
 
     let child;
     try {
-      child = spawnFn(launcher.command, {
-        shell: true,
+      child = spawnFn(spawnSpec.command, spawnSpec.args, {
+        shell: false,
         cwd: spawnCwd,
         env: {
           ...process.env,
@@ -544,6 +553,7 @@ export function createConductor(opts = {}) {
         session: session.id,
         error: err.message,
         cwd: spawnCwd || null,
+        command: spawnSpec.command,
       });
       handleFailure(session, `spawn_error:${err.message}`);
       return;
@@ -561,7 +571,9 @@ export function createConductor(opts = {}) {
       session: session.id,
       agent: session.config.agent,
       pid: child.pid,
-      command: launcher.command,
+      command: spawnSpec.command,
+      args: spawnSpec.args,
+      legacyCommand: launcher.command,
       restart: session.restarts,
     });
 

package/hub/team/execution-mode.mjs

@@ -1,5 +1,11 @@
 // hub/team/execution-mode.mjs — headless vs interactive execution mode selection
 
+import { existsSync } from "node:fs";
+
+import { whichCommand } from "../platform.mjs";
+
+const WIN32_EXT_PRECEDENCE = [".cmd", ".exe", ".bat", ".ps1"];
+
 export const MODES = Object.freeze({
   HEADLESS: "headless",
   INTERACTIVE: "interactive",
@@ -10,6 +16,98 @@ function quotePrompt(prompt) {
   return JSON.stringify(typeof prompt === "string" ? prompt : "");
 }
 
+function asPrompt(prompt) {
+  return typeof prompt === "string" ? prompt : "";
+}
+
+function pushFlag(args, flag, value) {
+  if (typeof value === "string" && value.length > 0) {
+    args.push(flag, value);
+  }
+}
+
+export function resolveCliExecutable(cli, opts = {}) {
+  const name = String(cli || "codex");
+  const resolveCommand = opts.resolveCommand || whichCommand;
+  const resolved = resolveCommand(name) || name;
+
+  // Windows: Node spawn({ shell: false }) calls CreateProcess directly and does NOT
+  // search PATHEXT. npm-installed CLIs (codex, gemini) live at `<npm>/codex` (Git Bash
+  // shell script) alongside `<npm>/codex.cmd` (Windows batch wrapper). whichCommand
+  // returns the extensionless path, which Windows cannot execute → ENOENT "The system
+  // cannot find the file specified." Append the correct extension when the resolved
+  // path has none.
+  const platform = opts.platform || process.platform;
+  if (platform === "win32" && resolved) {
+    const hasExt = /\.[^\\/.]+$/.test(resolved);
+    if (!hasExt) {
+      const existsFn = opts.existsSyncFn || existsSync;
+      for (const ext of WIN32_EXT_PRECEDENCE) {
+        const candidate = `${resolved}${ext}`;
+        try {
+          if (existsFn(candidate)) return candidate;
+        } catch {
+          // ignore stat failures, try next extension
+        }
+      }
+    }
+  }
+
+  return resolved;
+}
+
+export function buildSpawnSpecForMode(mode, opts = {}) {
+  const cli = opts.cli || "codex";
+  const prompt = asPrompt(opts.prompt);
+  const resolvedCommand = resolveCliExecutable(cli, opts);
+  const platform = opts.platform || process.platform;
+
+  // Node v20.12+ (CVE-2024-27980) rejects spawn of .cmd/.bat files with shell:false
+  // (EINVAL). npm-installed Windows wrappers (e.g. codex.cmd) hit this. Wrap via
+  // cmd.exe /c to keep shell:false while still launching the batch wrapper.
+  const needsCmdWrap =
+    platform === "win32" && /\.(cmd|bat)$/i.test(resolvedCommand);
+  const wrap = (args) =>
+    needsCmdWrap
+      ? { command: "cmd", args: ["/c", resolvedCommand, ...args] }
+      : { command: resolvedCommand, args };
+
+  if (cli === "gemini") {
+    const args = [];
+    pushFlag(args, "--model", opts.model);
+    args.push("--yolo", "--prompt", prompt, "--output-format", "text");
+    return { ...wrap(args), useExec: true, shell: false };
+  }
+
+  if (mode === MODES.INTERACTIVE || mode === MODES.AUTO) {
+    return { ...wrap([]), useExec: false, shell: false };
+  }
+
+  if (cli === "claude") {
+    const args = [];
+    pushFlag(args, "--model", opts.model);
+    args.push("-p", prompt);
+    return { ...wrap(args), useExec: true, shell: false };
+  }
+
+  const args = [];
+  pushFlag(args, "--profile", opts.profile);
+  args.push(
+    "exec",
+    "--dangerously-bypass-approvals-and-sandbox",
+    "--skip-git-repo-check",
+    "--color",
+    "never",
+  );
+  if (Array.isArray(opts.mcpServers)) {
+    for (const server of opts.mcpServers) {
+      args.push("-c", `mcp_servers.${server}.enabled=true`);
+    }
+  }
+  args.push(prompt);
+  return { ...wrap(args), useExec: true, shell: false };
+}
+
 /**
  * @param {{
  *   cli: "codex"|"gemini"|"claude",

package/hub/team/process-cleanup.mjs

@@ -12,10 +12,17 @@ const execFileAsync = promisify(nodeExecFile);
 const TARGET_PROCESS_NAMES = ["node", "python", "python3"];
 const SIGTERM_GRACE_MS = 5000;
 
-function forceKillPid(pid) {
-  if (IS_WINDOWS) {
+export function forceKillPid(
+  pid,
+  {
+    isWindows = IS_WINDOWS,
+    execFileSyncFn = execFileSync,
+    killFn = process.kill,
+  } = {},
+) {
+  if (isWindows) {
     try {
-      execFileSync("taskkill", ["/F", "/PID", String(pid)], {
+      execFileSyncFn("taskkill", ["/F", "/T", "/PID", String(pid)], {
         stdio: "ignore",
         timeout: 5000,
         windowsHide: true,
@@ -23,7 +30,7 @@ function forceKillPid(pid) {
       return;
     } catch (taskkillError) {
       try {
-        process.kill(pid);
+        killFn(pid);
         return;
       } catch {
         throw taskkillError;
@@ -31,7 +38,7 @@ function forceKillPid(pid) {
     }
   }
 
-  process.kill(pid, "SIGKILL");
+  killFn(pid, "SIGKILL");
 }
 
 // cmdLine 패턴 기반 화이트리스트 (고아 후보에서 제외)
@@ -296,6 +303,12 @@ export async function findOrphanProcesses(opts = {}) {
 export function createProcessCleanup(opts = {}) {
   const execFileFn = opts.execFileFn ?? execFileAsync;
   const dryRun = opts.dryRun ?? false;
+  const isWindows = opts.isWindows ?? IS_WINDOWS;
+  const execFileSyncFn = opts.execFileSyncFn ?? execFileSync;
+  const killFn = opts.killFn ?? process.kill;
+  const sleepFn =
+    opts.sleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sigtermGraceMs = opts.sigtermGraceMs ?? SIGTERM_GRACE_MS;
 
   let lastOrphans = [];
 
@@ -332,16 +345,16 @@ export function createProcessCleanup(opts = {}) {
       lastOrphans.map(async (p) => {
         try {
           // SIGTERM
-          process.kill(p.pid, "SIGTERM");
+          killFn(p.pid, "SIGTERM");
 
           // 5초 대기 후 살아있으면 강제 종료
-          await new Promise((resolve) => setTimeout(resolve, SIGTERM_GRACE_MS));
+          await sleepFn(sigtermGraceMs);
 
           try {
             // 프로세스가 아직 살아있는지 확인 (signal 0)
-            process.kill(p.pid, 0);
+            killFn(p.pid, 0);
             // 여전히 살아있음 → Windows는 taskkill/process.kill, 그 외는 SIGKILL
-            forceKillPid(p.pid);
+            forceKillPid(p.pid, { isWindows, execFileSyncFn, killFn });
           } catch {
             // ESRCH: 이미 종료됨 — 정상
           }

package/hub/team/swarm-cli.mjs

@@ -131,14 +131,20 @@ export async function cmdSwarmRun(args, { json = false } = {}) {
     baseBranch: flags.baseBranch,
   });
 
-  hyper.on("shardLaunched", ({ shard, sessionId, remote }) => {
+  hyper.on("shardLaunched", ({ shardName, sessionId, remote }) => {
     const tag = remote ? ` ${GRAY}(remote)${RESET}` : "";
-    console.log(`  ${GREEN}▸${RESET} launched: ${shard}${tag} [${sessionId}]`);
+    console.log(
+      `  ${GREEN}▸${RESET} launched: ${shardName}${tag} [${sessionId}]`,
+    );
+  });
+  hyper.on("shardCompleted", ({ shardName, sessionId, isRedundant }) => {
+    const tag = isRedundant ? ` ${GRAY}(redundant)${RESET}` : "";
+    console.log(`  ${GREEN}✓${RESET} ${shardName}${tag} [${sessionId}]`);
   });
-  hyper.on("shardCompleted", ({ shard, success, reason }) => {
-    const mark = success ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+  hyper.on("shardFailed", ({ shardName, failureMode, reason }) => {
     const reasonStr = reason ? ` ${GRAY}(${reason})${RESET}` : "";
-    console.log(`  ${mark} ${shard}${reasonStr}`);
+    const modeStr = failureMode ? ` ${GRAY}[${failureMode}]${RESET}` : "";
+    console.log(`  ${RED}✗${RESET} ${shardName}${modeStr}${reasonStr}`);
   });
   hyper.on("warning", ({ type, ...rest }) => {
     console.error(