Repository navigation
Description
Part of #1810.
Problem
#1810 names sessionIncarnation as "the one genuinely new field" in the Tier 1
record, and the export shipped without it. This issue is that field.
A session id is client-asserted and reusable, so it is not a unit of work. On the
archive the export was designed against, the id default recurs across the whole
2026-10-15 → 2026-11-06 range, in one directory, spanning many unrelated working
periods. Every per-session aggregate downstream therefore averages work that has
nothing to do with each other.
seq cannot separate them either. The counter lives on the store's entry, so a
session re-created under the same id restarts at 1, and a consumer cannot tell that
from a trimmed prefix.
Three consumers are blocked on it now:
- Offline analysis. @pdettori's TraceLab comparison (§4) needs "one sitting" to
compute a duty cycle. Today a consumer infers it from gaps inat, so every
consumer will do it differently and no two results will compare. - The shipped export.
core/sessionexport/record.godocuments the gap on
Record.SessionID, anddocs/session-export.mdlists it under what the export
does not carry. - The trajectory schema. @webchang is extending
rossoctl/trajectory-schemato
accept Cortex sessions. A record whose boundaries are undefined cannot state a
turn start or a duration.
Proposal
Derive an incarnation key and carry it as sessionIncarnation on the event, the
archive and the export, so every consumer splits the same way.
Derivation, starting from #1810's own suggestion:
- Archive segment boundaries are the primary signal. One session on that archive
has 34 segments across three weeks. - A
seqreset marks a re-created session under the same id. - An idle gap past a threshold, and a client or agent change under one id.
Export it as its own field beside sessionId, so a reader groups on it without
reimplementing the rule.
Open questions
- What ends a sitting? An idle gap is the obvious rule, but the threshold is a policy
choice, and a long agent run is legitimately idle at the proxy. feature: export session events for post-processing — content-free per-event projection, NDJSON sink, archive-replayable #1810 notes the
user-wait total is very sensitive to the gap ceiling (24.8 h at 300 s vs 56.8 h at
3600 s), so whatever is chosen has to be documented with the figure. - Derived on demand, like the timeline, or stored with the session? Stored survives a
restart; derived lets the rule change without a migration. - Does a subagent share its parent's incarnation? It should, but
agentRoleis only
declared by Claude Code today. - No
Recordschema bump needed: adding a field does not require one, per the rule on
sessionexport.SchemaVersion.
Relationship to other work
- Distinct from feat: Group a session's model calls into user prompts, in the recording and the timeline #1922, which groups calls within one session into user prompts. This
splits a reused id into separate sessions; feat: Group a session's model calls into user prompts, in the recording and the timeline #1922 then applies inside each one. - feature: agentop observe — group sessions and cost by working directory #1739 was the closest prior issue and went a different direction (grouping by working
directory). It is closed, so this is not a duplicate of it.
Where it lives
core/session/— the store's entry and itsseqcountercore/session/archive— segment boundaries, the primary derivation signalcore/sessionexport/record.go— the field and its doc commentdocs/session-export.md— the "does not carry" section and the reading rulesdocs/session-api.md— the event schema
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNew/ToDo
Activity