OpenClaw Main Adds Native Session Branch Switching—With One Race Still Open

OpenClaw’s macOS and iOS chat apps can now list and switch between session transcript branches on main. The more important part of the merged work is underneath the menu: queued messages are now tied to a branch epoch so a rewind, fork or branch switch does not casually replay an offline message onto a different history.

That is a material workflow change for native-app users who rewind sessions or move between clients. It is also not available in a current package yet. PR #112056 merged on 21 July at 17:59 UTC, after the current 2026.7.2-beta.3 release was published.

Operator decision

• macOS and iOS users: wait for a release that explicitly includes PR #112056 before expecting the branch menu or branch-aware outbox.
• Source-build testers: test branch changes with queued offline messages, app restarts and multiple windows—not just the visible switcher.
• Cross-client users: do not treat this as a complete transactional guarantee. The merged pull request documents a remaining race when another client switches branches while a send is reaching the Gateway.
• Web Control UI users: branch switching already existed in the web lineage. This change brings native parity and hardens the shared native durable-send path; it is not a new web feature.

“Un-rewind” reaches the native apps

A rewind or fork creates another possible history for a session. Before this change, OpenClaw’s web Control UI could expose and switch those branches, but the shared native chat interface used by macOS and iOS could not.

The merged native composer shows a branch control when more than one branch exists. Opening it refreshes the branch list, and each choice includes message-count and timestamp context. Selecting a non-active branch calls the Gateway’s sessions.branches.switch path.

This matters because rewinding no longer has to behave like a one-way trip in the native UI. An operator can inspect or return to another transcript leaf rather than losing access to it from the app.

The dangerous bit was the offline queue

A branch menu alone would have made an existing consistency problem easier to trigger.

The native clients keep a durable SQLite outbox so text can survive temporary disconnection or a process restart. Before this merge, an outbox row did not record which branch state owned it. A message queued before a rewind, fork or cross-client switch could therefore flush later against whichever branch had become active.

The patch adds a branch epoch to each session-and-agent outbox scope. Messages stamp the current epoch when they enter the queue. A confirmed branch mutation increments that epoch and parks stale rows instead of silently sending them into the newly active history.

Rewind, fork and switch also share a session-mutation lease. Active runs, send or abort work, and pending outbox state can block the mutation. If a lease goes stale, the implementation marks the scope as needing reconciliation rather than assuming it is safe to resume sends.

Those are sensible durability semantics: branch mutation and queued delivery are coordinated in local storage, so offline queueing does not need a Gateway round trip in its hot path.

Retries avoid resurrecting an old delivery

There is another subtle failure case. A client can lose confirmation after a queued send may already have reached the Gateway. Reusing the same delivery identity after parking that row could let Gateway idempotency associate the retry with the earlier attempt.

The merged design records that uncertainty and gives a possibly accepted parked row a fresh delivery identity when the user retries. Delivery callbacks are attempt-versioned as well, so a late callback from a superseded attempt becomes a no-op instead of changing the newer row’s state.

The pull request reports 157 Swift tests across seven suites covering mutation gating, epoch parking, restart replay, migrations, reconciliation, retry identity and stale callbacks. GitHub reports the pull request as merged, with the merge commit at 8f31892b5509606399eb56cad3650a0acb9ed124; the commit’s available check runs were successful or skipped at verification time.

These are upstream results, not an independent OpenClaw Academy reproduction. We inspected the merged source and API metadata, but did not build or run the macOS/iOS clients from this unreleased commit.

One cross-client race remains

The pull request explicitly accepts one unresolved boundary. If another client switches the active branch while a send is arriving at the Gateway, that message can still land on the newly active branch.

The reason is protocol-level: the send contract does not carry an expectedActiveLeaf precondition. Local epochs can stop stale rows known to one app, but they cannot make a Gateway accept a message only if the active transcript leaf still matches the sender’s view.

Closing that gap requires a conditional-send contract at the Gateway, not another local queue check. Until such a precondition ships, operators using several clients should verify the active branch before sending consequential instructions around a concurrent rewind or switch.

Availability

At verification time, the official channels remained:

• npm latest: 2026.7.1-2
• npm beta: 2026.7.2-beta.3
• npm alpha: 2026.5.19-alpha.1

The current beta release was published on 18 July; the native branch work merged on 21 July. A merged change on main does not prove inclusion in an installed app or npm package.

Bottom line

OpenClaw’s native branch switcher is not merely UI parity. Its real value is coordinating transcript mutation with a durable offline outbox, preventing known stale queued messages from drifting into another branch after a rewind, fork or switch.

The design substantially narrows that risk, but does not eliminate the cross-client arrival race. Treat the feature as unreleased source work, and test the queue and concurrency edges when a package containing it appears.

Verification note: OpenClaw Academy checked the official pull-request and commit APIs, merged source files, GitHub check-run metadata, GitHub release metadata and npm distribution tags on 21 July 2026. Behavioural claims and test totals are attributed to upstream evidence; we did not independently run the Apple clients.