Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Terminal session state machine (root-cause refactor)
Why
PR #659's terminal backend drew four straight review rounds (7–10) of P2 bugs that are all the same root cause: session state was split across three collections kept consistent by hand —
_connections: dict[str, TerminalConnection](attached)_detached_tmux_sessions: dict[str, float](detached, value = detach time)_reserved_sessions: set[str](mid-open)
…and the max_sessions cap was computed by summing all three with ad-hoc subtractions
(- existing, - reconnecting_detached). Every bug was "these collections got out of sync"
or "a transition wasn't atomic":
| Round | Symptom | Real cause |
|---|---|---|
| 7 | detach not tracked when client exits | transition gap |
| 8 | cancel-after-spawn leak; concurrent-reconnect overwrite; dead session marked detached | three collections desync |
| 9 | replace doesn't clear detached; recheck before recording | desync |
| 10 | open-fail drops detached; superseded marked detached | desync + cap arithmetic |
A second, smaller entanglement: _cleanup_connection() did two jobs at once — released
the OS client (fd + signal) and mutated _detached_tmux_sessions. That coupling is why
every caller (open/close/reaper/shutdown) had to reason about bookkeeping side effects.
The fix (one model, one owner per concern)
1. One registry, one entry per id, explicit phase.
_Phase = OPENING | ATTACHED | DETACHED
_Session(session_id, phase, persistent, connection?, detached_at?)
self._sessions: dict[str, _Session] # the ONLY collection
- Capacity =
len(self._sessions). A reconnect (id already present) reuses its slot; only a brand-new id is checked against the cap. No subtraction arithmetic → the round-8/9/10 cap bugs are gone by construction. - One dict key per id → double-counting is structurally impossible.
- DETACHED→OPENING→ATTACHED is the same entry transitioning in place → no "stale second entry / forgot to clear the other collection" class.
2. Separate OS teardown from registry bookkeeping.
_teardown_client(connection, *, kill_session)— fd + signal only, never touches_sessions.- All
_sessionstransitions happen inopen/close/reap_idle/shutdown, under the lock, as explicit moves with compare-and-set identity checks.
How each prior bug becomes impossible
- Concurrent reconnect:
openrejects when the slot is alreadyOPENING; a second open can never mutate someone else's OPENING entry. - Superseded client marked detached:
closeonly transitions whenslot.connection is connection(identity CAS); a newer connection owning the id is left untouched. - Open-fail drops a live detached session: failure path (
_abandon_open) reconciles the OPENING slot againsttmux has-session— re-tracks DETACHED if the session is alive, drops the placeholder otherwise. - Cancel-after-spawn leak: same failure path tears the spawned child down and reconciles.
- Detach vs. shell-exit:
closerecords DETACHED only whenpersistent and has-session.
Scope / safety
- Internal only. Public API (
open→TerminalConnection,close,resize,handle_websocket,shutdown,reap_idle,start_reaper) is unchanged;ui_serverand the WS pumps are untouched. No external reference to the old private collections. - The accumulated terminal tests (round-trip, reconnect-replaces, reserve-during-spawn,
ready-frame-fail, cancel-releases-slot, detach tracking, superseded, open-fail-preserves-
detached) are the regression net; internal-state assertions are re-pointed at
_sessions.
Files
core/terminal_service.py— the refactor.tests/test_terminal_backend.py— re-point internal assertions; keep behavior tests.
The symlink-over-target P1 (file_browser) is a separate, genuine fix handled in parallel.