document checkpoint mirror read behavior · Entire

document checkpoint mirror read behavior

f7e892e→main·

pfleidi·1mo ago·2 files·+17 added/-0 removed

Record that v1 remains the source of truth while checkpoints v1.1 reads use the local mirror as-is. This keeps the architecture notes aligned with the strategy-owned mirror paths.

Sessions

c1f42862e3acView transcript

[?
Centralize Checkpoint Metadata Mirror UpdatesCodex·GPT-5.5·2 steps](/content/gh/entireio/cli/session/019e89b2-44f8-7393-aa5f-ca3123a80a76#timeline-c1f42862e3ac/index.html)

Changes

2

426 unmodified lines

427
428
429
430
431
432
433

426 unmodified lines

- **Worktree-specific branches** - each git worktree gets its own shadow branch namespace, preventing conflicts
- **Supports multiple concurrent sessions** - checkpoints from different sessions in the same directory interleave on the same shadow branch
- Condenses session logs to permanent `entire/checkpoints/v1` branch on user commits
- When `checkpoints_version` is `1.1`, mirrors v1 metadata to the local-only `refs/entire/checkpoints/v1.1` read ref after active v1 write/fetch paths; read paths use that ref as-is
- Uses the `post-rewrite` Git hook to keep local session linkage aligned after amend/rebase rewrites
- Builds git trees in-memory using go-git plumbing APIs
- Rewind restores files from shadow branch commit tree (does not use `git reset`)

MCLAUDE.md+1

43 unmodified lines

44
45
46
47
48
49
50
29 unmodified lines

80
81
82
83
84
85
86
67 unmodified lines

154
155
156
157
158
159
160
47 unmodified lines

208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

43 unmodified lines

const (
    Temporary Type = iota // Full state snapshot, shadow branch
    Committed             // Metadata + commit ref, entire/checkpoints/v1
                          // (or the local v1.1 read mirror when configured)
)
```

29 unmodified lines

ListTemporary(ctx context.Context) ([]TemporaryInfo, error)

// Committed checkpoint operations (entire/checkpoints/v1 branch - metadata only)
    // Writes target v1. Reads use the configured committed-read ref.
    WriteCommitted(ctx context.Context, opts WriteCommittedOptions) error
    ReadCommitted(ctx context.Context, checkpointID id.CheckpointID) (*CheckpointSummary, error)
    ReadSessionContent(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*SessionContent, error)
67 unmodified lines

| Session State | `.git/entire-sessions/<id>.json` | Active session tracking |
| Temporary | `entire/<commit[:7]>-<worktreeHash[:6]>` branch | Full state (code + metadata) |
| Committed | `entire/checkpoints/v1` branch (sharded) | Metadata + commit reference |
| Committed read mirror | `refs/entire/checkpoints/v1.1` ref | Local-only mirror used by v1.1 reads |

### Session State

47 unmodified lines

└── 2/                   # Third session...

#### v1.1 local read mirror

`entire/checkpoints/v1` remains the durable source of truth: committed writes
target this branch, and push/fetch operations synchronize this branch with
remotes. When `strategy_options.checkpoints_version` is `"1.1"`, committed reads
resolve against `refs/entire/checkpoints/v1.1` instead.

The v1.1 ref is a local-only mirror. It lives outside `refs/heads/`, is never
pushed, and does not appear in normal branch listings. Strategy write paths and
active v1 fetch/sync paths update it after they advance `entire/checkpoints/v1`.
Read paths do not create, repair, or advance the mirror before use; they read
the configured committed-read ref as-is.

**Root-level metadata.json (`CheckpointSummary`):**
```json
{