OpenClaw's embedded session path picked up a meaningful durability fix tonight. PR #111949, titled "fix: preserve transcript cursors across embedded turns," changes how normal append-only turns settle into session history.
The issue affected users running the embedded OpenClaw harness. After ordinary turns, generation-aware transcript cursors could be invalidated even though older transcript events had not changed. Consumers that depend on those cursors then had to reset and rebuild their transcript representation instead of resuming incrementally.
That is the kind of problem that usually shows up as excess churn rather than a dramatic crash. Context engines, transcript readers, and other cursor consumers get more work to do, and the system loses some of the efficiency that cursor-based history was supposed to provide.
What Changed
Session settlement now uses an explicit durability barrier instead of replacing the whole transcript. SQLite appends are already synchronously durable, so normal turns can remain append-only. The file-backed support path still materializes an initial pending transcript when needed, but genuine transcript rewrites remain reserved for the cases that actually require them.
The SQLite persistence path also keeps the canonical runtime event ID when a pre-persisted user turn has already claimed the same idempotency key. That detail matters because assistant events and later descendants rely on parent links. Preserving the exact event identity keeps those links valid without falling back to full transcript replacement.
The user-facing result is simple:
- Normal embedded turns can resume from the cursor instead of forcing a reset.
- Context engines can consume only newly appended events.
- SQLite avoids unnecessary delete-and-reinsert work.
- Cursor format, schema, configuration, and Plugin SDK contracts stay unchanged.
Why It Matters
OpenClaw's session history is more than a chat log. It is the substrate for context, recovery, replay, embedded tools, and external views of what happened. When cursor consumers are forced to rebuild after every ordinary append, the system pays a reliability and performance cost that compounds over long sessions.
By making the durability boundary explicit, this patch tightens the distinction between "new events were appended" and "old transcript history changed." That distinction is small in code but large in behavior. Incremental readers can trust the cursor again across routine embedded work.
Proof From The PR
The PR includes a real-process end-to-end test that builds an exact head, launches a fresh child Gateway with isolated home and SQLite state, runs two ordinary embedded turns, and proves the public raw cursor resumes with only the second turn in the returned page.
Focused regression tests also cover the settlement behavior and the canonical runtime user event path. The author reports 72 focused SessionManager and embedded settlement tests passing after the final correction, with a broader earlier cursor suite passing 149 tests. Linux Node 24 CI was green for the SQLite session flip E2E, lint, production types, and test types.
For operators and developers building on embedded OpenClaw flows, the headline is less wasted transcript work and more dependable incremental history.