triflux 10.25.0 → 10.25.1

package/bin/triflux.mjs

@@ -4670,6 +4670,68 @@ async function cmdDoctor(options = {}) {
       }
     }
 
+    // ── MCP Gateway Health ──
+    // install-mcp-gateway-startup 으로 띄운 LaunchAgent/systemd daemon 의 stdout
+    // (~/.local/state/triflux/mcp-gateway.out.log) 를 파싱해 missing-env 등으로
+    // skip 된 server 를 잡는다. 로그가 없으면 gateway 미설치/미실행으로 침묵.
+    section("MCP Gateway Health");
+    {
+      const { checkMcpGatewayHealth, summarizeMcpGatewayHealth } = await import(
+        "../scripts/lib/mcp-gateway-health-check.mjs"
+      );
+      const gatewayHealth = checkMcpGatewayHealth();
+      const summary = summarizeMcpGatewayHealth(gatewayHealth);
+      addDoctorCheck(report, {
+        name: "mcp-gateway-health",
+        status: summary.level === "warn" ? "warning" : "ok",
+        log_path: gatewayHealth.logPath,
+        findings: gatewayHealth.findings,
+        started: gatewayHealth.started,
+        skipped: gatewayHealth.skipped,
+        ...(summary.fix ? { fix: summary.fix } : {}),
+      });
+      if (summary.level === "skip") {
+        info(summary.message);
+      } else if (summary.level === "ok") {
+        ok(summary.message);
+      } else {
+        warn(summary.message);
+        if (summary.fix) info(`수정: ${summary.fix}`);
+        issues++;
+      }
+    }
+
+    // ── MCP Gateway Wrapper ──
+    // 로그가 생기기 전 단계에서 wrapper 자체가 secrets.env 를 source 하는지 확인한다.
+    section("MCP Gateway Wrapper");
+    {
+      const { checkWrapperSourcing } = await import(
+        "../scripts/lib/mcp-gateway-wrapper-check.mjs"
+      );
+      const wrapperCheck = await checkWrapperSourcing();
+      addDoctorCheck(report, {
+        name: "mcp-gateway-wrapper-sourcing",
+        status:
+          wrapperCheck.status === "warn" ? "warning" : wrapperCheck.status,
+        path: wrapperCheck.wrapperPath,
+        ...(wrapperCheck.message ? { message: wrapperCheck.message } : {}),
+        ...(wrapperCheck.suggestedFix
+          ? { fix: wrapperCheck.suggestedFix }
+          : {}),
+      });
+
+      if (wrapperCheck.status === "ok") {
+        ok("wrapper sources secrets.env");
+      } else if (wrapperCheck.status === "warn") {
+        warn(wrapperCheck.message);
+        info(`수정: ${wrapperCheck.suggestedFix}`);
+        issues++;
+      } else {
+        warn("mcp-gateway wrapper not installed");
+        if (wrapperCheck.message) info(wrapperCheck.message);
+      }
+    }
+
     // ── Codex Config Health (BUG-H #132) ──
     // _codex_config_swap 의 restore 가 Windows lock/ACL 로 실패하면
     // ~/.codex/config.toml.pre-exec 가 남아 [mcp_servers.*] 섹션이 영구 손실된다.

package/config/mcp-registry.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "mcp-registry-schema",
+  "version": 1,
+  "description": "MCP 서버 중앙 레지스트리 — 진실의 원천",
+  "defaults": {
+    "transport": "hub-url",
+    "hub_base": "http://127.0.0.1:27888"
+  },
+  "policy_notes": {
+    "policy": "Server policy is the SSOT for client sync shape: hosted writes url+headers, gateway-sse writes http://127.0.0.1:81XX/sse with SSE metadata, and stdio writes command/args/env.",
+    "transport": "Server transport accepts \"hub-url\" for triflux Hub URL flow, \"http\" for direct Streamable HTTP MCP endpoints, or \"stdio\" for upstream-stdio-only MCP servers. Gateway-backed stdio upstreams use policy:\"gateway-sse\" plus gateway_port so clients receive URL/SSE config.",
+    "headers": "Optional headers are allowed only for HTTP-compatible transports. Each header value must be a descriptor: {\"value\":\"literal\"} for non-secret static values, {\"env\":\"ENV_VAR_NAME\"} for secrets resolved at sync/runtime, or {\"env\":\"ENV_VAR_NAME\",\"prefix\":\"Bearer \"} for common authorization formats.",
+    "secret_safety": "Resolved secret values must not be written back to this registry file. Missing env vars warn during sync and do not emit empty secret headers.",
+    "sync_denylist": "Array of client:server strings skipped by proactive registry sync, for example gemini:tfx-hub."
+  },
+  "servers": {
+    "tfx-hub": {
+      "policy": "hosted",
+      "transport": "hub-url",
+      "url": "http://127.0.0.1:27888/mcp",
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "triflux Hub MCP 서버"
+    },
+    "context7": {
+      "policy": "hosted",
+      "transport": "http",
+      "url": "https://mcp.context7.com/mcp",
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "Upstash Context7 — 라이브러리 문서/코드 컨텍스트 (HTTP MCP, API key 불필요)"
+    },
+    "exa": {
+      "policy": "hosted",
+      "transport": "http",
+      "url": "https://mcp.exa.ai/mcp",
+      "headers": {
+        "Authorization": { "env": "EXA_API_KEY", "prefix": "Bearer " }
+      },
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "Exa neural/semantic web search — 학술/기술 깊이. Key 발급: https://exa.ai/dashboard → secrets.env의 EXA_API_KEY"
+    },
+    "serena": {
+      "policy": "gateway-sse",
+      "gateway_port": 8105,
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "Serena MCP — supergateway singleton SSE endpoint (:8105)"
+    },
+    "brave-search": {
+      "policy": "gateway-sse",
+      "gateway_port": 8101,
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "Brave Search MCP — supergateway singleton SSE endpoint (:8101). BRAVE_API_KEY 환경변수 필요 (https://brave.com/search/api/). secrets.env 의 BRAVE_API_KEY 참조."
+    },
+    "tavily": {
+      "policy": "hosted",
+      "transport": "http",
+      "url": "https://mcp.tavily.com/mcp",
+      "headers": {
+        "Authorization": { "env": "TAVILY_API_KEY", "prefix": "Bearer " }
+      },
+      "safe": true,
+      "targets": ["claude", "gemini", "codex", "antigravity"],
+      "description": "Tavily research — 비용/운영/DX/일반 웹. Key 발급: https://app.tavily.com/home → secrets.env의 TAVILY_API_KEY"
+    }
+  },
+  "policies": {
+    "stdio_action": "replace-with-hub",
+    "unknown_server_action": "warn",
+    "sync_denylist": [],
+    "watched_paths": [
+      "~/.gemini/settings.json",
+      "~/.codex/config.toml",
+      "~/.claude.json",
+      "~/.claude/settings.json",
+      "~/.claude/settings.local.json",
+      ".claude/mcp.json",
+      ".mcp.json",
+      "~/.gemini/config/mcp_config.json"
+    ]
+  }
+}

package/config/routing-policy.json

@@ -0,0 +1,124 @@
+{
+  "version": 1,
+  "freshness": {
+    "max_snapshot_age_ms": 900000,
+    "max_cross_provider_skew_ms": 300000,
+    "local_clock_skew_guard_ms": 60000
+  },
+  "thresholds": {
+    "reset_imminent_ms": 86400000,
+    "exhaustion_high_percent": 80,
+    "exhaustion_low_percent": 20,
+    "expiry_drain_window_ms": 604800000,
+    "drain_usage_ceiling_percent": 50
+  },
+  "scenarios": [
+    {
+      "id": "S1",
+      "name": "claude-reset-imminent-drain",
+      "when": {
+        "provider": "claude",
+        "weeklyResetsAtLteMs": 86400000,
+        "weeklyPercentLt": 100,
+        "hasMultipleAccounts": true
+      },
+      "then": {
+        "lane": "multi",
+        "primary_cli": "claude",
+        "reserve_codex_share": 0.1,
+        "reason": "claude-weekly-reset-imminent-drain-fleet"
+      }
+    },
+    {
+      "id": "S2",
+      "name": "codex-reset-imminent-drain",
+      "when": {
+        "provider": "codex",
+        "weeklyResetsAtLteMs": 86400000,
+        "weeklyPercentLt": 100
+      },
+      "then": {
+        "lane": "swarm",
+        "primary_cli": "codex",
+        "reserve_claude_share": 0.1,
+        "reason": "codex-weekly-reset-imminent-drain-fleet"
+      }
+    },
+    {
+      "id": "S3",
+      "name": "claude-burned-codex-fresh",
+      "when": {
+        "claude_weekly_percent_gte": 80,
+        "codex_weekly_percent_lt": 20,
+        "claude_weekly_resets_at_gt_ms": 172800000
+      },
+      "then": {
+        "lane": "single",
+        "primary_cli": "codex",
+        "claude_lanes_allowed": ["explore", "final-challenge"],
+        "reason": "claude-burned-codex-fresh-rebalance"
+      }
+    },
+    {
+      "id": "S4",
+      "name": "claude-multi-account-staggered",
+      "when": {
+        "provider": "claude",
+        "accountCountGte": 2,
+        "staggered": true
+      },
+      "then": {
+        "lane": "multi",
+        "primary_cli": "claude",
+        "rank_by": "expiring_capacity_score",
+        "reason": "claude-multi-account-staggered-reset"
+      }
+    },
+    {
+      "id": "S5",
+      "name": "claude-parallel-leasemany",
+      "when": {
+        "provider": "claude",
+        "request_team_size_gte": 2,
+        "accountCountGte": 2
+      },
+      "then": {
+        "lane": "swarm",
+        "primary_cli": "claude",
+        "atomic": "leaseMany",
+        "atomic_policy": "balanced",
+        "reason": "claude-parallel-multi-account"
+      }
+    },
+    {
+      "id": "S6",
+      "name": "account-expiry-drain",
+      "when": {
+        "expiresAtLteMs": 604800000,
+        "weeklyPercentLt": 50,
+        "circuitStateNotOpen": true
+      },
+      "then": {
+        "lane": "single",
+        "riskTier": "drain",
+        "elevated_weight": 2.0,
+        "reason": "account-expiry-drain-before-loss"
+      }
+    }
+  ],
+  "fallback": {
+    "default_mode": "codex-default",
+    "default_cli": "codex",
+    "default_model": "gpt-5.5",
+    "triggers": [
+      "hud_null",
+      "hud_stale_gte_15min",
+      "weekly_reset_in_past",
+      "cross_provider_skew_exceeded",
+      "broker_empty",
+      "all_circuits_open",
+      "mirror_drift",
+      "flag_disabled"
+    ]
+  }
+}

package/hooks/safety-guard.mjs

@@ -340,7 +340,14 @@ function main() {
     return hasSegmentInvocation(cmd, WT_DIRECT_PATTERNS);
   }
 
-  if (isWtDirectInvocation(command)) {
+  // wt.exe는 Windows Terminal 전용. macOS/Linux에서는 PATH에 존재하지 않아
+  // 차단해도 dormant이며, 문서/로그 텍스트의 wt 단어가 false positive로 잡힐
+  // 위험만 있다. win32에서만 차단 적용.
+  // SAFETY_GUARD_FORCE_PLATFORM env로 테스트에서 platform 시뮬레이션 가능
+  // (mac CI에서 win32 차단 동작을 검증하기 위함).
+  const guardPlatform =
+    process.env.SAFETY_GUARD_FORCE_PLATFORM || process.platform;
+  if (guardPlatform === "win32" && isWtDirectInvocation(command)) {
     blockCommand(WT_DIRECT_BLOCK_MESSAGE, command);
   }
 

package/hub/team/claude-daemon-control.mjs

@@ -133,6 +133,23 @@ export function findDaemonJobByShort(listResponse, short) {
   return listResponse.jobs.find((job) => job?.short === short) || null;
 }
 
+export function findDaemonJobBySessionId(listResponse, sessionId) {
+  if (!Array.isArray(listResponse?.jobs)) return null;
+  const expected = String(sessionId || "");
+  if (!expected) return null;
+  return (
+    listResponse.jobs.find((job) => {
+      const candidate =
+        job?.sessionId ??
+        job?.session_id ??
+        job?.dispatch?.sessionId ??
+        job?.d?.sessionId ??
+        "";
+      return String(candidate) === expected;
+    }) || null
+  );
+}
+
 export async function waitForDaemonJobPid(
   controlSock,
   short,
@@ -158,3 +175,45 @@ export async function killDaemonJob(controlSock, short) {
     short,
   });
 }
+
+export async function sendKillBySessionId({
+  daemonPaths,
+  sessionId,
+  timeoutMs = 6000,
+} = {}) {
+  const controlSock = daemonPaths?.controlSock;
+  if (!controlSock || !sessionId) {
+    return { ok: true, killed: false, reason: "missing_target" };
+  }
+
+  try {
+    const list = await sendClaudeControlRequest(
+      controlSock,
+      {
+        proto: 1,
+        op: "list",
+      },
+      { timeoutMs },
+    );
+    const job = findDaemonJobBySessionId(list, sessionId);
+    if (!job?.short) {
+      return { ok: true, killed: false, reason: "not_found" };
+    }
+    return await sendClaudeControlRequest(
+      controlSock,
+      {
+        proto: 1,
+        op: "kill",
+        short: job.short,
+      },
+      { timeoutMs },
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      killed: false,
+      reason: "control_unavailable",
+      error: error?.message || String(error),
+    };
+  }
+}

package/hub/team/claude-native-bridge.mjs

@@ -4,6 +4,17 @@ import fs from "node:fs/promises";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import {
+  buildDaemonExecDispatchPayload,
+  killDaemonJob,
+  sendClaudeControlRequest,
+  waitForDaemonJobPid,
+} from "./claude-daemon-control.mjs";
+import {
+  buildClaudeSessionProjection,
+  removeClaudeSessionProjection,
+  writeClaudeSessionProjection,
+} from "./claude-session-projection.mjs";
 
 const DEFAULT_ROWS = 40;
 const DEFAULT_COLS = 120;
@@ -36,6 +47,8 @@ export function deriveClaudeDaemonPaths({
     rendezvousDir: path.join(daemonDir, "rv"),
     ptyDir: path.join(daemonDir, "pty"),
     rosterPath: path.join(resolvedConfigDir, "daemon", "roster.json"),
+    sessionsDir: path.join(resolvedConfigDir, "sessions"),
+    jobsDir: path.join(resolvedConfigDir, "jobs"),
   };
 }
 
@@ -203,6 +216,204 @@ export async function removeRosterWorkers(rosterPath, shorts) {
   });
 }
 
+export async function removeClaudeJobState(jobsDir, short) {
+  if (!short) return;
+  await fs.rm(path.join(jobsDir, short), { recursive: true, force: true });
+}
+
+function shellSingleQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function buildSwarmShardBridgeCommand({ displayName, sessionId }) {
+  const banner = `${displayName} native bridge active (${sessionId})`;
+  return `printf '%s\\n' ${shellSingleQuote(banner)}; while true; do sleep 3600; done`;
+}
+
+function compactDisplayPart(value, fallback = "") {
+  const text = String(value ?? "")
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text || fallback;
+}
+
+function toPositiveInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : null;
+}
+
+function formatShardOrdinal({ shardIndex, shardCount }) {
+  const index = toPositiveInteger(shardIndex);
+  const count = toPositiveInteger(shardCount);
+  if (!index || !count) return null;
+  const width = Math.max(String(count).length, 2);
+  return `${String(index).padStart(width, "0")}/${String(count).padStart(width, "0")}`;
+}
+
+function buildSwarmShardDisplayName({
+  sessionId,
+  cli,
+  swarmName,
+  shardIndex,
+  shardCount,
+  shardName,
+}) {
+  const groupName = compactDisplayPart(swarmName || sessionId, "swarm");
+  const agentName = compactDisplayPart(cli, "agent");
+  const workerName = compactDisplayPart(shardName, "shard");
+  return [
+    "Triflux swarm",
+    groupName,
+    formatShardOrdinal({ shardIndex, shardCount }),
+    agentName,
+    workerName,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isLocalHost(host) {
+  const value = String(host || "local").toLowerCase();
+  return value === "local" || value === "localhost" || value === "127.0.0.1";
+}
+
+function deriveSwarmShort({ sessionId, shardName, host }) {
+  return crypto
+    .createHash("sha256")
+    .update(`${sessionId}:${shardName}:${host || "local"}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+export async function registerSwarmShard({
+  sessionId,
+  cli = "codex",
+  role = "worker",
+  swarmName,
+  shardIndex,
+  shardCount,
+  shardName,
+  cwd = process.cwd(),
+  host = "local",
+  configDir = resolveClaudeConfigDir(),
+  tmpRoot = "/tmp",
+  _deps = {},
+} = {}) {
+  if (!sessionId) throw new Error("sessionId is required");
+  if (!shardName) throw new Error("shardName is required");
+
+  const displayName = buildSwarmShardDisplayName({
+    sessionId,
+    cli,
+    swarmName,
+    shardIndex,
+    shardCount,
+    shardName,
+  });
+  const warn = _deps.warn || ((message) => console.warn(message));
+  if (!isLocalHost(host)) {
+    warn(
+      `[native-bridge] remote shard ${shardName}@${host}: skipping local registration; remote launcher must register on that host`,
+    );
+    return {
+      ok: true,
+      skipped: true,
+      host,
+      sessionId,
+      shardName,
+      displayName,
+      close() {},
+    };
+  }
+
+  const derivePaths = _deps.deriveClaudeDaemonPaths || deriveClaudeDaemonPaths;
+  const buildPayload =
+    _deps.buildDaemonExecDispatchPayload || buildDaemonExecDispatchPayload;
+  const sendControl =
+    _deps.sendClaudeControlRequest || sendClaudeControlRequest;
+  const waitForPid = _deps.waitForDaemonJobPid || waitForDaemonJobPid;
+  const readProcStart = _deps.getProcStart || getProcStart;
+  const buildProjection =
+    _deps.buildClaudeSessionProjection || buildClaudeSessionProjection;
+  const writeProjection =
+    _deps.writeClaudeSessionProjection || writeClaudeSessionProjection;
+  const removeProjection =
+    _deps.removeClaudeSessionProjection || removeClaudeSessionProjection;
+  const removeJobStateImpl = _deps.removeClaudeJobState || removeClaudeJobState;
+  const killJob = _deps.killDaemonJob || killDaemonJob;
+  const accessControlSock = _deps.accessControlSock || fs.access;
+
+  const paths = derivePaths({ configDir, tmpRoot });
+  const sessionsDir =
+    paths.sessionsDir || path.join(paths.configDir || configDir, "sessions");
+  const jobsDir =
+    paths.jobsDir || path.join(paths.configDir || configDir, "jobs");
+  const short = deriveSwarmShort({ sessionId, shardName, host });
+  const command = buildSwarmShardBridgeCommand({ displayName, sessionId });
+  const payload = buildPayload({
+    short,
+    cwd,
+    command,
+    name: displayName,
+  });
+
+  await accessControlSock(paths.controlSock);
+  const dispatch = await sendControl(
+    paths.controlSock,
+    {
+      proto: 1,
+      op: "dispatch",
+      d: payload,
+      timeoutMs: 1000,
+    },
+    { timeoutMs: 1000 },
+  );
+  if (dispatch?.ok !== true) {
+    throw new Error(
+      `Claude daemon dispatch failed for swarm shard ${shardName}`,
+    );
+  }
+
+  const job = await waitForPid(paths.controlSock, short, { timeoutMs: 1000 });
+  const pid = job.pid;
+  const projection = buildProjection({
+    pid,
+    procStart: readProcStart(pid),
+    sessionId: payload.sessionId,
+    short,
+    cwd,
+    name: displayName,
+    agent: cli,
+    startedAt: job.startedAt || Date.now(),
+    updatedAt: Date.now(),
+  });
+  const sessionProjectionPath = await writeProjection(sessionsDir, projection);
+  let closed = false;
+
+  return {
+    ok: true,
+    skipped: false,
+    host: "local",
+    sessionId: payload.sessionId,
+    swarmSessionId: sessionId,
+    shardName,
+    cli,
+    role,
+    short,
+    displayName,
+    controlSock: paths.controlSock,
+    sessionProjectionPath,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await removeProjection(sessionProjectionPath).catch(() => {});
+      await killJob(paths.controlSock, short).catch(() => {});
+      await removeJobStateImpl(jobsDir, short).catch(() => {});
+    },
+  };
+}
+
 export function buildNativeWorkerRosterEntry({
   short,
   pid = process.pid,

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

@@ -96,6 +96,7 @@ export async function teamStart(args = []) {
     cwd,
     nativeBridge,
     nativeBridgeMode,
+    nativeBridgeUiOptOut,
   } = parseTeamArgs(args);
   // --assign 사용 시 task를 자동 생성
   const task =
@@ -133,6 +134,8 @@ export async function teamStart(args = []) {
   const { mode: effectiveMode, warnings: modeWarnings } =
     resolveEffectiveMode(teammateMode);
   for (const message of modeWarnings) warn(message);
+  const effectiveNativeBridge =
+    effectiveMode === "headless" && !nativeBridgeUiOptOut ? true : nativeBridge;
 
   console.log(`  세션:  ${WHITE}${sessionId}${RESET}`);
   console.log(`  모드:  ${effectiveMode}`);
@@ -180,7 +183,7 @@ export async function teamStart(args = []) {
             mcpProfile,
             model,
             cwd,
-            nativeBridge,
+            nativeBridge: effectiveNativeBridge,
             nativeBridgeMode,
           })
         : effectiveMode === "wt"

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

@@ -77,7 +77,10 @@ export function parseTeamArgs(args = []) {
   let model = "";
   let cwd = "";
   let nativeBridge = false;
-  let nativeBridgeMode = "roster";
+  let nativeBridgeMode = "agents";
+  let nativeBridgeExplicit = false;
+  let nativeBridgeUiRequested = false;
+  let nativeBridgeUiOptOut = false;
 
   for (let index = 0; index < args.length; index += 1) {
     const current = args[index];
@@ -127,9 +130,25 @@ export function parseTeamArgs(args = []) {
       model = args[++index].trim();
     } else if (current === "--native-bridge" || current === "-nb") {
       nativeBridge = true;
+      nativeBridgeExplicit = true;
     } else if (current === "--native-bridge-ui") {
+      if (nativeBridgeUiOptOut) {
+        throw new Error(
+          "cannot combine --native-bridge-ui and --no-native-bridge-ui",
+        );
+      }
       nativeBridge = true;
       nativeBridgeMode = "agents";
+      nativeBridgeExplicit = true;
+      nativeBridgeUiRequested = true;
+    } else if (current === "--no-native-bridge-ui") {
+      if (nativeBridgeUiRequested) {
+        throw new Error(
+          "cannot combine --native-bridge-ui and --no-native-bridge-ui",
+        );
+      }
+      nativeBridge = false;
+      nativeBridgeUiOptOut = true;
     } else if (current === "--native-bridge-mode") {
       const mode = args[++index];
       if (!NATIVE_BRIDGE_MODES.has(mode)) {
@@ -139,6 +158,7 @@ export function parseTeamArgs(args = []) {
       }
       nativeBridge = true;
       nativeBridgeMode = mode;
+      nativeBridgeExplicit = true;
     } else if (current === "--cwd" && args[index + 1]) {
       let p = args[++index].trim();
       // MSYS/Git Bash 드라이브 문자 변환: /c/... → C:/...
@@ -153,11 +173,20 @@ export function parseTeamArgs(args = []) {
     }
   }
 
+  const normalizedTeammateMode = normalizeTeammateMode(teammateMode);
+  if (
+    !nativeBridgeExplicit &&
+    !nativeBridgeUiOptOut &&
+    normalizedTeammateMode === "headless"
+  ) {
+    nativeBridge = true;
+  }
+
   return {
     agents,
     lead,
     layout: normalizeLayout(layout),
-    teammateMode: normalizeTeammateMode(teammateMode),
+    teammateMode: normalizedTeammateMode,
     task: taskParts.join(" ").trim(),
     assigns,
     autoAttach,
@@ -173,5 +202,6 @@ export function parseTeamArgs(args = []) {
     cwd,
     nativeBridge,
     nativeBridgeMode,
+    nativeBridgeUiOptOut,
   };
 }