Skip to main content

Session Management

What survives a close, a restart and a crash in Daintree: the agent resume journal, terminal scrollback serialization, drafts, and warm versus cold project state.

Updated
Reviewed

Three things called a session

"Session" means three different things in Daintree, at three different scopes. Most confusion about what comes back after you close something is really confusion about which of the three you were looking at.

ScopeWhat it isWhat brings it back
A terminal's agent sessionOne resumable conversation with one agent, identified by a session id the agent's CLI owns.The resume journal: a record written on close when a resumable session ID was captured.
A terminal's scrollbackThe visible output the terminal had on screen, serialized to a .restore file.Replay on reopen, marked with a separator banner.
A project's renderer stateThe live Chromium view behind a project, warm in memory or cold and rebuilt on demand.The warm view cache, or a cold reload from the saved layout on disk.

Above all three sits the app's crash-recovery snapshot, which is what a bad exit falls back to. See Crash Recovery for that layer.

What survives what

The whole subject in one table. Process is the agent's OS process, view is the panel and its scrollback, and conversation is whether the agent can pick the thread back up from the resume journal.

What you doProcessViewConversation
Switch worktreeKeeps runningRestored on returnNothing stopped, so nothing to resume
Switch projectKeeps running. Eviction affects the view, not the PTYWarm views reattach, cold ones rebuildNothing stopped, so nothing to resume
Sleep project, or idle auto-closeKilledLayout and available scrollback restored on reopen, under a "preserved while the terminal was stopped" bannerResumed on reopen, if a session id was captured
Close a panelRuns for 20 seconds in the trash, then killedRestorable during those 20 secondsResumable once the record is written, at removal or expiry
Delete a worktreeKilled, unless you uncheck Close all terminalsOn a rescue card, if terminals survivedThe record is scoped to a directory that no longer exists, so it cannot relaunch
Quit and choose Keep Agents Running, then reopenKeeps running in the background with every window closedThe same windows come back, reattached to the live terminalsNothing stopped, so nothing to resume
Quit and reopen DaintreeKilledLayout restored for every project that was live, not just the one each window showed. Scrollback too, under the size limitsResumed on relaunch, if a session id was captured
System sleep and wakeKeeps running, PTYs pause and resumeUnchangedNothing stopped, so nothing to resume
CrashKilledLayout restored from the crash backup. Scrollback is notResumable, if a session id was captured before the crash
Note
The pattern behind the table: views are persisted, processes are not, and a conversation is only as recoverable as the session id behind it. The closed-session journal is written on close. A crash may leave no journal entry, while a session ID already saved with the panel can still support restoration. That is why an id assigned at launch matters, and why agents differ: see Agent Session Resume for which CLIs support what.

The Daintree Assistant's own conversations follow the same rule: they survive a quit, a crash or the CLI exiting on its own, and Resume a past session… in the Assistant panel picks up an earlier one. See Past sessions.

The table describes a project on this machine. A project on a remote host keeps its terminals and agents on the host: closing your laptop, disconnecting or switching the window away leaves them running there, and the window catches up when it reconnects. See When the Connection Drops.

Where the detail lives

  • Persistence and Restore for what is written to disk and read back: panel layout, terminal scrollback, drafts, window state, where it is stored, and how to turn it off.
  • Resume Agents and History for the agent conversation journal: what writes a record, what a record holds, every place you can resume from, session ids, bookmarks, and retention.
  • Project Memory for warm and cold projects, eviction and freeze, reclaiming memory, auto-closing idle projects, and what happens across system sleep.

When the exit was not clean

Everything above assumes a close Daintree saw coming. For one it didn't, the crash-loop guard takes over: three unclean exits inside a 30-minute sliding window boots the app in safe mode and quarantines the panels that look like the cause, which breaks the loop; five stops auto-relaunch entirely. The window decays on its own, so once the most recent unclean exit ages out the next launch comes up normally. After a single crash, restoring the session brings the whole window set back.

This is where an assigned-at-launch session id earns its keep. The crash path recovers the panel layout from its backup, but not the scrollback, and the conversation is only resumable if the agent's id was known before the crash rather than read off a teardown that never ran. Not every CLI works that way, so what you get back varies by agent. See Crash Recovery for the full picture.