opencode-agent-tmux 1.2.6 → 1.3.0

package/dist/bin/opencode-tmux.js

@@ -268,7 +268,7 @@ function hasTmux() {
 }
 async function main() {
   const args = argv.slice(2);
-  const isCliCommand = args.length > 0 && (["auth", "config", "plugins", "update", "completion", "stats"].includes(args[0]) || ["--version", "-v", "--help", "-h"].includes(args[0]) || args.includes("--print-logs") || args.includes("--log-level"));
+  const isCliCommand = args.length > 0 && (["auth", "config", "plugins", "update", "completion", "stats"].includes(args[0]) || ["--version", "-v", "--help", "-h"].includes(args[0]));
   if (isCliCommand) {
     const opencodeBin2 = findOpencodeBin();
     if (!opencodeBin2) {

package/dist/index.d.ts

@@ -36,14 +36,26 @@ declare const TmuxConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     layout: z.ZodDefault<z.ZodEnum<["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"]>>;
     main_pane_size: z.ZodDefault<z.ZodNumber>;
+    spawn_delay_ms: z.ZodDefault<z.ZodNumber>;
+    max_retry_attempts: z.ZodDefault<z.ZodNumber>;
+    layout_debounce_ms: z.ZodDefault<z.ZodNumber>;
+    max_agents_per_column: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     enabled: boolean;
     layout: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical";
     main_pane_size: number;
+    spawn_delay_ms: number;
+    max_retry_attempts: number;
+    layout_debounce_ms: number;
+    max_agents_per_column: number;
 }, {
     enabled?: boolean | undefined;
     layout?: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical" | undefined;
     main_pane_size?: number | undefined;
+    spawn_delay_ms?: number | undefined;
+    max_retry_attempts?: number | undefined;
+    layout_debounce_ms?: number | undefined;
+    max_agents_per_column?: number | undefined;
 }>;
 type TmuxConfig = z.infer<typeof TmuxConfigSchema>;
 declare const PluginConfigSchema: z.ZodObject<{
@@ -52,18 +64,30 @@ declare const PluginConfigSchema: z.ZodObject<{
     layout: z.ZodDefault<z.ZodEnum<["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"]>>;
     main_pane_size: z.ZodDefault<z.ZodNumber>;
     auto_close: z.ZodDefault<z.ZodBoolean>;
+    spawn_delay_ms: z.ZodDefault<z.ZodNumber>;
+    max_retry_attempts: z.ZodDefault<z.ZodNumber>;
+    layout_debounce_ms: z.ZodDefault<z.ZodNumber>;
+    max_agents_per_column: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     enabled: boolean;
     port: number;
     layout: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical";
     main_pane_size: number;
     auto_close: boolean;
+    spawn_delay_ms: number;
+    max_retry_attempts: number;
+    layout_debounce_ms: number;
+    max_agents_per_column: number;
 }, {
     enabled?: boolean | undefined;
     port?: number | undefined;
     layout?: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical" | undefined;
     main_pane_size?: number | undefined;
     auto_close?: boolean | undefined;
+    spawn_delay_ms?: number | undefined;
+    max_retry_attempts?: number | undefined;
+    layout_debounce_ms?: number | undefined;
+    max_agents_per_column?: number | undefined;
 }>;
 type PluginConfig = z.infer<typeof PluginConfigSchema>;
 

package/dist/index.js

@@ -14,14 +14,22 @@ var TmuxLayoutSchema = z.enum([
 var TmuxConfigSchema = z.object({
   enabled: z.boolean().default(true),
   layout: TmuxLayoutSchema.default("main-vertical"),
-  main_pane_size: z.number().min(20).max(80).default(60)
+  main_pane_size: z.number().min(20).max(80).default(60),
+  spawn_delay_ms: z.number().min(50).max(2e3).default(300),
+  max_retry_attempts: z.number().min(0).max(5).default(2),
+  layout_debounce_ms: z.number().min(50).max(1e3).default(150),
+  max_agents_per_column: z.number().min(1).max(10).default(3)
 });
 var PluginConfigSchema = z.object({
   enabled: z.boolean().default(true),
   port: z.number().default(4096),
   layout: TmuxLayoutSchema.default("main-vertical"),
   main_pane_size: z.number().min(20).max(80).default(60),
-  auto_close: z.boolean().default(true)
+  auto_close: z.boolean().default(true),
+  spawn_delay_ms: z.number().min(50).max(2e3).default(300),
+  max_retry_attempts: z.number().min(0).max(5).default(2),
+  layout_debounce_ms: z.number().min(50).max(1e3).default(150),
+  max_agents_per_column: z.number().min(1).max(10).default(3)
 });
 var POLL_INTERVAL_MS = 2e3;
 var SESSION_TIMEOUT_MS = 10 * 60 * 1e3;
@@ -42,8 +50,359 @@ function log(message, data) {
   }
 }
 
+// src/spawn-queue.ts
+var BASE_BACKOFF_MS = 250;
+var DEFAULT_STALE_THRESHOLD_MS = 3e4;
+var SpawnQueue = class {
+  queue = [];
+  spawnFn;
+  spawnDelayMs;
+  maxRetries;
+  staleThresholdMs;
+  onQueueUpdate;
+  onQueueDrained;
+  logFn;
+  isProcessing = false;
+  hasItemInFlight = false;
+  isShutdown = false;
+  /**
+   * Map from sessionId to a pending promise for coalescing duplicate enqueues.
+   * Contains both queued and in-flight items.
+   */
+  pendingPromises = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.spawnFn = options.spawnFn;
+    this.spawnDelayMs = options.spawnDelayMs ?? 300;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+    this.onQueueUpdate = options.onQueueUpdate;
+    this.onQueueDrained = options.onQueueDrained;
+    this.logFn = options.logFn ?? log;
+    this.logFn("[spawn-queue] initialized", {
+      spawnDelayMs: this.spawnDelayMs,
+      maxRetries: this.maxRetries,
+      staleThresholdMs: this.staleThresholdMs
+    });
+  }
+  enqueue(item) {
+    if (this.isShutdown) {
+      this.logFn("[spawn-queue] enqueue rejected (shutdown)", { sessionId: item.sessionId });
+      return Promise.resolve({ success: false });
+    }
+    const existing = this.pendingPromises.get(item.sessionId);
+    if (existing) {
+      this.logFn("[spawn-queue] duplicate enqueue coalesced", {
+        sessionId: item.sessionId,
+        queueDepth: this.queue.length,
+        pendingCount: this.getPendingCount()
+      });
+      return existing.promise;
+    }
+    let resolveOuter;
+    const promise = new Promise((resolve) => {
+      resolveOuter = resolve;
+    });
+    this.pendingPromises.set(item.sessionId, { promise, resolve: resolveOuter });
+    this.queue.push({
+      sessionId: item.sessionId,
+      title: item.title,
+      enqueuedAt: Date.now(),
+      resolve: resolveOuter
+    });
+    this.logFn("[spawn-queue] enqueued", {
+      sessionId: item.sessionId,
+      queueDepth: this.queue.length,
+      pendingCount: this.getPendingCount()
+    });
+    this.notifyQueueUpdate();
+    this.processQueue();
+    return promise;
+  }
+  getPendingCount() {
+    return this.queue.length + (this.hasItemInFlight ? 1 : 0);
+  }
+  /**
+   * Shutdown the queue: stop processing new items and resolve all pending items as failed.
+   */
+  shutdown() {
+    if (this.isShutdown) {
+      return;
+    }
+    this.isShutdown = true;
+    this.logFn("[spawn-queue] shutdown initiated", {
+      queuedItems: this.queue.length,
+      hasInFlight: this.hasItemInFlight
+    });
+    while (this.queue.length > 0) {
+      const item = this.queue.shift();
+      this.logFn("[spawn-queue] shutdown - resolving queued item as failed", {
+        sessionId: item.sessionId
+      });
+      item.resolve({ success: false });
+      this.pendingPromises.delete(item.sessionId);
+    }
+    this.notifyQueueUpdate();
+    this.logFn("[spawn-queue] shutdown complete");
+  }
+  /**
+   * Alias for shutdown() for interface consistency.
+   */
+  dispose() {
+    this.shutdown();
+  }
+  notifyQueueUpdate() {
+    this.onQueueUpdate?.(this.queue.length);
+  }
+  async processQueue() {
+    if (this.isProcessing || this.isShutdown) {
+      return;
+    }
+    this.isProcessing = true;
+    while (this.queue.length > 0 && !this.isShutdown) {
+      const item = this.queue.shift();
+      this.hasItemInFlight = true;
+      this.notifyQueueUpdate();
+      const waitTimeMs = Date.now() - item.enqueuedAt;
+      if (waitTimeMs > this.staleThresholdMs) {
+        this.logFn("[spawn-queue] stale item skipped", {
+          sessionId: item.sessionId,
+          waitTimeMs,
+          thresholdMs: this.staleThresholdMs
+        });
+        item.resolve({ success: false });
+        this.pendingPromises.delete(item.sessionId);
+        this.hasItemInFlight = false;
+        continue;
+      }
+      this.logFn("[spawn-queue] processing start", {
+        sessionId: item.sessionId,
+        title: item.title
+      });
+      const result = await this.processItem(item);
+      item.resolve(result);
+      this.pendingPromises.delete(item.sessionId);
+      this.hasItemInFlight = false;
+      if (this.queue.length > 0 && !this.isShutdown) {
+        await this.delay(this.spawnDelayMs);
+      }
+    }
+    this.notifyQueueUpdate();
+    this.notifyQueueDrained();
+    this.isProcessing = false;
+  }
+  notifyQueueDrained() {
+    if (this.queue.length === 0 && !this.hasItemInFlight) {
+      this.logFn("[spawn-queue] queue drained");
+      this.onQueueDrained?.();
+    }
+  }
+  async processItem(item) {
+    let retryCount = 0;
+    let lastResult = { success: false };
+    while (retryCount <= this.maxRetries && !this.isShutdown) {
+      const request = {
+        sessionId: item.sessionId,
+        title: item.title,
+        timestamp: item.enqueuedAt,
+        retryCount
+      };
+      this.logFn("[spawn-queue] spawn attempt", {
+        sessionId: item.sessionId,
+        attempt: retryCount + 1,
+        maxAttempts: this.maxRetries + 1
+      });
+      try {
+        lastResult = await this.spawnFn(request);
+      } catch {
+        lastResult = { success: false };
+      }
+      if (lastResult.success) {
+        this.logFn("[spawn-queue] success", {
+          sessionId: item.sessionId,
+          paneId: lastResult.paneId,
+          attempts: retryCount + 1
+        });
+        return lastResult;
+      }
+      retryCount++;
+      if (retryCount <= this.maxRetries && !this.isShutdown) {
+        const backoffMs = BASE_BACKOFF_MS * Math.pow(2, retryCount - 1);
+        this.logFn("[spawn-queue] retry wait", {
+          sessionId: item.sessionId,
+          backoffMs,
+          nextAttempt: retryCount + 1
+        });
+        await this.delay(backoffMs);
+      }
+    }
+    this.logFn("[spawn-queue] final failure", {
+      sessionId: item.sessionId,
+      attempts: retryCount
+    });
+    return lastResult;
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
 // src/utils/tmux.ts
 import { spawn } from "child_process";
+
+// src/layout.ts
+function computeColumnCount(totalAgents, maxAgentsPerColumn) {
+  if (totalAgents <= 0) {
+    return 0;
+  }
+  if (maxAgentsPerColumn <= 0) {
+    throw new Error("maxAgentsPerColumn must be positive");
+  }
+  return Math.ceil(totalAgents / maxAgentsPerColumn);
+}
+function distributeAgentsRoundRobin(agentCount, maxAgentsPerColumn) {
+  const numColumns = computeColumnCount(agentCount, maxAgentsPerColumn);
+  if (numColumns === 0) {
+    return { numColumns: 0, columnAssignments: [] };
+  }
+  const columnAssignments = [];
+  for (let i = 0; i < agentCount; i++) {
+    columnAssignments.push(i % numColumns);
+  }
+  return { numColumns, columnAssignments };
+}
+function groupAgentsByColumn(agentIds, maxAgentsPerColumn) {
+  const { numColumns, columnAssignments } = distributeAgentsRoundRobin(
+    agentIds.length,
+    maxAgentsPerColumn
+  );
+  if (numColumns === 0) {
+    return [];
+  }
+  const columns = Array.from({ length: numColumns }, () => []);
+  for (let i = 0; i < agentIds.length; i++) {
+    const columnIndex = columnAssignments[i];
+    columns[columnIndex].push(agentIds[i]);
+  }
+  return columns;
+}
+function mainPanePercentForColumns(numColumns) {
+  if (numColumns <= 1) return 60;
+  if (numColumns === 2) return 45;
+  return 30;
+}
+function layoutChecksum(layout) {
+  let csum = 0;
+  for (let i = 0; i < layout.length; i++) {
+    csum = (csum >> 1) + ((csum & 1) << 15);
+    csum = csum + layout.charCodeAt(i) & 65535;
+  }
+  return csum;
+}
+function dumpLayoutCell(cell) {
+  const base = cell.wpId !== void 0 ? `${cell.sx}x${cell.sy},${cell.xoff},${cell.yoff},${cell.wpId}` : `${cell.sx}x${cell.sy},${cell.xoff},${cell.yoff}`;
+  if (cell.type === "WINDOWPANE") {
+    return base;
+  }
+  const children = cell.children ?? [];
+  const open = cell.type === "LEFTRIGHT" ? "{" : "[";
+  const close = cell.type === "LEFTRIGHT" ? "}" : "]";
+  return `${base}${open}${children.map(dumpLayoutCell).join(",")}${close}`;
+}
+function splitSizes(total, count) {
+  if (count <= 0) return [];
+  const separators = count - 1;
+  const available = Math.max(0, total - separators);
+  const base = Math.floor(available / count);
+  const remainder = available - base * count;
+  const out = [];
+  for (let i = 0; i < count; i++) {
+    out.push(base + (i < remainder ? 1 : 0));
+  }
+  return out;
+}
+function buildMainVerticalMultiColumnLayoutString(params) {
+  const { windowWidth, windowHeight, mainPaneWpId, columns, mainPanePercent } = params;
+  const numColumns = columns.length;
+  if (numColumns <= 0) {
+    throw new Error("columns must be non-empty");
+  }
+  const clampedPercent = Math.max(30, Math.min(80, mainPanePercent));
+  const desiredMainWidth = Math.floor(windowWidth * clampedPercent / 100);
+  const mainWidth = Math.max(0, Math.min(windowWidth - 2, desiredMainWidth));
+  const rightWidth = Math.max(0, windowWidth - mainWidth - 1);
+  const mainCell = {
+    type: "WINDOWPANE",
+    sx: mainWidth,
+    sy: windowHeight,
+    xoff: 0,
+    yoff: 0,
+    wpId: mainPaneWpId
+  };
+  const rightXoff = mainWidth + 1;
+  const colWidths = splitSizes(rightWidth, numColumns);
+  const columnCells = [];
+  let xoff = rightXoff;
+  for (let c = 0; c < numColumns; c++) {
+    const colPaneIds = columns[c];
+    const colWidth = colWidths[c] ?? 0;
+    if (colPaneIds.length === 1) {
+      columnCells.push({
+        type: "WINDOWPANE",
+        sx: colWidth,
+        sy: windowHeight,
+        xoff,
+        yoff: 0,
+        wpId: colPaneIds[0]
+      });
+    } else {
+      const rowHeights = splitSizes(windowHeight, colPaneIds.length);
+      const rows = [];
+      let yoff = 0;
+      for (let r = 0; r < colPaneIds.length; r++) {
+        rows.push({
+          type: "WINDOWPANE",
+          sx: colWidth,
+          sy: rowHeights[r] ?? 0,
+          xoff,
+          yoff,
+          wpId: colPaneIds[r]
+        });
+        yoff += (rowHeights[r] ?? 0) + 1;
+      }
+      columnCells.push({
+        type: "TOPBOTTOM",
+        sx: colWidth,
+        sy: windowHeight,
+        xoff,
+        yoff: 0,
+        children: rows
+      });
+    }
+    xoff += colWidth + 1;
+  }
+  const rightCell = numColumns === 1 ? columnCells[0] : {
+    type: "LEFTRIGHT",
+    sx: rightWidth,
+    sy: windowHeight,
+    xoff: rightXoff,
+    yoff: 0,
+    children: columnCells
+  };
+  const root = {
+    type: "LEFTRIGHT",
+    sx: windowWidth,
+    sy: windowHeight,
+    xoff: 0,
+    yoff: 0,
+    children: [mainCell, rightCell]
+  };
+  const layout = dumpLayoutCell(root);
+  const checksum = layoutChecksum(layout);
+  return `${checksum.toString(16).padStart(4, "0")},${layout}`;
+}
+
+// src/utils/tmux.ts
+var BASE_BACKOFF_MS2 = 250;
 var tmuxPath = null;
 var tmuxChecked = false;
 var storedConfig = null;
@@ -115,7 +474,7 @@ async function findTmuxPath() {
   const isWindows = process.platform === "win32";
   const cmd = isWindows ? "where" : "which";
   try {
-    const result = await spawnAsync([cmd, "tmux"]);
+    const result = await spawnAsyncFn([cmd, "tmux"]);
     if (result.exitCode !== 0) {
       log("[tmux] findTmuxPath: 'which tmux' failed", {
         exitCode: result.exitCode
@@ -127,7 +486,7 @@ async function findTmuxPath() {
       log("[tmux] findTmuxPath: no path in output");
       return null;
     }
-    const verifyResult = await spawnAsync([path3, "-V"]);
+    const verifyResult = await spawnAsyncFn([path3, "-V"]);
     if (verifyResult.exitCode !== 0) {
       log("[tmux] findTmuxPath: tmux -V failed", {
         path: path3,
@@ -156,22 +515,173 @@ function isInsideTmux() {
 }
 async function applyLayout(tmux, layout, mainPaneSize) {
   try {
-    await spawnAsync([tmux, "select-layout", layout]);
+    await spawnAsyncFn([tmux, "select-layout", layout]);
     if (layout === "main-horizontal" || layout === "main-vertical") {
       const sizeOption = layout === "main-horizontal" ? "main-pane-height" : "main-pane-width";
-      await spawnAsync([
+      await spawnAsyncFn([
         tmux,
         "set-window-option",
         sizeOption,
         `${mainPaneSize}%`
       ]);
-      await spawnAsync([tmux, "select-layout", layout]);
+      await spawnAsyncFn([tmux, "select-layout", layout]);
     }
     log("[tmux] applyLayout: applied", { layout, mainPaneSize });
   } catch (err) {
     log("[tmux] applyLayout: exception", { error: String(err) });
   }
 }
+async function getCurrentPaneId(tmux) {
+  const result = await spawnAsyncFn([tmux, "display-message", "-p", "#{pane_id}"]);
+  const paneId = result.stdout.trim();
+  return paneId ? paneId : null;
+}
+async function getWindowSize(tmux) {
+  const result = await spawnAsyncFn([
+    tmux,
+    "display-message",
+    "-p",
+    "#{window_width} #{window_height}"
+  ]);
+  const parts = result.stdout.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  const width = Number(parts[0]);
+  const height = Number(parts[1]);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  return { width, height };
+}
+async function listPaneIds(tmux) {
+  const result = await spawnAsyncFn([tmux, "list-panes", "-F", "#{pane_id}"]);
+  return result.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function paneWpId(paneId) {
+  if (!paneId.startsWith("%")) return null;
+  const n = Number(paneId.slice(1));
+  return Number.isFinite(n) ? n : null;
+}
+async function tryApplyMainVerticalMultiColumnLayout(tmux, maxAgentsPerColumn) {
+  const size = await getWindowSize(tmux);
+  if (!size) return false;
+  const currentPaneId = await getCurrentPaneId(tmux);
+  if (!currentPaneId) return false;
+  const panesBefore = await listPaneIds(tmux);
+  if (panesBefore.length < 2) return false;
+  if (panesBefore[0] && panesBefore[0] !== currentPaneId) {
+    await spawnAsyncFn([tmux, "swap-pane", "-s", currentPaneId, "-t", panesBefore[0]]);
+  }
+  const panes = await listPaneIds(tmux);
+  if (panes.length < 2) return false;
+  const mainPaneId = panes[0] ?? currentPaneId;
+  const agentPaneIds = panes.slice(1);
+  const columns = groupAgentsByColumn(agentPaneIds, maxAgentsPerColumn);
+  if (columns.length <= 1) {
+    return false;
+  }
+  const mainPanePercent = mainPanePercentForColumns(columns.length);
+  const mainWp = paneWpId(mainPaneId);
+  if (mainWp === null) return false;
+  const wpColumns = [];
+  for (const col of columns) {
+    const wpIds = [];
+    for (const paneId of col) {
+      const wpId = paneWpId(paneId);
+      if (wpId !== null) {
+        wpIds.push(wpId);
+      }
+    }
+    if (wpIds.length > 0) {
+      wpColumns.push(wpIds);
+    }
+  }
+  if (wpColumns.length <= 1) return false;
+  const layoutString = buildMainVerticalMultiColumnLayoutString({
+    windowWidth: size.width,
+    windowHeight: size.height,
+    mainPaneWpId: mainWp,
+    columns: wpColumns,
+    mainPanePercent
+  });
+  const result = await spawnAsyncFn([tmux, "select-layout", layoutString]);
+  if (result.exitCode === 0) {
+    log("[tmux] applyTmuxLayout: applied multi-column layout", {
+      columns: wpColumns.length,
+      mainPanePercent
+    });
+    return true;
+  }
+  log("[tmux] applyTmuxLayout: multi-column layout failed", {
+    exitCode: result.exitCode,
+    stderr: result.stderr.trim()
+  });
+  return false;
+}
+async function applyTmuxLayout() {
+  if (!storedConfig) {
+    log("[tmux] applyTmuxLayout: no stored config, skipping");
+    return;
+  }
+  const tmux = await getTmuxPath();
+  if (!tmux) {
+    log("[tmux] applyTmuxLayout: tmux binary not found");
+    return;
+  }
+  const layout = storedConfig.layout ?? "main-vertical";
+  const maxAgentsPerColumn = storedConfig.max_agents_per_column ?? 3;
+  const mainPaneSize = layout === "main-vertical" ? mainPanePercentForColumns(1) : storedConfig.main_pane_size ?? 60;
+  try {
+    if (layout === "main-vertical") {
+      const applied = await tryApplyMainVerticalMultiColumnLayout(
+        tmux,
+        maxAgentsPerColumn
+      );
+      if (applied) {
+        return;
+      }
+    }
+    await applyLayout(tmux, layout, mainPaneSize);
+  } catch (err) {
+    log("[tmux] applyTmuxLayout: failed, falling back to built-in layout", {
+      error: String(err)
+    });
+    try {
+      await spawnAsyncFn([tmux, "select-layout", layout === "tiled" ? "tiled" : "main-vertical"]);
+    } catch (fallbackErr) {
+      log("[tmux] applyTmuxLayout: fallback also failed", { error: String(fallbackErr) });
+    }
+  }
+}
+var spawnAsyncFn = spawnAsync;
+async function attemptSpawnPane(sessionId, description, config, tmux, serverUrl) {
+  const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`;
+  const args = [
+    "split-window",
+    "-h",
+    "-d",
+    "-P",
+    "-F",
+    "#{pane_id}",
+    opencodeCmd
+  ];
+  log("[tmux] attemptSpawnPane: executing", { tmux, args, opencodeCmd });
+  const result = await spawnAsyncFn([tmux, ...args]);
+  const paneId = result.stdout.trim();
+  log("[tmux] attemptSpawnPane: split result", {
+    exitCode: result.exitCode,
+    paneId,
+    stderr: result.stderr.trim()
+  });
+  if (result.exitCode === 0 && paneId) {
+    await spawnAsyncFn(
+      [tmux, "select-pane", "-t", paneId, "-T", description.slice(0, 30)],
+      { ignoreOutput: true }
+    );
+    log("[tmux] attemptSpawnPane: SUCCESS, pane created", {
+      paneId
+    });
+    return { success: true, paneId };
+  }
+  return { success: false };
+}
 async function spawnTmuxPane(sessionId, description, config, serverUrl) {
   log("[tmux] spawnTmuxPane called", {
     sessionId,
@@ -202,44 +712,35 @@ async function spawnTmuxPane(sessionId, description, config, serverUrl) {
     return { success: false };
   }
   storedConfig = config;
-  try {
-    const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`;
-    const args = [
-      "split-window",
-      "-h",
-      "-d",
-      "-P",
-      "-F",
-      "#{pane_id}",
-      opencodeCmd
-    ];
-    log("[tmux] spawnTmuxPane: executing", { tmux, args, opencodeCmd });
-    const result = await spawnAsync([tmux, ...args]);
-    const paneId = result.stdout.trim();
-    log("[tmux] spawnTmuxPane: split result", {
-      exitCode: result.exitCode,
-      paneId,
-      stderr: result.stderr.trim()
-    });
-    if (result.exitCode === 0 && paneId) {
-      await spawnAsync(
-        [tmux, "select-pane", "-t", paneId, "-T", description.slice(0, 30)],
-        { ignoreOutput: true }
-      );
-      const layout = config.layout ?? "main-vertical";
-      const mainPaneSize = config.main_pane_size ?? 60;
-      await applyLayout(tmux, layout, mainPaneSize);
-      log("[tmux] spawnTmuxPane: SUCCESS, pane created and layout applied", {
-        paneId,
-        layout
+  const maxRetries = config.max_retry_attempts ?? 2;
+  let attempt = 0;
+  let lastResult = { success: false };
+  while (attempt <= maxRetries) {
+    try {
+      lastResult = await attemptSpawnPane(sessionId, description, config, tmux, serverUrl);
+      if (lastResult.success) {
+        return lastResult;
+      }
+      log("[tmux] spawnTmuxPane: attempt failed", {
+        attempt: attempt + 1,
+        maxRetries
       });
-      return { success: true, paneId };
+    } catch (err) {
+      log("[tmux] spawnTmuxPane: exception on attempt", {
+        attempt: attempt + 1,
+        error: String(err)
+      });
+      lastResult = { success: false };
+    }
+    attempt++;
+    if (attempt <= maxRetries) {
+      const backoffMs = BASE_BACKOFF_MS2 * Math.pow(2, attempt - 1);
+      log("[tmux] spawnTmuxPane: waiting before retry", { backoffMs, attempt });
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
     }
-    return { success: false };
-  } catch (err) {
-    log("[tmux] spawnTmuxPane: exception", { error: String(err) });
-    return { success: false };
   }
+  log("[tmux] spawnTmuxPane: all retries exhausted", { attempts: attempt });
+  return lastResult;
 }
 async function closeTmuxPane(paneId) {
   log("[tmux] closeTmuxPane called", { paneId });
@@ -260,12 +761,7 @@ async function closeTmuxPane(paneId) {
     });
     if (result.exitCode === 0) {
       log("[tmux] closeTmuxPane: SUCCESS, pane closed", { paneId });
-      if (storedConfig) {
-        const layout = storedConfig.layout ?? "main-vertical";
-        const mainPaneSize = storedConfig.main_pane_size ?? 60;
-        await applyLayout(tmux, layout, mainPaneSize);
-        log("[tmux] closeTmuxPane: layout reapplied", { layout });
-      }
+      await applyTmuxLayout();
       return true;
     }
     log("[tmux] closeTmuxPane: failed (pane may already be closed)", {
@@ -293,11 +789,24 @@ var TmuxSessionManager = class {
   pollInterval;
   enabled = false;
   shuttingDown = false;
+  spawnQueue;
+  layoutDebounceTimer;
   constructor(ctx, tmuxConfig, serverUrl) {
     this.client = ctx.client;
     this.tmuxConfig = tmuxConfig;
     this.serverUrl = serverUrl;
     this.enabled = tmuxConfig.enabled && isInsideTmux();
+    this.spawnQueue = new SpawnQueue({
+      spawnFn: (request) => spawnTmuxPane(request.sessionId, request.title, this.tmuxConfig, this.serverUrl),
+      spawnDelayMs: tmuxConfig.spawn_delay_ms,
+      maxRetries: 0,
+      onQueueUpdate: (pendingCount) => {
+        log("[tmux-session-manager] queue update", { pendingCount });
+      },
+      onQueueDrained: () => {
+        this.scheduleDebouncedLayout();
+      }
+    });
     log("[tmux-session-manager] initialized", {
       enabled: this.enabled,
       tmuxConfig: this.tmuxConfig,
@@ -326,17 +835,7 @@ var TmuxSessionManager = class {
       parentId,
       title
     });
-    const paneResult = await spawnTmuxPane(
-      sessionId,
-      title,
-      this.tmuxConfig,
-      this.serverUrl
-    ).catch((err) => {
-      log("[tmux-session-manager] failed to spawn pane", {
-        error: String(err)
-      });
-      return { success: false, paneId: void 0 };
-    });
+    const paneResult = await this.spawnQueue.enqueue({ sessionId, title });
     if (paneResult.success && paneResult.paneId) {
       const now = Date.now();
       this.sessions.set(sessionId, {
@@ -352,6 +851,8 @@ var TmuxSessionManager = class {
         paneId: paneResult.paneId
       });
       this.startPolling();
+    } else {
+      log("[tmux-session-manager] failed to spawn pane", { sessionId });
     }
   }
   startPolling() {
@@ -369,6 +870,16 @@ var TmuxSessionManager = class {
       log("[tmux-session-manager] polling stopped");
     }
   }
+  scheduleDebouncedLayout() {
+    if (this.layoutDebounceTimer) {
+      clearTimeout(this.layoutDebounceTimer);
+    }
+    const debounceMs = this.tmuxConfig.layout_debounce_ms ?? 150;
+    this.layoutDebounceTimer = setTimeout(() => {
+      log("[tmux-session-manager] applying deferred layout after queue drain");
+      void applyTmuxLayout();
+    }, debounceMs);
+  }
   async pollSessions() {
     if (this.sessions.size === 0) {
       this.stopPolling();
@@ -456,6 +967,11 @@ var TmuxSessionManager = class {
   }
   async cleanup() {
     this.stopPolling();
+    this.spawnQueue.shutdown();
+    if (this.layoutDebounceTimer) {
+      clearTimeout(this.layoutDebounceTimer);
+      this.layoutDebounceTimer = void 0;
+    }
     if (this.sessions.size > 0) {
       log("[tmux-session-manager] closing all panes", {
         count: this.sessions.size
@@ -520,7 +1036,11 @@ var OpencodeAgentTmux = async (ctx) => {
   const tmuxConfig = {
     enabled: config.enabled,
     layout: config.layout,
-    main_pane_size: config.main_pane_size
+    main_pane_size: config.main_pane_size,
+    spawn_delay_ms: config.spawn_delay_ms,
+    max_retry_attempts: config.max_retry_attempts,
+    layout_debounce_ms: config.layout_debounce_ms,
+    max_agents_per_column: config.max_agents_per_column
   };
   const serverUrl = ctx.serverUrl?.toString() || detectServerUrl();
   log("[plugin] initialized", {

package/dist/scripts/update-plugins.js

@@ -72,18 +72,28 @@ function saveConfig(config) {
   }
 }
 function ensurePluginEntry(config) {
-  const existing = Array.isArray(config.plugins) ? [...config.plugins] : [];
+  const existingPlugin = Array.isArray(config.plugin) ? [...config.plugin] : [];
+  const existingPlugins = Array.isArray(config.plugins) ? [...config.plugins] : [];
+  const existing = [...existingPlugin, ...existingPlugins];
   const normalized = existing.map(
-    (plugin) => plugin === "opencode-subagent-tmux" ? "opencode-agent-tmux" : plugin
+    (entry) => entry === "opencode-subagent-tmux" ? "opencode-agent-tmux" : entry
   );
-  if (!normalized.includes("opencode-agent-tmux")) {
-    normalized.push("opencode-agent-tmux");
+  const deduped = [];
+  for (const entry of normalized) {
+    if (!deduped.includes(entry)) {
+      deduped.push(entry);
+    }
+  }
+  if (!deduped.includes("opencode-agent-tmux")) {
+    deduped.push("opencode-agent-tmux");
   }
-  if (JSON.stringify(existing) !== JSON.stringify(normalized)) {
-    config.plugins = normalized;
+  const changed = JSON.stringify(existingPlugin) !== JSON.stringify(deduped) || "plugins" in config;
+  if (changed) {
+    config.plugin = deduped;
+    delete config.plugins;
     saveConfig(config);
   }
-  return normalized;
+  return deduped;
 }
 function installLatest(plugins) {
   const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-tmux",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "OpenCode plugin that provides tmux integration for viewing agent execution in real-time",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +15,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "bun test",
     "prepublishOnly": "bun run build",
     "postinstall": "test -f dist/scripts/install.js && node dist/scripts/install.js || echo 'Skipping postinstall setup (dist not found)'"
   },
@@ -35,11 +36,13 @@
   },
   "homepage": "https://github.com/AnganSamadder/opencode-agent-tmux#readme",
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/bun": "^1.2.4",
     "@types/node": "^25.0.10",
+    "@types/proper-lockfile": "^4.1.4",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3"
   }