headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/persistent-terminal-sessions/design.md

## Context

Currently, terminal sessions are ephemeral. Each WebSocket connection to `/ws/tool-instances/{instance_id}/terminal` spawns a new `docker exec` process via `TerminalManager.create_session()`. When the WebSocket disconnects, the session is cleaned up and the `docker exec` process is killed. This means users lose their shell state, running processes, and command history every time they disconnect.

The current architecture:
- `TerminalManager` tracks sessions by `session_id` (UUID) in a dictionary
- Each session creates a new PTY and `docker exec` process
- WebSocket I/O loops are tied to the session lifecycle
- No concept of reconnection or session persistence

## Goals / Non-Goals

**Goals:**
- Terminal sessions persist across WebSocket disconnections/reconnections
- Users reconnect to the same shell process, maintaining state and history
- Add explicit "Reset Terminal" functionality to kill and restart the session
- Graceful handling of idle timeouts to clean up abandoned sessions
- Buffer recent output for replay on reconnect

**Non-Goals:**
- Multi-user shared terminal sessions (one session per instance, but only one active WebSocket at a time)
- Session persistence across container restarts or instance stops
- Full terminal scrollback history persistence (only recent buffer)
- Automatic session restoration after instance restart

## Decisions

**1. Session tracking by instance_id**
- Rationale: One persistent session per tool instance is the simplest model
- Alternative: Track by user_id + instance_id — rejected because it's overkill; users don't need multiple terminals to the same container
- Trade-off: Only one user can have an active terminal at a time per instance

**2. Detach WebSocket from session on disconnect**
- Rationale: Keep the `docker exec` process alive, just remove the WebSocket reference
- Implementation: Session stores a list of WebSocket connections (initially just one)
- On disconnect: remove WebSocket from session, don't kill process
- On reconnect: attach new WebSocket to existing session

**3. Circular buffer for output replay**
- Rationale: Users should see what happened while disconnected
- Size: 10KB buffer (configurable) — enough for ~100 lines of typical output
- Implementation: Buffer stores raw bytes, replayed on WebSocket attach

**4. Reset terminal via WebSocket message**
- Rationale: Users need a way to kill a stuck or corrupted session
- Implementation: JSON control message `{"type": "reset"}` kills process and starts fresh
- Alternative: HTTP endpoint — rejected because it's more complex and less intuitive

**5. Idle timeout cleanup**
- Rationale: Prevent resource leaks from abandoned sessions
- Timeout: 30 minutes of no WebSocket connections
- Implementation: Background task checks last_activity timestamp

## Risks / Trade-offs

- **[Risk] Zombie sessions**: Users disconnect and never reconnect, leaving `docker exec` processes running
  - Mitigation: Idle timeout of 30 minutes cleans up abandoned sessions
- **[Risk] Session corruption**: If the shell process crashes, the session is dead but still tracked
  - Mitigation: Health check on `docker exec` process; auto-reset on next connect if dead
- **[Risk] Concurrent connections**: Multiple tabs trying to connect to the same instance
  - Mitigation: Only allow one active WebSocket per session; new connection closes old one with a message

## Migration Plan

1. Deploy updated backend services (TerminalManager, TerminalSession, terminal endpoint)
2. Deploy frontend changes (reset button, reconnection handling)
3. No database migration needed
4. Rollback: Revert to previous code; existing sessions will be killed on disconnect as before

## Open Questions

- Should we show a "session resumed" indicator in the UI?
- Should we persist the last N commands for command history?