Sessions & Crash Recovery¶
A Harmony crash does not cost you the staging tree.
Until Assemble runs, that tree exists nowhere else in the world: there is no project format for it, and the vacuum reads the scene, which has not received anything yet. So OSA saves it, continuously, on its own.
What is saved¶
The staging tree, the selection, and the UI state — which panels are collapsed, which display toggles are on, where the splitters are.
The tree is the day's work. The UI state is a convenience: if collecting it ever fails, the tree is written anyway, because losing the splitter position is an annoyance and losing the tree is a day.
When it saves¶
Two timers, not one:
| Timer | Fires |
|---|---|
| Inactivity | a few seconds after you stop changing things — re-armed on every edit |
| Ceiling | a fixed maximum, whatever you are doing |
The ceiling is a second timer rather than a counter inside the first, because the inactivity timer is re-armed on every mutation — any deadline stored inside it would be pushed back forever by a busy session.
Where it is saved¶
%APPDATA%/Toon Boom Animation/Toon Boom Harmony Premium/
octo_scene_assembler/sessions/
One file per scene, named after the scene plus a hash. Not in the scene folder: the scene may never have been saved, and on Harmony Server the path is a logical one that needs mapping and is not guaranteed writable.
How it is written¶
tmp → the current file becomes .bak → atomic replace.
No instant leaves the target half-written. In a crash you either have the new file whole, or the previous one. There is one generation of backup, not a history.
Restoring¶
On open, if a session exists for this scene, a bar offers it:
| Button | Does |
|---|---|
| Restore | rebuild the staging tree from the saved session |
| Dismiss | delete the saved session |
Dismiss really deletes. A "dismiss" that only hides the bar means the same offer comes back on every open, forever.
With Auto-restore Session on (Preferences → Settings), the tree comes back without asking.
What the bar tells you¶
| Message | Means |
|---|---|
| Session restored — N nodes. | done |
| …(X could not be restored.) | the tree came back; part of "where I was" did not |
| The most recent session was corrupt; this is the previous one. | the .bak was used |
| The saved session is unreadable. | both copies failed to parse |
| This session was written by a newer version of OSA… | refused on purpose — applying a future format halfway would give you a tree that looks like yours and is not |
A corrupt session is never discarded in silence. Being told nothing is how a user concludes that autosave never worked.
Crash vs clean exit¶
On a clean close OSA removes a "running" marker. The absence of that marker on the next open is the only thing that distinguishes a crash from a normal exit — and that distinction is what lets the restore bar say something true.
Housekeeping¶
The sessions folder prunes itself: 20 files, 30 days, with the current scene's session always protected. Without that, the folder grows one file per scene forever and nobody goes there to clean it.
When autosave cannot write¶
If a save fails, a yellow message appears — once per failure streak, not on every tick, and it clears itself after a few seconds.
The reason goes to osa.log, in the same folder as the sessions, and it names the cause. If the failure was a value that could not be serialised, the log names the exact key, because "it failed" is not something anybody can act on.
Where to look when something is wrong
%APPDATA%/Toon Boom Animation/Toon Boom Harmony Premium/octo_scene_assembler/osa.log
That file is also how support reads what your Harmony did without needing your scene.