triflux 10.0.0 → 10.0.2

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

@@ -0,0 +1,69 @@
+import { createWtSession } from "../../../session.mjs";
+import { buildCliCommand } from "../../../pane.mjs";
+import { toAgentId } from "../../services/member-selector.mjs";
+import { buildTasks } from "../../services/task-model.mjs";
+import { warn } from "../../render.mjs";
+
+export async function startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl }) {
+  const paneCount = agents.length + 1;
+  const effectiveLayout = layout === "Nx1" ? "Nx1" : "1xN";
+  if (layout !== effectiveLayout) warn(`wt 모드에서 ${layout} 레이아웃은 미지원 — ${effectiveLayout}로 대체`);
+  console.log(`  레이아웃: ${effectiveLayout} (${paneCount} panes)`);
+
+  const session = createWtSession(sessionId, {
+    layout: effectiveLayout,
+    paneCommands: [
+      { title: `${sessionId}-lead`, command: buildCliCommand(lead) },
+      ...agents.map((cli, index) => ({
+        title: `${sessionId}-${cli}-${index + 1}`,
+        command: buildCliCommand(cli),
+      })),
+    ],
+  });
+
+  const members = [
+    {
+      role: "lead",
+      name: "lead",
+      cli: lead,
+      pane: session.panes[0] || "wt:0",
+      agentId: toAgentId(lead, session.panes[0] || "wt:0"),
+    },
+    ...agents.map((cli, index) => {
+      const pane = session.panes[index + 1] || `wt:${index + 1}`;
+      return {
+        role: "worker",
+        name: `${cli}-${index + 1}`,
+        cli,
+        pane,
+        subtask: subtasks[index],
+        agentId: toAgentId(cli, pane),
+      };
+    }),
+  ];
+
+  return {
+    sessionName: sessionId,
+    task,
+    lead,
+    agents,
+    layout: effectiveLayout,
+    teammateMode: "wt",
+    startedAt: Date.now(),
+    hubUrl,
+    members,
+    panes: Object.fromEntries(members.map((member) => [member.pane, {
+      role: member.role,
+      name: member.name,
+      cli: member.cli,
+      agentId: member.agentId,
+      subtask: member.subtask || null,
+    }])),
+    tasks: buildTasks(subtasks, members.filter((member) => member.role === "worker")),
+    wt: {
+      windowId: 0,
+      layout: effectiveLayout,
+      paneCount: session.paneCount,
+    },
+  };
+}

package/hub/team/cli/commands/status.mjs

@@ -0,0 +1,87 @@
+import { AMBER, BOLD, DIM, GRAY, GREEN, RED, RESET } from "../../shared.mjs";
+import { hasWindowsTerminalSession } from "../../session.mjs";
+import { fetchHubTaskList, nativeGetStatus } from "../services/hub-client.mjs";
+import { isNativeMode, isTeamAlive, isWtMode } from "../services/runtime-mode.mjs";
+import { loadTeamState } from "../services/state-store.mjs";
+import { formatCompletionSuffix } from "../render.mjs";
+
+export async function teamStatus(args = []) {
+  const json = process.env.TFX_OUTPUT_JSON === "1" || args.includes("--json");
+  const state = loadTeamState();
+  if (!state) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ status: "offline", sessionName: null, alive: false }, null, 2)}\n`);
+      return;
+    }
+    console.log(`\n  ${DIM}활성 팀 세션 없음${RESET}\n`);
+    return;
+  }
+
+  const alive = isTeamAlive(state);
+  const payload = {
+    status: alive ? "active" : "dead",
+    alive,
+    sessionName: state.sessionName,
+    teammateMode: state.teammateMode || "tmux",
+    lead: state.lead || "claude",
+    agents: state.agents || [],
+    startedAt: state.startedAt || null,
+    taskCount: (state.tasks || []).length,
+    members: (state.members || []).map((member) => ({
+      name: member.name,
+      cli: member.cli,
+      role: member.role,
+      pane: member.pane,
+    })),
+  };
+
+  if (isNativeMode(state) && alive) {
+    payload.nativeMembers = (await nativeGetStatus(state))?.data?.members || [];
+  }
+
+  if (alive) {
+    payload.hubTasks = await fetchHubTaskList(state);
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  console.log(`\n  ${AMBER}${BOLD}⬡ tfx multi${RESET} ${alive ? `${GREEN}● active${RESET}` : `${RED}● dead${RESET}`}\n`);
+  console.log(`    세션:   ${state.sessionName}`);
+  console.log(`    모드:   ${state.teammateMode || "tmux"}`);
+  console.log(`    리드:   ${state.lead || "claude"}`);
+  console.log(`    워커:   ${(state.agents || []).join(", ")}`);
+  console.log(`    Uptime: ${alive ? `${Math.round((Date.now() - state.startedAt) / 60000)}분` : "-"}`);
+  console.log(`    태스크: ${(state.tasks || []).length}`);
+  if (isWtMode(state) && !hasWindowsTerminalSession()) {
+    console.log(`    ${DIM}WT_SESSION 미감지: 생존성은 heuristics로 판정됨${RESET}`);
+  }
+
+  for (const member of state.members || []) {
+    console.log(`    - ${member.name} (${member.cli}) ${DIM}${member.role}${RESET} ${DIM}${member.pane}${RESET}`);
+  }
+
+  if (isNativeMode(state) && alive) {
+    for (const member of payload.nativeMembers) {
+      console.log(`    • ${member.name}: ${member.status}${formatCompletionSuffix(member)}${member.lastPreview ? ` ${DIM}${member.lastPreview}${RESET}` : ""}`);
+    }
+  }
+
+  if (alive) {
+    const hubTasks = payload.hubTasks || await fetchHubTaskList(state);
+    if (hubTasks.length) {
+      const completed = hubTasks.filter((task) => task.status === "completed").length;
+      const failed = hubTasks.filter((task) => task.status === "failed").length;
+      console.log(`\n  ${BOLD}Hub Tasks${RESET} ${DIM}(${completed}/${hubTasks.length} done)${RESET}`);
+      for (const task of hubTasks) {
+        const icon = task.status === "completed" ? `${GREEN}✓${RESET}` : task.status === "in_progress" ? `${AMBER}●${RESET}` : task.status === "failed" ? `${RED}✗${RESET}` : `${GRAY}○${RESET}`;
+        const owner = task.owner ? ` ${GRAY}[${task.owner}]${RESET}` : "";
+        console.log(`    ${icon} ${task.subject || task.description?.slice(0, 50) || ""}${owner}`);
+      }
+      if (failed > 0) console.log(`    ${RED}⚠ ${failed}건 실패${RESET}`);
+    }
+  }
+  console.log("");
+}

package/hub/team/cli/commands/stop.mjs

@@ -0,0 +1,31 @@
+import { closeWtSession, killSession, sessionExists } from "../../session.mjs";
+import { DIM, RESET } from "../../shared.mjs";
+import { nativeRequest } from "../services/native-control.mjs";
+import { isNativeMode, isWtMode } from "../services/runtime-mode.mjs";
+import { clearTeamState, loadTeamState } from "../services/state-store.mjs";
+import { ok } from "../render.mjs";
+
+export async function teamStop() {
+  const state = loadTeamState();
+  if (!state) {
+    console.log(`\n  ${DIM}활성 팀 세션 없음${RESET}\n`);
+    return;
+  }
+
+  if (isNativeMode(state)) {
+    await nativeRequest(state, "/stop", {});
+    try { process.kill(state.native.supervisorPid, "SIGTERM"); } catch {}
+    ok(`세션 종료: ${state.sessionName}`);
+  } else if (isWtMode(state)) {
+    const closed = closeWtSession({ layout: state?.wt?.layout || state?.layout || "1xN", paneCount: state?.wt?.paneCount ?? (state.members || []).length });
+    ok(`세션 종료: ${state.sessionName}${closed ? ` (${closed} panes closed)` : ""}`);
+  } else if (sessionExists(state.sessionName)) {
+    killSession(state.sessionName);
+    ok(`세션 종료: ${state.sessionName}`);
+  } else {
+    console.log(`  ${DIM}세션 이미 종료됨${RESET}`);
+  }
+
+  clearTeamState(state.sessionId);
+  console.log("");
+}

package/hub/team/cli/commands/task.mjs

@@ -0,0 +1,30 @@
+import { DIM, RESET, WHITE } from "../../shared.mjs";
+import { isTeamAlive } from "../services/runtime-mode.mjs";
+import { loadTeamState, saveTeamState } from "../services/state-store.mjs";
+import { normalizeTaskStatus, updateTaskStatus } from "../services/task-model.mjs";
+import { ok } from "../render.mjs";
+
+export function teamTaskUpdate(args = []) {
+  const state = loadTeamState();
+  if (!state || !isTeamAlive(state)) {
+    console.log(`\n  ${DIM}활성 팀 세션 없음${RESET}\n`);
+    return;
+  }
+
+  const nextStatus = normalizeTaskStatus(args[0]);
+  const taskId = String(args[1] || "").toUpperCase();
+  if (!nextStatus || !taskId) {
+    console.log(`\n  사용법: ${WHITE}tfx multi task <pending|progress|done> <T1>${RESET}\n`);
+    return;
+  }
+
+  const updated = updateTaskStatus(state.tasks || [], taskId, nextStatus);
+  if (!updated.target) {
+    console.log(`\n  ${DIM}태스크를 찾을 수 없음: ${taskId}${RESET}\n`);
+    return;
+  }
+
+  saveTeamState({ ...state, tasks: updated.tasks }, state.sessionId);
+  ok(`${updated.target.id} 상태 갱신: ${nextStatus}`);
+  console.log("");
+}

package/hub/team/cli/commands/tasks.mjs

@@ -0,0 +1,13 @@
+import { DIM, RESET } from "../../shared.mjs";
+import { isTeamAlive } from "../services/runtime-mode.mjs";
+import { loadTeamState } from "../services/state-store.mjs";
+import { renderTasks } from "../render.mjs";
+
+export function teamTasks() {
+  const state = loadTeamState();
+  if (!state || !isTeamAlive(state)) {
+    console.log(`\n  ${DIM}활성 팀 세션 없음${RESET}\n`);
+    return;
+  }
+  renderTasks(state.tasks || []);
+}

package/hub/team/cli/help.mjs

@@ -0,0 +1,42 @@
+import { AMBER, BOLD, DIM, GRAY, RESET, WHITE } from "../shared.mjs";
+
+export function renderTeamHelp() {
+  console.log(`
+  ${AMBER}${BOLD}⬡ tfx multi${RESET} ${DIM}멀티-CLI 팀 모드 (Lead + Teammates)${RESET}
+
+  ${BOLD}시작${RESET}
+    ${WHITE}tfx multi "작업 설명"${RESET}
+    ${WHITE}tfx multi --agents codex,gemini --lead claude "작업"${RESET}
+    ${WHITE}tfx multi --teammate-mode tmux "작업"${RESET}
+    ${WHITE}tfx multi --teammate-mode wt "작업"${RESET}   ${DIM}(Windows Terminal split-pane)${RESET}
+    ${WHITE}tfx multi --layout 1xN "작업"${RESET}               ${DIM}(세로 분할 컬럼)${RESET}
+    ${WHITE}tfx multi --layout Nx1 "작업"${RESET}               ${DIM}(가로 분할 스택)${RESET}
+    ${WHITE}tfx multi --dashboard-layout lite "작업"${RESET}    ${DIM}(dashboard-lite 기본 뷰)${RESET}
+    ${WHITE}tfx multi --dashboard-layout auto "작업"${RESET}    ${DIM}(dashboard viewer 레이아웃 자동 결정)${RESET}
+    ${WHITE}tfx multi --dashboard-size 0.4 "작업"${RESET}      ${DIM}(대시보드 분할 비율 0.2~0.8, 기본 0.50)${RESET}
+    ${WHITE}tfx multi --dashboard-anchor window "작업"${RESET} ${DIM}(대시보드 고정 위치: window|tab, 기본 window)${RESET}
+    ${WHITE}tfx multi --teammate-mode in-process "작업"${RESET} ${DIM}(tmux 불필요)${RESET}
+
+  ${BOLD}제어${RESET}
+    ${WHITE}tfx multi status${RESET}                      ${GRAY}현재 팀 상태${RESET}
+    ${WHITE}tfx multi debug${RESET} ${DIM}[--lines 30]${RESET}          ${GRAY}강화 디버그 출력(환경/세션/pane tail)${RESET}
+    ${WHITE}tfx multi tasks${RESET}                       ${GRAY}공유 태스크 목록${RESET}
+    ${WHITE}tfx multi task${RESET} ${DIM}<pending|progress|done> <T1>${RESET} ${GRAY}태스크 상태 갱신${RESET}
+    ${WHITE}tfx multi attach${RESET} ${DIM}[--wt]${RESET}               ${GRAY}세션 재연결 (WT 분할은 opt-in)${RESET}
+    ${WHITE}tfx multi focus${RESET} ${DIM}<lead|이름|번호> [--wt]${RESET} ${GRAY}특정 팀메이트 포커스${RESET}
+    ${WHITE}tfx multi send${RESET} ${DIM}<lead|이름|번호> "msg"${RESET} ${GRAY}팀메이트에 메시지 주입${RESET}
+    ${WHITE}tfx multi interrupt${RESET} ${DIM}<대상>${RESET}            ${GRAY}팀메이트 인터럽트(C-c)${RESET}
+    ${WHITE}tfx multi control${RESET} ${DIM}<대상> <cmd>${RESET}        ${GRAY}리드 제어명령(interrupt|stop|pause|resume)${RESET}
+    ${WHITE}tfx multi stop${RESET}                        ${GRAY}graceful 종료${RESET}
+    ${WHITE}tfx multi kill${RESET}                        ${GRAY}모든 팀 세션 강제 종료${RESET}
+    ${WHITE}tfx multi list${RESET}                        ${GRAY}활성 세션 목록${RESET}
+
+  ${BOLD}키 조작(Claude teammate 스타일, tmux 모드)${RESET}
+    ${WHITE}Shift+Down${RESET}  ${GRAY}다음 팀메이트${RESET}
+    ${WHITE}Shift+Tab${RESET}   ${GRAY}이전 팀메이트 (권장)${RESET}
+    ${WHITE}Shift+Left${RESET}  ${GRAY}이전 팀메이트 (대체)${RESET}
+    ${WHITE}Shift+Up${RESET}    ${GRAY}미지원 (Claude Code가 캡처 불가, scroll-up 충돌)${RESET}
+    ${WHITE}Escape${RESET}      ${GRAY}현재 팀메이트 인터럽트${RESET}
+    ${WHITE}Ctrl+T${RESET}      ${GRAY}태스크 목록 토글${RESET}
+`);
+}

package/hub/team/cli/index.mjs

@@ -0,0 +1,41 @@
+import { renderTeamHelp } from "./help.mjs";
+import { resolveTeamCommand } from "./manifest.mjs";
+import { teamAttach } from "./commands/attach.mjs";
+import { teamControl } from "./commands/control.mjs";
+import { teamDebug } from "./commands/debug.mjs";
+import { teamFocus } from "./commands/focus.mjs";
+import { teamInterrupt } from "./commands/interrupt.mjs";
+import { teamKill } from "./commands/kill.mjs";
+import { teamList } from "./commands/list.mjs";
+import { teamSend } from "./commands/send.mjs";
+import { teamStart } from "./commands/start/index.mjs";
+import { teamStatus } from "./commands/status.mjs";
+import { teamStop } from "./commands/stop.mjs";
+import { teamTaskUpdate } from "./commands/task.mjs";
+import { teamTasks } from "./commands/tasks.mjs";
+
+const handlers = {
+  attach: teamAttach,
+  control: teamControl,
+  debug: teamDebug,
+  focus: teamFocus,
+  help: renderTeamHelp,
+  interrupt: teamInterrupt,
+  kill: teamKill,
+  list: teamList,
+  send: teamSend,
+  start: teamStart,
+  status: teamStatus,
+  stop: teamStop,
+  task: teamTaskUpdate,
+  tasks: teamTasks,
+};
+
+export async function cmdTeam() {
+  const args = process.argv.slice(3);
+  const command = resolveTeamCommand(args[0]);
+  if (!args.length) return renderTeamHelp();
+  // 미등록 커맨드는 teamStart로 fallthrough (팀 생성 기본값)
+  if (!command) return teamStart(args);
+  return handlers[command](args.slice(1));
+}

package/hub/team/cli/manifest.mjs

@@ -0,0 +1,29 @@
+export const TEAM_COMMANDS = [
+  { name: "status", usage: "tfx multi status", desc: "현재 팀 상태" },
+  { name: "debug", usage: "tfx multi debug [--lines 30]", desc: "강화 디버그 출력" },
+  { name: "tasks", usage: "tfx multi tasks", desc: "공유 태스크 목록" },
+  { name: "task", usage: "tfx multi task <pending|progress|done> <T1>", desc: "태스크 상태 갱신" },
+  { name: "attach", usage: "tfx multi attach [--wt]", desc: "세션 재연결" },
+  { name: "focus", usage: "tfx multi focus <lead|이름|번호> [--wt]", desc: "특정 팀메이트 포커스" },
+  { name: "send", usage: "tfx multi send <lead|이름|번호> \"msg\"", desc: "팀메이트에 메시지 주입" },
+  { name: "interrupt", usage: "tfx multi interrupt <대상>", desc: "팀메이트 인터럽트(C-c)" },
+  { name: "control", usage: "tfx multi control <대상> <cmd> [사유]", desc: "리드 제어명령 전송" },
+  { name: "stop", usage: "tfx multi stop", desc: "graceful 종료" },
+  { name: "kill", usage: "tfx multi kill", desc: "모든 팀 세션 강제 종료" },
+  { name: "list", usage: "tfx multi list", desc: "활성 세션 목록" },
+  { name: "help", usage: "tfx multi help", desc: "도움말" },
+  { name: "start", usage: "tfx multi start [options]", desc: "새 팀 세션 시작 (기본 커맨드)" },
+];
+
+export const TEAM_COMMAND_ALIASES = new Map([
+  ["-h", "help"],
+  ["--help", "help"],
+]);
+
+export const TEAM_SUBCOMMANDS = new Set(TEAM_COMMANDS.map(({ name }) => name));
+
+export function resolveTeamCommand(raw) {
+  if (typeof raw !== "string") return null;
+  const command = raw.toLowerCase();
+  return TEAM_SUBCOMMANDS.has(command) ? command : (TEAM_COMMAND_ALIASES.get(command) || null);
+}

package/hub/team/cli/render.mjs

@@ -0,0 +1,30 @@
+import { AMBER, BOLD, DIM, GRAY, GREEN, RED, RESET, WHITE, YELLOW } from "../shared.mjs";
+
+export function ok(msg) { console.log(`  ${GREEN}✓${RESET} ${msg}`); }
+export function warn(msg) { console.log(`  ${YELLOW}⚠${RESET} ${msg}`); }
+export function fail(msg) { console.log(`  ${RED}✗${RESET} ${msg}`); }
+
+export function renderTasks(tasks = []) {
+  if (!tasks.length) {
+    console.log(`\n  ${DIM}태스크 없음${RESET}\n`);
+    return;
+  }
+
+  console.log(`\n  ${AMBER}${BOLD}⬡ Team Tasks${RESET}\n`);
+  for (const task of tasks) {
+    const dep = task.depends_on?.length ? ` ${DIM}(deps: ${task.depends_on.join(",")})${RESET}` : "";
+    const owner = task.owner ? ` ${GRAY}[${task.owner}]${RESET}` : "";
+    console.log(`    ${WHITE}${task.id}${RESET} ${String(task.status || "").padEnd(11)} ${task.title}${owner}${dep}`);
+  }
+  console.log("");
+}
+
+export function formatCompletionSuffix(member) {
+  if (!member?.completionStatus) return "";
+  if (member.completionStatus === "abnormal") {
+    return ` ${RED}[abnormal:${member.completionReason || "unknown"}]${RESET}`;
+  }
+  if (member.completionStatus === "normal") return ` ${GREEN}[route-ok]${RESET}`;
+  if (member.completionStatus === "unchecked") return ` ${GRAY}[route-unchecked]${RESET}`;
+  return "";
+}

package/hub/team/cli/services/attach-fallback.mjs

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+
+import {
+  getSessionAttachedCount,
+  hasWindowsTerminal,
+  resolveAttachCommand,
+} from "../../session.mjs";
+import { PKG_ROOT } from "./state-store.mjs";
+
+export async function launchAttachInWindowsTerminal(sessionName) {
+  if (!hasWindowsTerminal()) return false;
+
+  let attachSpec;
+  try {
+    attachSpec = resolveAttachCommand(sessionName);
+  } catch {
+    return false;
+  }
+
+  const beforeAttached = getSessionAttachedCount(sessionName);
+  try {
+    const child = spawn("wt", ["-w", "0", "split-pane", "-V", "-d", PKG_ROOT, attachSpec.command, ...attachSpec.args], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: false,
+    });
+    child.unref();
+
+    if (beforeAttached == null) return true;
+    const deadline = Date.now() + 3500;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 120));
+      const nowAttached = getSessionAttachedCount(sessionName);
+      if (typeof nowAttached === "number" && nowAttached > beforeAttached) return true;
+    }
+  } catch {}
+  return false;
+}
+
+export function buildManualAttachCommand(sessionName) {
+  try {
+    const spec = resolveAttachCommand(sessionName);
+    return [spec.command, ...spec.args].map((value) => {
+      const text = String(value);
+      return /\s/.test(text) ? `"${text.replace(/"/g, '\\"')}"` : text;
+    }).join(" ");
+  } catch {
+    return `tmux attach-session -t ${sessionName}`;
+  }
+}
+
+export function wantsWtAttachFallback(args = [], env = process.env) {
+  return args.includes("--wt") || args.includes("--spawn-wt") || env.TFX_ATTACH_WT_AUTO === "1";
+}

package/hub/team/cli/services/hub-client.mjs

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+import { publishLeadControl as publishLeadControlBridge } from "../../lead-control.mjs";
+import { getTeamStatus as fetchTeamStatus, subscribeToLeadCommands as pullLeadCommands } from "../../session-sync.mjs";
+import { HUB_PID_DIR, PKG_ROOT } from "./state-store.mjs";
+export { nativeGetStatus } from "./native-control.mjs";
+
+const HUB_PID_FILE = join(HUB_PID_DIR, "hub.pid");
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+export function formatHostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+export function buildHubBaseUrl(host, port) {
+  return `http://${formatHostForUrl(host)}:${port}`;
+}
+
+export function getDefaultHubPort() {
+  const envPortRaw = Number(process.env.TFX_HUB_PORT || "27888");
+  return Number.isFinite(envPortRaw) && envPortRaw > 0 ? envPortRaw : 27888;
+}
+
+export function getDefaultHubUrl() {
+  return `${buildHubBaseUrl("127.0.0.1", getDefaultHubPort())}/mcp`;
+}
+
+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";
+}
+
+async function probeHubStatus(host, port, timeoutMs = 1500) {
+  try {
+    const res = await fetch(`${buildHubBaseUrl(host, port)}/status`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data?.hub ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getHubInfo() {
+  const probePort = getDefaultHubPort();
+
+  if (existsSync(HUB_PID_FILE)) {
+    try {
+      const raw = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+      const pid = Number(raw?.pid);
+      if (!Number.isFinite(pid) || pid <= 0) throw new Error("invalid pid");
+      process.kill(pid, 0);
+      const host = normalizeLoopbackHost(raw?.host);
+      const port = Number(raw?.port) || 27888;
+      const status = await probeHubStatus(host, port, 1200);
+      return {
+        ...raw,
+        pid,
+        host,
+        port,
+        url: `${buildHubBaseUrl(host, port)}/mcp`,
+        ...(status ? {} : { degraded: true }),
+      };
+    } catch {
+      try { unlinkSync(HUB_PID_FILE); } catch {}
+    }
+  }
+
+  for (const portCandidate of Array.from(new Set([probePort, 27888]))) {
+    const data = await probeHubStatus("127.0.0.1", portCandidate, 1200);
+    if (!data) continue;
+    const port = Number(data.port) || portCandidate;
+    const pid = Number(data.pid);
+    const recovered = {
+      pid: Number.isFinite(pid) ? pid : null,
+      host: "127.0.0.1",
+      port,
+      url: `${buildHubBaseUrl("127.0.0.1", port)}/mcp`,
+      discovered: true,
+    };
+    if (Number.isFinite(recovered.pid) && recovered.pid > 0) {
+      try {
+        mkdirSync(HUB_PID_DIR, { recursive: true });
+        writeFileSync(HUB_PID_FILE, JSON.stringify({ ...recovered, started: Date.now() }));
+      } catch {}
+    }
+    return recovered;
+  }
+  return null;
+}
+
+export async function startHubDaemon() {
+  const serverPath = join(PKG_ROOT, "hub", "server.mjs");
+  if (!existsSync(serverPath)) {
+    const error = new Error("hub/server.mjs 없음");
+    error.code = "HUB_SERVER_MISSING";
+    throw error;
+  }
+
+  const child = spawn(process.execPath, [serverPath], {
+    env: { ...process.env },
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+  });
+  child.unref();
+
+  const expectedPort = getDefaultHubPort();
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    const status = await probeHubStatus("127.0.0.1", expectedPort, 500);
+    if (status?.hub) {
+      return {
+        pid: Number(status.pid) || child.pid,
+        host: "127.0.0.1",
+        port: expectedPort,
+        url: `${buildHubBaseUrl("127.0.0.1", expectedPort)}/mcp`,
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return null;
+}
+
+/**
+ * Hub가 살아있는지 확인하고, 죽어있으면 재시작을 시도한다.
+ * exponential backoff: 1초, 2초, 4초
+ * 모든 재시작 실패 시 에러를 throw한다 (silent fail 아님).
+ * @param {number} [maxRetries=3]
+ * @returns {Promise<object>} Hub 정보
+ * @throws {Error} 모든 재시작 시도 실패 시
+ */
+export async function ensureHubAlive(maxRetries = 3) {
+  const hub = await getHubInfo();
+  if (hub && !hub.degraded) return hub;
+
+  let lastError = null;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const restarted = await startHubDaemon();
+      if (restarted) {
+        // 재시작 후 연결 복구 확인
+        const recovered = await getHubInfo();
+        if (recovered) return recovered;
+      }
+    } catch (err) {
+      lastError = err;
+    }
+    // 다음 재시도 전 대기: 1초, 2초, 4초 (마지막 시도 후에는 대기 없음)
+    if (i < maxRetries - 1) {
+      const backoffMs = Math.pow(2, i) * 1000; // i=0: 1초, i=1: 2초, i=2: 4초
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+    }
+  }
+
+  const error = new Error(`Hub 재시작 ${maxRetries}회 모두 실패${lastError ? `: ${lastError.message}` : ""}`);
+  error.code = "HUB_RESTART_FAILED";
+  error.cause = lastError;
+  throw error;
+}
+
+export async function fetchHubTaskList(state) {
+  const hubBase = (state?.hubUrl || getDefaultHubUrl()).replace(/\/mcp$/, "");
+  const teamName = state?.native?.teamName || state?.sessionName || null;
+  if (!teamName) return [];
+
+  try {
+    const res = await fetch(`${hubBase}/bridge/team/task-list`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ team_name: teamName }),
+      signal: AbortSignal.timeout(2000),
+    });
+    const data = await res.json();
+    return data?.ok ? (data.data?.tasks || []) : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function publishLeadControl(state, targetMember, command, reason = "") {
+  const hubBase = (state?.hubUrl || getDefaultHubUrl()).replace(/\/mcp$/, "");
+  const leadAgent = (state?.members || []).find((member) => member.role === "lead")?.agentId || "lead";
+  const targetAgent = typeof targetMember === "string" ? targetMember : targetMember?.agentId;
+
+  const result = await publishLeadControlBridge({
+    hubUrl: hubBase,
+    fromAgent: leadAgent,
+    toAgent: targetAgent,
+    command,
+    reason,
+    payload: {
+      issued_by: leadAgent,
+      issued_at: Date.now(),
+    },
+  });
+
+  return !!result?.ok;
+}
+
+export async function subscribeToLeadCommands(state, member, options = {}) {
+  const hubBase = (state?.hubUrl || getDefaultHubUrl()).replace(/\/mcp$/, "");
+  const fallbackAgentId = (state?.members || []).find((candidate) => candidate.role === "lead")?.agentId || null;
+  const agentId = typeof member === "string"
+    ? member
+    : member?.agentId || options?.agentId || fallbackAgentId;
+
+  return await pullLeadCommands({
+    hubUrl: hubBase,
+    agentId,
+    ...options,
+  });
+}
+
+export async function getTeamStatus(state, options = {}) {
+  const hubBase = (state?.hubUrl || getDefaultHubUrl()).replace(/\/mcp$/, "");
+  return await fetchTeamStatus({
+    hubUrl: hubBase,
+    ...options,
+  });
+}