# tmux Provider

Use this provider inside an active tmux client.
A detached session is the fallback when tmux exists but no controllable terminal multiplexer is active.

Check installed syntax with `tmux -V` and `man tmux`.
Use pane IDs such as `%12`, never pane indexes.

## Split and Launch

`COMMAND` must be one correctly shell-quoted command string.

```bash
APP_PANE="$(tmux split-window -h -P -F '#{pane_id}' -t "$TMUX_PANE" -c "$ROOT" "$COMMAND")"
tmux display-message -p -t "$APP_PANE" '#{pane_id} cmd=#{pane_current_command}'
```

Use `-v` instead of `-h` for a lower split.
Keep `APP_PANE` for every later operation.

For a detached fallback:

```bash
SOCKET="terminal-harness-$(date +%s)"
APP_PANE="$(tmux -L "$SOCKET" new-session -d -P -F '#{pane_id}' -s live -n app -c "$ROOT" "$COMMAND")"
tmux -L "$SOCKET" attach -t live
tmux -L "$SOCKET" kill-server
```

Prefix all detached-session operations with `tmux -L "$SOCKET"`.

## Observe

```bash
tmux display-message -p -t "$APP_PANE" '#{pane_id} cmd=#{pane_current_command}'
tmux capture-pane -p -J -t "$APP_PANE" -S -200
```

Alternate-screen TUIs may expose only the current viewport.

## Wait for a State

Poll until a literal marker appears.
The loop returns as soon as the marker shows, a capture failure breaks it, and the `seq` times `sleep` product bounds the wait.

```bash
out=""
for i in $(seq 60); do
  out=$(tmux capture-pane -p -t "$APP_PANE") || break
  printf '%s' "$out" | grep -qF -- "$MARKER" && break
  sleep 5
done
printf '%s' "$out"
```

Match markers with `grep -F` so text like `[ok]` or `done.` is literal, not a regex.
Never park a wait in `sleep N; tmux capture-pane`;
the bash tool timeout is only a kill ceiling, and pi has no key that ends one tool call without aborting the whole turn.

## Input

Literal text and Enter:

```bash
printf '%s' "$TEXT" | tmux load-buffer -
tmux paste-buffer -d -t "$APP_PANE"
tmux send-keys -t "$APP_PANE" Enter
```

Control keys:

```bash
tmux send-keys -t "$APP_PANE" C-c
tmux send-keys -t "$APP_PANE" C-u
```

## Inspect and Close

```bash
tmux select-pane -t "$APP_PANE"
tmux kill-pane -t "$APP_PANE"
```