Persistence Without Magic
Herdr uses the word persistence for several different mechanisms, and choosing among them requires asking what must survive. This chapter follows a live agent and its terminal through detach, server restart, screen-history replay, native conversation restore, and live handoff. The practical result is a decision rule: preserve the original process when continuity matters most, accept reconstruction when layout is enough, use history when recent context is worth its exposure, and treat handoff as an experimental transfer of ownership rather than as a more reliable snapshot.
Detach preserves a live world; restart rebuilds a model
The strongest form of persistence is the least mysterious. When a person detaches a Herdr client, the background server continues to own the panes and their PTYs. The shell, coding agent, test process, development server, or other command remains the same process. Reattaching later reconnects a client to that live runtime, so the agent conversation continues because the agent never stopped. A lost SSH connection can be inconvenient without being a process failure when the server is running on the other side.
This guarantee depends on the server staying alive. Explicitly stopping the server is a different transition: server-owned pane processes end. A later launch can load the saved organization of the session, but it cannot pretend that the old process is still present. The difference is worth stating plainly because “I can see my panes again” and “my work resumed” are often treated as the same outcome. Herdr's design says they are not.
A normal restart begins with a snapshot of application state. The snapshot records the workspace arrangement, tab layouts, pane working directories, focus, labels, public identity information, and—when applicable—agent identity, native session reference, or launch arguments. It does not serialize an arbitrary shell, a running test server, an open network connection, or the internal memory of a coding agent. During restoration, Herdr creates new terminal runtimes in the saved locations and rebuilds the layout around them.
That reconstruction is valuable even when it is incomplete. A person returning to a large project does not have to recreate every workspace, tab, split, label, and working directory by hand. The saved shape provides orientation and a place to restart the processes that matter. But the snapshot's boundary also explains why a development server that was listening before the restart is not automatically listening afterward, and why a test that was halfway through cannot be assumed to have completed.
The saved layout is versioned, and the persistence code treats incompatible data conservatively. A newer snapshot version can be ignored rather than interpreted as if its fields were understood. Invalid session data is likewise not a license to guess. The save path writes through a temporary file and renames it into place, which helps avoid leaving a half-written JSON file after an ordinary write failure. That is useful file-handling hygiene, not a transaction that makes every runtime event durable at the exact moment it occurs.
Pane screen history is a separate layer. When enabled, Herdr stores recent terminal contents next to the session snapshot and can replay that text after a full server restart.