Define the pending dataset as both halves it actually contains

main

Commit

Stefan Haubold2mo ago

Answers five Copilot review comments on #2187. Four are one theme and Copilot is right about it: my definition said a pending checkpoint "has not yet been condensed onto entire/checkpoints/v1", which is true of only half the dataset. The strategy.go type doc contradicted itself inside a single sentence -- "not yet condensed... : either live shadow-branch state or a logs-only point" -- because a logs-only point is precisely one that HAS been condensed.

What ListLogsOnlyPendingCheckpoints actually builds: it scans the current branch's history for commits carrying an Entire-Checkpoint trailer, and keeps the ones whose trailer resolves against committed checkpoint storage. The row's ID is that branch commit, CheckpointID is the condensed checkpoint on v1, IsLogsOnly is true. It is listed so the session transcript can be restored from v1 via RestoreLogsOnly -- file state would need a git checkout. So it is derived from condensed history, not from un-condensed work, and ListPendingCheckpoints merges it with the live shadow-branch rows and sorts the two together by date.

One definition, adapted per context: checkpoint list --pending is the resume view of the current branch, and a row is either a live checkpoint on the session's shadow branch (not yet condensed) or a logs-only resume point recovered from a commit whose logs already are. "Pending" names the listing, not a property every row has.

Applied to the type doc (which now spells out which fields each shape sets), the command's Long text, the --pending flag help (still one line), CLAUDE.md, and sessions-and-checkpoints.md.

Five comments beyond the four flagged had the same defect, so they went too rather than leaving the file disagreeing with its own type doc: checkpoint_list.go described pendingCheckpointsLimit and both render functions as handling "live shadow-branch pending checkpoints" when all three see both shapes, and checkpoint_group.go's file-header summary of the two --pending modes said the same.

The fifth comment is a grammar nit: FindCheckpointUUID said it finds "the checkpoint point for where a task's transcript slice starts". It now says the UUID marks where the task checkpoint's transcript slice starts.

Wording only -- no behavior, no flag, no JSON change. No test asserted any of the strings touched (checked before editing: the only help-text substrings in *_test.go are none, and the two string assertions in checkpoint_list_test.go pin the empty-list message, which this commit does not touch). entire checkpoint list --help renders correctly.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com Entire-Checkpoint: 01M1BGJR1WNKTD6DSK67QMT11X