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

---

📜 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

[buenaflor]

Today session.json only gets written from the transport queue. This PR adds a second writer, persistCurrentSession, which writes the live session straight to disk. #5921 calls it when Flutter reports an unhandled error that didn't kill the app.

The issue is that the SessionStart envelope is queued, so it can land after that:

session S starts       → SessionStart(S) goes into the transport queue
unhandled Dart error   → S gets flagged, persistCurrentSession writes it to session.json
SessionStart(S) drains → session.json moved to previous_session.json, so last run's session is gone
                       → envelope's unflagged copy of S written over session.json
app killed             → S comes in as exited instead of unhandled

So we skip the move and the write if the SessionStart is for a session we already persisted. Nothing else changes.

[Copilot]

Pull request overview

This PR updates the core EnvelopeCache session persistence logic to prevent a delayed SessionStart write (processed on the transport executor) from rotating/overwriting a newer, synchronously persisted live session snapshot.

Changes:

• Added EnvelopeCache.persistCurrentSession(Session) and tracking via lastPersistedSessionId to protect newer on-disk session state from delayed SessionStart envelopes.
• Refactored session extraction into readSessionFromEnvelope(...) and guarded rotation+write in a shared sessionLock critical section.
• Expanded EnvelopeCacheTest coverage for same-SID delayed starts, different-SID rotation behavior, and null-SID handling.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
sentry/src/main/java/io/sentry/cache/EnvelopeCache.java	Adds synchronous current-session persistence and prevents stale SessionStart envelopes from clobbering newer session snapshots.
sentry/src/test/java/io/sentry/cache/EnvelopeCacheTest.kt	Adds tests validating same/different/null SID behaviors with the new persistence mechanism.
sentry/api/sentry.api	Updates the API surface to include the new persistCurrentSession(Session) method.

Suppressed comments (1)

sentry/src/main/java/io/sentry/cache/EnvelopeCache.java:295

• readSessionFromEnvelope() calls items.iterator() twice (hasNext() and next()), which creates two independent iterators. Using a single Iterator avoids redundant work and prevents surprising behavior for non-collection Iterables.

    final Iterable<SentryEnvelopeItem> items = envelope.getItems();

    // we know that an envelope with a SessionStart hint has a single item inside
    if (items.iterator().hasNext()) {
      final SentryEnvelopeItem item = items.iterator().next();

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[runningcode]

LGTM!

[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.}