herdr events follow — a CLI verb for the socket event stream

[joelhooks]

Environment: Herdr 0.7.5, protocol 17, macOS (also checked v0.8.0 release notes and --help — no equivalent verb there either).

The need

A steering agent (a Claude/Pi/Codex session in one pane) orchestrates several worker panes. It needs one process it can spawn that blocks and prints one JSON line per lifecycle event across N panes:

herdr events follow [--pane <id>]... [--workspace <id>]

The capability already exists — the socket API's events.subscribe works fine, verified live on 0.7.5:

{ printf '{"id":"sub","method":"events.subscribe","params":{"subscriptions":[{"type":"pane.agent_status_changed","pane_id":"w5:p2"}]}}\n'; sleep 300; } \
  | nc -U ~/.config/herdr/herdr.sock
# → {"id":"sub","result":{"type":"subscription_started"}}

What's missing is a CLI verb wrapping it.

What clients do today

• herdr agent wait <target> — one target, one settle, then exit. Watching N workers means N shells or sequential waits.
• Raw events.subscribe — needs a client that holds a unix-socket connection and parses frames. Shell-based orchestrators end up with nc -U plus a fixed sleep, which is not a daemon.
• A plugin — our herdr-pings registers [[events]] hooks for pane.agent_status_changed / pane.exited / pane.closed / pane.created and rebuilds the stream as spool files: a process spawn per event, JSONL spools, byte-offset cursors with exclusive locks so concurrent waiters can't rewind each other, an early-crash watchdog, and a follow-daemon mode. That's ~550 lines of userland plumbing (bridge/lifecycle.js + herdr-ping-wait.ts) re-exposing a stream the server already serves on its socket.

Suggested shape

A thin herdr events follow that opens events.subscribe with the requested filters and prints each event as one JSON line to stdout until killed. Notes from the live check that would shape it:

• pane.agent_status_changed requires a pane_id per subscription entry (omitting it errors missing field pane_id), so the verb would fan --pane flags into N entries — workable, though a workspace-wide or wildcard filter would be nicer for orchestrators whose pane set changes mid-run.
• Live-only semantics (or an explicit cursor/replay flag) would want events.subscribe replays retained historical events for new subscribers instead of streaming live only #1270 settled first, since new subscribers currently receive replayed historical events.

No new event types, no completion classification — transport ergonomics only. Every agent-orchestration stack on top of Herdr needs this loop, and today each one rebuilds it.

[thomaswitt]

Two findings from probing 0.8.0 (protocol 19) that might help shaping this from someone who drives panes the same way, but ended up keeping the unattended half elsewhere.

First: the streaming shape you're describing already exists in the binary, just not as a documented verb. herdr terminal session observe <target> holds open and writes newline-delimited JSON to stdout until killed — {"type":"terminal.frame","seq":N,"full":bool,"encoding":"ansi","width","height","bytes":<b64>}, with a monotonic seq, a full first frame and deltas after. It's the transport behind herdr --remote. It isn't listed in herdr --help and it's absent from all 90 methods in the bundled schema. Different payload from what you want — those are coalesced screen frames, so they're lossy for anything that scrolls (a generator emitting 200 numbered lines into a 23-row pane produced 5 frames, and only the last line on screen survived) — but the "hold the socket, print one JSON line per thing, exit on kill" machinery is already written and already sequenced. That makes this a smaller ask than it reads, and there's a house style to match.

Second, concising your #1270 note: the problem isn't only that new subscribers get replay, it's that the envelope has nowhere to put a position. Against the bundled schema, a subscription event is {"event": ..., "data": ...} with exactly those two required fields — no id, no seq, no timestamp — and events.subscribe takes {subscriptions[]} and nothing else. So a follow verb built today couldn't offer --since even as a later flag, and a consumer whose connection drops mid-run has no way to learn what it missed. Fine for a sidebar that re-reads state; not fine for anything that must act once per event.

Agreed on the fan-out point, and it's sharper than an ergonomics wart: pane.agent_status_changed requiring a pane_id per entry means an orchestrator whose pane set changes mid-run has to re-subscribe on every pane.created, and there's no way to make that atomic — a status change between the create event and the new subscription is lost. A workspace-scoped filter removes the race, not just the flags.