# checkpoint: record branch checkpoint version

`fdb35e5`→[main](/content/gh/entireio/cli/commits/main/index.html)

Persist the current branch-backed checkpoint format in root checkpoint metadata.

Default legacy root metadata to branch-v1 on read so older checkpoints have the same in-memory shape.

## Sessions

c9c392abba6bView transcript

## Changes

6

- cmd/entire/cli/checkpoint

- Mcheckpoint.go+14
  - Mcommitted.go+7/-2
  - Mcommitted_reader_resolve.go+1/-1
  - Mcommitted_update_test.go+115
  - Mcommitted_write_test.go+36

- docs/architecture

- Msessions-and-checkpoints.md+2

```
27 unmodified lines
```

```go
// Error thrown when no transcript is found for a checkpoint.
ErrNoTranscript = errors.New("no transcript found for checkpoint")

// CheckpointVersionBranchV1 identifies the branch-backed checkpoint metadata format.
const CheckpointVersionBranchV1 = "branch-v1"

// Checkpoint represents a save point within a session.
type Checkpoint struct {
    // ID is the unique checkpoint identifier
}

//nolint:revive // Named CheckpointSummary to avoid conflict with existing Summary struct
type CheckpointSummary struct {
    CLIVersion        string           `json:"cli_version,omitempty"`
    CheckpointVersion string            `json:"checkpoint_version,omitempty"`
    CheckpointID      id.CheckpointID  `json:"checkpoint_id"`
    Strategy          string            `json:"strategy"`
    Branch            string            `json:"branch,omitempty"`
    HasInvestigation bool `json:"has_investigation,omitempty"`
}

func normalizeCheckpointSummary(summary *CheckpointSummary) *CheckpointSummary {
    if summary == nil {
        return nil
    }
    if summary.CheckpointVersion == "" {
        summary.CheckpointVersion = CheckpointVersionBranchV1
    }
    return summary
}

// SessionMetrics contains hook-provided session metrics from agents that report
// them via lifecycle hooks (e.g., Cursor). These supplement transcript-derived
// metrics for agents whose transcripts lack usage/timing data.
```

```go
// readSummaryFromBlob reads CheckpointSummary from a blob hash.
func (s *GitStore) readSummaryFromBlob(hash plumbing.Hash) (*CheckpointSummary, error) {
    return readJSONFromBlob[CheckpointSummary](s.repo, hash)
}
```

```go
// ReadSessionMetadata reads only the metadata.json for a specific session within a checkpoint.
```

```go
// TestWriteCommittedWritesBranchCheckpointVersion verifies that writing a committed checkpoint version works as expected.
func TestWriteCommittedWritesBranchCheckpointVersion(t *testing.T) {
    // Test implementation here...
}
```

**Root-level metadata.json (`CheckpointSummary`):**
```json
{
"cli_version": "0.0.0-dev",
"checkpoint_version": "branch-v1",
"checkpoint_id": "abc123def456",
"strategy": "manual-commit",
"branch": "main"
}
```