tmux Provider
Use an active tmux client when available; otherwise create a detached session and drive it through tmux commands. Human attachment is optional and never a prerequisite for testing.
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.
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:
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" display-message -p -t "$APP_PANE" '#{pane_id} cmd=#{pane_current_command}'
tmux -L "$SOCKET" capture-pane -p -t "$APP_PANE"
Prefix all detached-session operations with tmux -L "$SOCKET".
Observe
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.
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:
printf '%s' "$TEXT" | tmux load-buffer -
tmux paste-buffer -d -t "$APP_PANE"
tmux send-keys -t "$APP_PANE" Enter
Control keys:
tmux send-keys -t "$APP_PANE" C-c
tmux send-keys -t "$APP_PANE" C-u
Inspect and Close
tmux select-pane -t "$APP_PANE"
tmux kill-pane -t "$APP_PANE"
After testing, shut down a test-owned detached server when no longer needed:
tmux -L "$SOCKET" kill-server