session-lifecycle

Session Lifecycle

This skill covers session creation, warm-up, activation, switching, and graduation. For container/runner infrastructure, see the session-containers skill.

Key Components

Component	Location	Role
SessionManager	orchestrator/sessions.ts	Persists session metadata (title, workspace dir, remote URL, warm flag) to JSON
SessionRunnerRegistry	orchestrator/session-runner.ts	App-level map of session ID -> runner. Fires onRunnerIdle callback for container cleanup
SessionRunnerInterface	orchestrator/session-runner.ts	Abstract contract: agent state, message queue, viewer count, preview
RepoStore	orchestrator/repo-store.ts	Tracks imported repos, clone status, warm session IDs

Session Types

1. Standalone session — no repo, fresh git repo initialized in the session directory. Created via POST /api/sessions.
2. Repo-backed session — its own independent local clone cut from the per-remote bare cache (git clone --local, hardlinked objects), checked out on a unique branch off the default branch. Created via warm pool or claim-session.
3. Warm session — a repo-backed session pre-created in the background: clone-from-cache + metadata plus, where there is idle headroom, a pre-booted standby container. Invisible in the sidebar until the user sends their first message ("graduated"). Where no standby exists, the container is created on-demand when the WebSocket connects. A warm session never survives an orchestrator restart — see "Restart" below.

Session Creation

Path A: Standalone Session (no repo)

Client                          Server
  |                               |
  +- POST /api/sessions ---------> createSessionDir(title)
  |  {title}                      |   mkdir sessions/{uuid}
  |                               |   git init
  |                               |   configure credentials
  |                               |   sessionManager.track()
  |                               |   threadManager.init()
  |<- {sessionId, sessionDir} -----
  |                               |
  |  store pendingWsMessage       |
  |  navigate(/session/{id})      |
  |                               |
  |  useSessionWebSocket opens    |
  +- WS /ws/sessions/{id} -------> activateSession(id)
  |                               |   runnerRegistry.getOrCreate()
  |                               |     -> factory creates container
  |                               |   attachToRunner()
  |                               |
  |  useConnectionSync fires      |
  +- GET /api/sessions/{id}/history -> returns messages, commits, etc.
  |                               |
  |  send pendingWsMessage        |
  +- WS send_message ------------> handleSendMessage()
  |                               |   POST /agent/start to worker
  |<- WS streaming events ---------