Document terminal block lifecycle hardening design

[vorporeal]

Description

Stack PR 1/8.

Problem

Warp uses shell lifecycle hooks such as Preexec, CommandFinished, and Precmd to keep its block model and prompt grids aligned with the real shell. Those hooks and local command starts currently enter through separate paths and can mutate the active block without one central check that the transition is valid or refers to the expected block.

That makes exceptional hook sequences dangerous rather than merely ignorable. A missing, duplicated, stale, or out-of-order hook can cause Warp to apply prompt metadata to the wrong block, mutate a finished prompt grid, lose preserved command or output, create phantom blocks, repeat once-per-block side effects, panic, or remain stuck in an executing state. Shared sessions add version skew and a second event stream, which makes conservative handling especially important.

Proposed direction and rollout

This spec defines the invariants and staged implementation for making those transitions recoverable without changing correctly ordered behavior. The design first adds completion metadata to Precmd, then types that evidence and centralizes the existing mutation pipeline before placing an exhaustive lifecycle coordinator in front of it. Later stages safely reconcile repeated and prompt-only Precmd hooks, recover a missing CommandFinished only from trustworthy completion metadata, and enable recovery in dogfood.

The sequencing is part of the safety design: protocol fields can reach stable before recovery launches, behavior-preserving refactors land before state-mutating recovery, and production recovery remains disabled during the compatibility soak.

Review guidance

• Do the behavioral guarantees cover the important user-visible corruption and stuck-state failure modes without changing normal lifecycle behavior?
• Are the transition policies conservative when evidence is duplicated, stale, malformed, prompt-only, or otherwise insufficient to prove completion?
• Does the rollout give version-skewed shared sessions enough compatibility time before recovery is enabled broadly?

Testing

• Documentation-only change; reviewed against the implementation stack.

[vorporeal]

• Enable terminal lifecycle recovery in dogfood #12859
• Recover missing CommandFinished hooks from Precmd completion metadata #12858
• Safely reconcile repeated and prompt-only Precmd hooks #12857
• Gate terminal lifecycle transitions with a coordinator #12856
• Centralize terminal lifecycle mutations #12855
• Distinguish Precmd hooks with completion metadata from prompt-only hooks #12854
• Add command completion metadata to Precmd #12853
• Document terminal block lifecycle hardening design #12852 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.