openclaw - 💡(How to fix) Fix [Backup] Preserve or explicitly support session transcript JSONL for chat history restore

Problem

After #72251, openclaw backup create skips agent session transcript files:

• {stateDir}/agents/<agentId>/sessions/*.jsonl
• {stateDir}/agents/<agentId>/sessions/*.trajectory.jsonl

I understand why #72251 did this: these files can be live-appended while node-tar is reading them, which can trigger did not encounter expected EOF and abort the whole backup. Making live backups succeed is important.

However, sessions/*.jsonl are also the durable chat transcript files. They are meaningful for user-visible chat history restore, not just runtime logs. Skipping them changes the practical restore semantics of openclaw backup create: a backup can contain sessions.json and trajectory pointer sidecars, but not the actual conversation transcript content needed to recover historical chat records.

Observed behavior

On a hosted OpenClaw node running OpenClaw 2026.5.22, openclaw backup create reports:

Backup skipped 5 volatile files (live sessions, cron logs, queues, sockets, pid/tmp).

The source session directory contains transcript files:

~/.openclaw/agents/main/sessions/<session-id>.jsonl
~/.openclaw/agents/main/sessions/<session-id>.trajectory.jsonl
~/.openclaw/agents/main/sessions/<session-id>.trajectory-path.json
~/.openclaw/agents/main/sessions/sessions.json

The produced backup archive contains only:

.openclaw/agents/main/sessions/<session-id>.trajectory-path.json
.openclaw/agents/main/sessions/sessions.json

It does not contain:

.openclaw/agents/main/sessions/<session-id>.jsonl
.openclaw/agents/main/sessions/<session-id>.trajectory.jsonl

I also checked an older backup created with a version around 2026.5.7, and that archive did include *.jsonl under:

payload/posix/home/admin/.openclaw/agents/main/sessions/

So this appears to be a user-visible backup content change introduced after that line.

Why this matters

For disaster recovery / migration, restoring sessions.json without the corresponding transcript JSONL files is not enough to restore historical chat records. The UI or session listing may know about sessions, but the actual conversation content is missing.

There are existing issues that show session history is meaningful user data, for example #13616 asks for backup/restore of session history. This issue is narrower: the current backup create implementation now skips the files that carry that history.

Possible directions

I do not think the correct fix is to simply revert #72251, because live append races are real. But the current filter may be too coarse for backup/restore semantics.

Potential options:

1. Add a mode/flag such as --include-session-transcripts, possibly warning that the gateway should be stopped or quiesced for a consistent snapshot.
2. Add a --quiesce or gateway-drain mode before archiving transcripts.
3. Include only transcripts for sessions that are not active / not currently being written.
4. Copy transcript files to a staging directory with retry/size-stability checks, then archive the staged copy instead of streaming live files directly through tar.
5. Document clearly that openclaw backup create does not back up chat transcript content after #72251, if that is the intended contract.

References

• #72251: skipped volatile files to make live backups succeed.
• #72249: original EOF race report.
• #13616: broader request for backup/restore including session history.