Stabilize checkpoint diffs for sparse turns and improve unavailable-diff UX

[Meetpatel006]

What Changed

This PR fixes checkpoint diff behavior for sparse turn histories and improves Diff Panel handling when checkpoints are unavailable.

• Added fallback checkpoint resolution at-or-before requested turn count to avoid hard failures when exact turn checkpoints are missing.
• Added dedupe for repeated placeholder checkpoint events (turn.diff.updated) for the same thread+turn.
• Removed the guard that skipped checkpoint capture when activeTurnId pointed to a different turn, so completed turns are still captured.
• Updated Diff Panel behavior to avoid endless loading in all-turn mode when missing checkpoints are present.
• Added explicit unavailable-checkpoint messaging and improved empty/loading/error states.
• Added/updated tests for fallback resolution, dedupe behavior, and Diff Panel availability logic.

Why

Users could hit unreliable or confusing diff behavior:

• Sparse checkpoint timelines could fail when exact turn checkpoints were not available.
• Repeated provider diff updates could create unstable placeholder checkpoint state.
• All-turn Diff Panel could appear stuck loading when one or more checkpoints were missing.
• Error/empty states in the Diff Panel were not clear enough.

This approach keeps behavior predictable under partial/missing checkpoint data, avoids duplicate placeholder writes, and provides clearer UI feedback without expanding scope beyond bug fixes.

UI Changes

Before

1. All-turn Diff Panel kept loading (stuck loading state).

2. Error state shown before the fix.

After

1. All-turn Diff Panel with better UX and no stuck loading.

2. Explicit state when a checkpoint is missing.

3. Normal Diff Panel state.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a images for interaction changes

Note

Stabilize checkpoint diffs for sparse turns and improve unavailable-diff UX

• getTurnDiff in CheckpointDiffQuery.ts now resolves to the nearest checkpoint at or before the requested turn count instead of throwing when an exact match is missing.
• The checkpoint reactor in CheckpointReactor.ts now captures completed turns even when the session's activeTurnId references a different turn.
• ProviderRuntimeIngestion.ts deduplicates placeholder checkpoints so repeated turn.diff.updated events for the same turn only enqueue one placeholder.
• DiffPanel.tsx skips the diff query when a selected turn's checkpoint is missing or lacks a ref, showing a descriptive message instead of a loading/error state.
• isCheckpointTemporarilyUnavailable now treats 'checkpoint ref is unavailable for turn' as a retriable condition.

^{Macroscope summarized b0fa258.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 41b960e3-0bbc-4da6-a6a2-ad482ae480c7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can make CodeRabbit's review stricter and more nitpicky using the `assertive` profile, if that's what you prefer.

Change the reviews.profile setting to assertive to make CodeRabbit's nitpick more issues in your PRs.

[juliusmarminge]

the root cause of this issue is that we're not handling subagents very well yet (they emit unique turn ids so a single user-assistant pass emits multiple turns but we are not capturing these), and codex is constantly 'improving' them. checkpointing worked flawlessly before we shipped, never had issues.

This seems like another bandaid to me(?), I was working on a real and proper fix earlier this week but got distracted.

Really like the UI improvements though!

[Meetpatel006]

the root cause of this issue is that we're not handling subagents very well yet (they emit unique turn ids so a single user-assistant pass emits multiple turns but we are not capturing these), and codex is constantly 'improving' them. checkpointing worked flawlessly before we shipped, never had issues.

This seems like another bandaid to me(?), I was working on a real and proper fix earlier this week but got distracted.

Really like the UI improvements though!

Thanks for the context on the subagent root cause that's genuinely helpful to have documented.

I dug into the codex-rs app-server some of the source to understand the event model better before putting this together. A few things that stood out: turn/diff/updated is emitted as a full snapshot keyed on threadId + turnId, not incremental fragments so the dedupe logic here is actually consistent with how codex expects clients to handle it (replace-in-place on same thread+turn). The turn/completed boundary is what codex treats as the finalization signal, and durable turn/history events are what replay rebuilds stable state from transient deltas are intentionally ephemeral on codex's side.

The subagent fan-out case is documented in the app-server model too spawn/collab flows carry sender/receiver thread relationships, meaning one user-visible exchange can fan out into multiple turns across multiple threads. So you're correct that the root fix needs to be thread-aware first, then turn-aware, not flattened. This PR doesn't go there.

That said, I'd push back slightly on "bandaid" for the PR. The surface-area is really two separate things:

1. Structural mitigations (fallback resolution, dedupe, activeTurnId guard removal) agreed these don't fix root cause. If your proper subagent-aware checkpoint model lands, some of these get replaced and that's fine.

2. UI/UX fixes (explicit unavailable states, no stuck loading, clear messaging) these are independently correct regardless of what the checkpoint model looks like underneath. Per how codex handles it, missing refs should produce an explicit unavailable state, not endless loading. That part isn't a bandaid, it's just correct defensive UI.

Happy to split the PR if that unblocks review UI changes fast-tracked, structural mitigations held until your fix lands. Or if you want to share what you had in mind for the subagent fix, I can rebase onto that approach instead.