[aristidesstaffieri]

What

Background messages that change accounts, secret sources or session state now run one at a time behind a single promise-chain lock in the extension message listener. That covers create, recover, add, import, hardware import, migration, phrase generation and storage, password confirmation, rename, account switch, sign-out and reset, and the session-lock alarm takes the same lock. A message holds the lock from the moment it builds its session store until its final state has been flushed to storage.session, so the next one starts from what the previous one wrote. Read-only messages skip the lock, so a slow Scrypt import doesn't hold up something like loading the account.

Why

Each message builds its own session store from storage.session and writes the whole state back, and the account lists in storage.local are read-modify-writes. When the popup, sidebar or fullscreen send account changes at the same time, the later write drops the earlier one, losing an imported account, a rename, a source label, a derivation index or a sign-out, and two adds on the same phrase can get the same index.

Closes stellar/freighter-private#112

Screenshots / video

N/A, no UI change.

Checklist

• I have read CONTRIBUTING.md and this PR meets its requirements.
• This PR has narrow scope and does not mix refactoring with feature changes.
• This PR adds tests for the new functionality or fixes.
• These changes have been tested in both Chrome and Firefox.
• This PR includes relevant before and after screenshots for UI changes.
• I took the time to review my own PR.

[github-actions]

PR Preview build is ready: https://github.com/stellar/freighter/releases/tag/untagged-76fe3b3cc6e3a2dda4a4
Backend: sandbox (aristidesstaffieri). SDF collaborators only — install instructions in the release description.

[Copilot]

🟡 Changes recommended

Critical queueing and persistence flaws can block sign-out or auto-lock, expose stale session state, and leave an unlocked session available for signing.

4 open issues

• Queued account switches can cause valid mutations to be rejected · New
• Unbounded subscription fetch blocks sign-out and auto-lock · New
• Handler rejection can release the queue before session writes flush · New
• Stale queued alarm can clear a renewed or unlocked session · New

What changed in this PR

This PR serializes account and session mutations in Freighter’s background listener to prevent concurrent requests from overwriting each other, while allowing read-only requests to proceed independently.

Changes:

• Adds a shared promise-based queue for account-mutating messages.
• Places session auto-lock behind the same queue and awaits session persistence before releasing successful mutations.
• Adds concurrency regression tests and lock-ordering tests.

File	Description
extension/​src/​background/​index.ts	Integrates mutation locking, session flushing, and queued auto-lock handling.
extension/​src/​background/​helpers/​account-mutation-lock.ts	Defines queued message types and the shared lock helper.
extension/​src/​background/​helpers/​__tests__/​account-mutation-lock.test.ts	Tests execution order and queue recovery after rejection.
extension/​src/​background/​__tests__/​initAlarmListener.test.ts	Adds the session-flush mock required by alarm handling.
extension/​src/​background/​__tests__/​concurrentAccountMutations.test.ts	Tests concurrent account changes, delayed persistence, sign-out, and read-only responsiveness.

_{Review effort: Balanced}