Clarify checkpoint step count docs · Entire

Clarify checkpoint step count docs

cddaed8→main·

dipree·1mo ago·2 files·+21 added/-1 removed

Sessions

29533fb28a76View transcript

Changes

2

424 unmodified lines

425
426
427
428
428
429
430
431
432
433

424 unmodified lines

// CreatedAt is when the checkpoint was created
    CreatedAt time.Time

// CheckpointsCount is the total number of checkpoints across all sessions
    // CheckpointsCount is the aggregate displayed "steps" count across sessions:
    // the sum of per-session prompt-window counts. Despite the historical name,
    // it is not a count of checkpoint records.
    CheckpointsCount int

// FilesTouched are files modified during all sessions

Mcmd/entire/cli/checkpoint/checkpoint.go+3/-1

230 unmodified lines

231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254

230 unmodified lines

}

checkpoints_count in the root summary is the aggregate displayed "steps" count: the sum of per-session prompt-window counts. Despite the historical name, it is not a count of checkpoint records.

Session-level metadata.json (CommittedMetadata, abbreviated):

{
  "checkpoint_id": "abc123def456",
  "session_id": "2025-12-01-8f76b0e8-b8f1-4a87-9186-848bdd83d62e",
  "strategy": "manual-commit",
  "created_at": "2025-12-01T12:34:56Z",
  "branch": "main",
  "checkpoints_count": 3,
  "save_step_count": 3,
  "files_touched": ["file1.txt", "file2.txt"]
}

In session metadata, checkpoints_count is the displayed prompt-window count for that session. save_step_count records SaveStep-created shadow-branch commits and is the conservative "real checkpoint work happened" signal; it is omitted when zero (for example, commit-only/fallback sessions). save_step_count is not aggregated into the root CheckpointSummary.

When condensing multiple concurrent sessions: