Push run state to subscribed websocket clients

Add a server-pushed run_event frame so a client no longer has to poll
once a second to notice run changes.

- protocol: RunEventFrame/RunStepDelta compact delta (run id, workspace,
  status, outcome, current stage, completed-step count, timestamps and an
  optional single step delta), plus subscribe/unsubscribe/run_event types
  and the optional RunEvent/RunIDs message fields. All fields optional so
  older peers ignore them.
- server: runEventHub with per-connection subscriptions scoped to a
  workspace (and optional explicit run ids), one bounded writer goroutine
  per subscription, slow-subscriber drop, per-client subscription cap and
  a ~220ms per-run coalescer that flushes pending deltas before a terminal
  frame.
- runner: emit deltas on created/queued, queued->running and step start,
  human waiting, step finish (outcome, target, diagnostic, artifacts and
  completed count), terminal finish, cancel of a waiting run and
  decide/resume; emitRun is a no-op without a hub.
- websocket: subscribe seeds current state before the ack, unsubscribe and
  connection teardown drop subscriptions, and pushed frames reuse the
  connection write closure.
- tests: protocol golden-JSON wire shape plus websocket coverage for the
  started-run frame sequence, subscribe current-state snapshot, silent
  unsubscribed/never-subscribed clients, workspace isolation and a
  bounded coalescing frame count.
- docs: note subscribe/unsubscribe/run_event in docs/cli.md; TUI and
  Android still poll in this release.
This commit is contained in:
2026-10-17 00:43:05 +01:00
parent 889d811858
commit 8f3036bd3b
9 changed files with 1025 additions and 6 deletions
+10
View File
@@ -348,6 +348,16 @@ or Tab to return to details. When not focused, the graph follows the latest visi
or selected stage. Existing polling refreshes the graph once per second, and
running durations show elapsed time rather than “in progress.”
The server can also push run changes. A client sends `subscribe` scoped to a
workspace (and optionally to explicit run ids); the server first returns the
current state of the matching runs, then a compact `run_event` delta on each
transition — which run changed, its status, outcome, current stage, completed-step
count and timestamps, and, when a single step changed, that step's sequence, stage,
status, outcome, target and diagnostic. It is a delta, never the whole run, and
rapid changes are coalesced to at most a few frames per second per run.
`unsubscribe` or disconnecting stops the frames. This lets a client drop the
once-per-second poll; the TUI and Android app still poll in this release.
In the run inspector, `n`/`p` select the next/previous recorded execution visit,
including repeated visits in loops, from any pane. Selection stops at the last
visit or overview; it does not wrap. The selected stage has a full-row highlight;