fix(core): [Unhandled Sessions 2] Don't let a queued SessionStart overwrite a newer session

[buenaflor]

PR Stack (Unhandled Sessions)

• feat(core): Unhandled Sessions #5915 (collection)
• feat(core): [Unhandled Sessions 1] Add Unhandled session state and non-terminating error flag #5919
• fix(core): [Unhandled Sessions 2] Don't let a queued SessionStart overwrite a newer session #5920
• feat(android): [Unhandled Sessions 3] Add internal non-terminating envelope capture #5921
• feat(android): [Unhandled Sessions 4] Add session update API for unsampled hybrid errors #5990

---

📜 Description

storeEnvelope runs on the transport executor, so a SessionStart reaches disk whenever the queue drains rather than when the session actually started. This PR adds EnvelopeCache.persistCurrentSession(Session), a second writer that writes the live session synchronously and bypasses that queue, which makes the two orderings diverge. #5921 is what calls it.

When they diverge, the SessionStart path rotates the still-running session into previous_session.json and overwrites session.json with the envelope's older copy. That drops any error recorded since the session started, and it deletes the previous run's session that MovePreviousSession filed at init, so that session is never reported.

persistCurrentSession now records the id it wrote in lastPersistedSessionId, and the SessionStart path skips both the rotation and the write when the starting session matches it. Two supporting changes: reading the envelope's session moved out of updateCurrentSession into readSessionFromEnvelope so the id is available for that comparison, and the rotation and the write now share one sessionLock critical section so persistCurrentSession cannot land between them.

Skipping the write is only safe while session.json still holds what persistCurrentSession put there, so the id is cleared whenever that stops being true:

• SessionEnd deletes session.json without looking at whose session it holds. Scopes.startSession() queues the end of the old session and the start of the new one back to back, so a persist for the new session can land in between and then be deleted by the old session's SessionEnd. That branch now clears the id under sessionLock, so the delayed SessionStart writes the session back instead of skipping.
• writeSessionToDisk swallowed every Throwable and returned void, so a failed persist still recorded the id — and since the stream truncates the file on open, it could leave session.json truncated with no queued write left to repair it. It now returns whether the write succeeded, and only then is the id recorded.

💡 Motivation and Context

Needed by #5921, which mutates the live session in place and persists it so the unhandled flag survives process death.

Nothing outside the hybrid capture path is affected. lastPersistedSessionId starts null, so until persistCurrentSession actually runs, both branches behave exactly as they do today.

💚 How did you test it?

EnvelopeCacheTest covers a delayed same-id start preserving a newer unhandled snapshot and a newer error count, different-id starts still rotating, and null session ids rotating rather than being treated as the same session. Two more cover the cleared id: a SessionEnd landing between the persist and the delayed start, and a persist whose write failed. The pre-existing SessionStart hint saves unfinished session to previous_session file guards the default path, where nothing was persisted out of band.

📝 Checklist

• I added GH Issue ID & Linear ID
• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

The capture API in #5921.

#skip-changelog

⚠️ Merge this PR using a merge commit (not squash). Only the collection branch is squash-merged into main.

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	318.25 ms	359.51 ms	41.26 ms
Size	0 B	0 B	0 B

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
85fd8b1	306.66 ms	377.10 ms	70.44 ms
62b579c	299.75 ms	364.84 ms	65.09 ms
7414e9b	322.49 ms	378.88 ms	56.39 ms
44472da	319.72 ms	351.90 ms	32.18 ms
62b579c	318.48 ms	367.71 ms	49.24 ms
694d587	305.45 ms	378.38 ms	72.94 ms
2195398	319.02 ms	342.38 ms	23.36 ms
5865051	324.24 ms	356.02 ms	31.78 ms
bb0ff41	344.70 ms	413.82 ms	69.12 ms
092f017	353.13 ms	433.84 ms	80.71 ms

App size

Revision	Plain	With Sentry	Diff
85fd8b1	0 B	0 B	0 B
62b579c	0 B	0 B	0 B
7414e9b	0 B	0 B	0 B
44472da	0 B	0 B	0 B
62b579c	0 B	0 B	0 B
694d587	1.58 MiB	2.19 MiB	620.06 KiB
2195398	0 B	0 B	0 B
5865051	0 B	0 B	0 B
bb0ff41	0 B	0 B	0 B
092f017	0 B	0 B	0 B

Previous results on branch: feat/unhandled-sessions-cache

Startup times

Revision	Plain	With Sentry	Diff
6376fbe	313.53 ms	364.04 ms	50.51 ms
783a09c	356.23 ms	424.70 ms	68.47 ms
d73395c	315.63 ms	350.86 ms	35.23 ms

App size

Revision	Plain	With Sentry	Diff
6376fbe	0 B	0 B	0 B
783a09c	0 B	0 B	0 B
d73395c	0 B	0 B	0 B

[sentry]

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.53.0 (1)	release

⚙️ sentry-android Build Distribution Settings

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ef55c1a. Configure here.}

[sentry]

Bug: When a new SessionStart envelope rotates the session file, lastPersistedSessionId is not updated, leading to a potential state inconsistency with stale envelopes.
_{Severity: LOW}

Suggested Fix

To ensure state consistency, update the lastPersistedSessionId variable with the new session's ID immediately after writeSessionToDisk is called within the SessionStart handling block.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: sentry/src/main/java/io/sentry/cache/EnvelopeCache.java#L143-L148

Potential issue: When handling a `SessionStart` envelope for a new session, the code
correctly rotates the old session file and writes the new session to
`current_session.json`. However, it does not update the `lastPersistedSessionId`
variable. This creates a state inconsistency between the in-memory session ID cache and
the on-disk session file. If a stale envelope for the old session ID arrives afterward,
the `isAlreadyPersisted` check will incorrectly return `true`, causing the write to be
skipped. This bug requires out-of-order envelope delivery to manifest.

[markushi]

sounds valid!