pi-teams 0.9.0 → 0.9.5

package/extensions/index.ts

@@ -142,10 +142,134 @@ function resolveModelWithProvider(modelName: string): string | null {
   return null;
 }
 
+/**
+ * Find the team this session is the lead for (if any).
+ * Checks the lead-session.json file to match PID.
+ */
+function findLeadTeamForSession(): string | null {
+  try {
+    const teamsDir = paths.TEAMS_DIR;
+    if (!fs.existsSync(teamsDir)) return null;
+
+    for (const teamDir of fs.readdirSync(teamsDir)) {
+      const sessionFile = paths.leadSessionPath(teamDir);
+      if (fs.existsSync(sessionFile)) {
+        try {
+          const session = JSON.parse(fs.readFileSync(sessionFile, "utf-8"));
+          if (session.pid === process.pid) {
+            return teamDir;
+          }
+        } catch {
+          // Ignore corrupted session files
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Register this session as the lead for a team.
+ */
+function registerLeadSession(teamName: string) {
+  const sessionFile = paths.leadSessionPath(teamName);
+  const dir = path.dirname(sessionFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(sessionFile, JSON.stringify({
+    pid: process.pid,
+    startedAt: Date.now(),
+  }));
+}
+
+/**
+ * Check if a process with the given PID is still alive.
+ */
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // Signal 0 = check if process exists
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clean up a stale team if the lead process is dead.
+ * Kills all teammate panes/windows and removes all state files.
+ * Returns true if cleanup was performed, false otherwise.
+ */
+function cleanupStaleTeam(teamName: string, terminal: any): boolean {
+  const sessionFile = paths.leadSessionPath(teamName);
+  const configFile = paths.configPath(teamName);
+  
+  if (!fs.existsSync(sessionFile) || !fs.existsSync(configFile)) {
+    return false;
+  }
+  
+  try {
+    const session = JSON.parse(fs.readFileSync(sessionFile, "utf-8"));
+    
+    // Only cleanup if the lead PID is actually dead
+    if (session.pid && !isPidAlive(session.pid)) {
+      // Read config to get member info for cleanup
+      try {
+        const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+        
+        // Kill all teammate panes/windows
+        for (const member of config.members || []) {
+          if (member.name === "team-lead") continue;
+          
+          // Kill via PID file
+          const pidFile = path.join(paths.teamDir(teamName), `${member.name}.pid`);
+          if (fs.existsSync(pidFile)) {
+            try {
+              const pid = fs.readFileSync(pidFile, "utf-8").trim();
+              process.kill(parseInt(pid), "SIGKILL");
+              fs.unlinkSync(pidFile);
+            } catch {}
+          }
+          
+          // Kill via terminal adapter
+          if (terminal) {
+            if (member.windowId) {
+              try { terminal.killWindow(member.windowId); } catch {}
+            }
+            if (member.tmuxPaneId) {
+              try { terminal.kill(member.tmuxPaneId); } catch {}
+            }
+          }
+        }
+      } catch {}
+      
+      // Delete entire team directory
+      const teamDirectory = paths.teamDir(teamName);
+      if (fs.existsSync(teamDirectory)) {
+        fs.rmSync(teamDirectory, { recursive: true });
+      }
+      
+      // Delete tasks directory
+      const tasksDirectory = paths.taskDir(teamName);
+      if (fs.existsSync(tasksDirectory)) {
+        fs.rmSync(tasksDirectory, { recursive: true });
+      }
+      
+      return true;
+    }
+  } catch {}
+  
+  return false;
+}
+
 export default function (pi: ExtensionAPI) {
   const isTeammate = !!process.env.PI_AGENT_NAME;
   const agentName = process.env.PI_AGENT_NAME || "team-lead";
-  const teamName = process.env.PI_TEAM_NAME;
+  const envTeamName = process.env.PI_TEAM_NAME;
+
+  // For leads without PI_TEAM_NAME, check if we're registered as lead for a team
+  const detectedTeamName = envTeamName || findLeadTeamForSession();
+  const teamName = detectedTeamName;
 
   const terminal = getTerminalAdapter();
 
@@ -181,27 +305,34 @@ export default function (pi: ExtensionAPI) {
       setTimeout(() => {
         pi.sendUserMessage(`I am starting my work as '${agentName}' on team '${teamName}'. Checking my inbox for instructions...`);
       }, 1000);
+    } else if (teamName) {
+      ctx.ui.setStatus("pi-teams", `Lead @ ${teamName}`);
+    }
 
+    // Inbox polling for BOTH teammates AND team-leads (anyone with teamName)
+    if (teamName) {
       setInterval(async () => {
-        if (ctx.isIdle() && teamName) {
+        if (ctx.isIdle()) {
           try {
             const unread = await messaging.readInbox(teamName, agentName, true, false);
-            await runtime.writeRuntimeStatus(teamName, agentName, {
-              lastHeartbeatAt: Date.now(),
-            });
+            if (isTeammate) {
+              await runtime.writeRuntimeStatus(teamName, agentName, {
+                lastHeartbeatAt: Date.now(),
+              });
+            }
             if (unread.length > 0) {
               pi.sendUserMessage(`I have ${unread.length} new message(s) in my inbox. Reading them now...`);
             }
           } catch (e) {
-            await runtime.writeRuntimeStatus(teamName, agentName, {
-              lastHeartbeatAt: Date.now(),
-              lastError: runtime.createRuntimeError(e),
-            });
+            if (isTeammate) {
+              await runtime.writeRuntimeStatus(teamName, agentName, {
+                lastHeartbeatAt: Date.now(),
+                lastError: runtime.createRuntimeError(e),
+              });
+            }
           }
         }
       }, 30000);
-    } else if (teamName) {
-      ctx.ui.setStatus("pi-teams", `Lead @ ${teamName}`);
     }
   });
 
@@ -289,7 +420,15 @@ export default function (pi: ExtensionAPI) {
       separate_windows: Type.Optional(Type.Boolean({ default: false, description: "Open teammates in separate OS windows instead of panes" })),
     }),
     async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      // Auto-cleanup stale team if the previous lead process is dead
+      // This handles the case where a session was aborted and restarted
+      if (teams.teamExists(params.team_name)) {
+        cleanupStaleTeam(params.team_name, terminal);
+      }
+      
       const config = teams.createTeam(params.team_name, "local-session", "lead-agent", params.description, params.default_model, params.separate_windows);
+      // Register this session as the lead so it can receive inbox messages
+      registerLeadSession(params.team_name);
       return {
         content: [{ type: "text", text: `Team ${params.team_name} created.` }],
         details: { config },
@@ -324,6 +463,15 @@ export default function (pi: ExtensionAPI) {
       }
 
       const teamConfig = await teams.readConfig(safeTeamName);
+      
+      // Check if a teammate with this name already exists - kill them first
+      // This handles the case where the user aborts mid-execution and restarts
+      const existingMember = teamConfig.members.find(m => m.name === safeName && m.agentType === "teammate");
+      if (existingMember) {
+        await killTeammate(safeTeamName, existingMember);
+        await teams.removeMember(safeTeamName, safeName);
+      }
+      
       let chosenModel = params.model || teamConfig.defaultModel;
 
       // Resolve model to provider/model format
@@ -409,11 +557,17 @@ export default function (pi: ExtensionAPI) {
             }
           }
 
+          const leadMember = teamConfig.members.find(m => m.name === "team-lead");
+          const anchorPaneId = terminal.name === "tmux"
+            ? leadMember?.tmuxPaneId || process.env.TMUX_PANE || undefined
+            : undefined;
+
           terminalId = terminal.spawn({
             name: safeName,
             cwd: params.cwd,
             command: piCmd,
             env: env,
+            anchorPaneId,
           });
           await teams.updateMember(safeTeamName, safeName, { tmuxPaneId: terminalId });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.9.0",
+  "version": "0.9.5",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": {
     "type": "git",

package/src/adapters/cmux-adapter.test.ts

@@ -0,0 +1,309 @@
+/**
+ * CmuxAdapter Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { CmuxAdapter } from "./cmux-adapter";
+import * as terminalAdapter from "../utils/terminal-adapter";
+
+describe("CmuxAdapter", () => {
+  let adapter: CmuxAdapter;
+  let mockExecCommand: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    adapter = new CmuxAdapter();
+    mockExecCommand = vi.spyOn(terminalAdapter, "execCommand");
+    delete process.env.CMUX_SOCKET_PATH;
+    delete process.env.CMUX_WORKSPACE_ID;
+    delete process.env.TMUX;
+    delete process.env.ZELLIJ;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("name", () => {
+    it("should have the correct name", () => {
+      expect(adapter.name).toBe("cmux");
+    });
+  });
+
+  describe("detect", () => {
+    it("should detect when CMUX_SOCKET_PATH is set", () => {
+      process.env.CMUX_SOCKET_PATH = "/tmp/cmux.sock";
+      expect(adapter.detect()).toBe(true);
+    });
+
+    it("should detect when CMUX_WORKSPACE_ID is set", () => {
+      process.env.CMUX_WORKSPACE_ID = "workspace-123";
+      expect(adapter.detect()).toBe(true);
+    });
+
+    it("should not detect when neither env var is set", () => {
+      expect(adapter.detect()).toBe(false);
+    });
+
+    it("should not detect when TMUX is set (defensive - nested)", () => {
+      process.env.CMUX_SOCKET_PATH = "/tmp/cmux.sock";
+      process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+      expect(adapter.detect()).toBe(false);
+    });
+
+    it("should not detect when ZELLIJ is set (defensive - nested)", () => {
+      process.env.CMUX_WORKSPACE_ID = "workspace-123";
+      process.env.ZELLIJ = "1";
+      expect(adapter.detect()).toBe(false);
+    });
+  });
+
+  describe("spawn", () => {
+    beforeEach(() => {
+      process.env.CMUX_SOCKET_PATH = "/tmp/cmux.sock";
+    });
+
+    it("should spawn a new pane and return the surface ID", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "OK surface-42", 
+        stderr: "", 
+        status: 0 
+      });
+
+      const result = adapter.spawn({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi --agent test",
+        env: { PI_AGENT_ID: "test-123" },
+      });
+
+      expect(result).toBe("surface-42");
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["new-split", "right", "--command", "env PI_AGENT_ID=test-123 pi --agent test"]
+      );
+    });
+
+    it("should spawn without env prefix when no PI_ vars", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "OK surface-99", 
+        stderr: "", 
+        status: 0 
+      });
+
+      const result = adapter.spawn({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi",
+        env: { OTHER: "ignored" },
+      });
+
+      expect(result).toBe("surface-99");
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["new-split", "right", "--command", "pi"]
+      );
+    });
+
+    it("should throw on spawn failure", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "", 
+        stderr: "cmux not found", 
+        status: 1 
+      });
+
+      expect(() => adapter.spawn({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi",
+        env: {},
+      })).toThrow("cmux new-split failed with status 1");
+    });
+
+    it("should throw on unexpected output format", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "ERROR something went wrong", 
+        stderr: "", 
+        status: 0 
+      });
+
+      expect(() => adapter.spawn({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi",
+        env: {},
+      })).toThrow("cmux new-split returned unexpected output");
+    });
+  });
+
+  describe("kill", () => {
+    it("should kill a pane by surface ID", () => {
+      mockExecCommand.mockReturnValue({ stdout: "", stderr: "", status: 0 });
+
+      adapter.kill("surface-42");
+
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["close-surface", "--surface", "surface-42"]
+      );
+    });
+
+    it("should be idempotent - no error on empty pane ID", () => {
+      adapter.kill("");
+      adapter.kill(undefined as unknown as string);
+      expect(mockExecCommand).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("isAlive", () => {
+    it("should return true if pane exists", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "surface-1\nsurface-42\nsurface-99", 
+        stderr: "", 
+        status: 0 
+      });
+
+      expect(adapter.isAlive("surface-42")).toBe(true);
+    });
+
+    it("should return false if pane does not exist", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "surface-1\nsurface-99", 
+        stderr: "", 
+        status: 0 
+      });
+
+      expect(adapter.isAlive("surface-42")).toBe(false);
+    });
+
+    it("should return false on error", () => {
+      mockExecCommand.mockImplementation(() => {
+        throw new Error("cmux error");
+      });
+
+      expect(adapter.isAlive("surface-42")).toBe(false);
+    });
+
+    it("should return false for empty pane ID", () => {
+      expect(adapter.isAlive("")).toBe(false);
+      expect(adapter.isAlive(undefined as unknown as string)).toBe(false);
+    });
+  });
+
+  describe("setTitle", () => {
+    it("should set the tab title", () => {
+      mockExecCommand.mockReturnValue({ stdout: "", stderr: "", status: 0 });
+
+      adapter.setTitle("My Team");
+
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["rename-tab", "My Team"]
+      );
+    });
+
+    it("should silently ignore errors", () => {
+      mockExecCommand.mockImplementation(() => {
+        throw new Error("cmux error");
+      });
+
+      // Should not throw
+      expect(() => adapter.setTitle("My Team")).not.toThrow();
+    });
+  });
+
+  describe("supportsWindows", () => {
+    it("should return true", () => {
+      expect(adapter.supportsWindows()).toBe(true);
+    });
+  });
+
+  describe("spawnWindow", () => {
+    it("should spawn a new window with command", () => {
+      mockExecCommand
+        .mockReturnValueOnce({ stdout: "OK window-1", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "", stderr: "", status: 0 })
+        .mockReturnValueOnce({ stdout: "", stderr: "", status: 0 });
+
+      const result = adapter.spawnWindow({
+        name: "test-agent",
+        cwd: "/home/user/project",
+        command: "pi",
+        env: { PI_TEAM: "myteam" },
+        teamName: "Team Alpha",
+      });
+
+      expect(result).toBe("window-1");
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["new-window"]
+      );
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["new-workspace", "--window", "window-1", "--command", "env PI_TEAM=myteam pi"]
+      );
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["rename-window", "--window", "window-1", "Team Alpha"]
+      );
+    });
+
+    it("should throw on new-window failure", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "", 
+        stderr: "error", 
+        status: 1 
+      });
+
+      expect(() => adapter.spawnWindow({
+        name: "test",
+        cwd: "/home/user",
+        command: "pi",
+        env: {},
+      })).toThrow("cmux new-window failed with status 1");
+    });
+  });
+
+  describe("window operations", () => {
+    it("should set window title", () => {
+      mockExecCommand.mockReturnValue({ stdout: "", stderr: "", status: 0 });
+
+      adapter.setWindowTitle("window-1", "New Title");
+
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["rename-window", "--window", "window-1", "New Title"]
+      );
+    });
+
+    it("should kill a window", () => {
+      mockExecCommand.mockReturnValue({ stdout: "", stderr: "", status: 0 });
+
+      adapter.killWindow("window-1");
+
+      expect(mockExecCommand).toHaveBeenCalledWith(
+        "cmux",
+        ["close-window", "--window", "window-1"]
+      );
+    });
+
+    it("should check if window is alive", () => {
+      mockExecCommand.mockReturnValue({ 
+        stdout: "window-1\nwindow-2", 
+        stderr: "", 
+        status: 0 
+      });
+
+      expect(adapter.isWindowAlive("window-1")).toBe(true);
+      expect(adapter.isWindowAlive("window-99")).toBe(false);
+    });
+
+    it("should handle empty window IDs gracefully", () => {
+      adapter.killWindow("");
+      adapter.killWindow(undefined as unknown as string);
+      expect(mockExecCommand).not.toHaveBeenCalled();
+
+      expect(adapter.isWindowAlive("")).toBe(false);
+      expect(adapter.isWindowAlive(undefined as unknown as string)).toBe(false);
+    });
+  });
+});

package/src/adapters/cmux-adapter.ts

@@ -10,7 +10,11 @@ export class CmuxAdapter implements TerminalAdapter {
   readonly name = "cmux";
 
   detect(): boolean {
-    // Check for CMUX specific environment variables
+    // Defensive: Don't detect cmux if we're inside tmux or Zellij
+    // This prevents false positives in nested terminal scenarios
+    if (process.env.TMUX || process.env.ZELLIJ) {
+      return false;
+    }
     return !!process.env.CMUX_SOCKET_PATH || !!process.env.CMUX_WORKSPACE_ID;
   }
 

package/src/adapters/terminal-registry.ts

@@ -7,8 +7,9 @@
 
 import { TerminalAdapter } from "../utils/terminal-adapter";
 import { TmuxAdapter } from "./tmux-adapter";
-import { Iterm2Adapter } from "./iterm2-adapter";
 import { ZellijAdapter } from "./zellij-adapter";
+import { CmuxAdapter } from "./cmux-adapter";
+import { Iterm2Adapter } from "./iterm2-adapter";
 import { WezTermAdapter } from "./wezterm-adapter";
 import { WindowsAdapter } from "./windows-adapter";
 
@@ -18,13 +19,15 @@ import { WindowsAdapter } from "./windows-adapter";
  * Detection order (first match wins):
  * 1. tmux - if TMUX env is set
  * 2. Zellij - if ZELLIJ env is set and not in tmux
- * 3. iTerm2 - if TERM_PROGRAM=iTerm.app and not in tmux/zellij
- * 4. WezTerm - if WEZTERM_PANE env is set and not in tmux/zellij
- * 5. Windows - if platform is win32 and not in tmux/zellij/iTerm2/WezTerm
+ * 3. cmux - if CMUX_SOCKET_PATH or CMUX_WORKSPACE_ID env is set
+ * 4. iTerm2 - if TERM_PROGRAM=iTerm.app and not in tmux/zellij/cmux
+ * 5. WezTerm - if WEZTERM_PANE env is set and not in tmux/zellij/cmux
+ * 6. Windows - if platform is win32 and not in tmux/zellij/cmux/iTerm2/WezTerm
  */
 const adapters: TerminalAdapter[] = [
   new TmuxAdapter(),
   new ZellijAdapter(),
+  new CmuxAdapter(),
   new Iterm2Adapter(),
   new WezTermAdapter(),
   new WindowsAdapter(),
@@ -41,9 +44,10 @@ let cachedAdapter: TerminalAdapter | null = null;
  * Detection order (first match wins):
  * 1. tmux - if TMUX env is set
  * 2. Zellij - if ZELLIJ env is set and not in tmux
- * 3. iTerm2 - if TERM_PROGRAM=iTerm.app and not in tmux/zellij
- * 4. WezTerm - if WEZTERM_PANE env is set and not in tmux/zellij
- * 5. Windows - if platform is win32 and not in tmux/zellij/iTerm2/WezTerm
+ * 3. cmux - if CMUX_SOCKET_PATH or CMUX_WORKSPACE_ID env is set
+ * 4. iTerm2 - if TERM_PROGRAM=iTerm.app and not in tmux/zellij/cmux
+ * 5. WezTerm - if WEZTERM_PANE env is set and not in tmux/zellij/cmux
+ * 6. Windows - if platform is win32 and not in tmux/zellij/cmux/iTerm2/WezTerm
  *
  * @returns The detected terminal adapter, or null if none detected
  */
@@ -65,7 +69,7 @@ export function getTerminalAdapter(): TerminalAdapter | null {
 /**
  * Get a specific terminal adapter by name.
  *
- * @param name - The adapter name (e.g., "tmux", "iTerm2", "zellij", "WezTerm", "Windows")
+ * @param name - The adapter name (e.g., "tmux", "zellij", "cmux", "iTerm2", "WezTerm", "Windows")
  * @returns The adapter instance, or undefined if not found
  */
 export function getAdapterByName(name: string): TerminalAdapter | undefined {
@@ -107,7 +111,7 @@ export function hasTerminalAdapter(): boolean {
 /**
  * Check if the current terminal supports spawning separate OS windows.
  *
- * @returns true if the detected terminal supports windows (iTerm2, WezTerm, Windows)
+ * @returns true if the detected terminal supports windows (iTerm2, WezTerm, Windows, cmux)
  */
 export function supportsWindows(): boolean {
   const adapter = getTerminalAdapter();

package/src/adapters/tmux-adapter.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Tmux Adapter Tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { TmuxAdapter } from "./tmux-adapter";
+import * as terminalAdapter from "../utils/terminal-adapter";
+
+describe("TmuxAdapter", () => {
+  let adapter: TmuxAdapter;
+  let mockExecCommand: ReturnType<typeof vi.spyOn>;
+  const originalTmux = process.env.TMUX;
+  const originalTmuxPane = process.env.TMUX_PANE;
+
+  beforeEach(() => {
+    adapter = new TmuxAdapter();
+    mockExecCommand = vi.spyOn(terminalAdapter, "execCommand");
+    process.env.TMUX = "/tmp/tmux-1000/default,123,0";
+    process.env.TMUX_PANE = "%16";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+
+    if (originalTmux === undefined) delete process.env.TMUX;
+    else process.env.TMUX = originalTmux;
+
+    if (originalTmuxPane === undefined) delete process.env.TMUX_PANE;
+    else process.env.TMUX_PANE = originalTmuxPane;
+  });
+
+  it("should have the correct name", () => {
+    expect(adapter.name).toBe("tmux");
+  });
+
+  it("should detect tmux when TMUX is set", () => {
+    expect(adapter.detect()).toBe(true);
+  });
+
+  it("should target the originating pane and its window when spawning", () => {
+    mockExecCommand.mockImplementation((_bin: string, args: string[]) => {
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%16" &&
+        args[4] === "#{pane_id}"
+      ) {
+        return { stdout: "%16", stderr: "", status: 0 };
+      }
+
+      if (args[0] === "split-window") {
+        return { stdout: "%42", stderr: "", status: 0 };
+      }
+
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%16" &&
+        args[4] === "#{window_id}"
+      ) {
+        return { stdout: "@7", stderr: "", status: 0 };
+      }
+
+      return { stdout: "", stderr: "", status: 0 };
+    });
+
+    const paneId = adapter.spawn({
+      name: "agent-1",
+      cwd: "/tmp/project",
+      command: "pi",
+      env: { PI_TEAM_NAME: "team-1", PI_AGENT_NAME: "agent-1", OTHER: "ignored" },
+    });
+
+    expect(paneId).toBe("%42");
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      [
+        "split-window",
+        "-h", "-dP",
+        "-F", "#{pane_id}",
+        "-t", "%16",
+        "-c", "/tmp/project",
+        "env", "PI_TEAM_NAME=team-1", "PI_AGENT_NAME=agent-1",
+        "sh", "-c", "pi",
+      ]
+    );
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      ["set-window-option", "-t", "@7", "main-pane-width", "60%"]
+    );
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      ["select-layout", "-t", "@7", "main-vertical"]
+    );
+  });
+
+  it("should prefer an explicit anchor pane when spawning", () => {
+    mockExecCommand.mockImplementation((_bin: string, args: string[]) => {
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%3" &&
+        args[4] === "#{pane_id}"
+      ) {
+        return { stdout: "%3", stderr: "", status: 0 };
+      }
+
+      if (args[0] === "split-window") {
+        return { stdout: "%42", stderr: "", status: 0 };
+      }
+
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%3" &&
+        args[4] === "#{window_id}"
+      ) {
+        return { stdout: "@9", stderr: "", status: 0 };
+      }
+
+      return { stdout: "", stderr: "", status: 0 };
+    });
+
+    const paneId = adapter.spawn({
+      name: "agent-1",
+      cwd: "/tmp/project",
+      command: "pi",
+      env: { PI_TEAM_NAME: "team-1", PI_AGENT_NAME: "agent-1" },
+      anchorPaneId: "%3",
+    });
+
+    expect(paneId).toBe("%42");
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      [
+        "split-window",
+        "-h", "-dP",
+        "-F", "#{pane_id}",
+        "-t", "%3",
+        "-c", "/tmp/project",
+        "env", "PI_TEAM_NAME=team-1", "PI_AGENT_NAME=agent-1",
+        "sh", "-c", "pi",
+      ]
+    );
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      ["set-window-option", "-t", "@9", "main-pane-width", "60%"]
+    );
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      ["select-layout", "-t", "@9", "main-vertical"]
+    );
+  });
+
+  it("should fall back to the current pane when the explicit anchor is stale", () => {
+    mockExecCommand.mockImplementation((_bin: string, args: string[]) => {
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%3" &&
+        args[4] === "#{pane_id}"
+      ) {
+        return { stdout: "", stderr: "no such pane", status: 1 };
+      }
+
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%16" &&
+        args[4] === "#{pane_id}"
+      ) {
+        return { stdout: "%16", stderr: "", status: 0 };
+      }
+
+      if (args[0] === "split-window") {
+        return { stdout: "%42", stderr: "", status: 0 };
+      }
+
+      if (
+        args[0] === "display-message" &&
+        args[1] === "-p" &&
+        args[2] === "-t" &&
+        args[3] === "%16" &&
+        args[4] === "#{window_id}"
+      ) {
+        return { stdout: "@7", stderr: "", status: 0 };
+      }
+
+      return { stdout: "", stderr: "", status: 0 };
+    });
+
+    const paneId = adapter.spawn({
+      name: "agent-1",
+      cwd: "/tmp/project",
+      command: "pi",
+      env: { PI_TEAM_NAME: "team-1", PI_AGENT_NAME: "agent-1" },
+      anchorPaneId: "%3",
+    });
+
+    expect(paneId).toBe("%42");
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      [
+        "split-window",
+        "-h", "-dP",
+        "-F", "#{pane_id}",
+        "-t", "%16",
+        "-c", "/tmp/project",
+        "env", "PI_TEAM_NAME=team-1", "PI_AGENT_NAME=agent-1",
+        "sh", "-c", "pi",
+      ]
+    );
+  });
+
+  it("should target the current pane when setting the title", () => {
+    mockExecCommand.mockReturnValue({ stdout: "", stderr: "", status: 0 });
+
+    adapter.setTitle("team: agent-1");
+
+    expect(mockExecCommand).toHaveBeenCalledWith(
+      "tmux",
+      ["select-pane", "-t", "%16", "-T", "team: agent-1"]
+    );
+  });
+});

package/src/adapters/tmux-adapter.ts

@@ -15,19 +15,70 @@ export class TmuxAdapter implements TerminalAdapter {
     return !!process.env.TMUX;
   }
 
+  private getCurrentPaneId(): string | null {
+    const paneId = process.env.TMUX_PANE?.trim();
+    return paneId ? paneId : null;
+  }
+
+  private getWindowIdForPane(paneId: string | null | undefined): string | null {
+    if (!paneId) return null;
+
+    try {
+      const result = execCommand("tmux", ["display-message", "-p", "-t", paneId, "#{window_id}"]);
+      if (result.status !== 0) return null;
+
+      const windowId = result.stdout.trim();
+      return windowId || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private isPaneUsable(paneId: string | null | undefined): paneId is string {
+    if (!paneId) return false;
+
+    try {
+      const result = execCommand("tmux", ["display-message", "-p", "-t", paneId, "#{pane_id}"]);
+      return result.status === 0 && result.stdout.trim() === paneId;
+    } catch {
+      return false;
+    }
+  }
+
+  private getOriginPaneId(preferredPaneId?: string | null): string | null {
+    if (this.isPaneUsable(preferredPaneId)) {
+      return preferredPaneId;
+    }
+
+    const currentPaneId = this.getCurrentPaneId();
+    if (this.isPaneUsable(currentPaneId)) {
+      return currentPaneId;
+    }
+
+    return null;
+  }
+
   spawn(options: SpawnOptions): string {
     const envArgs = Object.entries(options.env)
       .filter(([k]) => k.startsWith("PI_"))
       .map(([k, v]) => `${k}=${v}`);
 
+    const originPaneId = this.getOriginPaneId(options.anchorPaneId);
     const tmuxArgs = [
       "split-window",
       "-h", "-dP",
       "-F", "#{pane_id}",
+    ];
+
+    if (originPaneId) {
+      tmuxArgs.push("-t", originPaneId);
+    }
+
+    tmuxArgs.push(
       "-c", options.cwd,
       "env", ...envArgs,
       "sh", "-c", options.command
-    ];
+    );
 
     const result = execCommand("tmux", tmuxArgs);
     
@@ -35,11 +86,20 @@ export class TmuxAdapter implements TerminalAdapter {
       throw new Error(`tmux spawn failed with status ${result.status}: ${result.stderr}`);
     }
 
-    // Apply layout after spawning
-    execCommand("tmux", ["set-window-option", "main-pane-width", "60%"]);
-    execCommand("tmux", ["select-layout", "main-vertical"]);
+    const newPaneId = result.stdout.trim();
+    const layoutTarget = this.getWindowIdForPane(originPaneId) ?? this.getWindowIdForPane(newPaneId);
+
+    // Apply layout to the exact window that contains the spawned pane so the
+    // split always stays anchored to the intended tmux window.
+    if (layoutTarget) {
+      execCommand("tmux", ["set-window-option", "-t", layoutTarget, "main-pane-width", "60%"]);
+      execCommand("tmux", ["select-layout", "-t", layoutTarget, "main-vertical"]);
+    } else {
+      execCommand("tmux", ["set-window-option", "main-pane-width", "60%"]);
+      execCommand("tmux", ["select-layout", "main-vertical"]);
+    }
 
-    return result.stdout.trim();
+    return newPaneId;
   }
 
   kill(paneId: string): void {
@@ -69,7 +129,11 @@ export class TmuxAdapter implements TerminalAdapter {
 
   setTitle(title: string): void {
     try {
-      execCommand("tmux", ["select-pane", "-T", title]);
+      const paneId = this.getCurrentPaneId();
+      const args = paneId
+        ? ["select-pane", "-t", paneId, "-T", title]
+        : ["select-pane", "-T", title];
+      execCommand("tmux", args);
     } catch {
       // Ignore errors
     }

package/src/utils/paths.ts

@@ -39,3 +39,7 @@ export function runtimeStatusPath(teamName: string, agentName: string) {
 export function configPath(teamName: string) {
   return path.join(teamDir(teamName), "config.json");
 }
+
+export function leadSessionPath(teamName: string) {
+  return path.join(teamDir(teamName), "lead-session.json");
+}

package/src/utils/terminal-adapter.ts

@@ -21,6 +21,8 @@ export interface SpawnOptions {
   env: Record<string, string>;
   /** Team name for window title formatting (e.g., "team: agent") */
   teamName?: string;
+  /** Optional pane ID to anchor pane-based layouts to a specific origin pane */
+  anchorPaneId?: string;
 }
 
 /**