Skip to content

reflect can't surface entire checkpoints from sibling worktrees on the same machine #12

Description

@codeyogi911

Symptom

reflect search, reflect timeline, and reflect sessions cannot find Entire-tracked sessions whose checkpoints originate from a different worktree of the same repo on the same machine, even when the checkpoint commits exist on the local entire/checkpoints/v1 shadow branch.

This causes "why did the original session do X?" investigations to dead-end, even though the evidence is provably present in the local clone.

Reproduction

Setup:

  • Two clones of the same Git repo on the same Mac:
    • `/Users/me/Repos/myproject` — clone A
    • `/Users/me/Code/myproject` — clone B
  • Entire is configured in both, manual-commit mode, sharing the remote.
  • A Claude Code session runs in clone B, lands 6 commits with valid `Entire-Checkpoint:` trailers (e.g. `Entire-Checkpoint: ccabb3899d9e`), and pushes both the topic branch and the `entire/checkpoints/v1` shadow branch.
  • I open clone A, fetch, check out the same topic branch, and try to investigate.

What I see in clone A:

```
$ entire explain --commit de4799f01
checkpoint not found: ccabb3899d9e

$ reflect search "loanset"
[surfaces commit hashes via git log fallback, but no session/checkpoint hits]

$ reflect timeline --days 3
[lists only sessions that ran in clone A; the clone-B sessions are absent]

$ reflect sessions
[same — clone B's sessions don't appear]
```

But the checkpoint does exist locally:

```
$ git log --all --oneline --grep='Checkpoint: ccabb3899d9e'
c3950e66d Finalize transcript for Checkpoint: ccabb3899d9e
7bca6edfe Checkpoint: ccabb3899d9e
f5e1ef09b Checkpoint: ccabb3899d9e
6623e9671 Checkpoint: ccabb3899d9e

$ git show c3950e66d:cc/abb3899d9e/1/full.jsonl | head -c 200
{"type":"permission-mode","permissionMode":"bypassPermissions","sessionId":"8e5312dd-..."} ...
```

So the full transcript is one `git show` away — but `entire explain --checkpoint ccabb3899d9e` returns "checkpoint not found".

Suspected root cause

Both `entire` and `reflect` appear to look up checkpoints via per-worktree state (likely `.entire/metadata/` or a worktree-scoped index), not via a content-addressable lookup against `entire/checkpoints/v1` blobs. So a checkpoint authored in worktree B is invisible to worktree A even after `git fetch`, despite the underlying tree being globally accessible.

Why this matters

The whole point of pushing checkpoints to a shadow branch is so other clones / collaborators / future-self can replay agent reasoning. If the lookup is worktree-scoped, that point is defeated for the cross-worktree case.

This bit me concretely on a real investigation: a teammate (also me, on a different clone) shipped an agent-built feature that turned out to be partially broken. To understand what the original session did and didn't do, I needed the transcript. `reflect` and `entire` both said "don't have it". I had to drop to raw git: `git log --grep='Checkpoint: '` → `git show :/full.jsonl` → manual jq/python parsing. That worked, but it's a 10-step manual recovery for evidence the system already has.

Proposed scope

Two layers of fix, increasing in cost:

  1. Cheap: Make `entire explain --checkpoint ` and `reflect sessions ` fall back to scanning `entire/checkpoints/v1` (or any `entire/checkpoints/*` ref) by `git log --all --grep='Checkpoint: '` when the worktree-local lookup misses. Print a one-line note like "recovered from shadow branch" so the user knows.

  2. Right: Treat the shadow branch as the source of truth and the worktree state as a cache. Re-derive sessions, timeline, and search hits from any reachable checkpoint blob. Then a fresh clone with a single `git fetch` immediately sees the full agent history without any `entire` re-init.

Happy to send a PR for #1 if you'd accept it — let me know which path you prefer.

Versions

  • entire: 2.1.119 (per checkpoint metadata)
  • reflect: 0.6.0
  • macOS Darwin 25.3.0
  • Repo uses manual-commit mode

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions