Module fleet 

Fleet snapshot — the cluster-wide session view, shared on disk.

claudectl relay serve owns the write side: on every tick it records the sessions each connected peer advertised in its heartbeat, plus the sessions running on this machine. Readers (the TUI, claudectl --json) pick the file up on their own refresh.

A file rather than an HTTP call, because the relay and the TUI are separate processes on the same machine and the peers panel already reads peer state off disk the same way. That keeps the fleet view working with no port or token to configure first; the coordinator’s HTTP API stays available for dashboards outside the machine.

Writes go through a temp file + rename so a reader mid-tick never sees a half-formed snapshot.

Structs

FleetSnapshot

What relay serve publishes for local readers.

FleetWorker

One peer’s contribution to the fleet view.

LocalSessionCollector

Collects this machine’s sessions for advertising to peers, keeping the per-session parse state that makes repeated collection cheap.

Constants

SNAPSHOT_STALE_SECS

A snapshot older than this means relay serve is no longer running, so the whole file is ignored rather than showing a frozen fleet.

WORKER_STALE_SECS

Workers whose last heartbeat is older than this are dropped on read. Three times the default 30s heartbeat interval, matching the mesh’s own expiry so a peer doesn’t linger in the fleet view after it stops reporting.

Functions

build_snapshot

Build a snapshot from the local identity and the per-peer state the relay has accumulated.

collect_local_sessions

One-shot collection, for callers that run once and exit (relay fleet). Long-running callers should hold a LocalSessionCollector instead.

read_snapshot

Read the snapshot, or None when it’s absent, unparseable, or stale enough that relay serve has clearly stopped writing it.

read_snapshot_from

Read from an explicit path. Exists so tests don’t touch $HOME.

remote_sessions

The remote sessions a local reader should display, with stale workers dropped and each entry tagged with its originating worker.

sessions_from

Map a snapshot’s live workers into displayable sessions.

snapshot_path

Where the fleet snapshot lives.

write_snapshot

Write the snapshot atomically (temp file + rename).

write_snapshot_to

Write into an explicit directory. Exists so tests don’t touch $HOME.