# Session recovery Source: https://docs.ideharmony.com/troubleshooting/session-recovery Sessions live in the daemon, not in the window. That is why most "lost work" turns out to be recoverable — and it tells you where to look. ## First: what actually happened | What you did | Session state | |---|---| | Closed the window | **Running.** The UI hid to the tray | | Chose **Quit UI** | **Running.** The UI exited and the local host retained it | | Put the laptop to sleep | **Paused by the OS**, then rechecked on wake | | Rebooted | Original process ended; durable pane/history/task state restores after the daemon starts | | Ran `/detach` | **Running** | | Ran `/stop` | Turn cancelled, session alive | | Ran `/quit` | Session ended | | Left it past the retention window | Gone | Only the last two deliberately end the agent session or pass its retention window. A window reopen, Quit UI relaunch, or sleep/wake is a live reattach. A reboot is a restore and possible provider resume, not the same OS process. ```powershell harmony sessions list ``` This is the authoritative answer to "does it still exist." Ask it before concluding anything. --- ## The app crashed **Symptom:** Harmony exited unexpectedly and reopened without your panes. **Expected evidence:** a crash-restore banner on launch, with a progress list as panes reattach. **Repair:** accept the restore. Panes reattach to sessions the daemon still holds. **If no banner appears:** there was no restorable state recorded. Check what the daemon still has: ```powershell harmony sessions list harmony tasks list ``` Tasks and artifacts are durable independently of panes. **A lost pane does not mean lost work** — the task record and any artifacts survive. --- ## I rebooted and everything is gone **Likely cause:** you are looking at a different workspace, or the daemon has not started yet. **Safe diagnostic** ```powershell harmony doctor harmony sessions list --all-workspaces ``` `--all-workspaces` matters. `list` defaults to the current workspace, so a session created elsewhere looks absent when it is merely out of scope. --- ## `sessions list` shows nothing, but the app is running **Likely cause:** instance isolation. The CLI reached a different daemon. The runtime is namespaced by data suffix — data directory, socket, pipes. Development builds use `-dev`. A CLI invocation under a different suffix talks to a different daemon and will honestly report nothing. **Safe diagnostic** ```powershell harmony doctor --json ``` Compare the resolved data directory against the application you expect. See [CLI configuration](/docs/cli/configuration). --- ## The session exists but the pane is blank **Likely cause:** the client did not reattach cleanly. **Repair:** reopen the tray window first. If the UI itself is stuck, choose **Quit UI** (not **Exit Harmony**) and relaunch: ```powershell harmony desktop ``` **When not to retry:** do not delete the data directory to force a clean state. That is where sessions, tasks, and artifacts live. It is not a cache, and deleting it converts a recoverable problem into a permanent one. --- ## I stopped it by accident `/stop` cancels the in-flight turn — the session survives, so reattach and continue. `/quit` ends the session. That is not recoverable. > [!IMPORTANT] > `/detach` and `/stop` are the pair people confuse under pressure. Detach frees > your terminal and leaves the agent working. Stop cancels the work and leaves > you attached. When in doubt, detach. --- ## Recovering the work rather than the session Even when a session is genuinely gone, the durable record usually is not: ```powershell harmony tasks list ``` Tasks carry state and history. Artifacts are durable Markdown that outlive the session that produced them. If an agent wrote a summary or a plan to an artifact, that survives. > [!TIP] > This is the argument for asking agents to write artifacts as they go. A > conclusion that exists only in a transcript is a conclusion you can lose. --- ## Preventing the next one - **Detach rather than quit** when stepping away. - **Write artifacts** at natural boundaries. - **Keep one project per workspace** so scope questions do not arise. - **Do not delete the data directory.** ## Related - [Session survival](/docs/concepts/session-survival) - [Sessions in the TUI](/docs/tui/sessions) - [Daemon problems](/docs/troubleshooting/daemon)