@triflux/remote 10.25.1 → 10.26.0

package/hub/team/headless.mjs

@@ -18,7 +18,8 @@ import {
 import { createRequire } from "node:module";
 import net from "node:net";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { requestJson } from "@triflux/core/hub/bridge.mjs";
 import { escapePwshSingleQuoted } from "@triflux/core/hub/cli-adapter-base.mjs";
 import { getMaxSpawnPerSec } from "@triflux/core/hub/lib/spawn-trace.mjs";
@@ -28,8 +29,9 @@ import {
   buildDaemonExecDispatchPayload,
   deriveClaudeDaemonPaths as deriveClaudeControlPaths,
   killDaemonJob,
-  sendKillBySessionId,
+  resolveDaemonBridgeSessionId,
   sendClaudeControlRequest,
+  sendKillBySessionId,
   waitForDaemonJobPid,
 } from "./claude-daemon-control.mjs";
 import {
@@ -67,11 +69,17 @@ import { createWtManager } from "./wt-manager.mjs";
 
 const RESULT_DIR = join(tmpdir(), "tfx-headless");
 const DAEMON_COMPLETION_PREFIX = "__TFX_HEADLESS_DONE__:";
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 
 /** CLI별 브랜드 — 이모지 + 공식 색상 (HUD와 통일) */
 const CLI_BRAND = {
   codex: { emoji: "\u{26AA}", label: "Codex", ansi: "\x1b[97m" }, // ⚪ bright white (codexWhite)
   gemini: { emoji: "\u{1F535}", label: "Gemini", ansi: "\x1b[38;5;39m" }, // 🔵 geminiBlue
+  antigravity: {
+    emoji: "\u{1F535}",
+    label: "Antigravity",
+    ansi: "\x1b[38;5;39m",
+  },
   claude: {
     emoji: "\u{1F7E0}",
     label: "Claude",
@@ -84,17 +92,109 @@ const _ANSI_DIM = "\x1b[2m";
 /** 에이전트 역할명 → CLI 타입 매핑 (단일 소스: agent-map.json) */
 const _require = createRequire(import.meta.url);
 const AGENT_TO_CLI = _require("./agent-map.json");
+// scripts/tfx-route.sh also validates route agents from agent-map.json.
+const VALID_ROUTE_AGENTS = new Set(Object.keys(AGENT_TO_CLI));
 
 /**
- * 에이전트 역할명 또는 CLI 이름을 CLI 타입("codex"|"gemini"|"claude")으로 해석한다.
+ * 에이전트 역할명 또는 CLI 이름을 CLI 타입("codex"|"antigravity"|"claude")으로 해석한다.
  * route_agent()가 적용되지 않는 headless 경로에서 사용.
  * @param {string} agentOrCli — "executor", "codex", "designer" 등
- * @returns {'codex'|'gemini'|'claude'} CLI 타입
+ * @returns {'codex'|'antigravity'|'claude'} CLI 타입
  */
 export function resolveCliType(agentOrCli) {
   return AGENT_TO_CLI[agentOrCli] || agentOrCli;
 }
 
+function resolveHeadlessCliType(agentOrCli) {
+  const resolved = resolveCliType(agentOrCli);
+  return resolved === "gemini" ? "antigravity" : resolved;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function resolveHeadlessRouteScript(opts = {}) {
+  const candidates = [
+    opts.routeScript,
+    process.env.TFX_ROUTE_SCRIPT,
+    process.env.TFX_DELEGATOR_ROUTE_SCRIPT,
+    join(process.cwd(), "scripts", "tfx-route.sh"),
+    join(SCRIPT_DIR, "..", "..", "scripts", "tfx-route.sh"),
+    process.env.HOME
+      ? join(process.env.HOME, ".claude", "scripts", "tfx-route.sh")
+      : "",
+    "tfx-route.sh",
+  ];
+
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (candidate === "tfx-route.sh" || existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return "tfx-route.sh";
+}
+
+function resolveRouteAgentForHeadless(resolvedCli, opts = {}) {
+  const role = String(opts.role || "").trim();
+  if (
+    role &&
+    VALID_ROUTE_AGENTS.has(role) &&
+    !["gemini", "antigravity", "agy"].includes(role)
+  ) {
+    return role;
+  }
+  return resolvedCli === "antigravity" ? "antigravity" : resolvedCli;
+}
+
+export function normalizeHeadlessRole(role) {
+  const normalized = String(role || "")
+    .trim()
+    .toLowerCase();
+  return normalized && VALID_ROUTE_AGENTS.has(normalized) ? normalized : "";
+}
+
+export function resolveHeadlessDisplayName(assignment = {}, paneName = "") {
+  const normalized = String(assignment.displayName || "")
+    .trim()
+    .replace(/[\r\n\x00-\x1f]/g, " ");
+  return normalized || paneName || "";
+}
+
+export function normalizeHeadlessAssignment(assignment = {}, index = 0) {
+  const paneName = `worker-${index + 1}`;
+  return {
+    ...assignment,
+    role: normalizeHeadlessRole(assignment.role),
+    displayName: resolveHeadlessDisplayName(assignment, paneName),
+  };
+}
+
+function buildRouteBackedHeadlessCommand(
+  resolvedCli,
+  promptFile,
+  resultFile,
+  opts = {},
+) {
+  const routeScript = resolveHeadlessRouteScript(opts);
+  const routeAgent = resolveRouteAgentForHeadless(resolvedCli, opts);
+  const mcp = String(opts.mcp || "auto");
+  const timeout =
+    Number.isFinite(Number(opts.timeoutSec)) && Number(opts.timeoutSec) > 0
+      ? String(Math.trunc(Number(opts.timeoutSec)))
+      : "";
+  const timeoutArg = timeout ? ` ${shellQuote(timeout)}` : "";
+  const routeMode = resolvedCli === "antigravity" ? "antigravity" : resolvedCli;
+  const script =
+    `__tfx_prompt=$(cat ${shellQuote(promptFile)}); ` +
+    `TFX_CLI_MODE=${shellQuote(routeMode)} ` +
+    `bash ${shellQuote(routeScript)} ${shellQuote(routeAgent)} "$__tfx_prompt" ${shellQuote(mcp)}${timeoutArg} ` +
+    `> ${shellQuote(resultFile)} 2>${shellQuote(`${resultFile}.err`)} < /dev/null`;
+  return `bash -lc ${shellQuote(script)}`;
+}
+
 export function getHeadlessWorkerAgentId(sessionName, index) {
   return `headless-${sessionName}-${index}`;
 }
@@ -173,7 +273,7 @@ const MCP_PROFILE_HINTS = {
 
 /**
  * CLI별 헤드리스 명령 빌더
- * @param {'codex'|'gemini'|'claude'} cli
+ * @param {'codex'|'antigravity'|'claude'} cli
  * @param {string} prompt — 실행할 프롬프트
  * @param {string} resultFile — 결과 저장 파일 경로
  * @param {object} [opts]
@@ -205,7 +305,7 @@ export function buildDashboardAttachArgs(
 
 export function buildHeadlessCommand(cli, prompt, resultFile, opts = {}) {
   const { handoff = true, mcp, contextFile, model, cwd } = opts;
-  const resolvedCli = resolveCliType(cli);
+  const resolvedCli = resolveHeadlessCliType(cli);
 
   // contextFile 처리: 32KB(32768 bytes) 초과 시 UTF-8 안전 절단
   let contextPrefix = "";
@@ -241,12 +341,17 @@ export function buildHeadlessCommand(cli, prompt, resultFile, opts = {}) {
   writeFileSync(promptFile, fullPrompt, "utf8");
   void IS_WINDOWS; // referenced for diagnostic guard chain below
 
-  const backend = getBackend(resolvedCli);
-  const backendCommand = backend.buildArgs(fullPrompt, resultFile, {
-    ...opts,
-    model,
-    promptFile,
-  });
+  const backendCommand =
+    resolvedCli === "antigravity"
+      ? buildRouteBackedHeadlessCommand(resolvedCli, promptFile, resultFile, {
+          ...opts,
+          mcp,
+        })
+      : getBackend(resolvedCli).buildArgs(fullPrompt, resultFile, {
+          ...opts,
+          model,
+          promptFile,
+        });
   const safeCwd =
     typeof cwd === "string" ? cwd.trim().replace(/[\r\n\x00-\x1f]/g, "") : "";
   if (safeCwd && (safeCwd.startsWith("\\\\") || safeCwd.startsWith("//"))) {
@@ -679,16 +784,15 @@ async function dispatchProgressive(sessionName, assignments, opts = {}) {
   for (let i = 0; i < assignments.length; i++) {
     const assignment = assignments[i];
     const paneName = `worker-${i + 1}`;
+    const displayName = resolveHeadlessDisplayName(assignment, paneName);
     const workerId = getHeadlessWorkerAgentId(sessionName, i);
-    const resolvedCli = resolveCliType(assignment.cli);
+    const resolvedCli = resolveHeadlessCliType(assignment.cli);
     const brand = CLI_BRAND[resolvedCli] || {
       emoji: "\u{25CF}",
       label: resolvedCli,
       ansi: "",
     };
-    const paneTitle = assignment.role
-      ? `${brand.emoji} ${resolvedCli} (${assignment.role})`
-      : `${brand.emoji} ${resolvedCli}-${i + 1}`;
+    const paneTitle = `${brand.emoji} ${resolvedCli} (${displayName})`;
 
     let newPaneId;
     // 모든 워커를 split-window로 생성 (lead pane index 0은 비워둠)
@@ -708,13 +812,14 @@ async function dispatchProgressive(sessionName, assignments, opts = {}) {
     } catch {
       /* 무시 */
     }
-    await registerHeadlessWorker(sessionName, i, assignment.cli);
+    await registerHeadlessWorker(sessionName, i, resolvedCli);
 
     if (safeProgress)
       safeProgress({
         type: "worker_added",
         paneName,
-        cli: assignment.cli,
+        displayName,
+        cli: resolvedCli,
         paneTitle,
       });
 
@@ -731,6 +836,7 @@ async function dispatchProgressive(sessionName, assignments, opts = {}) {
       resultFile,
       {
         mcp: assignment.mcp,
+        role: assignment.role,
         model: assignment.model,
         cwd: assignment.cwd || assignment.workdir,
       },
@@ -742,14 +848,15 @@ async function dispatchProgressive(sessionName, assignments, opts = {}) {
     registerHeadlessSynapseWorker(workerId, assignment.prompt);
 
     if (safeProgress)
-      safeProgress({ type: "dispatched", paneName, cli: assignment.cli });
+      safeProgress({ type: "dispatched", paneName, cli: resolvedCli });
 
     dispatches.push({
       ...dispatch,
       paneId: newPaneId,
       paneName,
+      displayName,
       resultFile,
-      cli: assignment.cli,
+      cli: resolvedCli,
       role: assignment.role,
       command: cmd,
       workerId,
@@ -796,7 +903,9 @@ async function dispatchBatch(sessionName, assignments, opts = {}) {
   return await Promise.all(
     assignments.map(async (assignment, i) => {
       const paneName = `worker-${i + 1}`;
+      const displayName = resolveHeadlessDisplayName(assignment, paneName);
       const workerId = getHeadlessWorkerAgentId(sessionName, i);
+      const resolvedCli = resolveHeadlessCliType(assignment.cli);
       const resultFile = join(
         RESULT_DIR,
         `${sessionName}-${paneName}.txt`,
@@ -809,12 +918,13 @@ async function dispatchBatch(sessionName, assignments, opts = {}) {
         resultFile,
         {
           mcp: assignment.mcp,
+          role: assignment.role,
           model: assignment.model,
           cwd: assignment.cwd || assignment.workdir,
         },
       );
       const scriptDir = join(RESULT_DIR, sessionName);
-      await registerHeadlessWorker(sessionName, i, assignment.cli);
+      await registerHeadlessWorker(sessionName, i, resolvedCli);
       const dispatch = dispatchCommand(sessionName, paneName, cmd, {
         scriptDir,
         scriptName: paneName,
@@ -826,13 +936,19 @@ async function dispatchBatch(sessionName, assignments, opts = {}) {
       // progressive 모드에서는 split-window 시 새 pane에 바로 타이틀이 설정되므로 문제없음
 
       if (safeProgress)
-        safeProgress({ type: "dispatched", paneName, cli: assignment.cli });
+        safeProgress({
+          type: "dispatched",
+          paneName,
+          displayName,
+          cli: resolvedCli,
+        });
 
       return {
         ...dispatch,
         paneName,
+        displayName,
         resultFile,
-        cli: assignment.cli,
+        cli: resolvedCli,
         role: assignment.role,
         command: cmd,
         workerId,
@@ -851,7 +967,9 @@ async function dispatchDaemonBatch(sessionName, assignments, opts = {}) {
     for (let i = 0; i < assignments.length; i += 1) {
       const assignment = assignments[i];
       const paneName = `worker-${i + 1}`;
+      const displayName = resolveHeadlessDisplayName(assignment, paneName);
       const workerId = getHeadlessWorkerAgentId(sessionName, i);
+      const resolvedCli = resolveHeadlessCliType(assignment.cli);
       const resultFile = join(
         RESULT_DIR,
         `${sessionName}-${paneName}.txt`,
@@ -863,18 +981,20 @@ async function dispatchDaemonBatch(sessionName, assignments, opts = {}) {
         resultFile,
         {
           mcp: assignment.mcp,
+          role: assignment.role,
           model: assignment.model,
           cwd: assignment.cwd || assignment.workdir,
         },
       );
       const token = randomUUID().slice(0, 10);
       const short = randomUUID().replace(/-/g, "").slice(0, 8);
-      const name = `Triflux ${assignment.cli || "worker"} ${assignment.role || paneName}`;
+      const name = `Triflux ${resolvedCli || "worker"} ${displayName}`;
       const record = {
         paneId: `daemon:${short}`,
         paneName,
+        displayName,
         resultFile,
-        cli: assignment.cli,
+        cli: resolvedCli,
         role: assignment.role,
         command,
         token,
@@ -909,6 +1029,11 @@ async function dispatchDaemonBatch(sessionName, assignments, opts = {}) {
       }
 
       const job = await waitForDaemonJobPid(paths.controlSock, short);
+      const bridgeSessionId = await resolveDaemonBridgeSessionId({
+        daemonPaths: paths,
+        short,
+        job,
+      });
       const projection = buildClaudeSessionProjection({
         pid: job.pid,
         procStart: getProcStart(job.pid),
@@ -916,18 +1041,19 @@ async function dispatchDaemonBatch(sessionName, assignments, opts = {}) {
         short,
         cwd: assignment.cwd || assignment.workdir || process.cwd(),
         name,
-        agent: assignment.cli || "codex",
+        agent: resolvedCli || "codex",
         startedAt: job.startedAt || Date.now(),
         updatedAt: Date.now(),
+        bridgeSessionId,
       });
       record.sessionProjectionPath = await writeClaudeSessionProjection(
         paths.sessionsDir,
         projection,
       );
-      await registerHeadlessWorker(sessionName, i, assignment.cli);
+      await registerHeadlessWorker(sessionName, i, resolvedCli);
       registerHeadlessSynapseWorker(workerId, assignment.prompt);
       if (safeProgress) {
-        safeProgress({ type: "dispatched", paneName, cli: assignment.cli });
+        safeProgress({ type: "dispatched", paneName, cli: resolvedCli });
       }
     }
   } catch (error) {
@@ -997,6 +1123,7 @@ async function awaitAll(
             safeProgress({
               type: "progress",
               paneName: d.paneName,
+              displayName: d.displayName,
               cli: d.cli,
               snapshot: content.split("\n").slice(-15).join("\n"), // 마지막 15줄
             });
@@ -1015,6 +1142,7 @@ async function awaitAll(
                     safeProgress({
                       type: "progress",
                       paneName: d.paneName,
+                      displayName: d.displayName,
                       cli: d.cli,
                       snapshot: snapshot.split("\n").slice(-15).join("\n"),
                     });
@@ -1092,6 +1220,7 @@ async function awaitAll(
         safeProgress({
           type: "completed",
           paneName: d.paneName,
+          displayName: d.displayName,
           cli: d.cli,
           matched: completion.matched,
           exitCode: completion.exitCode,
@@ -1184,6 +1313,7 @@ async function waitForDaemonCompletion(
             safeProgress({
               type: "progress",
               paneName: dispatch.paneName,
+              displayName: dispatch.displayName,
               cli: dispatch.cli,
               snapshot: message.line.split("\n").slice(-15).join("\n"),
             });
@@ -1220,6 +1350,7 @@ async function awaitAllDaemon(
         safeProgress({
           type: "completed",
           paneName: d.paneName,
+          displayName: d.displayName,
           cli: d.cli,
           matched: completion.matched,
           exitCode: completion.exitCode,
@@ -1276,6 +1407,7 @@ async function collectResults(sessionName, results) {
       return {
         cli: d.cli,
         paneName: d.paneName,
+        displayName: d.displayName,
         paneId: d.paneId,
         workerId: d.workerId,
         role: d.role,
@@ -1337,8 +1469,11 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
   } = opts;
 
   mkdirSync(RESULT_DIR, { recursive: true });
+  const normalizedAssignments = (assignments || []).map((assignment, index) =>
+    normalizeHeadlessAssignment(assignment, index),
+  );
 
-  if (assignments.length === 0) {
+  if (normalizedAssignments.length === 0) {
     return { sessionName, results: [] };
   }
 
@@ -1349,11 +1484,16 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
       "[headless] --native-bridge-mode claude-wrapper is reserved and not implemented yet",
     );
   }
-  if (nativeBridge && nativeBridgeMode === "roster") {
+  if (
+    nativeBridge &&
+    (nativeBridgeMode === "roster" || nativeBridgeMode === "interactive-attach")
+  ) {
     nativeBridgeHandle = await startClaudeNativeBridge({
       sessionName,
-      assignments,
+      assignments: normalizedAssignments,
       cwd: process.cwd(),
+      workerType:
+        nativeBridgeMode === "interactive-attach" ? "interactive" : "headless",
       onKill() {
         try {
           killPsmuxSession(sessionName);
@@ -1381,11 +1521,11 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     .catch(() => {});
 
   // Synapse: 세션 registration (fire-and-forget, hub 미응답 시 무시)
-  const synapseIds = assignments.map(
+  const synapseIds = normalizedAssignments.map(
     (_, i) => `${sessionName}-worker-${i + 1}`,
   );
-  for (let i = 0; i < assignments.length; i++) {
-    const a = assignments[i];
+  for (let i = 0; i < normalizedAssignments.length; i++) {
+    const a = normalizedAssignments[i];
     requestJson("/synapse/register", {
       method: "POST",
       body: {
@@ -1402,7 +1542,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
   let tui = null;
   const resolvedLayout = resolveDashboardLayout(
     dashboardLayout,
-    assignments.length,
+    normalizedAssignments.length,
   );
   if (dashboard && process.stdout.isTTY) {
     tui = createLogDashboard({
@@ -1413,10 +1553,12 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
     });
     tui.setStartTime(Date.now());
     // 초기 워커 상태 등록
-    for (let i = 0; i < assignments.length; i++) {
-      const a = assignments[i];
-      tui.updateWorker(`worker-${i + 1}`, {
-        cli: a.cli || "codex",
+    for (let i = 0; i < normalizedAssignments.length; i++) {
+      const a = normalizedAssignments[i];
+      const paneName = `worker-${i + 1}`;
+      tui.updateWorker(paneName, {
+        cli: resolveHeadlessCliType(a.cli || "codex"),
+        displayName: resolveHeadlessDisplayName(a, paneName),
         role: a.role || "",
         status: "pending",
         progress: 0,
@@ -1437,12 +1579,14 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
   // per-worker state feed: onProgress 이벤트 → tui.updateWorker()
   function feedTui(event) {
     if (!tui) return;
-    const { type, paneName, cli, snapshot, matched, exitCode } = event;
+    const { type, paneName, displayName, cli, snapshot, matched, exitCode } =
+      event;
     if (!paneName) return;
 
     if (type === "progress" && snapshot) {
       tui.updateWorker(paneName, {
         cli: cli || "codex",
+        displayName,
         status: "running",
         snapshot: snapshot.split("\n").at(-1) || "",
         summary: snapshot.split("\n").at(-1) || "",
@@ -1453,12 +1597,14 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
       const status = matched && exitCode === 0 ? "completed" : "failed";
       tui.updateWorker(paneName, {
         cli: cli || "codex",
+        displayName,
         status,
         progress: 1,
       });
     } else if (type === "worker_added") {
       tui.updateWorker(paneName, {
         cli: cli || "codex",
+        displayName,
         status: "running",
         progress: 0.05,
       });
@@ -1507,16 +1653,16 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
   try {
     const dispatches =
       nativeBridge && nativeBridgeMode === "agents"
-        ? await dispatchDaemonBatch(sessionName, assignments, {
+        ? await dispatchDaemonBatch(sessionName, normalizedAssignments, {
             safeProgress,
           })
         : progressive
-          ? await dispatchProgressive(sessionName, assignments, {
+          ? await dispatchProgressive(sessionName, normalizedAssignments, {
               layout,
               safeProgress,
               dashboardLayout,
             })
-          : await dispatchBatch(sessionName, assignments, {
+          : await dispatchBatch(sessionName, normalizedAssignments, {
               layout,
               safeProgress,
               dashboardLayout,
@@ -1549,6 +1695,7 @@ export async function runHeadless(sessionName, assignments, opts = {}) {
       for (const r of collected) {
         tui.updateWorker(r.paneName, {
           cli: r.cli,
+          displayName: r.displayName,
           role: r.role || "",
           status: r.handoff?.status === "failed" ? "failed" : "completed",
           handoff: r.handoff,
@@ -1950,6 +2097,7 @@ export async function runHeadlessInteractive(
   // Fix P2: paneId를 dispatches에 포함 (snapshots에서 필요)
   const dispatches = results.map((r, i) => ({
     paneName: r.paneName,
+    displayName: r.displayName,
     paneId: r.paneId || "",
     cli: r.cli,
     role: r.role,

package/hub/team/interactive-native-launcher.mjs

@@ -0,0 +1,106 @@
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  buildNativeWorkerRosterEntry,
+  deriveClaudeDaemonPaths,
+  mergeRosterWorkers,
+  removeRosterWorkers,
+} from "./claude-native-bridge.mjs";
+import { startInteractiveNativeWorker } from "./interactive-native-worker.mjs";
+
+function buildWorkerSocketPaths({ configDir, sessionName, pid, short }) {
+  const hash = crypto
+    .createHash("sha256")
+    .update(`${configDir || ""}:${sessionName}:${pid}:${crypto.randomUUID()}`)
+    .digest("hex")
+    .slice(0, 10);
+  const socketRoot = path.join(os.tmpdir(), `tfx-in-${hash}`);
+  return {
+    rvSock: path.join(socketRoot, `${short}.rv.sock`),
+    ptySock: path.join(socketRoot, `${short}.pty.sock`),
+  };
+}
+
+export async function launchAdoptedInteractiveWorker({
+  cwd = process.cwd(),
+  sessionName,
+  launchCmd = "codex",
+  cli = "codex",
+  role = "interactive",
+  configDir,
+  pid = process.pid,
+  _deps = {},
+} = {}) {
+  const startWorker =
+    _deps.startInteractiveNativeWorker || startInteractiveNativeWorker;
+  const buildRosterEntry =
+    _deps.buildNativeWorkerRosterEntry || buildNativeWorkerRosterEntry;
+  const mergeWorkers = _deps.mergeRosterWorkers || mergeRosterWorkers;
+  const derivePaths = _deps.deriveClaudeDaemonPaths || deriveClaudeDaemonPaths;
+
+  const resolvedCwd = path.resolve(cwd);
+  const effectiveSessionName =
+    sessionName || `tfx-${cli}-${role}-${process.pid}`;
+  const paths = derivePaths({ configDir });
+  const short = crypto.randomUUID().replaceAll("-", "").slice(0, 8);
+  const { rvSock, ptySock } = buildWorkerSocketPaths({
+    configDir,
+    sessionName: effectiveSessionName,
+    pid,
+    short,
+  });
+  const displayName = `Triflux ${cli} ${role}`;
+
+  let worker;
+  let closed = false;
+  let closePromise = null;
+
+  try {
+    worker = await startWorker({
+      short,
+      rvSock,
+      ptySock,
+      sessionName: effectiveSessionName,
+      cwd: resolvedCwd,
+      launchCmd,
+      pid,
+    });
+    const workerShort = worker.short || short;
+    const workerPid = worker.pid || pid;
+    const entry = buildRosterEntry({
+      short: workerShort,
+      pid: workerPid,
+      cwd: resolvedCwd,
+      rendezvousSock: worker.rvSock,
+      ptySock: worker.ptySock,
+      name: displayName,
+      prompt: displayName,
+    });
+    await mergeWorkers(paths.rosterPath, { [workerShort]: entry });
+
+    return {
+      short: workerShort,
+      displayName,
+      rosterPath: paths.rosterPath,
+      close() {
+        if (!closePromise) {
+          closePromise = (async () => {
+            if (closed) return;
+            closed = true;
+            try {
+              await worker.close();
+            } finally {
+              await removeRosterWorkers(paths.rosterPath, [workerShort]);
+            }
+          })();
+        }
+        return closePromise;
+      },
+    };
+  } catch (error) {
+    if (worker) await worker.close().catch(() => {});
+    throw error;
+  }
+}