terminal_lifecycle

Terminal lifecycle

Runloop tracks a coding-agent terminal as two separate resources:

1. Process lease: ownership of the live tmux session.
2. Terminal snapshot: the read-only capture rendered in the UI.

The process lease is authoritative for cleanup. Hiding or expiring a snapshot does not release a live process. Bounded workflow-step processes receive a short shutdown grace after completion, while their snapshots can remain visible for the longer provider display-retention period. Main-agent sessions are persistent and use the idle backstop instead of the bounded deadline.

Every observed coding-agent tmux session is tagged with:

• @runloop_instance_id
• @runloop_owner_pid
• @runloop_owner_started_at
• @runloop_heartbeat

Startup recovery only removes tagged sessions whose owner PID/start-time pair is no longer live. It preserves untagged legacy sessions and sessions owned by another running backend or test process.

Terminal API state exposes:

• process_state: live, closing, or closed
• snapshot_kind: live or archived
• close_reason: the lifecycle reconciliation reason, when available

Operator actions follow these semantics:

• Dismiss hides only the snapshot.
• Complete asks the provider to finish and moves the lease toward closing.
• Fail closes the process and records a failed archived capture.
• Kill force-closes the process and records a failed archived capture.

SSE event buffers and session identity are retained for 24 hours after a session reaches a terminal state so reconnect/resume keeps its event cursor and chat context consistent. The event store's per-session count limit bounds memory; terminal process cleanup and terminal snapshot retention remain independent of this session-resume window.

Frontend authority rules

The terminal UI combines data from endpoints with different responsibilities. Keep these rules intact when changing polling, caching, or live attach:

1. The terminal-list poll owns lifecycle state. It decides state, active, process_state, snapshot_kind, and the tmux identity. A selected terminal detail/history response may contribute only its body (content, content_source, and rows). Detail responses can be older than the latest list poll; allowing them to overwrite lifecycle fields makes a live pane briefly appear completed and repeatedly reconnect.
2. A completed turn is not necessarily a closed CLI. Interactive main-agent CLIs remain available for follow-up messages after the current turn reaches completed. Continue live streaming while process_state=live; stop only when the process closes or the snapshot is archived.
3. A live connection has one fixed terminal grid. Do not resize xterm while bytes from the old grid can still arrive. Geometry changes must suspend old output, close the socket, fit the new grid, then reconnect for a fresh seed. Ignore duplicate ResizeObserver notifications when the containing box did not actually change size.
4. Only one browser window owns live geometry. A second viewer supersedes the first and the backend closes the first WebSocket with code 4001. The superseded viewer must keep its already-rendered local frame. It must not import a snapshot captured at the new owner's grid because reflowing that frame at a different width corrupts wrapping. The user can explicitly Take over, which fits and reconnects using the local grid.

The focused regression coverage is in:

• frontend/src/utils/terminalSnapshotIdentity.test.ts
• frontend/src/utils/terminalReconnect.test.ts
• agent_go/cmd/server/terminal_live_attach_test.go

Logical execution identity

The rail represents one logical execution once, even when that execution emits events through several wrappers. A background task can have lifecycle events keyed by background_agent_id while delegated content is keyed by a separate correlation_id. delegation_start is the canonical link between those IDs; the terminal store records it and resolves subsequent content to the lifecycle owner.

Do not solve duplicate entries by hiding cards in React. Producers must emit a declared execution_kind and stable parent/owner metadata, and the terminal store must normalize those identities before snapshots reach the frontend. Internal message-sequence items, scripted turns, and routers fold into their workflow-step transcript. Independently selectable background agents remain separate terminals.

The backend regression coverage is in agent_go/internal/terminals/store_test.go, especially TestStoreUnifiesBackgroundDelegationContentWithItsLifecycleTerminal.