Skip to main content
Harmony
Download

Durable sessions

PreviewAvailable on: WindowsShips in the preview channel only. Not a stable release.

Terminals that outlive the UI, reattach after sleep, and restore honestly after a restart.

A Harmony terminal is not a process owned by a window. It is a PTY session owned by the local session host and daemon. The UI is a disposable view: it can detach without ending the underlying work, while durable checkpoints make restart recovery possible when the original OS process cannot survive.

What survives what

EventWhat happens
Close the desktop windowHarmony hides to the tray. The same local PTYs keep running; reopening the window reattaches with scrollback.
Choose Quit UIThe Electron interface exits while the daemon/session host keeps local sessions running in the background. Relaunch to reattach.
Close the laptop / OS sleepThe operating system pauses every local process. On wake, Harmony renews session authority, rechecks process state, and reattaches. Work does not compute while the hardware sleeps.
Reboot the machineNo OS process survives a reboot. Harmony restores pane layout, terminal history, tasks, and checkpoints from disk; an agent resumes only when its provider has a valid resume binding, otherwise Harmony restores the shell and shows the available recovery path.
Choose Exit HarmonyHarmony deliberately stops the background processes. Durable layout/history checkpoints remain available for the next launch, but this is not a same-process reattach.
Suspend a sessionSuspended sessions persist to disk with a 7-day TTL. Resume any time within the week with nala resume <sessionId>.
Agent restartHarmony captures provider resume bindings when available and reports whether the result was reattached, respawned, or needs help. It does not invent exact continuation when a provider cannot prove one.

Scrollback is configurable from 1,000 to 100,000 lines per pane and is replayed on reattach.

The launch and reattach path

Launch and session survivalA launch intent is validated, then a slot is reserved on the session host, then the process launches and registers as a principal, bootstraps, and reaches readiness. From that point the session is owned by the daemon rather than by any client. Closing a client or choosing Quit UI detaches it and the session keeps running; reopening reattaches to the same process. Laptop sleep pauses the machine and Harmony rechecks the session on wake. A reboot ends the process, then restores durable workspace state from disk. Stopping is a separate, deliberate action that ends the live session.LAUNCHIntentyou askValidateReserve hostRegister principalBootstrap → readyOWNED BY THE DAEMON FROM HERESession lives in the daemonclose / Quit UI → reattach · sleep → pause / wake · reboot → restore · /stop → endClosing the UI preserves the live session. Reboot preserves durable workspace state, not the OS process.
Everything above the band belongs to launch. Everything below belongs to the daemon, which is why a client is disposable.

How recovery works

The daemon checkpoints session state to disk continuously. A live reattach keeps the same process. A restart recovery reconstructs panes and scrollback, then uses only the resume capability that the agent/provider actually reports. Shell integration does the quiet bookkeeping:

  • OSC 133 marks prompt boundaries, so command history and status survive meaningfully, not just as raw text.
  • OSC 7 reports the working directory, so restored panes reopen in the right folder.
  • OSC 9/99/777 drive desktop notifications; OSC 7727 keeps the git branch indicator live.

Hooks for PowerShell, Bash, and CMD are injected automatically. Nothing to configure.

Pausing on purpose: /stay and checkpoints

Inside the TUI, /stay pauses a session with a durable checkpoint (options: --now, --after-tool, --detach, --reason). /resume (or its friendly alias /come) picks it back up, in any terminal, on any surface.

nala sessions list          # everything the daemon is holding
nala sessions show <id>     # details of one session
nala resume <sessionId>     # bring it back
nala sessions archive <id>  # tidy it away

Why this changes how you work

Durability removes the two classic terminal taxes: the "don't close that window" anxiety, and the "rebuild context every morning" ritual. Long-running agents can run overnight while the machine stays awake; a week-long debugging saga can retain one durable record; and a reboot restores the saved workspace without pretending the original process survived. It also gives A2A messaging a durable inbox and cursor, so delivery does not depend on the UI being open.