Module session_archive 

Local, multi-session transcript archive.

Sessions live under an explicit archive root that callers must provide — this module never reads configuration or mutates the environment:

<root>/<session id>/meta.json     entry + provider metadata (private, atomic)
<root>/<session id>/events.jsonl  append-only journal of human/agent events

Session ids are generated locally (no global state) and validated before every use, so an id can never traverse out of the archive root. Journal reads tolerate an incomplete final line and report — but never silently discard — malformed records, and per-session metadata corruption is reported per session instead of hiding other sessions. Streaming writes go through BufferedSessionArchive, which performs all filesystem work on a background thread and only requires durability at explicit boundaries.

Structs

ArchiveEntry

Immutable identity and presentation data for one archived session.

ArchivedSession

A loaded archived session.

BufferedSessionArchive

Background archive writer used from the terminal event loop.

CreateSession

Parameters for creating a new archived session.

SessionArchive

Local archive of every CodeSwarm session for one machine.

SessionFailure

A session whose metadata could not be read. Reporting is per session so a single corrupt file never hides other valid sessions.

SessionListing

Result of listing the archive.

Enums

ArchiveEvent

One archived conversation record: a public human message or a normalized agent event, in journal order.

ArchiveState

Lifecycle description shown by the session browser.

Constants

ARCHIVE_SCHEMA_VERSION

Current on-disk schema of the archive metadata envelope.

EVENTS_FILE

Per-session append-only journal file name inside the archive root.

MAX_TITLE_CHARS

Titles are bounded so a runaway agent response cannot bloat listings.

META_FILE

Per-session metadata file name inside the archive root.

Functions

generate_session_id

Generate a fresh, filesystem-safe session id.

unix_nanos_time

Timestamps are stored as Unix nanoseconds; this converts to a display value.

validate_session_id

Reject ids that could escape the archive root or confuse the journal.