headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/persistent-terminal-sessions/proposal.md at 40ac931c65e8a05cf523bb41b8b45e9634c7c19f

Files

T

Developer caadd59441 chore: archive 15 completed OpenSpec changes

Move the following audited-and-implemented changes into
openspec/changes/archive/2026-06-12-completed-changes-archive/:

- backend-frontend-refactoring
- config-profile-git-mounts
- config-profile-includes-ui
- config-profile-multi-repo-mounts
- container-monitoring-notifications
- git-mount-url-validation
- home-path-expansion
- mobile-terminal-ux
- mount-specificity-ordering
- notification-center
- persistent-terminal-sessions
- session-list-overhaul
- ssh-key-mounting
- terminal-fullscreen-unified-header
- tool-session-progress-and-updates

Also regenerated .pi-map*.md files for openspec/changes so the
remaining active changes (multi-session-terminal-ux, reorganize-long-files,
working-copies, workspace-first-ui) reflect the new layout.

2026-06-12 14:26:55 +00:00

1.7 KiB

Raw Blame History

Why

Currently, each WebSocket connection to a terminal spawns a new docker exec process. When the user disconnects (e.g., closes the browser tab, navigates away, or loses network), their shell session is killed and all state is lost. This is frustrating for users who expect their terminal session to persist like a traditional SSH session. We need persistent terminal sessions that survive reconnections.

What Changes

Backend: Refactor TerminalManager to track sessions by instance_id instead of generating a new session per WebSocket connection
Backend: Support reattaching to an existing docker exec process when a WebSocket reconnects
Backend: Add session reset functionality (kill existing shell and start fresh)
Backend: Add idle timeout-based cleanup for abandoned sessions
Frontend: Add "Reset Terminal" button in the UI
Frontend: Handle reconnection gracefully with buffer replay of recent output

Capabilities

New Capabilities

persistent-terminal: Terminal sessions persist across WebSocket reconnections, maintaining shell state and history

Modified Capabilities

terminal-session-management: Existing terminal session creation and lifecycle behavior changes to support reconnection instead of always creating new sessions

Impact

apps/api/src/services/terminal_manager.py: Major refactoring to support instance-keyed sessions
apps/api/src/services/terminal_session.py: Support multiple/detached WebSocket connections
apps/api/src/api/terminal.py: Attach to existing session logic
apps/web/src/components/terminal.tsx or related: Add reset button, handle reconnection
apps/web/src/hooks/use-terminal.ts or related: Buffer replay on reconnect

1.7 KiB Raw Blame History

Why