AGENTS.md@packages/omo-opencode/src/features/tmux-subagent git:20260824.f7cdde8A

Immutable. This exact content is served forever at /api/v1/blob/d25e261539a5e624.

# src/features/tmux-subagent/ — Tmux Pane Management

**Generated:** 2026-05-15

## OVERVIEW

This module provides state-first tmux integration for background agent sessions (~48 files incl. colocated tests). It handles split decisions, grid planning, polling, and lifecycle events. Reusable tmux command, layout, and pane primitives are extracted to [`packages/tmux-core/`](../../../../../packages/tmux-core); this directory is the OpenCode session adapter.

## CORE ARCHITECTURE

```
TmuxSessionManager (manager.ts)
  ├─→ DecisionEngine: Should we spawn/close panes?
  ├─→ ActionExecutor: Execute spawn/close/replace actions
  ├─→ PollingManager: Monitor pane health
  └─→ EventHandlers: React to session create/delete
```

All tmux command execution is centralized through the shared `runTmuxCommand` runner (via the local adapter shim). Do NOT add direct `Bun.spawn([tmux,...])` calls in this module. They will drift from the retry/timeout/terminal-error discipline.

## KEY FILES

| File | Purpose |
|------|---------|
| `manager.ts` | `TmuxSessionManager` — main class, session tracking, event routing |
| `decision-engine.ts` | Evaluate window state → produce `SpawnDecision` with actions |
| `action-executor.ts` | Execute `PaneAction[]` (close, spawn, replace) |
| `grid-planning.ts` | Calculate pane layout given window dimensions |
| `spawn-action-decider.ts` | Decide spawn vs replace vs skip |
| `spawn-target-finder.ts` | Find best pane to split or replace |
| `polling-manager.ts` | Health polling for tracked sessions |
| `types.ts` | `TrackedSession`, `WindowState`, `PaneAction`, `SpawnDecision` |

## PANE LIFECYCLE

```
session.created → spawn-action-decider → grid-planning → action-executor → track session
session.deleted → cleanup tracked session → close pane if empty
```

## LAYOUT CONSTRAINTS

- `MIN_PANE_WIDTH`: 52 chars
- `MIN_PANE_HEIGHT`: 11 lines
- Grid limits: 2 columns, 3 rows, max grid size 4
- Main pane preserved (never split below minimum)
- Agent panes split from remaining space

## ISOLATION MODES

Supports `inline` (panes in the current window), `window` (dedicated window), and `session` (isolated tmux session). Cmux-compatible/headless environments are detected (`isCmuxCompatEnvironment`) and degrade to deferred-attach queues with readiness TTLs; never-activated panes hit a hard timeout via `polling-manager.ts`.

## EVENT HANDLERS

| File | Event |
|------|-------|
| `session-created-handler.ts` | New background session → spawn pane |
| `session-deleted-handler.ts` | Session ended → close pane |
| `session-created-event.ts` | Event type definition |