Skip to content

heed v0.2.0 — Session Succession

Choose a tag to compare

@github-actions github-actions released this 19 Aug 21:49
· 22 commits to main since this release

Session succession

A thread is keyed by native session UUID, but a conversation isn't. Claude Code rotates the session id part-way through when a session forks into its background daemon (--session-id <new> --fork-session --resume <old>.jsonl) or restarts in place. The hook stream moves to the new id while the old one falls silent but stays live — so a consumer watching the old id sees the thread go idle forever while the work carries on somewhere it can't see.

Heed now follows the conversation across that rotation.

Linking. At the successor's first hook event, the daemon looks for a predecessor using two deterministic signals: a matching (pid, pid_start), meaning the session rotated inside the same process; or the --resume value in the successor's argv, which names the predecessor's transcript outright. Process ancestry is deliberately not a signal — a background session spawned from a tracked session shares its ancestry without continuing it, and ancestry alone can't separate a sibling from a successor. Resolution happens at first sighting because it reads the live process; once the predecessor exits, the evidence is gone.

Ownership. Linking alone doesn't move the owner overlay, because a session may fork a sibling and keep working. Ownership follows the live end of the lineage: it moves when the predecessor's process is gone, when the successor is the same process, or when the predecessor has been hook-silent for 120s while the successor kept emitting. A predecessor that is no longer tracked but still holds an overlay is claimable too, so a handoff that happened while the daemon was down doesn't strand the thread.

The overlay is moved, never copied, in a single atomic owners.json write. A product's thread id must name exactly one native session, or a consumer diffing state.json flaps between the superseded record's frozen activity and the live one's.

Contract changes

Two optional fields on the per-thread record, omitted unless the thread is part of a lineage:

  • supersedes — native session id this thread continues
  • superseded_by — native session id that continued this thread

These are additive and schema_version is unchanged at 1, so existing consumers are unaffected and no lockstep upgrade is needed. Consumers need no new logic for the common case: the overlay arrives on the live session and the superseded record drops out of an owner_product filter on its own. Follow superseded_by if you want to render the chain; the successor's thread_id is what a later --resume should target.

See SPEC §4.7 for the full specification.

Also

  • cargo fmt --check passes again; CI on main is green for the first time since June.