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

`9658c4c`→[main](/content/gh/entireio/cli/commits/main/index.html)·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](/content/gh/entireio/cli/session/bedfc466-2682-40f4-b92b-9f07eaafcc9f#timeline-1513a1ef2b6b/index.html)

## 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:
  
// ...