u-foo 1.8.3 → 1.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/agent/launcher.js

@@ -177,6 +177,19 @@ function shouldShowLaunchBanner(agentType = "") {
   return true;
 }
 
+function computeInjectedSubmitDelayMs(agentType, text) {
+  const normalizedAgent = String(agentType || "").trim().toLowerCase();
+  const input = typeof text === "string" ? text : "";
+  let delayMs = normalizedAgent === "claude-code" ? 350 : 200;
+  if (input.includes("\n")) {
+    delayMs += normalizedAgent === "claude-code" ? 250 : 120;
+  }
+  if (input.length > 512) {
+    delayMs += Math.min(1200, Math.ceil(input.length / 512) * 90);
+  }
+  return delayMs;
+}
+
 async function resolveHostRegistrationData(launchMode) {
   if (launchMode !== "host") {
     return {
@@ -557,10 +570,10 @@ class AgentLauncher {
       let shouldUsePty = false;
 
       // 显式开关（优先级最高）
-      if (process.env.UFOO_DISABLE_PTY === "1") {
-        shouldUsePty = false;  // 强制回退spawn (CI/回滚)
-      } else if (process.env.UFOO_FORCE_PTY === "1") {
+      if (process.env.UFOO_FORCE_PTY === "1") {
         shouldUsePty = true;   // 强制使用PTY (测试/调试)
+      } else if (process.env.UFOO_DISABLE_PTY === "1") {
+        shouldUsePty = false;  // 强制回退spawn (CI/回滚)
       } else {
         // 自动检测：Terminal/tmux模式 + 非internal
         shouldUsePty =
@@ -778,13 +791,15 @@ class AgentLauncher {
                     // Claude Code (Ink TUI) interprets ESC+CR within ~100ms as
                     // Alt+Enter (newline) instead of two separate keys. Use a
                     // longer gap so the escape sequence parser times out.
-                    wrapper.write(req.command);
+                    const commandText = String(req.command);
+                    const submitDelayMs = computeInjectedSubmitDelayMs(this.agentType, commandText);
+                    wrapper.write(commandText);
                     if (normalizedAgentType === "claude-code") {
                       // Claude Code: send CR directly without ESC.
                       // ESC before CR is interpreted as Alt+Enter (newline).
                       setTimeout(() => {
                         wrapper.write("\r");
-                      }, 200);
+                      }, submitDelayMs);
                     } else {
                       // Codex/others: ESC dismisses autocomplete, then CR submits.
                       setTimeout(() => {
@@ -792,7 +807,7 @@ class AgentLauncher {
                         setTimeout(() => {
                           wrapper.write("\r");
                         }, 100);
-                      }, 200);
+                      }, submitDelayMs);
                     }
                     client.write(JSON.stringify({ ok: true }) + "\n");
                     if (wrapper.logger) {

package/src/agent/ptyRunner.js

@@ -85,6 +85,29 @@ function parseInputMessage(message) {
   return { raw: false, text: message };
 }
 
+function getOuterTerminalSize() {
+  const cols = Number.isInteger(process.stdout && process.stdout.columns) && process.stdout.columns > 0
+    ? process.stdout.columns
+    : 80;
+  const rows = Number.isInteger(process.stdout && process.stdout.rows) && process.stdout.rows > 0
+    ? process.stdout.rows
+    : 24;
+  return { cols, rows };
+}
+
+function computeInjectedSubmitDelayMs(agentType, text) {
+  const normalizedAgent = String(agentType || "").trim().toLowerCase();
+  const input = typeof text === "string" ? text : "";
+  let delayMs = normalizedAgent === "claude-code" ? 350 : 200;
+  if (input.includes("\n")) {
+    delayMs += normalizedAgent === "claude-code" ? 250 : 120;
+  }
+  if (input.length > 512) {
+    delayMs += Math.min(1200, Math.ceil(input.length / 512) * 90);
+  }
+  return delayMs;
+}
+
 function buildPrompt(text, marker) {
   if (!marker) return text;
   return `${text}\n\n请在完成后输出以下标记（单独一行）：\n${marker}\n`;
@@ -223,6 +246,9 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
     return 512 * 1024;
   })();
   let outputRingBuffer = "";
+  let outerInputHandler = null;
+  let outerResizeHandler = null;
+  let outerRawModeEnabled = false;
 
   function initScreenBuffer(cols = 80, rows = 24) {
     if (!Terminal || !SerializeAddon) return null;
@@ -302,6 +328,13 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
   function broadcastOutput(data) {
     const text = Buffer.from(data || "").toString("utf8");
     if (!text) return;
+    if (process.stdout && process.stdout.isTTY && typeof process.stdout.write === "function") {
+      try {
+        process.stdout.write(text);
+      } catch {
+        // ignore outer terminal write failures
+      }
+    }
     enqueueTermWrite(text);
     outputRingBuffer += text;
     if (outputRingBuffer.length > OUTPUT_RING_MAX) {
@@ -337,7 +370,9 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
             if (req.type === "inject" && req.command) {
               if (ptyProcess && ptyAlive) {
                 const isClaude = agentType === "claude-code";
-                ptyProcess.write(String(req.command));
+                const commandText = String(req.command);
+                const submitDelayMs = computeInjectedSubmitDelayMs(agentType, commandText);
+                ptyProcess.write(commandText);
                 if (isClaude) {
                   // Claude Code: send CR directly without ESC.
                   // ESC before CR is interpreted as Alt+Enter (newline).
@@ -345,7 +380,7 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
                     if (ptyProcess && ptyAlive) {
                       ptyProcess.write("\r");
                     }
-                  }, 200);
+                  }, submitDelayMs);
                 } else {
                   // Codex/others: ESC dismisses autocomplete, then CR submits.
                   setTimeout(() => {
@@ -356,7 +391,7 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
                         ptyProcess.write("\r");
                       }
                     }, 100);
-                  }, 200);
+                  }, submitDelayMs);
                 }
                 client.write(JSON.stringify({ ok: true }) + "\n");
               } else {
@@ -443,6 +478,60 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
     return server;
   }
 
+  function syncOuterTerminalSize() {
+    const { cols, rows } = getOuterTerminalSize();
+    if (ptyProcess && ptyAlive && typeof ptyProcess.resize === "function") {
+      try {
+        ptyProcess.resize(cols, rows);
+      } catch {
+        // ignore outer resize failures
+      }
+    }
+    if (term && typeof term.resize === "function") {
+      try {
+        term.resize(cols, rows);
+      } catch {
+        // ignore local screen buffer resize failures
+      }
+    }
+  }
+
+  function attachOuterTerminalBridge() {
+    if (process.stdin && typeof process.stdin.on === "function" && !outerInputHandler) {
+      outerInputHandler = (chunk) => {
+        if (!ptyProcess || !ptyAlive) return;
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        if (!text) return;
+        try {
+          ptyProcess.write(text);
+        } catch {
+          // ignore transient PTY bridge failures
+        }
+      };
+      process.stdin.on("data", outerInputHandler);
+      if (typeof process.stdin.resume === "function") {
+        process.stdin.resume();
+      }
+    }
+
+    if (process.stdin && process.stdin.isTTY && typeof process.stdin.setRawMode === "function" && !outerRawModeEnabled) {
+      try {
+        process.stdin.setRawMode(true);
+        outerRawModeEnabled = true;
+      } catch {
+        // ignore raw mode failures on unsupported hosts
+      }
+    }
+
+    if (process.stdout && process.stdout.isTTY && typeof process.stdout.on === "function" && !outerResizeHandler) {
+      outerResizeHandler = () => {
+        syncOuterTerminalSize();
+      };
+      process.stdout.on("resize", outerResizeHandler);
+      syncOuterTerminalSize();
+    }
+  }
+
   function cleanupInjectServer(server) {
     for (const sub of outputSubscribers) {
       try { sub.destroy(); } catch { /* ignore */ }
@@ -728,10 +817,11 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
       clearTimeout(readyTimer);
       readyTimer = null;
     }
+    const { cols, rows } = getOuterTerminalSize();
     const proc = pty.spawn(command, args, {
       name: "xterm-256color",
-      cols: 80,
-      rows: 24,
+      cols,
+      rows,
       cwd: projectRoot,
       env,
     });
@@ -762,6 +852,30 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
   const stop = () => {
     running = false;
     cleanupInjectServer(injectServer);
+    if (process.stdin && outerInputHandler) {
+      if (typeof process.stdin.off === "function") {
+        process.stdin.off("data", outerInputHandler);
+      } else if (typeof process.stdin.removeListener === "function") {
+        process.stdin.removeListener("data", outerInputHandler);
+      }
+      outerInputHandler = null;
+    }
+    if (process.stdout && outerResizeHandler) {
+      if (typeof process.stdout.off === "function") {
+        process.stdout.off("resize", outerResizeHandler);
+      } else if (typeof process.stdout.removeListener === "function") {
+        process.stdout.removeListener("resize", outerResizeHandler);
+      }
+      outerResizeHandler = null;
+    }
+    if (process.stdin && outerRawModeEnabled && typeof process.stdin.setRawMode === "function") {
+      try {
+        process.stdin.setRawMode(false);
+      } catch {
+        // ignore raw mode cleanup failures
+      }
+      outerRawModeEnabled = false;
+    }
     try {
       if (ptyProcess) ptyProcess.kill();
     } catch {
@@ -776,6 +890,7 @@ async function runPtyRunner({ projectRoot, agentType = "codex" }) {
   process.on("SIGHUP", () => {});
 
   ptyProcess = spawnPtyProcess();
+  attachOuterTerminalBridge();
 
   function processQueue() {
     if (busy || messageQueue.length === 0 || !running || !ptyAlive || !ptyReady) return;

package/src/daemon/groupOrchestrator.js

@@ -19,6 +19,32 @@ function asTrimmedString(value) {
   return value.trim();
 }
 
+function resolveBootstrapInjectSettleMs(agentType = "", promptText = "", options = {}) {
+  const byAgent = options && typeof options.byAgent === "object" ? options.byAgent : {};
+  const normalizedAgent = asTrimmedString(agentType).toLowerCase();
+  const explicit = Number.isFinite(byAgent[normalizedAgent]) ? byAgent[normalizedAgent] : Number.NaN;
+  if (Number.isFinite(explicit) && explicit > 0) {
+    return explicit;
+  }
+
+  let delayMs = 0;
+  if (normalizedAgent === "claude") {
+    delayMs = 800;
+  } else if (normalizedAgent === "codex") {
+    delayMs = 250;
+  }
+
+  const text = typeof promptText === "string" ? promptText : "";
+  if (!text) return delayMs;
+  if (text.includes("\n")) {
+    delayMs += normalizedAgent === "claude" ? 200 : 100;
+  }
+  if (text.length > 1024) {
+    delayMs += Math.min(800, Math.ceil(text.length / 1024) * 120);
+  }
+  return delayMs;
+}
+
 function asStringArray(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => asTrimmedString(item)).filter(Boolean);
@@ -608,6 +634,7 @@ function createGroupOrchestrator(options = {}) {
     bootstrapRetryDelayMs = 250,
     bootstrapProtectionMs = 3000,
     bootstrapWorkingGraceMs = 10000,
+    bootstrapInjectSettleMsByAgent = {},
   } = options;
 
   if (!projectRoot) {
@@ -775,6 +802,7 @@ function createGroupOrchestrator(options = {}) {
 
     const rollbackTargets = [];
     const eventBus = new EventBus(projectRoot);
+    const tmuxLayoutContext = { mode: "group-right-column" };
 
     for (let i = 0; i < compiled.executionPlan.length; i += 1) {
       const item = compiled.executionPlan[i];
@@ -810,6 +838,8 @@ function createGroupOrchestrator(options = {}) {
         agent: item.type,
         count: 1,
         nickname: item.nickname,
+        require_activity_monitor: true,
+        tmux_layout_context: tmuxLayoutContext,
         ...launchHostContext,
       };
       if (Object.keys(extraEnv).length > 0) {
@@ -924,6 +954,18 @@ function createGroupOrchestrator(options = {}) {
             member.bootstrap_error
           );
         }
+        const settleDelayMs = resolveBootstrapInjectSettleMs(
+          item.type,
+          item.bootstrap_prompt,
+          { byAgent: bootstrapInjectSettleMsByAgent }
+        );
+        if (settleDelayMs > 0) {
+          // Claude/Codex TUIs can render their prompt before the input handler
+          // is fully ready for a large bootstrap paste. Give the UI a short
+          // provider-specific settle window before injecting the group prompt.
+          // eslint-disable-next-line no-await-in-loop
+          await sleep(settleDelayMs);
+        }
         // eslint-disable-next-line no-await-in-loop
         const injected = await injectBootstrapPrompt(
           eventBus,
@@ -1058,4 +1100,5 @@ module.exports = {
   createGroupOrchestrator,
   buildLaunchPlan,
   normalizeGroupId,
+  resolveBootstrapInjectSettleMs,
 };

package/src/daemon/index.js

@@ -472,6 +472,12 @@ async function handleOps(projectRoot, ops = [], processManager = null) {
         const launchResult = await launchAgent(projectRoot, agent, count, nickname, processManager, {
           launchScope: op.launch_scope || "",
           terminalApp: op.terminal_app || "",
+          tmuxLayoutContext:
+            op.tmux_layout_context && typeof op.tmux_layout_context === "object"
+              ? op.tmux_layout_context
+              : ((op.tmuxLayoutContext && typeof op.tmuxLayoutContext === "object")
+                ? op.tmuxLayoutContext
+                : null),
           extraEnv:
             op.extra_env && typeof op.extra_env === "object"
               ? op.extra_env
@@ -486,6 +492,8 @@ async function handleOps(projectRoot, ops = [], processManager = null) {
             : ((op.hostCapabilities && typeof op.hostCapabilities === "object")
               ? op.hostCapabilities
               : null),
+          requireActivityMonitor:
+            op.require_activity_monitor === true || op.requireActivityMonitor === true,
         });
         if (launchResult.mode === "internal" && launchResult.subscriberIds && launchResult.subscriberIds.length > 0) {
           const probeAgentType = agent === "codex"

package/src/daemon/ops.js

@@ -102,6 +102,7 @@ function resolveHostLaunchContext(options = {}) {
       options.hostCapabilities && typeof options.hostCapabilities === "object"
         ? { ...options.hostCapabilities }
         : null,
+    requireActivityMonitor: options.requireActivityMonitor === true,
   };
 }
 
@@ -450,7 +451,7 @@ async function spawnManagedHostAgent(
   nickname = "",
   processManager = null,
   extraArgs = [],
-  extraEnv = "",
+  extraEnv = {},
   hostOptions = {}
 ) {
   void processManager;
@@ -462,11 +463,11 @@ async function spawnManagedHostAgent(
   }
 
   const hostContext = resolveHostLaunchContext(hostOptions);
+  const requireActivityMonitor = hostContext.requireActivityMonitor === true;
   if (!hostContext.hostDaemonSock) {
     throw new Error("host launch requires UFOO_HOST_DAEMON_SOCK");
   }
 
-  const existing = listSubscribers(projectRoot, agentType);
   const createOptions = {};
   if (hostOptions.groupId) {
     createOptions.group_id = String(hostOptions.groupId).trim();
@@ -474,22 +475,87 @@ async function spawnManagedHostAgent(
     createOptions.source_session_id = hostContext.hostSessionId;
   }
 
+  // Pre-register subscriber on the bus so waitForNewSubscriber resolves immediately
+  const crypto = require("crypto");
+  const EventBus = require("../bus");
+  const existing = listSubscribers(projectRoot, agentType);
+  let subscriberId = "";
+  let preRegistrationError = null;
+  try {
+    const bus = new EventBus(projectRoot);
+    await bus.init();
+    if (bus.subscriberManager) {
+      const sessionToken = crypto.randomBytes(4).toString("hex");
+      subscriberId = `${agentType}:${sessionToken}`;
+      const defaultNickname = agentType === "ufoo-code" ? "ucode" : normalizedAgent;
+      const finalNickname = nickname || defaultNickname;
+      await bus.subscriberManager.join(sessionToken, agentType, finalNickname, {
+        launchMode: "host",
+        parentPid: process.pid,
+      });
+      bus.saveBusData();
+    }
+  } catch (err) {
+    preRegistrationError = err;
+    subscriberId = "";
+  }
+
   const args = Array.isArray(extraArgs) ? extraArgs : [];
   const argText = args.length > 0 ? ` ${args.map(shellEscape).join(" ")}` : "";
-  const envParts = ["UFOO_LAUNCH_MODE=host"];
+
+  const titleCmd = buildTitleCmd(nickname);
+  const hasPreRegisteredSubscriber = !!subscriberId;
+
+  // Pass env vars to Horizon via the env parameter (Horizon will set them for the child process)
+  const env = {
+    UFOO_LAUNCH_MODE: "host",
+  };
+  if (requireActivityMonitor) {
+    env.UFOO_FORCE_PTY = "1";
+  }
+  if (subscriberId) {
+    env.UFOO_SUBSCRIBER_ID = subscriberId;
+  }
   if (nickname) {
-    envParts.push(`UFOO_NICKNAME=${shellEscape(nickname)}`);
+    env.UFOO_NICKNAME = nickname;
   }
-  if (extraEnv) {
-    envParts.push(String(extraEnv).trim());
+  // Parse extraEnv string (e.g., "UFOO_UCODE_BOOTSTRAP_FILE=/path/to/file") and add to env
+  if (extraEnv && typeof extraEnv === "object") {
+    for (const [key, value] of Object.entries(extraEnv)) {
+      if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(key || ""))) {
+        env[String(key)] = String(value ?? "");
+      }
+    }
   }
 
-  const titleCmd = buildTitleCmd(nickname);
-  const launchCmd = `${envParts.join(" ")} ${binary}${argText}`.trim();
-  const runCmd = titleCmd
-    ? `cd ${shellEscape(projectRoot)} && ${titleCmd} && ${launchCmd}`
-    : `cd ${shellEscape(projectRoot)} && ${launchCmd}`;
+  let runCmd;
+  if (hasPreRegisteredSubscriber) {
+    // Group mode: use ufoo launcher for activity_state monitoring
+    // This enables ReadyDetector and bootstrap to work correctly
+    const ufooRunner = path.join(projectRoot, "bin", "ufoo.js");
+    const launchCmd = `${shellEscape(process.execPath)} ${shellEscape(ufooRunner)} agent-pty-runner ${shellEscape(normalizedAgent)}${argText}`.trim();
+    runCmd = titleCmd
+      ? `cd ${shellEscape(projectRoot)} && ${titleCmd} && ${launchCmd}`
+      : `cd ${shellEscape(projectRoot)} && ${launchCmd}`;
+    // Force PTY wrapper so ReadyDetector + ActivityDetector work for activity_state monitoring.
+    // Horizon sets UFOO_DISABLE_PTY=1 unconditionally; UFOO_FORCE_PTY=1 takes priority over it.
+    env.UFOO_FORCE_PTY = "1";
+  } else {
+    if (preRegistrationError) {
+      console.error(
+        `[host-launch] pre-registration failed for ${nickname || agentType}: ${preRegistrationError.message || String(preRegistrationError)}`
+      );
+    }
+    // Fallback launch still goes through the regular agent launcher binary.
+    // For group/bootstrap-monitored flows we also force the PTY wrapper so
+    // activity_state can progress out of "starting" after self-registration.
+    const directCmd = `${binary}${argText}`;
+    runCmd = titleCmd
+      ? `cd ${shellEscape(projectRoot)} && ${titleCmd} && ${directCmd}`
+      : `cd ${shellEscape(projectRoot)} && ${directCmd}`;
+  }
   createOptions.command = runCmd;
+  createOptions.env = env;
 
   const created = await createHostSession(hostContext.hostDaemonSock, createOptions);
   const sessionId = normalizeOptionalString(created?.session_id);
@@ -498,8 +564,16 @@ async function spawnManagedHostAgent(
     throw new Error("host create_session returned incomplete session info");
   }
 
-  const subscriberId = await waitForNewSubscriber(projectRoot, agentType, existing, 20000);
-  return { child: null, subscriberId: subscriberId || null, sessionId, injectSock };
+  // If pre-registration succeeded we already have the subscriber ID;
+  // otherwise fall back to polling (slower but still works).
+  if (!subscriberId) {
+    subscriberId = await waitForNewSubscriber(projectRoot, agentType, existing, 20000);
+  }
+
+  // Return format must match what launchAgent expects: { mode, launchScope, subscriberIds }
+  // subscriberIds is an array for consistency with other launch modes
+  const resultSubscriberId = subscriberId || null;
+  return { child: null, subscriberId: resultSubscriberId, subscriberIds: [resultSubscriberId].filter(Boolean), sessionId, injectSock };
 }
 
 async function spawnInternalAgent(projectRoot, agent, count = 1, nickname = "", processManager = null, extraEnv = {}) {
@@ -679,7 +753,49 @@ function resolveTmuxPaneTarget() {
   return "";
 }
 
-function spawnTmuxPane(projectRoot, agent, nickname = "", extraArgs = [], extraEnv = "", target = "") {
+function runTmuxCommand(tmuxArgs = [], failureMessage = "tmux command failed", captureStdout = false) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("tmux", tmuxArgs);
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString("utf8");
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString("utf8");
+    });
+    proc.on("error", (err) => reject(err));
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(captureStdout ? stdout.trim() : "");
+      } else {
+        reject(new Error(stderr || failureMessage));
+      }
+    });
+  });
+}
+
+function applyTmuxLayout(layout = "", target = "") {
+  const normalizedLayout = String(layout || "").trim();
+  if (!normalizedLayout) return Promise.resolve("");
+  const tmuxArgs = ["select-layout"];
+  const normalizedTarget = String(target || "").trim();
+  if (normalizedTarget) {
+    tmuxArgs.push("-t", normalizedTarget);
+  }
+  tmuxArgs.push(normalizedLayout);
+  return runTmuxCommand(tmuxArgs, "tmux select-layout failed");
+}
+
+function spawnTmuxPane(
+  projectRoot,
+  agent,
+  nickname = "",
+  extraArgs = [],
+  extraEnv = "",
+  target = "",
+  splitOptions = {}
+) {
   return new Promise((resolve, reject) => {
     const normalizedAgent = normalizeLaunchAgent(agent);
     const binary = toTmuxBinary(normalizedAgent);
@@ -697,21 +813,25 @@ function spawnTmuxPane(projectRoot, agent, nickname = "", extraArgs = [], extraE
     const runCmd = `cd ${shellEscape(projectRoot)} && ${setPaneEnv}${modeEnv}${nickEnv}${ttyEnv}${envPrefix}${binary}${argText}`;
 
     const tmuxArgs = ["split-window", "-d"];
+    const orientation = String(splitOptions.orientation || "").trim().toLowerCase();
+    if (orientation === "horizontal") {
+      tmuxArgs.push("-h");
+    } else if (orientation === "vertical") {
+      tmuxArgs.push("-v");
+    }
+    const capturePaneId = splitOptions.capturePaneId === true;
+    if (capturePaneId) {
+      tmuxArgs.push("-P", "-F", "#{pane_id}");
+    }
     const normalizedTarget = String(target || "").trim();
     if (normalizedTarget) {
       tmuxArgs.push("-t", normalizedTarget);
     }
     tmuxArgs.push(runCmd);
 
-    const proc = spawn("tmux", tmuxArgs);
-    let stderr = "";
-    proc.stderr.on("data", (d) => {
-      stderr += d.toString("utf8");
-    });
-    proc.on("close", (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(stderr || "tmux split-window failed"));
-    });
+    runTmuxCommand(tmuxArgs, "tmux split-window failed", capturePaneId)
+      .then((paneId) => resolve({ paneId: capturePaneId ? paneId : "" }))
+      .catch(reject);
   });
 }
 
@@ -762,6 +882,12 @@ async function launchAgent(projectRoot, agent, count = 1, nickname = "", process
     }
     const paneTarget = resolveTmuxPaneTarget();
     const useSeparateWindow = launchScope === "window";
+    const tmuxLayoutContext = options.tmuxLayoutContext && typeof options.tmuxLayoutContext === "object"
+      ? options.tmuxLayoutContext
+      : null;
+    const useGroupRightColumnLayout = !useSeparateWindow
+      && tmuxLayoutContext
+      && tmuxLayoutContext.mode === "group-right-column";
     for (let i = 0; i < count; i += 1) {
       // Use "ucode" as default nickname for ufoo/ucode agents
       const defaultNick = normalizedAgent === "ufoo" ? "ucode" : normalizedAgent;
@@ -769,6 +895,31 @@ async function launchAgent(projectRoot, agent, count = 1, nickname = "", process
       if (useSeparateWindow) {
         // eslint-disable-next-line no-await-in-loop
         await spawnTmuxWindow(projectRoot, normalizedAgent, nick, [], extraEnvPrefix);
+      } else if (useGroupRightColumnLayout && paneTarget) {
+        const basePane = String(tmuxLayoutContext.basePane || paneTarget).trim() || paneTarget;
+        tmuxLayoutContext.basePane = basePane;
+        const rightColumnPane = String(tmuxLayoutContext.rightColumnPane || "").trim();
+        const splitTarget = rightColumnPane || basePane;
+        const splitOrientation = rightColumnPane ? "vertical" : "horizontal";
+        let splitResult;
+        try {
+          // eslint-disable-next-line no-await-in-loop
+          splitResult = await spawnTmuxPane(projectRoot, normalizedAgent, nick, [], extraEnvPrefix, splitTarget, {
+            orientation: splitOrientation,
+            capturePaneId: !rightColumnPane,
+          });
+        } catch {
+          // Fallback to new window when current pane target cannot be resolved.
+          // eslint-disable-next-line no-await-in-loop
+          await spawnTmuxWindow(projectRoot, normalizedAgent, nick, [], extraEnvPrefix);
+          continue;
+        }
+        if (!rightColumnPane && splitResult && splitResult.paneId) {
+          tmuxLayoutContext.rightColumnPane = splitResult.paneId;
+        }
+        // Keep the original chat pane on the left while stacking agents evenly on the right.
+        // eslint-disable-next-line no-await-in-loop
+        await applyTmuxLayout("main-vertical", basePane);
       } else {
         try {
           // eslint-disable-next-line no-await-in-loop
@@ -795,7 +946,7 @@ async function launchAgent(projectRoot, agent, count = 1, nickname = "", process
         nick,
         processManager,
         [],
-        extraEnvPrefix,
+        extraEnvObject,
         hostContext
       );
       if (result.subscriberId) subscriberIds.push(result.subscriberId);

package/src/terminal/adapters/hostAdapter.js

@@ -334,7 +334,7 @@ async function requestCloseSession(sockPath) {
 /**
  * Create a new terminal session via the daemon management socket.
  * @param {string} [daemonSock] - Override daemon socket path (defaults to env)
- * @param {object} [opts] - Options: { group_id, source_session_id, command }
+ * @param {object} [opts] - Options: { group_id, source_session_id, command, env }
  * @returns {Promise<{session_id: string, inject_sock: string}>}
  */
 async function createSession(daemonSock, opts = {}) {
@@ -343,6 +343,7 @@ async function createSession(daemonSock, opts = {}) {
   if (opts.group_id) req.group_id = opts.group_id;
   if (opts.source_session_id) req.source_session_id = opts.source_session_id;
   if (opts.command) req.command = opts.command;
+  if (opts.env) req.env = opts.env;
   return sendToSocket(sock, req);
 }