Files

gastown/crew/joe 1c82d51408 Add decision 009: Session events architecture

Documents that session events stay in events.jsonl (orchestration),
with work attribution via session_id on beads mutations.

Filed:
- gt-nvz8b: gt done captures session_id
- bd-tksk: Beads session_id support (slung to dave)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-31 12:50:56 -08:00

2.6 KiB

Raw Blame History

Decision 009: Session Events Architecture

Status: Accepted Date: 2025-12-31 Context: Where should session events live? Beads, separate repo, or events.jsonl?

Decision

Session events are orchestration infrastructure, not work items. They stay in events.jsonl (outside beads). Work attribution happens by capturing session_id on beads mutations (issue close, MR merge).

Context

The seance feature needs to discover and resume Claude Code sessions. This requires:

Pointer to session (session_id) - for claude --resume
Attribution (which work happened in this session) - for entity CV

Claude Code already stores full session transcripts indefinitely. Gas Town doesn't need to duplicate them - just point at them.

The Separation

Layer	Storage	Content	Retention
Orchestration	`~/.events.jsonl`	session_start, nudges, mail routing	Ephemeral (auto-prune)
Work	Beads (rig-level)	Issues, MRs, convoys	Permanent (ledger)
Entity activity	Beads (entity chain)	Session digests	Permanent (CV)
Transcript	Claude Code	Full session content	Claude Code's retention

Why Not Beads for Events?

Volume: Orchestration events are high volume, would overwhelm work signal
Ephemerality: Most orchestration events don't need CV/ledger permanence
Different audiences: Work items are cross-agent; orchestration is internal
Claude Code has it: Transcripts already live there; we just need pointers

Implementation

Phase 1: Attribution (Now)

gt done captures CLAUDE_SESSION_ID in issue close
Beads supports closed_by_session field on issue mutations
Events.jsonl continues to capture session_start for seance

Phase 2: Session Digests (Future)

Sessions as wisps: session_start creates ephemeral wisp
Session work adds steps (issues closed, commits made)
session_end squashes to digest
Digest lives on entity chain (agent CV)

Phase 3: Pruning (Future)

Events.jsonl auto-prunes after N days
Session digests provide permanent summary
Full transcripts remain in Claude Code

Consequences

Positive:

Clean separation of concerns
Work ledger stays focused on work
CV attribution via session_id on beads mutations
Seance works via events.jsonl discovery

Negative:

Two systems to understand (events vs beads)
Need to ensure session_id flows through commands

gt seance - Session discovery and resume
gt-3zsml - SessionStart hook passes session_id to gt prime
PRIMING.md - "The Feed Is the Signal" section
CONTEXT.md - Entity chains and CV model

2.6 KiB Raw Blame History