@cotal-ai/tmux

The tmux integration: a thin driver over the tmux CLI (open/close a window, send keys) plus a self-registering tmux Runtime provider. Importing it registers the runtime with the core Registry, so the manager can spawn agents into tmux windows without depending on this package.

Tier: extensions/. Peer-depends @cotal-ai/core; self-registers on import.

What it does

• Runtime (tmux): each agent gets its own window in a shared per-space tmux session (cotal-<space>). Spawned unfocused; switch to session:name to watch it. Env is isolated (env -i) so the tmux server's environment doesn't reach agents. That env is written to an owner-only launch script, which keeps it off tmux's command line, and the script removes its directory before it starts the agent. When it cannot remove the directory, the agent does not start. Graceful stop types /exit then closes the seat's pane; hard stop closes that pane immediately. Stop and interrupt follow the pane when it moves between windows. Their tmux commands check the opening server's identity, including the delayed graceful close, so a replacement server cannot receive an old handle's input or close. Status and exit waits bind the pane to that server too. Native attach guidance selects the seat's current window and pane by its stable pane ID, so moving the pane or renaming its window does not redirect the operator to another seat. A dead server proves exit; an unreachable recorded server that still runs remains unknown. Exit waits honor tmux's pane_dead state, including remain-on-exit; provider errors fail the wait closed. Direct window closes still accept only tmux's own gone-window/session reports. Each handle carries a reference to its tmux server, window and pane, so a later manager can reap the seat after the one that spawned it is gone. The reap closes the window while the session still holds it, even when the agent's pane already exited. It refuses a pane that has moved out of that window, whether it still runs or has exited, and a window that has moved out of the session, including one that moves while the reap runs.

Session-name, pane-capture, session-creation, window-selection and text/key delivery failures name the operation, include tmux's error text and retain the failed call as cause. A failed capture returns no screen only when the pane's exit is confirmed. A failed exit probe still throws. Runtime spawn refusals also carry the session-creation reason.

The package tests include native write controls on a fresh private socket when tmux is installed. They check failure diagnostics, successful delivery and the server-identity fence without using operator sessions.

Usage

cotal ext add @cotal-ai/tmux
cotal supervise --runtime tmux

Library composition roots can instead import it explicitly:

import "@cotal-ai/tmux"; // self-registers; no other setup needed

Differences from @cotal-ai/cmux

cmux opens a per-agent workspace (tab) in the cmux app; this package opens a per-agent window in a tmux session. Both are native-watch (no PTY streaming). No cli.ts helper is included: the driver runs the tmux on PATH and needs no bundled binary path.

See docs/architecture.mdx (Manager supervision) and the root AGENTS.md for the tier rules.

The launcher contract checks in package.smoke.ts are POSIX-only. On Windows they use the shared skipSuite helper to report a skip with zero passing cells.