checkpoint explain --session reports "No checkpoints found" when the scan limit truncates (false negative; misleads the shipped search skill)

Summary

entire checkpoint explain --session <id> applies a default scan limit, but when that limit truncates the scan it reports zero checkpoints in definitive language rather than reporting truncation. The output simultaneously claims the history is empty and admits it may be hidden:

  branch       <branch>
  session      <session-id>
  checkpoints  0

No checkpoints found on this branch.
Checkpoints will appear here after you save changes during an agent session.
note: checkpoint list reached its scan limit; older checkpoints may be hidden. Run 'entire checkpoint explain --json --limit <N>' to see more.

The same command with an explicit limit returns the checkpoints immediately:

entire checkpoint explain --session <id> --json --limit 2000
→ [ { "checkpoint_id": "…", "session_id": "…", "agent": "Claude Code", … }, … ]

So the data is present and reachable. Only the default-limit path misreports it.

Why this matters more than a cosmetic wording issue

The headline (checkpoints 0 + No checkpoints found) and the footnote (older checkpoints may be hidden) contradict each other, and the wrong half is the prominent one. A human may read down to the note. An agent generally does not.

This bites the search skill that Entire itself installs (--search-skill, ENTIRE-MANAGED SEARCH SKILL v1). Observed live: a subagent following the shipped v1 prompt concluded

"the accessible session transcripts in Entire don't contain the diagnostic discussion … the decision-making appears to have been done post-hoc in commit messages rather than during an interactive session transcript that Entire captured."

That was false. The session file held 306 matches for the search term, and --limit 2000 returned the checkpoints at once. The agent reported absence of history as a finding, with no signal to the user that the lookup had been truncated.

Step 5 of the shipped v1 prompt compounds it:

"If nothing looks right, rerun a narrower entire search --json --compact instead of explaining many hits or switching tools."

When the cause of "nothing looks like it exists" is a silent truncation, narrowing is exactly the wrong recovery — it makes the false negative more confident. The prompt has no instruction to raise the limit before concluding absence.

Environment

• Entire CLI 0.10.2 (go1.26.6, darwin/arm64)
• Checkpoint backend: git-refs
• Agents: Claude Code + Codex
• ~900 checkpoints in the repo, created by the history import that entire enable offers (Imported 921 turn(s) from 29 session(s))
• Private GitHub repo; all checkpoint refs confirmed pushed to origin

Possibly relevant: the imported checkpoints carry "is_logs_only": true, and some message fields are terminal scrollback rather than prompts. I did not test whether the same truncation reports zero on natively-captured (non-imported) checkpoints.

Reproduction

1. Enable Entire on a repo with substantial agent history, accepting the history import at enable (enough to exceed the default scan limit — ~900 checkpoints here).
2. Pick a session id known to contain matching content.
3. entire checkpoint explain --session <id> → checkpoints 0, No checkpoints found on this branch.
4. entire checkpoint explain --session <id> --json --limit 2000 → checkpoints returned.

Suggested fixes

Any one of these would remove the false negative; the first two seem most valuable:

1. Do not print No checkpoints found when the scan was truncated. If the limit was hit and zero matched, that is an inconclusive result, not an empty one. Say so in the headline — e.g. checkpoints 0 of ≥N scanned (scan limit reached — pass --limit to widen).
2. Make the --json shape carry it. A "truncated": true / "scan_limit_reached": true field would let agents detect this programmatically instead of relying on prose in a note they don't read.
3. Auto-widen once when a --session-scoped lookup returns zero and the limit was hit, since a session-scoped query has a naturally bounded result set.
4. Update the shipped search skill to require an explicit high-limit lookup before an agent may state that history has no match. (Patched locally, but it is an ENTIRE-MANAGED file, so a --force reinstall or a v2 skill will silently overwrite the fix.)

Related

Adjacent but distinct from #1195 — there, entire search returns 0 while checkpoint explain sees the data. Here it is checkpoint explain itself under-reporting. I also saw search return only type: "commit" hits while matching transcripts existed, which may be the same surface as #1195.

Start at the entire checkpoint explain --session entry point and reproduce the difference between the default scan limit and --limit 2000, in both text and JSON modes. Trace how a limit-hit zero-match result is represented, then check the shipped ENTIRE-MANAGED SEARCH SKILL v1 behavior. Done means truncated results are clearly inconclusive and machine-readable, with coverage for the reported reproduction.