Summary
Add the ability to connect PolyPilot to a running GitHub Codespace, creating sessions that execute inside the codespace environment rather than on the local machine.
Motivation
Users working with GitHub Codespaces want to use PolyPilot's multi-session management while leveraging the codespace's environment (dependencies, tools, repo state). Currently the only option is Remote mode via DevTunnel, which requires manual setup inside the codespace.
Implementation (PR #308)
- Discovery:
gh cs list --json enumerates available codespaces
- Connection: SSH tunnel (
gh cs ssh) to copilot headless server running in the codespace
- Health monitoring: Background loop detects tunnel failures and auto-reconnects
- Session lifecycle: Sessions persist across app restarts; resume when tunnel reconnects
- Alpha gate: Disabled by default, enabled via Settings → Alpha → Codespaces toggle
Requirements
- GitHub CLI (
gh) authenticated with codespace scope
- SSH server running in the codespace (typically via dotfiles configuration)
- Without SSH, the feature gracefully degrades to a "Setup Required" state — it cannot start copilot remotely
Known Limitations (Alpha)
- SSH process orphaning on app crash — Spawned
gh cs ssh processes survive hard crashes. No PID tracking for cleanup on next launch. Tunnels die when codespace times out.
- Port-forward fallback is non-functional —
gh cs ports forward cannot start copilot without SSH. Code correctly transitions to SetupRequired rather than hanging.
- No integration tests for tunnel lifecycle — Core reconnect/health-check paths require real SSH/gh CLI. Model, contract, and isolation tests are comprehensive (113 tests).
- No stale process cleanup on startup — Future improvement: track PIDs to clean up orphaned tunnels.
Files Changed
CodespaceService.cs / .Lifecycle.cs / .Diagnostics.cs — SSH tunnel and codespace management
CopilotService.Codespace.cs — Group lifecycle, health check, session resume
CopilotService.cs / .Persistence.cs / .Bridge.cs / .Organization.cs — Integration points
SessionSidebar.razor / CreateSessionForm.razor / SessionListItem.razor — UI
Settings.razor — Alpha toggle
ConnectionSettings.cs / SessionOrganization.cs — Model additions
- 8 test files (113 new tests)
Summary
Add the ability to connect PolyPilot to a running GitHub Codespace, creating sessions that execute inside the codespace environment rather than on the local machine.
Motivation
Users working with GitHub Codespaces want to use PolyPilot's multi-session management while leveraging the codespace's environment (dependencies, tools, repo state). Currently the only option is Remote mode via DevTunnel, which requires manual setup inside the codespace.
Implementation (PR #308)
gh cs list --jsonenumerates available codespacesgh cs ssh) to copilot headless server running in the codespaceRequirements
gh) authenticated with codespace scopeKnown Limitations (Alpha)
gh cs sshprocesses survive hard crashes. No PID tracking for cleanup on next launch. Tunnels die when codespace times out.gh cs ports forwardcannot start copilot without SSH. Code correctly transitions to SetupRequired rather than hanging.Files Changed
CodespaceService.cs/.Lifecycle.cs/.Diagnostics.cs— SSH tunnel and codespace managementCopilotService.Codespace.cs— Group lifecycle, health check, session resumeCopilotService.cs/.Persistence.cs/.Bridge.cs/.Organization.cs— Integration pointsSessionSidebar.razor/CreateSessionForm.razor/SessionListItem.razor— UISettings.razor— Alpha toggleConnectionSettings.cs/SessionOrganization.cs— Model additions