Module events 

Append-only workflow event log — .devflow/events.jsonl.

One JSON object per line, schema v1:

{"v":1,"ts":1752600000,"phase":14,"event":"transition","from":"code","to":"validate"}

Every line carries v, ts (unix seconds), phase, and event; the remaining fields are kind-specific. The log exists so any frontend (TUI, Hermes plugin, web) can observe a running loop by tailing one file instead of integrating with DevFlow internals — it is the read side of the gate notify hook’s push side.

Emission is fail-soft: an unwritable log warns and returns — recording an event must never abort the workflow it records. Appends are a single write_all of a complete line on an O_APPEND handle, so concurrent phase monitors’ lines interleave without tearing.

Structs

PhaseEventSummary

A phase’s latest event plus its newest matching stage_launched timestamp, both from the same one-pass read (999.30 / DEN-55 IN-01) — devflow status needs the real stage-entry time (21a) alongside the last-action line, and previously re-scanned the whole log per phase to get it (latest_stage_launched_ts, now folded in here).

Functions

describe

Render an event as a short human-readable summary (“gate_fired (ship)”).

emit

Append one event line. fields supplies the kind-specific payload and must be a JSON object (anything else is recorded under a "data" key).

events_path

Path of a project’s event log.

has_event_for_phase

Whether phase has ever emitted an event named event. Implemented as last_event_of_kind_for_phase.is_some() so there is one scanner, not two.

last_event_for_phase

Read the last event line recorded for phase, if any.

last_event_of_kind_for_phase

Read the last event line for phase whose event field equals event, if any. Scans the log line by line, parsing each as JSON; an unparsable line is skipped, not fatal — the log is append-only and a torn final line must not make the whole history unreadable. A missing file returns None.

last_events_by_phase

The most recent event per phase, from ONE read + parse pass over the log (14-CR-10) — devflow status renders N phases without N full-file scans. Each summary’s stage_launched_ts is the newest matching stage_launched event’s ts, independent of what the latest event overall is: a later transition, gate_fired, or corrupt line never clears an already-recorded launch timestamp.