Event subscription over the control socket (agtermctl events)

[melonamin]

TLDR: the README lists "no event subscription" as out of scope, this pitch tries to fight it :)

Problem

The control API can write but can't watch. Anything that wants to react to agterm polls tree --json: reaction latency equals the poll interval, N watchers means N poll loops, and a fast status transition (blocked → cleared by a keystroke) can vanish between polls.

The agent-status hooks make this concrete. They mark sessions active/blocked/completed, but the only consumer is the sidebar glyph. "Tell me the moment an agent blocks" has no answer today.

Proposal

agtermctl events — subscribe on the existing socket. The server acks the request (normal ControlResponse, carrying the current event seq), then streams NDJSON events on the same connection until the client hangs up:

$ agtermctl events --json
{"seq":3,"ts":1783969641.38,"kind":"status","window":"0F96…","workspace":"D545…","session":"9E55…","payload":{"name":"api-fix","status":"blocked","blink":true}}
{"seq":4,"ts":1783969641.40,"kind":"notify","session":"9E55…","payload":{"name":"api-fix","title":"api-fix","body":"tests passed"}}
{"seq":5,"ts":1783969641.94,"kind":"session.closed","session":"9E55…","payload":{"name":"api-fix"}}

Human mode prints one-liners (15:07:46 status api-fix blocked); --kind filters per subscriber.

v1 kinds: status, notify, session.created, session.closed, tree.changed (coalesced structural event, ~100 ms debounce — rename/move/reorder collapse into it, scripts re-read tree for detail). seq is monotonic per app run: gap detection now, --since catch-up later with no wire break.

What it enables

Jump to whichever agent just got stuck:

agtermctl events --kind status --json | jq -r --unbuffered \
  'select(.payload.status=="blocked") | .session' | while read -r sid; do
    agtermctl session select --target "$sid"
done

Same shape gets you: notify → phone push relay (ntfy/Telegram), completed → feed the next task into the freed session (session.type), a menubar widget showing blocked/working counts without a poll loop, and events --json >> journal.ndjson for "how long was I the bottleneck today" analytics.

Design notes

• Same socket, no second surface. Considered a separate events socket and a journal file; both add discovery/security/lifecycle surface. Instead the connection is handed off: on events.subscribe the server acks, sets the fd non-blocking, and gives it to a broker on its own serial queue. The accept loop stays strictly serial and one-shot — it never learns streaming exists.
• The app never blocks on a client. A subscriber that errors or stops reading (backlog cap) is dropped and closed.
• Emission at the store chokepoints, not command arms — a GUI keystroke-clear, an agent hook, and session.status all emit the same status event. Change-only: the hooks re-assert active --blink per tool call, and same-value re-sets don't spam the stream.
• Soft close emits at removal time, so grace-enabled GUI closes aren't hidden behind the grace timer.

Prototype

I have a working prototype, reasonably shaped and sized(~1K LOC)

[umputun]

Fair to start where you did: this does cut against the stated scope. The README calls out "no event subscription" as a deliberate non-goal, and you flagged that yourself, so I'm treating it as reopening a line I drew on purpose, not a small add.

That said, the pitch has my attention, because it covers things a tree --json poll genuinely can't:

• notifications: the notify title/body aren't kept anywhere, only the unseen count is. A poller sees the count tick up but never what fired, and if a keystroke clears it between polls it sees nothing at all. A phone push relay (ntfy/Telegram) has no polling equivalent.
• time-in-state analytics: a transition that opens and clears between two polls is just gone, so "how long was I blocked today" can't be rebuilt from samples, only from the edges.

Those are real, and they line up with where the agent-status side is already heading, so I don't want to wave it off.

What's keeping the jury out isn't the value, it's code growth and API surface against the benefit. Some kinds are already poll-covered, and part of the edge story is reachable today from the agent-status hook (a script you own, it can journal or curl a push directly). My first instinct was to ask for a trimmed kind set, just the OSC/GUI-native edges agterm alone sees. But that only pays off if the smaller set genuinely shrinks the implementation. If most of the ~1K LOC is the connection/broker/lifecycle scaffolding and per-kind emission is cheap on top, trimming kinds saves little and leaves the event API lopsided, which I'd like less than either doing it in full or leaving it out. Keeping the control API internally consistent matters more to me than shaving a couple of kinds.

So the real question, and worth you chewing on too: where does the ~1K LOC actually go? If it's mostly fixed scaffolding, this is close to all-or-nothing and it comes down to whether the full event surface is worth that fixed cost. If a good chunk is per-kind and a minimal v1 is genuinely small, a tight subset gets attractive. That breakdown is what would move the decision.

[melonamin]

Good question to force — I measured instead of guessing. Current branch: ~850 source lines (~800 net new; ~45 are a relocation) plus ~355 test lines.

Once again, obvious disclaimer - all numbers based on a draft implementation.

Where the lines go:

• Fixed scaffolding, independent of kind count (~75%): broker (subscriber fds, non-blocking fan-out, EOF watch) ~145, connection handoff + server plumbing ~75, CLI streaming loop + line reader ~145, wire types + seq bus + filter ~135, observer glue skeleton ~70, protocol/dispatcher ~25.
• Per-kind (~25%): status, notify, tree.changed cost ~20–30 lines each (a post at the chokepoint, an observer arm, a format case). The session-lifecycle pair is the outlier at ~90, and that's not emission plumbing — it's covering every tree entry/exit path (undo, Open Recent, window close/delete/reopen) so created/closed actually balance.

So this lands in your all-or-nothing branch: dropping two kinds saves ~50 lines out of 850 and leaves the API lopsided. The honest decision is the full v1 surface vs. nothing — with the wire frozen small (optional fields, seq reserved, no --since/replay until someone needs it), so v1 doesn't grow from here.

One correction on the hook-script alternative. "A script you own can journal or push directly" only covers the opening edges — the hook sees what it writes. The closing edges are app-native and fire no hook at all: the Esc/Ctrl-C keystroke-clear (which exists precisely because Claude Code has no event for a declined prompt — notifications.md documents it as "the only signal"), the GUI Clear Status, and the auto-reset visit-clear. So blocked-duration can't be rebuilt hook-side any more than notify content can be polled — same class of argument you already accepted, and it's why status emits from the store setter rather than the command arm.

Use cases that are impossible or painful without edges, beyond the two you granted:

• completed --auto-reset is designed to vanish when the session is visited — a poller can miss that a run ever finished. Any "feed the next task when an agent completes" pipeline only works edge-based.
• Every "type a command, wait for the agent to finish" script today hand-rolls its own tree poll loop; with events it's one events --kind status read.
• Push-native surfaces — a Stream Deck key or menubar dot that lights when any agent blocks — are miserable as per-plugin poll loops.
• External state keyed to session lifetime (per-session log dirs, tmux panes, recording processes cleaned up on session.closed) currently means diffing consecutive tree snapshots to infer what disappeared.

Happy to open the branch as a draft PR if you want to judge the code directly rather than my accounting of it.