feat(android): [Unhandled Sessions 3] Add internal non-terminating envelope capture

[buenaflor]

PR Stack (Unhandled Sessions)

• feat(core): Unhandled Sessions #5915 (collection)
• feat(core): [Unhandled Sessions 1] Add Unhandled session state and pending marker #5916
• fix(core): [Unhandled Sessions 2] Make session cache writes session-id aware #5917
• feat(android): [Unhandled Sessions 3] Add internal non-terminating envelope capture #5918

---

📜 Description

Adds InternalSentrySdk.captureEnvelopeNonTerminating(byte[]) for hybrid runtimes where an unhandled exception does not terminate the process.

Compared to captureEnvelope(byte[], boolean), the new path does not treat handled=false as a crash. Instead it:

• marks the current session pending-unhandled and increments its error count,
• keeps the session Ok with the same session id on the scope,
• attaches no session item to the envelope and starts no new session,
• persists the session so the marker survives process death.

The session is finalized later by normal lifecycle (endSession, background, or previous-session recovery) as unhandled, unless a native crash escalates it to crashed. Abnormal and Crashed remain authoritative, and captureEnvelope(byte[], boolean) is unchanged for the SDKs already using it.

Also in this PR:

• Scope.IWithSession is widened to public so InternalSentrySdk can mutate the session under the scope lock. This is its only consumer, hence it lives here rather than in PR 1.
• A shared private readEnvelope helper for both capture paths, and catch (Throwable) narrowed to catch (Exception) so OutOfMemoryError and friends propagate instead of being swallowed. Note IEnvelopeReader.read declares only IOException but also throws unchecked IllegalArgumentException for malformed payloads, which is why the helper still catches Exception.

💡 Motivation and Context

Flutter currently forwards handled=false events through the terminating hybrid capture path. That marks the session crashed and may start a replacement session even though the Flutter process keeps running, incorrectly lowering crash-free session rates.

This follows the session protocol's unhandled status for exceptions that are unhandled by the application but do not terminate the process.

💚 How did you test it?

New InternalSentrySdkTest coverage for: the session staying Ok with the same id and the marker persisted to disk; endSession afterwards finalizing as unhandled; and a subsequent hard crash through the existing terminating API finalizing the old session as crashed (clearing the marker) and starting a fresh Ok session. Existing captureEnvelope tests confirm the terminating path is unchanged, including malformed-payload handling.

📝 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.
• Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

Update the Flutter Android bridge to use captureEnvelopeNonTerminating for non-terminating unhandled events.

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

[github-actions]

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

• sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

[github-actions]

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

• sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Unreleased" section. Make sure the entry includes this PR's number.

Example:

## Unreleased

### Features

- [Unhandled Sessions 3] Add internal non-terminating envelope capture ([#5918](https://github.com/getsentry/sentry-java/pull/5918))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description or adding a skip-changelog label.

Generated by 🚫 dangerJS against e1b73c5

[sentry]

📲 Install Builds

Android

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

⚙️ sentry-android Build Distribution Settings

[github-actions]

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

• sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	334.13 ms	400.48 ms	66.35 ms
Size	0 B	0 B	0 B

[buenaflor]

Not actually merged into main. This PR was auto-closed when the collection branch feat/unhandled-sessions was accidentally fast-forwarded to the tip of the stack, which made GitHub consider every stack branch merged into its base.

The collection branch has been restored to its empty commit and the stack rebuilt unchanged. This PR continues as #5921.