doctor: check and repair the v1.1 committed-read mirror

9658c4c→main·computermode·1mo ago·7 files·+577 added/-3 removed

Read paths use the v1.1 mirror as-is (no read-time self-repair), so a missing, stale, or diverged refs/entire/checkpoints/v1.1 silently makes v1.1 reads miss checkpoints with no repair path. Make doctor the repair tool:

• strategy.DiagnoseCommittedMetadataMirror classifies the mirror against the local v1 tip (read-only): not configured, ok, missing, behind, diverged, or v1-branch-missing.
• entire doctor reports the state and repairs missing/stale/diverged with confirmation (auto under --force) via the existing MirrorCommittedMetadataRef. The mirror-outlives-v1 anomaly is warn-only with a fetch suggestion; restoring v1 is out of scope.
• entire doctor bundle captures entire-related refs plus the mirror diagnosis in entire-refs.txt for bug reports.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

Sessions

1513a1ef2b6bView transcript

?\ Identify Commands Needing Checkpoints v1.1 SupportClaude Code·Opus 4.8[1m]·1 step

Changes

7

• cmd/entire/cli

• Mdoctor.go+106/-2

• Mdoctor_bundle.go+47

• Mdoctor_bundle_test.go+38

• Mdoctor_test.go+190

• strategy

• Mv1_custom_ref_mirror.go+103

• Mv1_custom_ref_mirror_test.go+87

• docs/architecture

• Msessions-and-checkpoints.md+6/-1

33 unmodified lines

...

Checkpoint read mirror (checkpoints v1.1 only): detects when local-only refs/entire/checkpoints/v1.1 read mirror is missing, stale, or diverged relative to entire/checkpoints/v1, which makes reads miss checkpoints. Fixes by pointing the mirror at the v1 tip.

When Codex hooks are installed:

1. Codex hook trust: warn when hooks declared in .codex/hooks.json.
2. Codex hook trust: warn when hooks declared in .codex/hooks.json lack a trusted_hash entry in the user's Codex config (i.e., /hooks review hasn't run yet on this machine, or a newer entire release added a hook the user hasn't approved yet).

3. Stuck sessions: sessions stuck in ACTIVE or ENDED phase that need cleanup.  
   A session is considered stuck if:  
   - It is in ACTIVE phase with no interaction for over 1 hour

...

func checkCommittedMetadataMirror(cmd *cobra.Command, force bool) error {
    // Check 1: metadata check...
    // Check 2: v1.1 committed-read mirror drift...
}

// shortMirrorHash abbreviates a hash for mirror-check output; "none" when zero.
func shortMirrorHash(h plumbing.Hash) string {
    if h.IsZero() {
        return "none"
    }
    return h.String()[:7]
}

// checkCodexHookTrust warns about two kinds of drift in the Codex hook setup:
  
// ...