# Lessons

## 2026-06-09: tmux windows vs sessions
- **Symptom:** Enter/Shift+R on sessions did nothing; `tmux list-sessions` only showed main session
- **Cause:** Harness sessions were separate tmux sessions. `switch-client` moves the entire client away. Sessions died silently with no error feedback.
- **Fix:** Redesigned to use windows within a single `hqt-main` session. `select-window` stays in context. `remain-on-exit` + `respawn-pane` handles dead processes cleanly.
- **Signal:** If "attach" ever silently fails again, check: does the tmux target actually exist? Is the error being swallowed?

## General
- tmux `remain-on-exit` must be set BEFORE the command can exit (race condition if set after `new-session`/`new-window`)
- `respawn-pane -k` restarts a dead pane in-place without destroying the window — preferred over kill+recreate
- Always check and propagate tmux command return codes; silent failures are the worst debugging experience