PTY streaming and recovery
PTY streaming keeps a shell process alive while terminal views and network paths change. A PTY is the process boundary that carries terminal input and output. The system gives one active consumer control of a PTY, publishes output through owned delivery paths, limits output with credits, and uses snapshots or sequence-aware replay to recover after cancellation, reload, or connection loss. Background PTYs keep their output in the main-side model while delivery waits for a view or an interested stream. See terminal runtime for the wider terminal model.
PTY lifecycle
Process lifecycle
The PTY is the long-lived process boundary for a shell or terminal program. A local provider creates and watches the process directly. A remote provider asks the host or relay to create or attach to the process. Provider listeners feed output and exit facts to both the runtime model and any renderer or remote stream that is present. See src/…/local-pty-provider.ts• L546-570, src/…/bind-listeners.ts• L19-115, and src/…/controller.ts• L41-95.
For daemon-backed sessions, the local lifecycle coordinator joins the subprocess, terminal output model, startup ingress, shell-readiness gate, recovery barrier, producer pause, and termination state. It keeps one process incarnation for the session and sends the final exit only after held startup and recovery output has been flushed. See src/…/session.ts• L23-97 and src/…/session.ts• L335-368.
The lifecycle has one PTY identity and a separate incarnation for each process instance. A reattach may reuse the PTY identity only when the host, pane or tab identity, and incarnation still match. A new process with a reused ID is therefore not treated as the old process. Registration also rejects a process that exited before its surface was admitted. See src/…/ownership-state.ts• L8-15, src/…/spawn-registration.ts• L13-25, and src/…/pty-handler.ts• L2057-2091.
Daemon restart does not make every known PTY belong to the new daemon. The current adapter handles new work, while legacy adapters keep routes for sessions that survived on older daemon generations. The old router releases only its own subscriptions before the provider swap, so shared legacy adapters and their sessions remain available to the new router. See src/…/daemon-pty-router.ts• L294-329, src/…/daemon-provider-routing.ts• L8-29, and src/…/daemon-provider-restart.ts• L119-158.
When a process exits, the owner releases startup and pending output state. It publishes final output and the exit event before it removes the PTY record. A requested stop is not complete until the owning host confirms the process exit. On POSIX, shutdown captures live descendant ancestry before it signals the root because descendants can be reparented after root exit. On Windows, an owned process job or an identity-checked process tree supplies the equivalent boundary. A zombie root cannot authorize a new ancestry walk, and an ambiguous or reused PID is not escalated. See src/…/bind-listeners.ts• L86-115, src/…/exit.ts• L55-177, src/…/kill.ts• L16-25, src/…/pty-descendant-termination.ts• L99-249, and src/…/orca-runtime-on-pty-exit.ts• L29-71.
The runtime keeps enough disconnected record state for status and exit reads, then bounds the old record archive. Renderer delivery flushes pending bytes before the exit event and releases the delivery credit held for the dead PTY. Late physical exits are matched to the same incarnation so a synthetic stop cannot close a successor process that reused the PTY ID. See src/…/bind-listeners.ts• L86-115, src/…/exit.ts• L55-177, src/…/kill.ts• L27-95, and src/…/orca-runtime-on-pty-exit.ts• L29-71.
The lifecycle is:
flowchart TD
A[Admit spawn or attach] --> B[Assign PTY incarnation]
B --> C[Register pane and host identity]
C --> D[Read process output]
D --> E[Retain and publish source ranges]
E --> D
D --> F{Process exits or host loses contact?}
F -->|Exit is confirmed| G[Flush final output and publish exit]
F -->|Contact is lost| H[Keep surface unverifiable]
H --> I[Reattach or inventory]
I --> D
G --> J[Release delivery state and retain bounded status record]
References: src/…/ownership-state.ts• L8-35 src/…/bind-listeners.ts• L19-115 src/…/exit.ts• L55-177 src/…/controller.ts• L41-95 src/…/kill.ts• L27-95 src/…/pty-descendant-termination.ts• L99-321 src/…/orca-runtime-refresh-pty-worktree-records-with-controller-inventory.ts• L53-117 src/…/session.ts• L23-97 src/…/session.ts• L335-368 src/…/pty-handler.ts• L2057-2091
Spawn admission
Spawn admission is the boundary that prevents a new PTY from racing workspace removal or exceeding host capacity. It resolves the execution directory on the host that will run the shell, counts pending creations before the native process exists, and reserves a stable pane owner so renderer and runtime requests for the same pane join one spawn rather than create competing processes. Fresh spawns and revived PTYs use the same host and workspace fence. See src/…/pty-spawn-cwd.ts• L26-85, src/…/spawn-reservation.ts• L29-74, and src/…/spawn-execute.ts• L18-57.
The spawn path resolves the pane key and reservation before provider preflight. A pending runtime creation is awaited, and an existing reservation is joined instead of starting another provider process. A replacement holds that reservation while it stops the old owner, so a reveal that arrives during the handoff joins the replacement rather than reattaching the owner being stopped. See src/…/spawn-begin.ts• L20-110, src/…/spawn-reservation.ts• L59-74, and src/…/pane-owner-replacement.ts• L14-79.
Runtime-owned and renderer-owned spawns use staged admission. The controller can reserve a pane, prepare the provider and execution context, mark an initially hidden PTY before a daemon can emit byte zero, and begin registration before the provider call. It seeds restored terminal state before the first disk wait, persists the pane binding, and publishes the spawn only after the binding is safe. If admission fails or the client disconnects, it cancels pending registration and releases provisional state. See src/…/spawn-begin.ts• L107-127, src/…/spawn-execute.ts• L42-57, src/…/spawn-commit.ts• L46-78, and src/…/spawn-registration.ts• L28-52.
The spawn contract carries the execution host, workspace, session identity, startup delivery choice, and terminal size. A provider reply proves whether the process is live or whether a prior owner can be adopted. A binding save failure cleans up an uncommitted fresh process but does not destroy an adopted process. An unavailable provider remains unknown rather than becoming permission to create a second process. See src/…/spawn-state.ts• L90-141, src/…/spawn-execute.ts• L81-128, and src/…/spawn-registration.ts• L28-52.
An SSH pane has one current reattachable lease for its stable pane surface. A later relay identity can supersede the predecessor only after the pane binding names the successor. An unbound or merely disconnected lease stays askable because lease loss is not proof that the remote shell exited. See src/…/stable-owner.ts• L74-124, src/…/adopt-stable.ts• L18-91, and src/…/spawn-commit.ts• L46-135.
On reattach, the committed terminal size comes from the provider's proven grid or snapshot before the cached or requested size. Main then reflows its headless model to that grid. This keeps the restored screen aligned with the process that produced the retained output. See src/…/attached-pty-size.ts• L17-80.
References: src/…/pty-spawn-cwd.ts• L26-85 src/…/spawn-reservation.ts• L29-150 src/…/spawn-begin.ts• L20-127 src/…/spawn-execute.ts• L18-244 src/…/spawn-commit.ts• L46-297 src/…/spawn-registration.ts• L13-83 src/…/stable-owner.ts• L196-306 src/…/adopt-stable.ts• L18-91 src/…/attached-pty-size.ts• L17-80
Host launch environment
The host launch environment prepares the PTY for its execution host. It keeps agent hooks, account homes, proxy settings, browser routing, terminal image support, and workspace command behavior scoped to the selected agent and host. SSH paths do not receive host-local paths, and WSL paths use guest endpoints for hook and extension traffic. This prevents a nested or resumed PTY from using another agent's files or another host's service. See src/…/assembly.ts• L38-46, src/…/assembly.ts• L111-195, and src/…/terminal-image-environment.ts• L9-41.
The launch path builds this environment only after it resolves the target runtime and any resumable agent session. Passive WSL restore can avoid starting a stopped distro, while an intentional launch may start the target runtime. Invalid session IDs fail before host state is written, and a failed environment build clears only state created for that spawn. See src/…/spawn-host-env.ts• L104-118, src/…/spawn-host-env.ts• L218-291, and src/…/types.ts• L10-37.
Agent startup wrappers preserve the user's shell behavior while adding the PTY's scoped launch rules. They keep shell history and inherited terminal context tied to the worktree and execution host. Local, daemon, WSL, and remote paths use the shell family that will actually read the environment. See src/…/inherited-tmux-env.ts• L1-15, src/…/git-bash.ts• L169-203, and src/…/zsh-startup-hook-user-config-equivalence.live-shell.test.ts• L71-111.
References: src/…/assembly.ts• L38-46 src/…/assembly.ts• L111-195 src/…/assembly.ts• L227-322 src/…/spawn-host-env.ts• L104-291 src/…/types.ts• L10-37 src/…/terminal-image-environment.ts• L9-41 src/…/inherited-tmux-env.ts• L1-15 src/…/git-bash.ts• L169-203
Startup ingress
Startup ingress is the ordered path for early PTY output and terminal query replies. It lets the host answer queries that must reach the child process at once while keeping the reply's terminal echo out of visible output. The path closes query authority at the startup handoff and releases pending bytes in source order. Hidden-at-spawn state is committed before a daemon call so a background process does not wait for a renderer that has not mounted. See src/…/pty-startup-ingress.ts• L35-159, src/…/pty-startup-reply-echo-shapes.ts• L83-110, and src/…/spawn-state.ts• L90-128.
The ingress suppresses a reply echo only when the backend has a known safe echo shape. It does not treat ordinary output as an echo. Provider-delivered startup commands wait for a shell-ready signal when the host supports it. Main also seeds terminal color replies from the saved view theme when no viewer has reported colors, then publishes later viewer changes to current and future PTY owners. See src/…/pty-startup-ingress.ts• L241-367, src/…/pty-handler.ts• L906-939, and src/…/terminal-viewer-colors-method.ts• L6-20.
References: src/…/pty-startup-ingress.ts• L35-159 src/…/pty-startup-ingress.ts• L241-367 src/…/pty-startup-reply-echo-shapes.ts• L83-110 src/…/pty-handler.ts• L906-939 src/…/spawn-state.ts• L90-128 src/…/terminal-viewer-colors-method.ts• L6-20
Output lifecycle
The output lifecycle turns PTY reads into ordered source spans. A source span is a retained range of PTY output with its process incarnation and delivery identity. Main sends output to its terminal model first, then routes it to the renderer or to subscribed remote streams. Headless runtime sessions update the model without requiring renderer work. See src/…/relay-pty-source-output.ts• L25-50, src/…/bind-listeners.ts• L68-84, and src/…/register-headless-runtime.test.ts• L69-109.
The daemon Session exposes the local output plane for attached clients and snapshots. It can pause and resume the producer when a stream stalls, releases a pause when the last client detaches, and returns pending output with an optional final snapshot for teardown. This keeps local backpressure and recovery tied to the same process lifecycle as output and exit. See src/…/session.ts• L115-120, src/…/session.ts• L162-172, src/…/session.ts• L192-232, and src/…/session.ts• L276-304.
The renderer path uses bounded pending data and cumulative processed-character acknowledgements. Main pauses a producer when pending or in-flight data reaches its limit. A broken renderer channel rolls back send accounting and marks the PTY for restore. A dispatcher-ready watchdog prevents a lost readiness handshake from holding output forever, while a health report can write off only data that the renderer did not already receive. See src/…/accept.ts• L62-207, src/…/flush.ts• L39-67, src/…/payload.ts• L89-150, and src/…/resize-visibility.ts• L102-214.
When no visible renderer needs bytes, main can drop the renderer copy after the terminal model ingests it. A hidden PTY reports throttled output activity so an agent-exit watch can still notice work. A hidden drop records a restore episode and sends a restore marker; the episode stays active until the revealed renderer confirms that it painted the restore. A raw delivery interest or graphics-retaining view can keep selected bytes flowing. See src/…/pty-hidden-delivery-gate.ts• L10-18, src/…/pty-hidden-delivery-gate.ts• L118-185, src/…/hidden-transition.ts• L53-89, and src/…/payload.ts• L62-87.
Renderer reset clears renderer-owned visibility, interest, pending data, and credit state. Runtime-owned hidden marks and unresolved restore episodes survive the reset. A new visibility report can reveal the PTY, but a pane's own hidden claim still wins until that claim is released. Provider background pacing is then re-synced so a hidden stream is not force-fed and a visible stream is not left paused. See src/…/pty-hidden-delivery-gate.ts• L191-214, src/…/resize-visibility.ts• L199-280, and src/…/producer-sync.ts• L21-66.
Pending renderer data has a bounded per-PTY backlog. When the backlog is too large, main keeps only bounded terminal query data and state needed to close an open terminal mode, then marks the stream for snapshot restore instead of sending a gapped tail. The renderer receives final pending bytes before pty:exit, and exit then releases the PTY's accounting. See src/…/pending.ts• L61-160 and src/…/exit.ts• L75-154.
The renderer adds an ordered boundary after transport delivery. It assigns each transport stream a generation, rejects callbacks from older generations, and holds live chunks while a replay or snapshot establishes the visible baseline. Renderer writes return delivery credit only after the terminal output scheduler parses or discards the write. See src/…/transport-output-callbacks.ts• L10-103, src/…/live-data-callback.ts• L78-124, and src/…/write-pty-output-to-xterm.ts• L17-121.
References: src/…/relay-pty-source-output.ts• L25-73 src/…/bind-listeners.ts• L68-115 src/…/session.ts• L115-120 src/…/session.ts• L162-172 src/…/session.ts• L192-232 src/…/session.ts• L276-304 src/…/accept.ts• L62-207 src/…/flush.ts• L39-67 src/…/payload.ts• L62-150 src/…/producer-sync.ts• L21-66 src/…/pty-hidden-delivery-gate.ts• L118-214 src/…/pending.ts• L61-160 src/…/exit.ts• L75-154 src/…/resize-visibility.ts• L102-280 src/…/transport-output-callbacks.ts• L10-103 src/…/live-data-callback.ts• L78-124
Terminal stream sessions
Subscription lifecycle
The terminal stream interface lets a desktop or mobile client observe a terminal without owning the PTY process. terminal.subscribe provides one stream per request. terminal.multiplex keeps several terminal streams on one binary connection. Each request registers for cleanup before it waits for a PTY, so unsubscribe, socket close, stream replacement, and PTY exit can cancel the same pending work. See src/…/terminal-subscribe-method.ts• L12-119, src/…/terminal-multiplex-method.ts• L13-70, and src/…/terminal-subscription-registration.ts• L30-140.
Subscription roles are distinct. A mobile view can claim mobile layout and input priority. A desktop view can report geometry and claim the desktop viewport. A lease-only subscription keeps input presence without opening another output view. Cleanup removes only the viewport ownership and mobile presence created by that stream. See src/…/terminal-subscribe-json-and-lease.ts• L9-117 and src/…/terminal-multiplex-cleanup.ts• L5-80.
References: src/…/terminal-subscribe-method.ts• L12-119 src/…/terminal-subscription-registration.ts• L30-140 src/…/terminal-subscribe-json-and-lease.ts• L9-117 src/…/terminal-multiplex-method.ts• L13-70 src/…/terminal-multiplex-cleanup.ts• L5-80
Initial snapshot and live output
Each stream starts with a terminal snapshot, then switches to live output. The snapshot gives the client a screen baseline, dimensions, display mode, and an output sequence when the source can provide one. Output that arrives during snapshot creation is held in a bounded queue. After the snapshot, the stream drops covered output and publishes only the uncovered range. If the queue overflows, it takes a newer snapshot instead of joining a gapped live stream. See src/…/terminal-subscribe-binary-snapshot.ts• L20-320 and src/…/terminal-multiplex-initial-snapshot.ts• L20-110.
Snapshots distinguish an unavailable image from an empty terminal. A missing or truncated image becomes a recovery signal. Mobile width changes use a full restream so wrapped history matches the new grid. A resize or snapshot result is ignored when its stream or resize generation is no longer current. See src/…/terminal-multiplex-slot-frames.ts• L138-253, src/…/terminal-subscribe-binary-live.ts• L94-131, and src/…/terminal-multiplex-live-stream.ts• L60-99.
This flow is:
sequenceDiagram
participant C as Client
participant R as Runtime
participant M as PTY model
C->>R: Subscribe
R->>M: Read screen and output sequence
M-->>R: Snapshot baseline
R-->>C: Snapshot frames
R->>R: Hold output received during snapshot
R-->>C: Uncovered live output
C->>R: Resize or snapshot request
R-->>C: New bounded snapshot, then live output
References: src/…/terminal-subscribe-binary-snapshot.ts• L20-320 src/…/terminal-multiplex-initial-snapshot.ts• L20-110 src/…/terminal-stream-replay.ts• L33-63 src/…/terminal-multiplex-slot-frames.ts• L138-253 src/…/terminal-subscribe-binary-live.ts• L94-131
Multiplex credits
Multiplex output can use stream and connection byte credits. The runtime sends output while both windows have room, queues output when either window is full, and drains queued chunks in round-robin order. A client acknowledgement returns credit. This limits one fast PTY from starving other streams on the same connection. See src/…/terminal-multiplex-flow-control.ts• L18-178 and src/…/terminal-multiplex-frame-delivery.ts• L92-136.
If an acknowledgement-gated queue overflows, the runtime sends a bounded recovery snapshot. It can include history when the link has room. If the link is still busy, it sends a screen-only image first and records that history is owed until the queue drains. A failed snapshot ends the stream as unverifiable. See src/…/terminal-multiplex-flow-control.ts• L20-103.
The older renderer path uses cumulative processed-character totals rather than remote byte credits. A renderer health report repairs lost acknowledgements without claiming bytes still waiting in the renderer's write queue. Terminal multiplex streams measure text as UTF-8 bytes at their network boundary. See src/…/accounting.ts• L76-204, src/…/terminal-multiplex-frame-delivery.ts• L92-118, and src/…/terminal-multiplex-flow-control.ts• L1-13.
References: src/…/terminal-multiplex-flow-control.ts• L18-178 src/…/terminal-multiplex-frame-delivery.ts• L92-136 src/…/terminal-stream-replay.ts• L88-123 src/…/accounting.ts• L76-204 src/…/terminal-multiplex-flow-control.ts• L1-13
Input delivery
Input follows the current stream and ownership state. Desktop input waits for a successful viewport claim. Mobile input uses the mobile input floor. A stale or locked client is treated as having its input applied by policy so a replay does not run it later. See src/…/terminal-input-delivery.ts• L11-105 and src/…/terminal-multiplex-input-frame.ts• L13-61.
Clients can negotiate an input session and sequence input frames. The runtime waits for provider write settlement before acknowledging a sequenced frame. A duplicate receives an acknowledgement again. A refusal asks the client to resend, while an unknown handoff does not claim that the input was lost. See src/…/terminal-multiplex-input-frame.ts• L23-61, src/…/terminal-subscribe-binary-control-frames.ts• L39-65, and src/…/stream-schemas.ts• L6-27.
References: src/…/terminal-input-delivery.ts• L11-105 src/…/terminal-multiplex-input-frame.ts• L13-61 src/…/terminal-subscribe-binary-control-frames.ts• L39-65 src/…/stream-schemas.ts• L6-27
Relay source publication
Source publication
Relay source publication is the reliable path between a PTY and its negotiated session owner. It opens one delivery for a PTY, retains output ranges, sends them in order, and keeps enough state to finish or recover a delivery after the transport changes. A delivery identity includes the PTY ID, provider generation, client generation, owner generation, PTY incarnation, and delivery token. These fields fence old connections and old process instances from the current stream. See src/…/pty-source-credit-contract.ts• L4-30 and src/…/relay-pty-source-publication.ts• L63-240.
Activation is a short pending phase. The relay does not release the first source frames until the activation response settles. Publication rejects a connection that is not an admitted owner, a sealed delivery, or a source ledger that cannot retain more output. A failed append stays queued until it can publish or the delivery retires. See src/…/relay-pty-source-activation.ts• L44-117, src/…/relay-pty-source-publication.ts• L200-240, and src/…/pty-source-credit-ledger.ts• L85-113.
References: src/…/pty-source-credit-contract.ts• L4-30 src/…/relay-pty-source-activation.ts• L44-117 src/…/relay-pty-source-publication.ts• L63-240 src/…/pty-source-credit-ledger.ts• L85-113
Consumer ownership
A consumer is a connection that reads a PTY stream. The session owner is the one consumer allowed to drive the PTY and use the credit-controlled source path. A subscriber can observe output but cannot claim ownership. A legacy owner can use the older output path when it did not negotiate flow control. An unadmitted connection cannot receive or send PTY data.
Ownership uses a client instance, an authenticated principal, an owner generation, and a private owner lease. A reconnect can resume the same claim only when the client and principal match and the lease is valid. The relay does not hand a still-attached owner to another client. A replacement grant revokes the old connection only after the new claim publishes successfully. See src/…/pty-consumer-owner-recovery.ts• L22-90 and src/…/ssh-pty-consumer-session-adapter.ts• L211-255.
The pane binding boundary applies the same rule to renderer state. Only the current pane transport can bind a PTY, and a stale callback is ignored. Destructive actions also require host owner attestation. Agent writes re-check the current session lease before later chunks so a handoff cannot send old input to the new owner. See src/…/pane-pty-visibility-bind.ts• L39-84, src/…/pty-handler.ts• L2242-2320, and src/…/write-input.ts• L152-193.
References: src/…/pty-consumer-owner-recovery.ts• L22-90 src/…/ssh-pty-consumer-session-adapter.ts• L211-255 src/…/pane-pty-visibility-bind.ts• L39-84 src/…/pty-handler.ts• L2242-2320 src/…/write-input.ts• L152-193
Flow-control credits
Credit window
Output flow control is a negotiated owner capability. A source unit is one position in the ordered PTY source range. The relay gives the owner a source window and sends only output that the owner has not yet credited. The owner sends cumulative acknowledgements with the delivery token and generation values. See src/…/pty-source-credit-contract.ts• L1-3 and src/…/pty-source-credit-ledger.ts• L122-187.
The ledger tracks three ends of one source range:
| Counter | Meaning |
|---|---|
| Received end | Output accepted into the retained source ledger |
| Sent end | Output admitted to the consumer transport |
| Credited end | Output confirmed as consumed by the consumer |
| Outstanding range | Sent end minus credited end |
Acknowledgements must name the current delivery and stop at a valid send boundary. Acknowledgements that arrive while a send is settling wait for that exact boundary. This prevents an early acknowledgement from releasing data that the relay did not commit. The relay also splits source data into bounded frames and gives each delivery a small send turn so one flooding PTY cannot starve other PTYs or control messages. See src/…/pty-source-credit-settlement.ts• L20-88, src/…/pty-source-sent-boundaries.ts• L4-47, and src/…/relay-pty-source-send-scheduler.ts• L167-269.
Main uses the same idea with cumulative processed-character totals. A renderer health report can repair lost acknowledgements without claiming bytes still waiting in the renderer's write queue. Terminal multiplex streams apply a separate byte window at their network boundary and measure text as UTF-8 bytes. See src/…/accounting.ts• L76-204, src/…/terminal-multiplex-frame-delivery.ts• L92-118, and src/…/terminal-multiplex-flow-control.ts• L1-13.
References: src/…/pty-source-credit-contract.ts• L1-3 src/…/pty-source-credit-ledger.ts• L122-187 src/…/pty-source-credit-settlement.ts• L20-88 src/…/pty-source-sent-boundaries.ts• L4-47 src/…/relay-pty-source-send-scheduler.ts• L167-269 src/…/accounting.ts• L76-204 src/…/terminal-multiplex-flow-control.ts• L18-178 src/…/terminal-multiplex-flow-control.ts• L1-13
Producer backpressure
Credits control relay publication, while producer backpressure controls how much unread output enters the host-side queue. When a queue reaches its high-water limit, a provider that supports pause stops reading the underlying PTY. Providers without pause support still use bounded pending-output and retained-source budgets. See src/…/provider-contract.ts• L142-154 and src/…/pty-handler.ts• L1155-1232.
The consumer can also pause a delivery when its view cannot accept output. The pause is tied to the active delivery identity and is cleared when that identity or provider generation changes. Visibility, active-pane priority, and raw delivery interest then decide which renderer data may flow. Multiplex waits are canceled when a stream, slot, or connection closes. See src/…/ssh-pty-consumer-session-adapter.ts• L73-99, src/…/accept.ts• L93-159, src/…/producer-sync.ts• L18-62, and src/…/terminal-multiplex-cleanup.ts• L42-80.
References: src/…/provider-contract.ts• L142-154 src/…/pty-handler.ts• L1155-1232 src/…/ssh-pty-consumer-session-adapter.ts• L73-99 src/…/accept.ts• L93-159 src/…/producer-sync.ts• L18-62 src/…/terminal-multiplex-cleanup.ts• L42-80
Replay and recovery
Recovery checkpoint
A recovery checkpoint is the last source end that the consumer confirms it accepted. It is paired with the client generation, owner generation, PTY incarnation, and delivery token that produced that range. The checkpoint is stored with SSH consumer recovery state so a new transport can request the exact point at which it should resume. See src/…/pty-source-recovery-contract.ts• L1-22 and src/…/ssh-pty-consumer-recovery.ts• L8-15.
The relay recovers only when the current delivery still matches the checkpoint identity and remains open. It rotates the old delivery to a new token and retains a bounded range for the replacement owner. If the checkpoint is missing, stale, or inconsistent, the relay returns restoreRequired instead of guessing which bytes the consumer has. If the retained tail is larger than the new owner's window, recovery ends at the acknowledged checkpoint and the remaining tail becomes ordinary live output. See src/…/pty-source-credit-record.ts• L204-243, src/…/relay-pty-source-publication.ts• L113-153, and src/…/relay-pty-source-activation.ts• L18-26.
References: src/…/pty-source-recovery-contract.ts• L1-22 src/…/ssh-pty-consumer-recovery.ts• L8-15 src/…/pty-source-credit-record.ts• L204-243 src/…/relay-pty-source-publication.ts• L113-153 src/…/relay-pty-source-activation.ts• L18-26
Recovery fence
During recovery, the provider installs the new receiving activation before it accepts source frames. It holds those frames until the range from the checkpoint to the relay's recovery end arrives in order. The session checks the full identity and end positions before it releases recovered data and then live data. See src/…/ssh-pty-source-delivery-ledger.ts• L28-67 and src/…/ssh-relay-session.ts• L2760-2858.
The recovery fence rejects a gap, a changed token or incarnation, a timeout, or a retention failure. The session then requests a fresh activation or a screen restore path. A successful exact recovery preserves source order without duplicating the acknowledged prefix.
The recovery flow is:
sequenceDiagram
participant C as Consumer
participant R as Relay
participant P as PTY provider
C->>R: Reconnect with checkpoint identity
R->>R: Validate owner, delivery, and window
alt Checkpoint is usable
R->>R: Rotate delivery and retain bounded range
R-->>P: New receiving activation
P->>P: Quarantine source frames
R-->>C: Recovery data and recoveryComplete
P->>P: Release recovered range, then live range
P->>R: Advance checkpoint
else Checkpoint is not usable
R-->>C: restoreRequired
C->>P: Request fresh activation or screen restore
end
References: src/…/pty-source-recovery-contract.ts• L1-29 src/…/ssh-pty-source-delivery-ledger.ts• L28-67 src/…/ssh-relay-session.ts• L2760-2858 src/…/relay-pty-source-publication.ts• L113-153 src/…/relay-pty-source-activation.ts• L18-26
Screen replay
Screen replay is the fallback and the normal view rebuild path when a pane needs a new terminal surface. The host returns retained PTY output or an authoritative buffer snapshot. The renderer applies replay as history rather than new live output, so terminal replies and attention events from old bytes do not enter the shell or alert the user again. Main can request a serialized renderer buffer with its dimensions and sequence boundary. See src/…/pty-handler.ts• L2102-2169, src/…/serialize-buffer.ts• L86-111, and src/…/remote-runtime-pty-transport-snapshot-replay.test.ts• L40-95.
An attach first checks that the backing process is alive. A proven-dead process is reaped and reports an exit-backed result. An unknown or restarted relay does not turn absence from its current map into proof of death. Replay has a bounded retention window, and an over-sized or unavailable snapshot becomes a recovery condition rather than a silent blank screen. Persisted scrollback can supply a bounded history tail when the live surface is rebuilt. See src/…/pty-handler.ts• L2067-2080, src/…/pty-handler-attach-replay.test.ts• L70-171, src/…/recent-pty-output-buffer.ts• L1-14, and src/…/terminal-scrollback-snapshots.ts• L68-119.
Remote terminal streams use the same baseline rule. Their initial or requested snapshot carries an output sequence when available. Buffered live chunks covered by that sequence are removed, and a queue overflow causes a new snapshot rather than an unsafe tail replay. See src/…/terminal-stream-replay.ts• L33-63, src/…/terminal-multiplex-initial-snapshot.ts• L74-110, and src/…/terminal-multiplex-slot-frames.ts• L162-240.
The renderer keeps replay and live output in one stream order. A new stream generation cancels stale restore work. The live-data path drops chunks already covered by the restored snapshot and requests a fresh snapshot when sequence data has an unsafe gap. See src/…/transport-output-callbacks.ts• L15-30, src/…/live-data-callback.ts• L78-124, and src/…/pane-serializer-register.ts• L23-79.
References: src/…/pty-handler.ts• L2067-2080 src/…/pty-handler.ts• L2102-2169 src/…/serialize-buffer.ts• L21-111 src/…/recent-pty-output-buffer.ts• L1-14 src/…/terminal-scrollback-snapshots.ts• L68-119 src/…/terminal-stream-replay.ts• L33-63 src/…/terminal-multiplex-initial-snapshot.ts• L74-110 src/…/terminal-multiplex-slot-frames.ts• L162-240 src/…/transport-output-callbacks.ts• L15-30 src/…/live-data-callback.ts• L78-124
Parked-pane reveal
A parked-pane reveal rebuilds a terminal surface after the renderer released its view. A remote runtime PTY may have no relay replay tail, so a host snapshot can be the only structural image before live output resumes. The renderer probes that image once and applies it before queued live data. See src/…/reattach-result-handler.ts• L262-325 and src/…/run-deferred-connect.ts• L165-199.
The reveal distinguishes a positive host image, an unverifiable answer, and a confirmed lack of an image. An empty remote snapshot is not proof that the terminal is empty. Retries use bounded host and local restore budgets, and a confirmed missing image stops retry and makes loss visible. The probe checks the active transport before and after the request so a stale result cannot repaint a successor pane. See src/…/park-reveal-snapshot-verdict.ts• L18-119 and src/…/hidden-output-restore-request.ts• L159-205.
References: src/…/reattach-result-handler.ts• L262-325 src/…/run-deferred-connect.ts• L165-199 src/…/park-reveal-snapshot-verdict.ts• L18-119 src/…/hidden-output-restore-request.ts• L159-205
Cold restore
Cold restore replaces a missing PTY while preserving a resumable agent provider session. The renderer builds a new startup command only when the session belongs to the current execution host. If the pane is attached to another host, it does not launch a resume command that cannot find its transcript. The deferred connection path waits for deliberate workspace sleep to end before it chooses exact replay, a host snapshot, or a fresh restore. See src/…/cold-restore-resume-startup.ts• L33-61 and src/…/run-deferred-connect.ts• L35-73.
References: src/…/cold-restore-resume-startup.ts• L23-121 src/…/run-deferred-connect.ts• L35-73 src/…/run-deferred-connect.ts• L165-200
History cleanup
Terminal history is recovery data scoped to a worktree and shell. Startup injection creates a private history area for supported shells, records enough metadata to find fish history outside that area, and translates the path for a WSL shell. Inherited Orca history settings are cleared before a nested launch so one PTY cannot write another worktree's history. See src/…/terminal-history.ts• L16-71, src/…/terminal-history.ts• L75-190, and src/…/terminal-history.ts• L201-307.
History metadata is bounded and validated before it can guide cleanup. The fish session must match the worktree-derived name, and malformed or oversized metadata is ignored. Shell migration records prevent the same history changes from being installed more than once after a retry. See src/…/terminal-history.ts• L108-190.
Terminal history cleanup removes a worktree's persisted recovery data without blocking the main process. It first moves the live history tree to a pending-delete area, then removes the detached tree in the background. This keeps a worktree path free for reuse while protecting a newly created history tree from a late cleanup task. See src/…/terminal-history-deletion.ts• L139-161, src/…/terminal-history-deletion.ts• L251-269, and src/…/terminal-history-async-delete.test.ts• L26-50.
Cleanup is bounded and recoverable. Pending trees use a shared admission limit, retry transient removal failures, and remain as tombstones for a later drain when removal cannot finish. WSL history waits for the target distro when needed. The async-delete test verifies that the caller removes the live hash from the active root quickly and that the pending tree is eventually drained. See src/…/terminal-history-deletion.ts• L164-247, src/…/terminal-history-deletion.ts• L271-314, and src/…/terminal-history-id.ts• L1-5.
References: src/…/terminal-history.ts• L16-71 src/…/terminal-history.ts• L75-190 src/…/terminal-history.ts• L201-307 src/…/terminal-history-deletion.ts• L139-161 src/…/terminal-history-deletion.ts• L164-247 src/…/terminal-history-deletion.ts• L251-340 src/…/terminal-history-async-delete.test.ts• L26-50 src/…/terminal-history-id.ts• L1-5
Cancellation and liveness
Delivery cancellation
Cancellation ends one source delivery without ending the PTY process. The request names the PTY, client generation, owner generation, and delivery token. The relay returns the last sent and credited positions, then removes the delivery from the active owner path. A repeat request can receive remembered proof, while an unknown or stale token is rejected. See src/…/ssh-pty-source-credit-adapter.ts• L189-216 and src/…/pty-source-cancellation-index.ts• L4-47.
The relay uses cancellation when a client leaves, a delivery is replaced, recovery fails, or the publication service closes. Input cancellation is separate: a terminal write can be refused before the provider sees a byte or can return an unverifiable result after handoff. Renderer lifecycle reset removes old handlers, clears renderer-scoped pending data and credit, releases producer pauses, and waits for a new dispatcher-ready handshake. Remote stream cleanup also removes subscriptions, aborts pending PTY waits, and drops stream credit. See src/…/relay-pty-source-exit-publication.ts• L93-234, src/…/mailbox-pointer-pty-write.ts• L20-85, src/…/wire-session.ts• L120-145, and src/…/terminal-multiplex-cleanup.ts• L42-80.
Renderer-owned stop waits for provider startup and a process exit when possible. A missing SSH provider records an unverifiable result instead of claiming that the remote shell stopped. A fenced stop also checks the expected incarnation, host scope, and attachment rules before it publishes a synthetic exit. Only a confirmed, incarnation-bound stop is replayed at a later handshake. See src/…/renderer-kill.ts• L41-149, src/…/renderer-kill.ts• L151-208, src/…/kill.ts• L134-221, and src/…/liveness.ts• L75-114.
References: src/…/ssh-pty-source-credit-adapter.ts• L189-287 src/…/pty-source-cancellation-index.ts• L4-47 src/…/relay-pty-source-exit-publication.ts• L93-234 src/…/mailbox-pointer-pty-write.ts• L20-85 src/…/wire-session.ts• L120-145 src/…/terminal-multiplex-cleanup.ts• L42-80 src/…/renderer-kill.ts• L41-208 src/…/kill.ts• L134-221
Input forwarding
Input forwarding is the controlled path from a terminal view to the PTY. It keeps terminal query replies immediate, drops input that belongs to replay or a stale pane, and sends ordinary input only through the current transport. A rejected write asks the pane to recover instead of silently losing the user's action. See src/…/pty-input-forward.ts• L30-175.
The main IPC path also serializes input behind remote-desktop ownership and the current agent-session lease. Large inputs are split into bounded chunks and yield between writes so an ownership callback can run before the next chunk. Launch writes and terminal query replies are kept separate from user-driving input so they do not change run state or downstream activity signals. See src/…/write.ts• L20-68, src/…/write-input.ts• L103-193, and src/…/write-input-user-input.test.ts• L32-62.
References: src/…/pty-input-forward.ts• L30-175 src/…/pty-input-recovery.ts• L147-210 src/…/write.ts• L20-68 src/…/write-input.ts• L103-193 src/…/terminal-input-delivery.ts• L56-105
Owner grace
Owner grace depends on why the transport closed. A peer-closed transport proves owner departure and can shorten grace. A local close caused by relay backpressure or decode teardown does not prove owner death, so it must not shorten grace. See src/…/pty-consumer-session-contract.ts• L1-3.
A negotiated owner that disconnects can keep its deliveries for a bounded grace period. A valid reconnect can rotate those deliveries forward. A subscriber or legacy owner does not receive this source-delivery retention, so its output state closes with its connection. An attached incumbent blocks a different owner until it closes or its grace ends. See src/…/ssh-pty-source-credit-adapter.ts• L219-287 and src/…/pty-consumer-owner-admission.ts• L35-83.
References: src/…/pty-consumer-session-contract.ts• L1-3 src/…/ssh-pty-source-credit-adapter.ts• L219-287 src/…/pty-consumer-owner-admission.ts• L35-83
Liveness verdict
PTY liveness is separate from stream liveness. exited requires positive evidence from the owning host. live means the host lists or directly confirms the PTY. unverifiable means the runtime cannot observe the owning host or cannot complete its check. Loss of an SSH provider or relay is never treated as proof that the remote PTY stopped. See src/…/pty-liveness-verdict.ts• L1-21 and src/…/liveness.ts• L42-73.
Inventory is authoritative only for hosts that answered. A missing PTY in a current relay map can reflect a relay restart and does not certify the old process. Stable-pane reattach preserves a binding under that uncertainty. An expired SSH lease also preserves the pane owner until a termination proof exists. A provider-owned absence or a host process probe can certify death and retire the pane surface. Transport generations and identity checks fence late data after a relay or SSH connection changes. See src/…/orca-runtime-refresh-pty-worktree-records-with-controller-inventory.ts• L53-117, src/…/stable-owner.ts• L33-115, src/…/ssh-expired-lease-pane-readoption.test.ts• L65-127, and src/…/operations.ts• L85-114.
Provider teardown clears per-PTY delivery, visibility, geometry, and provider overlays. A connection loss preserves reconnectable ownership, while confirmed teardown clears it so a reused PTY ID cannot inherit old account or hidden-delivery state. Destructive workspace removal uses the same distinction and blocks ordinary removal for live or unverifiable PTYs. See src/…/state-cleanup.ts• L29-128, src/…/register-handlers.ts• L163-199, and src/…/unstopped-pty-verification.ts• L30-97.
Agent-session ownership uses provider listings only when the provider can make absence authoritative. A listing timeout or missing incarnation proof leaves ownership unknown, which blocks an unsafe replacement. Local status checks also require the same pane and incarnation to remain current while process evidence is collected. See src/…/agent-session-owners.ts• L14-137 and src/…/terminal-pane-status-lifecycle.ts• L117-199.
References: src/…/pty-liveness-verdict.ts• L1-21 src/…/liveness.ts• L42-114 src/…/unstopped-pty-verification.ts• L30-97 src/…/orca-runtime-refresh-pty-worktree-records-with-controller-inventory.ts• L53-117 src/…/stable-owner.ts• L33-115 src/…/agent-session-owners.ts• L14-137 src/…/terminal-pane-status-lifecycle.ts• L117-199 src/…/operations.ts• L85-114 src/…/state-cleanup.ts• L29-128 src/…/register-handlers.ts• L163-199
Change checklist
When these files or sections are changed, remember to consider these:
- Keep every delivery identity field aligned across relay frames, provider parsing, acknowledgements, cancellation proofs, and recovery checkpoints.
- Keep source cursors and committed send boundaries aligned across append, send reservation, acknowledgement, rotation, and recovery completion.
- Keep owner close-cause classification aligned with grace handling. Only a peer-ended transport may shorten owner grace.
- Keep owner grant publication fenced with displaced-owner close and delivery retention.
- Keep host owner attestation and runtime agent-session leases aligned with every destructive or input write path.
- Keep exit publication after source data settlement and legacy projection.
- Keep producer and consumer pauses tied to the current provider generation and delivery token.
- Keep checkpoint persistence keyed to the application PTY identity used by the next reconnect.
- Keep pane and tab PTY replacement atomic with the active transport check.
- Keep park-reveal verdicts distinct. An empty remote image is unverifiable, not proof of an empty pane.
- Keep host snapshot, relay replay, and cold restore precedence aligned.
- Keep snapshot probes fenced by the active PTY and transport generation before and after the await.
- Keep liveness wording distinct from transport failure. A lost route can be unverifiable without being an exited PTY.
- Keep spawn and revive cwd resolution aligned with the host that executes the shell.
- Keep early pane reservation keys aligned with the validated pane identity, worktree, and connection so replacement requests join the intended spawn.
- Keep host environment preparation scoped to the selected agent, execution runtime, and WSL guest.
- Keep renderer dispatcher readiness, lifecycle reset, pending output, hidden-drop episodes, and renderer credit as one reset and restore contract.
- Keep restore markers paired with the output sequence and retire hidden-drop memory only after painted restore acknowledgement.
- Keep renderer send rollback and provider background pacing aligned with visibility, raw delivery interest, and graphics-retaining claims.
- Keep terminal image and shell startup environment decisions tied to the host and viewer that will read them.
- Keep fenced termination restricted to the expected local incarnation and preserve remote leases when the provider is unavailable.
- Keep agent-session owner listings authoritative only for providers that can prove absence.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A frame carries an old token, generation, or PTY incarnation | The consumer could receive output from a prior owner or process | Source admission compares the complete delivery identity before publication |
| The owner stops acknowledging output | The source window closes and retained output grows | Credit windows, retained-range budgets, and producer backpressure bound the growth |
| A reconnect resumes without a usable checkpoint | The consumer could skip or repeat output | The relay returns restoreRequired instead of guessing the accepted source end |
| Recovery data arrives out of order or past the recovery end | Replayed and live output could be interleaved or duplicated | The receiving ledger requires the next contiguous source range and a matching identity |
| A replacement owner grant fails while the old owner is attached | Both owners could drive the PTY or the old owner could lose its claim | Grant publication commits displacement only after the replacement response settles |
| A local relay teardown is treated as peer departure | Owner grace can end too soon and a replacement can take over a still-live owner | Close-cause handling shortens grace only for a peer-closed transport |
| A stale renderer transport binds after a successor owns the pane | Visibility or tab state could point to an old PTY | The pane binding checks the current transport and rejects stale callbacks |
| A parked remote reveal treats an empty or timed-out host answer as an empty screen | The renderer can clear a valid client copy or hide lost history | Unverifiable answers stay out of structural paint and use bounded retries |
| A destructive stop lacks host or incarnation proof | The UI can report a normal exit while the remote shell remains alive | Provider stop verification and an unverifiable verdict preserve retry evidence |
| A terminal write crosses an agent-session lease handoff | Old input can reach the new owner | Each later write chunk re-admits the current lease |
| Renderer delivery loses its push channel after bytes are sent | Producer pauses can remain held and the pane can wait forever for acknowledgements | Send rollback, readiness watchdog, resync, and guarded write-off release only progress the renderer can prove |
| A hidden PTY drops renderer bytes without a restore boundary | A later reveal can show an incomplete terminal model | Hidden drops record an episode, report activity, and emit a restore-needed marker |
| Renderer re-registration leaves hidden state or provider pacing stale | A background PTY can be force-fed, or a visible PTY can remain paused | Lifecycle reset clears renderer state and re-syncs provider background state |
| A remote stream's pending output exceeds its bounded queue | The client can receive a gapped tail | The stream discards the unsafe tail and publishes a fresh snapshot |
| A multiplex acknowledgement window is full | One stream can delay every stream on the connection | Stream and total byte windows plus round-robin draining bound each stream's turn |
| A recovery snapshot is sent while the link is saturated | History can be lost or the client can mix an old tail with a new screen | The runtime sends a bounded screen image and owes history until the link drains |
| A sequenced input frame is acknowledged before provider handoff settles | A reconnect can drop input that may already be in flight | The runtime acknowledges only settled writes and marks unknown handoffs as delivery-unknown |
| A subscription waits for a PTY before it registers cleanup | An unsubscribe or closed socket can leave a pending wait and view presence active | Registration happens before the PTY wait and aborts all owned work on release |
| A resize result arrives after a newer stream or resize generation | An old geometry or snapshot can repaint the current view | Stream attachment and resize generation checks reject stale results |
| A failed binding save is treated like a failed adoption | A live adopted process can be killed | Cleanup stops only an uncommitted fresh incarnation |
| A relay restart reports an old pane ID as absent without host evidence | A live remote shell can be retired and replaced by a second shell | Stable-pane adoption keeps the binding unverifiable until the owning host certifies absence |
| The old router is fully disposed during a daemon restart | Legacy adapters lose subscriptions and surviving PTYs become unreachable | Router-only disposal removes the outgoing fanout without disposing shared adapters |
| Provider listeners survive daemon replacement | Output and exit events can be duplicated or disappear | Registration unbinds old listeners and binds the current provider once |
| A spawn reservation or pre-spawn hidden mark is not settled after failure | Later requests can wait forever or inherit hidden delivery | Spawn cleanup rejects the reservation, cancels registration, and releases the mark |
| A descendant scan trusts a zombie root or a reused PID | Shutdown can signal an unrelated process or miss the owned descendants | Capture live ancestry before root death and require matching start identity and process group before escalation |
| History metadata is oversized, malformed, or points to another fish session | Cleanup can miss recovery data or target the wrong shell history | Metadata has a size bound and validates the worktree-derived fish session before use |
| History deletion recursively removes the live worktree tree on the caller path | A recreated worktree can lose new terminal history, or the main process can stall | The live tree is tombstoned first and only the detached tree is removed asynchronously |
| A pending history tombstone cannot be removed | Old recovery data consumes disk space or WSL cleanup never completes | Bounded retries, startup draining, and distro-running deferral keep cleanup recoverable |
| A process stop uses a stale pane or incarnation identity | A successor PTY can be stopped by an old request | Fenced termination checks the expected incarnation and current pane ownership before publishing exit |
| A host environment inherits another PTY's agent or image state | A shell can use the wrong account, hook endpoint, or terminal image mode | Spawn assembly removes inherited state and rebuilds it for the selected host and viewer |
Key files
| File | Why to read it |
|---|---|
| src/…/pty-handler.ts | Relay-side PTY admission, process lifecycle, output queue, attach replay, liveness checks, and process exit |
| src/…/relay-pty-source-publication.ts | Opens, activates, rotates, publishes, seals, and retires source deliveries |
| src/…/relay-pty-source-activation.ts | Defines activation and the bounded recovery window used during reconnect |
| src/…/pty-source-credit-ledger.ts | Coordinates retained source ranges, send cursors, credits, cancellation, and close conditions |
| src/…/pty-source-credit-settlement.ts | Applies send settlement, cumulative acknowledgements, boundary checks, and span reclamation |
| src/…/relay-pty-source-send-scheduler.ts | Sends bounded source frames and resumes work when credit or transport capacity returns |
| src/…/relay-pty-source-exit-publication.ts | Orders final output and exit publication across source and legacy consumers |
| src/…/ssh-pty-consumer-session-adapter.ts | Connects owner admission, source delivery control, acknowledgements, and cancellation to the relay |
| src/…/pty-consumer-session-contract.ts | Defines whether a consumer close proves peer departure for owner-grace handling |
| src/…/pty-source-credit-contract.ts | Defines delivery identity, source spans, acknowledgements, cancellation proofs, and snapshots |
| src/…/session.ts | Coordinates one daemon-side PTY process with output, startup, recovery, attached clients, backpressure, and exit |
| src/…/controller.ts | Exposes the runtime boundary for spawn, attach, write, liveness, stop, resize, and repaint |
| src/…/spawn-execute.ts | Coordinates stable-pane adoption, provider admission, incarnation checks, and execution context |
| src/…/spawn-commit.ts | Commits restored model state, durable pane binding, ownership, geometry, and publication |
| src/…/stable-owner.ts | Resolves and attaches stable pane ownership across process and provider changes |
| src/…/agent-session-owners.ts | Reconciles agent-session ownership and rejects unproven provider listings |
| src/…/spawn-reservation.ts | Prevents concurrent requests from creating competing PTYs for one pane |
| src/…/registry.ts | Routes PTY operations to the execution host that owns the process |
| src/…/liveness.ts | Separates confirmed process absence from an unknown provider or host |
| src/…/state-cleanup.ts | Clears provider, pane, visibility, and delivery state without leaking it to a reused PTY ID |
| src/…/pty-descendant-termination.ts | Captures owned descendant identity before shutdown and limits signals to verified process instances |
| src/…/renderer-kill.ts | Applies local fenced stop rules and preserves unknown remote stops as unverifiable |
| src/…/accept.ts | Admits renderer output, applies hidden delivery policy, and creates restore markers for dropped data |
| src/…/flush.ts | Drains bounded renderer output and prevents a lost readiness handshake from blocking it forever |
| src/…/pty-hidden-delivery-gate.ts | Tracks hidden delivery, raw-byte interest, drop episodes, and painted restore state |
| src/…/payload.ts | Sends renderer data, hidden activity, and restore markers with accounting rollback |
| src/…/producer-sync.ts | Maps renderer visibility and interest to provider background pacing |
| src/…/resize-visibility.ts | Handles visibility, renderer credit, lifecycle readiness, and painted restore acknowledgements |
| src/…/exit.ts | Flushes pending renderer bytes and orders exit cleanup and notification |
| src/…/pending.ts | Bounds renderer backlog and preserves recovery markers and terminal query data |
| src/…/wire-session.ts | Connects renderer delivery, lifecycle reset, producer pacing, and PTY session state |
| src/…/terminal-subscribe-method.ts | Selects JSON, binary, or lease-only terminal subscriptions and registers cancellation |
| src/…/terminal-subscribe-binary-snapshot.ts | Establishes a snapshot baseline before live binary output |
| src/…/terminal-multiplex-method.ts | Creates one connection that can carry many terminal streams |
| src/…/terminal-multiplex-initial-snapshot.ts | Publishes the multiplex baseline and trims output covered by its sequence |
| src/…/terminal-multiplex-flow-control.ts | Enforces stream and connection credits and performs overflow recovery |
| src/…/terminal-multiplex-input-frame.ts | Orders, settles, deduplicates, and acknowledges sequenced input |
| src/…/terminal-multiplex-cleanup.ts | Detaches streams, cancels pending waits, and releases view ownership |
| src/…/terminal-stream-replay.ts | Defines sequence-aware replay and bounded pending-output handling |
| src/…/ssh-relay-session.ts | Coordinates SSH provider generations, checkpoint recovery, quarantine, and recovery completion |
| src/…/ssh-pty-source-delivery-ledger.ts | Installs receiving activations and enforces ordered source recovery on the provider side |
| src/…/ssh-pty-consumer-recovery.ts | Keeps owner claims and per-PTY checkpoints across SSH reconnects |
| src/…/terminal-scrollback-snapshots.ts | Stores bounded scrollback tails that can seed a rebuilt terminal surface |
| src/…/terminal-history.ts | Scopes shell history to a worktree and records safe recovery metadata for local and WSL PTYs |
| src/…/terminal-history-deletion.ts | Moves worktree history to safe tombstones and drains removal without blocking PTY runtime work |
| src/…/terminal-history-async-delete.test.ts | Verifies that history deletion leaves the live root quickly and drains the detached tree |
| src/…/connect-pane-pty.ts | Creates the pane transport and joins input, output, replay, visibility, and disposal lifecycles |
| src/…/transport-output-callbacks.ts | Fences stream generations and resets per-stream replay and restore state |
| src/…/live-data-callback.ts | Orders live chunks against restored snapshots and routes them to the terminal view |
| src/…/reattach-result-handler.ts | Chooses the structural replay source and orders parked-pane snapshot probes with reattach payloads |
| src/…/pty-input-forward.ts | Applies input ownership, replay, query-reply, and write-admission rules |
| src/…/pty-liveness-verdict.ts | Defines the difference between confirmed exit, confirmed live state, and an unverifiable host |
| src/…/pty-startup-ingress.ts | Coordinates early PTY output with live query replies and startup handoff |