[codex] add token guidance and checkpoint comparison

[peyton-alt]

Stacked on #1393.

Summary

• add --agent-brief to entire session tokens for compact agent-native next-step guidance
• add --compare to entire checkpoint tokens so users can measure observed token deltas between checkpoints
• make JSON output and agent brief mutually exclusive
• add tests for agent brief priority, comparison reduction/increase/no-change, missing token data, multi-session aggregate comparison, zero-baseline metrics, subcommand routing, and flag validation

Validation

• real session smoke test: GOCACHE=/private/tmp/entire-go-cache go run ./cmd/entire/main.go session tokens --agent-brief
• real checkpoint smoke test: GOCACHE=/private/tmp/entire-go-cache go run ./cmd/entire/main.go checkpoint tokens f1dfd807cfdc --compare ab4dd5b77ca7
• real checkpoint JSON smoke test: GOCACHE=/private/tmp/entire-go-cache go run ./cmd/entire/main.go checkpoint tokens f1dfd807cfdc --compare ab4dd5b77ca7 --json
• GOCACHE=/private/tmp/entire-go-cache go test ./cmd/entire/cli -run TestCheckpointTokensCmd_.*Comparison -count=1
• GOCACHE=/private/tmp/entire-go-cache go test ./cmd/entire/cli -run TestCheckpointTokensCmd|TestTokensCmd|TestSessionsCmd_TokensSubcommand|TestSessionsCmd_HelpIncludesTokensSubcommand -count=1
• mise run lint
• GOCACHE=/private/tmp/entire-go-cache go test ./cmd/entire/cli -count=1
• mise run check
• git diff --check

Real checkpoint comparison observed

• f1dfd807cfdc compared against ab4dd5b77ca7 showed observed_increase, not reduction: total tokens up 28.1%, cache/context replay up 26.9%, API calls up 30.5%.
• The output explicitly qualifies that token deltas do not prove quality was preserved or degraded; users still need to verify task outcome/tests.

Follow-up lane

Historical profiling/memory recommendations, e.g. entire tokens profile, is intentionally left out of this PR. That should aggregate repeated high cache replay, high API calls, broad search/read loops, subagent-heavy sessions, and cases where usage rose after recommendations.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f0a30be. Configure here.}

[Copilot]

Pull request overview

Adds an --agent-brief output mode to entire session tokens to provide compact, agent-oriented next-step guidance, while preventing conflicting output modes.

Changes:

• Added --agent-brief flag to session tokens with brief output formatting (usage line, next best action, signals).
• Enforced --json and --agent-brief mutual exclusivity.
• Added test coverage for agent-brief prioritization, cache-replay-only scenarios, missing token data, subcommand routing, and flag validation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
cmd/entire/cli/session_tokens.go	Adds --agent-brief flag handling and implements brief-format output helpers.
cmd/entire/cli/sessions_test.go	Adds tests validating agent-brief output content, routing, and mutual exclusivity with JSON.