orca/notes/orca-serve-terminal-persistence.md

# Orca Serve Terminal Persistence

## Problem

`orca serve` exposes terminal tabs to paired web clients through the runtime
`session.tabs` API, but the host-side terminal tab registry was process-local.
When the host published an empty session-tabs snapshot for a worktree, the web
client bootstrapped a new terminal, giving the user a fresh shell instead of
the previously running host session.

The browser must remain stateless for terminal identity. Browser storage is
intentionally sanitized because remote handles become stale after a new pairing
or host restart.

## Goals

- Keep the host runtime as the source of truth for paired web terminal tabs.
- Persist `orca serve` terminal tab, leaf, and PTY/session bindings in the
  existing workspace session model.
- Hydrate headless `session.tabs` snapshots from host persistence before a web
  client decides a worktree has no terminals.
- Mirror the SSH persistence model where it applies, while keeping SSH relay
  leases and local serve persistence behind their own provider checks.
- Preserve split-pane identity by routing all activation and attachment through
  parent tab id plus leaf id.

## Non-Goals

- Do not persist remote handles in browser local storage.
- Do not make browser panes supported in headless `orca serve`.
- Do not redesign the terminal daemon or SSH relay.
- Do not treat a persisted PTY id alone as proof that a live process belongs to
  a pane.

## Design

### 1. Persist Runtime-Owned Serve Spawns

The runtime PTY spawn path accepts a main-only `persistHostSessionBinding` flag.
Headless serve sets it when creating session-tab terminals. The PTY handler
then calls `Store.persistPtyBinding` only after validating `worktreeId`,
`tabId`, and stable `leafId`.

This keeps unrelated renderer-local PTY spawns from writing workspace-session
terminal bindings.

### 2. Use Stable Session IDs

Serve-created terminals pass `tabId`, `leafId`, optional `sessionId`, and
`persistHostSessionBinding` into `ptyController.spawn`.

If a pending hydrated terminal has a persisted PTY/session id, activation
passes that id back to the provider. New serve-owned local sessions use a
nonnumeric `serve-${uuid}` id so they cannot collide with older numeric PTY ids
after restart.

### 3. Hydrate Headless Snapshots

Before `list`, `listAll`, subscribe initial emission, activation, close, or
move returns an empty headless state, the runtime hydrates
`mobileSessionTabsByWorktree` from `workspaceSession.tabsByWorktree` and
`terminalLayoutsByTabId`.

Hydration preserves:

- parent terminal tab id
- stable leaf id
- title fields
- active tab and active leaf
- split layout and `ptyIdsByLeafId`
- persisted PTY/session id

Legacy terminal tabs without layout entries are still hydrated using a
deterministic stable leaf id derived from the parent tab id.

### 4. Materialize Pending Tabs On Activation

Hydrated terminal surfaces with no live trusted handle are exposed as
`pending-handle`. Activating one in headless serve materializes the exact
parent tab and leaf on the server, then returns a ready terminal surface.

Explicit leaf activation is exact. If `leafId` is provided and the requested
leaf is missing, the runtime returns `tab_not_found` instead of falling back to
a sibling.

### 5. Require Trusted PTY Identity

For headless-hydrated persisted tabs, a live PTY is safe to expose only when
the runtime record already matches the same worktree, parent tab id, and pane
key. A process-list entry with the same PTY id but no pane identity stays
pending, preventing stale or numeric id collisions from attaching the wrong
terminal.

Renderer-published authoritative session snapshots retain their existing
worktree-only daemon PTY adoption path.

### 6. Close And Move Without A Renderer

Headless close and move have no-renderer mutation paths:

- close hydrates and refreshes first, removes the persisted terminal tab and
  layout, updates active pointers, emits a new snapshot, and kills every live
  trusted leaf under the closed parent tab
- move updates in-memory and persisted tab order without changing PTY bindings

This prevents closed or reordered tabs from reverting on reconnect.

### 7. Renderer Guards

The web client still drops remote terminal identity from browser storage. It
mirrors the host snapshot and activates pending host mirrors through
`session.tabs.activate`.

Bootstrap of a default web terminal is allowed only for a fresh empty snapshot
for the active worktree when no local terminal state already exists. Stale empty
snapshots and fresh empty snapshots racing with staged local terminals do not
create duplicates.

### 8. SSH Parity

Runtime-owned SSH spawns record remote PTY leases with target-local relay PTY
ids while workspace-session PTY bindings keep app-facing ids. Lease writes are
deferred until after binding persistence succeeds for persisted runtime-owned
spawns, so a failed binding save cannot leave durable SSH lease metadata for a
tab/leaf that was not saved.

## Edge Cases Covered

- Browser reload or WebSocket reconnect mirrors host-owned terminal tabs.
- Pending headless terminal activation reuses persisted tab and leaf identity.
- Split panes attach and activate the requested leaf only.
- Removed split leaves fail fast even when siblings remain.
- Legacy tabs without layouts hydrate instead of appearing empty.
- Stale empty snapshots do not bootstrap duplicate terminals.
- Fresh empty snapshots do not bootstrap when local terminal state already
  exists.
- Numeric PTY id collisions remain pending until a safe reattach/spawn occurs.
- SSH reattach failure after binding persistence failure leaves no stale lease.

## Verification Plan

- Unit-test runtime hydration, activation, close, move, split-leaf exactness,
  stale PTY id handling, and legacy no-layout tabs.
- Unit-test PTY persistence gates, local session-id reattach behavior, SSH
  lease parity, and persistence failure cleanup.
- Unit-test renderer snapshot bootstrap guards and remote runtime PTY transport
  pending-mirror behavior.
- Run adjacent session-tab RPC and web-runtime session tests.
- Run typecheck, lint, and `git diff --check`.
- Launch the Electron dev app from this worktree with an isolated profile and
  verify CDP attachment, app identity, store availability, visible boot, and
  zero console errors.