feat: Terminal real shell — WebSocket PTY, multiple instances, localhost-only

[Abernaughty]

Summary

Add VS Code-style terminal with real shell access — multiple terminal instances, workspace-bound, WebSocket + PTY backend. Phased for Phase 2.5 or Phase 3.

Context

Per the Dashboard Workflow Roadmap, Section 7.2. The terminal panel currently shows a simulated event stream. This adds real shell terminals for direct command execution, similar to VS Code's integrated terminal.

Design

Features

• Multiple terminal instances via "+" button
• Each terminal bound to a workspace directory (active task workspace or default)
• Tab label shows working directory
• Local shell when no task is active; project workspace shell for active/selected task

Security Requirements

• Localhost-only binding — never exposed through any tunnel or public URL
• Explicit opt-in flag required to enable (e.g., ENABLE_TERMINAL_SHELL=true)
• WebSocket + PTY backend implementation

Architecture

Dashboard (SvelteKit)
  ↕ WebSocket
FastAPI backend
  ↕ PTY (pty.spawn)
Shell process (bash/zsh/powershell)

Terminal Instance Management

• Each instance tracks: PID, working directory, shell type, created_at
• Graceful shutdown on tab close (SIGTERM → SIGKILL after timeout)
• Max concurrent terminals configurable (default: 5)

Acceptance Criteria

• WebSocket endpoint for terminal communication
• PTY backend spawning real shell processes
• Multiple terminal instances with "+" button
• Tab management: create, switch, close
• Working directory bound to task workspace
• Localhost-only binding enforced
• Opt-in flag (ENABLE_TERMINAL_SHELL) required
• Graceful process shutdown on tab close
• Max concurrent terminals limit
• Input/output streaming via WebSocket
• Terminal resize events propagated to PTY

Dependencies

• feat: Workspace security model — allowed directories, protected workspaces, PIN auth #105 (Workspace security model) — terminals must respect workspace boundaries

Effort

Large (2-3 sessions)

Phasing

Phase 2.5 or Phase 3 — agent timeline blades (#107) ship first in Phase 2.

Source

Dashboard Workflow Roadmap, Section 7.2 — Terminal Redesign, Tab Group 2