Module session_journal 

BP-8 (catalog domain 5): the append-only session journal — one flush-per-record log of everything that happens to a session while it is live, written beside the transcript as <name>.journal.jsonl.

The problem it solves. supercode’s own store persists a session by REWRITING <name>.jsonl from the agent’s in-memory history at the end of a turn (SessionStore::save). That is durable but not append-only: a crash between the first tool call and the end of the turn loses the whole turn. The genuine per-message writer with a flush on every line (crate::sidecar::SidecarWriter) exists, but it owns the native-v2 SIDECAR file, whose presence means “this session is a reduced/imported family” to every resume door — so it cannot simply be switched on for an ordinary session without changing what that session IS.

The journal is therefore a separate, additive family member with a discriminated record shape of its own. It is:

• append-only — nothing in it is ever rewritten or truncated, so the bytes of a message that a later rewind removed are still on disk;
• line-atomic — full line + \n, then flush(), exactly crate::sidecar::SidecarWriter::append’s guarantee, so a crash mid-write can only tear the record being written, never one already there, and replay_str skips a torn trailing line;
• replayable — replay folds the log into the state it describes: the live message list, the pending input queues, and the current plan;
• invertible — every state-changing operation has an inverse that is itself an appended record (JournalOp::Rewind ↔ JournalOp::Unrewind), so “undo” never means “delete a record”.

Records carry a supercode_journal discriminant for the same reason crate::sidecar::NativeTurn carries supercode_turn: neither Claude Code’s nor Codex’s own record shapes have that key, so a tolerant foreign loader that is ever pointed at this file skips these lines rather than erroring on them.

Structs

JournalRecord

One journal line: the discriminant, a timestamp, and the operation.

JournalState

The state a journal describes once folded up.

PlanEntry

One step of a persisted plan (update_plan’s checklist).

RestoreReport

What arm found and put back.

SessionJournal

The append-only writer. Every Self::append is one line plus \n, flushed before returning — see the module docs.

Enums

JournalOp

What a journal line records.

QueueKind

Which of the agent’s two input queues an JournalOp::Enqueue / JournalOp::Dequeue record is about (crate::agent::Agent’s steer_queue — mid-turn — and follow_up_queue — at idle).

Constants

JOURNAL_RECORD_VERSION

Discriminant value every journal line carries.

Functions

arm

BP-8 — arm what [core.session] promises for a session about to go live under name, and restore what a previous process left behind.

checkpoint

BP-8 — the mirror of arm, run every time the durable view is rewritten: declare the journal caught up and write the plan and tree beside the transcript.

replay

replay_str over a file. Ok(None) when no journal exists.

replay_str

Fold a journal’s text into the state it describes.

timestamp

A fresh RFC3339 stamp — re-exported so callers building records by hand do not reach into the sidecar module for it.