document v1.1 mirror as best-effort and the resume-promote exception

0cfc8ed→main·

pfleidi·1mo ago·2 files·+8 added/-3 removed

Earlier wording said the mirror is advanced "after active v1 write/fetch paths" without specifying who advances it, that failures are non-fatal, or that the resume bootstrap is excluded. Update CLAUDE.md and sessions-and-checkpoints.md to describe the actual contract:

• mirror is best-effort, gated on the checkpoints_version setting
• entire-managed v1 writes and fetches advance it; failures log but never fail the primary operation
• promoteRemoteTrackingMetadataBranch deliberately does not mirror and is skipped entirely when v1.1 is opted in
• read paths use the configured ref as-is

Sessions

eb7c055bbe39View transcript

Changes

2

• MCLAUDE.md+1/-1

• docs/architecture

• Msessions-and-checkpoints.md+7/-2

426 unmodified lines

427
428
429
430
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
- When `checkpoints_version` is `1.1`, best-effort mirrors v1 metadata to the local-only `refs/entire/checkpoints/v1.1` read ref after entire-managed v1 writes and fetches; mirror failures are logged, not fatal. The resume bootstrap that promotes local v1 from origin's remote-tracking ref is the deliberate exception — it does not mirror and is skipped entirely in v1.1 mode. Read paths use the configured 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/-1

215 unmodified lines

216
217
218
219
220
219
220
221
222
223
224
225
226
227
228

215 unmodified lines

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`. pushed, and does not appear in normal branch listings. Entire-managed v1 write
and fetch paths advance the mirror best-effort after they advance
`entire/checkpoints/v1`; mirror failures are logged but never fail the primary
operation. The resume bootstrap that promotes local v1 from origin's
remote-tracking ref is the deliberate exception — it does not mirror and is
skipped entirely in v1.1 mode.

Read paths do not create, repair, or advance the mirror before use; they read
the configured committed-read ref as-is.

Mdocs/architecture/sessions-and-checkpoints.md+7/-2