[Feature] Surface session format version bumps in release notes

[VasiHemanth]

Area

Documentation, Coding agent and CLI

Problem

The session file format and its version history are documented in session-format.md, but version bumps are not surfaced in the release notes. Because of this, anything reading ~/.prime/agent/sessions/*.jsonl out of band, whether that is a twenty-line jq script or a larger tool, fails silently when the format changes. The parser just starts dropping unrecognized rows, with no warning and no deprecation window.

I ran into this while building a local reader for Prime Agent sessions in TokenTelemetry, but it applies to anyone writing scripts against these logs.

Proposed direction

Mention session format version bumps in the release notes, or post them in Announcements when a relevant release goes out. This needs no code change and does not commit the project to a stability guarantee. It just gives external readers the visibility to adapt.

Alternatives considered

• Pinning and refusing newer versions. The reader stops working the moment a user upgrades, which is worse than a partial read.
• Diffing the docs on a schedule. My current workaround. It is reactive and only catches the change after release.
• Warning on an unknown header version. Useful as a backstop, but it says something changed without saying what.

Additional context

On why I am parsing these files at all, since it explains what the version signal is protecting.

TokenTelemetry is a local dashboard that reads the session logs coding agents already write to disk. It runs on the user's machine and uploads nothing. For Prime Agent it discovers sessions from ~/.prime/agent/sessions/, follows the active branch and its ancestry so the trace mirrors the conversation the user saw, and preserves reported token totals, cost and model metadata. TT_PRIME_SESSIONS_DIR and Prime's own PRIME_AGENT_SESSION_DIR are both honoured when the directory is relocated. It reads about a dozen agents the same way, so a developer running Prime Agent alongside other tools sees them side by side rather than one per vendor dashboard. What it reads per agent is documented at tokentelemetry.com/docs/supported-agents.

The point is helping people see their own agent work, which is otherwise invisible once a run ends:

• Where the tokens actually went. A long run is mostly tool output and re-reads. Seeing the split between reasoning, responses and each tool by name tells you whether a task was expensive because it was hard or because the agent kept re-reading the same files.
• Where a run went sideways. Scrubbing a few thousand steps to find the point where the agent started looping is impractical in a terminal. A step index with per-category counts makes it navigable, and the loop is usually obvious once you can see the shape of the trace.
• What a workflow costs over time. Per-session cost and token counts roll up by project and by day, so you can compare approaches instead of guessing, and see the effect of a prompt or model change on the next run.
• What multi-agent work is doing. Subagent activity is attributed back to the parent session, which is the part that is hardest to reason about from raw JSONL.

None of that needs data to leave the machine, which is the whole reason it reads the on-disk format directly, and the reason a silent format change is a problem worth a line in the release notes.

I originally raised the integration side of this in #971, which was closed with the move to discussion-first. Re-filed here per CONTRIBUTING.md, narrowed to the part that affects the repo.

If it would be useful, I am happy to write a short "reading sessions externally" note for the docs, covering the file location, the header version field and checking it before parsing. No PR attached, just offering.

Separately, and only if you think it genuinely helps your users rather than just me: a pointer from the README to the Prime Agent section of the docs would make it findable for people who want to see where their tokens and time went across a long run. I know that is a promotional ask from someone outside the project, so treat it as a suggestion you are free to ignore. The release-note request above stands on its own either way, and so does the offer to write the docs note.