triflux 8.0.0 → 8.2.2

package/bin/triflux.mjs

@@ -127,8 +127,13 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
     },
   },
   multi: {
-    usage: "tfx multi <subcommand>",
+    usage: "tfx multi [--dashboard-layout single|split-2col|split-3col|auto] <subcommand|task>",
     description: "멀티-CLI 팀 모드",
+    options: [
+      { name: "--dashboard", type: "boolean", description: "headless dashboard viewer 표시 (기본값: 켜짐)" },
+      { name: "--no-dashboard", type: "boolean", description: "headless dashboard viewer 비활성화" },
+      { name: "--dashboard-layout", type: "string", description: "dashboard viewer 레이아웃 선택: single|split-2col|split-3col|auto" },
+    ],
     subcommands: {
       status: {
         usage: "tfx multi status [--json]",
@@ -1372,6 +1377,40 @@ async function cmdDoctor(options = {}) {
     }
   }
 
+  // 12.5. 고아 node.exe 프로세스 정리 (Windows)
+  section("Orphan Processes");
+  if (process.platform === "win32") {
+    try {
+      const { cleanupOrphanNodeProcesses } = await import("../hub/lib/process-utils.mjs");
+      if (fix) {
+        const { killed, remaining } = cleanupOrphanNodeProcesses();
+        if (killed > 0) {
+          warn(`고아 node.exe ${killed}개 정리 완료 (남은 프로세스: ${remaining})`);
+        } else {
+          ok(`고아 node.exe 없음 (활성: ${remaining})`);
+        }
+      } else {
+        // --fix 없이는 개수만 보고
+        const { execSync: execSyncDoctor } = await import("node:child_process");
+        const countStr = execSyncDoctor(
+          `powershell -NoProfile -Command "(Get-Process node -ErrorAction SilentlyContinue).Count"`,
+          { encoding: "utf8", timeout: 5000 },
+        ).trim();
+        const count = Number.parseInt(countStr, 10) || 0;
+        if (count > 20) {
+          warn(`node.exe ${count}개 실행 중 (고아 포함 가능). 정리: tfx doctor --fix`);
+          issues++;
+        } else {
+          ok(`node.exe ${count}개 (정상 범위)`);
+        }
+      }
+    } catch (e) {
+      info(`고아 프로세스 검사 실패: ${e.message}`);
+    }
+  } else {
+    ok("Windows 전용 검사 — 건너뜀");
+  }
+
   // 13. Stale Teams (Claude teams/ + tasks/ 자동 감지)
   section("Stale Teams");
   const teamsDir = join(CLAUDE_DIR, "teams");

package/hub/lib/process-utils.mjs

@@ -1,6 +1,15 @@
 // hub/lib/process-utils.mjs
 // 프로세스 관련 공유 유틸리티
 
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLEANUP_SCRIPT_DIR = join(tmpdir(), "tfx-process-utils");
+const CLEANUP_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "cleanup-orphans.ps1");
+const TREE_SCRIPT_PATH = join(CLEANUP_SCRIPT_DIR, "get-ancestor-tree.ps1");
+
 /**
  * 주어진 PID의 프로세스가 살아있는지 확인한다.
  * EPERM: 프로세스는 존재하지만 signal 권한 없음 → alive
@@ -18,3 +27,117 @@ export function isPidAlive(pid) {
     return false;
   }
 }
+
+/**
+ * PowerShell 헬퍼 스크립트를 임시 디렉토리에 생성한다.
+ * bash의 $_ 이스케이핑 문제를 피하기 위해 -File로 실행.
+ */
+function ensureHelperScripts() {
+  mkdirSync(CLEANUP_SCRIPT_DIR, { recursive: true });
+
+  if (!existsSync(TREE_SCRIPT_PATH)) {
+    writeFileSync(TREE_SCRIPT_PATH, `
+param([int]$StartPid)
+$p = $StartPid
+for ($i = 0; $i -lt 10; $i++) {
+    if ($p -le 0) { break }
+    Write-Output $p
+    $parent = (Get-CimInstance Win32_Process -Filter "ProcessId=$p" -ErrorAction SilentlyContinue).ParentProcessId
+    if ($null -eq $parent -or $parent -le 0) { break }
+    $p = $parent
+}
+`, "utf8");
+  }
+
+  if (!existsSync(CLEANUP_SCRIPT_PATH)) {
+    writeFileSync(CLEANUP_SCRIPT_PATH, `
+$ErrorActionPreference = 'SilentlyContinue'
+Get-CimInstance Win32_Process -Filter "Name='node.exe'" | ForEach-Object {
+    Write-Output "$($_.ProcessId),$($_.ParentProcessId)"
+}
+`, "utf8");
+  }
+}
+
+/**
+ * 부모 프로세스가 죽은 고아 node.exe 프로세스를 정리한다.
+ * Windows 전용 — Agent 서브프로세스가 MCP 서버를 남기는 문제 대응.
+ *
+ * 보호 대상: 현재 프로세스, Hub PID, 살아있는 부모를 가진 프로세스
+ * @returns {{ killed: number, remaining: number }}
+ */
+export function cleanupOrphanNodeProcesses() {
+  if (process.platform !== "win32") return { killed: 0, remaining: 0 };
+
+  ensureHelperScripts();
+
+  const myPid = process.pid;
+
+  // Hub PID 보호
+  let hubPid = null;
+  try {
+    const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+    if (existsSync(hubPidPath)) {
+      const hubInfo = JSON.parse(readFileSync(hubPidPath, "utf8"));
+      hubPid = Number(hubInfo?.pid);
+    }
+  } catch {}
+
+  // 보호 PID 세트: 현재 프로세스 + Hub + 현재 프로세스의 조상 트리
+  const protectedPids = new Set();
+  protectedPids.add(myPid);
+  if (Number.isFinite(hubPid) && hubPid > 0) protectedPids.add(hubPid);
+
+  try {
+    // 현재 프로세스의 조상 트리를 보호 목록에 추가
+    const treeOutput = execSync(
+      `powershell -NoProfile -ExecutionPolicy Bypass -File "${TREE_SCRIPT_PATH}" -StartPid ${myPid}`,
+      { encoding: "utf8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"] },
+    );
+    for (const line of treeOutput.split(/\r?\n/)) {
+      const pid = Number.parseInt(line.trim(), 10);
+      if (Number.isFinite(pid) && pid > 0) protectedPids.add(pid);
+    }
+  } catch {}
+
+  let killed = 0;
+  try {
+    // 부모가 죽은 고아 node.exe 찾기 — PS 스크립트로 실행 (bash $_ 이스케이핑 회피)
+    const output = execSync(
+      `powershell -NoProfile -ExecutionPolicy Bypass -File "${CLEANUP_SCRIPT_PATH}"`,
+      { encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    for (const line of output.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [pidStr, ppidStr] = trimmed.split(",");
+      const pid = Number.parseInt(pidStr, 10);
+      const ppid = Number.parseInt(ppidStr, 10);
+
+      if (!Number.isFinite(pid) || pid <= 0) continue;
+      if (protectedPids.has(pid)) continue;
+
+      // 부모가 살아있으면 건드리지 않음
+      if (Number.isFinite(ppid) && ppid > 0 && isPidAlive(ppid)) continue;
+
+      // 고아 프로세스 종료
+      try {
+        process.kill(pid, "SIGTERM");
+        killed++;
+      } catch {}
+    }
+  } catch {}
+
+  // 남은 프로세스 수 확인
+  let remaining = 0;
+  try {
+    const countOutput = execSync(
+      `powershell -NoProfile -Command "(Get-Process node -ErrorAction SilentlyContinue).Count"`,
+      { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] },
+    );
+    remaining = Number.parseInt(countOutput.trim(), 10) || 0;
+  } catch {}
+
+  return { killed, remaining };
+}

package/hub/server.mjs

@@ -18,6 +18,7 @@ import { createAssignCallbackServer } from './assign-callbacks.mjs';
 import { createTools } from './tools.mjs';
 import { DelegatorService } from './delegator/index.mjs';
 import { createDelegatorMcpWorker } from './workers/delegator-mcp.mjs';
+import { cleanupOrphanNodeProcesses } from './lib/process-utils.mjs';
 import { createModuleLogger } from '../scripts/lib/logger.mjs';
 import { wrapRequestHandler } from './middleware/request-logger.mjs';
 
@@ -778,6 +779,18 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
   }, 60000);
   sessionTimer.unref();
 
+  // 고아 node.exe 프로세스 주기적 정리 (5분마다)
+  // Agent 서브프로세스가 MCP 서버를 남기는 Windows 이슈 대응
+  const orphanCleanupTimer = setInterval(() => {
+    try {
+      const { killed } = cleanupOrphanNodeProcesses();
+      if (killed > 0) {
+        hubLog.info({ killed }, 'hub.orphan_cleanup');
+      }
+    } catch {}
+  }, 5 * 60 * 1000);
+  orphanCleanupTimer.unref();
+
   // Evict stale rate-limit buckets once per minute to bound memory usage.
   const rateLimitTimer = setInterval(() => {
     const cutoff = Date.now() - RATE_LIMIT_WINDOW_MS;
@@ -793,6 +806,32 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
   rateLimitTimer.unref();
 
   mkdirSync(PID_DIR, { recursive: true });
+
+  // Stale PID 파일 정리 — 이전 Hub 프로세스가 비정상 종료된 경우
+  if (existsSync(PID_FILE)) {
+    try {
+      const prevInfo = JSON.parse(readFileSync(PID_FILE, 'utf8'));
+      const prevPid = Number(prevInfo?.pid);
+      if (Number.isFinite(prevPid) && prevPid > 0) {
+        try {
+          process.kill(prevPid, 0); // alive 체크만
+          // 프로세스가 살아있으면 포트 충돌 가능성 — 기존 Hub 재사용 안내
+          if (Number(prevInfo.port) === Number(port)) {
+            hubLog.warn({ prevPid, port }, 'hub.stale_pid: previous hub still alive on same port');
+          }
+        } catch {
+          // 프로세스 죽음 → stale PID 파일 삭제
+          try { unlinkSync(PID_FILE); } catch {}
+          hubLog.info({ prevPid }, 'hub.stale_pid_cleaned');
+        }
+      } else {
+        try { unlinkSync(PID_FILE); } catch {}
+      }
+    } catch {
+      try { unlinkSync(PID_FILE); } catch {}
+    }
+  }
+
   await pipe.start();
   await assignCallbacks.start();
 
@@ -832,6 +871,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         clearInterval(hitlTimer);
         clearInterval(sessionTimer);
         clearInterval(rateLimitTimer);
+        clearInterval(orphanCleanupTimer);
         for (const [, session] of transports) {
           try { await session.mcp.close(); } catch {}
           try { await session.transport.close(); } catch {}
@@ -860,7 +900,14 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         stop: stopFn,
       });
     });
-    httpServer.on('error', reject);
+    httpServer.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        hubLog.error({ port, host }, 'hub.port_in_use: port already occupied — check for existing hub or other service');
+        reject(new Error(`Hub 포트 ${port}이(가) 이미 사용 중입니다. 기존 Hub 프로세스를 확인하세요. (PID file: ${PID_FILE})`));
+      } else {
+        reject(err);
+      }
+    });
   });
 }
 

package/hub/team/ansi.mjs

@@ -1,5 +1,8 @@
 // hub/team/ansi.mjs — Zero-dependency ANSI escape 유틸리티
 // TUI 대시보드 렌더링을 위한 최소 헬퍼.
+//
+// wcwidth 지원: emoji/CJK wide=2셀, combining mark=0셀, ANSI escape=0셀
+// 외부 의존성 없이 Unicode 범위 기반으로 구현.
 
 export const ESC = "\x1b";
 
@@ -65,44 +68,183 @@ export function dim(text)   { return `${DIM}${text}${RESET}`; }
 // ── 박스 그리기 (유니코드 테두리) ──
 const BOX = { tl: "┌", tr: "┐", bl: "└", br: "┘", h: "─", v: "│", ml: "├", mr: "┤" };
 
-export function box(lines, width) {
-  const top = `${BOX.tl}${BOX.h.repeat(width - 2)}${BOX.tr}`;
-  const bot = `${BOX.bl}${BOX.h.repeat(width - 2)}${BOX.br}`;
-  const mid = `${BOX.ml}${BOX.h.repeat(width - 2)}${BOX.mr}`;
-  const body = lines.map((l) => `${BOX.v} ${padRight(l, width - 4)} ${BOX.v}`);
+export function box(lines, width, borderColor = "") {
+  const bc = borderColor;
+  const rst = bc ? RESET : "";
+  const top = `${bc}${BOX.tl}${BOX.h.repeat(width - 2)}${BOX.tr}${rst}`;
+  const bot = `${bc}${BOX.bl}${BOX.h.repeat(width - 2)}${BOX.br}${rst}`;
+  const mid = `${bc}${BOX.ml}${BOX.h.repeat(width - 2)}${BOX.mr}${rst}`;
+  const body = lines.map((l) => `${bc}${BOX.v}${rst} ${padRight(l, width - 4)} ${bc}${BOX.v}${rst}`);
   return { top, body, bot, mid };
 }
 
+// ── wcwidth 구현 (외부 의존성 없음) ──
+// Unicode 코드포인트의 터미널 표시 너비를 반환: 0(combining), 1(일반), 2(wide)
+function charWidth(cp) {
+  // combining / zero-width 범위
+  if (
+    cp === 0 || cp === 0xAD ||
+    (cp >= 0x0300 && cp <= 0x036F) ||  // Combining Diacritical Marks
+    (cp >= 0x0610 && cp <= 0x061A) ||
+    (cp >= 0x064B && cp <= 0x065F) ||
+    (cp >= 0x1AB0 && cp <= 0x1AFF) ||
+    (cp >= 0x1DC0 && cp <= 0x1DFF) ||
+    (cp >= 0x20D0 && cp <= 0x20FF) ||  // Combining Diacritical Marks for Symbols
+    (cp >= 0xFE20 && cp <= 0xFE2F)     // Combining Half Marks
+  ) return 0;
+
+  // Wide: CJK Unified Ideographs, Hangul, Fullwidth, emoji 주요 블록
+  if (
+    (cp >= 0x1100 && cp <= 0x115F) ||  // Hangul Jamo
+    (cp >= 0x2E80 && cp <= 0x2EFF) ||  // CJK Radicals Supplement
+    (cp >= 0x2F00 && cp <= 0x2FFF) ||
+    (cp >= 0x3000 && cp <= 0x303F) ||  // CJK Symbols and Punctuation
+    (cp >= 0x3040 && cp <= 0x309F) ||  // Hiragana
+    (cp >= 0x30A0 && cp <= 0x30FF) ||  // Katakana
+    (cp >= 0x3100 && cp <= 0x312F) ||
+    (cp >= 0x3130 && cp <= 0x318F) ||  // Hangul Compatibility Jamo
+    (cp >= 0x3190 && cp <= 0x319F) ||
+    (cp >= 0x31C0 && cp <= 0x31EF) ||
+    (cp >= 0x3200 && cp <= 0x32FF) ||
+    (cp >= 0x3300 && cp <= 0x33FF) ||
+    (cp >= 0x3400 && cp <= 0x4DBF) ||
+    (cp >= 0x4E00 && cp <= 0x9FFF) ||  // CJK Unified Ideographs
+    (cp >= 0xA000 && cp <= 0xA48F) ||
+    (cp >= 0xA490 && cp <= 0xA4CF) ||
+    (cp >= 0xA960 && cp <= 0xA97F) ||
+    (cp >= 0xAC00 && cp <= 0xD7AF) ||  // Hangul Syllables
+    (cp >= 0xF900 && cp <= 0xFAFF) ||  // CJK Compatibility Ideographs
+    (cp >= 0xFE10 && cp <= 0xFE1F) ||
+    (cp >= 0xFE30 && cp <= 0xFE4F) ||
+    (cp >= 0xFF00 && cp <= 0xFF60) ||  // Fullwidth Forms
+    (cp >= 0xFFE0 && cp <= 0xFFE6) ||
+    (cp >= 0x1B000 && cp <= 0x1B0FF) ||
+    (cp >= 0x1F004 && cp <= 0x1F0CF) ||
+    (cp >= 0x1F200 && cp <= 0x1F2FF) ||
+    (cp >= 0x1F300 && cp <= 0x1F64F) || // Misc Symbols, Emoticons
+    (cp >= 0x1F680 && cp <= 0x1F6FF) || // Transport & Map
+    (cp >= 0x1F900 && cp <= 0x1FAFF) || // Supplemental Symbols
+    (cp >= 0x20000 && cp <= 0x2FFFD) ||
+    (cp >= 0x30000 && cp <= 0x3FFFD)
+  ) return 2;
+
+  return 1;
+}
+
+// 문자열의 터미널 표시 너비 계산 (ANSI escape 제외, wcwidth 적용)
+export function wcswidth(str) {
+  const plain = stripAnsi(str);
+  let width = 0;
+  for (const char of plain) {
+    width += charWidth(char.codePointAt(0));
+  }
+  return width;
+}
+
 // ── 텍스트 유틸 ──
+export function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\].*?(\x07|\x1b\\)/g, "");
+}
+
+// wcwidth-aware padRight: ANSI + wide char 보정 포함
 export function padRight(str, len) {
-  // ANSI 코드 제외한 실제 표시 길이 기준 패딩
-  const visible = stripAnsi(str);
-  const pad = Math.max(0, len - visible.length);
+  const w = wcswidth(str);
+  const pad = Math.max(0, len - w);
   return str + " ".repeat(pad);
 }
 
+// wcwidth-aware truncate: wide char 경계에서 자름
 export function truncate(str, maxLen) {
-  const visible = stripAnsi(str);
-  if (visible.length <= maxLen) return str;
-  return visible.slice(0, maxLen - 1) + "…";
+  const plain = stripAnsi(str);
+  const w = wcswidth(plain);
+  if (w <= maxLen) return str;
+
+  let acc = 0;
+  let i = 0;
+  for (const char of plain) {
+    const cw = charWidth(char.codePointAt(0));
+    if (acc + cw > maxLen - 1) break;
+    acc += cw;
+    i += char.length;
+  }
+  return plain.slice(0, i) + "…";
 }
 
-export function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\].*?(\x07|\x1b\\)/g, "");
+// wcwidth-aware clip: 정확히 width 셀에 맞게 자르고 패딩 (wide char 경계 보정)
+export function clip(str, width) {
+  const plain = stripAnsi(str);
+  let acc = 0;
+  let i = 0;
+  for (const char of plain) {
+    const cw = charWidth(char.codePointAt(0));
+    if (acc + cw > width) {
+      // wide char이 경계를 넘으면 공백으로 채움
+      const result = plain.slice(0, i) + " ".repeat(width - acc);
+      return result;
+    }
+    acc += cw;
+    i += char.length;
+  }
+  return plain + " ".repeat(width - acc);
+}
+
+// ── Catppuccin Mocha 색상 상수 ──
+export const MOCHA = {
+  ok:        `${ESC}[38;5;114m`,  // #a6e3a1 green
+  partial:   `${ESC}[38;5;216m`,  // #fab387 peach
+  fail:      `${ESC}[38;5;210m`,  // #f38ba8 red
+  thinking:  `${ESC}[38;5;183m`,  // #cba6f7 mauve
+  executing: `${ESC}[38;5;117m`,  // #74c7ec sky
+  border:    `${ESC}[38;5;238m`,  // #45475a surface1
+  text:      `${ESC}[38;2;205;214;244m`, // #cdd6f4 catppuccin text
+  subtext:   `${ESC}[38;2;166;173;200m`, // #a6adc8 subtext0
+  overlay:   `${ESC}[38;2;108;112;134m`, // #6c7086 overlay0
+  blue:      `${ESC}[38;2;137;180;250m`, // #89b4fa blue
+  yellow:    `${ESC}[38;2;249;226;175m`, // #f9e2af yellow
+  red:       `${ESC}[38;2;243;139;168m`, // #f38ba8 red (truecolor)
+  surface0:  `${ESC}[38;2;49;50;68m`,    // #313244 surface0
+};
+
+// ── badge 헬퍼 ──
+// statusBadge(status) → ANSI 색상 문자열
+export function statusBadge(status) {
+  switch (status) {
+    case "ok":
+    case "completed":
+    case "done":
+      return `${MOCHA.ok}✓ ${status}${RESET}`;
+    case "partial":
+    case "in_progress":
+    case "running":
+      return `${MOCHA.partial}◑ ${status}${RESET}`;
+    case "fail":
+    case "failed":
+    case "error":
+      return `${MOCHA.fail}✗ ${status}${RESET}`;
+    case "thinking":
+      return `${MOCHA.thinking}⠿ ${status}${RESET}`;
+    case "executing":
+      return `${MOCHA.executing}▶ ${status}${RESET}`;
+    default:
+      return `${FG.muted}· ${status}${RESET}`;
+  }
 }
 
 // ── 진행률 바 ──
-export function progressBar(ratio, width = 20) {
-  const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+// progressBar(percent, width) — percent: 0~100, ANSI colored bar string 반환
+export function progressBar(percent, width = 20) {
+  const ratio = Math.max(0, Math.min(100, percent)) / 100;
+  const filled = Math.round(ratio * width);
   const empty = width - filled;
-  return `${FG.accent}${"█".repeat(filled)}${FG.muted}${"░".repeat(empty)}${RESET}`;
+  const fillColor = percent >= 100 ? MOCHA.ok : percent >= 50 ? MOCHA.partial : MOCHA.fail;
+  return `${fillColor}${"█".repeat(filled)}${MOCHA.border}${"░".repeat(empty)}${RESET}`;
 }
 
 // ── 상태 아이콘 ──
 export const STATUS_ICON = {
-  running:   `${FG.blue}⏳${RESET}`,
-  completed: `${FG.green}✓${RESET}`,
-  failed:    `${FG.red}✗${RESET}`,
+  running:   `${MOCHA.partial}⏳${RESET}`,
+  completed: `${MOCHA.ok}✓${RESET}`,
+  failed:    `${MOCHA.fail}✗${RESET}`,
   pending:   `${FG.gray}⏸${RESET}`,
 };
 

package/hub/team/backend.mjs

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

package/hub/team/cli/commands/start/index.mjs

@@ -16,6 +16,7 @@ function printStartUsage() {
   console.log(`  사용법: ${WHITE}tfx multi "작업 설명"${RESET}`);
   console.log(`          ${WHITE}tfx multi --agents codex,gemini --lead claude "작업"${RESET}`);
   console.log(`          ${WHITE}tfx multi --teammate-mode headless "작업"${RESET} ${DIM}(psmux 헤드리스, 기본)${RESET}`);
+  console.log(`          ${WHITE}tfx multi --dashboard-layout auto "작업"${RESET} ${DIM}(dashboard viewer 레이아웃 자동)${RESET}`);
   console.log(`          ${WHITE}tfx multi --teammate-mode wt "작업"${RESET} ${DIM}(Windows Terminal split-pane)${RESET}`);
   console.log(`          ${WHITE}tfx multi --teammate-mode in-process "작업"${RESET} ${DIM}(mux 불필요)${RESET}\n`);
 }
@@ -38,7 +39,7 @@ function renderTmuxInstallHelp() {
 export { parseTeamArgs };
 
 export async function teamStart(args = []) {
-  const { agents, lead, layout, teammateMode, task: rawTask, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile, model } = parseTeamArgs(args);
+  const { agents, lead, layout, teammateMode, task: rawTask, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, dashboardLayout, dashboardSize, mcpProfile, model } = parseTeamArgs(args);
   // --assign 사용 시 task를 자동 생성
   const task = rawTask || (assigns.length > 0 ? assigns.map(a => a.prompt).join(" + ") : "");
   if (!task) return printStartUsage();
@@ -82,7 +83,7 @@ export async function teamStart(args = []) {
   const state = effectiveMode === "in-process"
     ? await startInProcessTeam({ sessionId, task, lead, agents, subtasks, hubUrl })
     : effectiveMode === "headless"
-      ? await startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile, model })
+      ? await startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, dashboardLayout, dashboardSize, mcpProfile, model })
       : effectiveMode === "wt"
         ? await startWtTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl })
         : await startMuxTeam({ sessionId, task, lead, agents, subtasks, layout, hubUrl, teammateMode: effectiveMode });

package/hub/team/cli/commands/start/parse-args.mjs

@@ -1,4 +1,5 @@
 import { normalizeLayout, normalizeTeammateMode } from "../../services/runtime-mode.mjs";
+import { parseDashboardLayout } from "../../../dashboard-layout.mjs";
 
 // --assign 파싱 시 마지막 콜론 뒤를 role로 인식할 알려진 역할/CLI 이름
 const KNOWN_ROLES = new Set([
@@ -47,6 +48,8 @@ export function parseTeamArgs(args = []) {
   let timeoutSec = 300;
   let verbose = false;
   let dashboard = true;
+  let dashboardLayout = "single";
+  let dashboardSize = 0.40;
   let mcpProfile = "";
   let model = "";
 
@@ -73,6 +76,10 @@ export function parseTeamArgs(args = []) {
       dashboard = true;
     } else if (current === "--no-dashboard") {
       dashboard = false;
+    } else if (current === "--dashboard-layout" && args[index + 1]) {
+      dashboardLayout = parseDashboardLayout(args[++index]);
+    } else if (current === "--dashboard-size" && args[index + 1]) {
+      dashboardSize = Math.min(0.8, Math.max(0.2, parseFloat(args[++index]) || 0.50));
     } else if (current === "--no-progressive") {
       progressive = false;
     } else if (current === "--timeout" && args[index + 1]) {
@@ -100,6 +107,8 @@ export function parseTeamArgs(args = []) {
     timeoutSec,
     verbose,
     dashboard,
+    dashboardLayout,
+    dashboardSize,
     mcpProfile,
     model,
   };

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

@@ -4,7 +4,7 @@ import { ok, warn } from "../../render.mjs";
 import { buildTasks } from "../../services/task-model.mjs";
 import { clearTeamState } from "../../services/state-store.mjs";
 
-export async function startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, mcpProfile, model }) {
+export async function startHeadlessTeam({ sessionId, task, lead, agents, subtasks, layout, assigns, autoAttach, progressive, timeoutSec, verbose, dashboard, dashboardLayout, dashboardSize, mcpProfile, model }) {
   // --assign이 있으면 그것을 사용, 없으면 agents+subtasks 조합
   const assignments = assigns && assigns.length > 0
     ? assigns.map((a, i) => ({ cli: resolveCliType(a.cli), prompt: a.prompt, role: a.role || `worker-${i + 1}`, mcp: mcpProfile, model }))
@@ -18,6 +18,8 @@ export async function startHeadlessTeam({ sessionId, task, lead, agents, subtask
     layout,
     autoAttach: !!autoAttach,
     dashboard: !!dashboard,
+    dashboardLayout,
+    dashboardSize: dashboardSize ?? 0.50,
     progressive: progressive !== false,
     progressIntervalSec: verbose ? 10 : 0,
     onProgress: verbose ? function onProgress(event) {
@@ -73,8 +75,9 @@ export async function startHeadlessTeam({ sessionId, task, lead, agents, subtask
     }
   }
 
-  // dashboard 모드: tui-viewer가 최종 상태를 캡처할 시간 확보
-  if (dashboard) await new Promise(r => setTimeout(r, 2000));
+  // dashboard 모드: tui-viewer가 최종 상태를 렌더링할 시간 확보
+  // WT pane spawn (~1s) + node 기동 (~500ms) + 첫 폴링 (~500ms) + 렌더 여유
+  if (dashboard) await new Promise(r => setTimeout(r, 5000));
 
   // 세션 정리
   handle.kill();

package/hub/team/cli/help.mjs

@@ -11,6 +11,8 @@ export function renderTeamHelp() {
     ${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 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 --teammate-mode in-process "작업"${RESET} ${DIM}(tmux 불필요)${RESET}
 
   ${BOLD}제어${RESET}

package/hub/team/dashboard-layout.mjs

@@ -0,0 +1,31 @@
+const USER_DASHBOARD_LAYOUTS = new Set([
+  "single",
+  "split-2col",
+  "split-3col",
+  "auto",
+]);
+
+const DASHBOARD_LAYOUTS = new Set([
+  ...USER_DASHBOARD_LAYOUTS,
+  "summary+detail",
+]);
+
+export function normalizeDashboardLayout(value, { allowAuto = true } = {}) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!normalized) return "single";
+  if (normalized === "auto" && !allowAuto) return "single";
+  return DASHBOARD_LAYOUTS.has(normalized) ? normalized : "single";
+}
+
+export function parseDashboardLayout(value) {
+  return normalizeDashboardLayout(value, { allowAuto: true });
+}
+
+export function resolveDashboardLayout(value, workerCount = 0) {
+  const normalized = normalizeDashboardLayout(value, { allowAuto: true });
+  if (normalized !== "auto") return normalized;
+  if (workerCount >= 4) return "summary+detail";
+  if (workerCount === 3) return "split-3col";
+  if (workerCount === 2) return "split-2col";
+  return "single";
+}