fix(checkpoint): keep the checkpoints a branch was made before

[voipmonitor]

Problem. Reported in the GLM TP2 Discord thread by hashspamjam, mrweiner and ktsaou: a conversation that continues after a retry, an aborted turn resumed with other tokens, or an auto-continue sometimes fails to restore. The log shows "K of M pages were readable" with exactly the recurrent-state pages missing, and the whole prompt is recomputed. mrweiner's analysis and reproducer are at https://github.com/mrweiner/lmcache-supersession-repro.

When a new request's prompt checkpoint superseded an earlier request's checkpoint, supersede() also marked every sibling of that request as superseded, including its longer response checkpoint. A branch that started before that response left the response's unique pages marked superseded while its manifest stayed listed. Those pages were then:

• dropped first under L1 pressure, without a write; and
• skipped by the shutdown flush.

The turn that continued the original line then failed its restore.

Fix.

• A sibling checkpoint is superseded only when the new prompt is longer than it, i.e. the conversation moved past it. Ancestors of the new prompt are unchanged, so on-evict keeps the flash-write savings of feat(checkpoint): keep the newest checkpoint per conversation; write checkpoints to L2 on eviction #85 for ordinary chat turns.
• The shutdown flush writes superseded pages after the current ones, within the same budget. Their manifests stay listed, and a shutdown writes each page at most once, so a branch restores after a restart.

This is a focused alternative to #101. See our comment there about the rest of that change.

Tests.

• CPU: tests/v1/multiprocess/test_checkpoint_storage.py and tests/v1/distributed/test_checkpoint_retention.py: 65 passed (base: 64). The new test_a_branch_keeps_the_checkpoints_it_branched_before and the updated shutdown-flush test both fail on base.
• E2E: GLM-5.3-Flash Spark TP2 (glm53-spark-tp2, beta c10dcc1b, LMCache L1 24 GB / L2 128 GB, on-evict, prune stale). mrweiner's reproducer ran with --mode all --restart-between-cells:

Cell	Base	This PR
P0 control	restored	restored
P1 supersede	restored	restored
P2 pressure	restored	restored
P3 supersede + L1 pressure	restored (not reproduced on this setup)	restored
R0 clean restart	restored	restored
R1 supersede + clean restart	failed: 40239: 13 of 22 pages on both ranks, walk-down to 40000/36864, full recompute	restored (40239 external)

The shutdown flush with this PR wrote, for example, "84 current and 34 superseded checkpoint pages" in 0.2 s.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• dev/*

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: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: d2e2d309-0e0e-4178-bbd4-dccb70ae4c6f

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

---

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