Module session 

Coder session state machine, event stream, and persistence.

A session moves Created → ContractProposed → ContractConfirmed → Running → NeedsApproval → Merged, with Failed/Abandoned as the other terminal states. Every transition is validated, emitted as a CoderEvent, audited to the event log, and snapshotted as JSON under the state dir so a daemon restart can at least report orphaned sessions (full resume is out of scope).

Structs

AgentBuildProgress

Live progress for an Agent-project build.

CoderEvent

One event in a session’s stream. seq is monotonically increasing per session so clients can resume from a cursor after reconnect.

CoderSession

A coding session. Serializes to the JSON snapshot persisted on every transition; the live worktree handle is process-only (#[serde(skip)]).

EventSink

Per-session event fanout + audit. Emits to the registered emitter (WS subscribers) and journals the audit-relevant subset to a JSONL event log.

IntegratedSubtask

One subtask whose patch reached the session worktree, and the files it wrote.

NoChangeFinding

A nominated (or accepted) “no code should change” conclusion.

NoChangeNomination

What the model actually said when it called report_no_change.

SessionRetention

Retention policy for the coder state dir, from ~/.car/coder.toml.

UserInputGate

Mid-session user-input rendezvous.

Enums

AdoptionOutcome

What adopt_orphaned_sessions decided about one on-disk snapshot.

AgentBuildPhase

The phase an Agent-project build is currently executing.

ApprovalKind

Which gate a NeedsApproval session is sitting on.

CoderEventKind

What happened. Serialized with "type": "snake_case_name" for WS clients.

CoderState

Session lifecycle states.

ContractProvenance

Where an outcome contract’s bytes came from.

NeedsYou

What a session is waiting on a human for, right now.

NoChangeKind

Why a session concluded no code should change.

NoChangeVerification

What makes a NoChangeKind verdict trustworthy.

SweepScope

Delete session snapshots (and their journals) beyond the retention caps.

Functions

adopt_orphaned_sessions

Adopt crash/restart-orphaned coder sessions at daemon boot.

can_transition

Whether from → to is a legal transition. Any non-terminal state may move to Failed (errors happen anywhere) or Abandoned (user cancel); terminal states never move.

default_state_dir

coder under the CAR state root (~/.car/coder unless CAR_HOME moves the root) — session snapshots, event journals, and worktrees. This is only the default; CAR_CODER_STATE_DIR still overrides it outright in coder_state_dir.

gc_sessions

gc_sessions_with_age_floor

gc_sessions with a minimum age for every deletion candidate.

needs_you_from

Derive NeedsYou from the three facts that decide it. Split out from the live registry so the table in docs/proposals/coder-board-wire-contract.md §1 is directly testable without a daemon.

Type Aliases

CancelFlag

Cooperative cancellation flag, checked between turns and checks.

EventEmitter

Callback receiving every CoderEvent (WS fanout, CLI rendering, tests).