Module tail 

keel tail — the live view of what Keel is doing for a running program: attempts, backoff waits, breaker open/half-open/close, rate-limit queueing, cache hits (dx-spec §6 — “the conversion moment”).

Where the events come from

The engine’s event sink (keel-core/src/events.rs) appends one NDJSON line per event to .keel/events/<run>.ndjson. keel tail only reads those files — no daemon, no IPC (dx invariant 3). The line format is versioned ("v": 1) but non-contract; this module parses lines as plain JSON values so an unknown future event degrades to a generic line instead of a parse failure.

Modes

• default: follow the newest run file, polling for appended lines and for a newer run superseding it (a new keel run mid-tail rotates the view; the new run’s run_start header announces the switch). Runs until interrupted.
• --run <id>: pin one run; rotation is disabled.
• --no-follow: render what is already recorded and exit — the deterministic snapshot mode (golden-testable byte-for-byte).
• --json: raw NDJSON passthrough with sorted keys (serde_json maps are BTreeMaps), one event per line — an agent can stream-parse it.

Determinism and color

The human renderer derives everything from the event line (ms is engine-elapsed, never wall time), so --no-follow output is byte-stable for a fixed feed. ANSI color is plain SGR, applied only when stdout is a terminal and NO_COLOR is unset (color_enabled); the color flag is explicit in TailOptions so tests pin both looks.

Structs

SleepTicker

Production ticker: a plain sleep between cheap re-reads (no file-watcher dependency; the feed is a local append-only file).

TailOptions

What keel tail was asked to do. follow is the default CLI behavior; --no-follow flips it off for deterministic snapshots.

Traits

Ticker

Drives the follow loop’s waiting, injected so tests never sleep for real: each call separates two polls and its return value decides continuation.

Functions

color_enabled

Whether the human view should use ANSI color: stdout is a terminal and NO_COLOR is unset or empty (https://no-color.org).

run

Run keel tail for project, writing rendered events to out. Errors (no .keel/, no runs in snapshot mode, an unknown --run) come back as a Rendered guidance report for the caller to emit; success streams to out and returns once following stops (Ticker::tick returning false, or immediately under --no-follow).