Session recovery
Getting work back after a crash, a reboot, or a session that seems to have vanished.
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. Detached only |
| Rebooted | Running after the daemon restarts |
Ran /detach | Running |
Ran /stop | Turn cancelled, session alive |
Ran /quit | Session ended |
| Left it past the retention window | Gone |
Only the last two actually lose a session. Everything else is a reattach.
nala sessions list
This is the authoritative answer to "does it still exist." Ask it before concluding anything.
The app crashed
Symptom: NALA 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:
nala sessions list
nala task 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
nala doctor
nala 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
nala doctor --json
Compare the resolved data directory against the application you expect.
See CLI configuration.
The session exists but the pane is blank
Likely cause: the client did not reattach cleanly.
Repair: close the desktop fully and relaunch:
nala 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:
nala task 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.