OpenClaw Hardens SQLite Recovery and Crash-Durable State Publication

OpenClaw merged four related state-integrity changes into main on 25 July. Together they change how diagnostics inspect a live SQLite database, how background corruption results attach to a particular database generation, which historical schema shapes an upgrade will accept, and when a filesystem publication may claim durable success.

This is a meaningful recovery boundary, not a reason to replace database files casually. The practical response is to identify a release that contains the whole relevant set, take a consistent backup, and test diagnostics plus restore in staging before upgrading production state.

Operator triage

All four changes are merged to main. A merge is not proof that an installed stable or beta package contains them; verify the release or exact source revision you deploy.

Read-only no longer means journal-blind

PR #113404 fixes a subtle but serious diagnostic problem. OpenClaw’s read-only state access could use SQLite’s immutable=1 mode, which bypasses normal locking and journal handling. After an interrupted writer, that can produce a view that ignores recovery state or combines database and sidecar files from different moments.

The new path resolves SQLite’s canonical filename and prepares a private snapshot before validation:

• rollback journals and complete active WAL families use SQLite locking and online backup under a pinned read transaction;
• incomplete WAL families are copied with stable source and sidecar fingerprints, avoiding writes beside the source;
• the private snapshot is normalized, integrity-checked and validated against canonical indexes; and
• cleanup can retry without mutating the original state directory.

Upstream’s exact-head evidence reports 229 focused tests passing, with six expected Linux skips, and 58 successful CI jobs. The covered cases include hot rollback recovery, active WAL reads, same-size WAL reset, source replacement, missing WAL/SHM pairs and unsafe indexes.

Operator implication: a read-only command is not entitled to ignore SQLite’s coordination files. If you need an incident copy, use a supported snapshot or backup path. Copying the main file alone while a writer is active can remove exactly the evidence SQLite needs to produce a coherent view.

Quarantine now follows the bytes it verified

A second race sat between verification and enforcement. A background worker could report corruption, then the file could be repaired or atomically replaced before the owning process applied that result. The healthy replacement could inherit a failure belonging to the old file.

PR #113459 makes worker results advisory until the database owner reconfirms them. The generation identity covers the database, WAL and rollback journal using descriptor-pinned content hashing. Process-local and persisted quarantine state attach to that generation, and stale generation-bound records expire when the underlying state changes.

The quarantine store moves from schema v1 to v2. Existing records are migrated, while a confirmed corrupt generation still fails closed. Upstream reports 212 focused SQLite tests and a clean changed-surface check; it also records that an earlier metadata-only identity failed a same-size committed-write regression, prompting the stronger content-based design.

Interpretation: this separates two cases that must not be conflated—“these verified bytes are corrupt” and “this pathname once referred to corrupt bytes.” Recovery depends on trusting the former without permanently poisoning the latter.

Schema upgrades become deliberately less forgiving

PR #113473 advances the shared-state schema from v5 to v6 and per-agent state from v14 to v15. The important change is not the version numbers; it is the admission policy.

Version-specific preflight now permits only known historical optional or additive table groups. Missing stable tables, unknown partial schemas, unsafe indexes, inline unique autoindexes and primary-key collation drift are rejected before mutation. Recognized canonical indexes may be repaired, but the complete current schema must validate before the version update commits.

Session-sharing and suggestion stores also stop using lazy runtime DDL as a silent repair path. If a verified current database later loses one of those tables, access fails visibly instead of creating a new empty table that could make lost data look like a valid empty state.

Upstream reports 268 focused tests passing across shared and agent database schemas, maintenance, board parity, native schema guards and collaboration stores.

Operator implication: some structurally drifted databases that previously opened may now refuse to do so. That is intentional fail-closed behaviour. Preserve the rejected database, logs, WAL/journal family and pre-upgrade backup. Do not add empty tables by hand simply to satisfy startup—the missing content may be the incident.

Filesystem publication gets one durability contract

PR #113453 adopts @openclaw/fs-safe 0.4.7 across crash-sensitive publication paths and removes divergent local directory-sync implementations.

The shared boundary now covers SQLite snapshots and restores, backup and migration archives, memory exports, session transcript archives, generated Gateway TLS material, Reef audit/replay journals and QA atomic files. Strict commit paths reject I/O failures and explicit unsupported outcomes. Former best-effort callers retain unsupported-filesystem compatibility only through a narrow policy adapter.

Gateway TLS generation receives additional safeguards: staged certificate and key inodes are flushed before linking, directory durability receipts travel through publication, and rollback avoids deleting output when pathname ownership can no longer be proven atomically. Upstream reports 126 checks passing and an exact-head live Gateway run that generated mode-0600 TLS files and loaded them into a TLS 1.3 context.

This does not make every filesystem equally durable. It makes unsupported or failed durability more explicit and prevents strict workflows from quietly treating it as success.

A safe acceptance test

Before adopting a containing release:

1. Stop and identify writers. Know whether the Gateway, a maintenance command or another process owns the database.
2. Take a consistent backup. Preserve the complete SQLite family and OpenClaw-managed archives; do not cherry-pick the main file from a live WAL database.
3. Record versions and paths. Capture the current OpenClaw version, database paths and diagnostic output without exposing credentials or message content.
4. Exercise read-only diagnostics in staging. Doctor and update planning should see committed state and fail clearly on intentionally damaged fixtures.
5. Test a supported restore. Confirm a healthy replacement is revalidated rather than inheriting stale quarantine.
6. Test a corrupted copy. Remove a non-sensitive fixture table and confirm the upgrade fails without silently recreating it.
7. Verify publication artifacts. Check backup, archive and generated-TLS outcomes, including permissions and reported durability status.
8. Only then upgrade production. Keep the pre-upgrade backup until sessions, boards, scheduled work and authentication state have been checked.

Evidence and limits

OpenClaw Academy reviewed the four official merged pull-request records, landed commit chronology and cited exact-head test evidence. We did not kill a production writer, inject a real power failure, corrupt an operator database or independently reproduce the cross-platform filesystem matrix.

Upstream explicitly leaves broader high-I/O, Docker, WSL, macOS, architecture and fault-injection work in the larger SQLite durability campaign. Treat the merged fixes as substantial hardening, not proof that every storage platform and crash point is solved.

Bottom line

The common theme is identity: diagnostics must inspect one coherent SQLite generation, quarantine must attach to the bytes actually verified, upgrades must distinguish a historical schema from lost tables, and publication must prove the directory edges that make a rename durable.

That is the right direction. It also means damaged or unsupported state should fail more loudly. Operators should prepare for that with consistent backups and rehearsed recovery—not by weakening the checks that finally make the failure visible.