feat(core): [Unhandled Sessions 1] Add Unhandled session state and non-terminating error flag - #5919
Draft
buenaflor wants to merge 6 commits into
Draft
feat(core): [Unhandled Sessions 1] Add Unhandled session state and non-terminating error flag#5919buenaflor wants to merge 6 commits into
buenaflor wants to merge 6 commits into
Conversation
Adds Session.State.Unhandled from the session protocol, plus a pending-unhandled marker that survives serialization. A session carrying the marker finalizes as Unhandled instead of Exited on end(), while Crashed and Abnormal keep taking precedence. Co-authored-by: Cursor <cursoragent@cursor.com>
"Unhandled" alone is ambiguous: a native crash is also an unhandled error, it just terminates the process and so ends the session as crashed rather than unhandled. Name the flag after the property that actually distinguishes the two and match the vocabulary of captureEnvelopeNonTerminating. Also clarify that the setter only restores the flag when rebuilding a session and must not be used to mutate a live one. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
|
This was referenced Aug 10, 2026
Contributor
Performance metrics 🚀
|
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 6b019b7 | 343.31 ms | 417.23 ms | 73.91 ms |
| d15471f | 286.65 ms | 314.68 ms | 28.03 ms |
| d217708 | 409.83 ms | 474.72 ms | 64.89 ms |
| d500866 | 326.13 ms | 378.70 ms | 52.58 ms |
| fcec2f2 | 314.96 ms | 373.66 ms | 58.70 ms |
| d501a7e | 314.55 ms | 343.34 ms | 28.79 ms |
| 7414e9b | 322.49 ms | 378.88 ms | 56.39 ms |
| fcec2f2 | 357.47 ms | 447.32 ms | 89.85 ms |
| a416a65 | 316.52 ms | 359.67 ms | 43.15 ms |
| 983e0f0 | 350.64 ms | 386.44 ms | 35.79 ms |
App size
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 6b019b7 | 0 B | 0 B | 0 B |
| d15471f | 1.58 MiB | 2.13 MiB | 559.54 KiB |
| d217708 | 1.58 MiB | 2.10 MiB | 532.97 KiB |
| d500866 | 0 B | 0 B | 0 B |
| fcec2f2 | 1.58 MiB | 2.12 MiB | 551.50 KiB |
| d501a7e | 0 B | 0 B | 0 B |
| 7414e9b | 0 B | 0 B | 0 B |
| fcec2f2 | 1.58 MiB | 2.12 MiB | 551.50 KiB |
| a416a65 | 1.58 MiB | 2.12 MiB | 555.26 KiB |
| 983e0f0 | 0 B | 0 B | 0 B |
Previous results on branch: feat/unhandled-sessions-protocol
Startup times
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 02a6680 | 341.96 ms | 461.54 ms | 119.58 ms |
| 97f3c00 | 309.04 ms | 359.62 ms | 50.58 ms |
| 4a7952f | 324.85 ms | 360.54 ms | 35.69 ms |
App size
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 02a6680 | 0 B | 0 B | 0 B |
| 97f3c00 | 0 B | 0 B | 0 B |
| 4a7952f | 0 B | 0 B | 0 B |
clone() and Session.Deserializer are both inside Session, so they can restore the field directly. Dropping the setter keeps it off the public API surface and makes it impossible to flip the flag on a live session without counting the error and advancing the sequence. Co-authored-by: Cursor <cursoragent@cursor.com>
📲 Install BuildsAndroid
|
Every other field is set at construction; the flag was the odd one out, assigned afterwards. A private canonical constructor keeps construction complete without putting the flag on the public API, which a 15-arg public overload would do. Co-authored-by: Cursor <cursoragent@cursor.com>
As a bare noun phrase the field read like it held the error rather than a boolean, most visibly where it is passed as a constructor argument. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Stack (Unhandled Sessions)
📜 Description
Adds the
unhandledsession status to the session model.Session.State.Unhandled— the protocol status for an unhandled error that did not terminate the process.nonTerminatingUnhandledErrorflag onSession(non_terminating_unhandled_errorwhen serialized) that records "this session saw an unhandled error the process survived" without ending the session or changing its status while it is still alive.end()finalizes a session carrying the flag asUnhandledinstead ofExited.CrashedandAbnormalkeep taking precedence, andupdate(Crashed, ...)clears the flag so a real crash always wins.clone()and the (de)serializer carry the flag; it is omitted from JSON when unset.Nothing sets the flag yet — this PR is inert on its own. It is the model layer for the rest of the stack.
A note on the name: "unhandled" alone is ambiguous, since a native crash is also an unhandled error — it just terminates the process and so ends the session as
crashedrather thanunhandled. The flag is therefore named after the property that actually distinguishes the two, matching the vocabulary ofcaptureEnvelopeNonTerminatinglater in the stack.💡 Motivation and Context
Hybrid runtimes such as Flutter report
handled=falseexceptions that do not kill the process. Today those go through the terminating capture path, which marks the sessioncrashedand starts a replacement session even though the app keeps running, incorrectly lowering crash-free session rates.The session protocol has had a dedicated status for exactly this case since 1.6.0:
unhandled— "an unhandled error occurred but the process did not terminate". Relay accepts it (SessionStatus::Unhandled→"unhandled").💚 How did you test it?
New
SessionTestcovering the flag's atomic update, terminal-state precedence (Crashed/Abnormalwin),clone(), and serialization round-trips.PreviousSessionFinalizerTestcovers recovery of a previous session carrying the flag, including a native crash escalating it tocrashed.SessionSerializationTestcovers the JSON round-trip.📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps
Persisting the flag across process death and exposing the capture API, in the following PRs in this stack.
#skip-changelog