Skip to content

feature: Derive sessionIncarnation — split a reused session id into sittings #1997

Open

Description

@mrsabath

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 in at, so every
    consumer will do it differently and no two results will compare.
  • The shipped export. core/sessionexport/record.go documents the gap on
    Record.SessionID, and docs/session-export.md lists it under what the export
    does not carry.
  • The trajectory schema. @webchang is extending rossoctl/trajectory-schema to
    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 seq reset 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 agentRole is only
    declared by Claude Code today.
  • No Record schema bump needed: adding a field does not require one, per the rule on
    sessionexport.SchemaVersion.

Relationship to other work

Where it lives

  • core/session/ — the store's entry and its seq counter
  • core/session/archive — segment boundaries, the primary derivation signal
  • core/sessionexport/record.go — the field and its doc comment
  • docs/session-export.md — the "does not carry" section and the reading rules
  • docs/session-api.md — the event schema

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestlaptopThe local (laptop) tool: install, abctl, the numbers

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions